别再把AI记忆库当向量库用了：团队落地 ai-memory 踩过的四个坑

周五晚上十点，Claude Code 的额度用完了，活儿才干到一半。

你换到 Codex，在同一个目录里敲下第一句话，它回你一句客客气气的“请介绍一下这个项目的架构”。

那一瞬间，血压是会上来的：项目背景、改过哪些方案、哪条路试过是死胡同、还有哪个问题没解决——全得从头再讲一遍。

最近在开发者圈子里被反复讨论的 ai-memory，就是冲着这个场景来的。官方一句话概括得很直白：在 Claude Code 里干到一半，切到 Codex，接着干，不用重新解释架构、失败过的尝试和悬而未决的问题。

但有意思的是，真正把它搬进团队的队伍，翻车的地方往往不在安装，而在认知——最常见的一条，就是把它当成了一个向量库。

一、先搞清楚：它不是“相似度搜索器”，是一本共用的项目笔记本

市面上的AI编程工具其实都在做“记忆”：Claude Code 会自己记笔记，Cursor 也会记一些东西。

问题是这些笔记都锁在一台机器、一个工具里。你一换工具、一换电脑、一交给同事，记忆就断线了。

ai-memory 的思路完全不一样，用大白话讲：

它把一本项目日记摊开放在你自己的服务器上，谁都能翻、能改、能带走。

更关键的是，这本日记是普通的 Markdown 文本文件，用 git 管着版本。你可以用 Obsidian 打开它，可以用命令行全文搜它，可以手动改两句话，也可以整包拷走。

数据库在它眼里只是个“目录卡片”——卡片丢了、坏了，可以照着账本重新做一遍。这一点特别重要，因为很多团队真正值钱的东西，恰恰是这些能被人读懂、能被人修改的文字。

它平时是这么干活的：

你写代码时，工具的生命周期钩子在旁边默默记录；一次会话结束，这些零散记录被整理成一篇篇可读的页面；下次开新会话，系统先递上一张“交接条”，写明上次停在哪、什么没成、什么还悬着。

而且默认情况下，这套流程一次大模型都不调用，不填任何 API Key 也能跑。

二、坑一：以为“记忆 = 向量检索”

这是踩得最狠、也最隐蔽的一个坑。

很多团队一听“AI记忆”，第一反应就是上向量数据库、配云端 embedding。结果呢？账单来了，延迟上来了，隐私评审卡住了，检索效果还不一定好。

ai-memory 的检索其实是“几条腿一起走路”：

关键词全文检索负责“精确命中”，比如某个报错码、某个函数名、某个配置项； 实体索引负责认人认物，把模块、服务、人名、错误类型拎出来； 链接关系负责顺藤摸瓜，从一页跳到相关的另一页； 向量检索只是可选的那条腿，用来兜住“说法不一样但意思差不多”的提问。

打个比方：向量像“凭感觉找相似的人”，全文像“翻字典按字找”，实体和链接像“顺着人际关系表找人”。只留一种，要么答非所问，要么漏掉那个你明明记得出现过的精确报错。

这套设计还有个很实用的地方：中文、日文、韩文不空格也能搜。做国内项目的团队应该懂，这一条能省多少骂。

什么时候才该开向量？ 等你发现大家提问越来越口语化、同义改写特别多，关键词老是差一口气的时候。要开也优先用本地小模型，八十多兆，不联网、不外发，普通笔记本就能跑。

这里有个必须提醒的雷：如果你运行一段时间后，才把 embedding 从“本地”改成“云端”，系统会把已有的全部页面重新算一遍，等于把历史记忆整体发到外部服务商那里。这不是一个随手拨动的开关，是一次“搬家”，动手前务必想清楚。

三、坑二：把 Markdown 事实源当成日志库

第二个误区更生活化：把“整理好的笔记”和“随手记的流水账”混为一谈。

在 ai-memory 里，这两层是分开的：

一层是原始记录——你输入的每一句提示、每一次工具调用、会话的开始和结束； 一层是编译出来的页面——经过整理后的决策、踩坑、流程、规则，也就是真正给人看、给AI查的那部分。

原始记录默认是永不清理的。一个热闹的团队跑上一年，攒出几个GB很正常。

于是就出现了两种典型翻车：

一种是“勤快型”：觉得原始记录太占地方，一把清空。结果发现，这些原始记录正是整理页面的原料——清掉之后，就算以后换上更强的模型、更好的提示词，也再也无法重新整理那段历史，只剩下一篇摘要孤零零地躺着。

另一种是“囤积型”：把所有流水全塞进 wiki 页面。页面变成垃圾场，检索质量断崖式下跌，AI 每次都被一堆无关细节带偏。

正确的姿势其实是分层管理：

原始流水可以按需保留，比如只保留最近 90 天，而且只清理已经整理成页面、页面还活着的那些会话； 页面层则长期保留，因为那才是团队的资产。

另外别忘了“分层”和“钉住”：语义类、流程类的页面天生不参与老化，重要的规范还可以直接钉死。

四、坑三：把“遗忘”当成 bug

几乎所有新团队第一次看到“记忆会过期”都会皱眉：我花钱花时间存的东西，你凭什么给我删了？

但真跑起来你会发现，全留着才是灾难：搜索变慢、噪音变大、AI 被半年前的旧结论带偏，最后大家又开始不信它了。

ai-memory 的默认策略其实很“温柔”：

它给每篇页面算一个分数，由重要程度、放了多少天、被用过多少次共同决定。大概八十天没人碰，页面才会变“冷”。 变冷也不是立刻删，而是先下架打个标记，再等一百八十天才真正清除。 而只要你打开过它、搜到过它、顺着链接点进去过，都算“用过”，寿命会往后延。 语义页、流程页、钉住的页面，完全豁免，不参与这套老化。

更妙的是“删”这件事本身也不粗暴：原始版本还留在 git 里，版本链还在，需要的时候可以恢复回来。

而且默认状态下，那些会改写内容或丢弃内容的操作——压缩合并、近似去重、矛盾标记、让大模型在夜里“做梦”重写冷页面——统统是关闭的。系统默认只做两件不会伤害你的事：让常用的记忆活得更久，给不常用的记忆打个冷标记。

给团队的建议是：先跑一个月，看看冷页清单长什么样，再动手调参数。一上来就把遗忘调得特别激进，等于把刚建立的信任亲手拆掉。

五、坑四：部署时想当然

这一段最不“AI”，但最容易出事。

一个数据目录，只能有一个服务进程。 别为了所谓高可用，起两个服务指向同一份数据，这不是加保险，是制造麻烦。

多用户不等于多租户。 它支持多人账号、操作归属、审计日志，但同一个服务里的所有已登录用户，属于同一个信任域，能读到同一个项目的记忆。项目之间的隔离靠命名空间，不靠账号权限。心里要有这根弦。

默认只绑本机。 一旦要给别人用、要放到局域网上，就必须配访问令牌，再加一层 HTTPS 反向代理。它本身不做静态加密，靠的是文件系统权限（目录仅本人可进、文件仅本人可读写）。笔记本丢了，记忆也就跟着丢了——磁盘加密这件事得你自己上。

抓取会脱敏，但那是“尽力而为”，不是保险箱。 常见格式的密钥、令牌、私钥路径会被自动抹掉，但它明确说了这不是保证。敏感仓库请用排除路径，或者干脆切成白名单模式；至于“把AI回复的原文也存下来”，那是个双重开关，默认关着。

还有三条会把数据送出本机的通道，务必记牢：云端 embedding、助手原文捕获、用大模型给搜索结果重排。默认全是关的，开之前请先过一遍合规。

六、真正该抄的落地清单：权限、备份、遗忘

说完了坑，给一份能直接用的清单。

权限三件事：初始化时自动生成访问令牌，别手工往配置文件里塞；多人使用就开账号，管理类接口只留给管理员；对外一律上 TLS，敏感仓库的抓取规则写进项目里；有人离开，记得吊销他的密钥。

备份三件事：wiki 本身就是 git 仓库，直接推到私有远端，最省事；数据库虽然能重建，但重建要时间，定期整目录快照更稳；升级前一定先备份，而且要真演练一次恢复，别等出事才第一次打开备份文件。

遗忘三件事：把“必须永远留着”的（架构决策、事故复盘、团队规范）钉住；把“到期就该消失”的（临时排查、一次性脚本、活动期数据）设上过期时间；把“只是流水”的原始记录设一个保留窗口。然后每季度花十分钟，看一眼冷页清单和被清掉的内容。

顺带提一句容量：它的写入上限大概在每秒七百条这个量级，是实测出来的，不是拍脑袋。几十人的团队日常使用完全够，但别把它当高频日志总线来用。

七、普通人上手，门槛到底高不高？

好消息是：不需要显卡，不需要 API Key，一台普通笔记本就够了。

安装就两步：跑一次安装脚本，再执行一次初始化。它会自动发现你机器上装了哪些AI编程工具，把钩子和接口接好，还会先给你看一遍计划再动手。重启工具，问一句“你还记得这个项目吗”，就知道通没通。

支持面也铺得很开：Claude Code、Codex、Cursor、Gemini CLI、OpenCode、Kimi、Qwen Code 等二十多种客户端都在名单里；Mac 用户有菜单栏小应用；喜欢容器化的可以直接上 Docker。

适合谁？一个人同时用好几种AI编程工具的独立开发者；几个人的小团队，想让“老员工的经验”变成大家都能查的东西；还有接手别人项目的“接盘侠”——这是我觉得最刚需的一群人。

不太适合谁？只想给聊天机器人加个“人设记忆”的个人用户。它是按代码仓库组织记忆的，不是万能第二大脑。

结语

AI记忆这件事，真正难的从来不是“存”，而是“下次能不能一句话接上”。

存得越多不代表越聪明，能把该记的记住、该忘的忘掉、该交接的交接清楚，才是一个团队真正的积累。

最后留个轻松的问题给大家：如果只能给你的AI定一条“必须忘掉”的规则，你会写什么？是三个月前的临时方案，还是某次争吵里的气话？评论区聊聊。