A Local-First Agent You Can Actually Read: Inside Waku
Most agent frameworks ask you to trust a black box. You install a pile of dependencies, wire up some abstractions, and hope the thing remembers what you told it yesterday. But what if you could open the memory file, read the loop, and understand the whole system in an afternoon? That's the pitch behind Waku, a local-first personal assistant built to show you the four pillars of a serious agent without hiding the good parts.
What It Does
Waku is a local-first personal assistant that runs on your laptop. It's built around four pillars: Harness, Loop, Memory, and Eval/LLM-Ops. The core agent loop is roughly 95 lines of plain Python, which means you can step through it line by line and see exactly how a message flows from input to response.
Memory is the centerpiece here. Waku splits it into three types—semantic, episodic, and procedural—and adds a gate that decides whether to remember something at all, plus a pass that decides what to keep. All of it lives in a single SQLite file at ~/.waku/state.db. You can open it, read it, and it's yours. The same memory file works from any folder on your machine.
There's also a local dashboard that lights up every message as it moves through the harness, so you can watch the agent think in real time. And evals are built in: deterministic tests and LLM-as-judge run side by side, with a release gate to keep things honest. On the provider side, Waku works with Anthropic (the default), OpenAI, Gemini, DeepSeek, MiniMax, Kimi, GLM, OpenRouter, OpenCode Zen, and OpenCode Go. A roughly 60-line adapter handles the differences between them, so the loop itself only speaks one dialect.
Why It's Cool
The memory is a file, not a service. This is the detail that stands out. Instead of shipping your conversation history off to some vector database you'll never inspect, Waku writes everything to one SQLite file. You can query it, back it up, delete it, or move it between machines. That's a meaningful difference from most agent setups, where memory is opaque by design.
The loop is small enough to actually read. Ninety-five lines is short. Short enough that you'll finish it in one sitting and come away understanding what every agent framework is doing under the hood. If you've ever wanted to build your own agent but got lost in abstraction layers, this is a solid reference implementation.
The gate-and-pass memory design is thoughtful. Deciding whether to remember something is a different problem from deciding what to keep. Waku treats them as separate steps, which is a design choice worth paying attention to if you're building anything with long-term context.
Provider flexibility without the usual mess. You probably already pay for one of these models. Waku lets you use it by setting WAKU_PROVIDER= and pasting a key. The adapter pattern keeps the loop clean while still supporting a wide range of providers.
The dashboard lets you watch it think. A browser cockpit at localhost:7777 that shows messages flowing through the harness is a genuinely useful debugging tool. It turns an otherwise invisible process into something you can observe.
Evals are not an afterthought. Having both deterministic tests and LLM-as-judge, plus a release gate, puts Waku ahead of a lot of hobby agent projects that skip evaluation entirely.
How to Try It
If you just want to run it, the install is two commands:
pip install waku-agent
waku
That drops you into a terminal chat with your Waku. It'll tell you which API key to set the first time. You can also fire up the browser cockpit:
waku dashboard
If you want to read the code (which is kind of the point), clone the repo instead:
git clone https://github.com/ShenSeanChen/waku-agent && cd waku-agent
uv venv && uv pip install -e .
cp .env.example .env
uv run waku
uv run waku dashboard
Once it's running, try this: tell it "Remember that Alex prefers morning meetings." Quit. Restart. Then say "Book a catch-up with Alex on Friday." It should remember and book 9am. That's the memory working end to end.
There's also a 20-minute code walkthrough video covering the loop, the memory pillars, the evals, the Telegram gateway, and the "Waku Waku" wake word. And if you want to share memory across agents, Waku Memory is a hosted option you can connect with waku connect waku-memory after installing the MCP extras.
The repo is at github.com/ShenSeanChen/waku-agent.
Final Thoughts
Waku isn't trying to be the most powerful agent framework out there, and it doesn't pretend to be. What it offers is transparency—a small, readable implementation of the core ideas behind agent design, with memory you can inspect and evals you can trust. If you're learning how agents work, want a local assistant you actually control, or just want to see what a clean 95-line loop looks like, this is worth an afternoon. The fact that your memory lives in one SQLite file you own is the kind of thing more projects should copy.
Follow @githubprojects for more developer tools and open source projects.