Waku
A local-first personal assistant whose loop, memory, tools, and evals you can inspect and modify.
- Source repo
- ShenSeanChen/waku-agent
- Stars
- ★ 2.2k
- Last updated
- 27d ago
- License
- MIT
- Primary language
- Python
- FA score
- 65/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- 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.
- Not a fit if
- People who want a managed consumer product, not a codebase to read
- Non-macOS users needing Apple Calendar or Mail briefings
- Source review
- 65/100 · Some gaps
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_eventandlist_eventsagainst 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 telegramwith 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.
How do you install or deploy this agent?
Quick install:
pip install waku-agent
wakuOn 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-agent
uv venv && uv pip install -e .
cp .env.example .envChoose 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]'.
What are this agent's strengths and limitations?
- Memory is stored in a local SQLite
state.dband mirrored into an inspectable.waku/MEMORY.mdfile, 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 gaterelease 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_eventsstill 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, andschedule_task.
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.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Waku This agent | 65 · Some gaps | CLIFree + model costs | ★ 2.2k | 27d ago | Python | OpenAI API · Claude API |
| Ankita Desktop AI Workspace | 69 · Some gaps | Desktop appFree + model costs | ★ 15 | 7d ago | JavaScript | ChatGPT · OpenAI API |
| Memmy — Personal AI Agent & Local Memory Hub | 71 · Some gaps | Desktop appFreemium | ★ 2.2k | 2d ago | TypeScript | Codex · Claude Code · OpenAI API |
| IWE Knowledge Graph & Agent Memory | 69 · Some gaps | CLIFree | ★ 1.8k | 1d ago | Rust | Codex · Claude Code · Claude.ai |
How does FollowAgents rate this agent?
Why each dimension lost points
The material presents a local core, explains key and database locations, and places voice, messaging gateways, and MCP behind optional extras; the security policy also says community skills can call tools. Deductions reflect that the sample does not show per-tool permission gates, confirmation for external writes, or recovery paths, and the meeting skill explicitly permits scheduling when the attendee is unknown.
README, setup docs, CLI entry point, and project metadata mostly agree on core commands, Python support, and optional integrations, and describe deterministic evaluation and dependency floors. The sample omits evaluation implementations and complete execution paths, while multiple model providers, services, and optional dependencies remain availability variables; no test outcome is inferred.
The docs cover personal and developer use, multiple model providers, terminal and dashboard interfaces, plus voice, messaging, calendar, mail, and research scenarios. Skill descriptions also define triggers for research reports, meeting scheduling, and briefings. The sample does not fully establish conflict handling or refusal boundaries, and some skills give limited treatment to side effects.
Navigation is clear and installation, configuration, and checks are well documented. The license file, README, and package metadata distinguish MIT code, the Elastic License hosted component, and brand assets. The sample does not provide an actual release history or complete upgrade record; maintainer guidance exists, but these files do not establish how response and release commitments are carried out.
The product combines a readable loop, memory, evaluation, and multiple interfaces in a local assistant, with commands, setup checks, and a user-facing report format. Deductions reflect that utility and cost claims are mainly project assertions; the sample cannot establish real-world memory, scheduling, or evaluation performance and gives no complete cost comparison.
README architecture and feature claims generally point to docs, code, or commands; setup steps are checkable, package metadata explains the version source, and the report skill requires source entries and attribution of vendor claims. Key security, correctness, and evaluation claims lack corresponding implementations or independent corroboration in the supplied material, which is incomplete and cannot establish execution outcomes.
- This is a low-confidence review of the supplied static material only; no program, evaluation, or integration was run.
- Calendar, mail, messaging, and community skills can touch personal data or cause external effects. Review permissions, confirmation behavior, and recovery options, especially automatic scheduling for an unknown attendee.
- Connecting hosted memory or research services sends data to external services; the supplied material does not fully establish end-to-end data handling or costs.
Maintain this project? Add the FARS badge to your README
[](https://followagents.com/en/agents/waku-agent)<a href="https://followagents.com/en/agents/waku-agent"><img src="https://followagents.com/badge/waku-agent.svg" alt="FARS review"></a>Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
waku-agent 0.1.9: see, grade and pay for every turn What changed for you - Observability: each turn is a trace with a readable waterfall, and an Evals page shows what CI passed on your release. - Turn evals: five checks grade your own turns, and an on-demand AI judge reviews a turn you pick. - treg: every local Waku Agent can call treg, the Tools tab leads with the endpoints a turn used, and a hosted tenant can bring their own treg key. - Memory: each fact is written to ~/.waku/memory/<id>.md, and a reply says "saved" only when Waku Memory has the fact. …View on GitHub ↗ -
Release notes excerpt
What's Changed * license: the Waku brand assets are not MIT by @ShenSeanChen in https://github.com/ShenSeanChen/waku-agent/pull/194 * dashboard: cards, buttons, actions and menus from ui.js by @etsai0603 in https://github.com/ShenSeanChen/waku-agent/pull/192 * fix: "waku connect google" exists, and so does /connect google by @ShenSeanChen in https://github.com/ShenSeanChen/waku-agent/pull/195 * release: 0.1.8 by @ShenSeanChen in https://github.com/ShenSeanChen/waku-agent/pull/196 New Contributors …View on GitHub ↗ -
v0.1.1 v0.1.1 — agent graphs
Release notes excerpt
```bash pip install waku-agent ``` What's new: waku/graph/ A stdlib graph engine, and the same job done two ways so you can read them against each other. A loop discovers what to do next. A graph pre-determines what happens next. | | | |---|---| | waku brief | the morning briefing as a LOOP — one prompt, the model works out which tools to call | | waku gather | the same job as a GRAPH — GitHub, web, calendar and memory fetched together, then one digest | Measured on a live run: ``` node_start scan_github scan_web scan_calendar scan_memory …View on GitHub ↗
FAQ
Does data leave the laptop?
127.0.0.1, and memory, traces, and usage files are local. The selected hosted model provider and optional web search, Telegram, and Google Calendar integrations involve network requests.Which model providers are supported?
WAKU_PROVIDER and configure its key.How does Waku prevent an endless tool loop?
waku/loop/agent.py stops when the model no longer requests tools; otherwise, a max_iterations hard limit ends the turn.Can I add my own tools?
[mcp] extra and configure an MCP server in .waku/mcp.json; its tools are exposed as <server>_<tool>.How can I verify a change before releasing it?
make eval for deterministic checks, make eval-judge for LLM-as-judge scoring, or make gate to run both suites and apply the documented release threshold.Thanks — we use this to improve the page.