Multi-Repo Agent Orchestrator

近頃皆さんやっていることだが, PC上のあらゆる作業にAI Agentを介入させるように仕事の再構築を進めている. 構築を進める中で, 複数のプロジェクトが同時進行する中で, CLAUDE.md/AGENT.md, skills の仕様判断, その他規約,コンテキストの設定を共有・自動化したいという欲求が出てきた.

複数Agentの並行管理自体は, Remote Control や cmux などの導入で軽くなってきたが, それぞれのrepoで独立していると初期設定,知識層の反映で手間がかかる. どのrepoで起動しても作業目標毎に知識,規約の引き継ぎの手間がボトルネックとなってきた.

そのために, 複数リポで別々に走らせている十数個の Claude/Codex セッションを, 横断で監視, 記録, タスク配分, 知識集約する上位レイヤ(Agent Orchestrator)を自作した. 各リポの Agent は賢いが, それらを束ねる視点 (誰が何を進行中か, 知見の横断再利用, タスクの配分) は別レイヤの問題で, そこを担うのがこの Orchestrator である.

このような用途としてはわざわざ車輪の再発明をしなくても既存 AI Assistant tool として有名なものに Pi (Inflection) や Hermes Agent (Nous Research) とがあり,わざわざこんなことをしなくても既存アーキテクチャを採用することで類似の効果は得られる.

Pi は製品 / UX 層, Hermes Agent はモデル + 単一 agent 層に当たる. どちらも記憶や知識の集約・反映の仕組みを持ち (Hermes Agent は永続メモリ + skills, Pi は会話文脈), 私の理解では orchestrator 的な役割もある程度こなす一般ツールである.

それでも自作したのは, 次の二点を得たかったところによる.

• 記憶層が小さい: 既製ツールの記憶は基本的に単一 agent スコープで, 複数リポ・複数分野にまたがる横断知識ベース (本プロジェクトの vault) としては手狭. RAG として手入れする前提の corpus を, agent の外側に独立して持ちたい.
• 作業ごとに分人的な役割分担がある: 研究, 講義, 開発, 私生活で必要な人格・文脈・規約は異なる. すべてを単一 agent に集約するより, agent ごとの個別コンテキストと, 横断の共通知識とを併存させたい. 一個の強い agent を作る (Hermes Agent の方向) のではなく, 弱くてもよいので多数の agent をそれぞれの分人として保ちつつ, 共通の知識層で束ねる, という選択である.

あと単純に自分で弄れる範囲が大きい方が楽しい. ので普通はHermes Agentを入れておけば殆ど事足りると思われる.

なお,以下の構成は最終的には,ネットワーク上の常時稼働Agentに引き継ぐが現在は試験的に,全てローカルで完結させている.

全体構成: 5 層

Orchestrator は管理対象リポの上位に立ち, launchd で毎時巡回するバッチと対話セッションの二面で動く. 処理は 5 層に分かれ, 各リポの Agent とは共有キュー (inbox/outbox) だけで接続する.

ポイントは, Orchestrator 自身は判断と記録に徹し, 各リポでの実作業はそのリポの Agent が担うこと. Orchestrator は司令塔兼書記であって, 現場では手を動かさない.

管理対象: 複数リポをカテゴリで束ねる

以下は匿名化したリポの構造を表している. 各リポは runtime (claude / codex), cadence (毎時 / 日次 / 週次), category, techs をメタデータに持ち, これが後段の routing と知識索引のキーになる. 設定は 1 枚の YAML に集約し, パーサも 1 本に統一している.

構造は二段に分かれる. Orchestrator が作業レイヤの頂点に立ち, 十数リポを束ねる. そして その Orchestrator を頂点とする系全体を, さらに外側から評価するのが existential (Vault) である.

二段構成のポイントは, Orchestrator と existential (Vault) の役割が違う層にあることだ. Orchestrator は作業レイヤの頂点として, 十数リポの routing / 知識 / タスクを束ねる司令塔である. これに対し existential は, その Orchestrator を頂点とする系全体をさらに外側からメタ的に評価する. ここには now.md をはじめ思想 / 現状 / 価値観の single source があり, 個々の作業や routing が自分の価値観・現状と整合しているかを問う. Orchestrator が “何を / どう進めるか” の司令塔なら, existential は “そもそもその方向で良いか” を問うメタ評価レイヤにあたる. now.md 自体は Orchestrator 経由で必要な agent にも配信されるが (思想 context の routing), existential の主たる役割は系全体のメタ評価である.

各リポもOrchesratorを通じて連携できるようにしている. 例えば, 最近開発を進めている paper 層は, 文献管理に特化したパイプラインを持つ. 論文 PDF を原典として取り込み, それを md に抽出・要約 (図表や式の扱いも含む) してから, 引用情報を bib (引用データベース) に落とす. この PDF → md → bib の流れが research 層の執筆へ供給され, 「読んだ論文がそのまま引用可能な形で原稿に届く」状態が構築されている.

通信モデル: repo-initiated

一番大事な制約として, Orchestrator は管理対象リポの FS を直接書き換えないことがある. 通信はすべて repo 側から共有キューへの push / pull に固定する.

境界を push/pull のキューに固定すると, どちらが何を書いたかが常に明確になり, 片方が壊れてももう片方は動き続ける. 上位が下位のコードを勝手に上書きしない, という規律でもある.

データ表現: (今のところ)すべて markdown

状態, タスク, 知識, 規約 - Orchestrator が扱うデータは全部 Obsidian による markdown + frontmatter で持つ. DB も独自フォーマットも使わない. 狙いは移行容易性で, 別マシン (常時起動の Mac mini を想定) へ移すとき, データ表現が markdown のままなら差し替えるのは通信層だけで済む.

\text{Phase 1 (file)} \;\longrightarrow\; \text{Phase 2 (MCP)} \;\longrightarrow\; \text{Phase 3 (LAN MCP)}

通信は進化させても vault の中身は不変. でそのまま人間が読める利点も大きい.

markdown / Obsidian を選んだ主な理由は, もともと個人の知識管理を Obsidian で行っていたことにある. 設計として一から選んだというより, 既存資産 (過去の日記やメモ) をそのまま agent に読ませられる連続性が大きく, 実際 existential (Vault) では過去の日記・メモを文脈として読ませている. したがって 人間が文章を読む面は当面 Obsidian 固定で行く予定だ. 一方, 人間が読まない orchestrator 層の内部表現 (state や中間データ) は markdown に縛る必然はなく, より効率的な手段があれば置き換える予定でいる. markdown は “人間も読む層” の共通項として残し, 機械専用の層は最適な表現へ寄せていきたい.

知識層 = 自前 RAG

このプロジェクトで一番効いている知識層は, 実質 RAG (Retrieval-Augmented Generation) の自前運用である. ただし主眼は “貯める” ことより “腐らせない” ことにある.

• ingestion: Agent が知見を [pattern] [gotcha] [howto] [reference] [domain] のタグ付きで報告 → 1 件 1 markdown を _staging/<tag>/ に保存. source repo, category, techs, confidence をメタデータに持つ.
• index: 埋め込みベクトルではなく, タグ + メタデータ + 全文キーワードの軽量索引. by-category/ by-tech/ の逆引きで横断取得 (ベクトル化は移行後の検討).
• retrieval: 必要時に pull_relevant_knowledge / search_knowledge. スコアは自リポとの親和度, 新しさ, 過去の使用回数の重み付き和:

\mathrm{score}(n) \;=\; w_c\,[\,c_n = c_q\,] \;+\; w_t\,\lvert T_n \cap T_q \rvert \;+\; w_r\,\mathrm{recency}(n) \;+\; w_u\,\mathrm{usage}(n)

• curation (本題): corpus をただ増やすとノイズで検索精度が落ちる. 引かれた note は本フォルダへ昇格, 古い / 撤回された note は _stale/ へ隔離 (黙って消さないので追跡可). retrieval のログ (usage signal) が次の curation を駆動する. 一度踏んだ gotcha を別リポの Agent が二度踏まないのは, corpus が増えるからでなく手入れされているからだ.

タスク管理層: Todoist

知識層と並ぶもう一つの管理層がタスクで, ここは Todoist を hub にしている. 人間と agent が同じタスクを同じ場所で見るための層である.

設計は単純で, source of truth は git 追跡の vault/tasks 側に置く. sync_tasks がそれを各リポの Todoist project に push し, agent は pull_my_tasks で自分宛てを取得する. どの project に置くかで担当 repo が決まる (置き場所で routing するので, ラベル付けは最小限). フィールド単位で真の側を分けており, 本文 / 詳細 / リンクは vault が真, 完了状態 / 期限は Todoist が真 (モバイルで完了する運用が多いため). 人間から見ると, Todoist が全リポのタスクを横断で俯瞰し操作する一枚の窓になる.

耐障害ルーティング

Agent のセッションで MCP server が一時的に繋がらないと, Agent は submit 系ツールを呼べず共有 inbox に素のファイルでフォールバックしてくる. これを要約に溶かさず, 種別ごとに振り分ける.

ツールが落ちても依頼の種別に応じて確実に拾われる. 賢いコンポーネントほど壊れ方に対する設計が効く, という一例である.

という感じで色々やってみているが, なんとなく機能してきたのでまとめました記事でした. 毎日変わっているのであくまで暫定版ですが.