callimachus

AI 编码 Agent 对话线程的本地索引与搜索工具——支持 11 种工具（Claude Code、Codex、Cursor、Gemini CLI、Qwen Code、Goose、OpenCode、Continue、Cline、Roo Code、Kilo Code），还提供与模型提供商无关的聊天功能、MCP 服务、命令行工具，以及 VS Code / Cursor 扩展。所有数据都保留在你的设备上。

名称取自 Callimachus，他建立了亚历山大图书馆的首个目录。

下载

从 Releases 获取最新的签名版本——macOS（.dmg，Apple Silicon）、Windows（.msi）或 Linux（.AppImage / .deb）。此后应用会自动更新。想自行构建？请参阅开发。

功能

• 为11 种编码 Agent 的每段对话建立索引，并存入一个本地 SQLite 存储库——Claude Code、Codex、Cursor、Gemini CLI、Qwen Code、Goose、OpenCode、Continue、Cline、Roo Code 和 Kilo Code。添加其他来源只需遵循一份简明且有文档说明的约定。
• 搜索采用混合排序：通过倒数排名融合（Reciprocal Rank Fusion），将关键词搜索（SQLite FTS5 / BM25）与设备端语义相似度（sqlite-vec KNN，无云端）结合。可按来源、项目、子 Agent、收藏和标签筛选。
• 按代码查找——在搜索栏输入 file:embed/mod.rs（或运行 cal files <path>），即可查找所有涉及某个路径的对话；索引时会建立文件提及索引，为此提供支持。
• 提炼知识——免费进行启发式 TODO 提取，还可选择使用大模型提炼决策、注意事项和摘要，并从过去的决策和注意事项中跨对话进行语义检索。可选的自动提炼会在后台处理新增或变更的对话，让记忆自动积累。支持使用本地 Ollama（无需密钥）、已登录的 Claude Code 或 Codex CLI 订阅（无需密钥或 API 密钥），或云端 API 密钥。
• 整理事实——固定、编辑或删除提炼出的事实，让你的编辑在重新提炼后仍能保留；还可通过大模型执行**“检查冲突”**，标记彼此矛盾的决策。
• 按项目记忆——Projects 标签页会汇总每个代码仓库的决策、注意事项和未完成 TODO，形成持久记忆（按规范项目键分组，因此工作树 / 符号链接 / ~ 不会拆分同一个代码仓库），并提供大模型简报和受管理的 .callimachus/memory.md。使用“在 CLI 中打开”时，该记忆会被前置；你也可以自动将其注入任何 Agent：更新 AGENTS.md（或运行 cal agents）会在代码仓库的 AGENTS.md / CLAUDE.md 中写入受管理区块，而 cal hook 会将其提供给 Claude Code SessionStart 钩子。
• 询问你的历史记录（RAG）——基于你自己的对话生成综合答案，并附上 [thread N] 引文，指向所用来源。需要启用大模型引擎（开启 Knowledge/提炼功能）。
• 整理为合集——收藏对话并添加自由格式标签，然后按收藏或标签筛选列表。
• 与内置 Agent 聊天（Anthropic / OpenAI / Gemini / OpenRouter / Ollama——本地或云端——或无需密钥的已登录 Claude Code / Codex CLI）；它可以搜索你自己的历史记录，并在你批准后运行 shell 命令；支持流式传输、取消操作，并实时提供模型列表。聊天内容会保存，也可以搜索。
• 在工具间传递上下文——在任意 Agent CLI 中打开任意对话（“在 Claude / Codex / Gemini 中打开……”；会预先载入整理好的对话记录）、在原生 CLI 中继续 Claude Code / Codex 对话、复制上下文，或将对话导出到 Obsidian（可选由 AI 总结决策 / 注意事项 / TODO）。
• 将对话关联到提交——通过比对对话中提及的文件与对话时间范围内 git log 中变更的文件，在设备端推断某段对话产生了哪些 git 提交（共享文件数量 = 置信度）。可查看对话→提交时间线（cal commits）、桌面 UI 中的单个对话信息（“Produced commits”），或使用 linked_commits MCP 工具。
• 为 Agent 会话创建快照——为对话建立持久、可恢复的检查点（整理好的对话记录 + 可延续的项目记忆），以便在上下文窗口压缩或跨工具交接时使用；也可通过 Claude Code PreCompact / SubagentStop 钩子自动捕获。可创建、列出和恢复快照（cal snapshot / cal snapshots / cal resume，或使用 snapshot_session / list_snapshots / load_snapshot MCP 工具）。
• 守护决策——决策可以附带理由（“为什么”）；启用守护后，Agent 若要重新讨论某个主题，会先看到已确定的决策（cal check "<proposal>" / check_decision MCP 工具）。
• 重做之前先回忆——可选的 Claude Code 钩子会在每次提示词到来时，悄悄将“你以前可能解决过这个问题”注入 Agent 的上下文，前提是当前任务与先前工作高度匹配（Settings → Claude Code → 主动回忆，默认关闭，并设有信号阈值，且每个会话仅提示一次）。
• 挖掘反复出现的问题——汇总你在所有工具中不断遇到的错误（归一化特征，最近 180 天），让你能修复问题模式而非个别案例（Coach 卡片或 cal issues）。
• 显示成本——在建立索引时记录每条消息的 token 用量和模型，然后按模型估算费用，并列出最昂贵的对话（Stats 卡片或 cal cost；重新建立一次索引即可补齐历史数据）。
• 为 PR 审查提供数据——cal audit-pr <repo> --changed-files … --shas … 会返回一个 JSON 数据包（每个提交的来源，可追溯到产生它的会话；每个文件的历史对话及推理；代码仓库中的常见错误；项目记忆），供外部本地 PR 审查工具展示差异背后的历史记录。
• 向你的 Agent 提供信息——随附的 MCP 服务（callimachus-mcp）将索引公开为工具，供任意 Agent 在会话期间调用；它还是双向的：Agent 可以写回 Callimachus 自己的记忆（关闭 TODO、记录决策 / 注意事项、为会话创建快照），无需触碰你的文件。/recall skill 会教 Agent 何时使用这些功能。
• 后台文件监视器会让内容始终保持最新；同时保护隐私——API 密钥存储在操作系统密钥链中，除你选择的大模型提供商外，不会向任何地方发送数据。

技术栈

• Shell： Tauri 2 (Rust) + React 19 + TypeScript + Vite 8
• **存储/搜索：**内置 SQLite + FTS5 (rusqlite)；通过 fastembed 在设备上生成嵌入向量（bge-small-en-v1.5，384 维）；通过 sqlite-vec (vec0) 在 SQL 中进行 KNN 搜索
• 监视器：notify + 防抖器
• **聊天：**通过 genai crate 支持多个提供商（Anthropic / OpenAI / Gemini / OpenRouter / Ollama local + Ollama Cloud），每个提供商都可配置基础 URL；通过 Tauri Channel 流式传输令牌；支持取消，并提供 Agent 工具调用（历史记录搜索 + 经批准的 shell 命令）
• **密钥：**通过跨平台 keyring crate 使用操作系统凭据存储——macOS Keychain、Windows Credential Manager、Linux Secret Service
• Sidecar：callimachus-mcp（MCP 服务）和 cal（CLI）——两者都通过同一个 index.db 重用桌面核心库
• **编辑器：**VS Code / Cursor 扩展（apps/vscode，已发布到 Marketplace + Open VSX），通过 shell 调用 cal

Monorepo

这是一个 Turborepo + pnpm 工作区。

apps/
  desktop/        # the Tauri 2 desktop app + the cal CLI and MCP server (src-tauri)
  vscode/         # VS Code extension (search history from the editor)
  web/            # marketing + download site (reserved, not built yet)
packages/         # shared code, when it appears
.changeset/       # version + changelog management
scripts/          # version-sync, release tagging

发布、版本管理和自动更新程序的文档见 RELEASING.md。

开发

pnpm install
pnpm desktop:dev      # launches the desktop window (tauri dev)

# from the repo root, across all apps:
pnpm build            # turbo: build every app's frontend
pnpm typecheck        # turbo: typecheck every app

首次启动时，索引为空——打开 Settings（或点击 Reindex）为你的来源建立索引，然后点击 Build semantic index 以启用语义搜索。Reindex 作为后台任务运行，并为每个来源显示单独的进度条，与 Build semantic index 分开运行——两者互斥（其中一个持有写入锁时，另一个会暂停）。

测试

cd apps/desktop/src-tauri
cargo test                                   # fast unit tests
cargo test -- --ignored --nocapture          # real-data + model + keychain smoke tests

--ignored 测试会读取此设备上的实时数据：每个来源都有一个 real_<source>_index 冒烟测试，以只读方式为你的真实历史记录建立索引（~/.claude、~/.codex、Cursor、~/.gemini、~/.qwen、Goose、OpenCode、Continue、Cline/Roo/Kilo）；此外还会测试嵌入模型下载（首次运行时需要网络）和 Keychain 往返读写。

随时随地使用你的历史记录

除了桌面窗口，你的 Agent、终端和编辑器也能访问同一个本地索引——它们都读取同一个 index.db。

MCP 服务——让任意 Agent 在会话过程中搜索自己的过往工作。最快的方法是使用 npx（首次运行时会下载预构建的二进制文件）；它也已列入官方 MCP 注册表，名称为 io.github.betabots-llc/callimachus：

claude mcp add callimachus -- npx -y callimachus-mcp    # or any MCP client

已经在运行桌面应用？callimachus-mcp 已在你的 PATH 中，因此无需使用 npm，就能运行 claude mcp add callimachus -- callimachus-mcp。要从检出目录构建？运行 cargo install --path apps/desktop/src-tauri --bin callimachus-mcp。

工具（21 个）——现在既可读，也可写。读取工具（17 个）：search_threads、search_current_project（自动限定为运行所在的代码仓库）、recent_threads、get_thread、list_tags、list_open_todos、get_thread_knowledge、recall_decisions、recall_gotchas、find_prior_work（“我以前做过这件事吗？”防护——查找与某个任务相似的过往会话）、project_memory（项目汇总的决策、注意事项和未完成 TODO）、ask_history（基于历史记录并附有引用的 RAG 答案）、threads_for_file（哪些会话涉及某个路径）、check_decision（在重新讨论提案之前，先展示已达成共识的决策）、linked_commits（某个会话可能产生的提交）、list_snapshots（项目的会话快照）和 load_snapshot（恢复已保存的检查点）。写入工具（4 个，只写入 Callimachus 自身的记忆，不会改动你的代码）：complete_todo（关闭未完成的 TODO）、record_decision（可选填写 rationale）、record_gotcha（将事实保存到项目记忆中）和 snapshot_session（为交接创建会话检查点）。捆绑的 /recall 技能（.claude/skills/recall）会告诉 Agent 何时使用这些工具。

CLI——cal，支持管道操作。随桌面应用一同提供（已在你的 PATH 中）；也可以从检出目录运行 cargo install --path apps/desktop/src-tauri --bin cal 构建。

cal search "vector index migration" -y    # -y = hybrid (semantic + keyword)
cal recent -n 10
cal cat 42 | pbcopy                        # packed transcript → clipboard
cal stats                                  # index totals + per-source breakdown
cal export 42 --vault ~/Obsidian           # write a thread as an Obsidian note
cal ask "how did we set up releases?"      # cited RAG answer over your history
cal files embed/mod.rs                     # threads that touched a file path
cal memory                                 # this repo's distilled memory (decisions/gotchas/TODOs)
cal done 17                                # mark an open TODO done (id from `cal todos`)
cal remember decision "use sqlite-vec for KNN" --because "no cloud, KNN in SQL"  # record a fact (+ rationale) into the repo's memory
cal check "switch to pgvector"             # surface settled decisions before re-litigating one
cal commits                                # infer the thread→commit timeline for this repo (--json; or pass a path)
cal issues                                 # recurring errors you keep hitting across sessions (last 180 days)
cal cost                                   # estimated $ spend by model + your priciest threads
cal audit-pr . --changed-files a,b --shas s1,s2  # one JSON bundle for an external PR auditor
cal snapshot 42 -l "pre-refactor"          # checkpoint a thread for handoff (transcript + project memory)
cal snapshots                              # list saved session snapshots (optionally for a project)
cal resume 7 -a claude                     # resume a snapshot in an agent CLI
cal agents                                 # write the repo's memory into AGENTS.md (any agent reads it)
cal hook                                   # print the repo's memory (use as a Claude Code SessionStart hook)

此外还有 star、tag、tags、todos、knowledge、distill、decisions、gotchas 和 related——运行 cal help 查看完整列表。

VS Code / Cursor——此扩展会添加“Callimachus History”侧边栏、状态栏搜索按钮，以及用于搜索、插入和复制会话的命令（通过 shell 调用 cal）。可从 VS Code Marketplace 或 Open VSX（Cursor 和 VSCodium 使用的注册表）安装，也可以从 Releases 获取 .vsix。详见 apps/vscode/README.md。

说明 / 限制

• 跨平台（macOS / Windows / Linux）。目前仅有“在 CLI 中打开”/“恢复”启动器只能在 macOS 上使用（它们通过 AppleScript 控制 Terminal）；在 Windows/Linux 上，这些操作会显示“暂不支持”提示——其他所有功能（索引、搜索、聊天、导出、密钥链）均可正常使用。
• Cline / Roo Code / Kilo Code 是没有 CLI 的编辑器扩展，因此只能用于索引（可以搜索，但无法通过“恢复”重新启动）。
• Cursor 不会为每个会话保存工作区，因此 Cursor 会话目前没有项目路径。
• Claude Code 子 Agent 的对话记录会编入索引，但默认由“subagents”开关隐藏。
• 首次建立大型索引需要一次性耗时（此处的 Claude 语料约有 9 万条消息，耗时约 25 秒）；后续处理会跳过未更改的文件。
• 其他来源（Charm Crush、Factory Droid、Copilot CLI）已纳入范围，但尚未集成——请参阅索引器指南。

参与贡献

欢迎提交问题和 PR。CONTRIBUTING.md 介绍了本地设置、约定和发布流程。为其他 Agent 添加支持只需遵循一份简短且有文档说明的约定——通常只需一个索引器模块、一次迁移和少量接线改动。

安全与隐私

Callimachus 从设计上就以本地优先：你的对话索引永远不会离开你的设备，API 密钥存储在操作系统钥匙串中（绝不写入磁盘），唯一的出站流量会发往你明确选择的大模型提供商。如需报告漏洞，请参阅 SECURITY.md。

许可证

双重授权。 根据 AGPL-3.0-or-later 免费开源 — 可使用、修改和分享；如果你分发该软件，或将修改后的版本作为网络服务运行，则必须根据 AGPL 发布源代码。

对于 AGPL 不允许的闭源、专有或营利性/SaaS 用途，必须获得商业许可证 — 请参阅 COMMERCIAL.md（联系 [email protected]）。

© 2026 Ari Shaller。署名信息请参阅 NOTICE。我们根据 CONTRIBUTING.md 中的条款接受贡献。

致谢

本项目基于 Tauri、fastembed-rs、sqlite-vec 和 genai 构建。项目名称取自 Callimachus of Cyrene，他曾为亚历山大图书馆编制目录。

_{社交媒体预览图：assets/og.png · 品牌素材位于 assets/brand/}