ShenSeanChen/waku-agent

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.

解决的问题

Waku 是一个以本地优先为设计原则的个人 AI 助手，旨在成为现代智能体工作方式的可读、透明的蓝图。它用一个简单、可读的代码库取代了复杂、"黑箱"式的智能体框架，使用户能够拥有并理解整个智能体循环、记忆系统和评估框架。

如何工作

智能体循环

核心是一个约 95 行的纯 Python 循环，遵循「推理-行动-观察」的循环：LLM 对请求进行推理，必要时调用工具，观察结果，并重复此过程，直到生成最终回复。

记忆支柱

记忆存储在本地 SQLite 数据库（state.db）中，并镜像到人类可读的 MEMORY.md 文件。它由三种类型组成：

语义性：持久的事实和用户档案。
事件性：带日期的事件和过往对话。
程序性：技能和「如何做」的说明。

检索门控

为防止无关记忆干扰回答并降低延迟，一个「检索门控」（小型、低成本模型）会在访问数据库前判断当前回合是否真的需要检索记忆。

图形工作流

对于需要特定结构的任务，Waku 使用图形工作流。这允许并行执行和确定性路由（例如，一个分诊节点将简单的「谢谢」消息路由到小型模型，而复杂任务则路由到完整智能体循环）。

LLM-Ops 与评估

系统包含内置的评估框架，将确定性测试（正确的工具是否被触发？）与 LLM 作为裁判的测试（回复是否有帮助？）分离。所有回合都会被记录为 JSONL 文件，便于调试。

适用人群

希望在不依赖重型框架的前提下构建或理解个人 AI 助手的开发者。
对实现本地优先记忆和智能体循环工程感兴趣的 AI 工程师。
希望拥有一个私密、本地优先的助手，并能与自己的工具（日历、邮件、Telegram）集成的用户。

特色亮点

本地优先：记忆是一个由用户拥有的单一 SQLite 文件。
可视化仪表板：一个本地 Web 仪表板，可实时观察智能体的推理、工具调用和记忆更新。
多提供商支持：通过简单适配器，兼容 Anthropic、OpenAI、Gemini、DeepSeek 等多种服务。
透明架构：系统每个组件都直接映射到代码中的可读文件。
集成评估：内置发布门控，结合确定性与人工判断评估。