waku-agent：把 agent 的循环、记忆和评测摊开成一个下午能读完的 Python 仓库

它要解决的是「看不懂」，不是「不够强」

多数 agent 框架的问题不在能力，而在你无法回答一个简单问题：这一轮到底发生了什么。检索是走了还是跳过了，工具被调了几次，记忆什么时候写进去的，成本花在哪一步。waku-agent 把这件事当成主要矛盾。仓库描述里写得很直白，它要做一个你真正拥有的本地优先 agent harness，包含 loop、memory、eval，全部是代码，并且设计目标是「随着增长仍然保持可读」。README 的措辞是「No frameworks hiding the good parts」，循环大约 95 行纯 Python。这个定位决定了它的取舍：它不会在抽象层上帮你省事，反而要求你愿意读实现。目标读者是个人开发者、想理解 agent 内部结构的学习者，以及需要把助手跑在自己机器上、不希望记忆外流的人。它不是一个给团队做基础设施的产品。

四根柱子如何落到具体文件上

README 把系统拆成 Harness、Loop、Memory、Eval/LLM-Ops 四部分，并且给出了一张架构白板图，声称「每个方框都对应一个文件」。这是这个项目比较少见的地方：文档不是先讲概念再让你猜代码在哪，而是反过来，从图直接指到文件。记忆被分成三类，语义、情景、程序性，对应 dashboard 的 Memory 标签页下的子标签，其中程序性记忆以可编辑的 skills 和 SOUL 的形式出现。模型接入被压缩成一层适配：循环里只认一种方言，其余由 waku/loop/models.py 这个约 60 行的适配器处理。README 列出的 provider 包括 Anthropic（默认）、OpenAI、Gemini、DeepSeek、MiniMax、Kimi、GLM、OpenRouter、OpenCode Zen、OpenCode Go。把多 provider 差异收敛到单个小文件里，是一个明确的可读性选择，代价是每个新 provider 的边界情况都要在这一个文件里处理。

检索门控：先决定要不要记，再决定留什么

记忆部分有两个机制值得单独看。一个是 gate，决定「是否要记住」；另一个是 pass，决定「保留什么」。README 把它描述为语义、情景、程序性三类记忆之上的两层判断。检索侧同样有门控：README 给出的示例里，先问「When am I swimming with Sergey?」再问「what's 12 × 8?」，前者触发 retrieve，后者触发 skip，dashboard 的 Overview 标签页会显示 gate 的 skip/retrieve 比例，Ops 标签页显示每一轮的决策。这个设计的意义在于把「要不要查记忆」变成一个显式的、可观测的决策，而不是每轮无脑注入上下文。需要说明的是，仓库材料没有给出这个门控的具体判定方式，是规则、分类器还是模型调用，从 README 无法确认，只能去读代码。

从安装到跑起来：三条命令路径

只运行的话，README 给的是 pip install waku-agent，然后 waku 进入终端对话，waku dashboard 起本地服务，地址是 localhost:7777。想读代码或参与开发则走 clone：git clone 之后 uv venv 建环境，uv pip install -e . 安装 waku 命令，cp .env.example .env 然后填一个 provider 的 key，最后 uv run waku 或 uv run waku dashboard。README 明确说 uv run 不需要激活虚拟环境，并列出三种等价方式：uv run waku dashboard（推荐，零激活）、source .venv/bin/activate 之后直接敲 waku、以及 uv tool install . 把 waku 全局装好。dashboard 是一个跑在 127.0.0.1 上的小型 web 服务器，前端是纯静态文件，没有构建步骤。如果设置了 TELEGRAM_BOT_TOKEN，同一个进程会顺带把 Telegram bot 也起起来。make dashboard 和 make run 是等价的快捷方式。

状态只有一个文件，这是优点也是约束

所有记忆落在 .waku/state.db 这一个 SQLite 文件里。README 的示例流程是：说「Remember that Alex prefers morning meetings」，退出，重启，再说「Book a catch-up with Alex on Friday」，它会记得并订在 9 点。dashboard 的 Data 标签页提供实时的 SQLite 浏览器，按表分标签，有 schema，还有一个对 state.db 的只读 SQL 控制台。这个设计让「你的记忆是你的」这句话可以被验证，你可以直接用 sqlite3 打开它。代价同样明显：单文件意味着并发写入受 SQLite 的锁机制约束，多进程同时写会互相阻塞。README 没有讨论多用户、多租户或并发写入的扩展路径，所以把它当成单用户本机助手是符合材料的读法，当成多人共享的服务端组件则没有依据。

评测带发布门禁，但材料只到这里

Eval 被列为核心支柱之一，README 的说法是确定性测试和 LLM-as-judge 并排存在，并且有一个 release gate。dashboard 的 Ops 标签页显示 eval 结论、历史记录、门控决策、最慢的轮次和内联的 JSONL trace。把评测和发布门禁绑在一起，意味着修改循环或记忆逻辑之后有一个可执行的判断标准，而不是靠手感。但需要坦白地说：仓库给出的材料没有列出具体的评测用例、判分标准、门禁阈值，也没有说明 LLM-as-judge 用哪个模型、成本如何计入。这些只能从代码里读。对打算采用的人来说，这是第一个应该去仓库确认的点，因为它直接决定这个门禁是真能拦住回归，还是只是仪表盘上的一块装饰。

什么时候它是错的工具

waku-agent 自称是 local-first 的个人助手，这个定位本身就是它的边界。如果你的需求是给多个用户提供隔离的会话和配额，单个 state.db 加上本机进程的模型并不匹配，README 也没有给出任何多租户线索。如果团队希望的是托管服务、托管向量库、开箱即用的运维面板，这个项目把复杂度交还给了你：你要自己管进程、自己管备份、自己管密钥。另一个实际约束是版本节奏。发布记录显示 v0.1.0 是首个带标签的版本，v0.1.1 加入了 agent graphs，两者相隔几天。图工作流这条路径在材料里只有 dashboard 的 Graph 标签页描述，说是从引擎本身画出实时的 triage 拓扑，除此之外没有更多细节。把生产负载压在这条路径上之前，值得先在代码里确认它的错误处理和持久化方式。

和通用编排框架的差别在哪

拿它和 LangChain、LlamaIndex 这类通用编排框架对比，差别不在功能清单，而在抽象层级的方向。通用框架的做法是提供抽象，你写声明式的东西，框架在下面拼装，代价是出问题时你要穿透好几层才能定位。waku-agent 反过来：循环约 95 行，模型差异收在一个约 60 行的适配器里，记忆是一个你可以用 SQL 直接查的文件。你得到的是可追踪性，付出的是自己写更多胶水代码。这不是谁更先进的问题，是两种不同的成本分配。如果你的团队里有人愿意读 Python 并且需要精确控制每一轮的行为，前者的抽象会变成阻碍；如果你需要快速接十几种数据源和检索器，自己写胶水的成本会迅速超过收益。

维护成本与许可

项目采用 MIT 许可，仓库未归档。MIT 允许商用和修改，但按惯例不提供任何担保，具体条款以仓库里的 LICENSE 文件为准，这里不构成法律意见。维护成本主要来自三处。一是 provider 适配，模型厂商的 API 会变，waku/loop/models.py 这个收敛点需要跟着改，好处是只改一处。二是记忆 schema，state.db 是你的数据，升级时如果表结构变化，迁移要你自己处理，README 没有提到迁移工具。三是评测门禁本身，LLM-as-judge 会带来额外的模型调用成本，这部分在 README 里没有给出量化的说法。发布节奏上，两个版本相隔数天，说明项目还在早期，跟进升级前建议先看 release notes 里对 agent graphs 的描述。

编辑结论

适合已经能读 Python、想看清 agent 每个环节怎么接起来的人，以及需要一个完全跑在本机、记忆归自己所有的个人助手的人。不适合需要多租户隔离、需要托管服务、或者团队里没人愿意读源码只想要黑盒 API 的场景。上手前先确认三件事：README 提到首次运行会提示需要设置哪个 key，先把 provider 和对应密钥定下来；.waku/state.db 是唯一的状态载体，先决定它放在哪、怎么备份；v0.1.1 才加入 agent graphs，两个发布版本之间只隔了几天，图工作流这条路径的成熟度需要你自己在代码里确认，而不是看版本号。

官方来源

1. Issues
2. License: MIT
3. README
4. Releases
5. ShenSeanChen/waku-agent on GitHub