{
  "markdown": "# Talamus\n\n<!-- mcp-name: io.github.ampres-ai/talamus -->\n\n[![CI](https://github.com/ampres-ai/talamus/actions/workflows/ci.yml/badge.svg)](https://github.com/ampres-ai/talamus/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/talamus)](https://pypi.org/project/talamus/) [![MCP Registry](https://img.shields.io/badge/MCP_Registry-active-5b5bd6)](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.ampres-ai%2Ftalamus) [![Smithery](https://img.shields.io/badge/Smithery-install-111827)](https://smithery.ai/servers/ampres-ai/talamus) ![license](https://img.shields.io/badge/license-Apache--2.0-blue) ![python](https://img.shields.io/badge/python-3.11%2B-blue)\n\n**Your coding agent forgets why a decision was made as soon as the session ends.**\n\nTalamus keeps the decisions, evidence, and corrections worth remembering as\nordinary Markdown, then gives Claude Code, Codex, Cursor, Gemini CLI, and any\nMCP agent cited recall in the next session.\n\n**No hosted account. No telemetry. No required embeddings. Plain search stays\non your machine; LLM-backed actions use only the engine you choose.**\n\nTry the whole local retrieval loop first — no persistent install, account,\nLLM, or hook, and no files written outside `./talamus-demo`:\n\n```bash\nuvx --from talamus talamus demo --root ./talamus-demo\nuvx --from talamus talamus search \"embedding\" --root ./talamus-demo\nuvx --from talamus talamus read \"Embedding\" --root ./talamus-demo\n```\n\nFor a technical evaluation, read the\n[architecture](https://ampres-ai.github.io/talamus/architecture/) and the\n[measured benchmarks](https://ampres-ai.github.io/talamus/benchmarks/).\n\n![Talamus demo — a completed agent session becomes cited, local memory for the next one.](https://raw.githubusercontent.com/ampres-ai/talamus/main/docs/assets/talamus-demo.gif)\n\nTalamus was created and is maintained by\n[Giovanni “Angio” Crapuzzi](https://github.com/GCrapuzzi) under\n[Ampres](https://ampres.io), an independent AI and open-source project.\nThe [engineering case study](https://ampres-ai.github.io/talamus/case-study/)\ndocuments the architecture, measurements, and trade-offs behind the project.\n\n## Connect an agent\n\nCopy-pasteable arc, with the reproducible version in\n[`scripts/demo/run_magic.py`](https://github.com/ampres-ai/talamus/blob/main/scripts/demo/run_magic.py):\n\n1. Set up the project brain. `talamus setup` initializes the brain, chooses an engine, installs MCP for Claude Code, Cursor, Codex, OpenCode, and OpenClaw when detected, asks once before installing the session-capture hook, and can probe the engine with one tiny live call.\n\n   ```bash\n   talamus setup\n   ```\n\n2. 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`.\n\n3. A fresh session asks what happened and gets an answer from real notes, with sources.\n\n   ```bash\n   talamus recall \"why did we choose FTS5?\"\n   talamus ask \"why did we choose FTS5?\"\n   ```\n\n4. Reproduce the scripted demo without spending LLM calls, or run it with your real engine.\n\n   ```bash\n   python scripts/demo/run_magic.py --fake\n   python scripts/demo/run_magic.py --keep --engine claude-cli\n   ```\n\n## What is different\n\n**TIME**: notes have version history, facts have valid-time windows, and `talamus ask --as-of 2026-01` answers from the brain as it was.\n\n**MEANING**: the ontology is induced from evidence, versioned, promoted by measured rules, and used to cluster and route the brain.\n\n**VERIFIABILITY**: every note carries provenance; `talamus verify` proposes corrections to review, and answers cite the notes they used.\n\n## Measured comparison\n\nThe one-screen benchmark is rendered in the\n[benchmark guide](https://ampres-ai.github.io/talamus/benchmarks/) and committed\nas [`one-screen.md`](https://github.com/ampres-ai/talamus/blob/main/benchmarks/results/one-screen.md).\nEvery number below traces to a\n[committed result artifact](https://github.com/ampres-ai/talamus/tree/main/benchmarks/results).\n\n| corpus | metric | Talamus | BM25 | MiniLM vector DB |\n|---|---:|---:|---:|---:|\n| SciFact, English-only turf | recall@10 | **0.797** | 0.776 | 0.783 |\n| SciFact, English-only turf | nDCG | **0.664** | 0.652 | 0.645 |\n| Book, cross-language + vague | hit@10 | **0.971** | 0.829 | 0.743 |\n| Book, cross-language + vague | recall@10 | **0.929** | 0.771 | 0.700 |\n\nAlso measured in committed artifacts: **−97.7% tokens** per answer versus loading the brain into context, refusal **1.000** on out-of-scope questions, and search latency p95 **72.6 ms** at 10k notes / p50 **624 ms** at 100k.\n\nThe 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.\n\n## Engines\n\nBring the LLM you already have: `claude-cli`, `codex-cli`, `antigravity-cli` (agy), `opencode`, `ollama`, or `anthropic-api`.\n\n## Quickstart\n\n```bash\npipx install \"talamus[mcp]\"\ntalamus setup\ntalamus ingest ./notes && talamus ask \"what should I remember?\"\n```\n\nRun `talamus` for the status dashboard, `talamus quickstart` for essential commands, or `talamus ui` for the local React workbench.\n\nAgent MCP connections are read-only by default. To let an agent deliberately\nupdate this project brain, regenerate its configuration with `talamus mcp\ninstall --enable-writes`; central-brain writes require the additional\n`--enable-central-writes` flag.\n\nInstall the consent-aware Talamus agent skill from [skills.sh](https://skills.sh):\n\n```bash\nnpx skills add ampres-ai/talamus --skill talamus-memory\n```\n\nOpenClaw can install the same standalone skill directly from ClawHub:\n\n```bash\nopenclaw skills install @ampres-ai/talamus-memory\n```\n\nInstalling the standalone skill does not install Talamus automatically. If the\nCLI is missing, the skill explains the isolated installation choices and asks\nbefore running one.\n\nGemini CLI can install Talamus directly from its extension gallery or from this\nrepository. The extension starts the pinned PyPI release through `uvx`, so it\ndoes not modify the cloned source tree:\n\n```bash\ngemini extensions install https://github.com/ampres-ai/talamus --auto-update\n```\n\ngoose can install the repository as an Open Plugin. This adds the consent-aware\nmemory skill and starts the pinned local MCP server for each new CLI session:\n\n```bash\ngoose plugin install https://github.com/ampres-ai/talamus.git\n```\n\nThe plugin requires `uv` on `PATH`; `uvx` downloads Talamus and its MCP\ndependencies into an isolated cache on first use.\n\nContainerized MCP (the brain remains in the mounted local folder):\n\n```bash\ndocker run --rm -i -v \"$PWD:/data\" ghcr.io/ampres-ai/talamus:1.1.3\n```\n\n## Links\n\nDocs: [quickstart](https://ampres-ai.github.io/talamus/quickstart/), [local-first agent memory](https://ampres-ai.github.io/talamus/local-first-agent-memory/), [agent install guide](https://github.com/ampres-ai/talamus/blob/main/llms-install.md), [commands](https://ampres-ai.github.io/talamus/commands/), [agent tool calling](https://ampres-ai.github.io/talamus/agent-tool-calling/), [configuration](https://ampres-ai.github.io/talamus/configuration/), [benchmarks](https://ampres-ai.github.io/talamus/benchmarks/), [architecture](https://ampres-ai.github.io/talamus/architecture/), [design principles](https://ampres-ai.github.io/talamus/design-principles/), [evaluation](https://ampres-ai.github.io/talamus/evaluation/), [multi-brain](https://ampres-ai.github.io/talamus/multi-brain/), [ontology](https://ampres-ai.github.io/talamus/ontology/).\n\nProject: [security](https://github.com/ampres-ai/talamus/blob/main/SECURITY.md), [contributing](https://github.com/ampres-ai/talamus/blob/main/CONTRIBUTING.md), [roadmap](https://github.com/ampres-ai/talamus/blob/main/ROADMAP.md), [changelog](https://github.com/ampres-ai/talamus/blob/main/CHANGELOG.md).\n\nSource code, issue tracking, and release history live at\n[ampres-ai/talamus](https://github.com/ampres-ai/talamus).\n\n## Development\n\n```bash\npip install -e \".[dev,mcp]\"\npython dev.py\n```\n\n`python dev.py` runs ruff, format check, mypy, and unittest. Product behavior changes should update user docs in the same change.\n\n## License\n\nApache-2.0.\n",
  "bytes": 8560,
  "sha": "be584ea328750e215c82311a7307dcba7340830979f64ba26b280108f815ff40",
  "repo_slug": "ampres-ai/talamus",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_ampres_ai_talamus_2315c921/readme"
}