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-agent は、エージェントのループ、記憶、評価を読み切れる Python コードとして持ち、SQLite 1 ファイルに状態を置く構成を取る。フレームワークに隠された部分を自分で追いたい人向けの道具であり、その代わりに自分で面倒を見る範囲が広い。
- 誰に向いている？
- 自分でエージェントのループを読み、記憶の中身を SQLite で直接確認したい個人開発者や小規模チームには向いている。逆に、複数ユーザーの権限分離や監査ログ、SLA を前提とする業務システムの土台としては、README にその領域の記述がないため勧められない。
- 商用利用できる？
- できます。MIT は寛容なライセンスで、著作権表示とライセンス表示を残せば、使用・改変・販売が可能です。
- 今もメンテナンスされている？
- されています。最後のコミットは 1 日前です。
- 何の言語で書かれている？
- 主に Python です（GitHub の言語統計による）。
回答はプロジェクトの GitHub データ（最終同期：2026年9月15日）と当サイトの分析に基づくもので、法的助言ではありません。
オープンソース詳細解説
誰のための道具か: フレームワークの内側を読みたい人
README はこのリポジトリの狙いを「Your own AI assistant. On your laptop. In code you can read in an afternoon.」と表現している。つまり対象は、既存のエージェントフレームワークを使うとループや記憶の実装が見えなくなることに不満を持つ開発者である。README の表現を借りれば「No frameworks hiding the good parts」であり、ハーネス、ループ、記憶、評価という 4 つの柱を自分のコードとして持つことが主題になっている。
もうひとつの軸はローカルファーストだ。記憶は SQLite の 1 ファイルで、README は保存先を .waku/state.db と明記し、「Open it. Read it. It's yours.」と書く。データを外部サービスに預けたくない、あるいは預けた結果として何が保存されているか分からなくなることを避けたい人に向く。
逆に、GUI で完結する製品を探している人や、複数人のチームで共有するアシスタントを求めている人には向かない。README が想定するのは、自分のラップトップ上で自分専用に動かす使い方である。
ループは約 95 行、モデル差は約 60 行のアダプタに寄せる
README によれば、エージェントのループは約 95 行の素の Python で書かれており、ステップ実行できることを売りにしている。加えて「One dialect in the loop; a ~60-line adapter handles the rest.」とあり、プロバイダごとの差分は waku/loop/models.py のアダプタに集約される。ループ本体は単一の対話形式だけを扱い、API の方言差はその外側に押し出すという分担である。
対応プロバイダとして README が挙げるのは Anthropic（既定）、OpenAI、Gemini、DeepSeek、MiniMax、Kimi、GLM、OpenRouter、OpenCode Zen、OpenCode Go である。選択は WAKU_PROVIDER で行い、キーを貼るという手順が示されている。OpenRouter については「one key, hundreds of hosted models」と説明されており、1 つのキーで多数のホスト型モデルを切り替える使い方を想定している。
ここで注意したいのは、ループが薄いということは、リトライ、タイムアウト、並列ツール呼び出しの調停といった周辺の作り込みも薄い可能性があるという点だ。README からはそれらの挙動を確認できない。ループが短いことを長所として受け取るか、足りない部分を自分で書く前提と捉えるかで評価が分かれる。
記憶は 3 種類と 2 つの関門で構成される
README は記憶を semantic、episodic、procedural の 3 つに分け、その上に 2 段階の判断を置くと説明する。1 つは「a gate that decides whether to remember」、もう 1 つは「a pass that decides what to keep」である。保存するかどうかの関門と、保存した中から何を残すかの整理を別工程にしている点が構成上の特徴だ。
この関門はダッシュボードの Overview で retrieve と skip の比率として見えるとされ、Ops タブではターンごとの判断を確認できると README は述べている。動作の例として README が挙げるのは、「Remember that Alex prefers morning meetings.」と伝えて終了し、再起動後に「Book a catch-up with Alex on Friday.」と頼むと、記憶を参照して 9am に予定を入れるという流れである。
記憶の実体は .waku/state.db の 1 ファイルで、README は MEMORY.md が更新される場面にも触れている。SQLite を直接開けることが、この設計の検証可能性を支えている。どの事実がいつ入り、どの整理工程で残ったのかを、ツール越しではなくファイル越しに追える。
導入: 2 つの入口と 3 つの実行方法
すぐ動かすだけなら pip install waku-agent の後に waku、または waku dashboard を実行する。README によれば、初回に設定すべきキーをツール側が教えるとある。コードを読む目的や貢献目的ならクローンする手順が示されている。
git clone https://github.com/ShenSeanChen/waku-agent && cd waku-agent の後、uv venv && uv pip install -e . で環境と waku コマンドを作り、cp .env.example .env でプロバイダを 1 つ選んでキーを貼る。実行は uv run waku、ダッシュボードは uv run waku dashboard である。README は uv run waku … なら venv の有効化が不要だと明記している。
実行方法は 3 通りが表で整理されている。uv run waku dashboard は有効化なしの推奨、source .venv/bin/activate の後に waku dashboard はセッション中だけ素の waku を使う方法、uv tool install . の後に waku dashboard は waku をグローバルに入れる方法である。make dashboard と make run も別名として用意されている。
ダッシュボードは 127.0.0.1 で動く小さな Web サーバで、ブラウザは UI に過ぎず、ターンを実行するのは同じプロセスだと README は説明する。フロントエンドは静的ファイルでビルド手順がない。TELEGRAM_BOT_TOKEN を設定すると Telegram ボットも同時に起動する。
タブ構成がそのまま設計図になっている
ダッシュボードの各タブは柱ごとに分かれ、それぞれ実ファイルに対応づけられている。Overview はコスト、レイテンシ、関門の skip/retrieve 比、クリック可能な構成マップを表示する。Gateway はダッシュボード、telegram、voice、cli のどの経路から来たメッセージかをタグ付けし、1 つの会話として並べる。Loop はターンごとの関門判断、ツール呼び出し、トークン、コストを出す。
Graph タブは v0.1.1 のリリース名にもある agent graphs に対応し、エンジン自身から描かれたトリアージのトポロジと、そのターンがどちらの入口を通ったかを表示すると README は述べている。Memory タブは柱ごとのサブタブに分かれ、semantic の事実、episode、編集可能な skills と SOUL、整理工程を扱う。Tools タブは出自ごとにまとめた利用可能ツールとその結果、MCP コネクタを表示する。
Data タブは state.db に対する SQLite ブラウザで、テーブルごとのタブ、スキーマ、読み取り専用の SQL コンソールを備える。Ops タブは評価の判定と履歴、関門の判断、遅いターン、JSONL トレースを表示する。サイドバーとチャットドックはドラッグで幅を変えられ、折りたたみもできる。
評価は決定論的テストと LLM 判定を並べ、リリースゲートにする
README は評価について「Deterministic tests and LLM-as-judge, side by side, with a release gate.」と書く。同じ対象に対して決定的なテストとモデルによる判定を併置し、その結果をリリースの関門として扱う構成である。Ops タブに判定と履歴が出るため、実行のたびに結果がどこかに消えるのではなく、状態として残る。
決定論的テストは入力と出力の対応が固定できる範囲を守り、LLM 判定は文章の質のように一致比較が難しい範囲を拾う。両者を並べる意味は、片方だけでは見落とす失敗を補うことにある。ただし README からは、判定に使うモデル、しきい値、ゲートが落ちたときの扱いまでは読み取れない。評価を実際の運用に組み込むなら、この部分は自分でリポジトリを読んで確認する必要がある。
評価が組み込まれていること自体は、エージェントを長く使う上で効く。プロンプトやツールを変えたときに、直前の挙動が壊れていないかを同じ手順で確かめられるからだ。
向かない場面と、代わりに検討する構成
このリポジトリが向かないのは、複数ユーザーで 1 つのインスタンスを共有する用途である。記憶は .waku/state.db という単一ファイルに置かれ、README はローカル、自分専用という前提を繰り返す。ユーザーごとの分離、権限、監査の話は README に見当たらない。組織で使うなら、この層は自分で足すことになる。
もうひとつの失敗の形は、ループの薄さを過小評価することだ。約 95 行という数字は読みやすさの裏返しで、ツール呼び出しの並列化、失敗時の再試行、長時間ターンの中断といった制御は、必要なら自分で書く領域になる。README が例に挙げる World Cup のターンは 8 回のループ反復を伴い、search_web を複数回呼んだ後に create_event を複数回呼ぶ。反復が増えるほど、途中で失敗したときの扱いが効いてくる。
代わりに検討できるのは LangGraph のようなグラフ記述を中心に据えた構成だ。waku-agent がループを素の Python の制御フローとして書き、グラフは v0.1.1 で加わった Graph タブ側の機能として扱うのに対し、LangGraph は状態遷移そのものを宣言的に記述し、分岐や再開の扱いをフレームワーク側の抽象に寄せる。読みやすさと引き換えに、制御の一般性を外から与えられる。どちらが良いかは、ループを自分で書き換えたいか、書き換えずに組み合わせたいかで決まる。
維持と更新のコスト、MIT ライセンスの意味
リポジトリ情報によれば、最初のタグ付きリリース v0.1.0 は 2026-07-26、agent graphs を掲げる v0.1.1 は 2026-07-31 で、直近の push は 2026-08-29 である。タグ付きのリリースは 2 件しかなく、版番号は 0.1 系にある。API とファイル配置が今後動く前提で読むべき段階だ。
維持コストの面で効くのは、依存の少なさと、状態が SQLite 1 ファイルに閉じていることだ。README は記憶を 1 ファイル、フロントエンドをビルド手順のない静的ファイルと説明しており、壊れたときに見る場所が限定される。一方で、プロバイダの API 仕様が変われば waku/loop/models.py のアダプタ側に対応が要る。README はこのファイルを約 60 行としているので、差分を読む負担は小さい。
ライセンスは MIT である。MIT は商用利用を含む利用と改変を許し、著作権表示と許諾表示の保持を求める類型で、コピーレフトのような派生物への同条件適用は課さない。ここから先は法的助言ではないが、同梱物や配布形態によって表示義務の満たし方が変わるため、配布する場合はライセンス全文の扱いを自組織の確認に回してほしい。
更新の追い方としては、タグ付きリリースがまだ 2 件という事実を踏まえ、main を追うか、タグを待つかを先に決めておくとよい。uv pip install -e . で入れた環境なら、git pull の後に依存が増えていれば uv pip install -e . を再実行する流れになる。
編集部の結論
自分でエージェントのループを読み、記憶の中身を SQLite で直接確認したい個人開発者や小規模チームには向いている。逆に、複数ユーザーの権限分離や監査ログ、SLA を前提とする業務システムの土台としては、README にその領域の記述がないため勧められない。導入前に確認すべきは、pip install waku-agent で入る版とリポジトリの main が一致しているか、WAKU_PROVIDER で選んだプロバイダのキーが .env.example のどの変数名に対応するか、そして .waku/state.db のスキーマを Data タブか sqlite3 で開いて自分の用途に足りる列があるかの 3 点である。
コミュニティノート