Provides hybrid search (FTS5 keyword + semantic embeddings with Reciprocal Rank Fusion) over a document corpus stored in SQLite.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@hybrid-recall find documents about hybrid search"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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.
Related MCP server: Hoard
Python 3.10+
llama.cpp (llama-server on your PATH)
A GPU is recommended for the embedding model (it runs on CPU too, slower)
# 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.pyThen point your MCP client at server.py (see example_config.json):
{
"mcpServers": {
"hybrid-recall": {
"command": "python",
"args": ["/absolute/path/to/hybrid-recall/server.py"]
}
}
}All settings have sane localhost defaults; override them with environment
variables or a .env file (see .env.example). The important ones:
Variable | Default | Purpose |
|
| embedding endpoint |
|
| reranker (optional) |
|
| memory daemon port |
|
| KG storage |
|
| 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 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.
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.
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.
MIT. See LICENSE.
Entity-relationship graph for structured facts. Use for entities with relationships - concepts, tools, people, patterns. Check here before semantic_search. For free-form text/learnings, use memory instead. Hybrid search (70% semantic + 30% keyword). Limits: 10K entities, 100 obs/entity. Audit log for destructive ops. Actions: create_entities, create_relations, add_observations, delete_entities, delete_relations, search, neighbors, stats, read, prune, remove_observation, update_entity, rename_entity, merge_entities, batch. IMPORTANT: Always specify entity_type when creating entities - omitting it defaults to 'unknown' which pollutes the graph. Knowledge graph is stored as JSONL.
Inputs: action (required), mode, depth, limit, +18 more.
On session start: get session:latest + project:overview. Semantic memory for cross-session persistence. Returns {success, results/value}. Actions: store (save key+message, full overwrite), append (add fragment to existing key without rewriting it - server concatenates and re-embeds), replace_section (in-place edit of marker-bounded region inside an existing entry), search (semantic query), get (exact key), delete, list. RAM-backed with async disk persist - use liberally. Key conventions: session:latest (current state), project:overview (architecture), learn: (discoveries), pref: (user prefs), todo:, code:. For large rolling docs (timelines, session logs) use append instead of store - massive token savings. For in-place section edits inside a long doc, use replace_section with HTML-comment markers like ''/''. Search is semantic with synonym expansion ('fast'->'quick'). Use preprocess=False for exact match. When encountering issues or problems search for related context. On milestones: store session:latest.
Inputs: action (required), key, tags, limit, +12 more.
Unified retrieval across KG, Memory, and Docs with KG-powered query expansion. Use for conceptual queries where keyword search fails. Automatically expands query using KG domain knowledge (e.g., 'transformer optimization' -> includes KV cache, Flash Attention). Fuses results via reciprocal rank fusion. Returns results with source attribution. Default: compact=true (shorter snippets, ~500-800 tokens). Use compact=false for full content (~2000 tokens).
Inputs: query (required), limit, rerank, compact, +6 more.
SQLite database operations + document-corpus search. Commands: catalog, exec, list_databases, open_database, health_check, docs_search, docs_semantic_search, docs_hybrid, docs_full, docs_context, docs_search_in_doc. docs_search: FTS5 keyword search over the ingested docs corpus. Use for exact terms, API names, phrases. docs_semantic_search: Embedding similarity search over docs. Use for general queries. docs_hybrid: PREFER THIS Run both keyword + semantic with RRF fusion. Best recall. docs_full: Retrieve complete document by exact path. Use sql param with path from search results. Wildcard % optional for fuzzy match. docs_context: Expand around a chunk - params: {chunk_id, before, after}. docs_search_in_doc: Hybrid search within a specific document - params: {query, limit, threshold}. sql=path. Returns chunk positions. All docs search commands: query via 'sql' param. docs_* filters: {doc_type, source, limit, threshold}. docs_* results are pre-chunked - do NOT use file reads; run more searches or use docs_context/docs_full instead.
Inputs: command (required), sql, write, params, +1 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 4 tools
Each tool has a distinct primary domain (sqlite for SQLite and doc search, retrieve for unified cross-source retrieval, memory for persistent key-value store, kg for graph), but retrieval functions overlap—sqlite's docs_search and retrieve both cover docs, and memory/kg each have search. Descriptions help, but an agent might still be uncertain which search to use.
Tool names are all lowercase but mix verb (retrieve) and nouns (sqlite, memory, kg); no consistent verb_noun pattern. Within sqlite, multi-word subcommands use underscores, but tool-level naming is inconsistent.
Four tools is well-scoped for a hybrid recall server covering docs, unified retrieval, memory, and knowledge graph; each earns its place without feeling bloated or sparse.
Covers the main retrieval surfaces (docs, memory, KG, unified) with CRUD on memory and KG and doc search operations; minor gaps like missing bulk document management are present, but core workflows are covered.
Self-hosted AI workspace: semantic RAG document search, long-term memory, and AI chat via MCP.
Cloud or self-hosted knowledge for AI agents: hybrid search, reranking, GraphRAG, scoped MCP tools.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
