kb-mcp

# kb-mcp — Session Information Flow Center & Historical Memory Hub [](LICENSE) [](https://python.org) [](tests/) [](https://github.com/jlowin/fastmcp) > The information bus for AI agent workflows. > Persist memory across sessions, relay large documents between agents, and bridge history — all in one SQLite file. ☕ **If kb-mcp saves you time, you can support development on Ko-fi:** [](https://ko-fi.com/win0528) --- ## What is kb-mcp? Modern AI agent workflows span multiple sessions and multiple agents. Information produced in one session (a plan, an audit, a research finding) must reach the next agent without being pasted wholesale into every prompt. Context windows are expensive; re-discovery is wasteful; in-prompt blob passing degrades retrieval quality. **kb-mcp is the information infrastructure that solves this:** - An **orchestrator** writes a plan to `docs/PLAN_v1.md` and calls `kb_index_path` — it is searchable in under 2 seconds. - A downstream **oracle** calls `kb_search("plan v1")` and gets the relevant chunks without ever receiving the full document. - A new session picks up exactly where the last left off because all decisions, handoffs, and context summaries live in the same SQLite bus. One file. No server. No cloud. Full ownership. --- ## Why kb-mcp? Local memory MCP servers already exist — Mem0's [OpenMemory MCP](https://mem0.ai/blog/introducing-openmemory-mcp), [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service), and Qdrant/Neo4j self-hosted stacks. kb-mcp is **not** the first. Its niche is the combination of **radical simplicity** and **active write tools** that make it a live information bus, not just a queryable archive. | | kb-mcp | Heavy self-hosted (Qdrant + Neo4j + Docker) | Cloud (Mem0 / Zep platform) | |---|---|---|---| | **Storage** | Single SQLite file | Multiple services + volumes | Their servers | | **Setup** | `uv sync` + Ollama | Docker Compose, N containers | API key + SaaS | | **Data location** | Your disk only | Your disk (heavier) | Cloud | | **Backup / migrate** | Copy one `.db` file | Multi-service dump | Vendor export | | **Live write tools** | `kb_index_path` + `kb_add_source` | Varies | API | | **Lifecycle** | active → stale → archived → evicted + tombstone | Varies | Basic CRUD | | **Link graph** | 97.3% wikilink resolution | Varies | Usually none | | **RAM footprint** | Low (SQLite + local embed) | High (vector DB + graph DB) | N/A | **Honest scope:** kb-mcp is built for individual developers and multi-agent systems that need a zero-moving-parts information bus they fully own. It does not compete with Mem0/Zep on cloud scale or team features. --- ## Core Concepts ### Information Flow Bus kb-mcp acts as the shared memory layer across your entire agent workflow. Any agent can write a document (`kb_index_path`), register a new knowledge source (`kb_add_source`), or query accumulated knowledge (`kb_search`) — all through the same MCP interface. ``` Agent A writes plan → kb_index_path("docs/PLAN_v1.md") Agent B reads plan → kb_search("implementation plan v1") New session resumes → kb_search("last handoff decisions") ``` ### Large Document Relay Protocol When an agent produces a large output (≥ 300 lines), injecting it verbatim into the next agent's prompt wastes tokens and degrades retrieval. The correct pattern: ``` 1. Write document to disk: docs/PLAN_v1.md 2. Index immediately: kb_index_path("docs/PLAN_v1.md") 3. Pass reference, not blob: "Search kb for 'plan v1' to get context" 4. Downstream agent calls: kb_search("plan v1") → relevant chunks only ``` ### Historical Memory Management Five document sources cover the full lifecycle of agent memory: | Source | Purpose | |--------|---------| | `memory` | Persistent project notes, rules, and decisions | | `handoff` | Session handoff documents — what was done, what comes next | | `context` | Architecture summaries, module maps, system snapshots | | `kb_native` | Project-specific documents (plans, audits, research) | | `export` | External imports, migrated content | Documents move through a managed lifecycle: `active → stale → archived → evicted` with tombstone support, so the search index stays fresh without manual cleanup. ### Session Continuity Every session can query the full history of decisions, context, and handoffs without re-reading source files. A new agent session starts informed, not blank. --- ## Features - **Hybrid search** — sqlite-vec (vector) + FTS5 (full-text trigram) + RRF(k=60) fusion, top-5 accuracy ~90% - **Live write tools** — `kb_index_path` for instant single-file indexing; `kb_add_source` for registering new directories - **Wikilink resolution** — `[[DocumentName]]` → resolved `dst_document_id`, 97.3% success on real corpus - **Lifecycle management** — `active / stale / archived / evicted` states with audit rows and tombstone support - **Atomic indexing** — per-document SAVEPOINT; one document's failure never corrupts the batch - **MCP-native** — 6 tools via stdio transport, zero external API calls at query time - **Incremental indexing** — SHA-256 content hash; unchanged files skipped, changed files re-embedded only - **Five knowledge sources** — `memory · handoff · context · kb_native · export` - **103 tests** — integration tests with real Ollama + unit tests with in-memory SQLite, zero mocks --- ## Architecture ``` Markdown files (.md) │ scan + parse ▼ ┌─────────────────────────────────────────────────────┐ │ Indexer │ │ chunking → Ollama embed → SAVEPOINT write │ │ link extraction → resolve_links (batch pass) │ └──────────────────────────────┬──────────────────────┘ │ SQLite WAL (kb.db) ┌──────────────────┼──────────────────┐ │ │ │ sqlite-vec FTS5 documents (vec0 table) (trigram) + links + tags + lifecycle │ │ └─────── RRF ──────┘ │ FastMCP stdio server ┌──────────┬───────────┬─────────────┬────────────┐ kb_search kb_get kb_related kb_index_path kb_add_source kb_stats ``` --- ## Requirements - Python **3.12+**, managed with [uv](https://docs.astral.sh/uv/) - [Ollama](https://ollama.com/) running locally with `qwen3-embedding:0.6b` pulled - SQLite 3.35+ (ships with Python) ```bash # Pull the embedding model once ollama pull qwen3-embedding:0.6b ``` --- ## Installation ```bash git clone https://github.com/chjien1917/kb-mcp.git cd kb-mcp uv sync ``` ### Initial index ```bash # Index your Markdown knowledge files uv run kb index --full # Check stats uv run kb stats ``` By default, kb-mcp discovers: - `~/.claude/` (memory files, handoff docs, context summaries) - Override with `~/.config/kb/config.toml` (see [Configuration](#configuration)) --- ## MCP Integration ### opencode Add to your `.opencode/opencode.json`: ```json "kb-mcp": { "type": "local", "command": ["/path/to/kb-mcp/.venv/bin/kb-mcp"], "enabled": true } ``` Replace `/path/to/kb-mcp` with your actual clone path. ### Claude Code / Claude Desktop Add to `~/.claude/claude_desktop_config.json` (Desktop) or `~/.claude/settings.json` (Code): ```json { "mcpServers": { "kb-mcp": { "command": "/path/to/kb-mcp/.venv/bin/kb-mcp" } } } ``` --- ## MCP Tools ### Read Tools | Tool | Description | |------|-------------| | `kb_search` | Hybrid vector+FTS search. Params: `query`, `k`, `mode` (hybrid/fts/vec), `tags`, `source`, `include_archived`, `expand_links` | | `kb_get` | Get a document by `document_id` or `path` — full content, outbound/inbound links, tags. Increments access count. | | `kb_stats` | DB statistics: doc count by source/state, chunk count, link resolution rate, last index run | | `kb_related` | Navigate the wikilink graph: outbound + inbound resolved links for a document | ### Write Tools | Tool | Description | |------|-------------| | `kb_index_path` | Index a single `.md` file immediately. Use after writing any large document to make it searchable within ~2 seconds. Returns `document_id` and `chunks_written`. | | `kb_add_source` | Register a directory as a knowledge source and optionally trigger incremental indexing. Persists to `config.toml` via `scan.roots`. Valid sources: `kb_native · memory · handoff · context · export` | --- ## Typical Agent Workflow ```python ``` # 1. Orchestrator: planner produces a large plan document # Write to disk, then register it immediately kb_index_path("project/docs/PLAN_v1.md", source="kb_native") # 2. New project directory? Register it once — all future files auto-scan kb_add_source("project/docs", source="kb_native", index_now=True) # 3. Oracle / downstream agent: retrieve relevant context without full blob results = kb_search("implementation plan database schema", k=5) # 4. Any session: resume from last known state handoff = kb_search("last session handoff decisions", source="handoff") ## Configuration Optional config file at `~/.config/kb/config.toml`: ```toml [db] path = "~/.local/share/kb/kb.db" [embed] base_url = "http://127.0.0.1:11434" # Ollama endpoint model = "qwen3-embedding:0.6b" batch_size = 32 [[scan.roots]] path = "~/.claude" source = "memory" [[scan.roots]] path = "/your/project/docs" source = "kb_native" ``` Environment variable overrides: - `KB_WORKSPACE_ROOT` — workspace root for path discovery - `KB_LOG_LEVEL` — log level (default: INFO) ## CLI Reference ```bash uv run kb index # Incremental index uv run kb index --full # Full re-index uv run kb stats # Print DB statistics uv run kb search "query" # Search from terminal uv run kb get <doc_id> # Get document by ID ``` ## Development ```bash uv sync --dev # Run all tests (requires Ollama online for integration tests) PYTHONPATH=. uv run pytest tests/ -q # Unit tests only (no Ollama) PYTHONPATH=. uv run pytest tests/ -q -m "not integration" ``` ## License MIT &copy; [SHI JIE HOU](https://github.com/chjien1917) &mdash; see [LICENSE](LICENSE) # Tool List