knowledge-base.mcp

A project-local RAG knowledge base MCP server for coding agents. It gives your agent a per-project, searchable memory of decisions, conventions, gotchas, and project notes — stored in a single SQLite file (knowledge-base.sqlite) at your project root. No separate services, no network calls at runtime, no API keys.

Features

• Single-file storage — documents, chunks, vectors, and full-text index all live in one SQLite file that you check into VCS. Every write lands in the file immediately, so the committed .sqlite is always current (see Storage model).
• Local, in-process embeddings — runs granite-embedding-small-english-r2 (384-dim ONNX) via @huggingface/transformers. Model files are downloaded once on first run into a shared cache under ~/.cache/knowledge-base-mcp/models; nothing else touches the network.
• Hybrid search — vector similarity (sqlite-vec) fused with FTS5 BM25 keyword search via Reciprocal Rank Fusion, so it catches both paraphrases and exact jargon/commands.
• Budget-friendly results — search returns the best sections of each document, capped by a character budget so context stays small; more_sections flags deeper results to fetch deliberately.
• Content-hash dedup — re-saving an identical body skips re-embedding, keeping committed-DB diffs small.
• Versioned schema & pinned model — if the embedding model ever changes, kb_stats reports model_mismatch instead of silently mixing incompatible vectors.

Install

pnpm install
pnpm build

The server binary is dist/index.js.

Usage

knowledge-base-mcp --db <path-to-knowledge-base.sqlite> [--model-cache <dir>]

• --db is required; the file is created if it doesn't exist.
• --model-cache defaults to $XDG_CACHE_HOME/knowledge-base-mcp/models (~/.cache/knowledge-base-mcp/models if XDG_CACHE_HOME is unset), shared across all projects.

Storage model

Your knowledge base lives entirely in knowledge-base.sqlite at the project root, and that file is committed to version control — committing your project is backing up your knowledge base. The server uses SQLite WAL mode internally, but every write is checkpointed into the main file immediately (and the WAL sidecars are removed on graceful shutdown), so the file you commit always reflects all stored documents. Check the project out on another machine and the knowledge base is intact. The WAL sidecars are gitignored (see .gitignore).

MCP tools

Tool	Description
kb_upsert_document	Create/update a doc (id optional → new UUID), re-chunks + re-embeds atomically
kb_get_document	Fetch a full document (title, body, timestamps) by id
kb_list_documents	List id, title, updated (no bodies)
kb_delete_document	Remove a doc and its chunks/vectors/FTS rows
kb_search	Hybrid search; doc-grouped sections, limit + max_chars budget
kb_stats	Counts, pinned model, schema version, model_mismatch, DB path & size
kb_reindex	Rebuild the whole index from stored bodies (after schema/model change)

Documents carry auto-managed metadata: id (UUIDv4), title, created, updated.

IntelliJ / PhpStorm configuration

JetBrains IDEs read MCP servers from a .mcp.json file at the project root (plus a user-level mcpServers.json). Place this in your project's .mcp.json:

{
  "mcpServers": {
    "knowledge-base": {
      "command": "node",
      "args": [
        "/abs/path/to/knowledge-base.mcp/dist/index.js",
        "--db",
        "/abs/path/to/your/project/knowledge-base.sqlite"
      ]
    }
  }
}

• cwd is set by the IDE to the project root containing .mcp.json.
• Replace the two paths with absolute paths on your machine.
• The server appears in Settings → Tools → MCP Servers; enable it for the project.

Configuring defaults

Tunables such as the embedding model, chunk sizes, and search limits live in src/constants.ts and take effect when you rebuild. See AGENTS.md for the full list and the reindex step required when changing the embedding model.

Development

Build/typecheck/test commands, architecture notes, invariants, and contribution conventions are in AGENTS.md.