ShenSeanChen/waku-agent

Waku Waku! Waku agent is your personal AI agent, on your own laptop, in code you can read in an afternoon — harness + loop + memory + eval

What it solves

Waku-agent is a local-first personal AI assistant designed to be transparent and readable. It solves the problem of "black box" AI agents by providing a codebase where the core loop, memory systems, and evaluation harnesses are explicit, simple, and fully owned by the user on their own machine.

How it works

The system is built around four primary pillars:

  • The Loop: A plain Python implementation (approximately 95 lines) that handles the reason-act-observe cycle, allowing the agent to call tools and iterate until a final response is reached.
  • Memory: A multi-tiered system using a local SQLite database (state.db) for semantic, episodic, and procedural memory. It includes a "retrieval gate" that decides if a turn actually requires memory access to avoid bias and latency.
  • Harness/Gateway: A unified interface that allows the agent to be accessed via a CLI, a local web dashboard, Telegram, or voice commands (with wake-word detection).
  • LLM-Ops: A built-in evaluation suite that separates deterministic unit tests (did the tool fire?) from LLM-as-judge scoring (was the reply helpful?), combined with tracing and cost tracking.

Who it’s for

It is designed for developers and AI enthusiasts who want a readable blueprint of how a serious agent works under the hood, rather than a polished product, and for those who prefer local-first data ownership.

Highlights

  • Local-first Memory: All memory is stored in a single SQLite file and mirrored to a human-readable MEMORY.md file.
  • Visual Dashboard: A local cockpit that animates the agent's thought process, showing tool calls, memory retrieval, and cost in real-time.
  • Multi-Tool Chaining: Capable of complex tasks, such as searching the web for multiple events and booking them all into a calendar in a single turn.
  • Transparent Evals: Integrated release gates that ensure deterministic tests pass 100% before deployment.
  • Flexible Integration: Supports multiple LLM providers (Anthropic, OpenAI, Gemini, etc.) and integrates with Apple Calendar, Mail, and Google Calendar.