内容
# 代理收据
**您的 AI 代理记住一切 — 而且您可以证明。**
AI 代理的持久记忆，由加密收据支持。您的代理学习的每个事实都经过签名、可追溯和独立验证。不需要云服务。
[](https://agent-receipts-web.vercel.app/)
[](https://agent-receipts-web.vercel.app/walkthrough)
[](https://www.npmjs.com/package/@agent-receipts/mcp-server)
[](./LICENSE)
[试用交互式演示](https://agent-receipts-web.vercel.app/walkthrough) · [30 秒安装](#开始使用) · [它的不同之处](#它的不同之处)
---
## 问题
您正在使用 AI 代理构建。Claude Code 重构您的身份验证模块并表示“完成，所有测试通过”。您的代理生成客户报价并表示已应用正确的定价。您的助手记住您上周的偏好 — 但您无法看到它为什么这么认为或是否正确。
三个问题存在：
1. **代理在会话之间忘记一切。** 每次对话都从零开始。上下文丢失。您需要重新解释相同的事情。
2. **当代理记住时，您无法看到内部。** 平台内存是一个黑盒。您无法看到它存储了什么，何时存储或为什么存储。您无法纠正它，导出它或验证它。
3. **没有证据证明代理实际执行了什么。** 日志是可变的。代理写入自己的日志。“我更新了 3 个文件，所有测试通过” — 它真的做了吗？您正在相信代理对自己工作的描述。
## 代理收据的作用
### 实际工作的记忆
您的代理在会话之间获得结构化、持久的记忆 — 人员、项目、工具、偏好、事实。不是一个简单的键值存储。是一个实体-观察图，每个事实都链接到创建它的对话。
```bash
# 您的代理学习了一些东西
memory_observe → "用户偏好 TypeScript，使用 Neovim，正在构建一个名为 ModQuote 的 SaaS"
# 下一次会话，它已经知道
memory_context → 加载所有内容：实体、观察、关系、偏好
# 您可以搜索它
memory_recall → "用户偏好的技术栈是什么？" → 结构化结果
# 您可以忘记（并且忘记本身会被跟踪）
memory_forget → 软删除，带有审计跟踪
```
代理自动处理这些事情，当您添加 [系统提示](#2-添加系统提示) 时。您不需要手动管理内存。
### 真正的证明
每个记忆观察和每个代理操作都会产生一个**收据** — 一个带有以下内容的签名 JSON 文档：
- **Ed25519 签名** — 防篡改，独立验证
- **输入/输出哈希** — 证明确切的输入和输出（原始数据从未存储）
- **时间戳** — 何时发生，何时完成
- **代理 ID** — 哪个代理执行了它
- **来源链** — 跟踪任何记忆到创建它的对话
这不是日志记录。日志是可变的文本文件，代理会写入关于自己的内容。收据是第三方可以验证的加密证明，无需信任您、您的服务器或代理。
### 一切都在本地运行
```bash
npx @agent-receipts/mcp-server
```
就是这样。没有 API 密钥。没有账户。没有云服务。没有月度费用。没有数据离开您的机器。`~/.agent-receipts/` 中的 SQLite 数据库。离线工作。
## 为什么存在
我正在构建 [ModQuote](https://modquote.io) — 一个多租户 SaaS，AI 代理为汽车保护商店生成报价。真金白银，真实客户，真实责任。
当 Claude 生成一个 2400 美元的 PPF 报价时，我需要答案：它接收了什么车辆数据？它应用了哪些定价规则？如果客户对价格提出异议，我能否证明发生了什么 — 不是通过代理写入的日志条目，而是通过加密证明？
我查看了现有的工具：
- **Mem0** — 优秀的记忆，但没有证据。它记得事情，但无法证明何时或为什么记住它们。记忆是可变的。
- **Langfuse** — 优秀的可观察性，但它是跟踪，而不是证据。日志是您系统内部的，第三方无法验证。
- **Zep** — 时间知识图，但托管且不透明。
没有一个能回答：**“向系统外的某人证明这个特定代理使用特定输入在特定时间采取了特定操作。”**
所以我构建了代理收据。现在每个报价生成都是一个签名的收据。每个记忆都有一个来源链。当有人询问“代理如何得出这个数字？” — 我会给他们一个收据，他们可以自己验证。
## 它的不同之处
| | 代理收据 | Mem0 | Langfuse | Zep |
|---|---|---|---|---|
| **记忆** | 签名的实体-观察图 | 智能提取 + 合并 | 无记忆 | 时间知识图 |
| **证据** | Ed25519 签名的收据 | 无 | 可变轨迹 | 无 |
| **验证** | 离线，由任何人，无需服务器 | 无 | 无 | 无 |
| **基础设施** | `npx` 即可使用。零配置。 | 需要 LLM 进行提取 | 云或自托管 | 云 API |
| **成本** | 永久免费（本地） | 免费层，然后付费 | 免费层，然后付费 | 付费 |
| **导出** | 可移植的具有加密验证的捆绑包 | 导出可用 | API 导出 | 无 |
| **审计跟踪** | 不变的收据链 | 可变 | 可变日志 | 可变 |
**代理收据不是这些工具的更好版本。它是不同的东西。**
Mem0 回答：*“我的代理记住了什么？”*
Langfuse 回答：*“我的 LLM 管道中发生了什么？”*
代理收据回答：*“你能证明吗？”*
## 开始使用
### 1. 添加 MCP 服务器
**Claude Code：**
```bash
claude mcp add agent-receipts -- npx @agent-receipts/mcp-server
```
**Claude Desktop** (`claude_desktop_config.json`) / **Cursor** (`.cursor/mcp.json`):
```json
{
"mcpServers": {
"agent-receipts": {
"command": "npx",
"args": ["@agent-receipts/mcp-server"]
}
}
}
```
### 2. 添加系统提示
这告诉您的代理何时观察记忆、回忆上下文和跟踪操作 — 所以它自动工作：
```bash
npx @agent-receipts/cli prompts claude-code
```
将输出复制到您的项目说明或系统提示中。
### 3. 开始使用
您的代理现在将：
- 在会话开始时调用 `memory_context` 加载它对您的了解
- 在学习值得记住的内容时调用 `memory_observe`
- 在执行重要操作时调用 `track_action`
- 使用 Ed25519 签署所有内容
### 4. 查看正在发生的事情
```bash
npx @agent-receipts/dashboard # 网页界面在 localhost:3274
npx @agent-receipts/cli stats # 终端概述
npx @agent-receipts/cli memory entities # 查看代理记住的内容
```
### 5. 在安装前试用
[运行交互式演示 →](https://agent-receipts-web.vercel.app/walkthrough) — 60 秒体验记忆、验证和捆绑导出。无需安装。
## 内部
- **24 个 MCP 工具** — 记忆、操作、验证、约束、判断、发票、捆绑包
- **21 个 SDK 方法** — 完整的 TypeScript API
- **14 个 CLI 命令 + 9 个记忆子命令** — 以终端为中心
- **18 个仪表盘页面** — 收据、记忆图、链、代理、约束、判断、发票
- **492 个测试** — 零 TypeScript `any`，零 ESLint 警告
- **Ed25519 + SHA-256** — via `@noble/ed25519`（已审核，纯 JS）
- **SQLite + FTS5** — 本地优先，支持全文记忆搜索
## 可移植的记忆捆绑包
导出代理的整个记忆为一个可验证的文件：
```bash
npx @agent-receipts/cli memory export > my-project.bundle.json
```
捆绑包包括每个实体、观察、关系、创建它们的收据和用于验证的公钥。将其交给另一个代理、另一个团队或另一个代理收据实例 — 他们可以无需信任您即可验证每个事实。
## 链接
| | |
|---|---|
| [交互式演示](https://agent-receipts-web.vercel.app/walkthrough) | 在浏览器中试用 — 60 秒 |
| [实时仪表盘](https://agent-receipts-web.vercel.app) | 查看具有示例数据的完整仪表盘 |
| [工作原理](https://agent-receipts-web.vercel.app/how-it-works) | 收据解剖、记忆模型、ModQuote 故事 |
| [npm](https://www.npmjs.com/org/agent-receipts) | 所有 6 个包 |
<details>
<summary><strong>完整的 SDK API 参考（21 个方法）</strong></summary>
### 操作跟踪
- `ar.track(params)` — 使用自动哈希跟踪完成的操作
- `ar.start(params)` — 创建一个待处理收据
- `ar.complete(receiptId, params)` — 完成一个待处理收据
- `ar.verify(receiptId)` — 验证收据的 Ed25519 签名
- `ar.get(receiptId)` — 按 ID 获取收据
- `ar.list(filter?)` — 列出收据并过滤和分页
- `ar.getPublicKey()` — 获取签名公钥
- `ar.getJudgments(receiptId)` — 获取收据的判断
- `ar.cleanup()` — 删除过期的收据
- `ar.generateInvoice(options)` — 从收据中生成发票
### 记忆
- `ar.context(params?)` — 获取会话初始化的完整记忆上下文转储
- `ar.observe(params)` — 存储记忆观察（始终记录）
- `ar.recall(params?)` — 搜索记忆（默认为静默，`audited: true` 记录）
- `ar.forget(params)` — 软删除观察或实体（始终记录）
- `ar.entities(filters?)` — 列出实体
- `ar.relate(params)` — 创建实体关系
- `ar.provenance(observationId)` — 获取观察的来源链
- `ar.memoryAudit(params?)` — 记忆审计报告
### 捆绑包
- `ar.exportBundle(params?)` — 导出可移植的、具有验证性的记忆捆绑包
- `ar.importBundle(bundle, params?)` — 导入和验证记忆捆绑包
### 别名
- `ar.emit(params)` — `track()` 的别名
</details>
<details>
<summary><strong>完整的 MCP 工具参考（24 个工具）</strong></summary>
| 工具 | 描述 | 关键参数 |
|------|-------------|---------------|
| `track_action` | 使用自动哈希跟踪代理操作 | `action`, `input`, `output`, `constraints` |
| `create_receipt` | 使用预计算的哈希创建收据 | `action`, `input_hash`, `output_hash` |
| `complete_receipt` | 使用结果完成待处理的收据 | `receipt_id`, `output`, `status` |
| `verify_receipt` | 验证加密签名 | `receipt_id` |
| `get_receipt` | 按 ID 检索收据 | `receipt_id` |
| `list_receipts` | 列出带有过滤的收据 | `agent_id`, `status`, `chain_id` |
| `get_chain` | 获取链中的所有收据 | `chain_id` |
| `get_public_key` | 导出 Ed25519 公钥 | — |
| `judge_receipt` | 启动 AI 判断评估 | `receipt_id`, `rubric` |
| `complete_judgment` | 完成待处理的判断 | `receipt_id`, `verdict`, `score` |
| `get_judgments` | 获取收据的所有判断 | `receipt_id` |
| `cleanup` | 删除过期的收据 | `dry_run`, `cleanup_memory` |
| `generate_invoice` | 从收据中生成发票 | `from`, `to`, `format` |
| `get_started` | 入门指南 | — |
| `memory_context` | 会话初始化的完整上下文转储 | `scope`, `max_entities` |
| `memory_observe` | 存储记忆观察 | `entity_name`, `entity_type`, `content` |
| `memory_recall` | 搜索存储的记忆 | `query`, `entity_type`, `scope` |
| `memory_forget` | 软删除观察或实体 | `entity_id` 或 `observation_id` |
| `memory_entities` | 列出已知实体 | `entity_type`, `scope`, `query` |
| `memory_relate` | 创建实体关系 | `from_entity_id`, `to_entity_id`, `type` |
| `memory_provenance` | 观察的来源链 | `observation_id` |
| `memory_audit` | 记忆操作审计报告 | `agent_id`, `from`, `to` |
| `memory_export_bundle` | 导出可移植的记忆捆绑包 | `entity_ids`, `include_receipts` |
| `memory_import_bundle` | 导入和验证记忆捆绑包 | `bundle`, `skip_existing` |
</details>
<details>
<summary><strong>完整的 CLI 参考</strong></summary>
| 命令 | 描述 |
|---------|-------------|
| `init` | 创建数据目录并生成签名密钥 |
| `keys [--export] [--import]` | 显示、导出或导入签名密钥 |
| `inspect <id\|file>` | 漂亮地打印收据 |
| `verify <id\|file> [--key]` | 验证收据签名 |
| `list [--agent] [--status] [--json]` | 列出带有过滤器的收据 |
| `chain <chain_id> [--tree]` | 显示收据链 |
| `judgments <id> [--json]` | 列出收据的判断 |
| `cleanup [--dry-run]` | 删除过期的收据 |
| `stats` | 收据聚合统计 |
| `export <id\|--all> [--pretty]` | 导出收据为 JSON |
| `invoice --from --to [--format]` | 生成发票 |
| `seed [--demo] [--count] [--clean]` | 种子演示数据 |
| `watch [--agent] [--action]` | 监视新的收据 |
| `prompts <client>` | 设置指南（claude-code, cursor, system） |
| `memory context` | 记忆上下文摘要 |
| `memory observe <name> <type> <content>` | 存储观察 |
| `memory recall [query]` | 搜索记忆 |
| `memory entities [--type]` | 列出实体 |
| `memory forget <id>` | 忘记观察或实体 |
| `memory audit` | 记忆审计报告 |
| `memory provenance <obs_id>` | 来源链 |
| `memory export` | 导出记忆为 JSON |
| `memory import <file>` | 导入记忆 |
</details>
<details>
<summary><strong>配置</strong></summary>
| 环境变量 | 描述 | 默认值 |
|---------------------|-------------|---------|
| `AGENT_RECEIPTS_DATA_DIR` | 数据目录路径 | `~/.agent-receipts` |
| `AGENT_RECEIPTS_AGENT_ID` | 默认代理 ID | `local-agent` |
| `AGENT_RECEIPTS_ORG_ID` | 组织 ID | `local-org` |
| `AGENT_RECEIPTS_ENVIRONMENT` | 环境标签 | `production` |
| `RECEIPT_SIGNING_PRIVATE_KEY` | Ed25519 私钥（十六进制） | 自动生成 |
**存储：**
```
~/.agent-receipts/
├── keys/
│ ├── private.key # Ed25519 私钥（模式 0600）
│ └── public.key # Ed25519 公钥
├── receipts.db # SQLite 数据库（收据 + 记忆）
└── config.json # 代理和组织配置
```
</details>
## 软件包
| 软件包 | 描述 |
|---------|-------------|
| [`@agent-receipts/schema`](packages/schema) | Zod 模式和 TypeScript 类型 |
| [`@agent-receipts/crypto`](packages/crypto) | Ed25519 签名、验证、密钥管理 |
| [`@agent-receipts/mcp-server`](packages/mcp-server) | 带有 24 个工具的 MCP 服务器 |
| [`@agent-receipts/sdk`](packages/sdk) | TypeScript SDK（21 个方法） |
| [`@agent-receipts/cli`](packages/cli) | 命令行界面 |
| [`@agent-receipts/dashboard`](packages/dashboard) | 任务控制网页界面 |
## 路线图
- [ ] **云层** — 团队仪表盘、多代理内存同步、跨组织验证
- [ ] **语义回忆** — 基于嵌入的记忆搜索
- [ ] **框架适配器** — LangChain、CrewAI、AutoGen 集成
- [ ] **跨组织信任桥梁** — 两个组织验证对方的代理收据
## 许可证
MIT
---
由 [Amin Suleiman](https://webaes.com) 构建 — 构建 [ModQuote](https://modquote.io) 和 [Agent Receipts](https://github.com/webaesbyamin/agent-receipts)。
