内容
# 可验证记忆 - MCP 服务器
**本地优先、仅追加、抗篡改的 AI 代理内存。**
`可验证记忆 - MCP 服务器` 是一个用于存储代理内存的 MCP 服务器，作为可验证的哈希链。
每个条目都是不可变的、带有时间戳的、通过密码学与前一条目链接的，并且可以作为可移植的证据导出。
本仓库是一个 **公开的、专注的实现**，用于实现一个理念：代理内存不仅应该是有用的，还应该是可检查的和抗篡改的。
它不是一个完整的代理操作系统、完整的内存架构或完整的治理层。它是一个狭窄的、实用的构建块，清晰地展示了一种特定的能力。
## 为什么存在
AI 代理会随着时间的推移积累内存：
- 决策、
- 操作员注释、
- 提醒、
- 约束、
- 上下文、
- 以及历史记录。
在大多数系统中，内存都是针对检索进行优化的，而不是针对完整性。
文件会被编辑。上下文会漂移。记录会被覆盖。解释会在事后产生。
本项目采取了不同的角度：
**在询问代理是否记得好的时候，先询问其内存是否可被检查。**
## 功能
该服务器为兼容 MCP 的客户端提供了一个本地内存存储，具有：
- 仅追加写入、
- 每个条目的哈希、
- 链完整性验证、
- 按时间顺序检查、
- 可移植导出、
- 基于浏览器的证据记录验证器。
结果很简单：
您可以稍后验证代理“记住”的内容是否与最初存储的内容相同。
## 不是什么
这 **不是**:
- 向量数据库、
- 语义内存系统、
- 长上下文推理引擎、
- 企业审计平台、
- 或完整的代理治理框架。
它不试图解决所有问题。
它专注于一个狭窄的属性：
**内存完整性。**
## 核心思想
每个内存条目都会创建哈希值，绑定内容、时间戳和链中的位置。
```text
contentHash = sha256(content)
entryHash = sha256({ contentHash, prevHash, createdAt })
```
- `contentHash` 检查存储的内容本身
- `prevHash` 将条目链接到前一条目
- `entryHash` 检查上下文中整个记录的完整性
如果有人直接编辑条目，则内容哈希值不再匹配。
如果有人插入、删除或重新排序条目，则链条会断裂。
## 可用工具
| 工具 | 描述 |
|---|---|
| `remember` | 存储新的内存条目（仅追加、哈希链） |
| `recall` | 按文本内容搜索内存 |
| `verify` | 重新计算哈希值并确认条目未被修改 |
| `chain` | 验证整个链条并检测断裂或重新排序 |
| `timeline` | 按时间顺序列出内存，可选按标签过滤 |
| `export` | 导出可移植的、可验证的证据记录 |
## 证据包和验证器
主要的证据工件是可移植的 `.eco` 包。验证器链接或二维码只是打开该包的一种快捷方式。
每个 `.eco` 文件都是一个 JSON 证据信封，包含：
- `bundleText`: 准确导出的证据记录（内部为 `verifiable-memory-bundle`），
- `anchor.bundleHash`: 证据哈希，即该记录的 SHA-256 哈希，
- `manifest`: 代理、周期、决策、内存状态、失败条目和时间戳，
- `report`: 发生情况的人类可读解释。
演示将包写入：
```text
demo/evidence/
```
示例：
```text
000_IDLE.eco
001_EXECUTE.eco
003_WAIT_FOR_OWNER.eco
005_STOP_BY_INTEGRITY.eco
latest.eco
```
该仓库还包含一个静态验证器，位于：
```text
verifier/index.html
```
它在浏览器中验证 `.eco` 包、`.ecox` 重放包和导出的证据记录文件。检查条目内容哈希、条目哈希、链链接和可选的 SHA-256 锚点，以确保导出的文件准确无误。严格模式允许审查者将证据记录和 ECO 收据作为单独的文件加载并验证它们是否匹配。
对于本地演示：
```bash
npm run demo:export
npm run demo:publish-local
```
然后打开由 `demo:export` 打印的 `.eco` 验证器 URL，或加载：
```text
demo/evidence/latest.eco
```
还提供独立的验证器模式：
```bash
npm run demo:verifier
```
如果包在篡改之前导出，验证器应显示 `INTACT`。如果在直接 SQLite 篡改后导出，验证器应显示 `ALTERED`。
`demo:publish-local` 从单个本地源提供仪表盘、验证器和 `.eco` 文件。这使得此 URL 形状可用于二维码或同一网络上的其他设备：
```text
http://<your-local-ip>:4190/verifier/index.html?eco=/evidence/latest.eco
```
要共享公共验证器 URL，请在导出之前设置 `DEMO_PUBLIC_BASE_URL`：
```bash
export DEMO_PUBLIC_BASE_URL=https://demo.example.com
npm run demo:export
```
导出脚本将打印本地和公共验证器 URL。
**手机/外部设备验证** 需要 HTTPS 才能使用浏览器 Web Crypto API。对于裁判或投资者演示，请使用 HTTPS 域、隧道（ngrok、cloudflared）或将 `.eco` 文件拖放到底层验证器作为可靠的备用方案。
## 为什么选择 MCP
该项目是为模型上下文协议（MCP）设计的，以便内存完整性可以作为工具公开，而不是作为实现细节埋藏。
这很重要，因为它允许代理：
- 编写内存，
- 检查内存，
- 验证内存，
- 以及导出内存证据
通过与执行其他工作相同的工具接口。
## 示例
```text
Remember: The deployment strategy prioritizes Europe over Asia for Q3.
✓ remembered (mem_a1b2c3d4)
Recall deployment strategy
Found 1 entry
Verify mem_a1b2c3d4
✓ Entry is intact and chain-verified
```
## 安装
```bash
npm install -g verifiable-memory-mcp
```
需要 Node.js 18+。
## MCP 客户端配置
```json
{
"mcpServers": {
"verifiable-memory-mcp": {
"command": "npx",
"args": ["-y", "verifiable-memory-mcp"]
}
}
}
```
## 直接使用
```bash
npx verifiable-memory-mcp
```
使用 JSON-RPC 进行测试：
```bash
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"0.1"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"remember","arguments":{"content":"test decision","tags":["test"]}}}' \
| npx verifiable-memory-mcp
```
## MCP 检验
```bash
npx -y @modelcontextprotocol/inspector npx -y verifiable-memory-mcp
```
## 工具示例
**remember**
```json
{
"content": "The deployment targets Europe for Q3",
"tags": ["strategy", "deployment"]
}
```
**recall**
```json
{
"query": "deployment"
}
```
**timeline**
```json
{
"includeContent": true
}
```
**verify**
```json
{
"id": "mem_a1b2c3d4"
}
```
**chain**
```json
{}
```
**export**
```json
{}
```
## 存储
数据存储在本地：
```text
~/.verifiable-memory-mcp/memory.db
```
SQLite，WAL 模式。无云。无遥测。无登录。
覆盖数据目录：
```bash
VMCP_DATA_DIR=/tmp/vmcp-demo npx -y verifiable-memory-mcp
```
## 演示流程
端到端演示默认仅限沙盒：
```bash
npm run demo:e2e
```
这使用 `/tmp/vmcp-agent-demo` 并且永远不会导出 `~/.verifiable-memory-mcp`，除非您明确选择在其他地方进行。
对于逐步记录流程：
```bash
export VMCP_DATA_DIR=/tmp/transparent-agent-demo
npm run demo:scenario:reset
npm run demo:cycle
npm run demo:owner-update
npm run demo:cycle
npm run demo:prompt-injection
npm run demo:cycle
npm run demo:owner-approve
npm run demo:cycle
npm run demo:tamper
npm run demo:cycle-after-tamper
npm run demo:export
npm run demo:publish-local
```
## Telegram 演示控制
演示也可以通过 Telegram 机器人控制。它只接受一组固定的演示命令，并运行与终端流程相同的本地脚本。
所需环境：
```bash
export TELEGRAM_BOT_TOKEN=...
export TELEGRAM_CHAT_ID=...
export VMCP_DATA_DIR=/tmp/transparent-agent-demo
export DEMO_PUBLIC_BASE_URL=http://<your-local-ip>:4190
npm run demo:telegram
```
可用机器人命令：
```text
/ready
/cycle
/owner_update
/prompt_injection
/approve
/reject
/tamper
/export
/eco
/status
/help
```
## 搜索行为
`recall` 目前使用基于文本的检索，而不是嵌入。
这是此版本的刻意选择。
本项目不竞争于语义召回质量。它竞争于内存是否可以稍后被检查和导出以供验证。
如果您跨语言工作，双语条目或双语标签会提高召回质量。
## 比较
| 特性 | 向量数据库 | 典型的内存层 | 可验证记忆 - MCP 服务器 |
|---|---|---|---|
| 主要目标 | 检索 | 便利 | 完整性 |
| 搜索 | 语义 | 混合 | 文本 |
| 仅追加 | 通常不 | 有时 | **是** |
| 链验证 | 否 | 很少 | **是** |
| 本地优先 | 有时 | 有时 | **是** |
| MCP 原生 | 变化 | 变化 | **是** |
## 更广泛的证据生态系统的一部分
这个公共完整性层是一个聚焦的构建块，位于一个更广泛的架构中，用于治理 AI、可移植证据和独立验证。
这些不是独立的产品声明。它们是同一个底层需求出现在不同地方的不同方式：关于信息的声明只有在可以针对其来源的记录进行检查时才值得信赖，而不仅仅是凭信仰。VMMCP 和 Talo 将此应用于代理的内存。EcoSign 和 CustodyArt 将此应用于文档和创意资产。WITH/WIT 将此应用于个人内存 - 答案链接回支持它们的记录。
## 应用的工作流证明
在沙盒之外，该模式正在一个完整的招聘应用程序工作流中得到验证：在采取行动之前验证内存，暂停所有者批准，并在完整性失败时停止。将录制演示视频并在此发布。
录制视频将显示外部候选人文档、所有者批准、证据生成和在实际操作流程中的完整性失败行为。在发布之前，上述沙盒仍然是直接评估模式的复制方式。
### [AppCrew](https://github.com/TemporalDynamics/AppCrew)
用于治理 AI 代理的可观察运行时。
AppCrew 是围绕代理执行的重用运行时层：运行状态、时间线、批准门和证据钩。VMMCP 是可以附加的完整性层，当必须在采取行动之前验证内存时。
### 应用的招聘工作流
垂直验证招聘代理。
相同的控制模式正在一个真实的招聘工作流中得到验证：外部候选人文档、批准门、证据轨迹和完整性失败处理。演示视频将发布在此；在此之前，公共沙盒是直接评估模式的方式。
### [可移植 ECO 验证](https://temporaldynamics.github.io/verifiable-memory-mcp/verifier/)
ECO 证据工件的独立验证。
目标是可移植性：证据应该在原始系统之外重新检查，以便在工作流、设备和操作员之间验证。
### [EcoSign](https://github.com/TemporalDynamics/ecosign-public)
用于数字文档的证据和验证工作流。
EcoSign 将证据优先的方法应用于文档完整性、导出和独立验证在文档中心的工作流。
### CustodyArt
创意数字资产的溯源和保管。
CustodyArt 将托管和证据规范应用于艺术品和数字文化资产，其中溯源和可追溯性随时间推移很重要。
### WITH / WIT
确定性语义内存层。
WITH/WIT 将相同的证据优先原则应用于人类记忆：系统可以检索答案并显示支持它的记录。核心仍然是私有的；相关的公共界面是 [with-typing](https://github.com/TemporalDynamics/with-typing)。
## 安全 / 威胁模型
- **篡改检测**：`verify()` 检测到条目内容的更改。`chain()` 检测到链接断裂、删除和重新排序。
- **无加密**：SQLite 数据库存储为明文。
- **无访问控制**：任何具有文件系统访问权限的人都可以读取数据库。
- **无云**：服务器不会将数据发送到外部服务。
- **不是强化审计设备**：如果攻击者完全控制机器，此工具不保证安全。
本项目有助于检测内存更改。
它不保证系统抵御入侵。
## 定位
理解此仓库的最好方式是：
**一个公开的、具体的演示，证明代理内存可以通过 MCP 实现仅追加、可检查和抗篡改。**
它故意比它指向的更广泛的架构问题更狭隘。
## 战略文档
- [透明代理证据](docs/strategy/transparent-agent-evidence.md)
- [ECO 和 ECOX 模型](docs/strategy/eco-and-ecox-model.md)
- [ECO 验证器通用模型](docs/strategy/eco-verifier-universal.md)
## 许可证
MIT
