agent-memory-kit

Claude Code 用户：本项目的原型运行于 Claude Code，宿主适配层接口已就位（memkit/host.py），Claude 适配器待实现。与 oh-my-claudecode 的边界见 § 与相邻方案的关系。

给 Codex 装一层看得见、改得动、管得住的长期记忆。

不是把对话灌进向量库，而是每次会话开始就把记忆目录放进模型手里。

快速开始 • 为什么 • 核心机制 • 架构 • 文档

快速开始

codex --version                  # 前置：Codex CLI 已安装并登录
npm install -g agent-memory-kit
amk setup                        # 装配记忆层（全部可逆），随后自动进入自检

重启一个 Codex 会话——hooks 在会话启动时加载，装配所在的会话不会生效。

就这样。此后记忆的注入、沉淀、整理都是自动的，只有落盘需要你点头。

amk skills                       # 看包内还捆绑了哪些技能（falsifier / 可视化 / a2a…）
amk add falsifier 可视化          # 按需追装
amk setup --all                  # 或一次装全部
amk doctor                       # 出问题先跑它

在 Codex 中说明来源，由内置的 skill-installer 完成拉取：

从 github.com/TZD666/agent-memory-kit 安装 skills/reg 技能

然后装配：

python3 ~/.codex/skills/reg/scripts/install.py --dry-run   # 演练，打印将改动的每一处
python3 ~/.codex/skills/reg/scripts/install.py
python3 ~/.codex/skills/reg/scripts/doctor.py

两种方式装出来的东西完全一致；npm 方式只是多了 amk 这个入口命令。

不确定从哪开始？

按这五步走一遍，能把整条链路都验证到：

1. 查看初始内容：cat ~/.codex/agent-memory/memory/MEMORY.md——四张示例卡各对应一种类型，看完可直接删。
2. 正常用 Codex 做一件小事，过程中纠正它一次（例如"这类改动以后先跟我确认"）。
3. 说「整理一下记忆」触发手动回归：体量审计 → 盘点 → 体检 → 沉淀 → 落盘 → 自检闸。
4. 检查产物：ls ~/.codex/agent-memory/memory/，那条纠正应已成为一张带 **Why:** 与 **How to apply:** 的 feedback_ 卡。
5. 关闭会话重新打开，直接问"我上次让你注意什么"。索引已在上下文中，不应出现"我不记得"。

为什么是 agent-memory-kit

• 每次会话自动注入，不靠模型自觉 —— 索引由 SessionStart hook 写进上下文，不需要工具调用、不需要你提醒
• 按需召回整卡 —— 每次输入由确定性打分器挑出至多 5 张相关卡整卡注入，宁缺毋滥，会话内不重复
• 密钥永远进不了记忆 —— gitleaks 高置信规则集在写入端扫描与脱敏，扫描报告绝不回显密钥原文
• 记的什么你随时能看 —— 全是普通 markdown，可读可改可删可进 git，不存在黑盒
• 自动整理，但绝不自动落盘 —— 提案写入独立目录，逐条确认后才进记忆层
• 产出物自带检索元数据 —— 新生成的 md 按 OKF 约定加头，并有确定性工具校验
• 零检索基础设施 —— 没有 embedding、没有向量库、没有服务要维护
• 常驻成本恒定 —— 只有规则和目录常驻，内容按需读取，不会随记忆增长而线性涨 token
• 关键判断全是代码 —— 触发时机、并发控制、递归防线、体检规则都是确定性实现，不依赖模型配合
• 改你的机器完全可逆 —— 备份、标记、幂等、一键卸载
• 零第三方依赖 —— 只用 Python 标准库，hook 不会因为 import 失败拖累宿主

核心机制

三级上下文注入

Agent 的上下文是一次性的。会话结束，纠正过的偏好、约定过的口径、踩过的坑随之消失。

把知识全塞进常驻指令文件，每次会话都要为全部内容付 token，很快撞上预算；灌进向量库，则检索结果不可预测且无法人工干预。本项目的取法是把"内容"和"目录"分开常驻：

| 级 | 内容 | 进入上下文的方式 | 成本 | | --- | --- | --- | --- | | 规则 | ~/.codex/AGENTS.md 中的瘦桩段 | 宿主每次会话必载 | ~2 KB，恒定 | | 目录 | memory/MEMORY.md 索引 | SessionStart hook 注入 additionalContext | ≤ 25 KB，恒定 | | 内容 | memory/*.md 卡片全文 | UserPromptSubmit hook 按需召回，或命中索引后主动读取 | 只为真正相关的付费 |

会话一开始，模型已经"知道自己知道什么"。只有当某一行确实与当前任务相关时，才去读那张卡的全文。

实现差异：Claude Code 的宿主自带原生记忆机制，会替你注入索引；Codex 的宿主不认识第三方目录，因此这一步由 session_inject.py 显式完成。在 Codex 上，这个 hook 就是整套系统的主通道——没有它，索引只是磁盘上一个模型"被告知应该去读"的文件。

索引常驻，是"一行 description 就能完成召回"的前提。 目录只有十几 KB，可以整份放进上下文，于是检索问题从"在海量中找相似"退化成"在一张百行清单里挑相关"，而后者恰是语言模型的强项。代价明确：索引上限约 200 行 / 25 KB，超过这条线宿主会静默截断，因此体检器把它作为硬约束持续监控，并在 80% 处发出毕业预警。

按需召回与新鲜度

索引解决"知道自己知道什么"，按需召回解决"用的时候不必再去翻"。每次用户输入，recall.py（UserPromptSubmit hook）对着卡片清单打分，把相关的卡整卡注入——模型不用花一轮工具调用去读文件：

• 确定性打分器（默认）：CJK 双字 + ascii 词与卡头（文件名 + description）的重叠打分，毫秒级、零成本、行为可测。只看卡头不读正文——description 命中才是设计出来的信号，这正是"description 决定召回"的机械兑现。
• 宁缺毋滥：低于阈值不注入，至多 5 张；本会话注入过的卡不重复注入。
• 新鲜度标注：注入的卡标注「N 天前」而非时间戳（模型不擅长日期算术，"47 天前"能触发陈旧性推理，ISO 串不能）；超过 1 天的卡附「彼时快照，引用前先核实」提示。
• MEMKIT_RECALL=llm 可换 LLM 选卡（更准，但 hook 同步执行，延迟加在每次敲回车上）；off 关闭。

密钥防线

记忆卡会进入未来每一次会话的上下文，还可能进 git、被分享——一个被写进记忆的 API key 会反复出现。所以扫描发生在写入端：

| 接入点 | 行为 | | --- | --- | | dream.py 提案落盘前 | 命中即替换为 [REDACTED]，报告点名警告并提示轮换凭据 | | lint_memory.py 全库体检 | 命中即 error | | doctor.py 自检 | 专项一行 |

规则移植自 gitleaks（MIT）的高置信子集——只收带独特前缀、近零误报的规则（AWS/GCP/GitHub/GitLab/Slack/Stripe/OpenAI/Anthropic/私钥块等约 35 条）。扫描结果只报规则名，绝不回显密钥原文。

记忆卡片体系

一文一事实，四种类型决定的是什么时候该删：

| 类型 | 装什么 | 生命周期 | | --- | --- | --- | | user | 你是谁：角色、专业、长期偏好 | 近乎永久，是其余卡片的解释背景 | | feedback | 你的纠正与确认过的做法（必须含 Why / How to apply） | 稳定后可毕业进文档层 | | project | 进行中的工作上下文 | 最易过期，回归时的首要清理对象 | | reference | 外部资源、工具、配置位置的指针 | 合法长期常驻 |

文件名前缀与类型强制一致，因此 ls memory/project_*.md | wc -l 就能直接回答"有多少个进行中的项目"——不必解析 YAML，更不必问模型。详见 卡片规范。

回归流程：手动与自动两档

| 档 | 触发 | 行为 | | --- | --- | --- | | 手动 | 会话中说 /reg | 你在场，走完 S0–S6 六步，真正落盘 | | 自动 | 会话结束（当天未手动整理过） | 后台生成提案写入 memory_dreamed/，绝不改原文 | | 审核 | 下次会话说 /reg apply | 看摘要 → 逐条 diff 应用 → 清除标记 |

自动档过五道闸才会启动：递归防线 → 手动优先 → 每日至多一次 → 并发锁 → 有料才跑。全过后 detach 启动并立即返回，不阻塞会话结束。

无人监督地改写记忆是本项目的第一条红线。

OKF：产出物的元数据约定

记忆层管的是"agent 记住什么"；OKF 管的是"agent 产出的 md 日后还能不能被找到"。两者都随装配写进常驻规则。

新生成的 md 默认在最顶端加一段元数据头：

---
type: research          # 唯一强制字段
title: 竞品定价策略对比
description: 六家竞品的定价结构与折扣策略横向对比
tags: [竞品, 定价, 调研]
timestamp: 2026-07-28T15:30:00+08:00
---

type 词表：daily-report · summary · research · analysis · note · reference · plan · spec · runbook，不在表内可自拟 kebab 词。

三条跳过决策表——命中任一条就不加，因为误加的代价远高于漏加（漏加事后补一行即可，误加到口播稿上会被 TTS 读进音频）：

1. 成品正文：会被发布 / 朗读 / 渲染排版 / 导出 PDF，或作为内容喂给下游流程
2. 由已有固定输出格式的流程产出：以那个格式为准
3. 用户明确要纯净 md

规则写进常驻指令只解决"知道该这么做"，不解决"到底做没做到"，所以配了确定性工具：

python3 ~/.codex/skills/reg/scripts/okf.py check <目录>       # 查合规，退出码可接入检查流程
python3 ~/.codex/skills/reg/scripts/okf.py add <文件> --type research --dry-run

add 只在文件最顶端插入，写入后逐字节复核正文未被改动，不符即回滚。决策表第 1 条需要判断产出物用途，代码判定不了，因此工具不替你决定——只在执行后打印跳过条件供你撤销。完整规范见 OKF 约定。

安全与可逆

装配只改三处，每处都有对应的回退路径：

| 改动 | 保护措施 | | --- | --- | | 创建 ~/.codex/agent-memory/ | 只新建，已存在的内容一律不覆盖 | | 向 ~/.codex/AGENTS.md 追加规则段 | 用 <!-- agent-memory-kit:begin/end --> 包裹，卸载时精确摘除 | | 合并 ~/.codex/hooks.json | 先备份再原子写；已有 hook 一条不动；重复安装幂等 |

uninstall.py 默认保留你写的记忆内容——那是你的东西，不该被卸载脚本带走。测试中有预置冲突场景的完整验证（见 tests/run_tests.py）。

架构

会话进行中
   │
   ├─ SessionStart ─────→ session_inject.py ──→ 索引注入上下文（+ 待审提案提醒）
   │
   ├─ UserPromptSubmit ─→ recall.py ─────────→ 相关记忆卡整卡注入（打分选卡，≤5 张）
   │
   └─ Stop ──────────→ reg_auto.py
                          │ 五道闸：递归防线 / 手动优先 / 每日一次 / 并发锁 / 有料才跑
                          ↓ 全过则 detach 启动，立即返回
                       dream.py
                          │ 输入：记忆全量 + 当日会话记录（有预算截断）
                          │ 输出：delta 变更集（非整库重写）
                          ↓
                       memory_dreamed/v<日期>_auto/   ← 只写这里
                          ↓ 下次会话提醒 → 你说 /reg apply
                       逐条审核 → memory/            ← 人确认才进

LLM 后端三级回退，逐级真探测：

| 级 | 判据 | 效果 | | --- | --- | --- | | codex exec | which codex 命中 | 零配置，用你已有的 Codex 额度 | | OpenAI 兼容 API | MEMKIT_API_BASE + MEMKIT_API_KEY | 任意兼容 /chat/completions 的端点 | | 无 | 都没有 | 退化为机械体检（断链 / 重复 / 相对时间 / 契约 / 体量），并明确说明这不是完整回归 |

delta 模式的由来、模型输出加固、五道闸的顺序与理由，见 架构说明。

附带的技能

仓库里是一组可独立安装的 Codex 技能。reg 是主体（记忆系统本身），其余按需取用：

| 技能 | 作用 | 安装路径 | | --- | --- | --- | | reg | 记忆系统本体：三级注入、手动/自动回归、OKF 约定、装配自检 | skills/reg | | a2a | 跨 agent 协作：任务章程、通道选择、有回执的多轮协作、独立终审 | skills/a2a | | karpathy-guidelines | 高标准编码准则：避免过度工程、外科手术式改动、显式暴露假设 | skills/karpathy-guidelines | | md-to-pdf | Markdown 转带中文样式的 PDF（需 pandoc + Chrome） | skills/md-to-pdf | | data-summary | 多份资料的脱敏摘要，逐条标注来源出处（PDF 解析需 pdfplumber） | skills/data-summary | | 播客文案 | 文档转双主持人中文播客对话稿，含自检报告 | skills/播客文案 | | skill-vetter | 技能审查：装之前先过一遍安全与质量 | skills/skill-vetter | | falsifier | 数据溯源审计：把已写好的总结/报告逐条拿回原始信源核对，专抓编造数字、估算冒充事实、张冠李戴 | skills/falsifier | | html速读 | 把一份资料做成「一眼读懂」的可视化速读页（总览图 + 分节图解，不改原文） | skills/html速读 | | 可视化 | 图表与图解生成引擎：选型决策表 + ECharts SSR 出 SVG/PNG + 色盲校验（需 Node.js，依赖自愈到 ~/.cache） | skills/可视化 | | 高级ui | 简洁高级的 Web UI 设计系统：新建页面/控制台/工具界面的默认风格 | skills/高级ui |

安装单个技能，在 Codex 中说明路径即可：

从 github.com/TZD666/agent-memory-kit 安装 skills/md-to-pdf 技能

也可以一次装多个——skill-installer 支持多个 --path。

除 reg 外都是可选的，装不装不影响记忆系统运行。

与相邻方案的关系

Claude Code 官方记忆系统（设计参照）

本项目的核心机制逐一对照了 Claude Code 记忆子系统的工程实现——四型分类、显式保存闸、引用前核实、宁缺毋滥的召回、密钥扫描、"N 天前"新鲜度标注，均有官方源码出处，其中多条措辞带线上评测分数。哪些原样移植、哪些因宿主差异改动、哪些明确不做，见 设计溯源。

Codex 原生记忆（~/.codex/memories/）

Codex 自带一套记忆，会话结束后自动蒸馏成按任务分组的摘要。两者并行运行、互不写入，可以同时开着。

| | Codex 原生记忆 | 本项目 | | --- | --- | --- | | 产生方式 | 会话结束自动蒸馏，无人工环节 | 自动生成提案，人工确认后落盘；也可随时手写 | | 存储形态 | 机器生成的分组摘要 | 一文一事实的 markdown 卡片，含 Why / How to apply | | 可编辑性 | 不直接编辑 | 普通 md 文件，可改可删可进 git | | 进入上下文 | 由 Codex 内部决定 | 索引每次注入，卡片按需读取，路径公开可查 | | 稳定性 | 会被 Codex 自行重写 | 只有你和你确认过的提案能改动它 |

本项目从不读取、也从不写入 ~/.codex/memories/。doctor.py 会报告两者的共存状态。

oh-my-claudecode（OMC）

本项目的原型长在 Claude Code + OMC 的环境里，因此有必要说明边界。

记忆层本身不依赖 OMC。 卡片、索引、回归流程、hook 脚本都是独立实现，不调用 OMC 的任何能力。移植到 Codex 后自然也不需要 OMC。

但两者在原环境中有三处真实交集，移植时都做了处理：

| 交集 | 原环境的情况 | 本项目的处理 | | --- | --- | --- | | 常驻指令文件 | CLAUDE.md 本身是 OMC 的编排层文件，记忆瘦桩写在其中 | 改写到 AGENTS.md，用注释标记包裹，与文件里其他内容互不干扰 | | 记忆能力重叠 | OMC 另有一套项目级记忆（project-memory hooks、.omc/project-memory.json、notepad、wiki 技能），作用域是单个仓库 | 本项目是跨会话的个人层，作用域是你这个人。两者层级不同，可以共存 | | 子进程自激 | 提案引擎调 headless 模型时必须 DISABLE_OMC=1，否则子会话会把整个编排层再拉起来 | 移植为 MEMKIT_CHILD=1 递归防线：子进程带标记，Stop hook 见到即退出。这是优先级最高的一道闸 |

同时使用 Claude Code + OMC 和 Codex 的话，两边各装各的，互不影响。

oh-my-codex（推荐搭配）

本项目只管记忆——记住什么、怎么召回、怎么整理。它不提供编排能力：没有多 agent 团队、没有自动规划、没有执行模式。

想要那一层，用 oh-my-codex (OMX)——OMC 作者做的 Codex 版工作流层，提供 hooks、agent 团队、HUD、结构化工作流与持久化项目状态：

npm install -g oh-my-codex     # 需 Node.js 20+ 与已认证的 Codex CLI

两者正交，可以同时装：OMX 负责怎么干活，本项目负责记住什么。 OMX 的项目状态落在 .omx/（单仓库作用域），本项目的记忆落在 ~/.codex/agent-memory/（跨会话的个人作用域），互不写入。

多 agent 协作

Codex 上有三条协作通路，能力与失控半径完全不同——原生 subagent（会话内有界扇出）、OMX 团队（tmux 持久 worker + 共享任务状态）、a2a 跨 CLI（仓库附带，异构 agent 互审与终审）。选型与四个"记忆层 × 多 agent"的真实交互（子代理看不到记忆、worker 会触发全部 hook、递归自激、作用域正交）见 harness 02 · 多 agent 协作。

其中一条交互已用代码兑现：OMX team worker 是真实 Codex 会话，会触发 Stop hook——reg_auto.py 检测 OMX_TEAM_WORKER 即跳过，不让 worker 的碎片化会话烧掉每日自动整理的名额（有测试覆盖）。团队运行时本身请用 oh-my-codex，本项目不重复造它。

日常操作

| 操作 | 方式 | | --- | --- | | 手动整理记忆 | 会话中说 /reg | | 审阅自动提案 | 会话中说 /reg apply | | 自检 | python3 ~/.codex/skills/reg/scripts/doctor.py | | 仅机械体检 | python3 ~/.codex/skills/reg/scripts/lint_memory.py | | 检查产出 md 的 OKF 头 | python3 ~/.codex/skills/reg/scripts/okf.py check <目录> | | 手动产一份提案 | python3 ~/.codex/skills/reg/scripts/dream.py --days 7 --label manual | | 临时停用自动档 | export MEMKIT_AUTO=off | | 卸载 | python3 ~/.codex/skills/reg/scripts/uninstall.py |

完整流程与运维速查见 操作指南。

环境要求

• Python 3.9+ —— macOS 自带的 python3 通常已满足
• 支持 hooks 的 Codex 版本 —— 缺失则手动 /reg 仍可用，自动档不触发
• 可写的 ~/.codex/
• 第三方 pip 包：零

自动整理的能力上限取决于可用后端，三级回退一个都没有也能用：

| 后端 | 怎么算具备 | 效果 | | --- | --- | --- | | Codex CLI | command -v codex 能找到 | 零配置 | | OpenAI 兼容 API | 设了 MEMKIT_API_BASE + MEMKIT_API_KEY | 任意兼容端点 | | 都没有 | —— | 机械体检，仍能查出断链 / 重复 / 相对时间 / 契约 / 体量问题 |

全部环境变量见 环境要求。

当前限制

• codex exec 后端未经实跑验证。 三级回退的第一级在开发机上无法验证（该机器 codex 不在 PATH）。实现遵循官方非交互模式：prompt 经 stdin 传入（codex exec -），因为以位置参数传 prompt 在非 TTY 子进程中会永久阻塞。首轮自动整理即为该通道的真实验证，doctor.py 中标注了其状态。API 后端与无后端降级路径均已验证。
• 仅支持 Codex。 宿主适配层接口已就位，Claude Code 适配器未实现。
• memory_dreamed/ 不自动清理。 每轮自动整理保留一份基线副本，需自行清理历史目录。
• 索引规模上限约 25 KB。 超出后应做知识毕业，而非放宽限制——这是宿主的静默截断线。

仓库结构

agent-memory-kit/
├── skills/reg/          技能本体与全部脚本（skill-installer 的安装单元）
│   ├── SKILL.md         手动回归 S0–S6、提案审核、装配自检
│   ├── scripts/         install / uninstall / doctor / lint / okf / dream / recall / hooks
│   │   └── memkit/      路径 · 宿主适配 · LLM 后端 · 会话解析
│   └── templates/       AGENTS.md 规则段、索引骨架、四张示例卡
├── skills/a2a/          跨 agent 协作技能
├── skills/<其余>/        karpathy-guidelines · md-to-pdf · data-summary · 播客文案 · skill-vetter
├── docs/                架构说明 · 操作指南 · 卡片规范 · OKF 约定 · 设计溯源 · 排障
│   └── harness/         工程笔记：hooks 生命周期 · 多 agent 协作 · 沙箱 · 会话数据层
├── requirements/        环境要求与依赖说明
└── tests/run_tests.py   90 项真实路径测试

验证仓库完整性：python3 tests/run_tests.py

文档

• 架构说明 —— 三级注入、delta 模式、五道闸、输出加固、设计取舍
• 操作指南 —— 从安装到卸载的完整流程与运维速查
• 卡片规范 —— 四种类型的分工与生命周期、description 写法、什么不该记
• OKF 约定 —— 产出物元数据规范：字段、type 词表、三条跳过决策表、校验工具
• 设计溯源 —— 每个机制在 Claude Code 源码中的对应物与移植取舍
• harness 工程笔记 —— hooks 生命周期 · 多 agent 协作 · 分叉代理与权限沙箱 · 会话数据层
• 排障 —— 安装失败、hook 未触发、提案异常、体检报错
• 环境要求 —— 前置条件、三级后端判据、全部环境变量