Modaka - Local-First Second Brain, Knowledge Hub & OKF Engine
  • TypeScript 93.4%
  • JavaScript 3.3%
  • CSS 1.4%
  • Astro 1.3%
  • Dockerfile 0.6%
Find a file
Olivier Lépine b299e51696
All checks were successful
Modaka Sovereign CI / Test & Build Validation (push) Successful in 1m27s
Modaka Sovereign CI / Test & Build Validation (pull_request) Successful in 1m33s
Build and Publish OCI Image / Build & Push ARM64 OCI Image (pull_request) Successful in 1m45s
Build and Publish OCI Image / Build & Push ARM64 OCI Image (push) Successful in 1m19s
Merge pull request 'chore: version 0.1.0' (#3) from chore/version-0.1.0 into develop
Reviewed-on: #3
2026-11-10 16:43:03 +00:00
.agents feat: implement backend initialization flow, task queue management, and category-based onboarding configuration 2026-07-15 20:20:42 +02:00
.forgejo/workflows fix(ci): build-oci workflow aligned on modaka/studio 2026-11-10 16:57:41 +01:00
.tycho feat: add audio support, reverse geocoding, and task management improvements to the queue system 2026-07-18 22:27:37 +02:00
.vscode Initial commit 2026-07-14 16:14:25 +02:00
.yarn feat(llm): support multi-provider LLM map architecture and GHCR container deployment 2026-09-22 16:43:38 +02:00
bin feat(container): add data-agnostic Bun alpine OCI image and fix SSR bundling 2026-09-21 22:31:37 +02:00
design-notes refactor: rename modaka core logic to @quatrain/chat and document architectural decoupling from UI 2026-07-18 22:32:24 +02:00
docs fix: remove private paths and legacy client references 2026-11-08 11:38:43 +01:00
public feat(ui): integrate official geometric elephant logo into app header, icons, and onboarding screen 2026-07-24 09:48:25 +02:00
scratch feat: add S3 storage support, enable batch file uploads with filename decoding, and implement URL hash-based navigation for dashboard states. 2026-07-16 13:48:33 +02:00
src fix: re-process edited notes with the configured model 2026-11-08 11:43:53 +01:00
.dockerignore feat(container): add data-agnostic Bun alpine OCI image and fix SSR bundling 2026-09-21 22:31:37 +02:00
.env.dist feat(config): integrate @quatrain/config and enforce fail-fast configuration across endpoints 2026-09-21 23:18:16 +02:00
.gitignore feat(llm): support multi-provider LLM map architecture and GHCR container deployment 2026-09-22 16:43:38 +02:00
.yarnrc.yml ci: use public NPM registry for @quatrain dependencies 2026-08-21 12:08:17 +02:00
AGENTS.md docs: align README with the implemented model providers and roadmap 2026-11-08 11:43:53 +01:00
astro.config.mjs fix: remove private paths and legacy client references 2026-11-08 11:38:43 +01:00
CLAUDE.md Initial commit 2026-07-14 16:14:25 +02:00
Containerfile chore: align licence, author and repository metadata 2026-11-08 11:43:54 +01:00
HOWTO.md fix: remove private paths and legacy client references 2026-11-08 11:38:43 +01:00
LICENSE Initial commit 2026-07-14 16:14:25 +02:00
OKF_AGENT_PROMPT.md feat: implement backend initialization flow, task queue management, and category-based onboarding configuration 2026-07-15 20:20:42 +02:00
package.json chore: version 0.1.0, aligned with modaka/studio 2026-11-10 17:38:43 +01:00
README.md docs: align README with the implemented model providers and roadmap 2026-11-08 11:43:53 +01:00
sonar-project.properties ci(sonar): add SonarCloud scan step and coverage report to modaka-npm-package workflow 2026-07-24 15:02:01 +02:00
tsconfig.json fix(backend): dynamically import GitStorageAdapter and configure tsconfig path aliases to resolve module import error 2026-07-23 23:43:48 +02:00
vitest.config.ts fix: remove private paths and legacy client references 2026-11-08 11:38:43 +01:00
yarn.lock feat(llm): support multi-provider LLM map architecture and GHCR container deployment 2026-09-22 16:43:38 +02:00

Modaka — Local-First Second Brain, Knowledge Hub & OKF Engine

License: AGPL v3 TypeScript Astro OKF v0.1 Local-First CI

Modaka is a decentralized, local-first, touch-optimized digital knowledge base and personal AI copilot built on Astro 5, React and Quatrain Core. The language model behind it is chosen by configuration (see Model Providers). It organizes your notes, audio transcripts, PDFs, images, and web research using the standardized OKF (Open Knowledge Format v0.1) structure backed by local Git storage.


🧭 Core Engineering Principles

1. Local-First Architecture

  • Single Source of Truth: The local disk (.modaka-data) is the primary reading and search target.
  • Instant Synchronization: Modaka bypasses indexing caches on read operations, ensuring that manual filesystem edits, file renames, or external note additions are visible immediately in the UI and to the LLM.

2. OKF (Open Knowledge Format v0.1) Compliance

Every document imported or generated is stored as clean, human-and-AI-readable Markdown:

  • Flat YAML Frontmatter: Bounded by ---. Null, empty string (""), or undefined fields are omitted.
  • Semantic Concept Kinds: The type field specifies the functional nature of the knowledge item (e.g., specification, guide, screenshot, invoice, recipe, note, concept).
  • Human-Readable Slugs: File and directory names use lowercase slugified titles instead of obscure UUIDs (e.g., /content/technology/ai/okf-spec.md).

3. Progressive Disclosure Navigation

  • Recursive Indices: Every category directory contains an auto-generated index.md file listing child subcategories and concept documents.
  • Token Efficiency: AI agents and LLM tools navigate the knowledge graph step-by-step using Markdown links without overwhelming their context window.

4. Hybrid Search Engine Integration (@quatrain/searchengine-qmd)

  • Integrates QMD (Query Markup Documents) hybrid search combining BM25 term matching, vector semantic search, and category filtering.
  • Exposed natively via the /api/search API endpoint and consumable by external agents.

5. Resilient Background Processing

  • Asynchronous task processing powered by SQLite Queue (@quatrain/queue-sqlite).
  • Ingestion tasks (PDF OCR, Audio Transcription, Web Scraping, Wikipedia Auto-Linking) run safely in the background with progress reporting and automatic retries.

🏗️ System Architecture

graph TD
    UI["Astro / React PWA Dashboard"] -->|Upload PDF / Image / Audio / Web| UploadAPI["API Server Endpoints"]
    UI -->|Hybrid Query| SearchAPI["/api/search Endpoint"]
    UI -->|Chat & Contextual AI| ChatAPI["/api/chat Endpoint"]
    
    UploadAPI -->|Enqueue Task| Queue["SQLite Queue Manager"]
    Queue -->|Background Worker| Ingestion["Quatrain Ingestion Adapters"]
    Ingestion -->|OCR / Audio / Web| LLM["AI port (@quatrain/ai)"]
    
    SearchAPI -->|Search Query| QMD["@quatrain/searchengine-qmd Adapter"]
    QMD -->|Hybrid Rank| Disk[("Local OKF Filesystem")]
    
    Ingestion -->|Persist OKF Markdown| OKFAdapter["OKFBackendAdapter"]
    OKFAdapter -->|Save & Auto-Index| Disk
    OKFAdapter -->|Git Stage & Commit| GitStorage["GitStorageAdapter"]
    GitStorage <-->|Async Push/Pull| RemoteGit[("Remote Git Repository")]

🌟 Key Application Features

📊 Multi-Mode Analytics & Knowledge Graph

The Stats module offers three distinct visualization perspectives:

  1. Synthetic Metrics Table: Live counters of documents, media files, hyperlinks, and category distribution.
  2. Interactive Link Network Graph: Dynamic SVG visualization mapping cross-document relationships with hover tooltips and category color-coding.
  3. AI Metrics & Conversation Log: History of past chat sessions with token consumption estimations, average response latency, and instant one-click export to OKF Markdown documents.

🔍 QMD Hybrid Search API

Run multi-modal queries across your knowledge base:

GET /api/search?q=ISO+27001&category=certification&mode=hybrid&limit=10

🎙️ Multi-Format Ingestion Pipelines

  • Audio Notes: Transcribes live or uploaded audio recordings (.wav, .m4a, .mp3) and derives structured summaries.
  • Multimodal OCR: Extracts text from scanned PDFs and images with a multimodal model (Gemini today, see Roadmap).
  • Web Crawling: Scrapes web pages, strips boilerplate navigation, extracts Markdown body text, and recursively processes sub-links.
  • Wikipedia Concept Auto-Linking: Identifies proper nouns in documents and automatically pulls Wikipedia summaries to build concept pages under content/concepts/.

🛠️ Monorepo & Core Package Dependencies

Modaka relies directly on the Quatrain Core modular ecosystem, published as @quatrain/* npm packages. To work against a local Core checkout, set CORE_DIR to its packages/ directory.

Package Role & Responsibility
@quatrain/core Core runtime container and singleton registry.
@quatrain/backend Abstract backend persistence layer and query builders.
@quatrain/okf Open Knowledge Format adapter and recursive index.md generator.
@quatrain/searchengine Abstract search engine contract and registry manager.
@quatrain/searchengine-qmd QMD (Query Markup Documents) hybrid BM25/Vector search adapter.
@quatrain/ai Provider-agnostic AI port.
@quatrain/ai-gemini Gemini adapter for the AI port.
@quatrain/ai-openai OpenAI-compatible adapter (OpenAI, Mistral, Groq, OpenRouter, Ollama, any compatible endpoint).
@quatrain/ingestion-ocr Multimodal document OCR processing pipeline.
@quatrain/ingestion-audio Audio transcription and metadata extraction.
@quatrain/queue-sqlite SQLite-backed background task queue.
@quatrain/storage-git Git repository transport layer for version control.

🚀 Quick Start Guide

Prerequisites

  • Node.js: >= 22.0.0
  • Package Manager: Yarn Berry or Bun
  • A language model: an API key for a hosted provider, or a local OpenAI-compatible server (see Model Providers)

Environment Configuration (.env)

Create a .env file in the root directory:

# User configuration file written by the settings screen (model provider, see below)
MODAKA_CONFIG_PATH=/absolute/path/to/user_config.json

# Only for the gemini provider
GEMINI_API_KEY=your_google_gemini_api_key_here
GEMINI_MODEL=gemini-2.5-flash

GIT_MODE=local
GIT_LOCAL_PATH=/absolute/path/to/modaka-data
DOCUMENT_STORAGE_PATH=/absolute/path/to/modaka-documents

OKF_STORAGE_PATH=/absolute/path/to/modaka-data/content
S3_BUCKET=documents

Installation & Local Server

# Install dependencies
yarn install

# Run development server
yarn dev

The application will be accessible at http://localhost:4321.

Running Tests

Execute the Vitest suite:

yarn test

Model Providers

Chat and the structuring of ingested content go through the @quatrain/ai port. The provider is chosen in the settings screen, which writes the user configuration file (MODAKA_CONFIG_PATH), or directly in that file:

{
  "llm": {
    "active": "ollama",
    "providers": {
      "ollama": { "model": "llama3.1", "endpoint": "http://localhost:11434/v1" }
    }
  }
}
active Adapter Default endpoint API key
gemini @quatrain/ai-gemini Google required (GEMINI_API_KEY or apiKey)
openai @quatrain/ai-openai https://api.openai.com/v1 required
mistral @quatrain/ai-openai https://api.mistral.ai/v1 required
groq @quatrain/ai-openai https://api.groq.com/openai/v1 required
openrouter @quatrain/ai-openai https://openrouter.ai/api/v1 required
ollama / llama @quatrain/ai-openai http://localhost:11434/v1 none

Any other OpenAI-compatible server (llama.cpp, vLLM, LM Studio) works with endpoint set to its /v1 URL.

Current limits, tracked in the Roadmap: OCR and audio transcription still require a Gemini model, and text-to-speech uses ElevenLabs, OpenAI or the browser's speech synthesis.


Roadmap

In progress or planned; not available yet:

  • Local models for every capability: OCR, transcription and text-to-speech through the AI port, so that a fully local setup needs no hosted provider; local embeddings.
  • Traceability: event log of LLM-judge verdicts, of the sources consulted for each answer, of human confirmations (reviewer, date), and of provenance events at ingestion (creation, update, validation, summary, transcription, transfer to a downstream instance). Today the history of a document is its Git history.
  • Governed sharing: filtered subsets delivered to downstream instances as Git forks, with feedback flowing back upstream.
  • Q/A regression tests replayed on every ingestion.

📄 License

Copyright © 2026 Quatrain Technologies SAS.

This project is licensed under the AGPL-3.0-only license. See the LICENSE file for details.