Skip to content
Andy963Public

About

Durable memory backend for AI agents on Cloudflare Workers: evidence-backed claims, semantic dedup, and vector recall built on Workers AI, D1 and Vectorize

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

cf-mem

一个部署在 Cloudflare Workers 上的 RAG 与持久记忆后端。

  • 用 Workers AI 生成 embedding
  • 用 D1 保存原文、证据和结构化 Claims
  • 用 Vectorize 做相似度搜索
  • 通过显式 X-Project-Id 和 D1/Vectorize namespace 隔离项目数据

先看这里

你想做什么 从哪里开始
第一次部署 三分钟部署
查看完整配置 docs/configuration.md
查看 Claims 设计 docs/durable-memory-design.md
查看所有接口和进阶说明 docs/complete-guide.md

三分钟部署

1. 安装并登录

需要一个 Cloudflare 账号,并在本机完成 Wrangler 登录:

npm install
npx wrangler login
cp wrangler.toml.example wrangler.toml

wrangler.toml 已被 Git 忽略,只在本地保存部署配置。

2. 创建 Cloudflare 资源

以下资源名称需要和 wrangler.toml 保持一致。已经存在的资源不要重复创建。

npx wrangler d1 create cf-text
npx wrangler vectorize create cf-vector --dimensions 1024 --metric cosine
npx wrangler vectorize create cf-claims --dimensions 1024 --metric cosine

把创建 D1 时返回的 database_id 填入本地 wrangler.toml,然后创建 Claims 的过滤索引:

for property in status scope_kind scope_id category type workspace_id; do
  npx wrangler vectorize create-metadata-index cf-claims \
    --property-name "$property" --type string
done

最后应用数据库迁移:

npx wrangler d1 migrations apply cf-text --remote

3. 配置公开入口

wrangler.toml.example 默认启用 fail-closed 路由:workers_dev = false、 preview_urls = false,且没有默认公开地址。首次部署前必须在本地 wrangler.toml 中配置一个受支持的自定义域名路由:

[[routes]]
pattern = "mem.example.com/*"
zone_name = "example.com"

把示例域名替换成 DNS 已托管到 Cloudflare 的域名。/admin 还需要额外的 Cloudflare Access 边界,不能只依赖自定义域名;不要通过重新启用 workers.dev 或 preview URL 绕过 Admin 鉴权。

4. 配置鉴权

# /health、embedding 或网页接口使用
npx wrangler secret put API_TOKEN

# /memory/* 使用独立的全局鉴权 token;项目由请求头显式指定
npx wrangler secret put MEMORY_API_TOKEN

新部署应始终显式配置 MEMORY_API_TOKEN。只有迁移期间尚未设置它时,服务才会回退使用 API_TOKEN;该兼容路径不应作为新客户端配置。

请求示例:

curl -sS \
  -H "Authorization: Bearer $MEMORY_API_TOKEN" \
  -H "X-Project-Id: cf-mem" \
  -H "Content-Type: application/json" \
  https://<your-worker>/memory/index \
  -d '{"text":"用户喜欢简洁的回答。"}'

旧的 PROJECT_TOKENS_JSON / PERSONAL_MEMORY_TOKEN 只在迁移窗口内接受,且必须同时带上 与旧凭据绑定的 X-Project-Id;它们不能再推断项目,也不能跨项目使用。新客户端只使用共享 token + 显式项目头。迁移完成后删除这两个旧 secret。

不要把 token 写进 wrangler.toml,也不要提交到 Git。

5. 部署

npm run typecheck
npm run deploy

部署完成后,使用上面配置的自定义域名检查:

curl -sS -H "Authorization: Bearer $API_TOKEN" \
  https://mem.example.com/health

需要配置什么?

大多数部署只需要根据实际接口选择上面的 secret。其他功能按需开启:

功能 额外配置
原始记忆 /memory/* MEMORY_API_TOKEN(未设置时回退 API_TOKEN)和 X-Project-Id
记忆自动提炼 PERSONAL_MEMORY_OWNER_ID、模型接口配置;鉴权使用共享 token
网页搜索和抓取 TAVILY_API_TOKEN、TAVILY_BASE_URL
搜索精排 RERANK_DEFAULT_ENABLED,或请求中的 rerank.enabled
管理后台 受 Cloudflare Access 保护的自定义域名、ADMIN_ALLOWED_EMAIL、ADMIN_ACCESS_TEAM_DOMAIN、ADMIN_ACCESS_AUD
语义去重 默认已启用;需要 cf-claims 及其 metadata index

完整配置表、默认值和 secret 用法见 docs/configuration.md。不要为了使用基础 embedding 接口预先配置 项目记忆、个人记忆、Tavily、精排或管理后台。

启用 Admin

启用管理后台时,按以下顺序配置:

  1. 在 wrangler.toml 中配置自定义域名路由,并保持 workers_dev = false、 preview_urls = false。

  2. 为同一主机上的 /admin* 和 /admin/api/* 创建 Cloudflare Access Application, 策略只允许管理员登录。

  3. 将 Access Application AUD、Access team domain 和同一管理员邮箱写入本地配置:

    [vars]
    ADMIN_ALLOWED_EMAIL = "[email protected]"
    ADMIN_ACCESS_TEAM_DOMAIN = "https://team.cloudflareaccess.com"
    ADMIN_ACCESS_AUD = "your-application-aud-tag"
  4. 重新部署后,未登录访问 /admin 应先经过 Access;允许的邮箱应能打开 Dashboard, 错误邮箱和缺少有效 Access JWT 的请求应被拒绝。

完整变量表和边界说明见 docs/configuration.md。

最小调用示例

生成 embedding

curl -sS \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  https://<your-worker>/v1/embeddings \
  -d '{"input":["你好,世界"]}'

写入原始记忆

curl -sS \
  -H "Authorization: Bearer $MEMORY_API_TOKEN" \
  -H "X-Project-Id: cf-mem" \
  -H "Content-Type: application/json" \
  https://<your-worker>/memory/index \
  -d '{"text":"用户喜欢简洁的回答。","metadata":{"session_id":"s1","kind":"note"}}'

搜索原始记忆

curl -sS \
  -H "Authorization: Bearer $MEMORY_API_TOKEN" \
  -H "X-Project-Id: cf-mem" \
  -H "Content-Type: application/json" \
  https://<your-worker>/memory/search \
  -d '{"query":"用户喜欢什么样的回答?","topK":5}'

写入持久记忆

curl -sS \
  -H "Authorization: Bearer $MEMORY_API_TOKEN" \
  -H "X-Project-Id: cf-mem" \
  -H "Content-Type: application/json" \
  https://<your-worker>/memory/claims \
  -d '{
    "operation": "create",
    "claim": {
      "scope_kind": "user",
      "scope_id": "user-123",
      "category": "rule",
      "applicability": "global",
      "type": "preference",
      "subject": "response",
      "memory_key": "response.language",
      "value": "zh-CN",
      "canonical_text": "用户偏好使用中文回复。",
      "provenance": "user_explicit",
      "confidence": 0.98,
      "evidence_segment_ids": ["<已有segment-id>"]
    }
  }'

Claims 的 create 会先检查身份键,再在同一项目、scope、分类、类型和 workspace 内做语义去重。 相似事实会 reinforce;rule 和 tool_insight 的更新或冲突会自动 supersede 旧版本,其他分类仍不会被静默覆盖。完整规则见 docs/durable-memory-design.md。

客户端集成

新客户端直接调用 /memory/*,使用共享 MEMORY_API_TOKEN 并显式发送 X-Project-Id。如果请求体同时包含 project_id,它必须与请求头一致;服务端不会再从 workspace 名称或旧凭据推断项目。

scripts/install-hooks.sh 和 scripts/cf_mem_hook.py 中的 hook-context、 hook-capture、hook-assistant 仅作为已弃用的兼容适配器。新集成应使用运行时中间件或 直接 HTTP API,迁移背景见 docs/complete-guide.md。

接口概览

路径 用途
GET /health 检查服务是否可达
POST /embed、POST /v1/embeddings 生成 embedding
POST /memory/index 写入原始记忆
POST /memory/search 搜索原始记忆
POST /memory/claims 创建或变更持久记忆
GET /memory/claims 查看 Claims
GET /memory/context 获取按分类路由的记忆上下文
POST /memory/context 获取当前有效记忆上下文
POST /memory/profile/ingest 提交记忆提炼证据(role 可选 user/assistant)
POST /memory/extraction/ingest 提交已索引证据进行自动提炼
POST /web/extract 提取网页正文
POST /web/search、POST /web/crawl 转发 Tavily 请求
/admin Cloudflare Access 保护的管理后台

POST /memory/context 对空输入、斜杠命令和短确认词会跳过语义 embedding 与 Vectorize 查询, 但仍会返回按 scope 确定性匹配的 Claims。

持久记忆支持 rule、tool_insight、user_profile 和 domain_fact 四类。task_state 已于 迁移 0019 退役:线上从未产生过该类记忆,而它是唯一需要 TTL 与工作区精确匹配的分类, 历史行统一置为 retracted 保留审计。 /memory/context 可通过 categories、workspace_id 和 scope_id 做按需路由;未指定 categories 时保持兼容旧调用,返回原有 scope 内的有效 Claims(不广播新分类的 tool_insight)。/memory/search 默认只检索 domain_fact 原始段落;profile_inbox 仅作为提炼证据,始终不会出现在原始搜索结果中。需要其他分类时显式传入 categories,并确保索引元数据包含对应字段。

所有接口的完整请求格式、限制和返回值见 docs/complete-guide.md。

项目结构

src/
  index.ts       # 路由和全局鉴权
  api/           # HTTP 接口
  ai/            # Workers AI 调用
  db/            # D1 数据访问
  vector/        # Vectorize 数据访问
  memory/        # 原始记忆和持久记忆逻辑
migrations/      # D1 迁移
docs/            # 配置、设计和完整参考

日常维护

npm run typecheck
npx wrangler d1 migrations list cf-text --remote
npx wrangler vectorize list-metadata-index cf-claims
npm run deploy

Worker 每十五分钟执行一次 Cron,依次处理:

  • Nudge 扫描:把缺少角色标记的用户证据转换为提炼任务;
  • Evidence flush:提交已经就绪的批量证据;
  • Retention sweep:执行原始记忆 TTL 和项目字节配额清理;
  • Profile jobs:运行有界数量的个人记忆提炼任务;
  • Claim reconciliation:修复 D1 与 Claims Vectorize 之间的不一致;
  • Segment reconciliation:修复 D1 与 raw segment Vectorize 之间的不一致。

Nudge 会将没有角色标记的 kind: "user" 原始文本作为用户证据处理;混合角色文本仍只提取 [user] 内容。 Nudge 处理带前缀的 session_id 时按实际分隔符提取外部 Session ID,不依赖 source_app 的字符串长度。 显式 extraction ingest 和 profile ingest flush 在成功入队后也会标记相关 Segment,避免 Nudge 重复拾取。 当提炼端点连续失败触发断路器时,Cron 会暂停提炼;排队任务会延后到冷却结束, 不会因此增加 Job 或原始段落的失败计数。 语义去重灰区中的 LLM 裁决也使用同一个断路器,上游故障时会快速跳过裁决并保留未合并 Claim。 断路器状态暂时无法从 D1 读取时按关闭处理,优先保证请求继续执行;D1 恢复后才会继续记录断路状态。 启用管理后台前,必须先用 Cloudflare Access 保护自定义域名上的 /admin*,并保持 workers_dev = false、preview_urls = false。Worker 会验证 Cloudflare Access JWT 的签名、 issuer、audience 和 email claim;单独伪造 email header 不再能通过鉴权。

升级

拉取新版本后先应用迁移,再部署:

npx wrangler d1 migrations apply cf-text --remote
npm run typecheck
npm run deploy

旧版本如果没有按项目 namespace 写入 Vectorize,需要按照 docs/complete-guide.md 的升级说明重新索引。

About

Durable memory backend for AI agents on Cloudflare Workers: evidence-backed claims, semantic dedup, and vector recall built on Workers AI, D1 and Vectorize

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages