vivac

$ vivac why 4

  Why we are here  ->  t4
  ------------------------------------------------------------------

  g1    Ship the 2.0 API
        the first customer is waiting on it
        (4 open / 1 closed below)
        |
        v
  t2    Replace the cache adapter
        the session bug traces back to it
        (3 open / 1 closed below)
        |
        v
  t4    No test for expiry  [closed]
        no way to reproduce the session bug
        ! the corpus run is what settled it
        = reproduced: sessions expire at 300s, not 3600

        ^^^ you are here

  In parallel, still open (3):
      t3     Rate limiting is undecided
      d5     Retry policy: three tries, then fail loudly
      t6     Migrate the callers

  t2 does not close until these close (1):
      t6     Migrate the callers

---

ひとりで取り組む仕事のために

私はオープンソース、仕事、自分のプロジェクトを合わせて8つ並行して進めており、そのうち5つは大規模です。どのプロジェクトに戻るときも、そこで何が決まったのかをつなぎ合わせなければならず、私たちがすでに決めたことを、私もエージェントも忘れていたために、エージェントがそれを変更するのを何度も目にしました。それに対処する方法は手作業でした。作業の一区切りごとにモデルに あとで再開できるよう、セーフポイントを作って と頼むか、プロジェクトのルートに where_are_we.txt を置いておくのです。

vivacはそうしたものに取って代わったもので、今もそれらのプロジェクトで評価しています。これがvivacの来歴のすべてであり、何が作られたのかにもそれが表れています。ここにある仕組みはどれも、私がすでに何日も費やすことになった不具合から生まれました。このページにある数値はどれも、READMEをよく見せるために書かれたベンチマークではなく、実際のツリーから得たものです。

このプロジェクトが自身について記録しているツリーは、23日目で 695ノード、そのうち315件がクローズ済み、確定した決定事項が176件、深さは16階層です。

3つの不具合と、それぞれがどう変わったかを紹介します。

• 調査結果が未解決のまま、実行が DONE とマークされていた — そのことに誰かが気づくまで26日かかりました。今では vivac done は処理を拒否し、何が不足しているのかを伝えます。
• 224行にわたる、未解決の課題109件を並べた読み返し用リストで、昨日触れた項目が一番下にありました。今では open が、あなたが対応を待たれている項目を、その順番で10件まで表示します。
• crates.ioに公開した3つの説明が、隣にあるバイナリの挙動と矛盾していました。 今では、このページに載っているすべてのコマンドをテストで実行し、その一覧が --help と一致するか確認します。

今、私が手放したくないのは特定の機能ではありません。何がなぜ決まったのかをツリーで確認できること、手元にあるモデルを使ってプロジェクトを再開し、前のモデルが確定した内容をそのモデルに把握させられること、そしていつでも作業の進捗を確認できることです。私の経験では、これらはほかのどんなことよりも価値があります。皆さんにも同じように役立つことを願っています。

Issueは受け付けています。どこでうまくいかないのか、ぜひ教えてください。プルリクエストはまだ受け付けていません。その理由は CONTRIBUTING.md に記載しています。

---

問題

エージェント型 AI を使って開発していると、作業から次の作業が生まれます。3つ先まで進むころには、そもそも何を始めようとしていたのか、見失っています。

これは記憶の問題ではありません。たいてい、すべて書き残されています。**問題は来歴です。**書き残された内容には、何をもとに生まれたのかが記されていません。そのつながりがなければ、なぜ今ここにいるのかを再構築する方法がありません。

実際のコンパイラーで測定したところ、目標からその日の作業までの道筋は、時系列順に並んだ8,853行のトラッカー、52件の計画ドキュメント、21件のイシューにまたがる6階層の深さでした。その構造は時間軸に沿ったもので、来歴とはまさに正反対です。

エージェント向けの航海日誌、意思決定記録、イシュートラッカー、セッションメモリーは、いずれもノードを保存します。そのうちどれかがつながりも保存している場合、それは誰かが忘れずに追加しなければならないリンクです。そのため、重要だとは誰も思わなかったノードに限って、リンクが欠けています。位置づけでは、これらをカテゴリーごとに取り上げ、それぞれがこのツールより優れている点を説明しています。

---

得られるもの

**エージェントは状況を把握した状態で開始し、誰かが尋ねる必要はありません。**セッションが開くと、フックが vivac session start を実行します。これにより、コンテキストに最初に入るのは、現在の状況、すでに決定したこと、触れてはいけないものです。

$ vivac brief

vivac · project: demo · lane: main · 2026-09-21
------------------------------------------------------------

 GOAL g1     Ship the 2.0 API
  |
  |-- t2     Replace the cache adapter
  |     why: the session bug traces back to it
  |
  `-- t6     Migrate the callers   <== HERE
        why: the old adapter had a different signature

 STANDING DECISIONS
  d5     Retry policy: three tries, then fail loudly

 LAST VIVAC
  v5 · push · 2026-09-21 · bcdba21
         you were about to: Migrate the callers

------------------------------------------------------------
 143 tokens · depth 3 · 0 parked

トークン数で言えば、それがすべてです。状態を3か所に保存しているプロジェクトに、作業の続きから再開するよう依頼しました。手書きの計画は9,252トークンで答えました。メモリーシステムは、プロジェクト名の2つの候補のうちどちらを解釈するかによって異なりますが、約12,720トークンを使って*「たぶん」*と答えました。ツリーの答えは100トークンでした。コンテキストウィンドウは、すべてのセッションが消費する唯一のリソースであるため、概要にはトークン予算が設定されています。

**未解決のものを残したまま完了にはしません。**モデル内で拒否を行う唯一の操作であり、それに見合う理由があります。未解決の所見がある状態で完了とマークされた実行が、発見されるまでに26日かかったことがありました。

$ vivac done 2

  t2 CANNOT close: 1 open closure condition(s)

      t6     Migrate the callers

  A run closes with its findings, not with its report.
  Closing it anyway leaves a trace:  vivac done 2 --force

すべての決定について、却下した案と、その判断基準を保持します。--alternative は却下した選択肢を保持し、--supersedes は撤回を、撤回対象へのリンクとして記録し、--against は判断の根拠となったルールや原則を記録します。これにより、1年後でも決定を推測で済ませず、議論できます。このプロジェクト自身のツリーには、そうした決定が176件あります。

前提が崩れても、その子は巻き添えになりません。abandon は、反証された前提とその配下すべてに印を付けます。ただし、救い出したものは除きます。救い出したものは生まれた場所にそのまま残ります。生まれた場所が誤りだと判明しても、そこで生まれた事実は取り消されないからです。

---

保証しないこと

**節約するのはトークンであり、すべてではありません。**作業の再開に必要だったのは、手書きの計画では9,252トークンでしたが、ツリーでは100トークンでした。この差はセッションが開くたびに生まれます。それでもエージェントはファイルを読み、推論し、自分の考えを説明します。そのどれも安くはなりません。

**何も忘れないことを保証するわけではありません。**このツールを含め、どのメモリーシステムでも不可能です。どれも依然としてモデルの判断に頼るからです。*これは保存すべきか。これは所見か。答える前にツリーをもう一度読む必要があるか。*世界最高のスキルでも、100個のサブエージェントでも、100個のデーモンでも、その判断が行われる場所を移すだけで、判断そのものをなくすことはできません。vivac はその判断ではなく、作業の節目から記録を取り込むようにし、それでもどこで取りこぼしたかを測定します。

それでも残るものがあるからこそ、ツリーは見て確認できるように作られています。

---

実際に見てみる

vivac web

エージェントがツリーを書き出すので、エージェントに何も尋ねなくても、いつでも確認できます。vivac web を実行すると、このマシン上のすべてのプロジェクトがブラウザーで開きます。どのプロジェクトが動き、どれが止まったままなのか、離れている間に何が変わったのか、ノードの全系譜、そしてツリー全体を確認できます。「Agents」ページでは、ハーネス間のネイティブバージョンを比較し、明示的にレビューした同期計画を vivac agents sync と同じ操作で適用できます。また「Artifacts」ページでは、保持された成果物を生成元と結び付け、正確なリビジョンを参照する判断を確認できます。チェック、キャプチャ、復元には成果物エンジンを使用します。ダウンロードでは、添付ファイルとして送信する前に、選択したリビジョンを検証します。静的な HTML、CSS、JavaScript のバンドルでは、宣言されたすべてのメンバーを1つのリビジョンとして保持し、新しいディレクトリに復元します。HTML のリビジョンとバンドルは、Vivac セッションとは分離された制限付きブラウザープレビューで開けます。成果物の保管と管理を参照してください。ここでは各項目の状態を自分で確認し、エージェントが見過ごしたものを見つけられます。

_{実際の vivac コマンドで書き出した4つのサンプルプロジェクトです。ページが変わるたびにこれらの画像を再撮影する tools/web-screenshots.py を使用しています。}

起動すると動き、閉じると終了するサーバーです。127.0.0.1 にバインドされ、表示される1回限りのキーを通じてアクセスできます。独自の機能はありません。ページに必要なものはすべて、まずコマンドライン上で構築されます。 → Web でできること、できないこと

---

1つのマップ

vivac はメモリシステムと競合するために作られたものではありません。 Alan Buscaglia による engram を使ったことがあり、 私もその開発に貢献しています。私が作ろうとしたのは意思決定の記録です。そして、その道のりにはメモリが必要だとわかりました。こうして vivac はメモリとしても機能するようになり、プロジェクト内のファイルに保存されるため、どのハーネスやモデルで開いても同じ内容を読み取れます。engram やほかのどのシステムよりも優れたメモリシステムではありません。別の目的のために作られました。

だからこそ、助言はどちらの方向にも当てはまります。すでにメモリシステムを使っていて、それでうまくいっているなら、vivac を追加しないでください。ツリーを目的に vivac を使うなら、ほかのメモリシステムを併用しないでください。どれであっても同じです。各システムはそれぞれ独自のコンテキストをモデルに注入し、2つのマップは衝突します。それぞれがエージェントに自らが保持する情報を示し、やがて一方がもう一方とは異なる形で示した内容を決定づけます。その意思決定をどちらが方向づけたのか、誰にも気づかれないままです。

これは推測ではなく、実際に確認されています。

• 書かれたルールによって、どのツールからも確認できない席が生まれることがあります。 あるプロジェクトでは、すべての更新をメモリシステムにも反映するようエージェントに指示していました。その結果、席が3つになり、実際に決定を左右していたのは、誰も調べられないものだけでした。
• 選んだかどうかにかかわらず、ハーネスは独自のマップを持ち込みます。 vivac を開発するプロジェクトでは、ツリーだけでスレッドを維持できるかを検証するため、ほかのものをすべて意図的にオフにしていました。それでも、ハーネスの自動メモリがプロジェクトの方針のコピーをすべてのセッションに注入し続けており、誰かが気づくまでに5日間かかりました。測定結果が間違っていたのではありません。測定は無効でしたが、何もそれを知らせてくれませんでした。

では、ハーネスだけではだめなのでしょうか？

ハーネスはセッションを提供します。しかし、3つのものは提供しません。その不在はそれぞれ、機能の不足ではなく、具体的な失敗につながります。

• エッジがありません。 学んだ内容は保存しますが、どの作業から得られたものかは保存しないため、たどって戻ることができません。
• フォーカスがありません。 想起される内容はすべて等しく存在し、そのどれにも 今ここにいる とは書かれていません。ましてや、より重要な そこには触れないでください とは示されません。
• 未完了と完了の状態がありません。 まだ不足しているものを報告できません。

そして、ハーネスのメモリはハーネスに属します。 ツールを変えれば、スレッドは引き継がれません。.vivac/ はプロジェクト内のファイルです。通常の JSON 行形式で、1つのコマンドでエクスポートでき、このバイナリがなくても読み取れます。

vivac は何もオフにしません。セットアップも同様です。別のシステムに触れる権限は vivac にはありません。vivac が提供するのは、エージェントが受け取るほかのすべてのマップを見つけ、ユーザーが許可した後に、元に戻せる形でそれぞれの使用終了を提案するスキルです。

---

コスト

理想ではなく、予算です。読み取りには 50 ms、書き込みには 5 ms が割り当てられており、達成できない場合は省略せず、そのことを明示します。

測定は2026年9月18日に、1万ノード、各セル200回の呼び出しで、2台のマシンと2種類のツリー形状を使って行いました。brief と open のコストは、ノード数ではなく、未完了のフロントがいくつあるかによって決まるためです。p99 の単位はミリ秒です。

	brief	why	open	find
CLI、コールドプロセス、Linux	15.5	18.8	20.4	19.9
MCP、常駐サーバー、Linux	0.5	7.1	4.2	8.8

MCP 経由の書き込みは p99 で 0.6 ms で、ツリーのサイズに左右されません。また、実際に制約となるのはコンテキストのため、ペイロードも測定しています。1万ノードでの vivac_open は1,993,053バイトから 599,012 バイトに、深いノードに対する why --json は86,894バイトから 7,139 バイトになりました。

→ 詳細な測定結果 — 2台のマシン、2種類のツリー形状、書き込みの表、Windows で達成できない項目とその理由。

---

保存しないもの

プロヴェナンスツリーは、システムの弱点と未修正の箇所を示すマップです。そのため、譲れないルールがいくつかあります。

• キーやシークレットは保存しません。 書き込み時に秘匿情報を保護します。判断に迷う場合は保存を拒否し、その理由を伝えます。黙って保存することはありません。
• 個人データは保存しません。 メールアドレス、氏名、ホームディレクトリのパスは保存しません。各イベントの actor は不透明な識別子です。
• プロヴェナンスログにファイルの内容は保存しません。 保存するのはパス、参照、決定内容に関する文章だけです。そのため、情報が漏えいしても、分かるのは 何に取り組んでいたか までで、コードの内容 までは分かりません。
• テレメトリーはありません。 バイナリが外部に接続することは決してありません。

これらは原則に基づいています。セキュリティは拒否権を持ち、パフォーマンスには予算を設け、UX は読む価値のある画面を示し、DX が判断を下します。

---

インストール

各リリースには、コンパイル済みバイナリが含まれています。Linux と macOS 向けは x86_64 および aarch64、Windows 向けは x86_64 です。バイナリは SHA256SUMS に記載され、ビルドの来歴情報に署名が付いています。展開して、vivac を PATH に追加してください。

Rust ツールチェーン（1.89 以降）と、同梱の SQLite 用 C コンパイラーがある場合：

cargo install vivac

cargo install は代替手段ではありません。crates.io で公開されているソースからビルドするため、作業内容を読み取るツールのサプライチェーンを確認したい人にとって、監査可能な方法です。 SQLite はバイナリにコンパイルされるため、実行時にシステムの SQLite や Python をインストールする必要はありません。リリースアーカイブにはコンパイル済みの依存関係が含まれています。

新しいリリースに更新するには、vivac update を実行します。現在の vivac のインストール方法と、置き換えに必要な手順を表示します。ビルドに使われた cargo install、または SHA256SUMS と照合した元のリリースアーカイブのどちらかを示し、同意すると更新します。Windows では、実行中のコピーを先に別の場所へ移すため、セッションを閉じるまでインストールが待たされることはありません。入力できるターミナルがない場合は、入力すべき内容だけを表示します。 → セットアップ

---

最初の5分

1. エージェントを起動するフォルダーで実行します。1つ目のコマンドでツリーを作成し、2つ目でエージェントにフック、開始用モジュール、サーバー、スキルを追加します。どちらも、変更するすべてのファイルと各フックが実行するコマンドを正確に表示してから、次のように確認します。

vivac init
vivac setup claude-code

Codex では vivac setup codex を使います。セットアップでは、視覚的または対話的なプレビュー用に vivac-artifacts もインストールします。バックエンドなしで動作する、自己完結型の HTML または HTML/CSS/JS のフロントエンドが対象です。キャプチャするリビジョンごとに、簡単な説明が必要です。SQLite を内包するフロントエンドには、インストール済みの sqlite_application 機能と、vivac が提供しリビジョンとともに保持する固定の JavaScript ランタイムも必要です。その他のファイルを引き渡す場合は、ユーザーが明示的に選択する必要があります。 セットアップによってファイルが自動的にキャプチャされることはありません。アーティファクトの管理をご覧ください。

2. 最初のスレッドを開始します。何をしているかは、いずれにせよ伝えるつもりだったでしょう。ここで伝えるだけで、手間をかけずにエッジが作成されます。

vivac push "Replace the cache adapter" --why "the session bug traces back to it"
vivac push "No test for expiry" --why "no way to reproduce it" --blocks
vivac pop "reproduced: sessions expire at 300s, not 3600"

3. 現在の状況とその理由を尋ねます。

vivac brief        where you are, and what NOT to touch
vivac why 2        the path from the root, narrated
vivac open         what is waiting on you, and what has been sitting
vivac web          the whole tree in a browser, on this machine only

これが基本の流れです。→ 各処理が実行されるタイミングと、エージェントが処理をスキップしたときに伝えること · すべてのコマンド

---

プロジェクトを取り込む

vivac に自動で取り込まれるものはありません。

プロジェクトですでに学んだことをメモリシステム、CLAUDE.md、AGENTS.md、MEMORY.md、ハーネス独自のメモリ、または内部ドキュメントに保存している場合でも、vivac setup の後に、それらがツリーに含まれることはありません。 vivac は他のシステムも、これらのファイルも読み取りません。ルールと周囲の文章を見分けるには判断が必要であり、推測するツールを使えば、初日からツリーが自信満々のナンセンスで埋め尽くされてしまうためです。

そのため、これはエージェントに任せる作業ですが、何を取り込むかはあなたが決めます。setup は vivac-migrate スキルをインストールします。次のように指示してください。

vivac-migrate スキルを使って、このプロジェクトが知っていることをすべて vivac に取り込んでください。

見つかったソースをすべて列挙し、どれを取り込むかを尋ね、書き込み前に計画を示し、書き込んだ内容を確認します。その後、他のマップを一つずつ使わないようにするか提案します。最後の手順こそが目的であり、単なる整理ではありません。 古い記録がまだエージェントに語りかける状態でツリーを完成させても、それは二つのマップであり、これによって抜け出せる状態そのものです。

→ プロジェクトを取り込むと実際のプロジェクトで起きたこと：8 件の移行、そのうち 2 件はソースごとに測定し、各失敗から何が変わったかを紹介します。

---

レーン

一つの製品を複数のフォルダーで作業することがあります。main のチェックアウト、ホットフィックス用の 2 つ目、他の人のブランチをレビューするための 3 つ目。または、一つのフォルダーで一日に 10 回ブランチを変更する場合です。

フォルダーが分かれても、記録を分岐させてはいけません。 これは何から生まれたのか？ という問いへの答えは、製品ごとに一つです。チェックアウトごとに一つではありません。3 つのツリーがそれぞれ違う答えを返すなら、それは誤った答えが 3 つあるということです。

そのため、ツリーは製品に属し、その製品を扱う各フォルダーはレーンになります。ブランチは書き込みごとに記録される事実であり、ツリーが保持するものではありません。

これによって、ブランチがいつ自分の作業中に移動したか、また前回ここに書き込んでから他のレーンで何が行われたかを、概要で確認できます。

状況	実行する内容
同じツリーを使う別のフォルダー	そのフォルダーでも vivac init を実行し、続けて vivac setup claude-code を実行します
まったく別の場所にあるフォルダー	vivac init --join <name> を実行し、続けて vivac setup claude-code を実行します
ツリーを別の場所に置く場合	vivac relocate <destination> を実行します
既存のレーンと、それぞれの現在の状態	vivac stack --lanes を実行します

同じフォルダー内で別のハーネスを使う場合も含め、claude-code を使う箇所では codex に読み替えてください。フォルダーが取得するファイルを決めるのはハーネスであり、ツリーについては何も決めません。

→ docs/LANES.md — レーンとは何か、何ではないか、そして間違いやすい 4 つの方法について説明します。

---

ここでの測定内容

Claude Code	vivac setup claude-code は、開始モジュール、フック、サーバー、スキルを書き込みます。このページの測定で使用したハーネスはこれです。これらの測定は、新しい開始モジュールのベンチマークではありません。開始モジュールについては、別個のネイティブチェックを説明した指示の配信をご覧ください。
Codex	vivac setup codex を実行すると、Codex が読み取るプロジェクトも同じように準備が整います。2026年9月22日に、実際の Codex セッションを最初から最後まで確認しました。プロジェクトを信頼するとサーバーが解決され、モデルにスキルが提示され、開始フックがブリーフをエージェントのコンテキストに入れ、終了フックが停止マーカーを残します。既存の内容にマージされ、2回実行しても2回目は何も書き込まず、同じ3つのフラグで Claude Code 側と同じように自身を元に戻します。ツリーはどちらか一方のものではありません。vivac init が一度だけ配置し、両方のハーネスが配置されたものを読み取ります。
その他すべて	フックは通常のコマンドを呼び出します。セッション開始時にコマンドを実行し、その出力をエージェントのコンテキストに入れられるハーネスなら、同じコマンドを呼び出せます。また、どの MCP クライアントでも vivac mcp を実行できます。MCP Registry での名前は mcp-name: io.github.JAAvila-Of/vivac です。

この一連の確認のうち、測定されておらず、測定もできないステップが1つあります。Codex 内で各フックを承認するのは人が一度行うことであり、人を見ることは測定ではありません。

チームモードにはまだ対応していません。プロジェクトは 0.x であり、マイナーバージョンで破壊的変更が入ります。

---

ドキュメント

各コマンドの実行タイミング	セッションの各時点、各時点で動作する主体、エージェントがいずれかを省略した場合の伝え方
使い方	実行者別にまとめたすべてのコマンド
セットアップ	セットアップで書き込まれる内容、Codex、MCP サーバー、保存場所
エージェントの管理	インベントリ、ガイド付き同期、ウェブ比較、明示的なモデル割り当て
プロジェクトの取り込み	移行について、そして追加ではなく移行である理由
レーン	1つの製品、複数のフォルダー、1つのツリー
コスト	すべての測定内容と測定方法
バージョン管理	いつ何が破壊的変更となるのか、そして 1.0 への移行を妨げているもの
位置づけ	ツールの各カテゴリが保存する内容と、それぞれがこれより優れている点
柱となる原則	ここでのすべての判断を評価する4つの基準
成果物の管理	対応する SQLite アプリケーションを含む、選択したファイルと完全なフロントエンドバンドルを保持し、正確なリビジョンを参照・復元する方法

ライセンス

利用者が選択する MIT OR Apache-2.0 です。それぞれのライセンス本文は LICENSE-MIT と LICENSE-APACHE にあります。

ライセンスが適用されるのはコードであり、名前ではありません。フォークは自由ですが、独自の名前で公開してください。名前とロゴの使用方法については TRADEMARKS.md に記載されています。セキュリティ上の欠陥は、SECURITY.md の説明どおり、非公開で報告してください。