Loci

Two thousand years ago, orators stored their speeches in the rooms of a palace and walked through them to remember. loci does the same for your files.

Loci is the method behind every memory palace: place knowledge in locations, recall it by walking the path.

A queryable "second brain" for the project docs, notes, and chat logs scattered across a dozen directories — and an MCP server so your AI agents can use it too.

Local files → heading-aware chunking → embeddings → hybrid retrieval (vector + BM25) → LLM answer with section-level citations. The index lives entirely on your machine; only embedding/chat calls go out, to any OpenAI-compatible API (Zhipu / DeepSeek / Kimi / OpenAI / …).

The thesis (from studying the 90k-star platforms and the graveyard of dead lightweight tools — see our competitive landscape study): don't build another chat app. Build the memory layer that every chat app can mount. Claude Desktop, Cursor, Cline, or any MCP host becomes this project's UI, for free.

Demo

Real session, indexed against the docs of minimax-h3-turing (paths shortened for display):

$ python main.py search "what the 22G card can and cannot do" -k 3

[1] minimax-h3-turing/docs/en/01-hardware-limits.md > 01 · What a 2080Ti 22G Can and Cannot Do    (similarity 0.562)
[2] minimax-h3-turing/docs/en/02-w4a8-vs-w4a4.md > 02 · Quantization Measured > You Can Try Without 22G  (similarity 0.446)
[3] minimax-h3-turing/docs/en/01-hardware-limits.md > ... > 3. VRAM is just barely enough — manage it  (similarity 0.504)

$ python main.py ask "How should I choose between T8 aggressive mode and the final-render mode, and why?"

Answer:
* Drafts / preview / shot selection: use T8 aggressive mode — a 43% speedup
  (2.7 min/clip), and "a different picture of equal quality" is fine for picking shots.
* Final shots: use final-render mode (no T8). T8 makes the numerical trajectory
  fork, so re-running with the same seed produces a different clip — which breaks
  the reproducibility final outputs need.

[source: docs/en/08-t8-blockcache-4step.md > Practical Advice (4-step Turbo route)]
[source: docs/en/06-faq.md > 12. Cache-style accelerators break "same-seed re-runs"]

Hybrid retrieval means a Chinese query still finds the English doc (and vice versa) — keyword evidence (BM25) catches what embeddings miss, and every citation points at a section, not just a file.

Does hybrid actually help? (mini-eval, 10 bilingual queries)

$ python scripts/eval_retrieval.py scripts/eval_cases.example.jsonl
vector-only: 9/10  →  hybrid: 10/10

Hybrid also fixed the #1 ranking on keyword-ish queries (e.g. "T8 block cache threshold speedup": vector put an FAQ first, hybrid puts the actual T8 writeup first). Run it against your own corpus with your own cases file.

Reranking: two providers

--rerank reorders the fused candidates for precision:

python main.py search "T8 speedup" --rerank          # provider from config
python main.py search "T8 speedup" --rerank local    # cross-encoder (BAAI/bge-reranker-base)

The local model downloads on first use (~1.1 GB; set HF_ENDPOINT=https://hf-mirror.com if HuggingFace is slow in your region). Measured on a 2080 Ti, bilingual query.

Office documents, PDF tables, web pages, org files, chat logs