Waku
可在自己电脑上运行、可读可改的本地优先个人助手。
这个 Agent 能做什么，适合哪些场景？
Waku 是一个本地优先的个人 AI 助手，核心由 Python 编写的 agent loop、SQLite 记忆、工具调用和评测/追踪组件构成。它通过终端、localhost:7777 仪表盘、Telegram 和可选语音入口接收同一会话中的消息，并在本机进程中执行每轮对话。记忆保存在 `.waku/state.db`，包含语义、情节和程序性记忆，并生成可读的 `.waku/MEMORY.md` 镜像。系统可调用日历、笔记、网页搜索等工具，记录每轮 trace、token 与估算成本，并提供确定性评测和 LLM-as-judge 发布门禁。它适合想拥有并理解个人助手核心机制的开发者或高级个人用户，而非需要托管式成品助手的人。
用户可用 waku 在终端聊天，或运行 waku dashboard 打开本机 127.0.0.1:7777 的浏览器界面；配置 TELEGRAM_BOT_TOKEN 后也可接收 Telegram 消息，waku voice 可通过“waku waku”唤醒词或按键通话。每轮消息先组成包含 SOUL.md、记忆和历史的工作记忆；waku/memory/retrieval_gate.py 决定是否检索 SQLite 中的 facts 与 episodes；随后 waku/loop/agent.py 反复调用模型、执行工具并把结果放回消息上下文，直到模型回复或达到最大迭代数。它可用 create_event 和 list_events 管理本地日历数据、用 save_note 等记忆工具保存信息，并可用 search_web 搜索网页。每轮会写入 .waku/traces/<date>.jsonl，token 用量追加到 .waku/usage.jsonl；make eval、make eval-judge 和 make gate 分别运行确定性评测、裁判评测和发布门禁。
- 希望在自己的笔记本上保留可检查 SQLite 记忆的个人用户，用它记住联系人偏好并在之后安排会议。
- 需要从终端或本地浏览器统一处理个人日程的开发者，用 `create_event`、`list_events` 查看和创建事件。
- 想观察工具调用、检索决策、迭代次数、token 与成本的 AI 工程学习者，使用 Dashboard 的 Loop、Memory 和 Ops 页面分析每轮运行。
- 希望通过手机消息触发本机助手的用户，配置 Telegram bot token 后以长轮询方式运行 `waku telegram`。
- 需要把外部 MCP 服务工具接入个人助手的用户，安装 `[mcp]` extra 并在 `.waku/mcp.json` 中声明服务器。
- 想为早晨工作安排生成摘要的 macOS 用户，授权 Calendar.app 和 Apple Mail 后运行 `WAKU_APPLE_TOOLS=1 make brief`。
这个 Agent 有哪些优点和局限？
- 记忆以本地 SQLite `state.db` 保存，并提供 `.waku/MEMORY.md` 可读镜像，用户可直接检查和编辑数据。
- 核心 loop、检索 gate、图工作流和追踪模块均以明确文件路径呈现，适合逐步阅读和定制。
- 同一运行时支持终端、本地 Dashboard、Telegram 与可选语音入口，消息来源会被标记。
- 将确定性测试与 DeepEval 的 LLM-as-judge 评测分开，并提供 `make gate` 发布门禁和评测历史。
- 首次可用需要选择模型提供商并配置相应密钥；模型调用与可选网页搜索、Telegram 等功能依赖网络。
- 本地日历和记忆是默认权威数据；Google Calendar 镜像只写入新建事件，而 `list_events` 仍读取本地数据库。
- Apple Calendar 与 Apple Mail 简报仅面向 macOS，且需要授予系统权限。
- 部分路线图工具仍是 skeleton；例如 `run_command`、`browse_web` 和 `schedule_task` 标为尚未实现的完整功能。
如何安装或部署这个 Agent？
快速安装：pip install waku-agentwaku
首次运行会提示需要设置的模型密钥。
如需阅读或修改源码：git clone https://github.com/ShenSeanChen/waku-agent && cd waku-agentuv venv && uv pip install -e .cp .env.example .env
在 .env 中选择 WAKU_PROVIDER= 并填入一个已支持提供商的密钥；README 列出 Anthropic（默认）、OpenAI、Gemini、DeepSeek、MiniMax、Kimi、GLM、OpenRouter、OpenCode Zen 和 OpenCode Go。随后运行 uv run waku。
如何使用这个 Agent？
运行 waku 开始终端对话；运行 waku dashboard 启动本机仪表盘并访问 http://localhost:7777。例如，可输入“Remember that Alex prefers morning meetings.”，重启后再询问与 Alex 的会议安排。运行 make eval 执行确定性评测，运行 make gate 执行完整发布门禁。可选功能需额外配置：Telegram 需要 pip install -e '.[telegram]' 和 TELEGRAM_BOT_TOKEN；语音需要 uv pip install -e '.[voice]'；MCP 需要 pip install -e '.[mcp]'。
这个 Agent 与同类方案有什么区别？
README 将 Waku 与 ChatGPT、Claude Desktop 等可直接使用的产品区分：Waku 的定位是让用户拥有并修改 loop、记忆 schema、检索 gate 与评测 harness。它也将自己与 OpenClaw、Hermes 等较大型开源助手对比，强调较小、可在短时间阅读的代码规模。作为记忆方案，它以 SQLite FTS5 为默认，并列出 Supabase pgvector、mem0、Letta 与 Zep 作为升级或替代路径。