open-memex

open-memex

为你的 AI 编码 Agent 提供持久记忆——存储在你的机器上，以纯 Markdown 格式呈现，并由你使用的所有编码工具共享。

中文文档

每次 AI 编码会话都从零开始：你要重新解释项目，Agent 又会重新发现相同的注意事项，而昨天的决策会在聊天结束后消失。open-memex 为你的 Agent 提供跨会话留存的记忆。只需说一次“记住：我们每周五部署”，下周 Copilot、Cursor、opencode 或 Claude Code 就已经知道了——因为它们都会读取和写入你机器上的同一份本地记忆。

• 免费且开源（Apache-2.0）。无需账号、无需云服务、没有遥测——所有内容都存储在你的机器上，保存在你可以打开和编辑的文件中。
• 本地优先：记忆以纯 Markdown 文件的形式保存（这是事实来源），并配有可重建的 SQLite 关键词索引。除非你主动分享，否则任何内容都不会离开你的机器。
• 一份记忆，适用于所有 Agent：用一条命令接入多个编辑器；它们共享同一份记忆，而不是各自维护孤立的数据。
• 精准的同义词搜索：搜索 ship 可找到 deploy，搜索 单点登录 可找到 SSO——每份记忆写入时都会索引一份精心整理的多语言对应词表，因此不会因措辞相关而漏掉正确答案。结果确定且可审计，无需嵌入模型。

初次使用？本 README 将在约一分钟内带你完成安装并运行记忆功能。概念指南会在你完成设置后深入讲解其思路。

目录

• 快速开始
• 核心概念
• 编辑器与功能
• 安装
• 设置编辑器
• init 会对你的机器做哪些更改
• 捕获：记忆如何保存
• Agent 可使用的工具
• 记忆类型
• 团队工作流：通过 Git 分享记忆
• 检索：如何找回记忆
• 安全与数据
• 限制
• 升级
• 存储布局
• 配置
• CLI 参考
• MCP 服务
• 作用域详解
• 故障排除
• 常见问题
• 项目状态

快速开始

你需要 Node.js ≥ 22.14（使用 node -v 检查）。然后：

npm install -g open-memex
open-memex init

init 会检测已安装的编辑器（VS Code、Cursor、opencode，以及在项目包含解决方案文件时检测 Visual Studio），并将它们逐一连接到 open-memex。之后重启编辑器。

看看它如何运行（30 秒）：

open-memex add "This project deploys on Fridays"

现在，在编辑器中打开一个新聊天，并询问你的 Agent：“这个项目什么时候部署？”它已经知道答案——无需重新解释。这一来一回，保存一次，永久找回，就是这个产品的全部。下文将介绍详细信息。

可选但推荐——检查所有配置是否已连接：

open-memex doctor

核心概念

四个理念几乎可以解释 open-memex 的所有工作原理。

1. 两种范围：project 和 personal。 每条记忆都属于以下两个位置之一：

• project — 关于某个代码库的知识（决策、约束、经验）。 自动限定为当前仓库；无需手动设置。
• personal — 关于你的知识（偏好、习惯），适用于每个项目。它只保存在本机，绝不会共享到仓库中。

关于你的事实（“我偏好简洁的差异”）会保存到 personal；其他所有内容默认归入当前项目。

2. 捕获 → 回忆。 记忆会保存为小型 Markdown 文件，每个文件记录一条事实。在每个新会话的第一轮中，open-memex 会自动将最相关的记忆交给你的 Agent，让它在会话开始时就了解这些信息。Agent 也可以按需搜索完整记忆。你无需亲自“加载”任何内容。

3. 你的文件，你的规则。 Markdown 文件是事实来源——你可以打开、编辑、删除和 grep 它们。旁边的 SQLite 索引只是用于加速搜索，并且可随时从文件重建（open-memex reindex）。如果你想与团队共享，流程与代码相同：所有内容都不会自动共享（参见团队工作流）。

4. 知识保持最新。 事实会发生变化：决策会被推翻，工具会被替换，昨天遇到的问题也会得到修复。open-memex 不会让旧版本悄然留存——memory_supersede 会用新版本替换一条记忆并保留链条，让检索提供当前事实，同时保留可审计的历史记录。仅仅过时的记忆可以弃用，而 open-memex audit 会报告重复项、过时条目和断裂的链条。清理是产品功能，而非日常维护：不清理，共享记忆就会腐化。

哪些编辑器，哪些功能

open-memex 通过两种方式与编辑器通信：原生 opencode 插件，以及任何兼容 MCP 的编辑器都能使用的标准 MCP 服务。（MCP — Model Context Protocol — 是编辑器用来为 Agent 提供额外工具的开放标准；open-memex 会以一组 memory_* 工具的形式出现在编辑器中。）具体功能取决于编辑器使用哪种方式：

编辑器	设置	工具	会话开始时回忆	关键词自动捕获
opencode（原生插件，推荐）	open-memex init --client opencode --global	5 个核心工具	内置 — 每个会话的第一轮	支持 — remember …、记住…
VS Code（Copilot）	open-memex init --client vscode	通过 MCP 提供全部 11 个工具	通过 MCP 指引*	不支持 — 由 Agent 在你提出要求时保存
Cursor	open-memex init --client cursor	通过 MCP 提供全部 11 个工具	通过 MCP 指引*	不支持 — 由 Agent 在你提出要求时保存
Claude Code	claude mcp add open-memex -- open-memex mcp	通过 MCP 提供全部 11 个工具	通过 MCP 指引*	不支持 — 由 Agent 在你提出要求时保存
Visual Studio 2022 17.14+ / 2026	open-memex init --client visualstudio	通过 MCP 提供全部 11 个工具	通过 MCP 指引*	不支持 — 由 Agent 在你提出要求时保存
Codex 和其他 MCP 客户端	open-memex mcp --print-config	通过 MCP 提供全部 11 个工具	通过 MCP 指引*	不支持 — 由 Agent 在你提出要求时保存

* MCP 没有严格意义上的会话开始钩子，因此 open-memex 会在 MCP 握手时向 Agent 发送指引（包括有多少条草稿在等待处理），而 init 会将更完整的版本写入编辑器的指令文件。实际使用中，Agent 通常会遵循这些指引；只有 opencode 插件能真正内置于首轮注入内容中。工具一节列出了 5 个核心工具和 6 个额外的工作流工具，明确说明了“5 个与 11 个”的区别。

同一台机器上的所有编辑器都会读取和写入同一份记忆 — 在 VS Code 中捕获的约束也会在 opencode 中得到遵循；在 Cursor 中学到的经验也会出现在 Claude Code 中。（不同机器之间不会自动同步；请参阅 常见问题。）

对于 VS Code 和 Cursor，以及使用项目级 MCP 模式的 opencode，init 还会安装一个 Agent Skill（用于教会具备技能感知能力的 Agent 使用 CLI 的简短指令文件）。若已接入 opencode 原生插件，则不会在此安装 Skill — 插件已经提供了记忆工具，再添加一套指令只会让 Agent 变得话多。

对比

	open-memex	指令文件（CLAUDE.md、AGENTS.md、…）	云端记忆服务	聊天记录
存储位置	你的机器 + 你的代码仓库	代码仓库中	服务提供商的服务器	聊天结束后即消失
维护者	工作时捕获；由你审核	由你手动编写和更新	服务	—
事实发生变化时	标记为已被取代，不会悄然过时 — 检索会提供当前版本，同时保留链路	由你手动编辑；过时副本会留存	因服务而异；通常会悄然过时	—
跨 AI 工具使用	支持 — 任何 MCP 客户端（同一台机器）	按工具惯例，每个工具各有一个文件	按集成而异	不支持
分享前审核	支持 — 发件箱 + 拉取请求	支持 — 就是普通文件	因服务而异	不支持
人类可读	纯 Markdown 文件	支持	控制面板 / API	不支持

指令文件很适合存放少量长期规则 — 请继续使用（open-memex 甚至可以根据你的记忆起草指令文件；见下文的 distill-agents）。open-memex 则用于收集日益增多的决策、经验和偏好，因为总会有人忘记把它们写下来。

安装

要求

• Node.js ≥ 22.14（open-memex doctor 会为你验证）。最低版本要求来自 SQLite 驱动：better-sqlite3 13 基于 Node-API 10 构建，而 Node 直到 22.14.0 才引入 Node-API 10 — 较旧版本的 Node 会在首次打开数据库时发生段错误。

安装 CLI

npm install -g open-memex

这是稳定版。安装软件包时可能会提示运行 open-memex init——编辑器配置是单独的步骤（请参阅 设置编辑器），所以如果没有看到提示，也不用担心；接下来直接运行 init 即可。

还有两种选择：

• 无需安装——通过 npx 运行： npx -y open-memex <command> 可以运行任意命令 而无需安装（例如，npx -y open-memex init --client vscode）。启动较慢， 但无需卸载。
• Alpha 版本（包含最新功能，但不够完善，适合测试人员）： npm install -g open-memex@alpha。运行 npm view open-memex version（稳定版）和 npm view open-memex@alpha version （Alpha 版）查看已发布的版本。

如果安装后找不到 open-memex，请检查 PATH — 参阅 故障排除。

从源代码安装（适合贡献者）

git clone -b main https://github.com/stoneskin/open-memex.git
cd open-memex
npm install
node --experimental-strip-types src/cli.ts <command>

设置编辑器

请在项目根目录（你正在使用的仓库的顶层文件夹）运行 init，这样项目范围才能解析为该仓库：

open-memex init --yes
# …or without installing the package first:
npx -y open-memex init --yes

--yes 会接受 init 中所有问题的推荐默认值 （要配置的编辑器、自动捕获、首轮上下文召回）。如果你想逐一回答问题，请不要使用此选项。不指定 --client 时，init 会检测已安装的编辑器并为它们全部配置——运行一次 init 即可覆盖所有项目。想只配置一个编辑器？ 请传入 --client：

VS Code（Copilot）：

open-memex init --client vscode

此操作会写入 MCP 服务条目；之后请重新加载窗口，并在 Copilot Chat 的 MCP 面板中确认 open-memex 服务已启动。默认情况下，此操作会写入项目级 .vscode/mcp.json（交互运行时会询问你想选择哪个级别）；添加 --global 则改为写入 VS Code 的用户级配置——设置一次即可用于每个项目。

Cursor：

open-memex init --client cursor

与 VS Code 配置方式相同：默认写入项目级 .cursor/mcp.json， 添加 --global 则写入用户级 MCP 配置，同时还会添加 Copilot 风格的指令。

opencode（原生插件——推荐）：

open-memex init --client opencode --global --yes

将原生插件合并到用户级 ~/.config/opencode/opencode.json （如果你已有 opencode.jsonc 文件，则写入该文件）——只需设置一次，每个项目都会自动加载，无需在每个项目中分别运行 init。你将获得 5 个核心工具、关键词自动捕获和首轮上下文注入。（如果配置文件包含注释，则会保持原样——init 会打印需要手动添加的行。）

同一安装支持 opencode 的两个代际：init 会分别写入 opencode 1 的写法（"plugin"）和 opencode 2 的写法（"plugins"）——每个宿主读取各自的键。opencode 1 需要 1.18.29 或更高版本。如果配置方式与已安装的宿主版本不匹配，open-memex doctor 会提示你。

opencode（作为普通 MCP 客户端）：

open-memex init --client opencode

此操作会写入包含 MCP 服务的项目级 opencode.jsonc。仅当你更偏好普通 MCP 而非原生插件时才需要这样做——但会失去关键词捕获和内置注入功能。

Claude Code（在项目根目录运行）：

claude mcp add open-memex -- open-memex mcp
# …or print the config snippet: open-memex mcp --print-config claude

Visual Studio（在解决方案目录运行）：

open-memex init --client visualstudio

此操作会写入解决方案级 .mcp.json。需要 Visual Studio 2022 17.14+ 或 Visual Studio 2026（仅限 Windows）。Visual Studio 也会自动发现 .vscode/mcp.json 和 .cursor/mcp.json，因此上述 VS Code 配置也适用。

**Codex：**目前尚无对应的 init 客户端——可以使用 open-memex mcp --print-config 作为起点，手动添加服务（在 config.toml 中添加 [mcp_servers]，或运行 codex mcp add）。

在所有项目中进行一次性设置（VS Code / Cursor）

open-memex init --client vscode --global --yes

两种不同的“全局”——不要混淆。

• npm install -g open-memex 会全局安装软件包：将 open-memex 命令添加到 PATH 中。
• init --global 会在用户级别而非项目中写入编辑器配置：只需初始化一次， 所有项目都能使用该配置。无论软件包是全局安装，还是通过 npx 运行，效果都相同。

--global 形式会将服务条目写入编辑器的用户级别 MCP 配置（Windows 上为 %APPDATA%\Code\User\mcp.json， macOS 上为 ~/Library/Application Support/Code/User/mcp.json， Linux 上为 ~/.config/Code/User/mcp.json；Cursor 上为 ~/.cursor/mcp.json）， 而不是写入项目中——只需初始化一次，所有项目都会启动该服务。 如果项目定义了自己的 .vscode/mcp.json，则以项目级配置为准。 如果用户级文件中包含注释（编辑器支持 JSONC），init 不会修改该文件， 而是打印出可手动粘贴的准确代码片段。

init 行为说明

• 现有配置文件会合并，绝不覆盖——重新运行 init 是安全的。--force 会重写我们添加的条目。
• 如果 PATH 中没有可持续使用的 open-memex（例如，通过一次性 npx 运行）， init 会将 npx -y open-memex mcp 服务命令写入配置，确保设置持续生效。 之后运行 npm i -g open-memex 和 open-memex init --force，即可切换为 更快的直接命令。
• 在交互式终端中，init 会显示检测到的编辑器并请你确认；脚本和 CI 不会提示， 而是为所有检测到的编辑器完成配置。
• 如果在从未完成初始化的机器上直接运行 open-memex，它会提供帮助你完成初始化 的选项（仅限交互式终端）。

移除配置

open-memex uninstall --yes

撤销 init 的操作——移除 MCP 服务条目、opencode 插件行、 Agent Skill，以及编辑器说明中的 open-memex 部分。不带 --client 时， 会清理所有检测到的编辑器；--global 则将清理范围限制为用户级配置。 你的记忆数据不会受到影响。

init 会在你的机器上修改哪些内容

init 写入的所有内容都列在这里：

• 记忆数据（首次使用时创建，init 本身不会创建）： Windows 上为 %APPDATA%\open-memex\，macOS/Linux 上为 ~/.local/share/open-memex/——其中包含你的记忆文件和搜索索引。 uninstall 永远不会修改这里的任何内容。
• 编辑器配置（由 open-memex uninstall 移除）：
  • opencode：合并到 ~/.config/opencode/opencode.json（或 .jsonc）中的 "plugin" 条目（opencode 1）和 "plugins" 条目（opencode 2）。 重命名之前遗留的 my-o-memory 条目也会同时移除。
  • VS Code / Cursor：在用户级或项目级 MCP 配置中添加 open-memex 服务条目，并在 Copilot 说明中添加 open-memex 部分（默认写入用户级 ~/.copilot/copilot-instructions.md；对于所有人都使用 open-memex 的团队， --instructions project 会改为在仓库中写入 .github/copilot-instructions.md）。
  • Visual Studio：在解决方案旁添加 .mcp.json。
  • Agent Skill：为 VS Code（~/.copilot/skills/）、Cursor（~/.cursor/skills/） 或处于项目级 MCP 模式的 opencode（~/.config/opencode/skills/）创建 skills/open-memex/ 文件夹。
• 你的仓库：不会有任何改动。只有在你明确运行 submit 时（参见“团队工作流”）， 文件才会出现在仓库中——这会创建本地提交，不会自动推送。

含注释的文件（JSONC）绝不会被重写：init 会打印出可粘贴的准确代码片段。

记录：记忆如何保存

记忆有三种保存方式：

• 关键词触发（仅适用于 opencode 原生插件）：说 remember …、 note that …、don't forget: …、TIL …、save this …，或用中文说 记住… / 记一下… / 记录一下… / 别忘了：…，句子就会被记录下来， 无需调用任何工具。默认情况下，记录会保存到当前项目；表示「这是关于我自己的」 短语——remember for me …、help me remember: …、记住我…、替我记…、 帮我记…、我觉得…、我喜欢…——会保存到个人记忆中；团队语境短语 （我们决定…、帮我们记住…）则仍保存到项目中。两条规则可减少误触发（D67）：触发语必须是 向记忆库发出的指令，因此叙述性表达 记得… / remind me to… / 别忘了带伞 / don't forget the wifi password 永远不会触发（加上分隔符——别忘了：…、 don't forget: …——或加上 that，就能将其变成指令）；而不足 3 个字符的记录内容 会被判定为片段并拒绝保存——capture --dry-run 会说明原因，而不是悄悄丢弃。 触发语也会独立记录自己的句子：插件会告知 Agent 刚刚保存的内容；如果接下来的几分钟内 memory_add 再次保存相同文字，则会被拒绝，并返回已保存的 ID（D73）——你说的一件事 就是一条记忆，而不是三份副本。
• 由 Agent 保存：在任何编辑器中，请 Agent 记住某件事（或者当你陈述值得保留的事实时， Agent 会自行保存）——它会调用 memory_add。上述路由规则只是启发式判断；你可以直接说 “将这条内容保存到我的个人记忆中”，也可以使用带 --scope 的 CLI 明确指定。
• 检查点建议：任务结束时，Agent 会根据本次会话提炼出 1–3 条简短的候选记忆——决策及其原因、 约定、注意事项、尝试过并放弃的方法——并且只保存你批准的内容。任何内容都不会悄悄写入： 不会擅自创建草稿。
• CLI：open-memex add "…"，可选参数为 --scope / --tag / --type / --aliases。

别名。 每条已保存的记忆最多可附带 4 个其他表达方式 （同义词、另一种语言中的对应表达），并会与记忆一同建立索引，这样即使问题的措辞不同，也能找到对应记忆——搜索 “vacation days”也能找到假期政策。别名始终启用——Agent 每条记忆最多可附加 4 个别名；你也可以通过 open-memex add --aliases 传入自己的别名。

添加别名有三种方式：open-memex add "text" --aliases "phrase one; phrase two"（用分号分隔，最多 4 个）；请 Agent 添加（“记住：Fluffy 是我的 AI agent，将它的别名设为 Momo”）；或者直接编辑记忆的 aliases: frontmatter—— Markdown 是事实来源，同步会读取其中的更改。

此外，经过整理的同义词／翻译映射会在写入时自动扩展到索引中（D80）——即使记忆没有别名， 搜索 ship 也能找到 deploy。个人昵称应放在别名中；通用的开发领域词汇应放在整理后的映射中。 参见检索：记忆如何被找回。

脱敏。 将敏感内容用 <private>…</private> 包起来，保存前就会将其剥除。识别出的机密信息 （API 密钥、令牌、高熵凭据）会在原位置打码——保留前 4 个字符，替换其余部分——记忆仍会保存。 随时安全预览消息中哪些内容会被记录：

open-memex capture --dry-run "…"

如果还是有机密信息漏网，open-memex forget <id> 可以删除该记忆。

Agent 可用的工具

MCP 服务提供 11 个工具；opencode 原生插件提供 5 个核心工具（标有 ●）。其余 6 个是团队审查工作流工具——只有通过 Git 分享记忆时才会用到。

工具	功能
● memory_add	保存事实、偏好、决定、笔记
● memory_search	在项目和个人记忆中进行关键词搜索（BM25）
● memory_list	按编号清单列出指定范围（project、personal 或 both）内的记忆；include=all 是审计视图
● memory_supersede	用更新的版本替换一条记忆（保留替代链）
● memory_forget	按 ID 删除一条记忆（soft=true 则改为隐藏——撤回后不可恢复）
memory_status	显示同步队列：发件箱草稿、仓库审查状态、未提交文件
memory_submit	将指定草稿移入仓库记忆目录（本地分支 + 提交）
memory_propose	将个人记忆复制到项目范围，作为待审候选内容
memory_promote	将状态推进为 proposed → approved → published（或拒绝 / 重新提交）
memory_resolve	列出冲突的记忆文件 / 对其中一个进行三方合并
memory_pr_status	将分支 PR 的 GitHub 状态映射到每条记忆的审查状态

因此，连接 MCP 的编辑器始终可以使用全部工具；opencode 插件负责记录和回忆，而工作流相关操作则通过命令行或连接 MCP 的编辑器完成。

记忆类型

每条记忆都有一个 type（记忆内容的类型）和 tags（记忆主题）。内置 11 种类型：

类型	记录内容
fact	关于项目或现实世界的稳定真实陈述
preference	某人喜欢的做事方式
decision	已做出的选择——原因和权衡
constraint	不得违反的规则
todo	之后要完成的事项
knowledge	持久的领域或架构知识
howto	已验证有效的操作流程
gotcha	应当避免的陷阱
lesson	从事件或错误中得到的经验
observation	注意到的现象，尚未得出结论
reference	指向权威文档的链接（不复制内容）

--type 接受任意字符串，但使用内置类型可以让会话开始时的标签、搜索和 distill-agents 输出保持可预测。

团队工作流：通过 Git 分享记忆

独自工作？可以跳过本节——对一个人来说，上面的内容就是完整产品。下面的流程不会自动发生。

个人笔记会保持私密。选择分享的项目知识则遵循明确、可审查的流程，其形式类似代码审查：

capture → outbox (draft, local) → submit → repo (.ai/open-memex/) → PR review → published → recall

1. 记录 — 在日常工作中将决定、易踩的坑和经验保存为草稿。
2. 审查 — 草稿会留在本地发件箱中（位于你的机器上，不会显示在 git 中）；open-memex sync-status——或者在聊天中直接说“同步记忆”——会显示待处理内容。
3. 提交 — 由你指定记忆；它们会移入 <repo>/.ai/open-memex/，并在当前分支上创建本地提交。open-memex 不会自行推送；它会打印推送和 PR 命令，并且只有在获得你明确同意后，Agent 才能执行这些操作。
4. PR 审查 — 记忆采用普通 Markdown 格式；审查者通过常规分支 / PR 流程批准、要求修改或拒绝。
5. 回忆 — 已发布的记忆会在会话开始时注入，也可按需搜索，供人和 Agent 使用。

负责维护共享记忆的人应遵循维护者约定：哪些内容应批准、哪些内容应退回，以及如何通过卫生规则避免共享记忆逐渐失效。

检索：记忆如何被找回

每次会话的第一轮中，open-memex 都会向 Agent 的上下文注入一个 [OPEN-MEMEX] 区块，其中包含最近的项目记忆（默认：前 8 条）和你的个人偏好（默认：前 5 条）。内容如下：

[OPEN-MEMEX]

User profile / preferences:
- I prefer concise diffs

Project knowledge (my-repo):
- [decision] We deploy on Fridays; the release train leaves at 10:00

Use the `memory_search` tool to look up more. Use `memory_add` to save new facts.
Do not mention this block to the user unless asked.

这只是一个快照，并非全部记忆——Agent 可以随时调用 memory_search 获取其余内容。两个前 N 条数量均可配置（参见 配置）。对于 MCP 客户端，此区块会作为握手指引发送，由 Agent 遵循；opencode 插件则会在第一轮直接注入。

检索评估

我们在已纳入版本控制的合成测试数据上测量召回率，而非将其作为断言：54 条记忆 + 44 个查询（精确词语、改写、同义词、中文、跨语言难例、仅含同义词的查询，以及用户自定义别名查询 D81）——可通过 node --experimental-strip-types scripts/retrieval-eval.ts 重现。 当前基线采用索引时同义词／翻译扩展（D80）和查询时用户别名扩展（D81）： recall@1 0.75、recall@5 0.98、MRR 0.86。 合成语料规模较小，因此应将其视为回归检查和起点，而非真实场景下的结论。

三层机制各有侧重，弥补其他机制的不足：BM25 关键词搜索 （SQLite FTS5——匹配精确词语、速度快，可通过 search --explain 解释）； 分为两部分的同义词扩展——(a) 索引时扩展（D80：精选并纳入版本控制的开发领域等价词和 EN↔ZH 翻译对，在写入时扩展到索引中，因此普通的单轮查询中，搜索 ship 可找到 deploy，搜索 bug 可找到 defect；结果确定性高，无需下载模型）；(b) 查询时用户别名（D81：包含 alias:／target: frontmatter 的别名记忆，可在每个作用域定义一次你的词汇——例如 Banana Plan → 支付系统重构项目——查询提及任一侧时，都会触发针对另一侧的第二轮查询，双向生效，并与第一轮结果均匀合并，因此别名命中不会被降低权重；别名更改后无需重新索引）；以及语义向量，作为可选实验（在跨语言测试数据切片上测得本地多语言嵌入的 R@5 为 92.7%——参见 docs/retrieval-ablation-study.md §4.7；未经你的明确选择，绝不会下载嵌入模型）。

使用公开数据进行外部验证：同一流程在 LongMemEval-S 上的得分为 recall@5 97.0%／ MRR 0.909（470 个问题，仅检索阶段——不生成答案，也不使用评判模型；这不是 LongMemEval 官方得分）。作为参考，agentmemory 在相同协议下公布的数字为 86.2%／ 0.715（仅 BM25）和 95.2%／0.882（BM25+向量）。在包含 22k 条记忆的混合压力测试中，recall@5 降至 40.6%——这是通过测量得出的词法检索上限，而非断言。可通过 node --experimental-strip-types scripts/bench-longmemeval.ts --data <path> 重现 （数据集：xiaowu0162/longmemeval-cleaned，MIT）。

安全与数据

• **本地优先：**所有内容都存储在你的设备上（Windows 上为 %APPDATA%\open-memex，macOS/Linux 上为 ~/.local/share/open-memex），以及你选择的仓库中。零云端调用、零账户、零第三方 API、零遥测。
• 保密信息不会外泄：<private>…</private> 范围会被剥离；检测到的 API 密钥／令牌会在保存前就地遮蔽。可通过 open-memex capture --dry-run "…" 预览。
• 个人内容永不同步：personal 作用域仅限此设备——默认不纳入导出，且绝不会进入仓库。
• **共享过程可审计：**团队记忆仅通过显式的 submit 流转，并经过分支／PR 审查；每次 promote 状态转换都会追加到记忆的 review_history 中（操作者／时间／原因）。
• **文件由你掌控：**Markdown 是事实来源——可手动检查、编辑或删除任何内容；SQLite 索引会根据文件重建。

局限

坦诚说明限制，避免意外：

• 关键词搜索，不是语义搜索。 检索采用 BM25 关键词匹配，并在写入时将精选的同义词映射扩展到索引中（ship 可找到 deploy，bug 可找到 defect）。精选映射之外的改述无法匹配——这正是可选语义层的用途。（普通提问没有问题——“how do we…” / “请问…”这类措辞会在匹配前过滤掉，因此自然提问不会稀释结果。）未经你明确选择加入，绝不会下载嵌入模型。（同义词扩展存放在独立的索引列中，与您自己的别名分开——但仅通过扩展匹配的查询，排名仍可能低于直接匹配；这是 BM25 长度归一化行为固有的结果，并非错误。）
• 仅限一台机器。 同一台机器上的编辑器共享记忆；机器之间不会同步。export / import 打包文件（见下文）可用于手动在机器之间迁移记忆。
• 快照，并非全部内容。 会话开始时的召回是一个 Top-N 快照（默认 8 条项目记忆 + 5 条个人记忆）；较早的记忆可通过 memory_search 查找，但不会一次性全部放入上下文。
• MCP 指引仅供参考。 在 opencode 之外，主动捕获和召回取决于 Agent 是否遵循握手说明——MCP 没有强制的会话开始钩子。直接调用工具时，工具始终可用。
• 捕获路由采用启发式规则。 个人信号短语（remember for me …、我喜欢…）会归入个人记忆；其他内容默认归入当前项目。如果判断有误，请明确说出范围，或在命令行中使用 --scope。

升级

npm install -g open-memex@latest   # or @alpha

你的编辑器配置指向已安装的 open-memex 命令，因此升级无需重新配置。重大升级后，运行一次 open-memex init --force，即可使用最新措辞刷新已安装的 Agent Skill 和指令文件。如果你从源码安装或移动了软件包，--force 也会重新指向 opencode 插件路径。

各版本的变更内容：请参阅 CHANGELOG。

存储布局

%APPDATA%\open-memex\               (Windows)
~/.local/share/open-memex/          (macOS/Linux; $XDG_DATA_HOME if set)
├── index.db                         # SQLite FTS5 index (rebuildable)
└── memories/
    ├── personal/
    │   └── <id>.md
    └── project__<name>__<hash12>/
        └── <id>.md

每个 .md 文件代表一条记忆：包含 YAML frontmatter（id, scope, type, tags, created_at, schema_version，……），后接正文。你可以手动编辑这些文件——索引会从文件重新同步，而 Markdown 始终是事实来源（open-memex reindex 会从头重建索引）。

执行 submit 后，项目记忆也会以 Markdown 文件的形式存放在 <repo>/.ai/open-memex/ 下（可通过 memoryDir 配置），并像其他文件一样随分支和 PR 一起流转。

配置

设置存放在 ~/.config/opencode/open-memex.jsonc 中——路径中的 opencode 是历史遗留名称；所有客户端共用这一个文件。使用 OPEN_MEMEX_CONFIG 覆盖配置路径，使用 OPEN_MEMEX_HOME 覆盖存储根目录（重命名前的 MY_O_MEMORY_CONFIG / MY_O_MEMORY_HOME 名称仍会作为回退选项生效）。

默认值：

{
  "maxProjectMemories": 8,    // top-N project memories injected on first turn
  "maxProfileItems": 5,       // top-N personal items injected on first turn
  "injectOnFirstTurn": true,  // [OPEN-MEMEX] system-prompt block
  "keywordCaptureEnabled": true,
  "logLevel": "info",          // info | debug
  "memoryDir": ".ai/open-memex" // in-repo project-memory dir, relative to repo root
}

open-memex config 会打印生效的配置（默认值 + 文件配置）。安装后更改设置：

open-memex config set keywordCaptureEnabled false
open-memex config set maxProjectMemories 12
open-memex config set sync.autoPull true   # best-effort pull at MCP session start

可设置的键：maxProjectMemories、maxProfileItems、injectOnFirstTurn、keywordCaptureEnabled、captureAliases、logLevel、memoryDir 和 sync.autoPull（这个带点号的键会写入嵌套的 sync 对象）。完整设计说明： docs/V2-DESIGN.md。

CLI 参考

设置与健康检查：

open-memex init [--client vscode|cursor|opencode|visualstudio]
              [--instructions personal|project] [--global] [--force] [--yes]
open-memex uninstall [--client vscode|cursor|opencode|visualstudio] [--global] [--yes]
open-memex config                                  # print effective config
open-memex config set <key> <value>                # change a setting
open-memex doctor                                  # environment health check (incl. plugin entry)
open-memex audit                                   # memory health check (duplicates, stale, broken chains)
open-memex capture --dry-run "remember that I like concise answers"  # preview keyword capture
open-memex mcp --print-config vscode|cursor|claude|opencode|visualstudio
open-memex --help      # this reference
open-memex <command> --help  # help for one command
open-memex --version   # installed version

记忆操作：

open-memex add "This repo uses better-sqlite3" --type fact
open-memex search "auth flow"
open-memex search "auth flow" --explain   # show FTS expression, scores, lifecycle-hidden counts
open-memex list --scope project
open-memex list --scope both       # each scope's newest under its own header
open-memex list --include all      # audit view: superseded versions, retracted, archived
open-memex supersede <id> "Updated content"
open-memex status <id> deprecated
open-memex forget <id>
open-memex forget <id> --soft      # hide instead of delete (retracted; one-way)

open-memex inventory                        # everything remembered, as readable text
open-memex inventory --format json          # the same data, for agents
open-memex inventory --format html          # the same data as a local page (writes <data dir>/inventory.html)
# Personal + current project, outbox drafts in their own section, hidden
# history counted. Refuses to write a personal-bearing report inside a
# git working tree unless you pass --allow-personal.
# `list` numbers every entry in one listing and says how many it left out.

团队审核工作流（两个存储位置，每个阶段一个）：

项目草稿存放在 appdata outbox 中（Git 不可见，不受分支影响）； 只有你批准的草稿才会移入 <repo>/.ai/open-memex/，在那里随分支和 PR 流转。未经你明确指定，不会移动任何内容。在连接了 MCP 服务的 AI 聊天中，只需说 “同步记忆”（或 "同步记忆"）——Agent 会运行状态检查、汇总 outbox 草稿，并询问要同步哪些草稿。服务也会主动告知 Agent：会话开始时，握手会报告正在等待的草稿数量；每个更改记忆的工具结果也会在数量非零时附带当前数量。

open-memex sync-status
# show when the index was last synced (and what triggered it), the outbox
# (pending sync), the repo review states
# (draft / proposed / approved / published / rejected),
# and any uncommitted repo memory files.

open-memex submit <id...> [--branch <name>] [--base <branch>]
# move your named drafts into .ai/open-memex/ as "proposed":
# copies, flips review_state, local git commit ON THE CURRENT BRANCH.
# Never creates a branch on its own — branch creation is your call
# (or the agent's, only with your explicit approval for the full chain).
# All-or-nothing; conflicts (same id, different content) abort cleanly.
# Prints the push + gh pr commands; an agent holding your Yes carries
# through push/PR itself. --branch <name> creates the branch first
# (agent full-chain path). Default PR base is the current branch (memory
# PRs stack onto your working branch); --base redirects it to main or
# wherever you review.

open-memex pr-status [--apply]
# read the branch's GitHub PR and map its state onto each in-repo memory:
# merged PR → published, PR approval → approved (approved_by = reviewer),
# changes-requested → suggestion only. Report by default; --apply performs
# the mapped transitions locally (no push).

open-memex pull
# pull shared memories from the git remote: fetch + fast-forward ONLY.
# A diverged branch fails with a clear message — open-memex never
# force-merges; resolve it by hand, then pull again. On success the
# local index re-syncs. Pulls are explicit by default; set
# `open-memex config set sync.autoPull true` for a best-effort pull
# at MCP session start (a failed pull never blocks the session).

open-memex push
# push the current branch (with its submitted memories) to the git remote.
# Explicit only — open-memex never pushes on its own.

open-memex export [--scope project|personal|both] [--type T] [--tag t] [--all] [-o <file>]
# bundle memories into a portable .tar.gz (markdown + manifest.json) for
# moving to another machine or another app. Excludes visibility:private
# memories by default; --all / -a includes everything (full migration).

open-memex import <bundle.tar.gz> [--dry-run]
# restore a bundle: personal memories go to the personal dir; project
# memories are re-keyed to the current project and land in the outbox as
# drafts. Identical ids are skipped; conflicting ids are reported,
# never overwritten.

open-memex distill-agents [--scope project|personal] [--type t1,t2] [--limit N] [-o <file>]
# propose an AGENTS.md snippet distilled from project memories
# (decisions, constraints, lessons, gotchas, howtos). Prints markdown;
# -o writes it to a file. You review and merge by hand — open-memex
# never rewrites your AGENTS.md on its own. The snippet ends with a
# "memory hygiene" section so agents reading AGENTS.md learn to propose
# distilled captures when a task ends.

open-memex propose <id...> --to project [--local-approve]
# propose one or several personal memories at once (one branch, one PR);
# each is copied with its own new id. All-or-nothing: a bad id aborts the
# whole batch, never a half-proposed one.
# copy a personal memory into the project scope as a review candidate
# (never moves — the personal original stays). Result lands in the outbox;
# run sync-status / submit when you're ready to put it in the repo.
open-memex promote <id> [--reject] [--resubmit] [--note "..."] [--by NAME]
# advance one step: proposed → approved → published (or reject with a note).
# Every transition is appended to the memory's review_history (who/when/why).
# A rejection never deletes the file — your call: accept it (close the PR,
# delete the branch), revise + --resubmit for another round, or keep it as
# a [rejected] record.
open-memex resolve [id-or-path]
# list conflicted memory files, or field-level 3-way merge one of them.
# Semantic conflicts are reported, never auto-resolved.

负责维护共享记忆的人应遵循策展人规范—— docs/CURATOR.md：说明要批准什么、要退回什么，以及防止共享记忆逐渐失效的卫生规则。

维护：

open-memex where        # show storage + config paths
open-memex scopes       # list project scopes with memory counts
open-memex reindex      # rebuild the SQLite index from markdown
open-memex audit        # memory health: duplicate pairs, stale memories, broken chains
open-memex migrate --to-v2 [--dry-run]   # v1 data → v2 (renames user scope to personal)

CLI 在 Node 22 下运行。从源代码检出目录运行时，它使用内置的实验性 TypeScript 加载器（无需构建步骤）；发布的 npm 包会附带预编译的 JS（发布时运行 npm run build）。从源代码检出目录运行时，每条命令前都要加上 node --experimental-strip-types src/cli.ts（简单情况下也可使用 npm run cli -- <command>——npm 会吞掉未知的 --flag 参数，因此建议直接使用 node）。

MCP 服务

通过 stdio 服务，使用 Model Context Protocol 提供相同的记忆工具——无需特定宿主的插件。任何 MCP 客户端都可以使用 open-memex。

open-memex mcp               # after a global install
npx -y open-memex mcp        # no install needed

项目范围根据进程的工作目录确定，因此请将服务配置为以项目根目录为 cwd（init 会为你处理此事）。

注意： MCP 采用请求/响应模式——它为 Agent 提供工具，而不是 opencode 插件的自动关键词捕获或首轮注入。 主动使用记忆取决于 Agent 的指令：服务会在 MCP 握手的 instructions 中发送会话开始指引（包括会话开始时实时的 outbox 草稿数量，以及在数量非零时附加到更改记忆的工具结果中的待处理数量）；init 则会将更完整的版本写入编辑器的指令文件。这两者都只是建议——没有 MCP 消费端提供硬性的会话开始钩子。

详细了解作用域

• project — 作用域限定为当前仓库，以 Git origin URL 哈希为键（因此同一仓库的克隆共享一个作用域）；如果没有远程仓库，则以 cwd 路径为键。新记忆的默认作用域。
• personal — 在你所有项目间全局共享，仅限本机，永不同步。用于个人偏好。（v1 中称为 user； migrate --to-v2 会将其重命名。）

完整的作用域模型请参阅 docs/SCOPES.md：包括键派生、迁移、可见性和保留名称。概念指南 将带你从头到尾了解整体思维模型。

故障排查

每条命令都会无输出地退出，或进程崩溃（exit 139、0xC0000005、“Segmentation fault”）。 你的 Node 版本低于 22.14，无法加载捆绑的 SQLite 驱动。better-sqlite3 13 是针对 Node-API 10 编译的，而 Node 到 22.14.0 才支持 Node-API 10；在任何更早的版本上，require() 都会成功，但首次打开数据库时进程就会因段错误而崩溃，且没有诊断信息。open-memex 现在会拒绝加载该驱动并说明原因，但如果你遇到的是此前的崩溃，几乎可以肯定就是这个问题。运行 node -v 检查，然后升级 Node（nvm install 22.14 && nvm use 22.14，或使用任何当前的 22.x/24.x 版本），或者将驱动固定为较低版本：npm install better-sqlite3@^12.11.1。open-memex doctor 会报告所需的最低 Node 版本，并实时探测驱动。已知的上游问题：WiseLibs/better-sqlite3#1514。

open-memex 无法识别／找不到命令。 通过 npm install -g 全局安装后，open-memex 启动器会放在 npm 的全局 bin 文件夹中。如果终端找不到它，说明该文件夹不在你的 PATH 中：

1. 查找该文件夹：npm config get prefix
   • **Windows：**启动器（open-memex.cmd）就在该文件夹中，例如 C:\Users\<you>\AppData\Roaming\npm
   • **macOS / Linux：**启动器位于 <prefix>/bin，例如 /usr/local/bin 或 ~/.nvm/versions/node/v22.x.x/bin
2. 将它添加到 PATH：
   • **Windows：**设置 → 系统 → 关于 → 高级系统设置 → 环境变量 → 将该文件夹添加到用户 Path → 重启终端。使用 where open-memex 验证。
   • **macOS / Linux：**将 export PATH="$(npm prefix -g)/bin:$PATH" 添加到 ~/.zshrc（或 ~/.bashrc），重启 shell，然后使用 command -v open-memex 验证。
3. 没有管理员权限／不想修改 PATH？使用 npx 形式——npx -y open-memex <command> 会自行解析软件包，无需修改 PATH。

Windows 上 better_sqlite3.node 出现 EBUSY / EPERM。 在 Windows 上，已加载的 DLL 会被锁定：如果 open-memex MCP 服务正在运行（VS Code MCP 面板、Cursor 等），npm install -g open-memex 就无法替换 better_sqlite3.node，并会报错 EBUSY / EPERM。请先停止 MCP 服务（或退出编辑器），然后重新运行安装。如果仍然失败，请删除全局 npm 根目录下的 node_modules/open-memex 和任何 node_modules/.open-memex-* 临时文件夹，然后再次安装。

init 提示配置文件未作更改。 你的编辑器配置含有注释（JSONC）或无效 JSON，open-memex 不会重写无法安全解析的文件。init 已输出需要手动添加的确切代码片段——将其粘贴进去即可。opencode 配置也适用相同规则：如果其中有注释，请手动添加 "plugin" 行。

遇到问题时——运行 open-memex doctor。 它会检查 Node 版本、配置来源、当前目录的范围解析情况以及存储是否可写；验证 VS Code 是否禁用了 MCP；随后启动一个真实的 MCP 服务，并对其运行 initialize + tools/list——全部十一个工具都必须显示出来。如果任何编辑器配置仍引用旧软件包名称，它也会报告重命名前遗留的 my-o-memory 配置。

常见问题

我需要 git 吗？ 不需要。在任何文件夹中都可以捕获和回忆内容——如果项目没有 git 仓库，项目范围就仅根据文件夹路径确定。团队工作流（submit / PR 审查）才需要 Git，但这是可选的。

我使用多个编辑器。它们真的会共享同一份记忆吗？ 会——前提是在同一台机器上。每个已接入的编辑器都会读取和写入同一份本地记忆；各编辑器支持的功能请参阅功能矩阵。在 VS Code 中记录的决策，在 opencode 中也会得到遵循。 我会在两台电脑（办公室 + 家里）上工作。记忆会同步吗？ 不会自动同步——记忆按设计存储在各台机器上，个人范围的记忆永远不会离开创建它的机器。要手动迁移记忆，请在一台机器上使用 open-memex export，再在另一台机器上使用 open-memex import。通过 Git 共享的项目记忆（团队工作流）会随仓库一起迁移，因此在第二台机器上克隆仓库也会带上已发布的项目记忆——而你的个人记忆会有意保留在原机器上。

它真的免费吗？我需要账户吗？ 免费且开源（Apache-2.0）。无需账户、无需注册、没有遥测，也不会调用云服务。如果它无法连接外部，就没有任何外部服务可连接：open-memex 唯一会访问的网络目标是你自己的 git 远程仓库，而且仅在你明确推送时访问。

我不小心把机密粘贴到记忆里了。现在怎么办？ 使用 open-memex search "<part of it>" 查找这条记忆，然后使用 open-memex forget <id> 将其删除。要防止下次发生，请将敏感文本包在 <private>…</private> 中（保存前会剥除）——识别到的 API 密钥和令牌也会自动屏蔽。使用 open-memex capture --dry-run "…" 安全预览任何消息。

每个项目都需要运行 init 吗？ 不需要。数据层无需任何设置——项目范围会根据当前工作目录的 git 远程仓库或路径自动确定，因此记忆会按项目分区，无需任何配置。编辑器集成只需每台机器运行一次 open-memex init（编辑器支持的情况下为用户级配置）。只有在升级后（使用 --force）或切换编辑器时才需要再次运行。

opencode 需要运行 init 吗？ 有两种方式。推荐方式：运行 open-memex init --client opencode --global——它会自动将原生 open-memex 插件合并到 ~/.config/opencode/opencode.json。只需设置一次，即可应用于所有项目，并额外启用关键词自动捕获和首轮记忆注入。想手动配置？将 "plugin": ["file:///absolute/path/to/open-memex/src/index.ts"]（已安装软件包的路径）添加到该文件即可。作为普通 MCP 客户端：open-memex init --client opencode 会写入项目级 opencode.jsonc（不含钩子）。如果用户级配置包含注释，init 会保持不变，并打印手动操作步骤。

VS Code——init 只需运行一次，还是每个项目都要运行？ 只需一次。直接运行 open-memex init 会自动检测 VS Code，并将 MCP 服务条目写入 VS Code 的用户级 mcp.json（Windows 上为 %APPDATA%/Code/User/mcp.json，macOS 上为 ~/Library/Application Support/Code/User/mcp.json，Linux 上为 ~/.config/Code/User/mcp.json），因此该服务会在每个项目中启动。如果存在项目级 .vscode/mcp.json，则优先使用它；该条目会保留 cwd=${workspaceFolder}，以便在每个窗口中继续正常解析项目范围。如果用户级 mcp.json 包含注释（VS Code 接受 JSONC），init 会保持不变，并打印需要手动添加的准确代码片段。空文件会被视为无内容，并直接写入。

如何移除编辑器集成？ open-memex uninstall 会撤销 init 的操作：移除 MCP 服务条目、opencode 插件行、Agent Skill 目录，以及 Copilot 指令中的 open-memex 部分。如果不指定 --client，则会清理所有检测到的编辑器；--global 则将清理范围限制在用户级集成。你的记忆不会受到影响。

我升级了 Node，或用 nvm 切换了版本。需要重新安装吗？ 软件包本身不受影响：它的 SQLite 驱动是 Node-API 预编译版本，因此无需重新编译，就能在任何受支持的 Node 版本（≥ 22.14）上加载，而且你的记忆存储在安装目录之外。但版本管理器（nvm 等）会为每个 Node 版本保留单独的全局软件包目录，因此切换版本后，open-memex 可能会显示“找不到”。在新 Node 版本下运行一次 npm install -g open-memex，然后运行 open-memex doctor 确认驱动已加载。

项目状态

open-memex 已稳定运行并在日常使用；当前稳定版本线已在 npm 上以 latest 发布，并提供供测试者使用的 alpha 版本。发布历史见 GitHub Releases；设计决策记录在只追加、不修改的日志 docs/V2-DESIGN.md 中。

未来计划（不承诺版本）：为更多编辑器提供原生 Agent 插件，作为同一组 MCP 工具的增强功能；将本地嵌入作为可选实验（未经询问绝不会下载任何模型）；只有在确有跨仓库共享、ACL 或合规需求时，才会添加组织层。

许可证

Apache-2.0