hybrid-recall

A local, self-hosted retrieval stack exposed over the Model Context Protocol (MCP). It gives an LLM four tools:

• sqlite - hybrid search over a document corpus you ingest (FTS5 keyword + semantic embeddings, fused with Reciprocal Rank Fusion).
• retrieve - one unified search across the knowledge graph, memory, and docs, with KG-powered query expansion and RRF fusion.
• memory - a semantic key/value store for cross-session notes (store / append / replace-section / search / get / list).
• kg - an entity-relationship knowledge graph with hybrid search.

Everything runs on your machine. The only external dependency is an OpenAI-compatible embedding server (a small llama-server process), and an optional reranker. Nothing is sent to a third party.

How it fits together

  MCP client (Claude Desktop, etc.)
        |  stdio (JSON-RPC)
        v
  server.py  ->  sqlite / retrieve / memory / kg tools
        |                 |                |
        |                 |                +--> memory daemon (TCP :8767)
        |                 +--> knowledge_graph.jsonl
        +--> docs.db (FTS5 + 2560-d embeddings) + embed_cache (mmap)
                          |
                          v
             embedding server (llama-server :8000, Qwen3-Embedding-4B)

The docs corpus, memory, and knowledge graph all embed through the same model, so a single llama-server covers the whole stack.

Requirements

• Python 3.10+
• llama.cpp (llama-server on your PATH)
• A GPU is recommended for the embedding model (it runs on CPU too, slower)

Quickstart

# 1. Install Python deps
pip install -r requirements.txt

# 2. Download the embedding model into ./models  (see models/README.md)
huggingface-cli download Qwen/Qwen3-Embedding-4B-GGUF \
  Qwen3-Embedding-4B-Q8_0.gguf --local-dir ./models

# 3. Start the embedding server (leave running in its own terminal)
scripts/start_embeddings.sh          # Windows: scripts\start_embeddings.bat

# 4. Start the memory daemon (needed for the memory + retrieve tools)
scripts/start_memory.sh              # Windows: scripts\start_memory.bat

# 5. Create the empty docs database
python init_databases.py

# 6. Ingest your documents (markdown, html, json, text, code)
python scripts/ingest_docs.py --source ./corpus     # ./corpus has sample docs

# 7. Embed the chunks (talks to the embedding server from step 3)
python scripts/embed_docs.py

# 8. (optional) Prebuild the mmap vector cache for instant search
python scripts/rebuild_mmap_cache.py

Then point your MCP client at server.py (see example_config.json):

{
  "mcpServers": {
    "hybrid-recall": {
      "command": "python",
      "args": ["/absolute/path/to/hybrid-recall/server.py"]
    }
  }
}

Configuration

All settings have sane localhost defaults; override them with environment variables or a .env file (see .env.example). The important ones:

Variable	Default	Purpose
EMBED_SERVER_URL	http://127.0.0.1:8000/v1/embeddings	embedding endpoint
RERANKER_URL	http://127.0.0.1:8001/v1/rerank	reranker (optional)
MEMORY_SERVICE_PORT	8767	memory daemon port
KNOWLEDGE_GRAPH_PATH	./data/knowledge_graph.jsonl	KG storage
DOCS_DB_PATH	./data/docs.db	docs corpus DB

To run the models on a different machine, point EMBED_SERVER_URL / RERANKER_URL at that host. The tools do not care where the servers live.

Reranking

Reranking is optional and off by default. Every search works without it and falls back to bi-encoder order if the reranker is not running. To enable it, start the reranker (scripts/start_reranker) and pass rerank=true on a call.

Notes

• The docs corpus, memory store, and knowledge graph are all built from your own data. A fresh clone starts empty.
• Index-time and query-time embeddings must come from the same model. If you switch embedding models, re-embed the corpus.
• The memory tool is a small TCP daemon (scripts/start_memory); the docs and KG tools run in-process inside the MCP server.

Benchmarks

The design choices here (Qwen3-4B bi-encoder, cross-encoder reranking off by default, RRF fusion, BGE-reranker-v2-m3) are backed by real measurements: recall suites, a 10-strategy fusion A/B, reranker and embedding model bake-offs, and latency profiles. See benchmark.md. Short version: real embeddings + reranking moved retrieval MRR from 0.36 to 0.77 on a 32-query suite, and plain reranking beat every fancy fusion scheme tried against it.

License

MIT. See LICENSE.