Waku-agent provides a local-first, transparent AI agent framework, enabling users to understand and customize core components like harness, loop, memory, and evaluation. It targets technically savvy users seeking a readable, ownable alternative to black-box AI products, offering deep insights into agent architecture.

How It Works

The system is built on four pillars: Harness (gateways), Loop (agent logic), Memory (semantic, episodic, procedural), and Eval/LLM-Ops (testing, monitoring). It employs a local-first approach with memory stored in a single SQLite file. The core loop is a concise ~95-line Python script, and a local dashboard visualizes the agent's internal flow. It supports multiple LLM providers and emphasizes code readability for educational purposes.

Quick Start & Requirements

Clone the repo, set up a Python environment using uv (uv venv && uv pip install -e .), and configure an LLM provider key in .env. Run the agent via uv run waku dashboard for a local web UI or uv run waku for CLI interaction. Optional features like voice (.[voice]), Telegram (.[telegram]), and Apple Calendar integration (WAKU_APPLE_TOOLS=1 make brief on macOS) require additional installs.

Highlighted Details

• Local-First & Privacy: All data, including memory and traces, remains on the user's machine.
• Transparent Architecture: Codebase is designed for readability, directly mapping to system diagrams.
• Modular Design: Clear separation of concerns across Harness, Loop, Memory, and Ops pillars.
• Advanced Loop Engineering: Demonstrates complex multi-tool chaining and retrieval gate optimization.
• Dual Evaluation System: Integrates deterministic unit tests with LLM-as-judge evaluations for robust quality control.
• Voice & Gateway Options: Supports hands-free voice interaction and multiple communication channels.

Maintenance & Community

Maintained by @ShenSeanChen, the project fosters community through Discord and X (@ShenSeanChen). Sponsorships are encouraged for continued development and new whiteboard content.

Licensing & Compatibility

The core code is licensed under MIT, permitting commercial use. Diagrams are licensed under CC BY-NC-SA 4.0, restricting commercial resale.

Limitations & Caveats

Some tools are experimental or require specific OS (e.g., macOS for make brief). Users incur costs for their chosen LLM API usage. Voice and advanced web search features may require additional setup or API keys.