证据记忆库 rrrrrredy/agent-memory-system

智能体记忆系统

面向编码智能体的本地优先、有证据支撑的记忆。

Agent Memory System 保留运行时暴露的任务证据，把它重建为片段，将受支持的观察转成可审查的记忆候选，再通过独立的私有 Git 仓库共享脱敏后的记忆，并附带明确的验证与晋升记录。部署策略要求由操作员做出这些决定；软件把每份证明绑定到证据上，但不认证调用方是否为人类。

它要回答的问题比「智能体该记住什么？」更难：

这条记忆有什么证据支撑？它现在还有效吗？另一台机器能否在不接收私有对话记录的前提下使用它？

版本 0.3.0 在存储、派生、审查、私有 Git、检索、恢复与评估的基础上，新增了不可变记忆装载、证据绑定的审查包、可重放验证的本地 Codex 执行回执、前瞻性纵向研究记录，以及仅限回环地址的只读仪表盘。运行时适配器仍对版本敏感。证据不完整或兼容性声明无法验证时，系统会失败关闭。

不同之处

多数记忆工具会总结对话，再把摘要放进检索索引。本项目把证据、判断与分发分开：

flowchart LR
A["Agent-local traces"] --> B["Append-only evidence ledger"]
B --> C["Episodes and compaction checks"]
C --> D["Candidate memories"]
D --> E["Validation attestation"]
E --> F["Promote, supersede, or revoke"]
F --> G["Private Git memory repository"]
G --> H["Bounded cross-agent retrieval"]
H --> I["Immutable memory loadouts"]
I --> J["Native receipts and prospective studies"]

原始对话记录、工具输出、暴露的推理过程与本地路径都留在本地证据存储里。Git 只接收已批准记忆的可移植投影。私有仓库不等于允许上传原始任务历史。

核心保证

- 归一化之前，先对精确的源字节做内容寻址。
- 每条证据记录都参与一条只追加的 SHA-256 链。
- 跨进程写锁阻止合规写入方分叉存储。
- 缺失、截断、不透明或不可用的数据都会变成显式缺口。
- 没有验证证明和单独的晋升证明，候选无法成为可移植记忆；两份证明各自绑定到确切的证据状态。
- 冲突候选会被隔离；跨设备的语义冲突只上报，不用最后写入者获胜的方式解决。
- 审查者与批准者标识由调用方提供，属于证明。操作员策略要求由人检查证据，但命令行不会验证人的身份。
- 活跃记忆组成不可变的修订链，支持显式取代和撤销。
- 检索会校验完整的可移植仓库，应用精确的作用域和结果数量限制，并加上估算 token 与 UTF-8 字节预算，同时记录交付了什么。
- 记忆配置档指定确切的活动修订头。发生取代或撤销后，旧配置档会变为过期，而不是悄悄替换成新内容。由配置档支撑的原生执行会从新鲜度校验开始，一直持有可移植仓库的使用锁，直到拿到终端回执。
- 审查包冻结展示的候选文本、来源、生成信息和证据前缀，不把校验权限与晋升权限合并在一起。
- 原生 Codex 回执绑定确切的本地可执行文件字节、请求、JSONL、输出、用量和终端状态；它们不验证远程服务商、服务端模型或隐藏推理。
- 前瞻性研究在执行前封存每个请求、验收断言和工作区快照。Codex 启动前会写入一次性研究预留；失败会消耗该预留，结果会重放完整的 Agent 消息字节。报告保持描述性，不作因果结论。
- 外部执行的三条件研究可以在同一个仅追加的本地证据账本中登记一份经过严格校验、内容绑定的计划。登记只保留来源信息；它不授予执行权限或结果权限。
- 原始证据备份是可选的，使用 age 加密，并与可读记忆仓库完全分离。
- 未经单独且绑定目标的批准，绝不改动 AGENTS.md、技能和其他规则面。

这些保证适用于本地可用的证据。任何客户端都无法恢复服务商隐藏的推理，或运行时从未暴露的字节。

安装

项目可以用 Go 1.25 或更新版本从源码构建。

Windows PowerShell：

git clone https://github.com/rrrrrredy/agent-memory-system.git
cd agent-memory-system
New-Item -ItemType Directory -Force .\bin | Out-Null
go build -o .\bin\agentmem.exe .\cmd\agentmem
.\bin\agentmem.exe version

macOS 或 Linux：

git clone https://github.com/rrrrrredy/agent-memory-system.git
cd agent-memory-system
mkdir -p ./bin
go build -o ./bin/agentmem ./cmd/agentmem
./bin/agentmem version

带标签的发布版提供经过校验和验证的 Windows、macOS 和 Linux 归档；受支持的安装程序面向 Windows 和 macOS。参见安装、升级和卸载。

试试完整生命周期

examples/quickstart 下有一个隐私安全的测试夹具，走的是和真实 Codex 历史相同的路径。一条命令即可导入、派生、校验并报告下一步操作员操作：

$Evidence = Join-Path ([System.IO.Path]::GetTempPath()) ("agentmem-" + [guid]::NewGuid())powershell
$Onboard = .\bin\agentmem.exe onboard codex --root $Evidence --path .\examples\quickstart | ConvertFrom-Json
.\bin\agentmem.exe status --root $Evidence
.\bin\agentmem.exe review list --root $Evidence --status review_ready --limit 20
sh
evidence="$(mktemp -d)/evidence"
./bin/agentmem onboard codex --root "$evidence" --path ./examples/quickstart
./bin/agentmem status --root "$evidence"
./bin/agentmem review list --root "$evidence" --status review_ready --limit 20

评审和晋升始终是两个独立的显式决定；onboard 不会替你做其中任何一个决定。快速开始给出了完整的 PowerShell 和 POSIX 命令，涵盖评审、晋升、私有 Git 导出、精确检索，以及切换到已有的 Codex 会话目录。

日常使用时，保持同一个证据目录，有新历史时重新运行 onboard codex。用 review list 查看待处理的记忆，用 recall context 把相关的已晋升记忆提供给下一个任务： text agentmem recall context --root <evidence> --repo <private-memory> --agent codex --query "the next task"

升级提取规则后，带 --rebuild 运行一次 onboard codex，重新处理现有存储中未变化的历史。参见升级后重建。

运行时探测是可选的，永远不会阻断历史导入： powershell .\bin\agentmem.exe compatibility --agent codex sh ./bin/agentmem compatibility --agent codex

history_import_available 与 runtime_status 保持独立，所以版本探测被阻断时，不会掩盖一个可用的离线导入器。

兼容性与验证

| 层面 | 当前证据 |
| Codex rollout 导入 | 维护者报告的 Windows 私有真实 rollout 验收，加上公开的丢失/压缩测试样本和跨平台协议测试；这次私有运行无法从本仓库独立复现 |
| Claude Code 导入 | Windows、macOS 和 Linux 上的 transcript、history、companion、thinking 和未知块测试样本 |
| OpenCode 插件 | 固定版本的 OpenCode 运行时在 GitHub 托管的 runner 上启动，加载插件，捕获匹配的 session.created 事件，导入该事件，并校验账本；不使用任何服务商模型或密钥 |
| DeepSeek Harness Bundle | 真实的 Cordis、SessionStore、JSONL Persistence 和 agent/pre-step 组合测试，覆盖逐字回填、崩溃安全的实时捕获、已验证记忆注入、真实命令行导入和干净卸载；这是社区 Bundle 证据，不是 DeepSeek 认证 |
| 评审与记忆生命周期 | 绑定证据的调用方声明、晋升、取代、撤销、密钥扫描和冲突测试；调用方身份未做认证 |
| 跨设备记忆 | 私有 Git 历史校验、离线使用、分叉处理、恢复，以及托管的 Windows/macOS/Linux 测试 |
| 原生 Codex 记忆诊断 | 一套冻结的 20 簇合成测试集，跑了 20 组配对的已认证 codex exec 任务，采用封存的无工具策略，并校验检索注入：19 胜、1 平、0 负；基线 1/20，记忆 20/20；单侧符号检验 p=0.0000019073。这是有边界的能力证据，不是纵向认证；见汇总回执 |
| 原生 Codex 过程回执 | 本地 Codex 与 runner 的精确字节、请求、参数、原始 JSONL、用量、输出和终端状态都可重放；服务商、模型和私有推理无法独立佐证 |
| 可移植配置档 | 按内容寻址的精确修订集、作用域、智能体允许列表、预算、过期头部拒绝，以及复合投递回执 |
| 前瞻性研究 | 预先封存的请求与工作区快照、不可变的智能体消息接受哈希、确定性均衡分配、单次使用且绑定研究的尝试，以及由重放推导的结果；未对已完成的真实世界纵向有效性作出声明 |
| 学习有效性 | 冻结语料指标与重放已实现；除非任务执行得到独立校验，否则有效性认证仍被阻断 |

运行本地、非变更的运行时探测： text agentmem compatibility

该探测检查可执行文件是否可用以及版本输出。它不声明账号已认证、服务商运行过模型，或原生会话已被捕获。见兼容性与证据等级。

记忆生命周期

可移植记忆不是可编辑的笔记。它是一条不可变的修订链： text promote -> active revision active revision -> supersede -> new active revision active revision -> revoke -> tombstone

只有当前、未撤销的头部才能被检索。两个根、同一父节点的两个子节点、被改动的历史文件，或相互对立的活跃记忆，都会让校验失败。见晋升与可移植记忆。

检索

检索是确定性的、离线的。它结合精确身份查找、Unicode 词与 CJK 双字匹配、作用域特异性、证据强度和稳定平局裁决。没有零匹配回退。

直接使用命令行，或通过本地 stdio MCP 服务器暴露同一套已校验的搜索： text agentmem recall search --root <evidence> --repo <private-memory> --agent codex --query "release checks" agentmem serve mcp --root <evidence> --repo <private-memory> --agent codex

Codex、Claude Code、OpenCode 和 DeepSeek Harness 消费同一套可移植协议。它们的原生钩子、插件或 Bundle 是可选的；命令行与 MCP 仍是稳定边界。DeepSeek Harness 社区 Bundle 的文档见 integrations/deepseek-harness。

运维记忆

创建一组可复用、精确的已晋升修订： text
agentmem loadout create --repo <private-memory> --name "Release checks" \
--scope-kind project --scope-value example-project --agent codex \
--memory <memory-id>
agentmem loadout context --root <evidence> --repo <private-memory> \
--loadout <loadout-id> --agent codex --scope-project example-project

晋升前先构建一个不可变的评审界面：

agentmem review packet --root <evidence> --status review_ready --limit 20
agentmem promote candidate --root <evidence> --candidate <candidate-id> \
--packet <review-packet-path-or-id> --approver local-user \
--reason "Approved after reviewing the bound packet."

从带版本的请求运行并重放本地 Codex 进程：

agentmem agent run codex --root <evidence> --file <request.json> \
--codex <codex-executable>
agentmem agent verify --root <evidence>

本地仪表盘只暴露校验摘要：

agentmem serve dashboard --root <evidence> --repo <private-memory>

参见 loadouts、native execution、prospective study registration and longitudinal studies 和 dashboard。

存储边界

| 区域 | 内容 | 可以进入 Git 吗？ |
| 本地证据 | 精确转录、工具输出、暴露的推理、归一化事件、缺口、回执 | 不可以 |
| 可移植记忆 | 经证明并脱敏的 Markdown/YAML 修订，加上不可变 loadout | 仅限单独的私有仓库 |
| 加密备份 | 完整的本地证据快照 | 可选备份后端，绝不能是记忆仓库 |

不要把整个 Codex home、Agent 状态数据库、会话目录或本地证据根目录复制进记忆仓库。SQLite 可以用作可重建的本地索引，绝不能作为 Git 合并的规范数据。

项目不声称什么

- 不捕获服务商隐藏的私有思维链。
- 不把摘要当作缺失的原始推理。
- 不自动晋升模型写出的断言。
- 不静默合并语义冲突。
- 不因为检索跑过就证明检索改善了工作。
- 不把描述性的纵向关联变成因果结论，也不变成由服务商独立认证的效力。
- 未经明确批准，不修改 Agent 规则，也不安装钩子。

仓库结构

- cmd/agentmem：跨平台命令行
- adapters：能感知丢失的 Codex、Claude Code、OpenCode 和 DeepSeek Harness 导入器
- internal/ledger：只追加的证据与按内容寻址的 blob
- internal/episodes、internal/candidates：重建与提取
- internal/review、internal/promotion：经证明的决策与记忆生命周期
- internal/portable、internal/gitsync：可移植投影与私有 Git
- internal/loadout、internal/retrieval、internal/mcpserver：精确 loadout、有界查询与投递回执
- internal/reviewpacket：不可变的候选评审界面
- internal/agentbridge：可回放验证的本地 Codex 进程证据
- internal/study：前瞻性分配、观察与描述性报告
- internal/dashboard：仅限回环地址的只读运行摘要
- internal/codexbench：密封的原生 Codex 基线/记忆诊断
- internal/evaluation：冻结语料、配对试验、指标与回放
- internal/backup、internal/diagnostics：加密恢复与完整性
- schemas：带版本号的公开 JSON 契约
- docs/adr：架构决策与威胁边界

详细的协议文档放在 docs 下。先读产品契约、威胁模型和验证指南。

开发

go test ./...
go vet ./...
go build ./cmd/agentmem

CI 矩阵在 Ubuntu、Windows 和 macOS 上运行。有状态的安全包还会开启 Go 竞态检测器运行。OpenCode 运行时冒烟测试只在一次性托管 runner 内安装其固定版本的运行时。DeepSeek Harness Bundle 有独立的 Node 22.19+/24 构建、Cordis 组合和包测试。

改动适配器、schema 或证据边界之前，先看 CONTRIBUTING.md。永远不要把真实对话记录或原始证据附到 issue 里。

许可证

MIT。见 LICENSE。