Cairn.ink Memory

Cairn Memory

在 AI 会话之间保留重要上下文。情况变化时，随之更新。

English · 繁體中文

查看示例 · 从这里开始 · 本地设置 · 托管设置 · 限制 · 隐私

开启新的 AI 会话，往往意味着要再次说明自己的偏好和项目决策。Cairn 提供记忆工具，用于在会话之间保存这些上下文、查看每条记忆所附的提交文本，并在情况变化时更新记忆。

偏好发生变化

假设你保存了 “我的报告要简短。” 后来，你决定需要详细报告。你可以查看旧记忆及其来源文本、更正已保存的偏好，或者将其遗忘，使其不再用于主动回忆。

这是一个通过显式调用工具展示的示例，并非聊天客户端截图。本地预览会使用工具来保存、查看、更正和遗忘记忆；它不会自动读取你的对话。

• 查看来源。 阅读与记忆一同保存的来源文本。回执并不能证明记忆真实或解读正确。
• 更正变化之处。 根据你查看时的记忆修订版本进行更新。
• 遗忘应移除的内容。 将记忆从主动回忆中移除。 删除和备份的范围适用。

来源回执是附加到记忆上的提交文本。它能帮助你检查保存或更正记忆时提供了什么内容。它不是整段对话的经验证实记录，也不能证明人的意图。

Cairn Memory 和 Cairn

Cairn Memory 是本仓库中的开源工具包，用于保存、查看和更改 AI 记忆。Cairn 是面向人和 AI 的托管共享记忆地图，人们可以在其中整理、审核和分享知识。

本仓库包含本地记忆工具，以及连接到托管 Cairn 服务的连接器。每种使用方式都有各自的设置和功能范围。本地使用无需 Cairn 账户；连接托管服务则需要兼容的服务和身份验证。

选择起点

您想要……	从这里开始	所需条件
安装前先了解这个理念	繁體中文 或录制的演示	无需安装或账户
在电脑上试用开源工具	本地预览设置 或 Windows 指南	终端设置；Linux x64 和范围有限的原生 Windows x64 检查；无需 Cairn 账户
使用文档中介绍的托管 Claude Code 或 Codex 连接	托管设置	兼容的托管服务和身份验证；与本地预览客户端支持相互独立
在记忆层上进行构建	架构 和 MCP 工具	JavaScript 或 MCP 集成工作

如果您使用 Claude 或 Codex，但通常不会从终端安装工具， 请从示例和录制的演示开始。此预览版需要进行设置； 连接 AI 工具前，请查看已测试的客户端路径。

当前预览版

Cairn 的开源记忆层会将记忆存储在您自己的 SQLite 文件中， 并通过 MCP 或 JavaScript 提供访问。无需 Cairn 账户即可本地使用。

开发者预览版。 已安装的持久化功能和范围有限的真实模型记忆循环已有 留存证据。默认提取功能仍未达到我们的来源支持标准；请参阅已知限制。 无需模型密钥即可保存、检查、修正和遗忘。语义召回 需要您的 OpenAI 密钥，并会将所选上下文发送给该服务提供方。

观看录制的演示

观看 36 秒的无模型演示（MP4）。 此演示记录的是记忆工具的运行情况，而非 Claude 或 Codex 中的对话。“无模型”表示演示过程中不会调用 AI 模型。

如需查看长对话的结果，请参阅四案例真实模型试点。 这是一项自愿参与的诊断，其中有一个 Cairn 回答失败，并非对 默认客户端长期召回可靠性的测量。已知限制

打开录制的工具演示（GIF）

以下演示记录的是无模型循环：保存、重启、检查、修正 和遗忘。其召回步骤会报告 model_not_configured。

录制的响应和重新生成说明 · 已验证的功能和客户端支持

## 安装

对于 Claude Code 和 Codex，运行一键安装程序：

npx @cairn-ink/memory setup

首次交互式安装会询问一次：使用此计算机上的本地 MCP 记忆工具，还是登录 cairn.ink 使用云端自动记忆；也可以通过 setup --local 或 setup --cloud 直接选择。首次非交互式运行需要指定 --local 或 --cloud；在 0.6.0 中，本地模式不支持自动捕获或回忆。

安装程序 0.6.0 于 2026-10-25 发布，因此 npx @cairn-ink/memory setup 会使用该版本；也可以在代码检出目录中运行 node packages/setup/bin/memory.mjs setup。插件版本为 0.3.3。 需要 Node ≥22.16，且 PATH 中至少有一个 CLI。云端设置会询问是否添加新工具、 更新已连接的工具，并在同时连接两者时使用一次浏览器登录。 默认服务为 cairn.ink。若存在冲突的服务或记忆 ID，会显示选项； 非交互式运行遇到冲突时不会更改任何内容。启用自动记忆前，Codex 必须通过格式 资格验证。自动化的 codex exec 运行默认会跳过捕获和提示词回忆；可通过 npx @cairn-ink/memory config --codex-capture-exec on 选择启用。

选择适合你工作流的模式：

• **本地预览：**使用你自己的 SQLite 数据库， 通过显式 MCP 记忆工具操作，无需 Cairn 账号。从这里开始体验开源 记忆层。语义回忆需要 OpenAI 密钥。
• **现有云端集成：**在 cairn.ink 上存储记忆， 通过 Claude Code 插件自动捕获和回忆。需要 Cairn 账号、令牌和兼容的服务。 也可使用显式云端 MCP。

试用本地记忆层

前置条件：Git、Node >=22.16、npm 和 tar。已记录的检查涵盖 Linux x64 和有限范围内的原生 Windows x64 安装。 在 Windows 上，请使用 PowerShell 设置与演练指南； 以下命令使用 Linux/WSL 路径。其他平台尚未验证。 请从此代码库安装： 未加作用域的 npm 和 PyPI 软件包 cairn-memory 是无关项目。 本地归档目前尚未发布到 npm。

1. 安装到新目录。 将下方路径替换为你可控制的现有父目录下 一个新的绝对目录。

git clone https://github.com/Cairn-ink/cairn-memory.git
cd cairn-memory
npm run install:preview -- --directory /absolute/new/cairn-local --owner local-user

安装程序会构建此检出，并在不运行安装脚本的情况下下载固定版本的公开 npm 依赖。 它会创建 app/、data/ 和私有的 installation-receipt.json，其中包含可执行文件路径和 MCP 设置。 它不会调用模型。请妥善保管回执：其中包含本地路径和身份信息。安装详情、恢复与备份

2. 运行无模型检查。 在源代码检出目录中，使用相同的 安装路径。无需设置聊天客户端，也无需模型密钥。

npm ci --prefix adapters/mcp
node adapters/mcp/walkthrough.mjs --executable /absolute/new/cairn-local/app/node_modules/.bin/cairn-memory

预期结果为 status: "passed"。检查会使用全新的合成数据库，并验证 五个工具、回执、进程重启后的持久性、更正和遗忘功能。 它会从子进程中移除模型密钥；model_not_configured 是预期的回忆结果。步骤与预期结果

3. 连接客户端。 将私有安装回执中的 stdio.command 和 stdio.args 复制到客户端的本地 MCP 配置中。每次会话都使用相同的数据库、所有者和项目。请参阅 已测试的客户端矩阵。

如需语义回忆，请通过 MCP 进程的 密钥环境显式提供 OPENAI_API_KEY。演练指南中的可选 --with-recall 路径会将 合成上下文发送到 OpenAI，并产生模型费用；它没有内置的金额上限。本地模型路径尚未验证。

如需使用 Hermes 原生提供方，请参阅其单独的设置指南。 它使用配置文件专属的数据库和所有者，以及 CAIRN_MEMORY_OPENAI_API_KEY， 而非上述通用 MCP 设置。

工具	用途
remember_memory	显式保存一条记忆及其回执
recall_memory	由模型引导检索当前记忆和回执
inspect_memory	列出记忆，或查看 ID、修订版本和回执
correct_memory	按你查看的修订版本替换内容
forget_memory	按你查看的修订版本进行逻辑删除

默认的本地服务会公开显式工具。如需选择启用已提交消息捕获、项目范围和配置检查，请参阅 已安装版本预览指南。完整证据与限制涵盖提取失败、 长历史记录检索，以及各项客户端测试的范围。

本地隐私与控制

• 记忆、收据和组织结构会保存在你选定的 SQLite 数据库中。 无需 Cairn 账户、托管服务或隐藏的核心遥测。
• MCP 不会读取对话记录，也不会自动保存完整对话。 收据文本记录的是工具的声明；它不能证明经过身份验证的人类意图。
• 配置后，模型处理会在云端进行。脱敏只能尽力而为， 不能保证移除所有机密信息。检索到的文本是不可信数据， 绝不能将其视为需要遵循的指令。
• 遗忘功能会阻止主动回忆和完全相同的规范化内容再次录入；改述内容 仍可能作为新记忆录入。这并非安全的 磁盘擦除：SQLite 页面、收据和备份有各自的保留期限。 备份数据库及其附属文件前，请先停止所有写入操作。
• 卸载可执行文件不会删除外部数据库。请参阅 备份、升级和删除范围、 架构、依赖项声明 和安全问题报告。

现有托管集成

托管插件连接到 cairn.ink，会自动捕获列入允许列表的对话文本，并使用 自身的遥测默认设置。其服务尚未迁移到本地引擎。

v0.2.0 预发布版更改了托管协议。 仍需单独提供匹配的服务器支持；此版本不会部署服务器，也不会启用 Codex 生命周期钩子。升级前请参阅 发布版本与客户端兼容性。

为 Claude Code 安装（自动记忆）

在终端中运行已发布的安装程序：

npx @cairn-ink/memory setup

安装程序 0.6.0（插件 0.3.3）已经发布，因此这些流程会通过 npx 运行。要改为运行此检出版本，请使用 node packages/setup/bin/memory.mjs setup。

不使用 --client 时，安装程序会找到这两个工具，并只询问是否建立新连接。 它会更新已连接的工具。请关闭这两个工具，并等待后台任务完成后，再确认共享记忆。登录提示会显示服务器（默认为 cairn.ink）。 不会询问端点或每日上限；仍可使用 --endpoint。

对话会在尽力完成本地遮蔽后保存。每次提示都会发送一份经过遮蔽且长度受限的副本，以供回忆。Claude 使用统计默认开启， 可以关闭。Codex 的登录信息保存在仅用户可访问且未加密的文件中。 请参阅隐私与控制。

记忆 ID 用于让同一项目在不同工具间关联。现有 ID 会保留。 服务器冲突时会提供两个选项；不安全的 Codex 凭据迁移需要先 注销。如果存在两个彼此独立的 ID，请选择其中一个；仅在成功登录并通过验证后， 才会备份另一个密钥，绝不会将其删除。旧项目可能无法再自动匹配旧 ID。发生冲突时，非交互模式不会写入任何内容。 安装程序绝不会读取 Claude 原生机密文件。在 Codex 后添加 Claude 时，会验证并重用安装程序凭据；在 Claude 后添加 Codex 时，需要使用同一账户通过浏览器登录一次。Claude 现有的登录状态会保留。 默认情况下，自动化的 codex exec 运行会跳过自动捕获和提示词回忆。运行 npx @cairn-ink/memory config --codex-capture-exec on 以启用；使用 off 恢复默认设置。此设置会同时为 exec 启用捕获和回忆。只有启用时，status 才会显示此设置；重新运行 setup 会保留该设置。 Hook 会读取转录记录中与会话绑定的 session_meta.payload.source，并检测原生 exec 上级进程，以支持恢复旧 CLI 线程的 exec resume。如果缺少标头或无法验证，Hook 会跳过捕获和注入。具有已验证 CLI 标头的交互式会话会正常运行。Codex app-server 上的线程（自 0.160 起的 TUI、VS Code 扩展和桌面应用）只有在其 originator 属于这三个客户端之一时才会被视为交互式；其他 app-server 客户端会被视为 exec，需要同样选择启用。必须先通过 setup 更新较旧的冻结运行时；config 会打印确切的命令。

若要停止提示词回忆，同时保留自动捕获，请运行 npx @cairn-ink/memory prompt-recall-off --client codex。 运行 prompt-recall-on --client codex 可重新启用。此操作不会更改 MCP。

Codex 默认每天自动捕获 200 次；重新运行时会保留已有上限。使用 setup --codex-daily-cap N 或 config --codex-daily-cap N 更改上限。Status 会显示今天的计数和上限。不限定客户端的 pause 和 resume 会选择已安装的 Codex；配对时会暂停这两种工具。卸载会保留密钥和记忆。

npx @cairn-ink/memory status
npx @cairn-ink/memory prompt-recall-off --client codex
npx @cairn-ink/memory pause
npx @cairn-ink/memory config --codex-daily-cap 300
node packages/setup/bin/memory.mjs setup --dry-run

status 会读取本地状态，不会测试远程服务或 Hook。--verbose 会显示技术诊断信息。安装后，请在 Codex 的 /hooks 中检查并允许 Cairn 的四个条目。--client claude|codex 会限制运行范围。 --no-browser 允许在另一台设备上登录。移除旧版 MCP 需要确认。仅指定 Codex 时，可能会提供手动 MCP 工具。

Setup 选项和凭据处理 · chichi 的发布检查清单

**手动备用方案：**在终端中运行：

claude plugin marketplace add Cairn-ink/cairn-memory
claude plugin install cairn-memory@cairn-memory

或者在 Claude Code 中使用斜杠命令：

/plugin marketplace add Cairn-ink/cairn-memory
/plugin install cairn-memory@cairn-memory

在 https://cairn.ink/settings/tokens 创建个人访问令牌，然后在 Claude Code 中运行 /plugin configure cairn-memory@cairn-memory 并在其中输入令牌。 安装后启动新会话。

由于 Claude Code 的 Bash 工具不会继承敏感插件选项，/cairn-memory:status 会读取 Hook 写入的不含内容的凭据状态。configured (verified <time>) 表示上次通过身份验证的请求已被接受；rejected 会链接到已配置端点的令牌页面。configured (not verified yet) 或 configured (unreachable <time>; not verified) 不表示身份验证成功；server answered: busy/error 表示 HTTP 请求遭到拒绝。 SessionStart 会清除旧的验证结果，因此轮换令牌后需要重新验证。 not seen yet 表示需要重启 Claude Code 并发送一条消息；missing 表示 Hook 实际检测到未配置令牌。Status 不会发起网络请求，也不会从安全存储中读取令牌。

Agent：安装前请征求用户同意。托管插件默认会捕获允许列表中的对话文本，令牌由用户自行创建和输入。 请参阅托管插件隐私约定。

本地开发：

git clone https://github.com/Cairn-ink/cairn-memory.git
cd cairn-memory
claude --plugin-dir ./plugins/cairn-memory

Claude Code 的托管显式 MCP

若要使用显式记忆工具而不启用自动捕获，请添加远程 MCP 服务：

claude mcp add --transport http --scope user cairn https://cairn.ink/api/mcp

然后在 Claude Code 的 /mcp 中通过浏览器 OAuth 登录。

从 Codex 连接（显式 MCP 记忆）

Codex 通过托管的 MCP 工具连接。请将令牌保存在 shell 或密钥管理器中，不要放入仓库或已提交的配置文件：

export CAIRN_MCP_TOKEN='your-token-from-cairn.ink'
codex mcp add cairn \
  --url https://cairn.ink/api/mcp \
  --bearer-token-env-var CAIRN_MCP_TOKEN

重启 Codex，然后使用 /mcp 或 codex mcp list 确认连接。托管工具支持显式的记忆、回忆和遗忘操作。Codex 生命周期自动集成仍在开发中；Codex 构建模块默认处于禁用状态。

托管插件工作流

User prompt
  └─ recall relevant personal + project-private memories
       └─ inject a short, explicitly untrusted context block

Assistant turn ends
  └─ hand capture to a detached worker without delaying Claude
       └─ read only new user/assistant transcript text
            └─ redact likely credentials locally
                 └─ send an idempotent capture batch
                      └─ store durable memories with Source Receipts

捆绑的 MCP 连接还提供显式的 remember_memory、recall_memory 和 forget_memory 工具。没有生命周期钩子的客户端可以手动使用这些工具；如果宿主不提供钩子，我们绝不会声称支持被动捕获。

托管插件隐私规范

• 安装需由用户明确操作。安装后会开始自动捕获，且默认开启。
• 仅将用户和助手的文本消息块列入允许列表。
• 排除工具结果和工具调用块；插件不会读取任意项目文件。不过，普通的用户或助手文本仍可能包含粘贴的文件内容、终端输出、路径或仓库名称，因而会被处理。
• 在传输之前，会在本地对捕获文本和自动回忆查询中的受支持凭证格式进行替换，替换为 [REDACTED]。脱敏是尽力而为的，并不保证能识别所有机密。托管服务还会再次脱敏，以提供纵深防御。
• 自动回忆会向配置的服务发送当前提示词的脱敏、有长度限制的版本。此操作发生在捕获之前，属于独立的处理路径。
• 如果宿主会话 ID 符合 1–200 个字符的 ASCII 允许列表（A–Z、a–z、0–9、.、_、:、-），提示词回忆会发送该 ID。可信钩子会提供此 ID，而非模型文本；服务器只存储作用域限定为用户的 SHA-256 哈希值。对于较旧的严格服务器，会在不含该可选字段的情况下，按完全相同的架构重试一次。
• 项目作用域是带密钥的不可读标识符。其派生密钥不会离开设备，并且与匿名遥测 ID 分开。
• 自动推断的记忆仅限个人或项目私有，不能发布到团队或社区。
• 产品遥测不包含内容，默认开启，且可禁用。其架构仅接受生命周期事件、客户端版本、平台和随机安装 ID。
• 钩子采用故障开放策略：Cairn 服务中断和超时不会阻止 Claude Code 正常工作。
• 捕获工作线程会脱离主进程运行，因此无头 claude -p 会话在结束清理时无法取消它们；允许列表中的数据会通过管道直接传递给工作线程，不会写入队列文件。

使用 /cairn-memory:pause、/cairn-memory:resume 和 /cairn-memory:status 控制捕获和回忆。

暂停期间的文本不会自动补录。恢复后，每个会话的第一个捕获钩子都会跳过当前尚未处理的历史记录（包括恢复后较早的文本）；之后的完整消息会被捕获。暂停前已启动的请求可能会完成。请参阅隐私指南中关于暂停边界的详细说明。

阅读完整的隐私与威胁模型。安全问题请通过 SECURITY.md 中说明的私密渠道报告，不要提交公开问题。

开放内容

本仓库是以下内容的唯一事实来源：

• Claude Code 插件和市场清单；
• 本地对话记录筛选、脱敏和项目身份推导；
• 公共 HTTP/MCP 线路协议和 JSON Schemas；
• 本地 SQLite 核心，包括回执、命名空间隔离、捕获编排、MOC 组织、模型引导的回忆、修正和删除抑制；
• 可选的 OpenAI 适配器、精简的本地 MCP 主机和经过检查的安装产物；
• 一致性测试和自托管实现指南。

Cairn.ink 托管提取服务、用户数据库、身份验证、计费、滥用控制和生产运维均位于单独的私有仓库中。有关公共服务边界，请参阅架构和自托管。

状态

已发布的托管插件和本地开发者预览版的就绪程度不同。本地安装生命周期已通过验证，但源支持质量仍未达标；目前尚未获准大范围推广。首批 10 位用户的结果和星标目标均未宣称已实现。请参阅已知限制、ROADMAP.md和拟议的采用实验。

为仓库点星，以关注本地预览版和即将推出的集成。

开发

无依赖的插件运行时和测试套件需要 Node.js 20 或更高版本。仅维护者使用的 Claude 插件验证工具需要 Node.js 22，并隔离在 tools/plugin-validation 下，因此绝不会随插件安装。

npm test
npm run test:setup
npm run validate
npm ci --prefix tools/plugin-validation
npm run validate --prefix tools/plugin-validation

在 Node >=22.16 上使用本地存储（无需安装依赖项）：

npm run test:core
npm run demo:store

欢迎贡献，请先阅读 CONTRIBUTING.md 和 docs/protocol.md 中的隐私不变量。