OwnMem 是什么
OwnMem 是 Git 原生的 AI 编码代理项目记忆系统:项目经验写成仓库 .ownmem/ 目录下的 Markdown,随代码 clone、review、回滚,由本地确定性召回按需投递给编码代理。Apache-2.0 协议,2026 年 8 月创建,2026-09 查询 GitHub 约 400 star,支持 Claude Code、Codex、Cursor、Gemini CLI、Grok CLI 五类 host。这篇覆盖安装、五个 host 的接入差异、0.6.0 升级的坑和日常使用;机制解析见《OwnMem 是什么》,与 CLAUDE.md 的分工见选型专文。
前置要求:Node.js 20.6+
唯一硬性前置是 Node.js 20.6+(官方 README 要求)。没有 Python、没有 Docker、没有要注册的云端服务——排序只读仓库文件与本地快照,装完也没有常驻进程。以 devDependency 安装还有一层含义:ownmem 跟着 package.json 走,团队成员 npm install 时一并装上,版本由 lockfile 钉住。
node -v
# 需要 v20.6.0 及以上
两步安装:install 装包,init 挂 host
整个接入就两条命令:
npm install --save-dev ownmem
npx ownmem init --hook --hosts claude,codex
第一条把 ownmem 装成 devDependency。第二条做三件事:创建 .ownmem/ 记忆目录、生成所选 host 的适配器、在指令文件里挂上接入点。
--hosts 的语义单独说:可选值 claude、codex、cursor、gemini、grok,逗号分隔;这份列表会被记录,重复执行 init 时按新传入的列表增删 host。第一次接了 claude,codex,后来团队上了 Cursor,再跑一次 --hosts claude,codex,cursor 就行。
init 有两个保护性设计:编辑 CLAUDE.md 等指令文件时,只在与令块内改动,文件其余部分不动(CLAUDE.md 结构见本站专文);拿不准就先跑 --check 预览全部改动。--locale auto 按系统语言生成指令。常用参数速查:
| 参数 | 作用 |
|---|---|
--hook | 安装 host 侧 hook 接入点(如 Claude Code 的 Edit/Write 前钩子) |
--hosts claude,codex | 指定 host 列表,传入即增删 |
--check | 预览将要做的改动 |
--locale auto | 按系统语言生成指令 |
--update | 升级后更新 hook 配置(0.6.0 起必需) |
五个 host 的接入方式
接入路径和一次性步骤各不相同,整理成表(出自官方 README):
| Host | 接入方式 | 一次性步骤 |
|---|---|---|
| Claude Code | 每次 Edit/Write 前的 hook + 按需召回 | init 自动完成 |
| Codex | 每次应用 patch 前的 hook | 三个一次性信任步骤,init 会打印 |
| Grok CLI | 兼容层读 Claude Code 的 hook 配置 | /hooks-trust 信任目录一次 |
| Cursor | 常驻 rule 或 MCP 服务器 | MCP 需一步手动配置 |
| Gemini CLI | 指令或 MCP 服务器 | 按所选方式配置一次 |
Claude Code 这行多说一句:接入点就是 hook 机制,每次 Edit/Write 前触发,把相关记忆投进上下文;hook 的生命周期与退出码语义见本站 Hooks 实战。注意表中 Claude Code 一栏是两部分:hook 保证记忆在代理动手前进上下文,按需召回由你在会话里主动触发。Codex 的三个一次性信任步骤,init 会把要执行的命令打印出来,照做即可——这是”每次应用 patch 前触发召回”的一次性代价。Grok CLI 通过兼容层读 Claude Code 的 hook 配置,等于复用同一份钩子文件,再用 /hooks-trust 把目录信任一次。Cursor 和 Gemini CLI 的 MCP 选项,适合想把记忆能力当工具暴露给代理的团队;选 rule 或指令则随指令文件在场。
表格的差异本质是各 host 的扩展点不同:Claude Code、Codex 有生命周期事件可挂,Grok CLI 复用 Claude Code 的配置,Cursor 和 Gemini CLI 走常驻 rule/指令或 MCP 服务器,不依赖 hook 事件。host 列表以后有增减,重跑 init 即可,不用手动清理旧接入。
0.6.0 升级警告:不跑 init —update,hook 会天天报错
升级到 0.6.0 后必须立刻执行 npx ownmem init --update。官方说明很直接:0.6.0 安装的 hook 子命令已不存在,不更新的话,每次 Bash 调用都会执行一个失败命令。
npm install --save-dev ownmem@latest
npx ownmem init --update
这次升级还涉及 git 的 core.hooksPath 清理,细节在官方 UPDATING.md。什么人会中招:从 0.6.0 之前的版本直接装 ownmem@latest、没跑 init —update 的仓库。升级后如果看到代理反复执行失败命令、输出里出现不存在的 ownmem 子命令,先跑 —update 再排查别的。批量升级多个仓库的话,把 init —update 排在 install 之后同一批执行,别让中间态进主干。
日常使用:起草、召回、daily
写入口是自然语言,README 原例:
记住这个:staging 部署超时源于连接池上限,不是 worker 太少,下次两个一起查
代理把它起草成 .ownmem/ 里的条目,变更以 commit 落库。记忆的合并流程和审代码完全一样:谁改的、改了什么、为什么改,git log 里都有。什么值得记:可复用的排查结论、环境怪癖、约定俗成的做法;官方也划了红线——密钥与生产数据不该进记忆。
读入口是召回命令:
npx ownmem recall -- "staging deploy timed out again, should I add more workers?"
README 示例输出的字段:条目名、score=0.875、lanes=exact,bm25f,ngram(命中了哪几条召回通道)、字段、信任级别(advisory authority),加一句风险提示——“当作线索去代码里复核,不要当作既定事实”——和正文摘录。lanes 里的 exact、bm25f、ngram 对应五条召回通道中的三条;advisory 是”建议级”的信任级别,配合那句提示,定位很清楚:记忆是线索,供你去代码里复核。
ownmem daily 面向管理者:把每天的代理活动压缩成计数包,不含查询文本、不含主题正文、不含文件路径;数据留在本机、Git 忽略、30 天过期。看得到活动量,看不到内容。
验证与隐私边界
验证两招:init 前用 npx ownmem init --check 预览改动;init 后看仓库里应出现 .ownmem/ 目录与指令文件中的与令块。不进会话也能直接验召回:
npx ownmem recall -- "你的项目相关问题"
有输出说明链路通了;再抛一个项目相关问题给代理,看它是否引用 .ownmem/ 里的条目。
隐私边界四条(官方 README):排序只读仓库文件与本地快照,无 LLM 调用、无网络请求、无检索 API 账单;遥测留在本机,Git 忽略、30 天过期;daily 计数包不含查询文本与文件路径;密钥与生产数据不该进记忆。本地优先的实际体感:断网也能召回,同一快照重复查询结果一致。被召回文本是数据不是权威,不能覆盖 host 指令或授权工具,代理自我归因也不算用户确认。关注点延伸到整个编码代理本地化的话,可以接着看本站的本地脱敏网关 Maskit。
常见问题
OwnMem 怎么安装?
两条命令:npm install —save-dev ownmem 装包,npx ownmem init —hook —hosts claude,codex 创建记忆目录并挂上 host 适配器;唯一前置是 Node.js 20.6+,装完仓库里多一个 .ownmem/ 目录,不用注册任何云服务。
init 只在与令块内改 CLAUDE.md 等指令文件,拿不准先 —check 预览;装完用 recall 验证召回。0.6.0 升级报错先跑 init —update,见上文警告一节。
OwnMem 支持 Cursor 和 Gemini CLI 吗?
支持,五类 host 全都支持。Cursor 走常驻 rule 或 MCP 服务器,MCP 需一步手动配置;Gemini CLI 走指令或 MCP 服务器;Claude Code、Codex、Grok CLI 则走 hook 接入。
--hosts 列表会被记录,重复传入即增删。Codex 有三个一次性信任步骤,Grok CLI 通过兼容层复用 Claude Code 的 hook 配置,五类 host 的完整接入表见上文。
OwnMem 0.6.0 升级后命令一直报错怎么办?
先跑 npx ownmem init —update:0.6.0 安装的 hook 子命令已不存在,不更新会在每次 Bash 调用时执行失败命令;升级涉及 core.hooksPath 清理,详见官方 UPDATING.md。
表现是代理每执行一条命令就先撞上一个失败的 ownmem 子命令。跑完 —update 无需其他操作;还不干净的话,按 UPDATING.md 检查 core.hooksPath 残留。