claude-rag — MCP RAG Server for Markdown Knowledge Bases

Author: Sergio Angelastro — MIT License

MCP server that indexes a folder of .md files into a local SQLite vector store and exposes semantic search as Claude Code tools. The core RAG system (chunking, embedding, SQLite vector store, MCP server, cosine similarity search) is original work by the author.

Hook system (hooks/) inspired by agd-memory by @Pinperepette (MIT) — see CREDITS.md

Architecture

📊 Interactive diagram →

Three components working together:

Stack: Python · sentence-transformers (paraphrase-multilingual-MiniLM-L12-v2, ~120MB, CPU-only) · SQLite · MCP stdio

Related MCP server: flightlog

Tools exposed

Setup

1. Clone

# Default layout: repo sits inside the KB folder
# KB files (.md) go in the parent directory
git clone https://github.com/sangelastro/claude-rag ~/.claude/my-kb/rag

Or clone anywhere and point to your KB folder via env var (see step 3).

2. Install dependencies

cd ~/.claude/my-kb/rag
pip install -r requirements.txt

On first run the model (paraphrase-multilingual-MiniLM-L12-v2, ~120MB) is downloaded automatically from HuggingFace. This model supports 50+ languages including Italian natively.

3. Register in Claude Code

Add to ~/.claude.json under mcpServers:

"my-kb": {
  "command": "python",
  "args": ["/absolute/path/to/rag/server.py"],
  "env": {
    "KB_RAG_DIR": "/absolute/path/to/your/kb/folder"
  }
}

• KB_RAG_DIR — folder containing your .md files (default: ../ relative to server.py)

• KB_RAG_DB — SQLite database path (default: kb.db next to server.py)

• CHUNK_MAX_CHARS — max chars per chunk before splitting (default: 400)

• CHUNK_OVERLAP — overlap in chars between consecutive sub-chunks (default: 80)

If the repo is cloned inside the KB folder (as in the example above), both env vars can be omitted.

4. Restart Claude Code

The server starts automatically. On first launch it indexes all .md files in KB_RAG_DIR.

Optional: Claude Code Hooks

Two hooks auto-inject KB context without explicit kb_search calls. Approach inspired by agd-memory (MIT).

Setup hooks

Copy the relevant sections from hooks/hooks_example.json into your ~/.claude/settings.json, replacing the placeholder paths:

{
  "hooks": {
    "SessionStart": [{
      "matcher": "*",
      "hooks": [{"type": "command", "command": "python /absolute/path/to/rag/hooks/kb_session_start.py"}]
    }],
    "UserPromptSubmit": [{
      "matcher": "*",
      "hooks": [{"type": "command", "command": "python /absolute/path/to/rag/hooks/kb_recall.py", "timeout": 5}]
    }]
  }
}

kb_chunks.json (used by kb_recall.py) is auto-generated next to kb.db on every reindex. No model loading in hooks — scoring uses token overlap only.

Hook behaviour is tunable via env vars:

File structure

rag/
├── server.py           # MCP server
├── requirements.txt
├── .gitignore
├── README.md
├── hooks/
│   ├── kb_session_start.py   # SessionStart hook
│   ├── kb_recall.py          # UserPromptSubmit hook
│   └── hooks_example.json    # Hook config template
├── architecture.html   # Technical documentation
└── kb_rag_slides.html  # Architecture slide deck

kb.db and kb_chunks.json are generated locally and excluded from git.

How it works

1. Chunking — each .md file is split on ## headers; frontmatter is stripped; sections longer than CHUNK_MAX_CHARS (400) are further split into overlapping sub-chunks with CHUNK_OVERLAP (80) chars of context continuity

2. Embedding — chunks are encoded with paraphrase-multilingual-MiniLM-L12-v2 (384 dimensions, 50+ languages)

3. Storage — vectors stored as float32 BLOBs in SQLite + kb_chunks.json for hooks

4. Search — cosine similarity computed in numpy over all chunks; top-K returned

5. Hooks — keyword scoring on kb_chunks.json (no model), injected before each prompt

6. Invalidation — mtime-based: only modified files are re-indexed on startup

7. Savings tracking — every search records chars served vs full-file baseline in search_stats table; kb_savings() aggregates the cumulative token reduction without re-reading any file

Environment variables

Credits

Hook architecture inspired by agd-memory by Pinperepette (MIT License) — in particular the UserPromptSubmit recall pattern and guard rail logic.