memory-core

@domencai/agent-memory 的便携 CLI、安装器、体检脚本和 agent skills。它是共享记忆库唯一的读写实现。

Claude Code、Codex 和 Grok 通过 memory-ops / handoff skill 调用它；@domencai/dsh-memory 也只把模型工具转成同一个 CLI 调用。写作格式、路径白名单、并发保护和隔离提交因此只实现一次。

安装

前置要求：Node.js >= 20、Git。无需安装其他 npm 依赖。

从 npm 安装（推荐）

npx @domencai/agent-memory install
node ~/.agents/agent-memory/verify.mjs

从源码安装

cd memory-core
node install.mjs install
node verify.mjs

安装器会先展示计划并等待确认，然后：

1. 创建或接入记忆库，默认位置是 ~/.agents/memory。
2. 把完整运行时复制到 ~/.agents/agent-memory，不依赖 checkout 或 npx 缓存继续存在。
3. 写入 ~/.agents/scripts/memory.mjs，并为已安装的 harness 配置两个 skill。
4. 用可重复更新、可干净卸载的标记块注入 CLAUDE.md / AGENTS.md。

默认不会覆盖外来文件、目录或软链；冲突目标会被跳过并报告。只有用户确认后才应使用 --force，且它也不会覆盖记忆库。所有安装参数与目标占用规则见 INSTALL.md。

第一次使用

安装完成后，直接用自然语言告诉 agent 你的意图：

先搜一下这个项目关于构建和包管理的记忆。
记一下：发布前必须先生成规则节，否则 DSH 会加载旧提示。
这里当初为什么选择复制运行时，而不是软链到 npx 缓存？
把当前执行状态交接给 Claude。

memory-ops 负责长期记忆和 decision log；handoff 只在用户明确要求交接时运行。两者都会显式传入当前工作目录和项目槽，不依赖 CLI 猜测上下文。

人工使用 CLI

每个子命令都必须带 --pwd <绝对路径> --slug <项目名>。这是刻意设计：CLI 不读 process.cwd()、不问 Git remote，也不推导项目名。

下面的入口在所有安装方式下都存在：

node ~/.agents/scripts/memory.mjs search \
  --pwd "$PWD" --slug agent-memory install symlink

检索时传 3–6 个短而独立的关键词。多个关键词是 OR 关系，命中更多的完整条目排在前面；默认不搜索记忆库的 README.md，元规则应使用 read README.md 查看。

命令速查

| 命令 | 用途 | | --- | --- | | index | 列出可读文件及 revision | | read [path] | 读取文件；省略 path 时读取当前项目槽 | | search <q>... [--regex] [--limit N] | 按完整条目检索，多关键词 OR | | capture --premise --guidance --why [--check] | 追加一条长期教训并单独提交 | | save --path --base --content-file --reason | 用 revision 保护的整文件替换 | | sync | 显式执行远端同步；普通读写绝不自动同步 | | handoff write/read/list | 写入、读取或检查单槽会话交接 | | log write --title --what --why --instead-of | 追加一条有取舍的决定 | | log search <q>... [--all] | 搜索决策原因；默认只搜当前项目 |

完整参数以 node ~/.agents/scripts/memory.mjs --help 为准。

记忆、log 与交接

| 类型 | 默认位置 | 回答的问题 | 生命周期 | | --- | --- | --- | --- | | 记忆 | ~/.agents/memory/ | 有哪些教训不要重犯？ | 改写成当前有效版本，过期就删除 | | 决策 log | ~/.agents/logs/<slug>/ | 当初为什么这样改？ | 只追加，永不改写 | | 会话交接 | ~/.agents/handoffs/<slug>/ | 上一个 agent 干到哪了？ | 单槽覆盖，用完即弃 |

三者不会混存：当前执行状态不属于长期记忆；决策 log 的历史不可改写，而长期记忆必须允许移除已经失效的指导。

什么才是一条记忆

一条长期记忆只有一种结构：在前提 P 成立时，做 X。

• --premise：这条指导成立的前提；前提失效，记忆就应退出。
• --guidance：在对应场景下应该怎么做。
• --why：观察到的症状，或用户拍板的理由。
• --check：可选的机械检验方式，例如命令、测试名或文件 + 符号。

capture 在构造时强制前三项。能提供 --check 的前提可以由当前 repo 重新验证；不能机械验证的指导以人的决定为权威，不能仅凭代码现状静默推翻。

什么才值得写 decision log

log write 要求 --title、--what、--why 和 --instead-of。如果说不出“认真考虑过但放弃了什么”，它通常只是一次工作记录，不值得成为长期决策依据。

每条决定写入独立 Markdown 文件并单独提交；同名决定也只会创建新文件，不会覆盖历史。

安全与恢复

• 每次写入只提交目标文件，不改变调用前已有的 staged / unstaged 状态。
• save 使用 read 返回的 revision 做 CAS；并发更新会明确冲突，不会后写覆盖先写。
• 所有可写路径都经过白名单和真实路径检查，拒绝 ..、.git 与 symlink 越界。
• 读结果明确标记为次级、未验证证据，并限制返回体大小。
• verify.mjs 对真实安装和真实记忆库只读；CLI 行为测试只在临时目录中写入。
• 记忆库和 log 都使用 Git 保留恢复路径，但脚本绝不自动 push。

更新与卸载

重新运行安装命令即可检查并更新受管运行时：

npx @domencai/agent-memory@latest install

卸载只移除受管运行时、CLI / skill 入口和注入块，不删除记忆库、log 或交接数据：

npx @domencai/agent-memory@latest uninstall

开发

bin/memory.mjs            CLI 入口：记忆、log、交接
lib/                      存储、Git、检索、规则与安装共享实现
skills/memory-ops/        长期记忆与 decision log skill
skills/handoff/           会话交接 skill
templates/                记忆库元规则与 harness 注入规则
install.mjs               安装、更新与卸载
verify.mjs                真实环境只读体检 + 临时目录行为验收

针对 CLI 或安装器的修改，至少运行：

node verify.mjs

设计文档

• docs/shared-writer.md — 共享写入器和 CLI 契约
• docs/module-boundaries.md — 数据模型与模块边界
• docs/acceptance.md — 并发、路径、提交隔离和检索验收

以上设计文档位于源码仓库；npm 包只携带运行时、skills、安装文档和体检脚本。