waku-agent记忆系统全解：一个SQLite文件如何教会AI长期记忆

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-agentwaku-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.dbSQLite 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_ftsepisodes情景记忆日期(happened_at)摘要(summary)带episodes_ftschat_log原始聊天记录按session_id分会话是巩固的原料calendar_events日历工具产生的事件供确定性测试断言除了这个可查询的真相来源state.dbwaku-agent 每轮对话后还会重新生成一份人类可读的~/.waku/MEMORY.md把 facts 和 episodes 平铺成 markdown。于是你的记忆是一个你能打开的文件这句话是字面成立的。检索门先问这一轮需要记忆吗 很多 agent 每轮都去查记忆库代价是又慢、又容易被无关记忆带偏。waku-agent 的解法叫检索门retrieval gate它是项目文档里标注的 hero moment #1代码在 waku/memory/retrieval_gate.py。在碰任何存储之前先用一个便宜的小模型回答一个问题这条消息到底需不需要用户的记忆22 等于几→ 不需要跳过我什么时候和 Alex 见面→ 需要去查并生成检索词门是**失败开放fail open**的万一判断本身出错就照常去检索——过时的记忆好过丢失的记忆。这样只有真正有用的轮次才付出检索成本。巩固每 6 轮把聊天蒸馏成事实 ⏳光存不够还要会提炼。waku-agent 的**巩固consolidation**逻辑在 waku/memory/consolidation.py每攒够 N 轮默认WAKU_CONSOLIDATE_EVERY6未提炼的对话就让一个小模型去读这些原始聊天产出两样东西facts→ 写进语义记忆Alex 喜欢上午开会episode→ 写进情景记忆2026-07-10和 Alex 规划了 Acme 演示批处理 N 轮而不是每条都跑摘要是因为攒够上下文模型才提取得准。巩固还会做两件事防止记忆污染研究报告轮次最多留 2 条关于用户本人的事实结论已存进报告不再重复回忆轮次会用确定性检查丢掉只是复述已有记忆的内容。槽位门只让真正重要的事实进门waku-agent 还预留了一个可选的槽位门slot gateJev在 waku/memory/slot_gate.py。它对每条拟存的事实打分问未来的回答会需要它吗低于阈值的直接丢弃。默认关闭、失败开放打开它需要WAKU_SLOT_GATEjev。它的效果在 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），仅供参考