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 等多種服務。
透明架構：系統每個元件都直接映射到程式碼中的可讀檔案。
整合評估：內建發布門控，結合決定性與人工判斷評估。