拆解Second Brain架构:一个Cloudflare Worker如何撑起完整AI记忆系统(D1+Vectorize+KV)
拆解Second Brain架构:一个Cloudflare Worker如何撑起完整AI记忆系统(D1+Vectorize+KV)
Second Brain 是一个开源 AI 记忆系统:它用单个 Cloudflare Worker 充当所有 AI 工具的共享"第二大脑",底层由 D1(关系数据库)、Vectorize(向量检索)与 KV(键值存储)三块拼装。本文拆解 Second Brain 架构,带你从一次 recall 请求的完整旅程入手,看懂这个自托管在 Cloudflare 免费层上的记忆系统是如何运转的 🧠
先说清楚:它解决什么问题
Claude、ChatGPT、Cursor、Codex 这些 AI 工具之间天然不共享上下文——你在 Claude 里说过的项目决策,到 Cursor 里还得再说一遍。Second Brain 的思路是:存储一次,处处召回。
所有客户端(MCP 客户端、CLI、浏览器扩展、Obsidian、Notion、日历、邮件)都连接到同一个 Worker,通过 REST 或 Model Context Protocol(MCP)读写同一份记忆。记忆的语义检索、去重、关联、过期检测,全部发生在这个 Worker 内部。
三大存储分工:D1、Vectorize、KV 各干什么
整个系统的资源绑定都声明在 wrangler.jsonc 里,一眼就能看全:
| 组件 | Cloudflare 服务 | 在 Second Brain 中的角色 |
|---|---|---|
DB |
D1(Serverless SQLite) | "事实库":记忆条目、关系图谱、审计日志、团队租户 |
VECTORIZE |
Vectorize 向量数据库 | 384 维、余弦距离的向量索引,负责"按意思找" |
AI |
Workers AI | 文本嵌入、交叉编码器重排、LLM 摘要与洞察推理 |
OAUTH_KV |
KV | 跨实例协调状态:FTS 就绪标志、回填游标、配置、OAuth、夜间摘要 |
💡 关键点:这四个服务全部在 Cloudflare 免费额度内可用,这也是项目能"零成本自托管"的原因。
D1:记忆的"事实库"
核心 Schema 在 db/schema.sql 中。最基础的是 entries 表(db/schema.sql#L3-L19):每条记忆一行,含正文、标签、来源、时间戳,以及 valid_from / valid_until 两列——让记忆自带"事实成立的时间区间",从而支持"按某个历史时间点回忆"(recall 的 as_of 参数)。
围绕它还有几张各司其职的表:
edges(db/schema.sql#L32-L44):记忆之间的关系图谱,supersedes(取代)、caused_by(因果)、part_of_project等类型,支撑"顺藤摸瓜"式召回;entries_fts(db/schema.sql#L378):FTS5 trigram 全文索引,由触发器与entries表自动同步,让关键词检索按 BM25 相关度排序,而不是扫全表——官方实测在 2 万条记忆上比全表扫描便宜 200~300 倍;workspaces/users/memberships:Team Edition 的租户模型,Personal 层 + Shared 层共存于同一个 Worker;entry_events:只增不改的审计日志,"防篡改"靠的就是代码里根本没有 UPDATE/DELETE 这两条路。
Vectorize:语义召回的引擎
写入记忆时,Worker 会用 Workers AI 的嵌入模型(默认 @cf/baai/bge-small-en-v1.5,见 src/constants.ts#L62)把长笔记切成 1600 字符的块逐块向量化,写入 Vectorize 索引。召回时,查询语句同样被嵌入,Vectorize 返回语义最近的候选——所以"我们为什么换了服务器"能找到当初存的那条"把 Postgres 迁移到 Vitess 的决策",哪怕用词完全不同。
值得注意的是容错设计:Vectorize 不可用时,记忆捕获和关键词召回照常工作,语义索引恢复后自动补齐,服务永不整体中断。
KV:被低估的协调中枢
KV 存的不是记忆,而是"系统状态",典型用法包括(源码可查 src/db/fts-backfill.ts、src/config.ts):
fts:ready标志:标记全文索引是否建好,所有实例 5 分钟内感知切换;- 回填游标:存量大脑的 FTS 索引每夜建 2000 行,游标记录进度;
- 运行配置:覆盖默认值的用户设置;
- OAuth 会话与夜间维护摘要。
由于 Worker 是无状态多实例的,KV 充当了它们之间的"共享内存"。
一次 recall 请求的完整旅程 🚀
召回是整个系统最精巧的部分,核心在 src/recall/search.ts,流程分五步:
- 双路召回:dense 臂向 Vectorize 查语义最近邻;keyword 臂走 FTS5 索引按 BM25 排名(FTS 未就绪或查询不含可检索词时,自动降级为 LIKE 子串匹配,保证永远有结果);
- RRF 融合:两路候选用倒数排名融合(src/recall/rrf.ts)合并成一份带权重的候选池;
- 时间衰减重排:近期记忆获得加成,符合"记忆有热度"的直觉;
- 交叉编码器重排:
auto模式下,用@cf/baai/bge-reranker-base对前 30 个候选精读打分(src/recall/model-reranker.ts),失败时精确回退到未重排的结果,并带熔断器防止模型故障拖垮请求; - 图谱扩展 + MMR 多样性:沿
edges追踪关联记忆,再用 MMR 避免返回一堆近义重复。
整条管线有"预算纪律":每一步的 D1 语句数、读取行数都被严格控制,这正是它能跑在免费层的根本。
写入路径:remember 之后发生了什么
你调用 MCP 的 remember 存一条记忆时,Worker 会依次做(入口 src/capture/entry.ts):
- 自动分类与标签解析,识别项目归属;
- 重复检测:向量相似度 ≥ 0.95 直接判定重复,≥ 0.85 给出提示(阈值见 src/constants.ts#L53-L54);
- 写入 D1:
entries表的触发器同步更新 FTS 索引和每工作区计数表entry_counts,一次写入全部生效; - 向量化:长笔记分块嵌入,批量写入 Vectorize(每批最多 1000 个向量);写不进去的条目先落 D1,由夜间任务补齐,保存动作本身永不因索引失败而报错。
夜间维护:免费额度下的"五连发"定时任务 ⏰
免费层每次调用只有 50 个 D1 查询、10ms CPU 的预算,而 Cloudflare 免费版最多挂 5 个 cron 触发器。Second Brain 把这 5 个名额用得分毫不爽,全部定义在 wrangler.jsonc#L46-L75:
| 计划 | 干什么 |
|---|---|
0 1 * * * |
夜间维护:压缩摘要、图谱推断、过期检测、FTS 回填/自检、回收站清理、补索引 |
30 * * * * |
每小时集成同步(日历/邮件/Notion 镜像)+ 到期事项推送 |
45 1 * * * |
洞察候选累积 |
15 2 * * SUN |
每周洞察推理(用更大的 LLM 读两条旧记忆,判断是否存在张力) |
45 2 * * SUN |
团队层每周洞察(第 5 个名额,官方注释明确写"第五个也是最后一个") |
路由逻辑在 src/index.ts#L89-L296:Worker 按 cron 字符串把每次触发分发给对应任务,任何一个任务失败只记日志,不会拖垮其他任务。多个任务"各领各的预算额度"而非挤在一次调用里,是整套设计里最有工程味的一处取舍。
分层模块:大项目如何保持可读
这个 Worker 从单体 index.ts 演进而来,现在的模块布局与依赖规则写在 src/ARCHITECTURE.md:
| 层 | 路径 | 职责 |
|---|---|---|
| Pure | memory/、text/ |
纯函数:分词、时间解析、余弦相似度,只依赖常量 |
| Infra | env.ts、lib/、db/ |
环境、HTTP、认证、数据库初始化 |
| Domain | capture/、recall/、graph/、insight/ |
捕获、召回、图谱、洞察等核心业务 |
| Edge | routes/、mcp/、oauth/ |
REST 路由、MCP 服务器、OAuth |
| Entry | src/index.ts |
只做接线,不写业务 |
规则很简单:只允许自上而下依赖,禁止反向引用,这让每一层都能被独立测试(test/ 下有 300+ 测试文件)。
新手上手:两种部署方式
- 桌面应用(推荐):官方提供 Mac / Windows 安装器(见 installer/README.md),选一个口令、登录 Cloudflare,约两分钟自动创建 Worker、D1、Vectorize 并完成 AI 客户端连接,全程无终端操作;
- 手动部署:clone 仓库后执行
git clone https://gitcode.com/gh_mirrors/se/second-brain-cloudflare
cd second-brain-cloudflare
npm install
npm run deploy
部署完成后,把 MCP 客户端指向 https://你的Worker地址/mcp,配合 AUTH_TOKEN 口令即可。随后在 Claude 里问一句"我们上次关于部署的结论是什么",就能感受这套记忆系统的工作方式。
总结:这套架构最值得学的三点
- 职责单一的存储组合:D1 存事实、Vectorize 存语义、KV 存状态,三者在免费额度内互相补位,没有任何一块"大包大揽";
- 处处可降级的召回管线:FTS 未就绪降级 LIKE、重排失败回退启发式排序、Vectorize 离线保留关键词路径——系统在每个环节都准备了"次优但可用";
- 预算即架构:所有设计决策(拆分 cron、语句数上限、行读取上限)都围绕免费层配额展开,这为"Serverless 上跑重度 AI 应用"提供了非常具体的参考。
如果你正在考虑给多个 AI 工具搭一个共享记忆层,Second Brain 的 src/ 目录(尤其是 src/recall/ 与 src/capture/)本身就是一份值得细读的工程教材 📚
