Waku-agent is a local-first Python-based personal AI assistant that runs on a laptop, featuring a loop, memory pillars, and an eval harness. It uses a SQLite state DB and supports multiple providers via a simple interface.
Collecting history — the radar snapshots this repo daily. The trend line appears after 3 days of data (2 so far).
What it is
Waku-agent is a local-first personal AI assistant that runs on your laptop. It exposes four pillars: Harness, Loop, Memory, and Eval/LLM-Ops. The memory is stored in a single SQLite file and the system includes a local dashboard for monitoring turns and gate decisions. It supports deterministic evals and LLM-based judging, with a release gate that combines both.
How it works
The architecture comprises a Gateway (CLI/voice/Telegram/web), Working Memory stored in state.db, and a Loop that reasons, calls tools, observes results, and updates memory. The Eval subsystem provides deterministic tests and LLM-based judgments for release decisions. The Loop is described as ~95 lines of Python code. The memory system includes semantic, episodic, and procedural components, with a retrieval gate to decide whether to retrieve memory. A local dashboard visualizes each turn.
Getting started
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 … supports three ways to run without activating a venv beforehand:
uv run waku dashboardsource .venv/bin/activate→waku dashboarduv tool install .→waku dashboard
waku and waku dashboard enter the same Waku, with the dashboard serving as a local UI. Memory is stored in .waku/state.db.
Providers supported include Anthropic (default), OpenAI, Gemini, DeepSeek, MiniMax, Kimi, GLM, or OpenRouter, selected via WAKU_PROVIDER= and a pasted key.
Recent releases
- none
Traction
- stars_7d: 0
- stars_1d: 0
Behind the repo
- Repository: ShenSeanChen/waku-agent
- Language: Python
- License: MIT
- Created: 2026-07-10
- Last push: 2026-07-16
- Stars: 221
- Forks: 55
- Open issues: 3
Caveats
- Memory: state.db is used for durable memory; MEMORY.md is generated as a mirror
- The README indicates a local dashboard and local server without cloud transmission
- The code includes a local gateway, loop implementation, and eval harness; there are deterministic tests and an eval-judge suite