Waku
A local-first personal assistant whose loop, memory, tools, and evals you can inspect and modify.
What does this agent do, and when should you use it?
Waku is a local-first personal AI assistant built around a plain-Python agent loop, SQLite memory, tool calls, and evaluation and tracing components. It accepts messages through a terminal CLI, a dashboard at localhost:7777, Telegram, and an optional voice interface, with turns executed by a process on the user's machine. Its semantic, episodic, and procedural memory is stored in `.waku/state.db`, with a human-readable `.waku/MEMORY.md` mirror. The assistant can operate calendar, note, and web-search tools while recording traces, token usage, and estimated costs. It is a strong fit for developers and advanced users who want to own and study a personal assistant's mechanics, rather than adopt a managed consumer product.
Users can chat with waku in a terminal or run waku dashboard for a browser UI on 127.0.0.1:7777; with TELEGRAM_BOT_TOKEN, it can also receive Telegram messages, and waku voice supports a “waku waku” wake word or push-to-talk. For each turn, it builds working memory from SOUL.md, stored memory, and conversation history; waku/memory/retrieval_gate.py decides whether to retrieve facts and episodes from SQLite. waku/loop/agent.py then repeatedly calls a model, runs requested tools, and feeds tool results back into the message context until the model replies or the iteration limit is reached. The documented tools include create_event, list_events, save_note, and search_web. It appends turn events to .waku/traces/<date>.jsonl and token usage to .waku/usage.jsonl; make eval, make eval-judge, and make gate run deterministic evaluation, LLM-as-judge evaluation, and the combined release gate.
- A privacy-conscious individual who wants preferences and past conversations stored in an inspectable local SQLite file, then asks Waku to schedule follow-ups with those preferences in mind.
- A developer managing personal events from a terminal or local browser interface, using `create_event` and `list_events` against Waku's local calendar data.
- An AI engineer learning agent-loop behavior who inspects retrieval decisions, tool calls, iterations, tokens, costs, and JSONL traces in the Dashboard.
- A user who wants to message a laptop-hosted assistant while away from the laptop, configuring a Telegram bot and running `waku telegram` with long polling.
- A user who needs external tools in a personal assistant, installing the MCP extra and defining servers in `.waku/mcp.json`.
- A macOS user who wants a focus-first morning briefing based on Calendar.app, recent Apple Mail, and stored memory, using `WAKU_APPLE_TOOLS=1 make brief`.
What are this agent's strengths and limitations?
- Memory is stored in a local SQLite `state.db` and mirrored into an inspectable `.waku/MEMORY.md` file, so users can examine and edit their data.
- The loop, retrieval gate, graph workflow, and tracing components are mapped to specific source files, making the system practical to read and customize.
- One runtime supports terminal, local dashboard, Telegram, and optional voice entry points, with each message tagged by source.
- It separates deterministic tests from DeepEval LLM-as-judge scoring, and provides a `make gate` release gate plus evaluation history.
- A working setup requires selecting a model provider and configuring its key; hosted models and optional web search, Telegram, and calendar integrations require network access.
- The local SQLite calendar remains authoritative; Google Calendar mirroring only writes created events, while `list_events` still reads the local database.
- Apple Calendar and Apple Mail briefing support is macOS-only and requires system permissions.
- Several roadmap tools remain skeletons, including `run_command`, `browse_web`, and `schedule_task`.
How do you install or deploy this agent?
Quick install:pip install waku-agentwaku
On first run, Waku tells you which model key to set.
To inspect or modify the source:git clone https://github.com/ShenSeanChen/waku-agent && cd waku-agentuv venv && uv pip install -e .cp .env.example .env
Choose WAKU_PROVIDER= and add one supported provider key in .env. The documented providers are Anthropic (the default), OpenAI, Gemini, DeepSeek, MiniMax, Kimi, GLM, OpenRouter, OpenCode Zen, and OpenCode Go. Then run uv run waku.
How do you use this agent?
Run waku for a terminal conversation, or waku dashboard and open http://localhost:7777 for the local cockpit. For example, tell it “Remember that Alex prefers morning meetings.”, restart it, and then ask it to arrange a catch-up with Alex. Run make eval for deterministic checks and make gate for the full release gate. Optional interfaces require extra setup: Telegram needs pip install -e '.[telegram]' and TELEGRAM_BOT_TOKEN; voice needs uv pip install -e '.[voice]'; MCP needs pip install -e '.[mcp]'.
How does this agent compare with similar options?
The README contrasts Waku with products such as ChatGPT and Claude Desktop: Waku is intended to let users own and change the loop, memory schema, retrieval gate, and evaluation harness. It also contrasts its smaller, readable codebase with larger open-source assistants including OpenClaw and Hermes. For memory, SQLite FTS5 is the default, while Supabase pgvector, mem0, Letta, and Zep are listed as upgrade or alternative paths.