别把记忆库当向量库用：团队落地 ai-memory 的真实踩坑清单

当"AI 智能体记忆"这个词出现在技术圈，多数人的第一反应是向量数据库：embedding、余弦相似度、ANN 索引。市面上从 Mem0、Chroma 到腾讯云的 TencentDB Agent Memory，宣传口径几乎都落在"语义检索"上。这也导致大量团队在落地开源项目 ai-memory 时，沿用了部署 RAG 的那套心智模型——先配 embedding 模型、先调向量索引参数、把记忆当"能检索的日志"来灌。结果往往事与愿违：要么多花钱配了根本用不上的 LLM 与 embedding 密钥，要么把事实源和索引的边界搞混，最后连数据该不该备份、能不能删都说不清楚。

ai-memory 是 Rust 实现的编码智能体长期记忆服务，为 Claude Code、Codex、Cursor、Gemini CLI、OpenCode 等二十余种 CLI 提供跨智能体、跨机器的共享记忆。它的设计初衷恰恰是"别当向量库用"：源码里明确写着默认路径 zero LLM calls——捕获、检索、Handoff 交接全部可以在不配置任何 API key 的情况下工作。本文结合项目源码与部署文档，把团队落地时最常见的三类误区拆开讲清楚，附上仓库内可核验的文件路径，供正在评估或已经踩坑的团队对照。

误区一：以为记忆 = 向量检索，忽略 FTS5 与实体索引

先看检索链路的真面目。在 核心架构说明 的稳态数据流第 6 步写得非常直白：memory_query 的默认答案来自 FTS5 全文检索 + 实体匹配 + 链接邻居的 RRF 融合；只有当配置了 embedder 时，向量余弦相似度才作为第四路信号加入同一个 RRF。也就是说，向量检索在 ai-memory 里不是地基，而是"可选加分项"。

FTS5 才是默认主力

全文检索层由 SQLite 的 FTS5 承担，查询预处理逻辑 里有几个值得团队注意的实现细节：

• 裸多词查询按 OR 连接而非 FTS5 默认的 AND。代码注释解释了原因：一句自然语言查询如"cross project search strategy"若要求每个词在同一页面共现，除单关键词外召回率几乎为零；改成 OR + bm25 排序后，最匹配的页面仍然排在前面。团队排查"怎么搜不到"时，先想想自己是不是在用 AND 的心智模型。
• 内置英文停用词表（DEFAULT_STOPWORDS）。高文档频率的功能词会压制 BM25 信号，所以 a/an/the/of 等 60 个词在裸查询里被过滤掉；但索引层是 unicode61 remove_diacritics 2，即 É/é/e 会命中同一 posting——对非英语团队，停用词表需要自己按语言配置。
• 裸冒号会被当作列限定语法而报错。pick: handoff 这类查询会让 SQLite 报 no such column: pick，实现里专门做了中和处理。

实体索引来自 frontmatter，而非抽取模型

实体匹配依赖页面 frontmatter 里显式声明的 entities 列表，由 canonical 数据驱动生成实体索引。一个很容易被忽略的推论是：实体索引为空就完全不参与评分——它不会像向量库那样"自动从文本里抽实体"。想用好实体检索，就得让页面结构本身规范。

全局检索只有 FTS

memory_query 的实现 还注明：跨项目的 global=true 检索是 FTS-only，向量流、图流均不参与。这意味着团队若把跨仓库知识复用完全押在 embedding 上，得到的结果会比预期弱一截——因为设计上全局层刻意保持轻量。

落地建议

• 先以 零向量、零 LLM 的默认路径上线，跑通 FTS5 + 实体 + 链接邻居的 RRF，验证召回是否满足业务，再决定要不要为 embedding 付费。
• 向量能力由 嵌入抽象层 提供，支持本地模型与远端 API；但注意向量命中依赖 page_embeddings 表的存在，且查询向量与文档向量必须同源（仓库里专门有回归测试防止"查询向量与文档向量不一致"的 bug）。
• 让"好搜索"回归到写规范页面这件事上：有清晰的标题、frontmatter 实体、路径式 wikilink。把力气花在灌向量上，不如花在整理知识结构上。

误区二：把 Markdown 事实源当成日志库

ai-memory 与绝大多数"记忆即向量库"方案最根本的分野，是它的双层存储：

Markdown Wiki 是唯一事实源，SQLite 是派生索引。

架构文档 反复强调这一不变式。落到磁盘上，数据目录的结构在 备份文档 里被拆得清清楚楚：

data/
├── wiki/    # markdown 事实源（本身就是一个 git 仓库）
├── raw/     # 不可变的会话日志账本
├── db/      # memory.sqlite（FTS5、实体、嵌入）—— 派生数据
├── logs/    # 滚动追踪日志
└── models/  # 本地嵌入模型权重（可重新下载）

事实源是"知识"，不是"流水账"

raw/ 与 wiki/ 的区分，对应了 捕获-编译模型 中的两步：生命周期钩子把会话中发生的事（提示词、工具调用、会话边界）以脱敏观测的形式收集进 raw/；到会话结束时，服务端把观测编译成 sessions/<id>.md 这类可读页面，后续整合进 concepts/、decisions/、gotchas/、procedures/ 等知识目录。这正是 Karpathy 提出的"知识只编译一次"范式，社区解读文章里也专门强调它区别于"每次都从 RAG 现查"。

团队最常见的错位，是把 raw/ 或 sessions/ 页面当"日志库"去查询和备份——查最新事件、按时间翻旧账。而 ai-memory 的检索是面向编译后的知识页面的，FTS 查询代码 明说用户/智能体输入是"search text"而非"log filter"。会话摘要只是知识沉淀的中间态，真正长期复用价值在 decisions/、gotchas/、procedures/ 这些可被权威度加权、可跨会话引用的页面上。

页面是 OKF 概念文件，不是随意笔记

从 2.0 起，wiki 原生是 Open Knowledge Format（OKF）v0.2 bundle：每个 .md 文件必须携带声明 type 的 YAML frontmatter，页面归属通过路径族判定——_rules/ → Rule、gotchas/ → Gotcha、decisions/ → Decision、procedures/ → Procedure、sessions/ → Session Summary。另有 generated（生成者与时间）、sources（来源会话）、stale_after（过期时间）等字段。这意味着：

• 记忆可移植：ai-memory export-okf --project <proj> 导出的就是一份符合 OKF 规范的 markdown 目录，任何 OKF-aware 工具或直接 Obsidian 都能读；
• 页面有生命周期语义：stale_after 直接参与遗忘调度（见误区三），手写一个没有 frontmatter 的 .md 扔进 wiki，既污染规范，也会在遗忘策略面前行为异常。

别绕过写入通道

所有页面写入都汇入 ops::upsert_page_in_tx 这一个咽喉点，由它完成 OKF 归一化、supersession（版本链）、admission 与 git 提交。手工去改 SQLite 索引、或者绕过 wiki 层直接操作文件，等于破坏了"索引可从事实源重建"的整个承诺。正确的"人肉维护"姿势是：直接编辑 markdown（watcher 会检测并重新索引），或者用 memory_write_page / 管理端接口，然后把重建交给 reindex。

落地清单：权限、备份、遗忘策略三件事

如果说前两个误区是"用错了心智模型"，那么这三件事就是团队真正上线时必然会撞上的工程问题。项目在这三块的实现相当完整，但恰恰因为默认值偏保守，很多团队会误读默认配置的含义。

第一件：权限——默认无认证是"设计如此"，但只对单机成立

安全模型文档 开宗明义：默认绑定 127.0.0.1:49374 且无认证，是因为对单用户笔记本这是安全的——机器外的进程够不着它。一旦把服务暴露到局域网或公网，必须开认证：设置 AI_MEMORY_AUTH_TOKEN（ai-memory generate-auth-token 生成），或绑定 loopback。

按团队规模分层对照：

• 单机单人：loopback + 无认证即可，config.toml 默认值已经正确。
• 局域网/远程：bearer token 只是认证，不加密传输。文档明确要求用 Caddy 或 Cloudflare Tunnel 反向代理模板 终结 TLS；非 loopback 绑定还要设 AI_MEMORY_ALLOWED_HOSTS 防 DNS rebinding。
• 多人共享服务器：多用户模式下每个写操作按人归因（users 表 + aim_ API key），/admin/* 立即变为 root-only。如果团队之间要互相隔离项目，需要开启 按项目授权：project_grants 表 + projects.access_mode（默认 open），把项目设为 restricted 后，只有 root、项目创建者和持有 read/write 授权的用户能访问，匿名一律拒绝，越权捕获直接丢弃且不重试。
• Handoff 归属：多人服务器上，Handoff 默认归创建者私有，只有显式 shared: true 才向项目内所有人开放。跨人交接踩坑的常见场景就是"我以为 teammates 能看到我的交接，实际看不到"。

一个容易被忽视的点：wiki 里存的不是抽象知识，而是智能体会话期间看到的一切经过脱敏的内容——提示词、工具输出都可能含敏感信息。备份文档 直言：脱敏器会去掉明显的凭据，但无法证明每个 prompt 都安全。所以权限的边界要延伸到备份侧（见下一条）。

第二件：备份——git push 就是一半的备份方案

因为 wiki 本身就是 git 仓库，一半的备份已经做好了：备份文档 建议 git push 把 wiki 推到任何你拥有的远端，配合按需的 ai-memory backup --to <tarball>（基于 SQLite online backup API，源库可继续写入）。

关键的分层决策：

目录	要不要备份	原因
wiki/	必须	markdown 事实源，不可再生，且自带 git 历史
raw/	看需求	不可变会话日志，不备份不影响 wiki 工作
db/	不要	SQLite 是派生索引，ai-memory reindex 可重建；提交 WAL 模式数据库进 git 每次写入都膨胀仓库
logs/、models/	不要	追踪输出与可重下载权重

踩坑点集中在两处：一是把 db/ 当宝贝备份，白占空间还容易在恢复时和新版 schema 打架；二是把 wiki 推到远端却忘了它可能含敏感内容。文档给出的方案从保守到激进排列：.gitignore 排除 config/*.env、auth.json 等凭据文件；内容敏感就用 restic/borg 加密快照、git-crypt 定向加密 wiki 路径，或 age 加密 tarball 扔到第二位置。先想清楚"wiki 里有什么"，再决定备份往哪放。

第三件：遗忘策略——默认只开"保留下限"，重写类操作默认全关

记忆系统没有遗忘策略就是灾难：知识越积越多，检索信噪比崩掉，磁盘与索引膨胀。ai-memory 的遗忘设计在 记忆老化设计文档 里，核心是一条纯函数保留公式（retention_score）：

retention = salience·exp(−λ·age_days) + σ·ln(1+access_count)·exp(−μ·days_since_access)·breadth

默认参数：λ=0.02（约 35 天半衰期）、σ=0.6、μ=0.04、cold_threshold=0.20、hard_delete_after_days=180。两个容易被误解的设计：

• "用得多就忘得慢"是内置行为：access_count + last_accessed_at 会因检索、翻页、链接遍历而累加（bump_access_for_pages_for_actor，异步、节流、且不重写 FTS 索引）。所以"经常被读到的记忆"衰减得更慢，且这一路默认开启，因为它只会让记忆留得更久。
• 重写/删减类操作默认关闭：compaction、去重、按层衰减曲线默认不开；开 LLM 的"dream"整理更是 opt-in。原因是这些操作不可逆地改变内容。唯一默认开启的删除路径是：frontmatter expires_at 到期（TTL 硬删）、episodic 层低于冷阈值转 tombstone、以及 180 天后 tombstone 连同版本谱系一起 purge。semantic / procedural 层和 pinned 页面永不衰减。

给团队的操作建议：

1. 先定 TTL：给有实效性的页面写 expires_at，让时效性知识自动退场，而不是靠人肉删。
2. 用 tier 管理价值分层：不想让某页被遗忘就 pinned；想让 episodic 笔记活得更久、working 草稿更快退场，可配 per-tier 半衰期覆盖。
3. 谨慎开启 observation prune（[decay] observation_retention_days）：原始观测是整合的输入，prune 后该会话永远无法重新整合——换更好的模型、更好的提示词都不行。它在"该会话的摘要页仍然存活"的前提下才执行，属于不可逆操作，上线前务必评估。

一点收尾：用架构图对齐认知

团队评估或培训时，建议直接看 架构总览图：实线是请求/读/写路径，虚线是后台对账与 provider 维护路径，核心不变式就是"markdown wiki 是事实源、SQLite 是派生索引"。把这张图贴进团队文档，能避免 80% 的认知错位。

结语

ai-memory 在竞品对比表（对比文档）里把自己和 Mem0、Zep、mcp-memory-service、basic-memory 等逐一做了定位区分，共同主题是：你拥有的文件（git 管理的 markdown）、零 LLM 默认、单二进制、跨智能体/跨机器/跨团队共享、生命周期钩子自动捕获、类型化且仅认领一次的 Handoff。落地它最忌照搬"向量库"的操作手册。把检索心智切回"结构良好的可编译知识"，把运维心智建立在"事实源/派生索引/不可逆操作"三层边界上，这套系统才会真正成为团队的知识资产，而不是另一个需要专人伺候的语义搜索服务。