ShenSeanChen/waku-agent

What it solves

Waku is a local-first personal AI assistant designed to be a readable, transparent blueprint for how modern agents work. It replaces complex, "black-box" agent frameworks with a simple, readable codebase that allows users to own and understand the entire agentic loop, memory systems, and evaluation harness.

How it works

The Agent Loop

At its core is a plain Python loop (approximately 95 lines) that follows a reason-act-observe cycle: the LLM reasons about a request, calls a tool if necessary, observes the result, and repeats until a final reply is generated.

Memory Pillars

Memory is stored in a local SQLite database (state.db) and mirrored to a human-readable MEMORY.md file. It consists of three types:

• Semantic: Durable facts and user profiles.
• Episodic: Dated events and past conversations.
• Procedural: Skills and "how-to" instructions.

The Retrieval Gate

To prevent irrelevant memories from biasing answers and to reduce latency, a "retrieval gate" (a small, cheap model) decides whether a turn actually requires memory retrieval before accessing the database.

Graph Workflows

For tasks requiring specific structure, Waku uses graph workflows. These allow for parallel execution and deterministic routing (e.g., a triage node that routes simple "thanks" messages to a small model and complex tasks to the full agent loop).

LLM-Ops and Evaluation

The system includes a built-in evaluation harness that separates deterministic tests (did the right tool fire?) from LLM-as-judge tests (was the reply helpful?). All turns are traced to JSONL files for debugging.

Who it’s for

• Developers who want to build or understand personal AI assistants without relying on heavy frameworks.
• AI engineers interested in implementing local-first memory and agentic loop engineering.
• Users who want a private, local-first assistant that integrates with their own tools (Calendar, Mail, Telegram).

Highlights

• Local-First: Memory is a single SQLite file owned by the user.
• Visual Dashboard: A local web cockpit to watch the agent's reasoning, tool calls, and memory updates in real-time.
• Multi-Provider Support: Compatible with Anthropic, OpenAI, Gemini, DeepSeek, and others via a simple adapter.
• Transparent Architecture: Every system component maps directly to a readable file in the code.
• Integrated Evals: Built-in release gates using both deterministic and judged evaluations.