waku-agent

Your own AI assistant. On your laptop. In code you can read in an afternoon.

Meet Waku — a local-first personal assistant that shows the four pillars behind every serious agent: Harness · Loop · Memory · Eval/LLM-Ops. No frameworks hiding the good parts. Built by seanchen.io.

• Local-first. Your memory is one SQLite file. Open it. Read it. It's yours.
• Memory is the hero. Semantic + episodic + procedural — with a gate that decides whether to remember, and a pass that decides what to keep.
• The loop is ~95 lines of plain Python. Step through it.
• Watch it think. A local dashboard lights up every message as it flows through the harness.
• Eval built in. Deterministic tests and LLM-as-judge, side by side, with a release gate.

The system-design whiteboard from the series. Every box maps to a file — see the whiteboard maps to the code.

▶ Watch the 20-min code walkthrough — the loop, the memory pillars, the evals, the Telegram gateway and the "Waku Waku" wake word, live.

YouTube · X · LinkedIn · Instagram · TikTok · Discord · 哔哩哔哩 · 小红书 · 抖音

☕️ Buy me a coffee — it keeps this repo (and the videos) coming

Quickstart

Just want to run it:

pip install waku-agent
waku                                    # talk to your Waku in the terminal
waku dashboard                          # …or the browser cockpit → localhost:7777

It will tell you which key to set the first time. Want to read the code (the point of this repo) or contribute — clone it instead:

git clone https://github.com/ShenSeanChen/waku-agent && cd waku-agent
uv venv && uv pip install -e .          # create the env + install the `waku` command
cp .env.example .env                    # pick a provider, paste ONE key
uv run waku                             # talk to your Waku in the terminal
uv run waku dashboard                   # …or the browser cockpit → localhost:7777

uv run waku … needs no venv activation. Three ways to run it:

waku and waku dashboard are two doors into the same Waku. The dashboard is a tiny web server on your machine — chat in the browser, that process runs the turn. Nothing leaves your laptop. Set TELEGRAM_BOT_TOKEN and it starts your bot too. (make dashboard works as well.)

Now try it. "Remember that Alex prefers morning meetings." Quit. Restart. "Book a catch-up with Alex on Friday." → it remembers, and books 9am. Your memory is one file: .waku/state.db.

Use the model you already pay for. Anthropic (default), OpenAI, Gemini, DeepSeek, MiniMax, Kimi, GLM, OpenRouter (one key, hundreds of hosted models), OpenCode Zen, or OpenCode Go — set WAKU_PROVIDER=, paste the key, done. One dialect in the loop; a ~60-line adapter handles the rest.

Watch the harness run — the dashboard

waku dashboard          # starts a local server → http://localhost:7777

A small web server you own (127.0.0.1, no cloud). The browser is just the UI — the same process runs every turn. This is the fastest way to get the system.

A chat dock sits on every tab. Type or speak, and watch it flow through the harness on the Overview diagram: gate lights up → loop calls a tool → reply comes back → memory updates. The frontend is plain static files. No build step.

Each tab is one pillar, linked to the real files:

The sidebar and chat dock are drag-resizable and hideable, and the chat has New chat + history like any chat app.

Things to try (each shows off a pillar)

Type these in the chat dock (or make run) and watch the dashboard light up:

The money shot is the World Cup one. In one turn, Waku searches the web a few times, reasons over the results, and books every remaining match — 8 loop iterations, live. Needs a free TAVILY_API_KEY (paste it in Connections). Watch the LOOP box pulse per cycle. That's loop engineering, on tape.

How is this different from ChatGPT / Claude Desktop?

Those are products you use. This is a codebase you own — the loop, the memory schema, the gate, the eval harness, all yours to read and change. Understand this repo, and you understand what the products do under the hood.

Versus the big open-source assistants (OpenClaw, Hermes)? Same architecture, 1/100th the code. Products vs. a readable blueprint.

The whiteboard gallery — editable system-design charts

Every whiteboard from the videos lives in docs/whiteboards/ as an editable .excalidraw source — download one, drop it on excalidraw.com, and remix it for your own team:

New charts land here with every video. If they help you, a star keeps them coming — and sponsoring gets new whiteboards early.

The whiteboard maps to the code

This diagram renders straight from the README (it's Mermaid text, not an image — edit it in a PR):

flowchart LR
  GW["Gateway<br/>cli · telegram · voice · dashboard"] --> WM["Working memory<br/>SOUL.md + memory + history"]
  WM --> LLM
  subgraph LOOP["The Loop — loop/agent.py"]
    LLM["LLM"] -->|tool call| TOOLS["Tools<br/>create_event · list_events<br/>search_web · save_note · …"]
    TOOLS -->|result| LLM
  end
  LLM -->|reply| REPLY["Reply"] --> GW
  GATE{{"Retrieval gate<br/>does this turn need memory?"}} -. only if needed .-> WM
  MEM[("Memory — state.db<br/>SQLite + FTS5<br/>semantic · episodic · procedural")] --> GATE
  REPLY -. save chat .-> MEM
  MEM -->|every N chats| CONS["Consolidate → facts"] --> MEM
  REPLY --> OPS["LLM Ops<br/>trace → eval → gate → release"]
  OPS -. improved prompt/config .-> WM
  WM -.- WATERMARK["waku-agent · Sean's AI Stories · @ShenSeanChen"]:::wm
  classDef wm fill:none,stroke:none,color:#9aa0aa,font-size:11px;

Architecture of waku-agent — built on the series (@ShenSeanChen). Code is MIT; this diagram is licensed CC BY-NC-SA 4.0 — reuse it with credit to the channel, not for commercial resale.

Every box is one module (full version with every file path: docs/architecture.md):