waku-agent

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 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

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

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, the same from every folder.

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.

Connect Waku Memory

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 too

Your browser opens once to sign in. To connect Claude Code, Codex, Hermes or Grok Bot to the same memory, see integrations. For live data when it researches, waku connect treg (or /connect treg) signs in to your own treg account the same way; see integrations.

What's inside

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.

Docs

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 Docker tier, 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

Community

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.

Also from me

• 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 — except hosted/, which is Elastic License 2.0: run it yourself, including commercially, but not as a service for others. See hosted/LICENSE. waku/, the harness itself and everything PyPI ships, is MIT. The Waku name, mark and design system belong to AutoManus Technologies, Inc. and are not MIT — see LICENSE-BRAND. Built by @ShenSeanChen (YouTube · X).