waku-agent记忆系统全解：一个SQLite文件如何教会AI长期记忆
【免费下载链接】waku-agentWaku Waku! Waku Agent is a local-first AI agent harness you actually own, including loop, memory, eval, all in code built to stay legible as it grows.项目地址: https://gitcode.com/gh_mirrors/wa/waku-agent
waku-agent 是一个本地优先（local-first）的 AI 智能体框架，它的长期记忆系统几乎全部装在一个 SQLite 文件（state.db）里——没有黑盒向量库，你可以随时打开、读懂、甚至直接编辑它。这篇指南带你拆解 waku-agent 的记忆系统：三大记忆支柱、一个"该不该查"的检索门、以及把聊天蒸馏成事实的巩固流程，看它是如何让 AI 拥有真正可用的长期记忆。
💡 一句话理解：waku-agent 把"记忆"当成主角，用最小、可读、可拥有的一套代码，把 AI 的长期记忆落到一个你能打开的文件里。
为什么"记忆"是 waku-agent 的主角
大多数 agent 把重点放在工具调用和循环上，waku-agent 却把记忆系统放在了 C 位。项目 README 直接写道："Memory is the hero"——它认为，一个助手最值钱的不是会调多少工具，而是记得你是谁、发生过什么。
从这张系统白板图可以看到，waku-agent 的记忆围绕一个state.db（SQLite + FTS5）展开，分出三条支路：语义记忆（持久事实）、情景记忆（带日期的事件）、程序记忆（技能）。下面逐一拆解。
三大记忆支柱：facts / episodes / skills
| 支柱 | 回答什么问题 | 存储位置 | 检索方式 |
|---|---|---|---|
| 语义记忆 Semantic | "什么长期为真？" | facts表 | FTS5 关键词（BM25） |
| 情景记忆 Episodic | "上周几发生了什么？" | episodes表 | FTS5 相关性 + 时间最近 |
| 程序记忆 Procedural | "该怎么做？" | SKILL.md文件 | 关键词匹配，按需加载 |
三者的代码分别落在 waku/memory/semantic/store.py、waku/memory/episodic/store.py 与 waku/memory/procedural/loader.py，统一由 waku/memory/init.py 里的Memory门面类对外暴露。
语义记忆：只存"值得记一个月"的事实
语义记忆存的是关于你、你的人、你的项目的持久事实，例如"Alex 喜欢上午开会"。它刻意不用向量、不用 embedding，而是用 SQLite 的 FTS5 全文索引做关键词检索（BM25 排序）。对单用户量级的数据来说，关键词检索足够快、完全本地，而且——这是关键——你能用 sqlite3 直接读整个索引。
情景记忆：带日期的"发生了什么"
情景记忆回答"上周二和 Sergey 游泳了吗"这类带时间的问题。每一条都带一个happened_at日期，检索时把相关性（FTS 排名）和新鲜度（时间最近）结合起来，正是架构图里那句 "RAG for relevance + SQL for recency"。
程序记忆：会自己长大的技能文件
程序记忆是一堆SKILL.md——教 agent"怎么做某类事"的说明书。它采用渐进式披露：所有技能的 frontmatter 永远被轻量扫描，但某个技能的正文只在和当前消息匹配时才加载进提示词。这样 agent 的"方法论"也能沉淀、也能随你教它而生长。
一个 SQLite 文件装下全部记忆
waku-agent 所有记忆和状态都写在~/.waku/state.db这一个文件里，没有任何外部服务。schema 就写在 waku/db.py 的SCHEMA里，核心就四张表：
| 表 | 作用 |
|---|---|
facts | 语义记忆：主体(subject)+内容(content)，带 FTS5 索引facts_fts |
episodes | 情景记忆：日期(happened_at)+摘要(summary)，带episodes_fts |
chat_log | 原始聊天记录，按session_id分会话，是巩固的原料 |
calendar_events | 日历工具产生的事件，供确定性测试断言 |
除了这个"可查询的真相来源"state.db，waku-agent 每轮对话后还会重新生成一份人类可读的~/.waku/MEMORY.md，把 facts 和 episodes 平铺成 markdown。于是"你的记忆是一个你能打开的文件"这句话是字面成立的。
检索门：先问"这一轮需要记忆吗" 🚪
很多 agent 每轮都去查记忆库，代价是又慢、又容易被无关记忆带偏。waku-agent 的解法叫检索门（retrieval gate），它是项目文档里标注的 "hero moment #1"，代码在 waku/memory/retrieval_gate.py。
在碰任何存储之前，先用一个便宜的小模型回答一个问题：这条消息到底需不需要用户的记忆？
"2+2 等于几？"→ 不需要（跳过）"我什么时候和 Alex 见面？"→ 需要（去查，并生成检索词）
门是**失败开放（fail open）**的：万一判断本身出错，就照常去检索——"过时的记忆好过丢失的记忆"。这样只有真正有用的轮次才付出检索成本。
巩固：每 6 轮把聊天蒸馏成事实 ⏳
光"存"不够，还要会"提炼"。waku-agent 的**巩固（consolidation）**逻辑在 waku/memory/consolidation.py：每攒够 N 轮（默认WAKU_CONSOLIDATE_EVERY=6）未提炼的对话，就让一个小模型去读这些原始聊天，产出两样东西：
- facts→ 写进语义记忆（"Alex 喜欢上午开会"）
- episode→ 写进情景记忆（"2026-07-10：和 Alex 规划了 Acme 演示"）
批处理 N 轮而不是每条都跑摘要，是因为攒够上下文，模型才提取得准。巩固还会做两件事防止记忆污染：研究报告轮次最多留 2 条关于"用户本人"的事实（结论已存进报告，不再重复）；回忆轮次会用确定性检查丢掉只是复述已有记忆的内容。
槽位门：只让真正重要的事实进门
waku-agent 还预留了一个可选的槽位门（slot gate，Jev），在 waku/memory/slot_gate.py。它对每条拟存的事实打分，问"未来的回答会需要它吗？"，低于阈值的直接丢弃。默认关闭、失败开放，打开它需要WAKU_SLOT_GATE=jev。它的效果在 lab/jev-system-one 的实验里被验证：记忆检索准确率能到 12/12。
把记忆共享给其他 Agent 🌐
本地记忆之外，waku-agent 还能通过Waku Memory把同一份记忆共享给 Claude Code、Codex 等其它 agent——在本机保存的东西，在别处能直接调出来。
接入方式是一条命令：waku connect waku-memory（或在 dashboard 聊天里/connect waku-memory）。详细用法见 docs/integrations.md。
动手：打开并读懂你的记忆
想亲自看 waku-agent 的记忆系统长什么样，克隆下来跑起来即可：
git clone https://gitcode.com/gh_mirrors/wa/waku-agent && cd waku-agent uv venv && uv pip install -e . cp .env.example .env # 选一个 provider，粘贴一个 key uv run waku然后试一句："记住 Alex 喜欢上午的会议。"退出、重启，再问"约 Alex 周五碰面"——它会记得，并且约在上午。
要直接查看记忆，有两个入口：
- 命令行：
sqlite3 ~/.waku/state.db ".tables"，再select * from facts; - 浏览器：
waku dashboard打开 Memory 页，可增删改每条 fact、重写SOUL.md
完整的记忆后端对比（SQLite / Supabase / Mem0 / Zep / LangMem）见 docs/memory-backends-playbook.md。
小结
waku-agent 的记忆系统，把"AI 长期记忆"这件玄学拆成了三张可读的表、一个"该不该查"的门、一段"该留什么"的巩固逻辑——全部落在一个你能打开的 SQLite 文件里。它不追求黑盒式的智能，而是追求可拥有、可读懂、可修改。这也是它区别于一众封装成产品的大型助手的地方：这套记忆代码，是你自己的。
更多细节可以看 docs/architecture.md 和 docs/tour.md。
【免费下载链接】waku-agentWaku Waku! Waku Agent is a local-first AI agent harness you actually own, including loop, memory, eval, all in code built to stay legible as it grows.项目地址: https://gitcode.com/gh_mirrors/wa/waku-agent
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
