sdk

MnemoPay

为执行重大操作的 AI Agent 提供治理层。 由章程驱动的任务范围、带人工介入审批的策略执行、FiscalGate 预算管控、符合《欧盟 AI 法案》第 12 条要求的审计包、Agent 声誉评分（300-850），以及可防篡改的 MerkleAudit 链——无论操作是资金转移还是基础设施变更。

MnemoPay 位于支付轨道（Stripe、Paystack、Lightning、Stripe MPP、x402、Google AP2）之上，并位于 Agent 运行时（LangChain、CrewAI、Claude Agent SDK 或你自己的循环）之下。支付轨道转移资金。运行时做出决策。MnemoPay 声明规则、执行预算并生成证据。

支付只是重大操作的一种。同一套章程、策略、审批和审计流程也适用于运维工具——无论这一步是完成一笔付款还是让一个节点瘫痪，这些原语都一视同仁。

npm install @mnemopay/sdk

初次使用？ 从 docs/QUICKSTART.md 开始——60 秒、三个步骤，即可运行代码。

文档： 快速入门 · 架构 · 权限 · 操作账本 · 集成（OpenAI/Anthropic/Gemini/Cohere/Mistral/LangGraph） · Recall · FiscalGate · 审计包（《欧盟 AI 法案》第 12 条） · 子路径导入规则 · Claude Agent SDK 指南 · 打包工具：Vite · Webpack · Bun

社区： LICENSE（Apache 2.0） · CHANGELOG · CONTRIBUTING · CODE_OF_CONDUCT · SECURITY · 讨论 · 适合新手的议题

凭证： 信任中心（实体、KYB、Apple Team ID、第 12 条审计链——5 分钟内即可验证） · 基准测试（100 万次操作、100% 对抗性检测、账本差异为 0 美元） · PyPI 上的 Python SDK（自 1.1.0 起与 TS 支付轨道完全一致）

import MnemoPay, {
  Charter, FiscalGate, MerkleAudit,        // governance primitives
  AgentReputationScoring, BehavioralEngine, // trust + reputation
  StripeRail, X402Rail, GoogleAP2Rail,      // rails
} from "@mnemopay/sdk";

const agent = MnemoPay.quick("my-agent");

await agent.remember("User prefers monthly billing");
const tx = await agent.charge(25, "Monthly API access");   // FiscalGate hold
await agent.settle(tx.id);                                  // FiscalGate capture

// Agent Reputation Score — portable, 300-850 range. NOT FICO-brand, NOT a consumer
// credit report, NOT governed by FCRA. Scores agents (software), not humans.
const scorer = new AgentReputationScoring();
const result = scorer.compute({ transactions: [tx], createdAt: new Date(), /* ... */ });
// → { score: 672, rating: "good", feeRate: 0.015, trustLevel: "standard" }

14 个模块。哈希链式账本。章程 / FiscalGate / 第 12 条审计包。6 条支付轨道。经过 20 万次操作的压力测试。Apache 2.0。

MnemoPay 不是什么： 不是银行，不是汇款机构，不是 Stripe 的替代品，不是 Agent 框架，也不是合规平台。它是支付轨道与运行时之间的规则与证据层。

---

治理延迟（亚秒级不变量）

“亚秒级治理”是经过测试的不变量，而非营销宣传。基准测试位于 tests/bench/governance-latency.bench.ts，使用 vitest bench 测量每条治理热点路径，并为每种场景输出一行可供 grep 检索的 [gov-bench] 汇总结果。以下数据是通过 npm run bench:governance 得出的稳态百分位数（在开发机上运行；你的硬件会有所不同，重要的是相对顺序）。

热点路径	p50	p95	p99	机器
policy.evaluateAction（EU AI Act，单次 tool_call）	2.1 µs	2.8 µs	5.0 µs	Intel i5-1035G1 @ 1.0 GHz · Node 25.9 · Windows 11
MerkleAudit.record（追加 + 链哈希）	20 µs	45 µs	150 µs	Intel i5-1035G1 @ 1.0 GHz · Node 25.9 · Windows 11
MnemoPayLite.remember() 端到端（含自动锚定，Ed25519）	1.0 ms	1.7 ms	2.5 ms	Intel i5-1035G1 @ 1.0 GHz · Node 25.9 · Windows 11

两条按事件处理的热点路径（evaluateAction、MerkleAudit.record）都能在 1 毫秒内以两个数量级的余量通过完整的 EU AI Act 策略门控和审计链写入。端到端的 remember() 路径——包括 Ed25519 签名、序列处理和链事件输出——也轻松处于“亚秒级治理”范围内，并留有三个数量级的余量。

CI 强制执行的防护测试 tests/governance/latency-invariant.test.ts 会在每次运行 npm test 时执行降级模式抽样；如果 policy.evaluateAction 的 p95 超过 1 ms，或 MerkleAudit.record 的 p95 超过 5 ms，就会失败。这些阈值旨在捕捉约 10 倍的性能退化，而非因抖动频繁触发。

复现方法：npm run bench:governance（完整的 vitest.bench 基准测试套件），或 npm test -- latency-invariant（CI 阈值检查）。

---

原生支付通道

每种支付通道都采用与 StripeRail / PaystackRail / LightningRail 相同的 PaymentRail 接口：

支付通道	说明
StripeMPPRail	Stripe Machine Payments Protocol——Agent 支付通过 Stripe 固定版本的 API 2026-03-04.preview，以加密货币存款的形式在 Tempo 网络上路由
X402Rail	Coinbase x402（HTTP 402 复兴）——通过 EIP-3009 transferWithAuthorization 在 Base L2 上使用 USDC。可插拔签名器（可自带 viem/ethers/noble）。SDK 不包含任何加密货币依赖。
GoogleAP2Rail	Google Agent Payment Protocol（FIDO Alliance，AP2 v0.2）。Mandate VC + Intent VC + HTTP 结算。生成任何签名之前，先进行预检策略强制执行（上限、有效期、货币、接收方）。

此外还有 Spatial 治理折叠——attachSpatialEvidence() 使用具身 Agent（无人机、机器人）的 GridStamp 在场证明，为 MerkleAudit 链联合签名。采用松耦合设计——没有 gridstamp 运行时依赖。

更小、更安全的使用方可通过子路径导入

如果你只需要 MnemoPay 的一个模块，请导入对应的子路径，而不是软件包根路径。这样可使 MCP 服务和其他标准输入输出工具保持安静，避免将未使用的中间件打包进去，并让依赖边界一目了然。

import { localEmbed, cosineSimilarity } from "@mnemopay/sdk/recall";
import { StripeRail, X402Rail } from "@mnemopay/sdk/rails";
import { SQLiteStorage } from "@mnemopay/sdk/storage";
import { CommerceEngine } from "@mnemopay/sdk/commerce";

需要完整 SDK 功能时，请使用根路径导入。只有在有意挂载 MnemoPay MCP 服务时，才使用 @mnemopay/sdk/mcp。

---

Swarm（稳定版 — v1.11+）

@mnemopay/sdk/swarm 补上了 browse.sh 作为公开技能目录推出的那块拼图。我们的方案还增加了它没有的功能：Swarm 中的每个 Agent 都带有 DID；每项操作都会经过 FiscalGate 检查，并遵守单个 Agent 和总额度上限；每个 TaskResult 都会追加到共享的 Article-12 审计链；每次技能调用都可通过 SDK 其余部分使用的同一哈希链账本计费。

CLI： npx @mnemopay/swarm list · npx @mnemopay/swarm demo — 参见 mnemopay-swarm。

import { Swarm } from "@mnemopay/sdk/swarm";
import { AuditChain } from "@mnemopay/sdk/governance";
import { open } from "@mnemopay/browser";   // any BrowserProvider works

const provider = await someProviderFactory();
const swarm = new Swarm({
  size: 4,
  provider,
  did: "did:mp:abc...",
  budget: { perAgent: 0.25, total: 1.00 },
  audit: { chain: new AuditChain() },
});

const run = await swarm.spawn([
  { id: "t1", skillId: "ramp.com/expense-create",  prompt: "submit $42 lunch" },
  { id: "t2", skillId: "linear/issue-create",      prompt: "file UI bug" },
  { id: "t3", skillId: "cloudflare/dns-record-set", prompt: "add CNAME" },
]);

const results = await swarm.gather(run);
const final   = await swarm.recombine(results, "merge-json");

适用场景。 当你想并行打开 N 个浏览器会话来解决问题时——例如多源研究、跨平台问题分类，或类似 A/B 测试的“询问三个 Agent，采纳多数意见”——但又希望只有一份审计包、一个预算额度，并在同一处完成计费。

三种结果重组策略（也可自定义）。

• first-success — 返回第一个 ok:true 任务的输出；适合任意答案都可以的竞速模式。
• majority-vote — 返回所有 ok:true 任务中最常见的输出；适合重视共识的事实提取。
• merge-json — 深度合并每个 ok:true 对象输出，并按键排序（跨运行保持确定性）。
• concat — 按任务派生顺序，以 \n 拼接字符串输出。
• 或传入任意 (results) => unknown 回调。

技能目录。 公开列表位于 mcp.mnemopay.com/skills。该目录刻意保持精简，并如实标注——只有签署正式合作协议后才会显示经过验证的合作伙伴徽章。其他所有条目均标记为 verified: false, status: 'pending-partner'，让你准确了解其信任级别。

BrowserSwarm — 原生浏览器会话并行派发（自 1.11.0 起稳定）

@mnemopay/sdk/swarm/browser 扩展了 Swarm，为每项任务提供一组带类型的步骤序列（goto / act / extract / screenshot / wait），并采用延迟连接的方式接入 @mnemopay/browser（可选 peer 依赖项——安装 SDK 不会拉取 Playwright）。每项任务都有自己的浏览器会话，每个步骤都会向共享审计链追加一个 browser.step 事件；若某个步骤抛出异常，只会终止该任务——其他会话仍会继续运行。

import { BrowserSwarm } from "@mnemopay/sdk/swarm/browser";
const swarm = new BrowserSwarm({
  size: 3, provider: undefined as never,
  budget: { perAgent: 0.25, total: 1.00 },
  browser: { provider: "stagehand" },
});
const run = await swarm.spawn([
  { id: "amzn", prompt: "amazon price",  steps: [{type:"goto", url:"https://amazon.com/dp/X"},  {type:"extract", selector:"#priceblock_ourprice"}] },
  { id: "bby",  prompt: "best buy price", steps: [{type:"goto", url:"https://bestbuy.com/site/X"},{type:"extract", selector:".priceView-customer-price"}] },
  { id: "tgt",  prompt: "target price",   steps: [{type:"goto", url:"https://target.com/p/X"},   {type:"extract", selector:"[data-test=product-price]"}] },
]);
const results = await swarm.gather(run);   // BrowserTaskResult[] with .screenshots + .extractedData

请在 github.com/mnemopay/mnemopay-sdk 提交问题。

仅审计中间件 — .audit(client)，支持流式处理和磁盘链（1.11.0-alpha.0）

适用于聊天组件和受监管的工作流：任何提示词修改都属于违规，但仍需 Article-12 遥测：

import { AuditChain } from "@mnemopay/sdk/governance/audit-chain";
import { AnthropicMiddleware } from "@mnemopay/sdk/middleware/anthropic-audit";

const chain = new AuditChain({ path: "./.audit-chain/llm.jsonl" });  // file-backed since 1.11.0-alpha.0
const client = AnthropicMiddleware.audit(new Anthropic(), { chain });

// .create AND .stream now both emit one `llm.call` event per call. Streams
// that get cancelled mid-iteration emit `partial: true` with tokens-so-far.
for await (const chunk of client.messages.stream({ model, max_tokens, messages })) { /* ... */ }

@mnemopay/sdk/middleware/openai-audit 为 OpenAI 提供了同等形式的接口——会自动拦截 chat.completions.create({ stream: true })（传入 stream_options: { include_usage: true } 以捕获最终用量块）。

---

要构建 MCP 服务？从这里开始。

如果你正在推出 MCP 服务，并希望按次收费——即使金额低于一美分——MnemoPay 就是为你打造的。

• 低于一美分的支付，通过 Lightning 通道实现（由于费用问题，Stripe/Paystack 无法实现）
• 使用 agent.charge(amount, toolName) 按工具计量——只需两行代码
• Agent Reputation Scoring 自动拦截滥用调用者——声誉评分范围为 300-850，提供免费和付费层级
• 加密收据，每位用户都可以审计——不必“信我就行”的计费方式
• 前 10 个采用该方案的 MCP 服务可永久免费使用；未来若有任何变更，须提前 90 天书面通知（通过 email 发送你的代码仓库链接）

import MnemoPay from "@mnemopay/sdk";
const agent = MnemoPay.quick("my-mcp-server");

// Inside your tool handler:
const tx = await agent.charge(0.002, "embed_document");  // 0.2¢
if (tx.status === "blocked") return { error: "Payment declined" };
await agent.settle(tx.id);
// ... run the tool

零配置入门 → 生产级 Lightning 通道 → Agent Reputation Scoring 门控。同一套 API。

---

MnemoPay 的独特之处

5 家竞争对手共获得了 8,700 万美元投资，但没有一家拥有以下 10 项功能中的 3 项以上：

功能	MnemoPay	Mem0（2,400 万美元）	Skyfire（950 万美元）	Kite（3,300 万美元）	Payman（1,400 万美元）
持久记忆	是	是	否	否	否
支付通道（3 种）	是	否	仅 USDC	稳定币	仅银行
Agent 身份（KYA）	是	否	开发中	Passport	否
Agent 声誉评分（300-850）	是	否	否	否	否
行为金融	是	否	否	否	否
记忆完整性（Merkle）	是	否	否	否	否
EWMA 异常检测	是	否	否	否	否
复式记账	是	否	否	否	否
自主商务	是	否	否	否	否
多 Agent 网络	是	否	部分支持	部分支持	否
得分	10/10	1/10	2/10	2/10	1/10

---

Agent 声誉评分

为 AI Agent 设计的新型跨会话声誉评分系统。评分由五个部分组成，范围为 300-850（对开发者而言，这个范围与消费信用评分相似；MnemoPay 与 Fair Isaac Corporation 或任何消费信贷局均无关联）：

import { AgentReputationScoring } from "@mnemopay/sdk";

const scorer = new AgentReputationScoring();
const result = scorer.compute({
  transactions: await agent.history(1000),
  createdAt: agentCreationDate,
  fraudFlags: 0,
  disputeCount: 0,
  disputesLost: 0,
  warnings: 0,
  budgetCap: 5000,
  memoriesCount: agent.memories.size,
});

console.log(result.score);      // 742
console.log(result.rating);     // "very_good"
console.log(result.feeRate);    // 0.013 (1.3%)
console.log(result.trustLevel); // "high"
console.log(result.requiresHITL); // false

组成部分	权重	衡量内容
付款记录	35%	成功率、争议情况、按时间加权
信用利用率	20%	支出与预算上限的对比，理想范围为 10-30%
记录时长	15%	账户年限、活动密度
行为多样性	15%	交易对手、类别、金额范围
欺诈记录	15%	欺诈标记、争议败诉、警告

评分范围	评级	信任级别	费率
800-850	卓越	完全信任	1.0%
740-799	非常好	高度信任	1.3%
670-739	良好	标准	1.5%
580-669	一般	降低	1.9%
300-579	较差	最低 + HITL	2.5%

---

行为金融引擎

基于诺贝尔奖得主 Daniel Kahneman 及其合作者经同行评审的行为经济学研究。每个参数均引用已发表的研究成果。

import { BehavioralEngine } from "@mnemopay/sdk";

const behavioral = new BehavioralEngine();

// Prospect Theory (Kahneman & Tversky, 1992)
// Losses hurt 2.25x more than gains feel good
behavioral.prospectValue(100);   // { value: 57.5, domain: "gain" }
behavioral.prospectValue(-100);  // { value: -129.5, domain: "loss" }

// Should the agent wait before buying?
const cooling = behavioral.coolingOff(2000, 5000); // amount, monthly income
// → { recommended: true, hours: 3.2, riskLevel: "high", regretProbability: 0.65 }

// Frame spending as goal delay (2.25x more effective than gain framing)
const frame = behavioral.lossFrame(200, {
  name: "Emergency Fund", target: 10000, current: 3000, monthlySavings: 500
});
// → "This $200 purchase delays your Emergency Fund goal by 12 days."

// Save More Tomorrow (Thaler & Benartzi, 2004)
const smart = behavioral.commitmentDevice(0.035, 0.03, 4);
// → { finalRate: 0.095, explanation: "3.5% → 9.5% over 4 raise cycles" }

// Predict regret from purchase history
behavioral.recordRegret({ amount: 300, category: "gadgets", regretScore: 8, timestamp: "..." });
const prediction = behavioral.predictRegret(400, "gadgets");
// → { probability: 0.72, triggerCoolingOff: true }

研究来源： Tversky 与 Kahneman（1992）、Laibson（1997）、Thaler 与 Benartzi（2004）、Barber 与 Odean（2000）、Nunes 与 Dreze（2006）、Shiller（2000）。

---

记忆完整性（Merkle 树）

具备篡改检测能力的记忆。如果有人注入、修改或删除 Agent 的记忆，Merkle 根就会改变，你也会知晓。

import { MerkleTree } from "@mnemopay/sdk";

const tree = new MerkleTree();

// Every memory write adds a leaf
tree.addLeaf("mem-1", "User prefers monthly billing");
tree.addLeaf("mem-2", "Last purchase was $25 API access");

// Take periodic snapshots
const snapshot = tree.snapshot();
// → { rootHash: "a3f2...", leafCount: 2, snapshotHash: "b7c1..." }

// Later: check if memories were tampered
const check = tree.detectTampering(snapshot);
// → { tampered: false, summary: "Integrity verified. 2 memories, root matches." }

// Prove a specific memory exists without revealing others
const proof = tree.getProof("mem-1");
MerkleTree.verifyProof(proof); // true

防范： MemoryGraft 注入、隐蔽删除、内容篡改、重放攻击、重排序攻击。

---

异常检测（EWMA + 行为指纹 + 金丝雀）

三套独立系统，用于发现遭到入侵的 Agent。

import { EWMADetector, BehaviorMonitor, CanarySystem } from "@mnemopay/sdk";

// 1. EWMA: real-time streaming anomaly detection
const detector = new EWMADetector(0.15, 2.5, 3.5, 10);
detector.update(100); // normal
detector.update(100); // normal
detector.update(9999); // → { anomaly: true, severity: "critical", zScore: 8.2 }

// 2. Behavioral fingerprinting: detect hijacked agents
const monitor = new BehaviorMonitor({ warmupPeriod: 10 });
// Build profile over time
monitor.observe("agent-1", { amount: 100, hourOfDay: 14, chargesPerHour: 2 });
// Sudden change = suspected hijack
monitor.observe("agent-1", { amount: 9999, hourOfDay: 3, chargesPerHour: 50 });
// → { suspected: true, severity: "critical", anomalousFeatures: 3 }

// 3. Canary honeypots: plant traps for compromised agents
const canary = new CanarySystem();
const trap = canary.plant("transaction");
canary.check(trap.id, "rogue-agent");
// → { severity: "critical", message: "CANARY TRIGGERED: Agent compromised" }

数学公式： mu_t = alpha * x_t + (1 - alpha) * mu_{t-1}，当 |x_t - mu_t| > k * sigma_t 时发出警报（Roberts 1959，Lucas 与 Saccucci 1990）。

---

记忆（不断积累的知识库）

这不是传统的 RAG 查找。MnemoPay 的记忆会不断积累——每笔交易都会强化相关上下文，较弱的记忆会逐渐衰退，较强的记忆则会得到整合。这与 Karpathy 所说的“LLM Wiki”模式相同，但应用于支付和信任场景。

• 艾宾浩斯遗忘曲线 — 记忆会随时间自然衰退
• 赫布强化 — 成功的交易会强化相关记忆
• RL 反馈回路 — rlFeedback(ids, reward) 会在 Agent 执行操作后应用 EWMA 重要性更新
• 记忆整合 — 自动清理较弱的记忆，保留重要内容
• 语义回忆 — 按相关性而非仅按新近程度查找记忆
• 每条记忆 100KB — 存储丰富的上下文，而不只是字符串

// After a recall + action, signal usefulness with rlFeedback
const memories = await agent.recall("user preferences", 5);
// ... agent acts on recalled memories ...
await agent.rlFeedback(memories.map(m => m.id), +1.0);   // +1 = useful, -1 = not useful

选择持久化适配器

Recall 由可插拔的 PersistenceAdapter 提供支持。根据部署形态进行选择：

适配器	基础设施	最适合	导入路径
MemoryAdapter（默认）	无	开发、测试、临时 Agent	内置
SQLiteAdapter	单个文件（better-sqlite3）	单节点、本地优先、边缘场景	@mnemopay/sdk/storage
PostgresAdapter / NeonAdapter	Postgres + pgvector	托管式／多节点生产环境（Neon、Supabase、RDS/Aurora、Cloud SQL）	@mnemopay/sdk/recall/postgres

PostgresAdapter 和 NeonAdapter 是由 pgvector 提供支持的同一个实现 ——“Neon”只是托管式 Postgres；选择适合你基础设施的名称即可。

import { MnemoPay } from "@mnemopay/sdk";

// Via MnemoPay.create — { type: "postgres" } (alias of "neon")
const agent = await MnemoPay.create({
  agentId: "agent-1",
  persist: { type: "postgres", url: process.env.DATABASE_URL! },
});

// Or construct the adapter directly
import { PostgresAdapter, postgresMigrationSql } from "@mnemopay/sdk/recall/postgres";
const adapter = new PostgresAdapter({ url: process.env.DATABASE_URL! });

架构（一个 vector(384) 列和 HNSW 余弦索引）会在首次写入时自动创建。若要改用自己的迁移工具管理，请运行 postgresMigrationSql(table?, dimensions?) 中的 DDL，并传入 skipBootstrap: true。 需要可选的对等依赖项：npm install pg。

声誉连胜记录与徽章

Agent 会随着时间积累信任。连续成功结算会累积连胜记录，解锁徽章并降低费用。

const rep = await agent.reputation();
console.log(rep.streak);
// → { currentStreak: 47, bestStreak: 312, streakBonus: 0.094 }

console.log(rep.badges);
// → [
//   { id: "first_settlement", name: "First Settlement", earnedAt: 1712700000000 },
//   { id: "streak_50", name: "Streak Master", earnedAt: 1712900000000 },
//   { id: "volume_10k", name: "High Roller", earnedAt: 1713100000000 },
// ]

徽章	要求
首次结算	完成 1 次结算
连胜 10 次	连续结算 10 次
连胜 50 次	连续结算 50 次
交易额 $1K	累计结算金额达到 $1,000 以上
交易额 $10K	累计结算金额达到 $10,000 以上
完美记录	结算 100 次以上，且没有争议

退款或争议会重置连胜记录。连胜奖励可叠加，声誉最高提升 +10%。

哈希链式账本

每条账本记录都通过 SHA-256 哈希链与上一条记录关联。任何记录被修改，哈希链都会断裂，verify() 会立即检测到。

const summary = agent.ledger.verify();
console.log(summary.chainValid);     // true
console.log(summary.chainIntegrity); // 1.0 (100% of links verified)

结合记忆的 Merkle 完整性校验和交易的 HMAC，MnemoPay 为你提供三套彼此独立的防篡改检测系统。

支付（精确到分的复式记账）

• 复式记账 — 每笔借记都有对应贷记，始终保持收支平衡
• 托管流程 — charge -> hold -> settle -> refund（流程形式与 Stripe/Square 相同）
• 按交易额分级收费 — 根据累计交易额收取 1.9% / 1.5% / 1.0%
• 3 种支付渠道 — Paystack（非洲）、Stripe（全球）、Lightning（BTC）
• 精确到分的整数运算 — 经 50 个并发 Agent 的 200,000 笔交易压力测试，误差为零

身份（KYA 合规）

• 加密身份 — HMAC-SHA256 密钥对、防重放保护
• 能力令牌 — 附带支出限额的范围限定权限
• 交易对手白名单 — 限制 Agent 可以与谁进行交易
• 紧急停用开关 — 立即撤销所有令牌

欺诈检测（ML 级别）

• 频率检查 — 每分钟／小时／天的限额
• Isolation Forest — 无监督 ML 异常检测
• 地理增强 — 国家追踪、快速跨区检测、OFAC 制裁筛查
• 自适应引擎 — 非对称 AIMD、防博弈、断路器、PSI 漂移检测

多 Agent 商务

• CommerceEngine — 通过授权、托管和审批回调实现自主购物
• MnemoPayNetwork — 注册 Agent、执行交易、共享记忆上下文
• 供应链 — 10 步 Agent 链、100 个 Agent 的市场，均已通过测试

---

Claude Agent SDK 集成

专为 Claude Agent SDK 模式打造的两个原语；在此模式中，Opus 编排器会启动 Sonnet/Haiku 子 Agent。

召回结果的 1 小时提示词缓存

将 MnemoPay 召回结果传入 Claude 系统提示词时，使用 formatForClaudeCache() 生成包含 cache_control: { type: "ephemeral", ttl: 3600 } 的内容块。Anthropic API 会将该前缀缓存最多 1 小时；读取缓存的费用约为正常输入费率的 10%。使用稳定的召回前缀并保持 1 小时缓存热运行时，用户观察到召回部分输入 token 的节省幅度通常为 85-92%——实际结果取决于调用频率和记忆集的稳定性。

import MnemoPay, { formatForClaudeCache } from "@mnemopay/sdk";
import Anthropic from "@anthropic-ai/sdk";

const agent = MnemoPay.quick("my-agent");
const anthropic = new Anthropic();

// Option A: recall() directly returns a cache block
const cacheBlock = await agent.recall("user preferences", 10, {
  formatForClaudeCache: true,
});

// Option B: convert an existing memory array (no extra recall call)
const memories = await agent.recall("user preferences", 10);
const cacheBlock2 = MnemoPay.formatForClaudeCache(memories);
// OR: formatForClaudeCache(memories) from the module directly

const response = await anthropic.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 1024,
  system: [
    { type: "text", text: "You are a helpful assistant.", cache_control: { type: "ephemeral" } },
    cacheBlock,  // ← MnemoPay recall cached for 1 hour
  ],
  messages: [{ role: "user", content: userMessage }],
});

序列化文本按记忆 ID 排序，因此相同的记忆集会产生逐字节相同的输出——这是后续轮次命中缓存前缀所必需的。

按子 Agent 归因成本

跟踪多 Agent 流水线中每个子 Agent 的花费——记录为复式账本条目对，以确保审计记录清晰。

import MnemoPay, { SubagentCostTracker } from "@mnemopay/sdk";

const orchestrator = MnemoPay.quick("orchestrator");

// After each Claude API call, record the cost:
orchestrator.subagentCosts.attributeSubagentCost({
  parentAgentId: "orchestrator",
  subagentId: "researcher-1",
  subagentRole: "researcher",
  modelId: "claude-sonnet-4-6",
  inputTokens: 5000,
  outputTokens: 2000,
  cacheReadTokens: 8500,   // tokens served from the 1h recall cache
  cacheWriteTokens: 500,
  cacheWriteTtl: "1h",
});

// At end of pipeline, get breakdown ordered by cost:
const breakdown = orchestrator.subagentCosts.subagentCostBreakdown("orchestrator");
// → [{ subagentId, subagentRole, modelId, totalCostUsd, cacheSavingsUsd, ... }]

const totalSaved = orchestrator.subagentCosts.totalCacheSavings("orchestrator");

使用的定价表：2026 年 Anthropic 标价（Opus 4.7 $5/$25/M、Sonnet 4.6 $3/$15/M、Haiku 4.5 $1/$5/M；缓存读取 0.1×，1 小时写入 2×）。如果费率发生变化，请更新 src/subagent-cost.ts 中的 MODEL_PRICING。

完整集成指南请参阅 docs/agent-sdk-guide.md。

---

支付渠道

每种渠道都实现相同的 PaymentRail 接口——createHold / capturePayment / reversePayment。无需修改 Agent 代码即可切换支付渠道。

渠道	覆盖范围
StripeRail	卡（USD、EUR、GBP 等）
PaystackRail	非洲（NGN、GHS、ZAR、KES）
LightningRail	BTC 低于 1 美分的微支付
StripeMPPRail	通过 Stripe MPP 在 Tempo 上进行加密货币存款
X402Rail	通过 EIP-3009 transferWithAuthorization 在 Base 上使用 USDC
GoogleAP2Rail	AP2 v0.2 基于授权的结算（FIDO Alliance）

import {
  PaystackRail, StripeRail, LightningRail,
  StripeMPPRail, X402Rail, GoogleAP2Rail,
} from "@mnemopay/sdk";

const paystack  = new PaystackRail(process.env.PAYSTACK_SECRET_KEY!);
const stripe    = new StripeRail(process.env.STRIPE_SECRET_KEY!);
const lightning = new LightningRail(LND_URL, MACAROON);

const mpp   = new StripeMPPRail(process.env.STRIPE_SECRET_KEY!);
const x402  = new X402Rail({ signer: yourEip3009Signer });   // bring-your-own crypto
const ap2   = new GoogleAP2Rail({ mandate, endpoint, signer });

const agent = MnemoPay.quick("my-agent", { paymentRail: paystack });

Stripe — 使用已保存的客户信息实际扣款

无需跳转浏览器，即可向用户已保存的卡片扣款的端到端流程：

import MnemoPay, { StripeRail } from "@mnemopay/sdk";

const rail = new StripeRail(process.env.STRIPE_SECRET_KEY!);
const agent = MnemoPay.quick("agent-1", { paymentRail: rail });

// 1. Create a Stripe customer (one-time, persist cus_... to your DB)
const { customerId } = await rail.createCustomer("[email protected]", "Jerry O");

// 2. Collect a card via Stripe.js: create a SetupIntent, return client_secret
//    to the browser, let Stripe Elements confirm it. You receive pm_... from
//    the webhook or confirmation callback. Save it alongside the customer.
const { clientSecret } = await rail.createSetupIntent(customerId);
// → hand clientSecret to frontend, get back paymentMethodId after confirm

// 3. Charge the saved card later, off-session, no user interaction needed
const tx = await agent.charge(25, "Monthly API access", undefined, {
  customerId,
  paymentMethodId: "pm_saved_from_step_2",
  offSession: true,
});

// 4. Settle (captures the hold) or refund (releases it)
await agent.settle(tx.id);

Paystack 通过 authorizationCode 支持相同模式：

const tx = await agent.charge(5000, "NGN invoice", undefined, {
  email: "[email protected]",
  authorizationCode: "AUTH_abc123", // from an earlier Paystack transaction
});

---

MCP 服务

npx @mnemopay/sdk init
# or
claude mcp add mnemopay -s user -- npx -y @mnemopay/sdk

默认工具组：essentials（14 个工具，约 1K token）。 这是可安装的最轻量级 MCP 服务之一——MnemoPay 默认只加载记忆 + 钱包 + 交易，因此不会占用 Agent 的上下文预算。

• memory：remember、recall、forget、reinforce、consolidate
• wallet：balance、profile、history、logs
• tx：charge、settle、refund、dispute、receipt_get

需要更多工具？请显式启用：

npx @mnemopay/sdk --tools=all       # all 95 tools
npx @mnemopay/sdk --tools=agent     # essentials + commerce + hitl + payments + webhooks
npx @mnemopay/sdk --tools=reputation  # Agent Reputation Scoring only

工具组：memory、wallet、tx、commerce、hitl、payments、webhooks、reputation、security、governance、identity、skills、spatial、agent_os、organization_admin、operator。别名：essentials（默认）、agent、all。也可通过 MNEMOPAY_TOOLS 环境变量设置。

v1.3.0 中的破坏性变更： 默认值原为 all，现改为 essentials。如果你依赖无需标志即可使用 commerce/hitl/webhooks/fico/security，请传入 --tools=all 或 --tools=agent。请参阅 CHANGELOG。

---

中间件

可直接使用的代理，让召回过程变得无感：每次聊天调用都会自动将最相关的记忆注入系统上下文，并在调用后存储对话内容。所有提供商都采用相同的 Middleware.wrap(client, agent) 形式。

// OpenAI
import { mnemoPayMiddleware } from "@mnemopay/sdk/middleware/openai";

// Anthropic
import { mnemoPayMiddleware } from "@mnemopay/sdk/middleware/anthropic";

// Gemini
import { GeminiMiddleware } from "@mnemopay/sdk/middleware/gemini";

// Cohere (v2 chat API)
import { CohereMiddleware } from "@mnemopay/sdk/middleware/cohere";
const cohere = CohereMiddleware.wrap(new CohereClientV2({ token }), agent);

// Mistral
import { MistralMiddleware } from "@mnemopay/sdk/middleware/mistral";
const mistral = MistralMiddleware.wrap(new Mistral({ apiKey }), agent);

// LangGraph
import { mnemoPayTools } from "@mnemopay/sdk/langgraph";

---

架构

完整的技术栈示意图和模块图：docs/architecture.md。

┌──────────────────────────────────────────────────────────────────┐
│                       MnemoPay SDK                                │
│              Governance · Memory · Payments · Identity            │
├─────────────────────────────────────────────────────────────────┤
│ GOVERNANCE  Charter · FiscalGate · Article 12 · MerkleAudit      │
│             mission scope, budget enforcement, audit bundles     │
├──────────┬──────────┬───────────┬─────────────────────────────────┤
│  Memory  │ Payments │ Identity  │  Agent Reputation Scoring       │
│          │          │           │  300-850, 5-component           │
│ remember │ charge   │ KYA       ├─────────────────────────────────┤
│ recall   │ settle   │ tokens    │  Behavioral Finance             │
│ reinforce│ refund   │ perms     │  prospect theory, nudges        │
│ forget   │ dispute  │ killswitch├─────────────────────────────────┤
│          │          │           │  Anomaly Detection              │
│          │          │           │  EWMA + fingerprinting          │
├──────────┴──────────┴───────────┼─────────────────────────────────┤
│     Double-Entry Ledger         │  Merkle Integrity               │
│  debit + credit = always zero   │  tamper-evident memory          │
├─────────────────────────────────┼─────────────────────────────────┤
│     Fraud Guard (ML-grade)      │  Canary Honeypots               │
│  velocity + geo + adaptive      │  compromise detection           │
├─────────────────────────────────┴─────────────────────────────────┤
│ SPATIAL    GridStamp adapter — proof-of-presence for embodied      │
│            agents (drones, robots). Loose-coupled, fail-closed.    │
├──────────────────────────────────────────────────────────────────┤
│ RAILS  Stripe · Paystack · Lightning · StripeMPP · x402 · AP2    │
│        same PaymentRail interface — drop-in swap, no agent diff   │
└──────────────────────────────────────────────────────────────────┘

---

模块稳定性

MnemoPay 遵循语义化版本规范。稳定性等级说明在 2.0 版本之前，模块的公共 API 可能发生多大变化——完整约定请参阅 VERSIONING.md。

模块	导入路径	稳定性	备注
记忆 / 回忆	@mnemopay/sdk/recall	稳定	记住 · 回忆 · 强化 · 遗忘
支付	@mnemopay/sdk	稳定	收费 · 结算 · 退款 · 争议处理，精确到分
复式记账	@mnemopay/sdk	稳定	借方+贷方=0，哈希链式记录
身份（KYA）	@mnemopay/sdk/identity	稳定	Ed25519、能力令牌、紧急停用开关
Agent 声誉评分	@mnemopay/sdk	稳定	5 个组成部分，300–850
欺诈 / 异常	@mnemopay/sdk	稳定	频率、地理位置、EWMA、金丝雀
支付通道（Stripe/Paystack/Lightning）	@mnemopay/sdk/rails	稳定	统一的 PaymentRail 接口
治理 — 策略	@mnemopay/sdk/governance/policy	稳定	亚秒级 evaluateAction
治理 — 审计链	@mnemopay/sdk/governance/audit-chain	稳定	Merkle 事件流，Article 12 导出
治理 — 章程 / Article 12	@mnemopay/sdk/governance	稳定	使命范围 + EU AI Act 套件
治理 — 审批路由	@mnemopay/sdk/governance/approval	Beta	HITL 队列 + routeVerdict
治理 — 风险分类体系	@mnemopay/sdk/governance/risk	Beta	从低到严重的等级 + 预设策略
治理 — 操作账本	@mnemopay/sdk/governance/action-ledger	Beta	类型化的“Agent 做了什么”记录
MnemoSkills（受治理的技能）	@mnemopay/sdk/skills	Beta	版本化、受权限控制、可计费的能力——参见 examples/08-invoice-collector.ts
空间 / GridStamp	@mnemopay/sdk/governance	Beta	在场证明、松散耦合、故障关闭
支付通道 — x402 / AP2 / StripeMPP	@mnemopay/sdk/rails	Alpha	新兴的 Agent 支付标准
Swarm	@mnemopay/sdk/swarm	稳定	spawn / gather / recombine / stop；27 个单元测试
Swarm CLI	@mnemopay/swarm	稳定	目录列表/安装/演示
BrowserSwarm / 语音	@mnemopay/sdk/swarm/browser	稳定	可选的 @mnemopay/browser 对等依赖

---

测试

npm test    # full test suite across 12 files

• core.test.ts — 记忆、支付、生命周期、声誉评分、行为、Merkle、EWMA、金丝雀、连胜、徽章
• fraud.test.ts — 频率、异常、费用、争议、重放检测
• geo-fraud.test.ts — 地理信号、信任、制裁
• identity.test.ts — KYA、令牌、权限
• production-100k.test.ts — 100K 次操作、10 个并发 Agent、哈希链验证、零漂移
• stress-200k.test.ts — 200K 次真实场景压力测试：50 个 Agent、突发流量、竞态条件、退款风暴、内存泄漏检测
• ledger.test.ts — 复式记账、对账
• network.test.ts — 多 Agent、交易、供应链
• paystack.test.ts — 支付通道、webhook、转账
• stress.test.ts — 1000 次循环精度、并行操作
• recall.test.ts — 语义搜索、衰减、强化

---

许可证

Apache License 2.0 — 请参阅 LICENSE。

版权所有 2026 J&B Enterprise LLC。

---

第三方归属说明

src/recall/observations.ts 中的实体观察写入路径（按实体汇总摘要、防抖重新生成、跨会话汇总）衍生自 vectorize-io/hindsight（MIT，版权所有 (c) 2025 Vectorize AI, Inc.）。完整的上游声明保留在 NOTICE 和移植文件的文件头中。

---

商标和监管声明

Agent Reputation Scoring 是一种针对自主软件 Agent的可信度评分系统，并非用于消费者信用报告。它不会生成《公平信用报告法》（FCRA）所定义的消费者报告，也不受 FCRA 监管。MnemoPay 不是消费者征信机构。

MnemoPay 不是银行、汇款机构或保险公司，也不持有客户存款。支付通过第三方支付网络（Stripe、Paystack、Lightning Network）结算——MnemoPay 是一款代表开发者连接这些网络的软件，而非金融机构。

“FICO”是 Fair Isaac Corporation 的注册商标。MnemoPay 及其 Agent Reputation Scoring 模块均与 Fair Isaac Corporation 无关联，未获其背书，也并非源自该公司。AgentCreditScore 和 AgentFICO 导出名称是已弃用的别名，为兼容早期 Beta 版本而保留，并将在未来的主版本中移除。

---

由 Jeremiah Omiagbo 构建