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

Agent Memory System

CI
License: MIT

面向编码代理的本地优先、证据支撑的记忆系统。

Agent Memory System 会保留运行时暴露的任务证据，将其重建为片段（episodes），把有支撑的观察转化为可审查的记忆候选，并仅通过一个独立的私有 Git 仓库，以显式验证和晋升记录的方式共享经过脱敏的记忆。部署策略要求由操作员做出这些决定；该软件将每份证明绑定到证据，但不会认证调用者是人类。

它要解决的是一个比“代理应该记住什么？”更难的问题：

是什么证据支撑这条记忆，它是否仍然有效，另一台机器能否在不接收私有对话记录的情况下使用它？

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

为什么这不一样

大多数记忆工具会总结一段对话，并把摘要放入检索索引。本项目将证据、判断和分发分开：

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 链。
- 跨进程写入锁可防止合规写入者分叉存储。
- 缺失、截断、不透明或不可用的数据都会成为显式缺口。
- 没有验证证明和单独的晋升证明，候选记忆就不能成为可移植记忆，且每份证明都绑定到确切的证据状态。
- 冲突的候选记忆会被隔离；跨设备的语义冲突会被报告，而不是用最后写入获胜（last-write-wins）来解决。
- 审查者和批准者标识符是调用者提供的证明。操作员
策略要求由人工检查证据，但 CLI 不会对人工身份进行认证。
- 活跃记忆形成不可变的修订链，并具有显式的取代和撤销机制。
- 检索会验证完整的可移植仓库，应用精确的作用域和结果限制以及估算 token 和 UTF-8 字节预算，并记录已交付的内容。
- 记忆加载配置指定确切的活跃修订头。取代或撤销会使旧加载配置失效，而不是静默替换为新内容。基于加载配置的原生执行从新鲜度验证到终端回执期间持有可移植仓库使用锁。
- 审查包冻结所显示的候选文本、来源、生成信息和证据前缀，而不将验证权限与提升权限合并。
- 原生 Codex 回执绑定确切的本地可执行文件字节、请求、JSONL、输出、用量和终端状态；它们不认证远程提供方、服务端模型或隐藏推理。
- 前瞻性研究在执行前封存每个请求、验收断言和工作区快照。在 Codex 启动前写入一次性研究预留；失败会消耗该预留，结果会重放完整的 Agent 消息字节。报告保持描述性而非因果性。
- 外部执行的三条件研究可以在同一个仅追加的本地证据账本中注册经过严格验证的、内容绑定的计划。注册仅保留来源信息；它不授予执行或结果权限。
- 原始证据备份是可选的，使用 age 加密，并且与可读记忆仓库完全分离。
- 未经独立的、绑定目标的批准，绝不更改 AGENTS.md、Skills 和其他规则表面。

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

安装

该项目可以使用 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 从不做出
其中任何一个决策。quickstart 提供了完整的
PowerShell 和 POSIX 命令，用于审查、提升、私有 Git 导出、精确
检索，以及切换到现有的 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 上的转录、历史、伴随、思考和未知块夹具 |
| OpenCode 插件 | 固定版本的 OpenCode 运行时在 GitHub 托管的运行器上启动，加载插件，捕获匹配的 session.created 事件，导入它，并验证账本；不使用任何提供商模型或密钥 |
| DeepSeek Harness Bundle | 真实的 Cordis、SessionStore、JSONL Persistence 和 agent/pre-step 组合测试覆盖逐字回填、崩溃安全的实时捕获、已验证记忆注入、真实 CLI 导入和干净卸载；这是社区 Bundle 证据，而非 DeepSeek 认证 |
| 审查与记忆生命周期 | 证据绑定的调用方证明、提升、取代、撤销、密钥扫描和冲突测试；调用方身份未经认证 |
| 跨设备记忆 | 私有 Git 历史验证、离线使用、分歧处理、恢复，以及托管的 Windows/macOS/Linux 测试 |
| 原生 Codex 记忆诊断 | 一个冻结的 20 簇合成套件运行了 20 个配对的经认证 codex exec 任务，采用密封的无工具策略并验证检索注入：19 胜、1 平、0 负；基线 1/20，记忆 20/20；单侧符号检验 p=0.0000019073。这是有界的能力证据，而非纵向认证；参见聚合回执 |
| 原生 Codex 进程凭据 | 精确的本地 Codex 和运行器字节、请求、参数、原始 JSONL、用量、输出和终端状态会被重放；提供商、模型和私有推理不会被独立证明 |
| 可移植加载项 | 内容寻址的精确修订集、作用域、Agent 允许列表、预算、过期头拒绝和复合交付凭据 |
| 前瞻性研究 | 预密封请求和工作区快照、不可变的 Agent 消息接受哈希、确定性平衡分配、一次性的研究绑定尝试，以及重放派生的结果；不作出已完成的真实世界纵向有效性声明 |
| 学习有效性 | 冻结语料库指标和重放已实现；除非任务执行被独立验证，否则有效性认证仍被阻止 |

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

该探测检查可执行文件可用性和版本输出。它不声称账户已认证、提供商运行了模型，或原生会话已被捕获。参见兼容性和证据级别。

记忆生命周期

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

只有当前的、未被撤销的头可以被检索。两个根、一个父级的两个子级、被更改的历史文件，或相互对立的活跃记忆都会使验证失败。参见提升和可移植记忆。

检索

检索是确定性的且离线进行。它结合了精确身份查找、Unicode 单词和 CJK 二元组匹配、作用域特异性、证据强度和稳定的平局打破规则。没有零匹配回退。

直接使用 CLI，或通过本地 stdio MCP 服务器暴露相同的已验证搜索：
text
agentmem recall search --root  --repo  --agent codex --query "release checks"
agentmem serve mcp --root  --repo  --agent codex

Codex、Claude Code、OpenCode 和 DeepSeek Harness 使用相同的可移植协议。它们的原生钩子、插件或 Bundle 是可选的；CLI 和 MCP 仍是稳定的边界。DeepSeek Harness 社区 Bundle 记录在 integrations/deepseek-harness 下。

操作记忆

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

在提升之前构建一个不可变的审查界面：
text
agentmem review packet --root  --status review_ready --limit 20
agentmem promote candidate --root  --candidate  \
--packet  --approver local-user \
--reason "Approved after reviewing the bound packet."

从版本化请求运行并重放本地 Codex 进程：
text
agentmem agent run codex --root  --file  \
--codex
agentmem agent verify --root

本地仪表板仅公开验证摘要：
text
agentmem serve dashboard --root  --repo

参见 loadouts、native execution、
prospective study registration and longitudinal studies，以及
dashboard。

存储边界

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

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

该项目不声称的内容

- 它不捕获提供商隐藏的私有思维链。
- 它不将摘要视为缺失的原始推理。
- 它不会自动提升模型编写的声明。
- 它不会静默合并语义冲突。
- 它不会仅因为检索运行了就证明检索改善了工作。
- 它不会将描述性纵向关联转变为因果性或
由提供商独立认证的效力。
- 未经明确批准，它不会修改 Agent 规则或安装钩子。

仓库地图

- cmd/agentmem：跨平台 CLI
- 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：精确 loadouts、
有界查询和交付回执
- internal/reviewpacket：不可变候选审查界面
- internal/agentbridge：可重放验证的本地 Codex 进程证据
- internal/study：前瞻性分配、观察和描述性报告
- internal/dashboard：仅限回环的只读操作摘要
- internal/codexbench：密封的原生 Codex 基线/记忆诊断
- internal/evaluation：冻结语料库、配对试验、指标和重放
- internal/backup、internal/diagnostics：加密恢复与完整性
- schemas：带版本的公共 JSON 契约
- docs/adr：架构决策与威胁边界

详细的协议文档位于 docs 下。请从
产品契约、威胁模型
和验证指南开始。

开发
text
go test ./...
go vet ./...
go build ./cmd/agentmem

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

在更改适配器、schema 或证据边界之前，请参阅
CONTRIBUTING.md。切勿将真实转录或原始证据附加到 issue 中。

许可证

MIT。请参阅 LICENSE。