waku-agent：把 agent 的迴圈、記憶與評測攤在你自己的 SQLite 裡
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.
秒懂
- 它是什麼？
- ShenSeanChen/waku-agent 是一個 MIT 授權的 Python 本地優先 agent harness，訴求是讓人讀得懂、跑在自己的筆電上、狀態只落在一個 .waku/state.db。它的價值不在功能多，而在把 harness、loop、memory、eval 四個部分寫成可追蹤的檔案；代價是你得自己承擔 provider 金鑰、eval 基準與升級節奏。
- 適合誰用？
- 如果你要的是一個能逐行讀完、狀態存在自己機器上、並且把記憶與評測當作一等公民的 agent 骨架，waku-agent 值得在筆電上跑一次；它的迴圈約 95 行、記憶落在 .waku/state.db，這兩點決定了它的可審計性。反過來說，需要多租戶隔離、合規稽核紀錄或託管 SLA 的團隊不該選它，因為 README 描述的部署形態是 127.0.0.1 上的單機服務。
- 可以商用嗎？
- 可以。MIT 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 1 天前。
- 用什麼語言寫的？
- 主要是 Python（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。
開源專案深度解析
它想解決的是「框架把好東西藏起來」這件事
多數 agent 框架把迴圈、記憶與工具呼叫包進抽象層，使用者能呼叫，但看不到中間發生什麼。waku-agent 的 README 把立場寫得很直白：No frameworks hiding the good parts，並宣稱它的迴圈是約 95 行純 Python。目標讀者是願意讀程式碼的人，例如想理解 agent 內部如何運作、或想在自己的程式碼裡改動記憶策略的工程師。
它同時把「擁有權」放進賣點：記憶是一個 SQLite 檔，README 的說法是 Open it. Read it. It's yours.，預設路徑為 .waku/state.db。這對在意資料落地位置的人有實際意義，因為對話歷史、語意事實與事件紀錄都寫在同一個檔案裡，你可以用任何 SQLite 工具打開檢查，不必經過服務商 API。
需要說清楚的是，這是一個個人助理取向的專案，不是通用 agent 平台。README 舉的例子是排網球、查行事曆、記住某人偏好早晨會議，而不是多租戶工作流編排。把它當成後者會失望。
四個支柱如何對應到檔案：harness、loop、memory、eval
README 把系統拆成四個部分，並附上一張系統設計白板圖，聲稱每個方框都對應到一個檔案。這是這個專案最值得看的地方：它不是先有架構圖再補程式碼，而是用檔案結構當作說明文件。
迴圈的部分，README 說約 95 行，且模型方言的差異由一個約 60 行的 adapter 處理，位置在 waku/loop/models.py。這代表新增一個 provider 的成本被壓縮在單一檔案內，而不是散落在各處的條件分支。
記憶分成三類：semantic（語意事實）、episodic（事件）、procedural（可編輯的技能與 SOUL）。README 特別提到兩個機制，一個是 gate，決定「要不要記」，另一個是 consolidation pass，決定「留下什麼」。這個切分比常見的「把對話全部塞進向量庫」細緻，因為寫入前先判斷，可以避免記憶被瑣碎對話稀釋。
評測則分成兩條線：確定性測試與 LLM-as-judge 並行，並且有 release gate。README 沒有給出具體的通過門檻數字，所以無法判斷這個 gate 在什麼條件下會擋下發布，這一點需要看程式碼或實際跑一次才能確認。
安裝路徑有三條，差別在你要不要啟用虛擬環境
如果只是想跑起來，README 給的是兩行：pip install waku-agent，然後 waku 進終端對話，或 waku dashboard 開瀏覽器介面，位址是 localhost:7777。第一次啟動時它會提示你要設定哪一把金鑰。
想讀程式碼或貢獻的人，README 建議改用 clone：git clone https://github.com/ShenSeanChen/waku-agent && cd waku-agent，接著 uv venv && uv pip install -e . 建立環境並安裝 waku 指令，再 cp .env.example .env 挑一個 provider 貼上金鑰，最後用 uv run waku 或 uv run waku dashboard 啟動。README 強調 uv run 不需要先 activate 虛擬環境。
第三條路是 uv tool install .，把 waku 安裝成全域指令。官方文件把三種方式的適用時機列成表格：uv run waku dashboard 適合零啟用的快速開始，source .venv/bin/activate 後直接打 waku 適合整個 session 都在同一個環境工作，uv tool install . 則適合想長期保有指令的人。另外 make dashboard 也可以。
provider 的設定鍵是 WAKU_PROVIDER，README 列出 Anthropic（預設）、OpenAI、Gemini、DeepSeek、MiniMax、Kimi、GLM、OpenRouter、OpenCode Zen 與 OpenCode Go。這些名稱與金鑰對應關係，README 沒有逐一展開，只說第一次啟動會提示要設哪一把。
dashboard 不是裝飾，它是理解 harness 的主要入口
waku dashboard 啟動的是一個跑在 127.0.0.1 的小型網頁伺服器，README 明確說瀏覽器只是 UI，同一個行程負責跑每一輪對話，資料不離開你的筆電。前端是靜態檔案，沒有建置步驟。
每個分頁對應一個支柱，而且直接連到實際檔案。Overview 顯示成本、延遲、gate 的 skip/retrieve 比例，以及可點擊的架構圖。Gateway 把同一個對話跨通道的訊息依來源標記為 dashboard、telegram、voice 或 cli。Loop 列出每一輪的 gate 決策、工具呼叫、token 與成本。Memory 用子分頁呈現三個支柱，包含可編輯的技能與 SOUL。Data 分頁是一個 SQLite 瀏覽器，有 per-table 分頁、schema，以及針對 state.db 的唯讀 SQL 主控台。Ops 則放 eval 判定與歷史、gate 決策、最慢的回合，以及行內 JSONL trace。
這裡有一個容易被忽略的設計選擇：把 SQL 主控台做成唯讀。它降低了誤改狀態的風險，但也意味著你不能在 dashboard 裡直接修資料，要改就得另外開工具。對照它「記憶是你的檔案」的立場，這個限制算是保守。
另外，README 說設定 TELEGRAM_BOT_TOKEN 之後同一個行程會一併啟動 bot，所以 gateway 的多通道能力不需要另外部署服務。
retrieval gate 與多工具迴圈：兩個能看出設計取向的示範
README 提供一組「試這些」的範例，每一條對應一個支柱，並且標註該去哪裡觀察。其中兩條最能反映系統行為。
第一條是檢索閘門。先問 When am I swimming with Sergey?，再問 what's 12 × 8?，README 說前者觸發 retrieve、後者 skip，並可以在 Overview 的 gate 條與 Ops 的 per-turn 決策看到。這個設計的意義是：並非每一輪都需要動用記憶檢索，跳過檢索可以省下延遲與成本。實際的判斷邏輯與準確率，README 沒有提供數字，只能從程式碼或自己的紀錄去驗證。
第二條是多工具迴圈。範例是要求它搜尋世界盃剩下的賽程並逐一加進行事曆，README 說這一輪會跑 8 次迴圈迭代，先多次 search_web，再多次 create_event，並註明需要一組免費的 TAVILY_API_KEY，在 Connections 頁面貼上。這是展示迴圈工程最直接的一條，因為它同時涉及外部搜尋、結果推理與多筆寫入。
要注意的是，這些都是 README 描述的預期行為，不是實測結果。工具呼叫的穩定性、失敗重試策略、以及搜尋結果不完整時的行為，材料裡都沒有交代。
記憶的自動管理與它的邊界
README 示範了一句 Remember that Raj prefers evening games，並說這會觸發 save_note，Memory 的 Semantic 分頁會多一筆事實，MEMORY.md 也會更新。這說明記憶有兩份呈現：SQLite 裡的結構化紀錄，以及一份人類可讀的 markdown 檔案。對想用 git 追蹤記憶變化的人來說，後者比資料庫檔案友善得多。
另一個示範是跨重啟的記憶：先說 Remember that Alex prefers morning meetings，退出再重啟，接著要求 Book a catch-up with Alex on Friday，README 說它會記得並訂在 9am。這條路徑同時驗證了持久化與偏好套用。
限制在於判斷品質。gate 決定要不要記、consolidation 決定留什麼，這兩個機制都是啟發式的，README 沒有說明誤判時如何回退，也沒有提供手動覆寫的指令。當記憶開始累積錯誤事實，你大概只能進 Data 分頁或直接用 SQLite 工具處理。這是本地優先的必然代價：沒有服務商幫你收拾。
另外，記憶全部集中在 .waku/state.db 一個檔案，好處是備份簡單，壞處是它同時是單點故障。README 沒有提到任何備份或遷移工具。
v0.1.x 的發布節奏與你該預期的維護成本
GitHub 上可見的標記版本只有兩個：v0.1.0 於 2026-07-26 發布，標題是 the first tagged release；v0.1.1 於 2026-07-31 發布，標題是 agent graphs，相隔五天。這個節奏說明專案還在早期，API 與檔案格式都可能在後續版本變動。
對採用者的實際影響是升級成本。因為記憶是單一 SQLite 檔，schema 一旦調整，你需要自己確認舊檔案能否被新版本讀取。材料裡沒有任何 migration 說明或版本相容承諾，所以升級前先複製一份 .waku/state.db 是唯一能自己掌握的保險。
授權是 MIT，這對商業使用相對寬鬆，但這裡不提供法律意見，實際條款請讀 repository 內的 LICENSE 檔案。需要留意的反而是相依成本：README 把 provider 列成十個選項，每個都牽涉不同的金鑰、計費與速率限制，這些不在 MIT 授權的範圍內，而是你與各家服務商的關係。
專案由 seanchen.io 維護，README 附有 YouTube 系列與贊助連結，說明它同時是內容產品的一部分。這對文件品質通常是加分，但也意味著開發節奏可能跟著影片主題走，而非跟著 issue 走。
什麼情況下該選別的方案
如果你需要的是成熟的工具生態與穩定的 API 表面，LangGraph 這類框架的取向明顯不同：它把 agent 表達成狀態圖，節點與邊是抽象層的一等公民，好處是複雜分支與人為介入點容易描述，代價是迴圈本身被框架接管，你讀的是框架的執行模型而不是自己的 95 行。waku-agent 在 v0.1.1 才加入 agent graphs，兩者在圖編排上的成熟度不在同一個階段。
如果你的重點是檢索品質而非迴圈透明度，直接用向量資料庫加上自己的檢索層會更可控，因為 waku-agent 的 gate 與 consolidation 是內建策略，能不能換成你自己的判斷邏輯，材料裡看不出來。
如果你的場景需要多人共用、權限隔離或稽核軌跡，這個專案從設計上就不對應：它的 dashboard 綁在 127.0.0.1，記憶是一個本機檔案，README 描述的部署形態是單機。把單機助理硬推到團隊環境，你得自己補上隔離與備份，那已經超出這個專案提供的範圍。
反過來說，如果你的需求正好是「一個我能完全看懂的個人助理，資料不出筆電」，那麼它的取捨是合理的，而且省下的抽象層除錯時間是真實的。
編輯結論
如果你要的是一個能逐行讀完、狀態存在自己機器上、並且把記憶與評測當作一等公民的 agent 骨架，waku-agent 值得在筆電上跑一次；它的迴圈約 95 行、記憶落在 .waku/state.db，這兩點決定了它的可審計性。反過來說，需要多租戶隔離、合規稽核紀錄或託管 SLA 的團隊不該選它，因為 README 描述的部署形態是 127.0.0.1 上的單機服務。動手前先確認三件事：WAKU_PROVIDER 對應的金鑰與計費歸屬、你打算用哪個 provider 跑 eval 的 LLM-as-judge、以及 .waku/state.db 的備份方式，因為那個檔案就是你全部的記憶。
社群筆記