Cairntir

Cairntir

面向 AI 编码 Agent 的持久化、本地优先记忆。Claude Code、Codex、 Cursor、Qwen Code 和其他 MCP 客户端共享一份可搜索的项目历史。

Cairntir 将决策、事实、未完成的工作和结果以原文形式存储为 抽屉，保存在由你掌控的 SQLite 数据库中。预算受限的交接会在不同会话间恢复完整 抽屉；语义检索和文件锚定检索则可找到更深层的证据。

当前版本：1.12.3。请参阅 版本发布证据和更新日志。 已发布的下载可在 PyPI和 GitHub Releases获取。

安装

pip install --upgrade cairntir
cairntir setup

需要 Python 3.11+。安装程序会初始化存储，并为其检测到的受支持 宿主配置服务。之后请重启 Agent。

cairntir version
cairntir doctor

以下诊断变更尚未发布；目前，pip install 会安装已发布的 1.12.3。该版本的 doctor/status/version 仍可能运行注册和更新回调，status 也可能以写入模式打开存储。在将已安装的诊断工具视为只读之前，请先查看变更记录。

在此候选版本中，version 会报告此 CLI 的版本。status 和 doctor 会检查存储 和配置，不会注册宿主或检查更新。已配置的 MCP 条目并不能证明连接正常。安装程序的本地写入/读取 检查不能证明宿主能够接收信息，也不能证明语义检索有效：请先确认收到实际的 保存回执，然后在新聊天中使用验证步骤恢复准确的任务。

变更与采用记录区分候选、已发布、已安装和已通过宿主验证的变更，并列出剩余检查及回滚 范围。源代码编辑不会更新已经运行的宿主。

若只针对一个宿主或项目，请使用 cairntir init --host codex；添加 --user 可配置用户范围。Cursor 的全局 User Rule 需要手动粘贴；安装程序会显示规则并提示此步骤。

请参阅入门指南，了解配置、 验证、恢复和故障排除。

使用

让 Agent 将一项决策记在项目对应的 wing 中，然后在下一个任务开始时调用 cairntir_handoff(wing="myproject")。wing 代表项目，room 代表主题，drawer 则是一条原文记忆。

cairntir handoff myproject
cairntir handoff myproject --task "repair cache invalidation" --budget 8192
cairntir recall "why did we choose Postgres?" --wing myproject
cairntir recall-for-change src/auth.py
cairntir recover --host codex --wing myproject
cairntir cost myproject

交接会返回完整的抽屉，或列出因字符预算而省略的抽屉名称。 其中包含近期写入默认层的内容、未关闭的预测，以及可选的代码锚点。 结算会追加观测到的结果，而不会改写预测。

可移植证据可在不同存储间保留来源标识和 关系。经评估的流程 需要留出验证证据和本地批准；范围限定的共享 通过所有者签发的授权来限制访问。

主机支持

界面	支持情况
配置	Claude Code、Cline、Codex CLI、Copilot CLI、Cursor、Gemini CLI、OpenCode、Qwen Code
转录恢复	Claude Code、Codex、Qwen Code
其他 MCP 客户端	手动配置 cairntir-mcp stdio 命令
Cursor 转录	不支持；明确的回执会说明这一限制

转录恢复需选择启用，单独计入预算，只读且不可信。 它会读取有界的、由主机管理的转录尾部；无法恢复主机从未保存的文本。 只有通过 cairntir recover ... --write N 明确选择后，才能保存恢复的请求。记忆不会仅仅因为出现在转录或导入文件中，就自动成为权威信息。

数据与安全

权威存储是本地 SQLite 和 sqlite-vec。嵌入在本地运行；首次使用时可能会下载嵌入模型。可选的更新检查会连接 PyPI，明确选择的 LLM 适配器则可能连接其提供商。Cairntir 并非供使用它的 Agent 使用的沙箱。

可移植 JSONL 会验证内容哈希，并可通过 Python API 验证 HMAC 签名。CLI 会将导入内容视为不可信，且不会验证签名。版本 1 无法安全导入源端本地的历史引用；对于关联历史记录，请使用数据库备份。导出和导入也会强制执行该格式对外部 URL 的限制。有关备份和信任边界，请参阅数据处理。

构建与集成

MCP 服务通过 stdio 暴露 21 个工具。稳定的 Python 协议支持自定义后端；请参阅集成指南。

src/cairntir/
├── memory/       # SQLite storage, embeddings, retrieval
├── mcp/          # stdio server and backend
├── reason/       # prediction, experiment, observation
├── recipes/      # composable workflows
└── cli.py        # cairntir setup | init | handoff | recover | recall | replay | hotfix | doctor | export | import
tests/            # unit, integration, contract, property, evaluation
docs/             # guides, architecture, recipes, release evidence

贡献指南介绍了锁定的开发环境和必需的检查。测试要求被测范围的覆盖率至少达到 80%；传输入口不计入其中，并单独测试。LongMemEval 子集是回归门槛，并不代表通用基准测试结果。

文档

• 入门指南
• 概念与数据处理
• 多主机架构
• 配方：CodeGlass、Decision Replay、Signal Reader、Bounded Hotfix 和 Finalization Mode
• 路线图
• 安全政策 · 发布政策
• 设计原则 · 谱系

Cairntir（CAIRN-teer）将石冢——由石块堆叠而成的路标——与观视之石结合。由 Patrick McGuire 维护。采用 MIT 许可证。