最近一直在折腾给AI应用加“长期记忆”这件事。早期聊天机器人那种“关掉窗口就失忆”的状态实在太难受了——每次重新开会话都得把背景重新讲一遍仿佛对面坐着一个非常热情但记性极差的新同事。我试着用向量数据库自己搭RAG但折腾来折腾去发现真正的瓶颈不在“存储”而在“怎么无感地把散落各处的信息收进来再在需要的时候准确捞出去”。后来在GitHub上翻到一个叫Supermemory的项目实际部署体验了一轮发现它把这条链路做得相当完整值得拿出来分享。Supermemory定位很直接它是AI应用的一个“记忆层”。你喂它URL、文档、纯文本甚至推文链接它帮你做抓取、清洗、摘要、向量化最后统一存进可检索的存储里之后你的Agent或聊天机器人就可以通过一句自然语言查询召回几个月前你随手保存过的东西。这篇文章我会从它的核心架构讲起给出完整的部署流程、关键接口实战以及我实际运行中踩过的坑和解决方案适合那些正在构建AI原生产品、或者单纯想给自己的知识库加一层智能索引的开发者参考。1. 为什么我需要一个“第三大脑”AI记忆问题的本质1.1 光靠对话上下文撑不住真实场景先聊聊我这边的痛点。之前做过一个内部知识库问答机器人把公司文档切片后扔进向量库看起来一切正常。但实际用起来问题很明显文档本身就是静态的而每个人问问题的“上下文”是动态的。今天问“我们上次讨论的缓存方案”这个“上次”到底指哪次如果没有跨会话的记忆系统只能瞎猜。更头疼的是知识来源不只是文档——还有群聊里的链接、网页收藏、看完的行业报告这些东西平时根本没有结构化的入口进入知识库。市面上大部分“AI记忆”方案解决的是对话历史的存储说白了就是把你和ChatGPT聊过什么存下来下次接着聊。但真实世界的记忆远不止对话还包括你消费过的信息、保存过的链接、浏览过的页面。这才是Supermemory这类“记忆层”项目要解决的问题把一个人/一个Agent的数字足迹变成可以查询的结构化记忆。1.2 Supermemory是什么以及它做对了什么Supermemory这个项目直白点说就是一套可以从零部署的AI记忆后端。它的核心工作是把“非结构化内容”转化为“可供语义检索的知识”并在其上封装了简单的API。它的几个设计决策我很认可输入方式多你可以直接丢给它一段纯文本content也可以丢给它一个URL它会自己抓取网页正文甚至支持推文和PDF自动做摘要和实体提取不是简单切片存向量而是先用LLM生成摘要让存储的粒度更接近“知识”而不是“文本碎片”存储层用的是Cloudflare生态部署在Workers上数据库用D1基于SQLite向量检索也直接在D1里完成不需要额外维护一套重型向量数据库对外暴露的是HTTP API任何语言都可以对接Python、Node、Go都行。我接触过的很多开源项目要么只做了抓取要么只做了向量化Supermemory比较难得的是把所有环节串成了一条完整的流水线而且给出了可以直接用的云端托管版本和自托管方案。1.3 和主流方案的区别它处在RAG和你之间很多做RAG的朋友会问我已经有LangChain Pinecone了还需要Supermemory吗我的理解是RAG框架解决的是“如何检索增强生成”但Supermemory解决的是更前一步——“记忆从哪来、以什么形式存”。它不是要替代你的向量数据库或编排框架而是处于它们上游的一个记忆采集与处理层而且它开放了底层存储访问你可以很轻松地对接自己的下游应用。对我来说最有价值的一点是它解决了“源头供给”的问题——给你的RAG管道持续供应“新鲜且经过清洗”的知识内容而不是每次都要手动准备文档再切片这是一套基础设施不只是Demo。2. 把Supermemory拆开看核心模块与数据流转2.1 六大模块各司其职Supermemory的代码库结构非常清晰每个模块干一件事部署时也可以灵活选择用哪些。我按观察到的职责划分如下模块职责关键点Hono API应用处理HTTP请求、鉴权、路由跑在Cloudflare Workers上supermemory-core记忆的写入、查询、管理核心逻辑封装了所有业务操作Scraper抓取并清洗URL内容支持网页、PDF、推文Flows从Twitter、书签、GitHub Stars等导入数据属于上层导入器ModelsLLM调用摘要、实体提取、嵌入向量默认用Cohere和MoonshotStorageD1 KV Queues持久化、缓存、异步任务全在Cloudflare家这种模块化最大的好处是你如果只需要“内容清洗向量化”可以把Scraper和Models单独拎出来用如果你只想用API完全不用关心底层实现。我第一次看到这种拆分时第一反应是“这项目不只是个玩具”结构设计显然考虑了真实部署的可维护性。2.2 一次完整的数据流转从URL到答案我用“保存一个网页”的场景来说明数据是怎么走的客户端调用API提交一个URL比如POST /v1/writebody里带上url和typeHono应用收到请求后先做基础校验然后把任务发给Cloudflare Queues队列——这是异步设计的关键抓取一个慢网页可能要几秒甚至几十秒不能占用HTTP请求的同步时间Worker队列消费者拿到URL后调用Scraper模块抓取网页正文去除导航、广告、脚本等噪声得到干净的正文内容正文随后被送到LLM摘要模块生成一段简明的摘要并可能提取出关键实体摘要和正文标题被送进Embedding模块用Cohere的embed-v3模型转成1024维向量向量和原始内容一起写入D1数据库期间KV缓存会被更新用于快速命中反复查询的内容之后当用户通过/v1/query提交一个问题例如“我上个月收藏的关于矢量数据库优化的文章讲了什么”系统把问题向量化后在D1里做余弦相似度或点积检索取Top-K相似记忆再返回给客户端。这套流程最打动我的一点是“异步处理”的决策。很多自建的RAG管道都是同步做“抓取→切片→embedding”一次请求可能耗时几十秒用户直接看到超时。Supermemory把最慢的抓取和向量化环节放到了队列里HTTP接口立刻返回“已受理”然后在后台慢慢干体验就顺滑很多。2.3 为什么这套架构适合个人开发者和中小团队先摆一个反直觉的结论做AI记忆层SQLiteD1就是SQLite的分布式版本够用了不需要一开始就上pgvector或Pinecone。很多人的惯性思维是“向量检索必须用专业向量数据库”但实际在个人知识库的体量下——几万条向量、每天新增几百条——D1里存的向量暴力扫描或简单索引的查询耗时就足够用了。Supermemory用D1做向量存储配合Cloudflare的全球边缘网络查询延迟能控制在几百毫秒以内。这让部署和维护成本无限趋近于零不需要额外管理一个数据库实例不用操心备份和扩容。对于已经跑在Cloudflare生态里的项目来说这套方案几乎是零摩擦集成。如果你本来就是个Node/Worker架构那Supermemory的接入就像装一个中间件那么自然。即使你是从零开始创建一个Workers项目、配置好wrangler整个部署过程我实测下来也能在半小时左右跑通。3. 手把手部署从空项目到可调用API3.1 初始化项目把仓库拉下来依赖要求不高本机装好Node.js 18、npm然后全局安装Cloudflare的CLI工具wrangler。我自己用的Node版本是20跑起来完全没问题。# 安装 wrangler npm install -g wrangler # 克隆项目 git clone https://github.com/supermemoryai/supermemory.git cd supermemory然后安装依赖。这个项目用的是npm workspace所以一定要在根目录执行不要在子包里单独装npm install装完依赖后建议先把根目录下的.dev.vars.example复制一份成.dev.vars——这是本地开发环境的变量配置文件后端的密钥都放在这里cp .dev.vars.example .dev.vars3.2 在Cloudflare控制台创建配套资源Supermemory部署需要三样Cloudflare资源D1数据库存储记忆和向量、KV命名空间缓存、Queues队列异步任务处理。我用wrangler命令逐一创建然后记录返回的ID后面写配置要用的。# 创建D1数据库 wrangler d1 create supermemory-db # 创建KV命名空间 wrangler kv namespace create SUPERMEMORY_KV # 创建队列这里需要登录Cloudflare账号 wrangler queues create supermemory-queue创建D1和KV后wrangler会输出对应的database_id和id把它们填到wrangler.toml或wrangler.jsonc的对应字段里。如果用的是新版wrangler配置文件里D1的写法大致是这个样子{ d1_databases: [ { binding: DB, database_name: supermemory-db, database_id: 你的D1数据库ID } ], kv_namespaces: [ { binding: KV, id: 你的KV命名空间ID } ] }3.3 配置模型密钥与关键环境变量Supermemory的向量化默认走Cohere的embed-v3摘要生成走Moonshot AIEclipseMoonshot或者OpenAI兼容接口。你需要去对应平台申请API Key填进.dev.vars里。我整理了一份对照方便知道每个变量是干什么的变量名用途获取地址COHERE_API_KEY调用Cohere嵌入模型生成向量Cohere DashboardMOONSHOT_API_KEY调用Moonshot模型生成摘要/提取实体Moonshot平台KVKV绑定在wrangler里配置Cloudflare控制台DBD1数据库绑定在wrangler里配置Cloudflare控制台TURNSTILE_SECRET_KEY人机验证密钥不用的可忽略Cloudflare Turnstile配置完后wrangler dev启动之前可以先跑数据库迁移建表。Supermemory的迁移文件在packages/db或类似目录下用wrangler的migration命令执行npx wrangler d1 execute supermemory-db --file./packages/db/migrations/0001_init.sql如果本地迁移执行成功D1里就会生成memories、documents这些核心表后面写入和查询都靠它们。3.4 本地跑通与线上发布初始化完成后本地启动npm run devwrangler会给你一个本地地址一般是http://localhost:8787。保险起见先用健康检查接口试一下通不通curl http://localhost:8787/health返回正常的话就可以先写一条记忆试水。确认一切正常然后发布到线上需要已经登录Cloudflare账号npx wrangler deploy部署成功后Cloudflare会分配一个*.workers.dev域名这个就是你的线上API地址。走到这里你已经拥有一个可以随时写入和检索记忆的服务了。整个过程不算复杂但对不熟悉Cloudflare生态的开发者最耗时间的往往是“搞懂D1、KV、Queues之间的绑定关系”所以我专门把这份配置关系放在上面建议先对照着看清楚再动手。4. 核心接口实战写入知识、检索记忆4.1 写入记忆直接喂纯文本Supermemory接口风格走REST简洁直白。写入一条纯文本记忆调用/v1/write即可curl -X POST https://你的域名/v1/write \ -H Content-Type: application/json \ -d { type: content, content: 分布式系统设计中最终一致性和强一致性的取舍需要结合业务场景例如支付系统更关注强一致性而社交媒体的点赞数可以接受最终一致性。, title: 一致性权衡笔记, source: manual-note }服务器处理后会返回一个UUID比如memoryId字段这就是这条记忆的标识。响应很快因为实际写入和向量化在后台队列里异步跑接口只负责受理任务。4.2 写入记忆抓取一个URL抓取网页是Supermemory的拿手好戏。之前做知识管理的时候最烦的就是“把网页正文提取干净”各种广告、弹窗、导航栏混在里面。Supermemory的Scraper模块用mozilla/readability一类的库做正文提取实测下来对主流的博客站、文档站效果都挺干净。curl -X POST https://你的域名/v1/write \ -H Content-Type: application/json \ -d { type: url, url: https://jvns.ca/blog/2024/01/01/some-notes-on-http/, source: pocket }有两点要注意一是type字段要填url别填content否则系统会认为请求体里的content字段才是正文二是URL别带重定向链太长否则抓取超时会自动失败。4.3 检索记忆用自然语言查“模糊的东西”我觉得Supermemory检索接口做得最有价值的地方是它允许你用语义查询而不是非得记准关键词。比如你只记得看过一篇关于HTTP缓存的文章但想不起标题可以这样查curl -X GET https://你的域名/v1/query?qHTTP缓存的策略和注意事项 \ -H Content-Type: application/json返回结果是一个数组包含Top-K个最相关的记忆每个记忆里带content、title、source、createdAt和相似度分数。你可以根据自己的应用场景把返回结果直接拼进Prompt让大模型基于这些记忆来回答。4.4 权限与用户隔离多用户记忆的分开存储Supermemory的API默认是开放模式只要知道API地址就能写入和读取。如果要做成产品给不同用户分开记忆需要自己在应用层加一层“用户标识”或者在路由前面加一层鉴权逻辑。我的做法是封装一个中间层每个请求带上自己的X-User-Id由中间层校验身份并调用Supermemory的写入/查询接口。原因很简单——Supermemory本质上是“记忆引擎”账号体系还是得自己做它并不负责认证和用户管理。5. 真实运行中的坑我踩过的五个问题5.1 嵌入模型维度不匹配导致静默失败我第一次部署后调用写入接口接口返回成功但查询时老是什么都查不到。查了日志才发现D1里存的向量维度是1536维OpenAI的text-embedding-ada-002而查询时用的模型或者代码里配置的维度是1024维Cohere embed-v3。Supermemory默认配置是用Cohere的如果自己改过模型或者配置项没统一就会出现这种“写是写进去了但查不出来”的静默失败。解决思路要么把环境变量里的VECTOR_DIMENSION和模型对应好要么直接调用wrangler d1 execute查一下表里的向量长度确认和查询侧一致。这个坑特别隐蔽因为它不报错纯粹是数据层面维度对不上相似度计算直接失效。5.2 队列任务超时大PDF直接卡死抓取一个2MB的PDF时任务在队列里跑了超过30秒还没结束最终超时。原因是Scraper处理PDF时要做文本提取大文件还要逐页处理整个过程耗时很长超过了我设置的队列超时上限。调整方案有两个方向一是把队列消费者的max_retries调大超时后自动重试二是把抓取超时时间从默认的15秒上调到60秒在队列配置里设置。我采用的是后者实测处理5MB以内的PDF基本能稳定跑完。如果PDF超过10MB建议自己先把文档拆分再分别喂给Supermemory。5.3 摘要模型返回空的边界情况有一次抓取一个纯图片构成的网页正文提取后几乎是空的但Scraper没有报错而是把一段空白内容送给了摘要模型结果摘要模型返回了空字符串。这导致后续流程里虽然生成了向量但向量本身是“空内容”的向量检索时会造成大量噪声。我在代码层加了一个保护正文清洗后长度少于100个字符的内容直接丢弃不进入摘要和向量化环节。这个阈值可以根据自己的业务调整但核心原则是“宁可不存也不要存垃圾”。这个经验适用于所有知识库类的项目不只是Supermemory。5.4 速率限制与冷却策略Cohere和Moonshot这类模型API都有速率限制RPM/TPM。默认配置下如果一批导入任务同时进来比如我一次性导入100个书签队列会同时发多个请求去打模型API很容易触发429限流。一开始我以为是自己配置问题查了日志才发现是并发太高。后来的处理是在队列消费者的处理流程里加一层速率控制比如每次最多并行3个抓取任务多余的任务在队列里排队等着。Cloudflare Queues本身支持max_concurrency配置我把它从默认的10调低到3后429再也没出现过。如果你的模型API配额比较高可以适当调高并发。5.5 KV缓存的命中率优化Supermemory里KV缓存主要用来存网页抓取的中间结果避免同一个URL反复抓取。但默认的缓存策略对于“不同的URL但在相同域名下页面结构变化不大”的场景命中率不高。我实际使用中把缓存的TTLTime To Live从默认的1小时调到了24小时因为对于大多数博客文章来说内容在一天内不会变。这样二次查询时会直接命中缓存少一次抓取和embeddings调用省时也省钱。6. 把它接到自己的Agent/工作流里6.1 给聊天机器人装一个“外挂记忆”部署完Supermemory一周后我开始把它接进自己的聊天机器人测试。实现的逻辑其实很简单用户每次提问时先用/v1/query把问题送进Supermemory检索拿到Top-3相关的历史记忆然后把记忆内容作为System Prompt的一部分拼进上下文再让大模型生成回答。这样用户问“我之前有没有收藏过关于xx的帖子”机器人就能基于记忆来回答而不是一脸茫然。下面这段伪代码展示了我接OpenAI时的做法你可以直接用在自己项目里// 用一个中间函数把Supermemory接入你的Agent async function getRelevantMemories(question) { const resp await fetch(https://你的域名/v1/query?q${encodeURIComponent(question)}); const memories await resp.json(); return memories.slice(0, 3).map(m m.content).join(\n); }这个方案也有局限性如果用户的记忆里根本没有相关信息检索返回的结果可能并不相关需要做一层相关性过滤。我使用的是分数阈值法——相似度低于0.5的结果直接丢弃。6.2 做一个每日回顾用Flows自动积累Supermemory提供的“Flows”概念很实用——它可以把你的外部数据源比如Twitter收藏、GitHub Stars、Pocket书签自动同步过来。我搭了一个定时任务每天早上从我的Pocket里拉取新增的书签批量写入Supermemory这样我的知识库每天都会自动更新不需要人工干预。真正让我觉得这个项目“值得一用”的瞬间是我在两周后某天问它“我之前看到过一篇讲SQLite性能优化外文文章”它准确地把那篇存过的文章标题和链接捞了出来。那一刻的感觉是AI终于开始记得我“看过什么”了。6.3 后续还能怎么玩如果想更进一步这几个方向值得尝试把Supermemory和浏览器扩展结合做“一键收藏当前页面”任何网页都能1秒进入记忆库对接微信/Telegram机器人让它成为个人助理的“记忆后端”在团队内部署一套共享团队知识但要注意在API前面加好鉴权和用户隔离。写在最后部署Supermemory之前我一度觉得“AI记忆”是个大工程要自己搭向量库、写抓取服务、设计embedding管道。实际把它跑起来之后最大的感受是这个领域已经有人在认真做“基础设施”了不需要每个开发者都从轮子开始造。你可以把它当成一个“自托管的记忆API”来玩也可以参考它的架构设计自己实现一套——不管哪种方式我觉得这套“异步采集LLM摘要向量存储语义检索”的模式会是未来AI应用的基本底盘之一。项目本身还在快速迭代社区也活跃遇到问题去GitHub Issues里搜一搜大概率能找到答案。如果你也在为AI的“七天记忆”发愁花一个下午把它部署起来应该不会让你失望。
