Arra Memory Lab

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

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

本实验室演示的内容

• 权威层级： 记忆是权威的；分块/嵌入和观察是派生的。

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

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

• 安全变更： 遗忘和重建都是先试运行；遗忘确认绑定到确切的预览快照，确认的重建工作是有界的。

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

• 痕迹关联的召回： 当痕迹持久化成功时，召回会返回 traceId；排名结果快照仅保留记忆 ID、排名/分数来源、源修订版本和源哈希。

• 显式取代： supersedesMemoryId 在写入时一次性解析为不可变的 ID/修订版本/哈希快照。它不推断时间图。

• 小型来源信息： project、sourcePath 和 createdBy 是结构化字段；Oracle 身份仍然是 oracle-<name> 标签。retrospective 和 cheatsheet 是一等记忆类型。

痕迹 queryHash 是关联句柄，而非匿名化——尤其是对于低熵查询——因此即使省略了原始查询和记忆内容，痕迹访问仍然受到保护。

Related MCP server: Ghostkeep

发布标识

package.json 是实验室曼谷 CalVer 的唯一事实来源： YY.M.D-alpha.HMM，其中 HMM = 小时 × 100 + 分钟，时区为 Asia/Bangkok。 构建仅将该字符串注入公共客户端；/api/info、MCP initialize、lab_info 工具和 UI 页脚报告相同的值。

npm run version:next   # preview the next available Bangkok minute
npm run version:bump   # update package.json + package-lock.json, no commit/tag
npm run version:check  # fail if format or lock metadata drift

bump 命令拒绝同分钟重用、时钟回拨、未知标志，以及 任何不比现有 arra-memory-lab-v* 标签更新的 CalVer。

这有意不是生产身份或租户设计。私有 Web API 使用一个所有者 bearer 密钥。远程 MCP 通道使用 OAuth 2.1、S256 PKCE、动态客户端注册（DCR）、过期访问令牌和刷新令牌，以便 Claude.ai 和其他 Web MCP 客户端无需存储所有者口令即可连接。租户、队列、ANN 索引和自主整合仍被推迟。

数据流和隐私边界

• 创建记忆时，在 D1 源写入成功后尝试尽力而为的嵌入。

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

• 确认的重建将选定的记忆标题/内容分块发送到 Workers AI，并将派生的向量写入 D1。

• 关键词召回和重建预览不调用 Workers AI。

• D1 存储权威文本以及派生的分块文本/向量；搜索痕迹和结果链接仅存储哈希、ID、排名、分数和操作元数据。

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

部署

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

2. Cloudflare 部署表单会提示输入 LAB_ACCESS_TOKEN。提供一个长的随机值（例如，使用 openssl rand -hex 32 生成的值）；Cloudflare 将其存储为机密绑定。相同的值解锁浏览器 API 并批准新的 OAuth 客户端，但 OAuth 客户端永远不会收到它。

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

4. 打开 Worker URL。输入一次相同的令牌；浏览器仅将其存储在 sessionStorage 中，因此关闭该浏览器会话会清除它。

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

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

对于已检出的发布版本，请勿编辑 wrangler.jsonc 中的占位符 ID。 发布助手首先构建和测试，解析恰好一个名为 arra-memory-lab 的 D1 数据库 和一个名为 arra-memory-lab-oauth 的 KV 命名空间， 仅将其 ID 写入模式为 0600 的临时配置，应用迁移， 然后部署相同的不可变构建：

npm run deploy:dry-run
npm run deploy

私有 /api/* 路由需要 Authorization: Bearer $LAB_ACCESS_TOKEN。/mcp 仅接受实验室 OAuth 提供程序颁发的访问令牌；所有者机密本身在那里被拒绝。OAuth 发现、DCR、令牌交换和批准 UI 位于 /.well-known/*、/oauth/* 和 /authorize 下。只有 GET /api/info 是公共应用程序内容。如果 LAB_ACCESS_TOKEN 不存在，私有 API 访问和 OAuth 批准将失败关闭。

同意响应有意省略 CSP form-action：真实 MCP 主机使用的嵌入式 OAuth 浏览器即使使用精确来源允许列表也阻止了提交。表单目标是固定的相对 /authorize；base-uri 'none' 防止基本目标重写，每个 DCR 派生的字段都经过 HTML 转义，并且 POST 路径在 OAuth 提供程序验证并完成重定向之前重新解析 PKCE/作用域/客户端状态。这是一个经过衡量的兼容性 边界，而不是通用的 CSP 建议。

为什么选择 D1 进行一键部署？

使用 D1 是因为 Cloudflare 的部署流程可以自动配置和绑定它，使这个实验室真正接近一键部署。权衡是故意的提供商耦合：此版本不演示可移植的数据库层或 Turso/libSQL 部署。这对于专注的 Cloudflare 实验室是可接受的，而不是全面的生产建议。

本地开发

需要 Node.js 用于安装/构建/部署，Bun 用于测试/检查脚本，以及 Cloudflare 账户用于 Workers AI。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":"retrospective","tags":["architecture"],"project":"github.com/soul-brews-studio/claude-ai-mcp-poc","sourcePath":"ψ/memory/retrospectives/example.md","createdBy":"rrr","oracleName":"neo","supersedesMemoryId":"OPTIONAL_EXISTING_MEMORY_ID"}'

# 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","project":"github.com/soul-brews-studio/claude-ai-mcp-poc","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、trace_list、trace_get。

lab_info 对于有效令牌始终存在。memory:read 控制 recall、memory_stats、trace_list 和 trace_get；memory:write 控制 remember、observe、forget 和 rebuild_index。作用域检查使用 每个无状态请求上的未包装访问令牌作用域，包括刷新令牌 降级。

实现固定使用 @modelcontextprotocol/server@2.0.0 并使用 Cloudflare Agents createMcpHandler 包装器。“SDK v2”和“协议版本” 是独立的轴：端点服务现代 2026-07-28 请求，并保持 2025 时代的 initialize 流程作为无状态兼容通道。两个通道都不 创建 Mcp-Session-Id；每个请求都获得一个新的服务器实例。 参见 docs/mcp-v2-stateless.md 了解证明矩阵。

连接或重新加载 MCP 客户端

npm run mcp:connect -- codex "$LAB_URL/mcp" arra-memory-lab
# or Claude Code:
npm run mcp:connect -- claude "$LAB_URL/mcp" arra-memory-lab

助手注册 URL 并启动客户端的 OAuth 登录。重新运行它会刷新注册/登录路径。对于 Claude.ai，打开 设置 → 连接器 → 添加自定义连接器，仅输入 https://…/mcp，点击 连接，并在批准页面上输入实验室口令。

Bearer 与 OAuth

参见 docs/provenance-oauth-report.md 了解衡量的决策和清理后的证明。

失败契约

• 权威记忆写入在嵌入失败时仍然存活。

• 混合召回仅在嵌入提供程序失败时降级，并报告原因。

• 如果语义推理不可用，显式语义召回会出错。

• 数据库/向量错误不会被误标为 AI 回退。

• 痕迹写入失败永远不会改变成功的召回或掩盖其原始错误。

• 完成的痕迹、排名结果链接和保留修剪在一个 D1 批处理中尝试；痕迹持久化相对于召回保持故障安全。

• 遗忘记忆不会擦除历史痕迹结果或取代快照；修剪痕迹会级联到其排名链接。

• 重建在替换派生的分块之前重新检查源修订版本/哈希。

• 遗忘确认需要其预览返回的修订版本、哈希、分块计数和观察计数；过时的确认失败并返回 HTTP 409 / stale_preview。

参见 CONTRACT.md 了解当前运行时边界，以及 DESIGN.md 了解 UI 系统。

主要平台参考

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

• Cloudflare D1 绑定配置

• Cloudflare Workers AI 绑定

• 用于远程 MCP 的 Cloudflare OAuth 提供程序

• Anthropic 远程 MCP 连接器认证

• EmbeddingGemma 300M 模型契约

• Drizzle ORM 与 Cloudflare D1