agent-memory

agent-memory

面向 AI 编码 Agent 的本地 Git 原生项目记忆。调用一次 MCP，即可获得结构化记忆更新——当前任务状态、决策、约定、注意事项和各模块事实。支持分支感知。保护机密信息。保留原始字节。无云服务、无向量数据库——Markdown 是事实来源，Git 负责同步。提供 3 个 MCP 工具和完整的 CLI。

它的独特之处在于：记忆是提交到仓库中的纯 Markdown，因此你可以阅读并使用 git diff 查看差异；持久化变更会暂存以供人工审核（review --diff → apply），而不是悄无声息地写入；写入任何内容之前都会扫描并剔除机密信息和个人身份信息。请参阅 ROADMAP.md，了解项目的发展方向（系统级／多仓库记忆）。

演示

Agent 记录一项持久化决策；它会暂存以供审核；你可以查看准确的差异，将其应用，之后的 fetch 会呈现这项决策——本地、Git 原生、可审核且能保护机密信息。该演示可复现：docs/demo/demo.sh 是可运行的流程， docs/demo/demo.tape 则使用 vhs 生成 gif——详见 docs/demo/。

对比

能力	AGENTS.md / CLAUDE.md	厂商记忆（例如 Claude）	向量／数据库记忆（mem0、Zep）	agent-memory
纯文本、由 Git 版本管理的事实来源	✓ 扁平文件	✗ 厂商管理	✗ 数据库／云端	✓ 仓库中的 Markdown
结构化、按章节更新	✗	✗	~	✓
人工审核关卡（先查看差异）	✗ 可自由编辑	✗	✗	✓ 暂存 → review --diff → 应用
厂商中立（MCP — 支持任意 Agent）	~ 广泛约定	✗ 单一厂商	~ 各不相同	✓ Claude · Cursor · Codex · Gemini
写入时扫描机密信息／个人身份信息	✗	✗	~ 各不相同	✓
团队并发编辑合并	✗ 文本冲突	✗	✗	✓ 章节合并驱动程序
完全本地运行（无云服务）	✓	✗	~ 各不相同	✓
可验证任务协议（VTP-1）与机器回执	✗	✗	✗	✓ 5 阶段加密生命周期 + Clause B 不相交席位

以上是概括性描述，工具也在快速迭代——发现不准确之处？提交 issue，我会修正表格。agent-memory 可与 AGENTS.md／CLAUDE.md 这类指令文件互补（它甚至会安装其中一个）：这些文件说明如何行动；agent-memory 则提供背后的持久、可搜索、经审核的知识。

状态

Release 0.6.1 — Swarm Audit Hardening & Metamorphic Rebase 版本： 将持久化记忆与可验证的自主执行及严格的失败关闭安全不变量相结合：

• Astra Pro Audit Hardening (AM-001..AM-008) — 强制按类别路由审批（DecideRoutingWithCategory）， 全文件前置状态 CAS（proposal.PreHashes），在 Jaccard 去重中保留极性／否定限定词（criticalQualifiers）， 幂等且纯只读的 fetch_context，以及规范的三方合并删除语义。
• Metamorphic Rebase & Drift Detection (internal/memory/rebase.go) — 在变基期间检测全文件前置哈希漂移， 防止并发编辑相邻分区时发生静默覆盖，并通过变形组合测试进行验证。
• 控制平面清单隔离 — 强制对 .agent-memory/meta/manifest.yaml 实施失败关闭保护，防止直接修改、符号链接绕过或路径遍历攻击。
• RFC 8785 (JCS) 确定性 (internal/vtp) — 严格遵循 JSON 规范化方案， 通过全部 26 个官方 RFC 8785 附录 B 测试向量，支持 ECMAScript 浮点数格式（1e+21）， 拒绝孤立代理项，并进行递归 UTF-8 验证。
• 失败关闭的跨进程 SQLite NonceStore (internal/memory/nonce.go) — 持久化的仓库范围存储， 使用 withDB 模式消除 Windows 文件描述符锁， 提供零漂移的原子验证，并自动清理过期 nonce。
• 两阶段暂存与复合回滚 (internal/memory/staging.go) — 严格的路径遍历清理 （ValidateStagingID、agentfs.ValidateMemoryPath）、符号链接包含检查，以及 原子多文件回滚；部分失败时报告 RollbackIncomplete 复合错误。
• VTP-1 严格断言标识与双预言机结算 (internal/vtp) — 必须提供可识别且与声明的断言 ID 匹配的 AssertionResults，验证器密钥绑定验证，以及 Workpool/0 Clause B 不相交席位强制执行。

此版本基于 0.6.0（防止装饰性内容的 SAR-008 接地 nonce、SAR-007 字节保留）、0.5.4（VTP-1 初始协议引擎）、0.5.0（联邦、引用式景观存储）和 0.4（分区合并驱动）。

完整变更列表请参阅 CHANGELOG.md。

文档	用途
ROADMAP.md	项目发展方向、原则和非目标。
CHANGELOG.md	各版本的功能列表和已知限制。
Design Doc v0.4.1	此二进制文件所实现的规范设计。
Implementation Plan	历史 MVP 构建日志（M0–M8）；后续计划请参阅 ROADMAP。
Retrieval eval	fetch 的离线召回率／MRR／nDCG 基准测试（方法和数据）。
Patterns	按子系统记录的可复用设计模式。
Spikes	M1 前的技术预研结果（字节保留引擎、MCP SDK、flock、FTS5）。

快速开始

安装 — 下载预构建二进制文件（推荐）：从最新版本下载适用于你的操作系统/架构的压缩包，解压后将 agent-memory 放入 PATH。无需工具链。

# npx (no Go, no manual download): fetches the verified release binary on
# first run and caches it — also usable straight from an MCP client config.
npx -y @xchucx/agent-memory --help

# Go toolchain alternative (Go 1.25+)
go install github.com/xChuCx/agent-memory/cmd/agent-memory@latest

# from source
go build -o agent-memory ./cmd/agent-memory

Homebrew、Scoop 和 winget 安装包正在计划中。agent-memory 也已列入 MCP Registry。

然后，在你希望赋予记忆能力的仓库中：

# Scaffold .agent-memory/ in a repo
agent-memory init --name my-project

# Install the Claude Code skill + register the project MCP server
# (writes .claude/skills/agent-memory/SKILL.md and merges .mcp.json)
agent-memory install claude

# Verify (prints the release tag, the go-install version, or dev+vcs locally)
agent-memory version

# Read context
agent-memory fetch                # bootstrap pack
agent-memory fetch "auth"         # FTS query

# Start MCP server (your agent spawns this automatically once configured)
agent-memory mcp

install claude 会为你注册 MCP 服务：它会在仓库根目录合并一个项目级 .mcp.json，运行 agent-memory mcp --root ${CLAUDE_PROJECT_DIR:-.}。 Claude Code 会在启动时将 CLAUDE_PROJECT_DIR 展开为该仓库，因此服务始终服务于这个仓库——此配置可在不同克隆间移植，并且（根据 Claude Code 的作用域优先级：本地 > 项目 > 用户）会覆盖任何意外设置的用户级服务。提交 .mcp.json，让团队成员共用它。

⚠️ 不要注册一个根目录写死的单一用户级服务（claude mcp add -s user agent-memory -- agent-memory mcp --root /some/repo）： 它会通过同一个仓库为所有项目提供服务，因此你在项目 B 中写入的记忆会悄无声息地落入项目 A。按项目注册（install 写入的方式）才是正确做法；agent-memory doctor 会标记根目录配置错误的注册项。

服务会依次从 --root、$CLAUDE_PROJECT_DIR，然后是工作目录解析仓库。其他运行时（Cursor、Gemini CLI，以及任何读取 AGENTS.md 的工具）使用同一服务——安装对应的适配器即可（见下文）。

在现有项目中采用

init 会搭建空白记忆。要从实际代码库中填充记忆，让你的编码 Agent 来分析——这正是此工具的核心用途。完成 init + install <adapter> 并注册 MCP 服务（如上所述）后，重启 Agent，以便加载 memory.* 工具，然后粘贴下面的提示词。

执行过程：Agent 会读取仓库并调用 memory.propose_update。 工作笔记和易错点会立即生效；持久类别（约定、决策、模块）会暂存以供你审核——使用 agent-memory review --diff 检查每一项，再用 agent-memory apply 应用（或用 reject 拒绝）。未经你批准，不会写入任何持久内容。

You now have agent-memory MCP tools (memory.fetch_context,
memory.propose_update, memory.status) backed by this repository's
.agent-memory/ store. Bootstrap the project's memory from the codebase.

1. Call memory.fetch_context with an empty query to see the current
   (mostly empty) state and the conventions/decisions/pitfalls/modules
   layout.

2. Analyze THIS repository — read the build files, CI config, entry
   points, and the main packages/modules. Identify:
   - build / test / run / lint commands and the toolchain;
   - conventions: code style, branching, commit rules, review practices;
   - architecture: the major modules/components and what each is for;
   - durable decisions: notable choices and WHY (only ones that are real
     and stable — not speculation);
   - pitfalls: footguns, sharp edges, "don't do X because Y" you can infer
     from the code, tests, or docs.

3. Persist what you found via memory.propose_update, choosing the intent
   per kind:
   - update_conventions  → conventions.md (build/test/style/workflow)
   - refresh_module      → modules/<name>.md (one per major component)
   - record_decision     → decisions.md (Date / Status / Confidence +
                           sources; type ∈ file|test|user, NOT external)
   - add_pitfall         → pitfalls.md
   - update_shared       → local/current.shared.md (a short "current
                           state / where things stand" summary)

Rules:
- Cite provenance: pass sources as file references you actually read
  (e.g. {"type":"file","ref":"internal/auth/session.go"}). Use
  confidence=confirmed for facts from code, inferred for deductions.
- Every section needs a unique "" anchor; keep entries
  concise — this is working knowledge, not a wiki. Decisions need
  **Date**, **Status** (active|superseded|deprecated|proposed), and
  **Confidence** fields.
- NEVER put secrets, tokens, or credentials in memory (the server will
  reject them anyway).
- Work in a few focused passes (conventions + architecture first, then
  modules, then decisions/pitfalls). Report what you proposed and what
  staged for review.

手边没有 MCP 服务？Agent（或你）也可以改用 CLI——使用相同的验证、密钥扫描和路由流程：

agent-memory propose --intent update_conventions --op append_section \
  --path conventions.md --heading "Build & test" --heading-level 2 \
  --source file:Makefile --confidence confirmed \
  --content-file - <<'MD'
## Build & test

Run `go build ./...` and `go test ./...`. ...
MD
# add --apply to land it immediately (you are the reviewer);
# or omit it and review the staged proposal with `review --diff` + `apply`.

构建

需要 Go 1.25+（MCP SDK 会间接要求此版本）。

go build -o agent-memory ./cmd/agent-memory   # binary
go test ./...                                  # unit + integration tests
go test -tags=e2e ./internal/e2e/...           # end-to-end smoke (linux/macos)
go test -race ./internal/...                   # race detector

make 目标与上面的 go 命令等效；如果你更喜欢这种方式，请参阅 Makefile。

CLI

agent-memory init [--root DIR] [--name NAME] [--force]
        # Create the .agent-memory/ scaffold.

agent-memory status [--root DIR] [--json]
        # Project state: version, file counts per category, lock metadata.

agent-memory doctor [--root DIR]
        # Diagnostic layout checks. Advisory; exits 0 even with findings.

agent-memory digest [--root DIR] [--verify SHA256] [--json]
        # Compute or verify deterministic SHA-256 Merkle root of active memory.
        # CRLF-normalized; cryptographic receipt for VTP-1 or swarm audit.

agent-memory fetch [QUERY] [--scope X,Y] [--budget N]
                   [--exclude-archive] [--json] [--root DIR]
        # Return a budgeted Markdown context pack.

agent-memory mcp [--root DIR]
        # Start the MCP server (stdio). Exposes memory.fetch_context and
        # memory.propose_update.

agent-memory propose --intent INTENT --op OP --path PATH [op flags...]
                     [--content STR | --content-file FILE|-] [--source type:ref]
                     [--confidence C] [--apply] [--from-json FILE|-] [--json]
        # Create a proposal WITHOUT an MCP server, through the same
        # validate / secret-scan / route pipeline. --from-json takes a full
        # multi-op ProposeRequest; --apply immediately lands a result that
        # would otherwise stage (you are the reviewer).

agent-memory review [STAGING_ID] [--diff] [--show] [--json] [--root DIR]
        # List staged proposals or inspect one. --diff shows a unified diff
        # of each staged file vs the current on-disk version.

agent-memory apply STAGING_ID [--json] [--root DIR]
        # Re-validate drift and apply a staged proposal.

agent-memory reject STAGING_ID [--json] [--root DIR]
        # Discard a staged proposal.

agent-memory rebase STAGING_ID [--force] [--json] [--root DIR]
        # Re-plan a staged proposal against the current disk state
        # after target_drift. --force is required for soft drifts
        # (acknowledges accepting the new base as planning input).

# review / apply / reject / rebase accept a full STAGING_ID, any unique
# prefix (Git-style), or --latest for the most recently staged proposal:
#   agent-memory apply 20260527       # unique prefix
#   agent-memory apply --latest       # newest staged proposal

agent-memory install <adapter> [--user-global] [--force] [--json]
        # Materialise agent-runtime adapter assets.
        # Supported: claude, cursor, agents, gemini.

agent-memory merge-driver --install [--root DIR]
        # Register the section-aware git merge driver so a team's concurrent
        # edits to .agent-memory/ files union by @id instead of conflicting.
        # Run once per clone. (git invokes the bare `merge-driver %O %A %B %P`
        # form itself during a merge.)

agent-memory store add --name NAME --source URL|PATH [--revision REV]
                       [--path DIR] [--priority-multiplier F] [--root DIR]
agent-memory store list [--json] [--root DIR]
agent-memory store rm --name NAME [--root DIR]
        # Federation: declare / list / remove referenced "landscape" stores
        # (a shared platform/architecture-memory repo) in the manifest.

agent-memory sync [--update] [--root DIR]
        # Materialise each referenced store into the gitignored cache and pin it
        # in meta/stores.lock (committed). --update moves a pin forward.

agent-memory rebuild-index [--root DIR] [--clobber] [--no-assign-ids] [--json]
        # Recreate the FTS5 shadow index from canonical Markdown files.
        # Use for SQLite corruption, schema changes, or after manual .md edits.

agent-memory sweep [--root DIR] [--ttl DURATION] [--dry-run] [--json]
        # Remove staged proposals past the manifest's staging.ttl_seconds.
        # Each removal also writes a ttl_expired entry to meta/rejection-log.jsonl.

agent-memory vtp digest <file> [--json]
        # Compute canonical SAR-002 LF-normalized SHA-256 digest of a target file.

agent-memory vtp verify --receipt FILE [--spec FILE] [--stdout FILE]
                        [--diff FILE] [--exit-code N] [--verifier ID]
                        [--disjoint] [--json]
        # Verify a TaskReceipt execution proof against stdout/diff digests, exit code,
        # and enforce Workpool/0 Clause B (disjoint seat isolation).

agent-memory vtp settle --verify FILE [--spec FILE] --payer ID --payee ID
                        --seq N [--json]
        # Emit a canonical TaskSettle artifact from a passed verification, enforcing
        # that Clause B disjoint verification was satisfied.

agent-memory version
        # Print binary version and exit.

MCP 工具

由 agent-memory mcp 通过 stdio JSON-RPC 暴露：

工具	用途
memory.fetch_context	读取有预算限制的 Markdown 上下文包。
memory.propose_update	提交结构化编辑（应用或暂存）。
memory.status	报告记忆健康状况：文件数量、已暂存的提案（及偏差）、安全/git/锁定状态。

联邦记忆（全景存储库）

仓库的 .agent-memory/ 只了解自身。联邦机制让它能够引用共享的只读“全景”存储库，将架构知识库、平台架构或同级服务记忆直接接入 Agent 的主动推理循环。

这与引入静态 Wiki 有本质区别：

• **零浪费工程（同级方案发现）：**Agent 无需从零重新发明复杂的分布式机制（例如事务发件箱、分布式限流、2PC/Sagas），而是查询联邦存储库，了解同级服务已有的解决方案，包括设计理由（decisions.md）和已知的生产环境陷阱（pitfalls.md）。
• **超越公共 API 的上下文：**API（OpenAPI、gRPC）声明结构语法，却隐藏了运行时机制：数据库隔离级别、锁竞争模式、去重窗口和背压行为。联邦记忆会揭示这些隐藏的运行边界。
• **安全地跨服务提交 PR：**当 Agent 必须修改上游或相邻服务时，联邦记忆会提供本地约定和不变量，帮助它提出安全且不造成破坏的贡献。

使用 arch-wiki 快速入门

连接公开、权威的架构 Wiki（https://github.com/xChuCx/arch-wiki — 涵盖 L1–L4 四层分类体系的 165 篇生产级技术文章）：

# 1. Declare the landscape store (edits .agent-memory/meta/manifest.yaml)
agent-memory store add --name arch-wiki --source https://github.com/xChuCx/arch-wiki

# 2. Fetch, sandbox-validate, scan for secrets/PII, and pin commit into meta/stores.lock
agent-memory sync

# 3. Rebuild local shadow index with federated content
agent-memory rebuild-index

# 4. Fetch budgeted, high-density context pack with exact full-article pointers
agent-memory fetch "Debezium Transactional Outbox"

返回的数据包实现了双层检索——低 Token 的不变量数据包，并按需提供指向完整 50 页深度文章的指针：

## АНТИ-ПАТТЕРН: Это гарантированно сломается
**Executive Summary:** TL;DR: Change Data Capture (CDC) — это единственный надежный способ превратить базу данных (State) в поток событий (Stream)...
- **Full Article Access:** [L2.DB.14 Change Data Capture (CDC), Debezium, log‑based replication.md](file:///.../4Layers/L2.System Design & Architecture/L2.DB/L2.DB.14 Change Data Capture (CDC), Debezium, log‑based replication.md)
- **Repository Path:** `4Layers/L2.System Design & Architecture/L2.DB/L2.DB.14 Change Data Capture (CDC), Debezium, log‑based replication.md`

主要保证：

• **各存储库公平排序 + 固定优先级。**每个存储库都会提供自己的热门候选项；只有已固定到提交、且记录在锁文件中的存储库才会参与混合。平局时本地内容优先于全景内容（priority_multiplier，默认值为 0.8）。
• **来源追踪 + 信任边界。**每个全景内容块都会标注其存储库和提交，并明确包裹在“证据，而非指令”的边界内。
• **可选启用。**未声明存储库时，行为与单仓库路径逐字节一致。

联邦命名空间治理与并发屏障（SAR-010 和 SAR-010.1）

在不同仓库和异构文件系统（Windows 上的 NTFS、macOS 上的 APFS、Linux 上的 ext4）之间合并知识时，简单的标识符匹配会导致静默覆盖和缓存投毒。agent-memory 强制执行正式的加密屏障：

1. Unicode 规范化契约（SAR-010）： 标识符和搜索键通过完整的 Unicode Case Folding（FullCasefold(NFC(Trim(s)))）进行规范化。部署前，agent-memory doctor 会自动检查记忆键，并标记潜在的跨平台大小写冲突。
2. 本地解析覆盖（meta/store_overrides.yaml）： 当上游发生冲突或架构分歧时，本地所有者可显式定义路由覆盖项（local_alias、exclude），而不修改上游源：

   version: 1
   overrides:
     - store: "arch-wiki"
       upstream_commit: "9dda4b6f2544"
       key: "STRASSE"
       local_alias: "strasse-arch"
       approved_by: "steward-artemy"
       assigned_steward: "agent-stanislavsky"
       escalation_deadline: "2026-10-01T00:00:00Z"
   

3. 读回一致性与治理准入门槛： 如果覆盖项针对的是最终一致性存储（readback_consistency: eventual），则会被严格拒绝准入。准入会在产生任何网络或磁盘副作用前失败关闭，以防根据过期的锁定视图进行验证。此外，incident_id、assigned_steward 和有效的 RFC3339 escalation_deadline 均为强制必填项，以消除责任分散。
4. 防 TOCTOU 双重并发屏障（协作进程模型）：
   • 内核级 OS 建议锁（internal/lock）： 独占的跨进程文件锁会串行化写入操作（agent-memory sync、apply）。与此同时，读取方（agent-memory fetch）在存储解析和上下文包组装期间持有共享 OS 读锁（AcquireShared），以消除目录交换（SwapDir）期间的撕裂读取或交错操作。
   • 无条件锁文件 CAS 摘要验证（VerifyStoresLockCAS）： 在验证时捕获 meta/stores.lock 的 SHA-256 摘要，并在写入前立即进行验证（即使该文件最初不存在），以防止协作参与方之间出现并发检查/使用竞态和交错创建。
   • 契约边界： 对于所有遵循锁定协议的协作进程，这种双重屏障可保证严格可串行化：持有建议锁可串行化执行窗口，而摘要验证会检测验证前发生的更改。此保证明确不涵盖绕过 OS 建议锁的非协作外部写入方。
5. 读集写偏斜验证（ReadSections CAS）： 暂存提案会捕获提案生成期间读取的所有分区的哈希值（proposal.ReadSections）。agent-memory rebase 和 agent-memory apply 都会在应用变更前验证读集分区是否发生偏移，以防止并发会话更新相互依赖的记忆分区时出现静默写偏斜异常。
6. 类型化治理事件回执（ProvenanceAlert）： 对隔离的冲突或过期偏移，会生成机器可读的回执，记录 incident_id、assigned_steward、escalation_deadline 和上游提交 SHA，以防止责任分散。

模式：federation-stores.md、multi-store-fetch.md、sar-010-unicode-canonicalization-contract.md。

可验证任务协议（VTP-1）与群体共识

在多 Agent 集群中运行或执行经济任务的自主 AI Agent，不能依赖未经验证的自然语言声明（“我修复了 bug”“测试通过了”）。在开放网络中，对话式声明容易受到压缩遗忘、客套循环和对抗性框架的影响。

**VTP-1（可验证任务协议）**将任务执行转变为端到端、可由机器验证的 5 阶段加密生命周期：

警告

VTP-1 状态：实验性 / 正在加强安全性 虽然确定性摘要验证、断言检查和跨任务结算绑定已通过加密方式强制执行，但 Clause B 的不同席位验证目前依赖身份字符串不相等（worker != verifier != creator）。在没有外部 PKI 或经过证明的硬件身份的开放去中心化或经济环境中，目前不应将其用作对抗性信任边界。加密账户证明正在积极开发中。

[TASK-SPEC] ──> [TASK-CLAIM] ──> [TASK-RECEIPT] ──> [TASK-VERIFY] ──> [TASK-SETTLE]
 Creator         Worker           Worker             Independent      Dual-Oracle
 Bounty/Oracle   TTL/IdemKey      Stdout/Diff SHA    Disjoint Seat    Payout / Mint

阶段	结构	角色与机器不变量
阶段 1：SPEC	TaskSpec	声明式要求、预言机类型（execution@1、rule_kb@1）、目标仓库/提交和赏金。
阶段 2：CLAIM	TaskClaim	工作者质押幂等键和基于序列的 TTL，以防止并发竞态条件。
阶段 3：RECEIPT	TaskReceipt	确定性执行证明，记录经 CRLF 规范化（SAR-002）的 stdout、差异代码块和进程退出码的 SHA-256 摘要。
阶段 4：VERIFY	TaskVerify	独立评估，强制执行 Workpool/0 Clause B（is_disjoint_seat == true）：验证必须在隔离的机器/席位上执行（例如无密钥沙盒与存有机密的主机隔离）。
阶段 5：SETTLE	TaskSettle	与已验证回执引用绑定的确定性结算负载，用于账本铸造（例如 Grain 共识）或托管款释放。

跨平台行尾一致性（SAR-002）

Windows（CRLF）与 Linux/macOS（LF）上的 Git 检出可能会导致相同文本内容产生不同的哈希值。VTP-1 引擎会在计算 stdout、补丁代码块和内存 Merkle 叶子的 SHA-256 摘要前应用规范 LF 规范化（NormalizeLF），确保异构平台之间的字节级共识。

自主 Agent 的 CLI 工作流

# 1. Compute canonical normalized digest for an output log or diff patch
agent-memory vtp digest ./artifacts/stdout.log --json

# 2. Verify a worker's TaskReceipt against live execution output
agent-memory vtp verify --receipt receipt.json --spec spec.json \
                        --stdout stdout.log --diff patch.diff \
                        --verifier @orca-agent --disjoint --json > verify.json

# 3. Settle verified task into a settlement artifact (fails closed if Clause B violated)
agent-memory vtp settle --verify verify.json --spec spec.json \
                        --payer @creator --payee @worker --seq 14500 --json > settle.json

证据（实测）

三个层面，如实说明范围——检索 → 连续性 → 行为。 前两项具有确定性、不使用 LLM，并在 CI 中运行且带有回归保护； 语料、标签和方法均可在仓库中审查。

1 · 检索质量。 fetch 是否会返回正确的章节？在一个包含 28 个查询和 28 个章节的标注基准中，已发布的 match-any 检索在 98% 的查询中会将相关章节排入前 5 名——相比之前的 match-all 行为，召回率提升了 0.91。

配置	recall@5	hit@1	MRR
match-all (AND) — 之前	0.07	0.07	0.07
match-any (OR) — 已发布	0.98	0.96	0.97

→ 方法和注意事项：docs/eval/retrieval.md · go test -run TestRetrievalEval -v ./internal/eval/

2 · 跨会话连续性。 一个会话中记录的经验能否延续到下一个会话？通过真实的记录 → 持久化 → 检索循环，在启用 agent-memory 时，经验在 5 / 5 个场景中出现在下一个会话的上下文中；不启用时则为 0 / 5（失忆基线）。

→ docs/eval/continuity.md · go test -run TestMemoryContinuity -v ./internal/eval/

3 · 行为（任务成功率）。 Agent 是否会据此采取行动，从而减少重复犯错？这需要在循环中使用 LLM，因此它以可运行的 A/B 测试框架形式提供（“groundhog-day”，对比启用与未启用记忆），你可以使用自己的模型运行：eval/behavioural/。这里不公布数字——要干净地隔离未启用组并不容易（原版 Claude Code 自带的自动记忆会在多次运行之间泄漏；请参见测试框架 README）。按设计，它不在 CI 中运行。

Agent 运行时适配器

agent-memory install <adapter> 会在各运行时读取的位置生成一份完整的指令文件：

适配器	目标文件	备注
claude	.claude/skills/agent-memory/SKILL.md	Claude Code 技能格式。--user-global 会写入 ~/.claude/skills/。
cursor	.cursor/rules/agent-memory.mdc	使用基于描述的匹配规则的 Cursor MDC 规则。--user-global 会写入 ~/.cursor/rules/。
agents	AGENTS.md（仓库根目录）	广泛适用的行业惯例。OpenAI Codex CLI、Cursor 的 Agent 模式、Sourcegraph Cody 等均会读取。仅限项目本地。
gemini	GEMINI.md（仓库根目录）	Gemini CLI 的长期项目上下文。仅限项目本地。

每个文件都会教运行时何时调用 memory.fetch_context 和 memory.propose_update、意图词汇、来源规则以及调试拒绝原因。 四种适配器采用相同的行为模型；每种适配器只是将其封装为运行时的原生格式。

架构（概览）

.agent-memory/
├── meta/
│   ├── manifest.yaml      operational settings (budgets, approval, security)
│   ├── schema.yaml        per-category file/glob, section schema, provenance
│   ├── index.sqlite       FTS5 shadow index (regenerable)
│   ├── lock               OS-level advisory lock (flock)
│   └── lock.info          informational metadata sidecar
├── conventions.md         project conventions
├── decisions.md           durable architectural decisions
├── pitfalls.md            known footguns
├── index.md               server-managed memory index summary
├── modules/<name>.md      per-module facts
├── archive/<date>-*.md    write-once archived entries
├── local/
│   ├── current.shared.md  cross-branch working notes
│   └── current.<branch>.md branch-scoped working notes
├── sessions/<YYYY-MM-DD>.md per-day session logs
└── staging/<id>/          pending human-review proposals
    ├── proposal.json
    ├── target-checksums.json
    └── files/<rel-path>

目录结构

cmd/agent-memory/                       CLI and MCP binary entry point
internal/
  adapters/                             agent runtime adapters (Claude, Cursor, Codex, Gemini)
  bench/                                retrieval & FTS5 benchmark harness
  cli/                                  cobra subcommands (init, fetch, propose, digest, vtp, etc.)
  config/ schema/                       YAML loaders (manifest.yaml + schema.yaml)
  e2e/                                  release smoke test suite (-tags=e2e)
  eval/                                 offline retrieval and continuity benchmarks
  fs/                                   atomic file swap and path sanitization
  git/                                  branch resolution and repo inspection
  index/                                FTS5 incremental shadow index
  lock/                                 flock-based cross-process advisory lock
  logging/                              structured slog logging with level filtering
  markdown/                             byte-preserving section-level Markdown engine
  mcp/                                  stdio JSON-RPC 2.0 Model Context Protocol server
  memory/                               operations, staging pipeline, security scanner, Merkle tree
  vtp/                                  Verifiable Task Protocol (VTP-1) engine & Clause B verifier
spikes/                                 pre-M1 architectural spikes (S1-S4)
docs/
  patterns/                             reusable architecture patterns (SAR, Merkle, federation)
  eval/                                 retrieval and continuity benchmark methods and logs
  spikes/                               spike outcome write-ups
.github/workflows/                      CI & CD release workflows (goreleaser)
agent-memory-design-doc-v0.4.1.md       canonical design specification
agent-memory-implementation-plan.md     MVP and federation build log
CHANGELOG.md                            per-release feature list and upgrade notes

发布

通过 goreleaser 由标签驱动。推送 v* 标签会触发 .github/workflows/release.yml， 该工作流会构建二进制文件矩阵，并发布附带归档文件的 GitHub Release。

每次发布的矩阵：

• linux_amd64、linux_arm64
• darwin_amd64、darwin_arm64
• windows_amd64、windows_arm64

每个归档文件都包含 agent-memory 二进制文件、README.md 和 CHANGELOG.md。同级的 agent-memory_<version>_checksums.txt 文件提供 SHA-256 哈希值。

# Verify a downloaded archive
sha256sum -c agent-memory_0.2.0_checksums.txt

在本地试运行发布流水线（需要安装 goreleaser）：

goreleaser check                       # parse + validate .goreleaser.yml
goreleaser release --snapshot --clean  # full build with no upload

源码构建始终将版本标识为 dev：

$ go build -o agent-memory ./cmd/agent-memory
$ ./agent-memory version
dev

通过 goreleaser 进行发布构建时，会通过 -ldflags='-X .../cli.ProgramVersion=v0.X.Y' 写入实际标签。

许可证

Apache License 2.0。你可以根据其条款使用、修改和分发本软件；该许可证包含明确的专利授权。贡献内容也须遵循相同许可证（参见 CONTRIBUTING.md）。