Talamus

Talamus

Talamus is a local-first knowledge compiler — a second brain you and your AI agents share.

Your agent remembers. Locally. €0.

It turns documents, notes, repos, URLs, and agent sessions into source-grounded Markdown concept notes, then answers from those notes with citations — powered entirely by the LLM you already have.

Talamus is an open-source project by Ampres, an independent AI and open-source lab.

If Talamus makes agent memory less disposable, star the repository so other builders can find it.

The 60-second story

Copy-pasteable arc, with the reproducible version in scripts/demo/run_magic.py:

1. Install the CLI.

   pipx install "talamus[mcp]"
   

2. Set up the project brain. talamus setup initializes the brain, chooses an engine, installs MCP for Claude Code/Cursor/codex, asks once before installing the session-capture hook, and can probe the engine with one tiny live call.

   talamus setup
   

3. Your agent session ends. The consented hook reads the transcript and git diff, applies the worth-remembering gate, writes only useful memory into this brain, and audits the event at .talamus/logs/capture.log.

4. A fresh session asks what happened and gets an answer from real notes, with sources.

   talamus recall "why did we choose FTS5?"
   talamus ask "why did we choose FTS5?"
   

5. Reproduce the scripted demo without spending LLM calls, or run it with your real engine.

   python scripts/demo/run_magic.py --fake
   python scripts/demo/run_magic.py --keep --engine claude-cli
   

What is different

TIME: notes have version history, facts have valid-time windows, and talamus ask --as-of 2026-01 answers from the brain as it was.

MEANING: the ontology is induced from evidence, versioned, promoted by measured rules, and used to cluster and route the brain.

VERIFIABILITY: every note carries provenance; talamus verify proposes corrections to review, and answers cite the notes they used.

Measured comparison

The one-screen benchmark is rendered at docs/benchmarks.md and committed at benchmarks/results/one-screen.md. Every number below traces to a committed artifact under benchmarks/results/.

corpus	metric	Talamus	BM25	MiniLM vector DB
SciFact, English-only turf	recall@10	0.797	0.776	0.783
SciFact, English-only turf	nDCG	0.664	0.652	0.645
Book, cross-language + vague	hit@10	0.971	0.829	0.743
Book, cross-language + vague	recall@10	0.929	0.771	0.700

Also measured: −97.7% tokens per answer versus loading the brain into context, 100% source-resolvable answers, refusal 1.000 on out-of-scope questions, search latency p95 72.6 ms at 10k notes / p50 624 ms at 100k.

The honest part: retrieval quality tracks the LLM you bring. With a strong expansion engine, talamus-smart leads a strong multilingual dense model (multilingual-e5) on every metric including ranking (nDCG 0.847 vs 0.837); with a weak or free one, e5 leads ranking while Talamus keeps the best hit/recall — and on a slow local engine, plain search beats --smart outright. Every number traces to a committed artifact; the losses stay on the table.

Engines

Bring the LLM you already have: claude-cli, codex-cli, antigravity-cli (agy), opencode, ollama, or anthropic-api.

Quickstart

pipx install "talamus[mcp]"
talamus setup
talamus ingest ./notes && talamus ask "what should I remember?"

Run talamus for the status dashboard, talamus quickstart for essential commands, or talamus ui for the local React workbench.

Containerized MCP (the brain remains in the mounted local folder):

docker run --rm -i -v "$PWD:/data" ghcr.io/ampres-ai/talamus:1.0.3

Links

Docs: quickstart, agent install guide, commands, agent tool calling, configuration, benchmarks, architecture, design principles, evaluation, multi-brain, ontology.

Project: security, contributing, roadmap, changelog.

Maintained by Ampres. Source code and issue tracking live at ampres-ai/talamus.

Development

pip install -e ".[dev,mcp]"
python dev.py

python dev.py runs ruff, format check, mypy, and unittest. Product behavior changes should update user docs in the same change.

License

Apache-2.0.