一个部署在 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 |
需要一个 Cloudflare 账号,并在本机完成 Wrangler 登录:
npm install
npx wrangler login
cp wrangler.toml.example wrangler.tomlwrangler.toml 已被 Git 忽略,只在本地保存部署配置。
以下资源名称需要和 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 --remotewrangler.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 鉴权。
# /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。
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、精排或管理后台。
启用管理后台时,按以下顺序配置:
-
在
wrangler.toml中配置自定义域名路由,并保持workers_dev = false、preview_urls = false。 -
为同一主机上的
/admin*和/admin/api/*创建 Cloudflare Access Application, 策略只允许管理员登录。 -
将 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"
-
重新部署后,未登录访问
/admin应先经过 Access;允许的邮箱应能打开 Dashboard, 错误邮箱和缺少有效 Access JWT 的请求应被拒绝。
完整变量表和边界说明见
docs/configuration.md。
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 deployWorker 每十五分钟执行一次 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 的升级说明重新索引。