memoir

Memoir

为编码 Agent 提供可移植、限定项目范围的记忆和会话交接。

Memoir 将决策、理由、目标和后续操作保存在易读的本地文件中。MCP 服务可让 Agent 保存和检索这些上下文。可选的本地、Git 和云端备份可在不同设备间传递这些内容。

可靠性方面的变更记录在修复记录中。升级共享加密备份的客户端前，请查看升级和恢复指南。

在这台电脑上的 Codex 和 Cursor 之间继续工作

Memoir 提供独立的、仅限项目范围的交接功能。它会传递已回答的问题、 决策、后续操作，以及通过 Memoir 实际运行的检查凭据。它不会导入个人记忆或对话记录。

以下项目交接、浏览器视图和恢复命令需要 3.16.0 或更高版本：

npm install -g [email protected]
cd /path/to/your/project
memoir work setup
memoir work resume
memoir work view

如需进行源码开发，请安装依赖，并将 memoir 替换为 Memoir 检出目录中的 node bin/memoir.js。

在 Codex 或 Cursor 中打开同一个文件夹和分支，然后说**“继续这个 项目。”** 托管指令会使用项目 MCP 连接；如果连接不可用，则使用附带的 CLI 后备方案。现有设置和 审批策略都会保留。仍需 Agent 遵循这些指令；普通的终端检查不会自动记录。

项目视图会在这台电脑的浏览器中打开。搜索已保存的 回答，查看某项检查为何需要重跑，修正决策，或将其从下一次交接中移除。已移除的记录可以恢复；较早版本仍保留在本地 历史记录中。使用项目视图时，请保持其终端窗口打开，并按 Ctrl+C 停止。 你也可以让 Agent “打开我的 Memoir 项目视图。” 请参阅 本地视图验证，了解实际浏览器测试 以及新会话连续性结果的局限。后续的 调试修复和恢复测试涵盖保存缓慢、 响应中断和配置保留问题。

通过 memoir work check 运行的检查使用客户端通常的终端 权限。MCP 记忆连接有意不具备执行命令的能力。 请参阅对抗性审计和剩余的信任限制。

项目日志保存在被忽略的 .memoir/ 文件中。此工作流不会通过 GitHub 同步这些文件，也不会连接不同的检出目录。请参阅 设置和日常使用指南，了解命令、修正方式、 隐私边界，以及何时需要重新运行检查。即使从 npm 安装，该功能也会在本地运行；发布软件包 不会上传你的项目日志。

现在，项目交接支持自动创建本地恢复快照。运行 memoir work doctor 检查快照，或运行 memoir work backup --output /path/to/backup.memoir 在项目之外创建加密副本。恢复操作会在应用更改前预览内容，并保留原始文件。请参阅备份和恢复。

现有记忆和备份工作流

Node.js 18 或更高版本可用于运行 CLI。生产环境建议选择仍受维护的 LTS 版本（Node 22 或 24）；Node 18/20 仍是兼容性测试目标。请参阅 Node 版本发布政策。

npm install -g memoir-cli
cd /path/to/project
memoir setup --tool claude,codex,cursor
memoir goal "Finish the account recovery flow"
memoir note "Use single-use recovery codes" --why "Prevent replay"
memoir next "Test expired recovery codes"
memoir recall "recovery codes"
memoir resume

setup 会保留现有设置，写入项目 MCP 条目，并启动 Memoir 服务以检查其工具。重启客户端并接受其项目信任/MCP 提示。服务启动并不能证明特定客户端版本已接受其配置。

如需进行源码开发，请使用 npm ci，然后运行 node bin/memoir.js setup。生成的条目使用 Node 和服务的绝对路径；移动安装位置后，请检查该条目。其他现有的 Memoir 条目会保留下来，供你检查。

memoir activate 会添加托管使用说明，并为检测到的受支持客户端进行设置。memoir resume --inject --to codex 会将托管交接信息添加到项目的 AGENTS.md，同时保留其他内容。

记忆与连续性

• memoir_note 记录有范围的决策及其理由。工作摘要写满后，较早的决策会归档。
• memoir_remember 写入规范的 Markdown 记录。使用 memoir_read 打开它返回的 ID，参数为 tool: "memoir"、filepath: "<id>.md"。
• memoir_recall 搜索当前项目和共享记录，并返回匹配段落、路径、行号证据，以及可用的 ID。
• 回想时会复用增量词法索引，同时在每次查询时检查源文件变更和范围。发现新的项目指令不会受到定时缓存延迟的影响。请参阅检索行为与基准测试。
• memoir_resume 返回目标、后续操作、问题和决策，并对比已保存的提交与当前检出版本。旧观察结果绝不代表当前测试已通过。
• memoir_forget 接受决策匹配项或规范 ID。隐藏记录不会出现在回想或会话视图中；purge: true 还会移除当前规范文本和本地修订历史。

规范记忆存放在 ~/.config/memoir/memories/，会话状态存放在 ~/.config/memoir/session.json。这些源文件以明文形式保存在设备上。备份加密不会加密这些文件。

新记忆使用 MEMOIR_PROJECT_ROOT 或工作目录。对于通用偏好，请使用显式的 scope: "shared"。Git 身份识别常见的 SSH/HTTPS 远程地址写法；本地身份基于相对于主目录的路径。重命名、不常见的远程地址别名或不同的目录布局可能需要显式选择范围。配置档案用于选择备份目标；它们不是彼此独立的安全租户。

没有范围元数据的旧记录会被视为共享记录，已识别的 Claude 项目目录除外。在依赖严格隔离之前，请检查并标记导入的历史记录。范围是组织边界，并不能防止已获准读取文件系统的 Agent 访问数据。

备份与恢复

首次使用时会创建本地配置。它不会创建 GitHub 仓库，也不会自动上传。使用 memoir init 选择其他目标和加密方式。

memoir push
memoir restore
memoir push --only claude,codex
memoir restore --only codex

经过筛选的推送会保留其他工具和机器的文件。会话记录和规范记录会随工具筛选内容一起保存，以实现跨工具连续性。

对于加密的本地/Git 备份，请通过环境变量或密码管理器提供 MEMOIR_PASSPHRASE，也可以交互式输入。旧版六字符密钥仍可读取；新备份请使用较长且唯一的密钥。未配置加密时，无人值守写入不会悄悄改用明文。

快照会验证清单和每个文件。缺失的二进制对象、损坏的内容、不安全的路径、符号链接和超大输入都会导致恢复失败。重复执行加密推送时，会先验证并合并先前的快照，再进行替换。本地加密迁移会在切换后从当前目标中移除明文；Git 历史记录和文件系统快照仍可能保留旧的明文。

本地推送会锁定整个读取、合并和写入操作。Git 会拒绝冲突的远程更新，不会强制推送；请重试以读取并合并新状态。请使用专用备份目录。

云端

新的云端写入需要用户持有的密钥，且至少为 12 个字符，存放在 MEMOIR_CLOUD_PASSPHRASE（或 MEMOIR_PASSPHRASE）中。该密钥不会根据账户身份派生，也不会发送到元数据中。所有套餐均支持客户端加密，并非仅限 Pro 套餐。

memoir cloud push
memoir cloud restore
memoir cloud restore --version 3
memoir cloud migrate
memoir cloud migrate --apply

写入端要求先执行部署指南中的数据库迁移。若未执行迁移，版本分配会在上传前失败。Memoir 托管服务已于 2026 年 9 月 6 日应用此迁移；请参阅部署检查。可自托管服务必须先应用迁移，才能启用新的写入。

cloud migrate 会显示迁移计划。--apply 会下载每个旧备份，创建使用用户口令的新备份，下载并按字节校验该备份，然后移除旧对象。迁移中断后可以复用替换后的备份。请确保每台用于恢复的设备都能使用该密钥；没有找回密钥的服务。

旧版按账户 ID 加密和未加密的云端备份仍可读取，但会显示警告。只有替换备份时，其保护方式才会改变。随机保险库密钥封装、设备注册、硬件支持的存储，以及经过独立审查的密钥轮换仍是未来工作。

恢复最新云端备份时，会合并保留版本中的会话状态和规范状态，因此需要额外下载。显式恢复版本则会选择该快照。云端测试使用模拟后端；生产环境中的授权和租户隔离需要单独验证。

可选工作区文件

memoir push --workspace 会从活动项目中捕获符合条件的文件，包括未被 Git 忽略的未跟踪文件。它不会归档整个主目录。

memoir restore --workspace 会将这些文件校验后放入 ~/memoir-restored/ 下的新文件夹，供检查。不会修改现有检出内容。会记录提交信息；这是文件快照，而非 Git 历史备份。

常见的密钥文件名和检测到的模式会被排除，并列在清单中。检测采用启发式方法。旧版基于 tar 的工作区归档会保留，但不再自动解压。

支持的界面

界面	功能	验证范围
Claude Code	项目级 MCP 配置、Memoir 工具、指令导入/导出	已测试 JSON 保留和真实服务启动
Codex	项目级 TOML MCP 配置、Memoir 工具、AGENTS.md 导入/导出、~/.codex/AGENTS.md 中固定的会话区块	已测试 TOML 往返转换和服务启动
Cursor	项目级 MCP 配置、Memoir 工具、规则导入/导出	已测试 JSON 保留和服务启动
其他现有适配器	所选记忆/配置的导入/导出	适配器固件测试，不涵盖完整的原生会话连续性
通用 MCP 客户端	Memoir 工具契约	真实 stdio 测试

配置参考：Claude Code、Codex、Cursor。

搜索、隐私与限制

搜索采用本地的 Unicode 感知型词法检索，并结合字段／文档频率权重、别名、筛选和段落预算。它不是语义搜索，也没有经过演示证明达到最先进水平的结果。

记忆是上下文，不代表有权运行命令或配置工具。模型编写的记录默认标记为 unverified。自动捕获转录内容尽力而为，不应视为工作已成功完成的证明。

memoir consolidate 会报告重复或过时文件。仅凭相似度不能删除不同内容。已确认的删除会保留恢复副本；打印出的 memoir consolidate --undo <id> 会恢复到不存在的目标位置。--smart 会明确向 Gemini API 发送有长度限制的摘录；使用 MEMOIR_CONSOLIDATE_MODEL 选择模型。

memoir clean-decisions 会报告那些并非源于你所做选择，而是转录捕获通过正则匹配生成的决策——这些条目是捕获模式的开头，在分句中途截断。此命令只报告；--apply 会将它们标记为删除，设置 hidden: true，但绝不删除内容，因此文本仍保留在磁盘上且可供审计。检测方式较为保守，基于文本进行：它可能漏掉泄露的条目，也不会标记带有 why 或被拒绝的替代方案的条目。

安装 SessionStart hook（memoir hooks install）后，memoir auto-refresh 会在标准输出中打印简短的会话摘要，Claude Code 会将其添加到模型上下文中。是否传递不再取决于模型是否选择调用 memoir_session。摘要上限约为 300 个 token，没有内容时保持静默，在压缩时跳过，并可通过 MEMOIR_NO_SESSION_BRIEF 禁用。使用 memoir auto-refresh --show-brief 预览。它会优先按手写的 [project] 文本前缀限定范围，其次使用存储的项目字段；未标记的条目会单独列出，不会被呈现为关于当前仓库的事实。

push --redact 会启发式地遮蔽暂存文本，不会处理原文或历史备份。不使用该选项时，普通记忆备份会发出警告并保留内容。新安装和已有安装的匿名使用遥测默认关闭。使用 memoir telemetry on 开启；使用 memoir telemetry status 检查；使用 memoir telemetry off 关闭。即使已选择开启，DO_NOT_TRACK=1 或 MEMOIR_TELEMETRY=0 也始终会禁用远程遥测。关闭时不会进行任何遥测网络调用，包括首次运行时。本地事件会区分执行失败与成功；它们不会衡量回答是否有用。

遗忘操作会在后续同步时传播到更新后的客户端。旧客户端、快照和 Git 历史中仍可能包含已删除文本。清除所有历史副本是另一项独立操作。原生配置恢复无法在多个应用目录之间以原子方式完成。

开发

npm ci
npm test
node evals/run.mjs
npm audit --omit=dev
npm pack --ignore-scripts

测试使用合成主目录和本地 Git 远程仓库。CI 声明支持 macOS/Linux/Windows，并使用 Node 18/20/22/24；shell 测试套件会跳过 Windows。有关验证限制，请参阅修复状态和发布门槛。

MIT 许可证