Cairn Remembers

Cairn

构建知识，留下线索。 — 为现代探索者打造的工具。

面向 AI Agent，也面向你自己的本地优先情景记忆。

Cairn 是一堆用来标记路径的石头。这个 Cairn 标记的是你思考的路径：每个决定、死胡同和理由都会成为一个节点，让你和任何模型都能在不同会话、不同模型世代中再次找到它。

• 本地优先 — 所有内容都保存在 ~/.cairn/ 下的一个 SQLite 文件中。无需云端、无需账户、没有遥测。
• 模型无关 — 任何能运行 shell 命令或使用 MCP 的 Agent 都可以使用：Claude、GPT/Codex、Gemini、本地模型。
• 仅追加 — 记忆会被作废，但不会删除。记录就是记录。
• 归你所有 — Cairn 不会将任何内容发送出你的设备。你的聊天仍会发送给你选择的模型，与未使用 Cairn 时完全相同；使用本地模型，则不会有任何内容离开你的设备。

两种开始方式：

• 🧑 你是要设置 Cairn 的用户吗？ 请继续阅读——快速开始约需 5 分钟。所有选项和修复方法见：QUICKSTART.md。
• 🤖 你是要为他人安装 Cairn 的 AI Agent 吗？ → SETUP_FOR_AGENTS.md 为你编写（安装、同意、归属）。

查看 Cairn 内部

保留你想要回头查看的决定、理由和未完成工作。Cairn 会将它们存储在本地保险库中，你和已连接的 AI 工具都可以读取并添加内容。每个 AI 都有自己的记忆和上下文。以下演示展示了用于浏览记录的可选仪表板。

中心	项目	连接
接续未完成的工作。	将相关工作归到一起。	探索关联的记忆。

查看全部五个演示及说明。

• 中心 — 9 秒
• 项目 — 18 秒
• 索引 — 6 秒
• 实时动态 — 14 秒
• 连接 — 8 秒

录制于本地安装环境中。私密文本使用示例替代；控件和来源归属信息均予以保留。该录制所用的安装版本尚未针对 0.3.3 版本中的每个控件进行验证。演示说明和录制备注。

目录

• 快速开始
• 接入你的 AI
• 你将获得什么
• 高级安装
• 多个账户
• 需要备份的内容
• 常用命令
• 许可证

快速开始

两个位置，切勿混淆： 🖥️ 你的终端（PowerShell / Terminal）——本页中的每条命令都在这里、你的电脑上运行。连接始终通过终端命令或编辑配置文件完成——AI 可以替你运行这些终端步骤（这是下面最快的方式），但绝不要把连接操作粘贴到聊天框中。 💬 AI 聊天——记忆会在这里显示，你也可以在这里通过要求 AI 使用它来测试连接。

最快方式——让 AI 帮你完成

打开 Claude Code、Codex 或 Cursor，然后粘贴：

帮我从 https://github.com/CairnRemembers/cairn 安装并设置 Cairn

AI 会运行终端步骤，并在启用记忆前征求你的同意——你电脑上的每个 AI 都会单独询问一次是否同意，默认选项为 No。未经你同意，不会记录任何内容。（使用 Codex？ 之后还需要额外粘贴一次——请参阅连接你的 AI。）

或自行操作

1 — 安装 🖥️ （只安装软件——不会记录任何内容，保险库初始为空）

⚠️ 在 Linux / WSL 上安装 [all]？ 请先运行 pip install torch --index-url https://download.pytorch.org/whl/cpu，否则 pip 会拉取你用不上的数 GB CUDA torch 套件。Windows 和 macOS 的 torch wheel 已经是 仅 CPU 版本。

pip install cairn-remembers            # base install
pip install "cairn-remembers[all]"     # + embedder + dashboard

从源码安装

仍然是更完善的方式——安装程序会替你处理 CPU torch 这一步：

获取代码 🖥️

git clone https://github.com/CairnRemembers/cairn
cd cairn

运行安装程序 🖥️

# Windows:      .\install.ps1      (blocked? powershell -ExecutionPolicy Bypass -File .\install.ps1)
# macOS/Linux:  ./install.sh

安装程序会查找 Python 3.11+、安装所有内容（首次运行会下载 PyTorch——Linux/Windows 上为轻量 CPU 版本，需要几分钟），并进行自检。

2 — 连接你的 AI。 记忆从这一步才会真正启用，而且每个 AI 的连接方式都不同——设置时输入 y 可以为 Claude Code 完成设置，但不能为 Codex 或 Claude Desktop 完成设置。请在下方找到你使用的 AI，并按照步骤操作，直到看到 ✅。

连接你的 AI

Cairn 有两种独立的连接方式，了解它们的区别可以避免所有常见意外：

• 捕获——自动记住你的聊天内容（写入保险库）。
• 工具——AI 可以在聊天中搜索和记录你的保险库内容（读取 + 按需写入）。

有些 AI 只需要一种连接方式，有些则两种都需要。不要在第一个 ✓ 处停下——请按照步骤操作，直到看到对应 AI 的 ✅。

Claude Code — 一条命令

🖥️ 在终端中：

python -X utf8 -m cairn setup        # answer y for Claude Code

这会连接捕获功能：每次新建 Claude Code 聊天时，都会自动获取上下文（你会看到横幅），在你工作时记录内容，并在聊天结束时进行整理。适用于整台机器，只需设置一次，可撤销（cairn disconnect --global）。只想用于一个项目？请在该代码库中运行 cairn connect（全局连接与单项目连接互斥——doctor 会标记这一点）。

✅ 完成标志：打开一个新聊天时，会显示 "CAIRN — inherited context" 横幅， 并且 🖥️ python -X utf8 -m cairn doctor 会显示 ✓ capture。

可选——原生工具： Claude Code 已经可以通过在其 shell 中运行 cairn 命令来读取保险库。若要改用原生 cairn_* 工具，请以用户级配置注册 MCP 服务，并指定可以 import cairn 的 Python（无法导入的裸 python 是最常见的故障原因——请先确认路径，QUICKSTART §6a）：

claude mcp add --scope user cairn -- <full-path-to-python> -X utf8 -m cairn mcp

💬 验证：请聊天中的 AI “调用 cairn_orient”。（doctor 无法检测这种连接方式——询问 AI 才是测试。）

OpenAI Codex — 三个部分，各司其职

1. 捕获 🖥️ — python -X utf8 -m cairn setup → 输入 y 选择 Codex（= codex-hook install）。 Codex 触发 notify 时实时捕获对话轮次（按轮次 ID 去重）。若要全面扫描磁盘上的所有内容，可随时运行 🖥️ python -X utf8 -m cairn import codex-sessions --apply。
2. 工具 📄 — 添加到 ~/.codex/config.toml，然后完全重启 Codex （完整的 §6 操作指南）：

[mcp_servers.cairn]
command = "<full-path-to-python>"
args = ["-X", "utf8", "-m", "cairn", "mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 120
default_tools_approval_mode = "approve"

3. 习惯 📄 — 创建 ~/.codex/AGENTS.md，粘贴 QUICKSTART §6c 中的记忆协议，让 Codex 主动了解上下文、获取记忆并记录笔记。（需要第 2 部分——协议会调用这些工具。）

✅ 完成标志： 🖥️ python -X utf8 -m cairn codex-hook status 输出 INSTALLED， 并且 💬 Codex 聊天对 “call cairn_orient” 的回复包含摘要（如果还配置了第 3 部分，它的首条回复会以 [cairn: oriented — N] 开头）。 ⚠️ 如实说明： cairn doctor 可以从结构上检测 Codex MCP 注册情况（即 [mcp_servers.cairn] 代码块），但无法证明服务能否启动，也无法证明 notify 钩子能否捕获——上述检查才是真正的验证方式。

Claude Desktop / Cursor — 粘贴一次即可

📄 添加到 claude_desktop_config.json（或 Cursor 的 MCP 设置）中，然后重启应用：

{
  "mcpServers": {
    "cairn": { "command": "python", "args": ["-X", "utf8", "-m", "cairn", "mcp"] }
  }
}

这就是工具接入方式——你可以在聊天中搜索、获取、探索和记录笔记。这些 界面不会自动捕获内容；你让 AI 执行 cairn_note 的内容才会被记录。 （如果应用找不到 Python，请使用安装 Cairn 时所用 Python 的完整路径。）

✅ 完成标志： doctor 显示 ✓ MCP — 已在 Claude Desktop 配置中注册 （Desktop），或者 💬 “call cairn_orient” 冒烟测试有回复（Cursor）。

适用于以上所有 AI：

• 接入只需一次。 新聊天会自动记住——无需在每次聊天中激活。orient 读取记忆，不会开启任何功能。接入范围因方式而异：Claude Code 钩子适用于整台机器（也可通过 cairn connect 限定到一个项目）；Desktop/Cursor 和 Codex 则使用各自应用中、每个账户独立的配置。
• 只有新的聊天才会使用新接入的配置——完成接入后，再开启一个新聊天。（长期运行的 MCP 客户端只有在完全重启后才会重新读取工具。）
• 隐私控制： 跳过单次聊天——在该 shell 中设置 CAIRN_CAPTURE=0（PowerShell $env:CAIRN_CAPTURE="0" · cmd set CAIRN_CAPTURE=0 · bash export CAIRN_CAPTURE=0）· 暂停所有捕获：cairn capture off / on · 写入前清除机密信息（仅追加，失败时默认拒绝）。
• 撤销： cairn disconnect [--global] · cairn codex-hook uninstall · 重新运行 cairn setup 以检查配置。

你将获得什么

• 一个保险库，适用于所有模型。 任何支持 MCP 或能运行 cairn 的 Agent 都可读写同一份记忆——因此，一个 Agent 可以在另一个 Agent 写入内容的基础上继续工作，即使它们来自相互竞争的厂商。
• 达到用量上限后也能接着做。 一个模型达到上限后，切换到另一个模型继续，并告诉它从哪里接着做——记录保存在保险库中，而不是某个模型的上下文里。
• 工作过程自动捕获——从完成接入起，决策、失败尝试、工具调用和对话轮次都会成为可搜索的节点。
• 值得保留的内容不会丢失。 每个捕获的对话轮次都会保存完整文本：搜索结果是摘要——也就是索引——cairn read <id> 会完整打印任意节点，MCP cairn_read 会调高 max_chars 并获取完整内容。
• 你来运行的本地维护流程——按习惯每晚运行 cairn sleep，也可以交给自己的调度器（它不会自行调度）：嵌入 → 整合 → 修剪 → 重建图谱 → 编译，所有操作都在你的机器上完成。“无需联网”只有一个例外：首次嵌入时会下载约 80 MB 的模型，只下载一次。
• 思维地图——仪表板星系图（cairn dashboard → http://127.0.0.1:7331），以及便于人类阅读的 Hub / Book / Index。
• 回填——将旧对话提炼为精炼且相互关联的 claim 节点。

高级安装

# Linux / WSL: install the CPU-only PyTorch first, or pip pulls a ~4.6 GB CUDA
# stack you don't need. (Want a GPU build? Install your torch first, then run the
# line below — it's preserved.) macOS: skip this line — its default wheel is CPU/MPS.
pip install torch --index-url https://download.pytorch.org/whl/cpu

pip install -e ".[all]"      # package + embedder + dashboard

pip install -e ".[embeddings]"   # no dashboard
pip install -e ".[dashboard]"    # no embedder

python3 -m venv .venv && source .venv/bin/activate && ./install.sh

多个账户

每个 AI 只登录一个账户？跳过此部分即可，一切都会自动正常运行。 每个 AI 都使用自己的账户登录，Cairn 会自动将该 AI 的工作存入其专属星系——Claude 和 GPT 绝不会混在一起，无需任何设置。

只有在同一个 AI 使用两个账户时才继续阅读（两个 Claude 登录账户、两个 ChatGPT/Codex 登录账户——例如个人和公司账户）。星系根据每个登录账户的稳定 ID 进行标识，永不合并——但在同一台机器上使用同一个 AI 的两个登录账户时，Cairn 不一定能确认当前使用的是哪一个。请遵循以下规则以保持区分明确：

声明，而非检测：提前为每个账户设置 CAIRN_ACCOUNT。

# Claude Code — launch each account with its label:
export CAIRN_ACCOUNT=work && claude        # bash/zsh (or set it in that profile)
#   PowerShell: $env:CAIRN_ACCOUNT="work"; claude
# Codex — put it in that account's ~/.codex/config.toml:
#   [mcp_servers.cairn]  env = { CAIRN_ACCOUNT = "work" }
# Importing old history? Always pass the flag:
cairn import <export> --source=claude --account=work

随时为账户命名和管理：

cairn account                          # list galaxies + node counts
cairn account rename <key> "Company"   # display label only — never merges or deletes
cairn account doctor                   # read-only check — prints the exact fix command per mismatch
cairn account fix-session <session-id> <slug>   # re-file ONE named session (backed up, then locked)
cairn account fix-session <slug>                # same, for the current session only

需要了解的限制——避免意外：

• Claude Desktop 会自动确认每个会话使用的账户。Claude Code CLI 和 Codex 无法做到这一点——它们会读取机器当前的登录文件，因此在会话进行中切换账户可能会导致会话被静默标记为先前的账户。CAIRN_ACCOUNT 才是可靠的保障，检测并不可靠。
• account doctor 会验证可确认的信息（Claude Desktop 会话）；无法审计纯 CLI 或 Codex 历史记录。
• 此处同样采用仅追加原则：重命名只会更改显示标签；不会合并任何内容，也不会删除任何内容。

需要备份的内容

只需备份一个文件夹：你的保险库 ~/.cairn/（其中的 cairn.db 保存着你的实际记忆）。其他内容都可以替换——代码托管在 GitHub 上，重新安装绝不会影响你的保险库。

常用命令

orient · note · fetch · wander · query · read（完整读取任意节点）· dashboard · doctor · setup · connect / disconnect / capture · account · backfill · sleep（维护周期——由你运行）· edges · book · import

包含所有选项的完整参考：QUICKSTART.md。

许可证

根据 Business Source License 1.1，可免费用于个人和非商业用途——阅读、运行、修改并自行托管。商业或企业用途需要商业许可证——请发送邮件至 [email protected]。源代码可用（不属于 OSI 定义的「开源」）；每个版本都会在其 LICENSE 中指定的变更日期转换为宽松的 MIT License。

专利申请中——一项涵盖 Cairn 核心机制的美国临时专利申请已于 2026-07-07 提交。Cairn Remembers™ 是 James Wescott Maitland IV 的商标。

知识是一条路径，而非终点。