一、项目定位与设计目标

verifiable-memory-mcp 是一个面向 AI 智能体（agent）的 MCP（Model Context Protocol）服务器，专注于解决智能体长期记忆中的完整性（integrity）问题。其核心定位非常克制：只解决一个狭窄但关键的问题——内存完整性（memory integrity），而不试图取代向量数据库、语义记忆系统或企业级审计平台 资料来源：README.md。

README 明确说明该项目的核心承诺是：智能体在执行动作前会先校验所依赖的记忆是否被篡改；若记忆状态在已批准流程之外被更改，智能体会主动停止，并生成可移植的证据 资料来源：index.html。整个项目遵循"local-first"原则，可以离线运行，无需后端信任依赖，这一特性在产品首页被反复强调 资料来源：index.html。

项目不是什么

为避免误解，README 显式列出了该项目的边界：

• 不是向量数据库（vector database）
• 不是语义记忆系统（semantic memory system）
• 不是长上下文推理引擎（long-context reasoning engine）
• 不是企业审计平台
• 也不是完整的智能体治理框架

它专注于一个狭窄属性：memory integrity，这一聚焦也体现在沙盒设计中 资料来源：sandbox/index.html。

二、核心机制：哈希链式追加记忆

项目的技术核心是 追加式（append-only）+ 哈希链（hash-chained） 的内存结构。每条记忆条目都会生成两类哈希，将内容、时间戳与链上位置绑定在一起 资料来源：README.md：

contentHash = sha256(content)
entryHash   = sha256({ contentHash, prevHash, createdAt })

• contentHash 用于校验存储内容本身是否被修改；
• prevHash 将当前条目链接到前一条目；
• entryHash 校验整条记录在链上下文中的完整性。

chain.ts 中的 validateChain 函数按链顺序对每条记录执行三重校验：重新计算 contentHash 与 entryHash，并比对 prevHash 是否等于上一条的 entryHash；任一环节失败即返回 {valid: false, checked, failedAt} 资料来源：src/tools/chain.ts:1-30。这意味着：

• 直接编辑某条记录 → contentHash 不匹配；
• 插入、删除或重排记录 → 链断裂。

三、MCP 工具集与证据格式

项目通过 src/index.ts 注册了 6 个 MCP 工具，完整覆盖了"写入—查询—校验—导出"的全链路：

资料来源：src/index.ts。

证据（evidence）是该项目的核心交付物，格式为可移植的 .eco 包（JSON envelope）。每个 .eco 文件包含：bundleText（导出时刻的精确 bundle）、anchor.bundleHash（SHA-256 哈希）、manifest（智能体、周期、决策、记忆状态、失败条目、时间戳）以及 report（人类可读说明） 资料来源：README.md。

flowchart LR
    A[加载 brief<br/>载入起始状态] --> B[运行智能体<br/>读取状态并执行]
    B --> C{记忆完整性<br/>校验}
    C -- 通过 --> D[生成证据<br/>导出 .eco 包]
    C -- 失败 --> E[停止并导出<br/>事件证据]
    D --> F[浏览器校验<br/>verifier/index.html]
    E --> F

该流程在 sandbox/index.html 与 demo/dashboard.html 中均以受控、可复现的方式呈现：先进行 IDLE / EXECUTE 等正常周期，再注入 prompt-injection 警告，最后通过 demo:tamper 触发链断裂，使智能体输出 STOP_BY_INTEGRITY 决策 资料来源：sandbox/index.html。

四、独立校验器与本地复现

为了让任何第三方都能在不信任后端的情况下验证证据，项目自带一个纯静态、纯客户端的验证器 verifier/index.html。其验证逻辑是 src/tools/chain.ts 的精确副本，可逐项重算 contentHash、entryHash、prevHash，并在提供外部 anchor 时比对完整文件的 SHA-256 资料来源：verifier/README.md。

校验器产出三种判定：INTACT（绿）、ALTERED（红）、或因文件不可读/anchor 格式错误导致的中性错误——特别注意，当提供有效 anchor 时，anchor 比对会取代结构校验决定最终裁决，这可以发现"内部一致但被整体重写"的情况 资料来源：verifier/index.html。

社区最新发布锚点为 Anchor 20260613T050846Z，对应 sha256(bundle.json) = 62db7d731117434c4893713584abaaaa3541a1f0bae702a34475af66a08c437c。本地复现流程如下 资料来源：README.md sandbox/index.html：

npm install -g verifiable-memory-mcp
npm run demo:scenario:reset
npm run demo:cycle
npm run demo:tamper
npm run demo:cycle-after-tamper
npm run demo:export
npm run demo:verifier

执行后，证据包会写入 demo/evidence/ 目录（如 000_IDLE.eco、001_EXECUTE.eco、003_WAIT_FOR_OWNER.eco、005_STOP_BY_INTEGRITY.eco、latest.eco），用户可加载到独立验证器中确认 资料来源：README.md。

概述

verifiable-memory-mcp 是一个本地优先（local-first）的 MCP（Model Context Protocol）服务器，对外暴露 6 个 MCP 工具，让 AI 代理以"先校验、再行动"的方式使用持久化记忆。记忆以仅追加（append-only）的哈希链形式存储：每条记录都带有时间戳，并通过 SHA-256 与上一条记录链接，从而支持独立审计与可移植证据的导出。v0.1.2 已发布到 npm，运行时不需要联网。

资料来源：README.md、package.json

服务器入口在 src/index.ts 中通过 MCP SDK 注册所有工具，并为每个工具同时声明了 JSON 输入模式（inputSchema）与 MCP 操作注解（annotations），包括 readOnlyHint、destructiveHint、idempotentHint 与 openWorldHint。这些注解使客户端能够在不阅读源码的前提下区分读写与破坏性操作。

资料来源：src/index.ts

工具清单

资料来源：src/index.ts、README.md

各工具详解

写入：`remember`

remember 接收 content 字符串与可选的 tags 数组，在内部生成 content 的 SHA-256 摘要得到 contentHash，再以规范 JSON {contentHash, prevHash, createdAt} 计算 entryHash，并将上一条记录的 entryHash 作为本条的 prevHash 完成链式连接。该工具被标注为 readOnlyHint: false、destructiveHint: false、idempotentHint: false、openWorldHint: false：只追加、不破坏既有数据、但每次写入都是新条目（不可幂等）。

资料来源：src/index.ts

检索：`recall`

recall 接收 query 字符串与可选的 limit（默认 20），返回匹配的记忆条目。其注解为 readOnlyHint: true、idempotentHint: true、openWorldHint: false，意味着重复执行结果一致、不会触发副作用，也不会访问本地浏览器之外的世界。

资料来源：src/index.ts

单条校验：`verify`

verify 接收 id，在内存中重新计算该条目的 contentHash 与 entryHash，并检查其 prevHash 是否等于前一条记录的 entryHash。这是"先校验、再行动"流程的关键入口：代理在依赖某条记忆之前调用它，一旦哈希失配即应停止执行。

资料来源：src/index.ts、verifier/README.md

全链审计：`chain`

chain 返回完整哈希链的可审计视图，逐条重算 contentHash、规范 JSON 的 entryHash 并校验链向链接，任一环节不符即返回 valid: false 与 failedAt：

for (let i = 0; i < entries.length; i++) {
  const entry = entries[i];
  const recomputedContentHash = hashContent(entry.content);
  if (recomputedContentHash !== entry.contentHash) {
    return { valid: false, checked: i + 1, failedAt: entry.id };
  }
  const canonical = buildEntryCanonical(entry.contentHash, entry.prevHash, entry.createdAt);
  ...
}

资料来源：src/tools/chain.ts

时间线与导出

timeline 按时间顺序列出记忆，并支持按标签过滤，便于人工审查与回溯。export 则把整条链打包为可移植的 verifiable-memory-bundle JSON，可被 verifier/index.html 在浏览器中离线重算校验，从而产生不依赖原始系统的独立证据。

资料来源：src/index.ts、verifier/README.md

集成方式

全局安装

npm install -g verifiable-memory-mcp

需要 Node.js 18 或更高版本。package.json 中 bin.verifiable-memory-mcp 指向编译产物 dist/index.js，scripts.start 即 node dist/index.js；开发模式下可使用 npm run dev（tsx src/index.ts）直接运行 TypeScript 源码。

资料来源：package.json、README.md

MCP 客户端配置

{
  "mcpServers": {
    "verifiable-memory-mcp": {
      "command": "npx",
      "args": ["-y", "verifiable-memory-mcp"]
    }
  }
}

直接 JSON-RPC 调用

在没有 MCP 客户端时，也可通过 printf 向 npx verifiable-memory-mcp 注入 initialize 与 notifications/initialized 等 JSON-RPC 消息进行协议级探测与集成测试。

资料来源：README.md

公共锚点

社区最近发布的 Anchor 为 20260613T050846Z，对应 bundle.json 的 SHA-256 为 62db7d731117434c4893713584abaaaa3541a1f0bae702a34475af66a08c437c。在使用 export 工具公开证据时，可用此锚点判断整包是否被改写——这也是 verifier/index.html 中"可选 anchor 对照"模式的依据。

资料来源：verifier/README.md

See Also

• README.md — 项目总览与示例
• verifier/README.md — 独立浏览器验证器
• src/index.ts — MCP 工具注册与 JSON Schema 定义
• package.json — 入口、脚本与依赖

概述

verifiable-memory-mcp 项目的核心承诺是"代理可验证的内存"（memory your AI agents can verify）。证据包（.eco）与独立验证器是这一承诺的落点：代理的内存状态以可移植、可重复校验的方式被导出，并在不信任原系统的前提下完成二次验证。

证据包本质上是"事件的离线快照"：包含某次决策周期所依赖的内存内容、内存状态以及决策报告；验证器则是一个纯浏览器、单文件、零依赖的静态 HTML 页面，使用 WebCrypto 在本地重新计算哈希并比对锚点（anchor）。

社区最近一次公开锚点为 Anchor 20260613T050846Z，对应 sha256(bundle.json) = 62db7d731117434c4893713584abaaaa3541a1f0bae702a34475af66a08c437c。该值可作为独立验证 .eco 包中 anchor.bundleHash 字段的外部参考。

证据包结构：`.eco` 格式

每个 .eco 文件是一个 JSON 证据信封，导出位置在 demo/evidence/。README.md 明确指出其由四部分组成：

典型文件命名直接表达决策阶段，例如 000_IDLE.eco、001_EXECUTE.eco、003_WAIT_FOR_OWNER.eco、005_STOP_BY_INTEGRITY.eco，以及指向最近一次的 latest.eco。这种命名策略使得任意第三方在拿到包后即可在不了解 MCP 客户端的情况下理解上下文。

验证器工作原理

静态验证器位于 verifier/index.html，其核心逻辑在 <script id="vmcp-core"> 中以纯函数形式实现，完全复刻 src/hashing.ts 与 src/tools/chain.ts 中的链校验算法，因此服务端与浏览器侧结论一致（verifier/README.md:1-15）。

校验步骤按顺序执行：

1. contentHash = sha256(content)
2. canonical   = JSON.stringify({ contentHash, prevHash, createdAt })
3. entryHash   = sha256(canonical)
4. prevHash    === entries[i-1].entryHash
5. (可选) sha256(file bytes) === anchor.bundleHash

根据 verifier/index.html 中的 verifyBundle()，任何一步失败都会返回 failure.check 字段，类别涵盖 parse / format / structure / content / entry / link / anchor / anchor_invalid 八种。这避免了"含糊的红绿判定"——例如若用户输入了语法错误的锚点字符串，结果为中性错误而非误报为"被篡改"（verifier/index.html: anchor_invalid 分支）。

判定结果：

• INTACT（绿）：所有条目哈希与链链接均通过；如提供锚点则 anchor = match。
• ALTERED（红）：在 content / entry / link / anchor 任一检查失败。
• 错误（中性）：文件不可读或锚点格式无效，除非锚点比较本身可决断。

flowchart LR
    A[加载 .eco / bundle] --> B{解析 JSON}
    B -->|失败| X[错误: parse]
    B --> C[逐条校验]
    C --> D{contentHash<br/>一致?}
    D -->|否| Y[ALTERED: content]
    D --> E{entryHash<br/>一致?}
    E -->|否| Y2[ALTERED: entry]
    E --> F{prevHash<br/>链接正确?}
    F -->|否| Y3[ALTERED: link]
    F --> G{锚点哈希<br/>匹配?}
    G -->|不匹配| Y4[ALTERED: anchor]
    G -->|匹配/未提供| Z[INTACT]

本地使用流程

package.json 暴露了完整的端到端脚本链路，使用者可以在本地复现从内存写入、篡改、停止到导出并验证的全过程（package.json: scripts）：

npm run demo:scenario:reset   # 初始化演示内存
npm run demo:cycle            # 干净周期
npm run demo:tamper           # 模拟越权篡改
npm run demo:cycle-after-tamper  # 触发 STOP_BY_INTEGRITY
npm run demo:export           # 生成 .eco 包到 demo/evidence/
npm run demo:verifier         # 启动独立验证器

或者直接打开 verifier/index.html，通过 ?bundle=<url>、?anchor=<sha256hex> 查询参数，或文件选择器加载包（verifier/README.md: Usage）。UI 支持 ES/EN 切换，加载后即完全离线工作，不向任何外部服务发送数据。

已知限制与安全边界

README.md 的"Security / threat model"段落明确指出该项目不提供的能力：

• 不做加密（SQLite 以明文存储）；
• 不做访问控制（任何有文件系统权限者可读）；
• 不上云（无外部服务调用）；
• 不抗整机失陷（攻击者若完全控制机器则不保证安全）。

因此，证据包与验证器的价值在于事后可审计性与跨环境可重复校验，而非运行时防御。这一点对集成方选型尤为关键：它适合作为"完整性层"叠加在已有治理流程之上，而非替代审计或权限系统。

参见

• README.md：可用工具与威胁模型
• src/tools/chain.ts：链校验实现
• verifier/README.md：独立验证器说明
• 项目主页：生态与定位

概述

本页面向希望本地复现并运维 verifiable-memory-mcp 演示流程的开发者，涵盖仓库自带的 demo 脚本序列、.eco 证据包结构、浏览器独立验证器，以及需要关注的失败模式与运维边界。整个演示的设计目标在 README.md 中被表述为 "a public, concrete demonstration that agent memory can be append-only, inspectable, and tamper-evident through MCP"，强调"完整性先于动作"的可复现性，而非自由形式的实时搜索。sandbox/index.html 中明确写到沙箱 "is controlled by design … here to demonstrate integrity-before-action clearly, repeatably, and independently verifiably"。

标准演示步骤

sandbox/index.html 与 README.md 共同给出了一条可复现脚本链，用于在本地走完"加载 → 执行 → 篡改 → 停机 → 导出 → 验证"的完整故事：

npm install -g verifiable-memory-mcp
npm run demo:scenario:reset
npm run demo:cycle
npm run demo:tamper
npm run demo:cycle-after-tamper
npm run demo:export
npm run demo:verifier

各步骤的角色如下（综合 sandbox/index.html 与 README.md 描述）：

• demo:scenario:reset：清理本地 SQLite 数据库，建立受控起始状态。
• demo:cycle：驱动智能体在一个执行周期内调用 src/index.ts 暴露的六个 MCP 工具（remember、recall、verify、chain、timeline、export）。
• demo:tamper：在带外（out-of-band）修改 SQLite 中的某条记忆，模拟攻击或意外写入。
• demo:cycle-after-tamper：再次运行周期，链断裂应触发 STOP_BY_INTEGRITY 决策。
• demo:export：写出 verifiable-memory-bundle 与对应 .eco 证据包。
• demo:verifier：在终端打印用于打开浏览器验证器的 URL（也可直接打开 demo/evidence/latest.eco）。

ECO 证据包结构与生命周期

README.md 描述了 .eco 包的核心字段：bundleText（导出时刻的完整 bundle）、anchor.bundleHash（该 bundle 的 SHA-256）、manifest（agent / cycle / decision / memory status / failed entry / timestamp）、report（人类可读解释）。sandbox/index.html 列出了 demo/evidence/ 下典型产物及对应决策：

sandbox/index.html 在 "003_WAIT_FOR_OWNER" 场景中演示了 prompt injection 警告与 owner gate 流程；在 "005_STOP_BY_INTEGRITY" 场景中演示 out-of-band 篡改后智能体主动停机。verifier/sample-bundle.json 中的样本条目（如 mem_b91c9c02）则展示了 contentHash / prevHash / entryHash 三字段的规范连接方式（verifier/sample-bundle.json）。

验证器与本地运维

verifier/README.md 与 verifier/index.html 描述了独立静态验证器：完全在浏览器内运行，无后端、无构建、无外部依赖，加载后可离线使用。验证算法是 src/tools/chain.ts 中 validateChain 的逐字复刻，按链顺序执行：

1. 重新计算 contentHash = SHA-256(content)；
2. 重新计算 entryHash = SHA-256({contentHash, prevHash, createdAt})（规范化 JSON 序列化，键序固定）；
3. 比对 prevHash 与前一条 entryHash 是否相等；
4. 若提供 anchor，则再比对 bundle 文件字节的 SHA-256 与锚点。

verifier/index.html 中 verifyBundle 返回的 verdict 取值为 "green" | "red" | "error"；anchor 取值为 "not_provided" | "match" | "mismatch" | "invalid"（注意 "invalid" 表示锚点字符串本身不合规，并非完整性判定）。failure.check 枚举为 parse | format | structure | content | entry | link | anchor | anchor_invalid。运维上须注意：必须通过 https:// 或 http://localhost 提供页面（WebCrypto 要求安全上下文），并支持 ?bundle=<url> 与 ?anchor=<sha256hex> 查询参数。

社区最新发布记录为 Anchor 20260613T050846Z，对应 bundle.json 的锚点哈希为 62db7d731117434c4893713584abaaaa3541a1f0bae702a34475af66a08c437c。运维时可通过验证器 anchor 输入框或 ?anchor=62db7d73… 查询参数核对该锚点，专门用于发现"内部自洽但被整体重写"的 bundle。

失败模式与运维注意事项

README.md 明确划定了威胁模型边界：verify() 检测 entry 内容被改，chain() 检测链接断裂、删除与重排；但同时声明 不做加密（SQLite 明文存储）、不做访问控制、不做云端转发、非硬化审计设备——若攻击者完全控制宿主机，本工具无法保证安全。verifier/README.md 进一步强调："tamper-evident ≠ content truthfulness"——.eco 证据只证明"记忆曾是什么"，不证明"内容是否真实"。运维上应将这一边界写入演练剧本，避免把"完整性通过"误读为"内容正确"。

See Also

• README.md — 顶层定位、可用工具与威胁模型
• verifier/README.md — 浏览器验证器详细说明
• sandbox/index.html — 公共交互沙箱
• src/index.ts — MCP server 与六个工具实现
• src/tools/chain.ts — 链验证核心算法
• 社区最新锚点：Anchor 20260613T050846Z，sha256 = 62db7d731117434c4893713584abaaaa3541a1f0bae702a34475af66a08c437c

Pitfall Log / 踩坑日志

项目：TemporalDynamics/verifiable-memory-mcp

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

1. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/TemporalDynamics/verifiable-memory-mcp | README/documentation is current enough for a first validation pass.

2. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/TemporalDynamics/verifiable-memory-mcp | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/TemporalDynamics/verifiable-memory-mcp | no_demo; severity=medium

4. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/TemporalDynamics/verifiable-memory-mcp | no_demo; severity=medium

5. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/TemporalDynamics/verifiable-memory-mcp | issue_or_pr_quality=unknown

6. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/TemporalDynamics/verifiable-memory-mcp | release_recency=unknown