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 architecture.
▶ Watch the 20-min code walkthrough — the loop, the memory pillars, the evals, the Telegram gateway and the "Waku Waku" wake word, live.
Waku Memory — the same memory in Claude Code, Codex, Grok Bot and this agent: waku.one · docs
YouTube · X · LinkedIn · Instagram · TikTok · Discord · 哔哩哔哩 · 小红书 · 抖音
Buy me a coffee — it keeps this repo (and the videos) coming
Just want to run it:
pip install waku-agent
waku # talk to your Waku in the terminal
waku dashboard # …or the browser cockpit → localhost:7777It 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:7777Now 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.
New to it? Getting started walks the whole setup, with a check at the end of every step.
Waku's own memory is local. Waku Memory is the hosted memory you share across agents: save something in Claude Code, recall it here.
pip install 'waku-agent[mcp]' # in a checkout: uv pip install -e '.[mcp]'
waku connect waku-memory # or /connect waku-memory in the dashboard chat
waku skill export --to claude,codex # carry Waku's skills to Claude Code and Codex tooYour browser opens once to sign in. To connect Claude Code, Codex, Hermes or Grok Bot to the same memory, see integrations.
| Pillar | In one line | Read more |
|---|---|---|
| Harness | gateways (terminal, dashboard, voice, Telegram, Discord, WhatsApp) and tools around one loop | architecture |
| Loop | ~95 lines of plain Python: reason, act, repeat, with two ways to stop | the tour |
| Memory | semantic, episodic and procedural (skills); a gate decides whether to remember, consolidation decides what to keep | the tour |
| Eval / LLM-Ops | deterministic tests and LLM-as-judge side by side, a release gate, a trace for every turn | evals |
How is this different from ChatGPT or Claude Desktop? Those are products you use. This is a codebase you own: the loop, the memory schema, the gate and the eval harness are all yours to read and change. Versus the big open-source assistants (OpenClaw, Hermes)? Same architecture, 1/100th the code.
| Read | For |
|---|---|
| Getting started | installing, the first run, connecting Waku Memory |
| The tour | the dashboard, things to try, the loop, graph workflows, skills |
| Architecture | every box on the whiteboard, and the file behind it |
| Integrations | voice, Telegram, calendars, MCP servers, Waku Memory |
| Commands | every waku and make command |
| Evals & tracing | the two kinds of eval, the release gate, traces and spend |
| Roadmap | what is live, what is still a skeleton, upgrade paths |
| Whiteboards | the editable system-design charts from the videos |
| lab/ | Waku meets other agents and models: the video experiments |
| AGENTS.md · CONTRIBUTING.md | the rules, and how to send a PR |
Star the repo, join the Discord, and grab a good first issue — that link is the live list, so it's always current. Gateways, memory backends and community skills are all shaped to be first PRs; the easiest needs no Python at all (see contributing a skill).
Comment on an issue before you start and it gets assigned to you, so two people never build the same thing.
- launch-mvp-stripe-nextjs-supabase — NextJS + Supabase + Stripe, everything you need to ship a SaaS.
- AutoManus.io — my AI startup: a sales lead manager for made-to-order products. It embeds where conversations already happen (WhatsApp, email, web chat) to capture inbound, automate follow-ups and kill CRM busywork. Pre-seed backed by Character VC. (AutoManus Discord)
Code is MIT — see LICENSE. The Waku name, mark and design system belong to AutoManus Technologies, Inc. and are not MIT — see LICENSE-BRAND. Built by @ShenSeanChen (YouTube · X).
