Content
# hybrid-recall
[](LICENSE)
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](https://github.com/ggml-org/llama.cpp) (`llama-server` on your PATH)
- A GPU is recommended for the embedding model (it runs on CPU too, slower)
## Quickstart
```bash
# 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`):
```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`](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`.
