Git 作为记忆层

使用 git-as-memory 作为代理（agents）的持久化、可审计的记忆层。它将记忆存储在专用的 Git 引用（ref）中，而非工作树（working tree）内。

默认引用（ref）：

refs/git-as-memory/memory/v1

支持的代理：OpenClaw、Hermes、Claude Code、Codex，或任何能够执行 shell 命令的代理。

安装与初始化

若已安装 gam，优先使用：

command -v gam

若未安装，任选其一进行安装：

npm install -g git-as-memory
pip install git-as-memory

无需全局安装（按需运行）：

npx git-as-memory --help
python -m git_as_memory.cli --help

所有命令均需在 Git 仓库中执行。若未指定 --repo 参数，则默认使用当前工作目录所在的仓库。

每个仓库仅需初始化一次，该操作是幂等的：

gam init --repo /path/to/repo

记忆写入策略

仅对稳定、可复用的信息写入记忆。

应在以下情形写入记忆：

• 用户明确要求记住某项内容；
• 出现稳定的用户偏好；
• 发现项目约定、工作流或关键决策；
• 习得反复出现的缺陷、临时解决方案、工具行为或运维经验；
• 某次会话产出简洁结论，未来代理应复用该结论。

禁止写入以下内容：

• 密钥、API 密钥、密码、令牌、Cookie、凭据、私有认证材料等敏感信息；
• 大段原始对话记录或高噪声日志；
• 无长期价值的一次性任务细节；
• 未经验证的推测，除非显式指定 --type hypothesis；
• 本应存于源码文件、文档、 Issue 或测试中的内容，而非记忆中。

写入前请执行以下步骤：

1. 首先搜索已有相关记忆：

   gam search "" --repo /path/to/repo
   

2. 若存在相关记忆，更新同一稳定 ID 对应的记忆条目；
3. 若不存在，则创建一条简明的新记忆；
4. 始终通过 --source 参数说明该记忆的来源。

写入完成后，请报告该记忆的键（key）：

/

记忆类型（Types）

使用一组精简且保持一致的类型：

• entity：用户、项目、组织、工具或其他实体的偏好/档案；
• semantic：持久性事实、规则、约定、决策或技术经验；
• episodic：任务/会话/事件的简洁摘要；
• working：生命周期较短的任务上下文，后续可能被清理；
• hypothesis：未经验证的推断，应在强依赖前完成确认。

ID 命名规范

使用稳定、小写的 kebab-case 格式 ID，优先选用未来代理可合理推测出的名称。

推荐示例：

user-preference-concise-answers
project-release-workflow
openclaw-memory-policy
git-as-memory-storage-layout

除非确实无法抽象出稳定概念，否则避免使用随机 ID。

核心命令

写入（Write）

gam write "User prefers concise technical answers with concrete commands." 
  --repo /path/to/repo 
  --type entity 
  --id user-preference-concise-answers 
  --tag user 
  --tag preference 
  --source "User corrected the agent for over-explaining and asked for practical output."

多行内容写入（通过 stdin）：

printf '%sn' "Decision summary..." | gam write --stdin 
  --repo /path/to/repo 
  --type semantic 
  --id project-decision-example 
  --source "Summarized from the current implementation session."

读取（Read）

当你已知确切记忆键（key）时，使用 read：

gam read entity/user-preference-concise-answers --repo /path/to/repo

show 在仅提供 ID 并可选指定 type 时效果等同：

gam show user-preference-concise-answers --type entity --repo /path/to/repo

搜索（Search）

使用 search 进行内容检索：

gam search "release workflow" --repo /path/to/repo
gam search "concise answers" --repo /path/to/repo --json

搜索基于本地子字符串匹配，覆盖记忆正文、标签（tags）、元数据及 source 字段文本。

通配匹配（Glob）

glob 用于记忆键（key）匹配，而非任意工作树文件。支持匹配 / 格式或裸 ID：

gam glob "entity/*" --repo /path/to/repo
gam glob "user-*" --repo /path/to/repo
gam glob "*release*" --repo /path/to/repo

--files 仅用于调试底层 Git 树结构：

gam glob "entity/*" --files --repo /path/to/repo

列举（List）

gam list --repo /path/to/repo
gam list --repo /path/to/repo --json

历史与审计（History and Audit）

gam history user-preference-concise-answers --type entity --repo /path/to/repo

直接通过 Git 检查：

git -C /path/to/repo log --oneline refs/git-as-memory/memory/v1
git -C /path/to/repo ls-tree -r --name-only refs/git-as-memory/memory/v1

删除（Delete）

优先使用软删除（soft delete）：

gam delete user-preference-concise-answers --type entity --repo /path/to/repo

仅当用户明确要求移除当前可见文件时，才使用 purge：

gam purge user-preference-concise-answers --type entity --repo /path/to/repo

代理工作流（Agent Workflow）

在仓库中启动新任务时：

1. 若记忆可能影响任务执行，先执行定向搜索：

   gam search "" --repo /path/to/repo
   

2. 仅读取真正相关的匹配项；
3. 除非用户主动要求审计，否则切勿批量加载全部记忆。

当出现持久性经验时：

1. 判断是否符合写入策略；
2. 搜索重复条目；
3. 写入或更新一个稳定 ID 的记忆；
4. 报告该记忆键（key）及其一行摘要。

当用户询问“你记住了什么？”时：

1. 使用 gam list、gam glob 或 gam search 列出候选项；
2. 对相关 key 使用 gam read 获取详情；
3. 仅当出处（provenance）或演进过程（evolution）至关重要时，才附加 gam history 输出。

输出规范（Output Discipline）

完成一次记忆写入后，请简要响应：

Remembered: entity/user-preference-concise-answers

若决定不写入记忆，仅在具备实际意义时说明原因：

Not writing memory: this is a one-off task detail.