Talamus

Talamus

会话一结束，你的编码 Agent 就忘了做出某项决策的原因。

Talamus 将值得记住的决策、证据和修正作为普通 Markdown 保存下来， 然后让 Claude Code、Codex、Cursor、Gemini CLI 和任何 MCP Agent 在下一次会话中 都能通过引用找回这些内容。

无需托管账户。无遥测。无需强制使用嵌入。普通搜索留在你的设备上；由大模型驱动的操作只使用你选择的引擎。

先试试完整的本地检索流程——无需持久安装、账户、 大模型或钩子，也不会在 ./talamus-demo 之外写入任何文件：

uvx --from talamus talamus demo --root ./talamus-demo
uvx --from talamus talamus search "embedding" --root ./talamus-demo
uvx --from talamus talamus read "Embedding" --root ./talamus-demo

如需进行技术评估，请阅读 架构和 实测基准。

Talamus 由 Giovanni “Angio” Crapuzzi 创建并维护，隶属于 Ampres，这是一个独立的 AI 与开源项目。 工程案例研究 记录了该项目背后的架构、测量结果和权衡取舍。

连接 Agent

可直接复制粘贴的流程，可在 scripts/demo/run_magic.py中查看可复现版本：

1. 设置项目知识库。talamus setup 会初始化知识库、选择引擎，在检测到 Claude Code、Cursor、Codex、OpenCode 和 OpenClaw 时为它们安装 MCP，在安装会话捕获钩子前征求一次同意，并可通过一次极小的实时调用探测引擎。

   talamus setup
   

2. Agent 会话结束。经同意启用的钩子会读取对话记录和 git diff，应用记忆价值筛选，只将有用的记忆写入此知识库，并在 .talamus/logs/capture.log 中记录事件审计信息。

3. 新会话会询问发生了什么，并根据真实笔记给出带来源的回答。

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

4. 无需消耗大模型调用即可重现脚本演示，也可以使用你的真实引擎运行。

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

有何不同

时间：笔记具有版本历史，事实具有有效时间窗口，而 talamus ask --as-of 2026-01 会根据当时的知识库作答。

含义：本体由证据归纳生成、进行版本管理、按实测规则提升，并用于对知识库进行聚类和路由。

可验证性：每条笔记都带有来源信息；talamus verify 会提出修正建议供审核，回答也会引用所用笔记。

实测对比

单屏基准测试在基准测试指南中呈现，并提交为one-screen.md。 下方每个数字都可追溯至已提交的结果产物。

语料	指标	Talamus	BM25	MiniLM vector DB
SciFact，仅限英语领域	recall@10	0.797	0.776	0.783
SciFact，仅限英语领域	nDCG	0.664	0.652	0.645
Book，跨语言 + 模糊查询	hit@10	0.971	0.829	0.743
Book，跨语言 + 模糊查询	recall@10	0.929	0.771	0.700

已提交的产物中还测得：与将知识库加载到上下文相比，每个答案的 token 数减少 97.7%；面对范围外问题时，拒答率为 1.000；在 10k 条笔记时，搜索延迟 p95 为 72.6 ms；在 100k 条笔记时，p50 为 624 ms。

坦诚地说：检索质量取决于你使用的大模型。配合强大的扩展引擎时，talamus-smart 在包括排名在内的所有指标上都领先于强大的多语言稠密模型（multilingual-e5）（nDCG 为 0.847，对比 0.837）；配合较弱或免费的引擎时，e5 的排名表现更好，而 Talamus 的命中率和召回率仍然最佳；在速度较慢的本地引擎上，普通 search 则明显胜过 --smart。每个数字都可追溯至已提交的产物；结果中的不足也一并列出。

引擎

使用你已有的大模型：claude-cli、codex-cli、antigravity-cli（agy）、opencode、ollama 或 anthropic-api。

快速入门

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

运行 talamus 查看状态仪表盘，运行 talamus quickstart 查看基本命令，或运行 talamus ui 打开本地 React 工作台。

Agent MCP 连接默认只读。如需让 Agent 明确更新此项目知识库，请使用 talamus mcp install --enable-writes 重新生成其配置；写入中央知识库还需要额外添加 --enable-central-writes 标记。

从 skills.sh 安装尊重用户同意的 Talamus Agent 技能：

npx skills add ampres-ai/talamus --skill talamus-memory

OpenClaw 也可以直接从 ClawHub 安装同一个独立技能：

openclaw skills install @ampres-ai/talamus-memory

安装独立技能不会自动安装 Talamus。如果缺少 CLI，该技能会说明隔离安装选项，并在运行安装操作前征求同意。

Gemini CLI 可以直接从其扩展库或此仓库安装 Talamus。该扩展通过 uvx 启动指定版本的 PyPI 发布包，因此不会修改克隆的源代码树：

gemini extensions install https://github.com/ampres-ai/talamus --auto-update

goose 可以将该仓库安装为 Open Plugin。这会添加尊重用户同意的记忆技能，并在每次新的 CLI 会话中启动指定版本的本地 MCP 服务：

goose plugin install https://github.com/ampres-ai/talamus.git

该插件要求 PATH 中包含 uv；首次使用时，uvx 会将 Talamus 及其 MCP 依赖下载到隔离缓存中。

容器化 MCP（知识库仍保存在挂载的本地文件夹中）：

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

链接

文档：快速入门、本地优先的 Agent 记忆、Agent 安装指南、命令、Agent 工具调用、配置、基准测试、架构、设计原则、评估、多脑、本体。

项目：安全、贡献指南、路线图、更新日志。

源代码、问题跟踪和发布历史均位于 ampres-ai/talamus。

开发

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

python dev.py 会运行 ruff、格式检查、mypy 和 unittest。产品行为变更应在同一项更改中更新用户文档。

许可证

Apache-2.0。