ProjectRecall

Local retrieval over your own project notes, served to Claude Code as an MCP server. Ask "how did I fix that crash?" and get the paragraph you wrote months ago, with its file and line.

How it works

1. Index — markdown files in allowlisted folders are split by heading, so every chunk keeps its breadcrumb (Project > Bugs > Encoder drift).

2. Embed — chunks are embedded on your machine with nomic-embed-text through Ollama.

3. Store — one SQLite file holds the text, an FTS5 keyword index and the vectors.

4. Search — BM25 and vector rankings are merged with weighted reciprocal rank fusion.

5. Serve — an MCP server over stdio exposes search_notes and list_projects.

New to search or RAG? Start with the documentation: concepts, usage, architecture, retrieval, evaluation and privacy, written for readers without a background in any of them.

Related MCP server: ai-lab

Privacy model

The repository contains code and an invented sample corpus only.

• The index and the real config live in %LOCALAPPDATA%\ProjectRecall, outside the repository.

• Indexing is allowlist-only, and files that look like secrets (.env*, *.key, ...) are always skipped.

• Embeddings are computed locally; no hosted embedding API or vector database is used.

• The server speaks stdio only and opens no network port.

• A pre-commit guard blocks database files and any staged line that matches a privately indexed note.

Retrieved snippets do become part of the conversation with whichever MCP client asks for them.

Setup

py -3.11 -m venv .venv
.venv\Scripts\pip install -e ".[dev]"
ollama pull nomic-embed-text
git config core.hooksPath .githooks

.venv\Scripts\recall init      # creates the config; add your folders to it
.venv\Scripts\recall index
.venv\Scripts\recall search "why did training crash"

Register with Claude Code:

claude mcp add --scope user project-recall -- <repo>\.venv\Scripts\python.exe -m recall.server

Evaluation

python eval/run_eval.py indexes sample_corpus/ (16 invented projects with deliberately overlapping topics, 148 chunks) and scores questions from eval/golden.jsonl. A question is answered at rank r if the r-th chunk comes from the expected file and contains the expected text.

Fusion settings were tuned on 99 dev questions. The table is the held-out test split: 59 questions (42 paraphrased, 17 exact-term), assigned by hash and scored once, after the settings were fixed.

Hybrid hit@1 has a 95% interval of 81.6% to 96.3%. It beats BM25 on 19 questions and loses on none. Against vector search it is ahead on average but level question by question (2 better, 2 worse), so this eval does not show hybrid beating vector search; it does show hybrid as the only mode that puts the answer in the top five every time.

Plain RRF (equal weights, k = 60) scored below vector search alone. The fix was a small k, a vector weight of 0.8, and equal weights for short exact-term queries. See docs/retrieval.md and docs/evaluation.md.

Tests

.venv\Scripts\python -m pytest

License

MIT. See LICENSE.