Model or dataset
ShenSeanChen/waku-agent avatar
ShenSeanChen/waku-agent

waku-agent had two version numbers for four releases, and says so in its own manifest

Waku Waku! Waku Agent is a local-first AI agent harness you actually own, including loop, memory, eval, all in code built to stay legible as it grows.

2,174 stars432 forksPythonMIT

At a glance

What is it?
ShenSeanChen/waku-agent is a local-first personal agent whose whole argument is legibility: one SQLite file for memory, a loop of about ninety-five lines, and evals beside the code. Its packaging comments record a version drift bug that is more interesting than most changelogs.
Who is it for?
This suits someone who wants to read an agent end to end rather than configure one, since the memory is a database file you can open and the loop is small enough to step through. Three things to know before you commit.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • ShenSeanChen/waku-agent2,174 ★ · +454
Star history
Repository2026-09-102026-11-15
ShenSeanChen/waku-agent1.7k2.2k

454 Stars in the last 66 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Four pillars, and a loop you could read in one sitting

The project states its thesis in the first line of substance: every serious agent has four parts, and this one refuses to hide them behind a framework. The harness is the set of gateways and the tools around a single loop, and the gateways are the terminal, a browser dashboard, voice, and three messaging platforms. The loop itself is described as about ninety-five lines of plain Python with two ways to stop, and the page invites you to step through it rather than take its word. Memory is the third pillar and the one the page calls the hero. Evaluation is the fourth: deterministic tests and model-as-judge side by side, a release gate, and a stored trace for every turn. The claim that every box on the design diagram maps to a file is the one to test, and the architecture document is where you test it.

Memory is one database file, and a gate decides whether to write

The memory design is the part with the most thought in it. Three kinds are named: semantic, episodic, and procedural, the last being the skills. What is interesting is that two decisions are separated. A gate decides whether something is worth remembering at all, and a separate pass decides what to keep from what was admitted. That split is the difference between a system that accumulates and one that stays legible, and it is the answer to the usual objection that agent memory becomes a junk drawer. The storage claim is deliberately plain, and installing it is two lines:

bash
pip install waku-agent
waku dashboard

One SQLite file at a fixed path in your home directory, the same file no matter which folder you launch from, which you can open and read with any tool.

Two wire formats cover ten providers through one adapter

The dependency list is four packages, and two of them do the provider work. The manifest comments say which is which: one wire format covers the default provider plus two others that speak its dialect, and the other covers another three plus embeddings. That accounts for five providers from two SDKs, and the page lists ten: the default one, two more from the first family, three from the second, plus an aggregator offering one key and hundreds of hosted models, and two further gateways. The claim is that the loop speaks one dialect and a single adapter of roughly sixty lines translates for everything else. That is the load-bearing claim of the whole design, and the file it lives in is named in the page, so it is checkable rather than asserted.

The version number lived in two places and disagreed for four releases

The packaging manifest carries the most revealing comment in the repository. The version is declared dynamic rather than written, and the comment above it explains why in plain terms: the single source of truth is the package's own init file, and previously the manifest and the package disagreed for four releases, with one saying 0.1.4 and the other saying 0.1.0, because nothing forced them to match. Now there is one number to bump. The release history explains how young the project is: the first tagged release came at the end of July 2026, described as such, then a follow-up for agent graphs five days later, and the newest visible tag in mid-September. A project six weeks old carrying a comment about a four-release regression is a good sign about how it learns.

The licence is three expressions and one of them is custom

The package does not simply say MIT. The licence field is an expression joining three things, and the comment above it explains the shape: the code is MIT, the brand assets are not and live in a separate licence file at the root, and the bundled fonts are under a font licence, whose text files are shipped inside the package behind a glob. The comment also names the reason for the precision, pointing out that the packaging standard now allows a package to declare all three so that an index no longer reports the entire wheel as MIT when part of it is not. That is a small, correct piece of hygiene, and it is also a reminder that when you install this you are getting fonts and a brand name alongside the code, under different terms from the code.

Contributors run against a local memory, and the dashboard forgets Python changes

Two Makefile comments describe the traps, and both are the kind nobody documents. The first is about data: the home directory for memory is set to a directory inside the repository for anyone working on the code, with the reason written out, namely that maintainers work on the repository's own memory and never on the one a person's real assistant uses, referencing an internal specification number for the decision. An explicit setting still wins, so this is a default rather than a hard rule, but it is the right default. The second is about the dashboard server: it holds the Python in memory, so static assets reload on refresh while the routes do not, and after pulling a change that touches any imported module you must stop the process and start it again or the interface shows stale backend data.

One job has two implementations, and the env template is generated

The build targets are organised as one command per pillar, and two of them do the same work on purpose. A briefing target composes a calendar, mail and memory as a loop. A second target does the identical job as a graph, with four sources gathered in parallel and then one digest. That pairing is a teaching device: the same requirement expressed in both execution models. The environment template is generated too, from a script, with the definitions living in the integrations module, which is why every provider block repeats the same shape and every channel block lists its install extra. The generated blocks also carry the operational details, including alternative regional endpoints for three providers and, for one chat platform, a requirement that messages mention the bot, a per-hour turn cap, and a home directory override.

The hosted memory is a second product sharing the same store

The open project is not the whole picture. A hosted memory service sits at its own address, described as the same memory you can share across agents: save something in another coding agent, recall it here. Connecting it needs an optional install extra and one command, your browser opens once to sign in, and skills can be exported from this agent into two other agents. The documentation names four agents that can share one memory. The repository tree shows where the boundary runs: alongside the open package there are directories for the hosted deployment and for database schema, plus a lab directory described as video experiments where this agent meets other agents and models. So the open core and the service share a design, and reading the tree tells you which parts you are actually being given.

Editorial conclusion

This suits someone who wants to read an agent end to end rather than configure one, since the memory is a database file you can open and the loop is small enough to step through. Three things to know before you commit. The hosted memory service is a separate product sharing your local store, so connecting it is a real decision rather than a default. Contributors are protected from touching your own data by a repository-local home directory, which is a small courtesy you should understand before you run the project's tooling on your machine. And the package declares a three-way licence including a custom brand term, so the code is MIT but the name and the fonts are not.

Frequently asked questions

What is waku-agent?

It is an MIT-licensed, local-first personal AI agent harness organised around four pillars: a harness of gateways and tools, a loop of about ninety-five lines of plain Python, a memory system with semantic, episodic and procedural layers, and evaluation with both deterministic tests and model-as-judge behind a release gate. It runs on Python 3.11 and newer with four runtime dependencies.

Where does waku-agent store its memory?

In one SQLite file at a fixed path in your home directory, and it is the same file no matter which folder you launch from, so you can open it and read it directly. A gate decides whether something is worth remembering at all, and a separate consolidation pass decides what to keep from what was admitted.

Which model providers does waku-agent support?

Ten are listed, from the default Anthropic through OpenAI, Gemini, DeepSeek, MiniMax, Kimi, GLM, an aggregator offering one key for many hosted models, and two further gateways. The manifest comments explain that two wire formats cover most of them, so the loop speaks one dialect and an adapter of roughly sixty lines handles the rest.

What is Waku Memory?

It is a hosted memory service at its own address, separate from the local one, so you can save something in another coding agent and recall it in this one. You install the optional extra, run waku connect waku-memory, sign in through your browser once, and can export this agent's skills into Claude Code and Codex. The integrations documentation names four agents that can share one memory.

How does waku-agent evaluate itself?

Two kinds side by side: deterministic tests and model-as-judge, with a release gate in front of them and a stored trace for every turn. There is also a tier that runs in containers, and the documentation covers both kinds along with tracing and spend. When working on the code, the build file points memory at a directory inside the repository so maintainer runs never touch a person's real assistant data.

Official sources

  1. Issues
  2. License: MIT
  3. README
  4. Releases
  5. ShenSeanChen/waku-agent on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/shenseanchen-waku-agent.svg)](https://hysenlabs.com/projects/shenseanchen-waku-agent)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/shenseanchen-waku-agent.svg)](https://hysenlabs.com/projects/shenseanchen-waku-agent)

Was this useful?