Arra Memory Lab

一个独立的单用户 Cloudflare 实验室，用于学习可信 AI 记忆背后的契约：权威来源、可重建嵌入、有证据支持的观察、可检查的混合召回、有界跟踪以及预览后再变更的操作。

该部署会创建一个 Worker，从 wrangler.jsonc 自动配置其 D1 数据库，并通过部署脚本运行附带的迁移。Workers AI 提供 768 维的 @cf/google/embeddinggemma-300m 嵌入。

本实验演示的内容

• 权威层级： 记忆是权威来源；块/嵌入和观察是派生数据。

• 坦诚的召回： 每次搜索都会报告请求模式、实际模式、降级情况以及排名来源。

• 证据溯源： 观察保留源记忆 ID、修订版本和哈希。

• 安全变更： forget 和 rebuild 均先进行试运行；forget 确认绑定到精确的预览快照，且已确认的 rebuild 工作是有界的。

• 数据最小化： 最新的 100 条搜索跟踪仅包含操作元数据，绝不包含查询或记忆内容。

跟踪中的 queryHash 是关联句柄，而非匿名化手段——尤其是对于低熵查询——因此即使原始查询和记忆内容被省略，跟踪访问仍受到保护。

这有意不是生产环境下的身份或租户设计方案。它使用一个承载令牌，在没有该令牌时默认拒绝访问，并将 OAuth/DCR、租户、队列、ANN 索引和自主整合留待将来处理。

数据流与隐私边界

• 创建记忆时，会在 D1 源数据写入成功后，尽力尝试计算嵌入。

• 语义/混合召回会将查询文本发送到 Workers AI。

• 确认后的 rebuild 会将选定的记忆标题/内容片段发送到 Workers AI，并将派生向量写入 D1。

• 关键词召回和 rebuild 预览不会调用 Workers AI。

• D1 存储权威文本以及派生的结果；声明和派生文本/向量；而来其文本/向量；搜索跟踪仅存储查询哈希和操作元数据。

除非你的 Cloudflare 账户策略和威胁模型明确允许此处理，否则请使用合成数据或非敏感数据。在本地开发时，Workers AI 绑定仍会访问远程服务，可能产生用量费用。

部署

1. 点击上方的 Deploy to Cloudflare 并授权仓库部署。

2. Cloudflare 部署表单会提示输入 LAB_ACCESS_TOKEN。提供一长串随机值（例如，用 openssl rand -hex 32 生成的值）；Cloudflare 会将其存储为密钥绑定。

3. 点击部署后继续。仓库的部署脚本会在构建和发布 Worker 之前自动应用 D1 迁移。

4. 使用管理员打开 Worker 地址。输入同一令牌一次；浏览器仅将其存储在 sessionStorage 中，因此关闭该浏览器会话即可清除。

如果部署表单或自动迁移步骤需要手动恢复，请使用等效的 CLI 备用方案：

printf '%s' 'replace-with-a-long-random-token' | npx wrangler secret put LAB_ACCESS_TOKEN
npx wrangler d1 migrations apply DB --remote

API 和 /mcp 都需要 Authorization: Bearer $LAB_ACCESS_TOKEN。只有 GET /api/info 是公开的，它仅公开架构/能力信息，而不公开语料内容。如果 LAB_ACCESS_TOKEN 缺失，受保护的访问将默认拒绝。

为什么使用 D1 实现一键部署？

选择 D1 是因为 Cloudflare 的部署流程可以自动配置仓库绑定它，使本项目真正做到接近一键部署。这种取舍是有意的供应商绑定：此版本不演示可移植的数据库层或 Turso/libSQL 部署。这对于一个有明确范围的 Cloudflare 实验室是可接受的，而不是针对所有场景的生产环境建议。

本地开发

安装/构建/部署需要 Node.js，运行测试/检查脚本需要 Bun，使用 Workers AI 需要 Cloudflare 账户。Wrangler 会发出警告，因为即使在本地运行 Worker 和 D1 时，AI 绑定仍然是远程的。

cd labs/arra-memory-lab
npm install
cp .env.example .dev.vars
# Set LAB_ACCESS_TOKEN in .dev.vars
npx wrangler d1 migrations apply DB --local
npm run dev

质量检查：

npm run typecheck
npm test
npm run build
# or all three:
npm run check

postbuild 钩子会从 dist/ 中移除 .env* 和 .dev.vars* 文件。这是对本地产物进行的实时防护；Wrangler 的部署清单不会上传这些开发文件。

HTTP 示例

export LAB_URL='https://arra-memory-lab.<account>.workers.dev'
export LAB_ACCESS_TOKEN='your-long-random-token'
export AUTH="Authorization: Bearer $LAB_ACCESS_TOKEN"

# Public capability disclosure
curl "$LAB_URL/api/info"

# Create an authoritative memory (indexing is best effort)
curl -X POST "$LAB_URL/api/memories" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"title":"Prefer explicit authority","content":"Memories are sources; embeddings are projections.","kind":"decision","tags":["architecture"]}'

# Hybrid recall exposes requested/effective modes and rank provenance
curl -X POST "$LAB_URL/api/search" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"query":"Which data is authoritative?","mode":"hybrid","limit":8}'

# Preview a forget and retain the returned expected* fields
curl -X POST "$LAB_URL/api/memories/MEMORY_ID/forget" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"confirm":false}'

# Confirm only that exact preview. A changed source/impact returns 409 stale_preview.
curl -X POST "$LAB_URL/api/memories/MEMORY_ID/forget" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"confirm":true,"expectedRevision":1,"expectedHash":"COPY_FROM_PREVIEW","expectedChunks":0,"expectedObservationCount":0}'

# Preview a bounded rebuild; confirmed work is capped at 10 memories / 256 chunks
curl -X POST "$LAB_URL/api/index/rebuild" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"confirm":false}'

MCP

该实验室在 /mcp 端点暴露无状态的 Streamable HTTP MCP，并包含以下工具：

lab_info、remember、recall、observe、forget、rebuild_index、memory_stats。

本实现固定使用 @modelcontextprotocol/server@2.0.0，并通过 Cloudflare Agents 的 createMcpHandler 包装器进行暴露。“SDK v2” 和 “协议版本” 是两个独立的维度：端点同时服务现代的 2026-07-28 请求，并将 2025 时代的 initialize 流程保留为无状态兼容路径。两个路径都不会创建 Mcp-Session-Id；每个请求都会获得一个全新的服务器实例。请参阅 docs/mcp-v2-stateless.md 了解验证矩阵。

使用 curl 检查 MCP 端点

curl -X POST "$LAB_URL/mcp" \
  -H "$AUTH" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

MCP 客户端配置

对于支持 Streamable HTTP 服务器的客户端：

{
  "mcpServers": {
    "arra-memory-lab": {
      "type": "http",
      "url": "https://arra-memory-lab.<account>.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${LAB_ACCESS_TOKEN}"
      }
    }
  }
}

如果你的客户端不会在请求头中插值环境变量，请使用其 secret manager，而不是将令牌提交到仓库中。确切的配置包装因 MCP 客户端而异；端点和支持的 bearer header 是固定的。

失败契约

• 权威记忆的写入操作不会因客户端嵌入失败而失败。

• 混合召回仅在嵌入提供方失败时降级到其他模式，并报告原因。

• 显式的语义主要由记忆的结果，如果语义推断不可用，则返回明确错误。

• 数据库/错误不会错误地表现为 AI 的备用回退。

• 跟踪写入失败绝不会改变成功的召回结果，也不会掩盖其原始错误。

• Rebuild 在替换派生块之前会重新检查，直到确认源修订/哈希。

• 忘记操作的确认必须与预览返回的修订号、哈希、块数和观察数匹配；过期的是 409 / stale_preview。

请参阅 CONTRACT.md 了解冻结的 v1 边界，以及 DESIGN.md 了解 UI 系统。

主要平台参考

• Cloudflare 部署按钮和自动资源预配置

• Cloudflare D1 绑定配置

• Cloudflare Workers AI 绑定

• EmbeddingGemma 300M 模型规范

• Drizzle ORM 与 Cloudflare D1