supragnosis

supragnosis

誰が言ったかも覚えている、AI エージェントのためのメモリーです。

コーディングエージェントのための、記録付き共有プロジェクトメモリーです。supragnosis は、Claude Code、Codex、Cursor、その他の MCP クライアント向けのローカル MCP サーバーです。エージェントは作業しながら学んだことを記録し、すべての主張には、誰が、誰の代理として、どのような根拠に基づき、このノードがどの程度信頼しているかが保持されます。矛盾する主張は、後からの主張が先の主張を上書きするのではなく、あなたが解決できるよう並んで残ります。

ベンダーのクラウドを使わず、各自のマシンにある1つのプロジェクトのメモリーをチームメイトと共有したい小規模チーム向けに作られています。単一のバイナリー、組み込みストア、アカウント不要です。ワークスペースがマシンの外に出るのは、あなたが共有対象に指定したときだけです。

supragnosis = supra (above) + gnosis (knowing) - knowledge about knowledge.

解決する課題

ほとんどのエージェントメモリーが答えるのは、何を記憶したかです。誰がそう言ったかには答えません。

1人のユーザーの好みを1つのアシスタントが記憶するだけなら、それで問題ありません。しかし、2つのエージェント、2台のマシン、または2人の人が同じメモリーに書き込むようになった途端、問題になります。

• 2つのエージェントが正反対の事実を主張します。最後に書いたものが勝ち、意見の相違は消えてしまいます。
• エージェントが汚染された文書をメモリーに要約します。出所が記録されないため、その要約が他に何を汚染したかをたどる方法がありません。
• プロジェクトの知識をチームメイトと共有しつつ、個人的なメモは共有したくないとします。しかし、ストアには誰の知識かという概念がないため、境界を設けられません。
• 認証情報がログに入り込んでしまいます。それを見つける方法も、取り除く方法もありません。

supragnosis では、主張と事実を別のものとして扱います。保存されるのは「Xは真実である」ではなく、「ホストHが、時刻Tに、根拠Sに基づいてXを主張した」という情報です。現在の信念は、置き換え可能なポリシーに従ってそれらの主張から計算されます。そのため、競合の解決方法について考えを変えた場合も、書き換えではなく再計算で対応できます。

それによって得られること

すべての主張に来歴を記録	操作を行ったホスト、代理する主体、ワークスペース、ソース、観測時刻、信頼度、および受信ノードが受け入れるのではなく計算する信頼階層
競合が見える状態で残る	矛盾する主張が共存し、片方が黙ってもう片方を上書きするのではなく、調停のために表面化します
何も破棄されない	観測ログは追記専用で、コンテンツアドレス方式です。訂正は新たな観測として記録され、マージは元に戻せます
正規情報として確定する前にゲートを設置	エンティティのマージ、信頼度の昇格、スキーマの変更は、判定によって覆される内容の差分を計算した提案を通じて行われます
共有はオプトイン方式	ワークスペースがノードの外に出るのは、共有対象に指定した場合だけです。ピアは、同期経路とクエリ経路の両方で、ワークスペースごとに認可されます
シークレットは取り込まれない	認証情報のような形式のテキストは書き換えられるのではなく、取り込み時に拒否されます。複製済みの追記専用ログからは取り消せないためです
ローカルファースト、クラウド不要	単一のバイナリー、組み込みの純粋なRust製ストア、アカウント不要。ピアを設定しない限りネットワーク接続もしません

クイックスタート

brew tap ashon/tap
brew install supragnosis-server
supragnosis service install         # MCP on :7373 + local viewer, now and at every login
supragnosis connect claude-code     # or claude-desktop, cursor, vscode, codex, gemini, opencode

アプリを指定せずに supragnosis connect を実行すると、アプリの一覧と、それぞれの接続方法が表示されます。アプリに supragnosis bridge を登録します。これはデーモンに中継する stdio サーバーで、デーモンのベアラートークンを ~/.supragnosis/mcp.token（モード 0600）から自身で読み取るため、アプリの設定にトークンのコピーが保存されることはありません。ローカルサーバーを stdio でしか利用できない Claude Desktop にも接続できます。URL を使うクライアントの場合は、トークンを指定して http://127.0.0.1:7373/mcp を使えます。supragnosis status はコマンドを表示しますが、トークンを表示せず、ファイルから読み取ります。

Claude Code では、connect がフックも登録するため、何も頼まなくてもメモリが蓄積されます。エージェントがコミットした後、diff からはわからない変更の背景にある判断についてエージェントに質問し、セッションの開始時には、このプロジェクトのワークスペースにある内容を把握できるようにします。--no-capture を指定するとフックは登録されません。フックが自ら何かを書き込むことはありません（docs/client-connect.md のセクション 12）。

デスクトップアプリ（brew install --cask supragnosis）では、設定ページ（メニューバーの Settings...、または Cmd+,）から、ターミナルを使わずに両方を設定できます。「ログイン時に起動」を有効にするとデーモンが起動したままになり、「AI アプリ」からは Claude Desktop、Claude Code などをワンクリックで接続できます。brew upgrade の後は、supragnosis restart を実行して新しいバイナリを読み込みます。それまでは、supragnosis status とメニューバーに、デーモンが古いバージョンで実行中と表示されます。

Homebrew を使わない場合：

curl -fsSL https://supragnosis.dev/install.sh | sh    # ~/.local/bin, checksum-verified
supragnosis service install                           # macOS; Linux: deploy/systemd
supragnosis connect claude-code

検索はキーワードだけでなく、セマンティック検索にも対応しています。ローカルの埋め込みモデル（多言語対応、224 MB、API 呼び出しなし）は、service install が一度だけ ~/.supragnosis/models にダウンロードします。手動で行う場合は supragnosis embed fetch を実行します。モデルがまだない間はキーワード検索のみとなり、supragnosis status にその旨が表示されます。ツール呼び出しでモデルを読み込むと、デーモンは約 1 GB のメモリを使用します。SUPRAGNOSIS_EMBED=none を指定すると、キーワード検索のみとなり、使用量を抑えられます（docs/semantic-retrieval.md）。

アンインストールすると、デーモンのログイン時起動を解除し、各 AI アプリの接続を解除して、バイナリを削除します。~/.supragnosis のナレッジは残ります。削除する場合は、そちらも削除してください （deploy/README.md, Operations）。

最初の1分

普段使う言葉で、エージェントに何かを記憶するよう頼んでみましょう。

あなた： このリポジトリの認証は有効期限15分の JWT だと覚えておいて。モバイルクライアントではセッション Cookie を保持できないため、この方式に決まった

エージェントは observe を呼び出します。記録されるのはその文章ではなく、名前の挙がったエンティティ、それらの間の関係、発言者を含む観察情報です。

observed  "auth in this repo is JWT with a 15-minute expiry..."
          entities   JWT [AuthMechanism], mobile client [Component]
          relations  repo --uses--> JWT,  JWT --constrained_by--> mobile client
          provenance host=your-laptop  on_behalf_of=you  tier=agent_extracted

後で、コンテキストウィンドウにその情報が何もない別のセッションで：

あなた： ここでは認証をどのように実装していますか？

エージェント： 有効期限15分の JWT です。これはコードを読んで得た情報ではなく、あなた自身が直接伝えた内容で、理由として、モバイルクライアントではセッション Cookie を保持できないと述べていました。

回答の後半が重要です。検索結果として返るのは一致した内容の ID で、その ID から出典をたどれます。get_entity はエンティティの根拠となるすべての証言を一覧表示し、元になった観察情報（supragnosis://observation/{id}）には、元のテキストと、誰が誰にいつ伝えたかが記録されています。そのため、エージェントは 誰が伝えたのか、どの程度確かなのか を教えることができ、あなた自身でも内容を確認できます。

ビューアーはデーモンと並行して unix ソケット上で動作します。デスクトップアプリから開くか、直接読み取れます。

curl -s --unix-socket ~/.supragnosis/viz.sock http://localhost/api/graph

エージェントの作業中にビューアーを見る様子は、文章で伝えるのが難しい部分です。

## エージェントが利用できるもの

13 個の MCP ツールがあり、それぞれに繰り返し使われる用途があります。

• observe - 自由記述のテキストと、任意の構造化された主張を受け付けます。事前にスキーマを用意する必要はありません。
• search_knowledge - キーワード検索（すべての語句を対象とし、順不同）とセマンティック検索を行い、使用したモードを示します。
• get_entity、traverse - 完全一致での検索と、範囲を限定したグラフ探索を行います。
• workspace_map - 共起するハイパーエッジ、つまり、何が一緒に語られる傾向にあるかを示します。
• define_type - パターンをワークスペースの用語集に登録します。
• propose、review、list_proposals、get_proposal - 正典に登録するためのゲートです。
• sync_status、sync_pull、sync_push - フェデレーションを行います。

さらに、参照可能なリソースがあります。supragnosis://workspaces、supragnosis://workspace/{ws}/graph、supragnosis://workspace/{ws}/hypergraph、supragnosis://workspace/{ws}/types、supragnosis://observation/{id}。

利用できるもの

4 つの MCP プロンプトがあり、クライアントはこれらをコマンドとして提供します（Claude Code では /mcp__supragnosis__brief）。

• brief - ワークスペースの知識の現在の概要です。テーマ、異論のある点、単一のエージェントによる主張にのみ基づく点、判断待ちの項目を示します。
• what-do-we-know-about - あるトピックについて、保存されている内容とその情報源、および保存されていない内容を示します。
• curate - モデルが、キュレーションのシグナルが示す整理について提案を作成します。
• review-proposal - ある提案について、統合によって何が変わるのかを示し、推奨案を提示する一次レビューです。

モデルは現在の状態だけをもとに概要を作成し、何も保存しません。残しておく価値のある判断は提案となり、アプリの Review パネルで判定を下します。残ったものが正典となり、次の概要に反映されます。docs/prompts.md を参照してください。

仕組み

3 つの考え方があり、ほかのすべてはそこから導かれます。

イベントソーシング。 不変でコンテンツアドレス指定された観測が信頼できる情報源です。エンティティと関係のグラフは、ログを再生して破棄・再構築できるプロジェクションです。解決ポリシーの変更は移行ではなく、再プロジェクションです。

トポロジーに依存しない収束。 同じ観測セットを保持するノードは、イベントがどの経路をたどり、どのような順序で到着したかにかかわらず、同じグラフを生成します。コンテンツアドレス指定で重複を排除し、ハイブリッド論理クロックで順序を決定し、プロジェクションは決定論的な畳み込みとして構成されます。ローカルのみ、ハブアンドスポーク、直接ピア接続、またはその組み合わせのいずれであっても、トポロジーは運用上の選択であり、意味には影響しません。

ヘキサゴナルポート。 ドメインクレートには IO 依存関係がありません。ストア、エンベッダー、トランスポートは、共通の適合性テストスイートに準拠するポートの背後に置かれています。これは単なる目標ではありません。異なるクエリパラダイムと異なるストレージエンジンを持つ 3 つ目のストアアダプターを追加し、元のバックエンドを削除しましたが、core や engine のコードは一行も変更していません。

ドキュメント

architecture.md	何がどのように構築されているか、および第 14 節：実装されていないものについての率直な記録
principles.md	規範となるドキュメントです。すべての設計判断が、この原則に照らして正当化されています
federation.md	ノード ID、同期プロトコル、信頼性評価
proposal-workflow.md	正典に登録するためのゲート
resolution.md	主張が現在の信念になる仕組み
excision.md	知識を削除する唯一の操作と、それが最後の手段である理由
consolidation.md	何も削除せずにワークスペースを整理された状態に保つ方法
CONTRIBUTING.md	ビルド、テスト、変更の提出方法

ステータス

現在対応済み：ハイブリッド検索、異議のある主張を明示した信念の解決、取り消し可能なエンティティ統合ゲートを備えた ID 解決、TLS 上で ed25519 署名付きイベントを使用するハブアンドスポーク型ログレプリケーション、ライブビューアー。

未対応：二時点間のタイムトラベルクエリ、複数プリンシパルのガバナンス、検索順位の引き下げとアイドル時の統合、自動的な型の推定。

2 つ目のリストは、単なるロードマップ上の表明ではありません。未達の要求はそれぞれ、宣言済みのエビデンス状態を持つ名前付き条項であり、principle_coverage.rs によってテストされています。また、延期した項目には、対応が行われるマイルストーンがそれぞれ明記されています。ガードを削除または改名すると、その条項は自身がガードされていないことを報告します。architecture.md のセクション 14 を参照してください。

互換性。 ストアが誤って読み込まれることはありません。リリースは、以前のリリースが書き込んだストアをその場でアップグレードします。それより後のリリースが変更したストアに遭遇した場合は、変更を一切加えずに拒否し、インストールすべきリリースをメッセージで示します。一度作成された ID や署名は、その後のすべてのビルドで検証できます。1.0 より前は、マイナーリリースでストアの必要条件が引き上げられる場合があり、その場合はリリースノートで事前に告知します。CLI の --json の応答にはスキーマ番号が含まれます。MCP ツールに対する破壊的変更は、Breaking changes に記載されます。互換性に関する全体的な約束と、フェデレーションの設計（同期ワイヤー）に委ねられる内容については、docs/compatibility.md を参照してください。

設定

すべての項目に、そのまま使えるデフォルト値が設定されています。設定項目の一覧は supragnosis --help、デフォルト値の根拠は docs/architecture.md を参照してください。

よく使う設定：

• SUPRAGNOSIS_WORKSPACE - デフォルトのワークスペース（デフォルトは default）
• SUPRAGNOSIS_DATA_DIR - ストアのディレクトリ（デフォルトは ~/.supragnosis/redb）
• SUPRAGNOSIS_EMBED - fastembed（デフォルト） | hashing | none。none はキーワード検索のみです
• SUPRAGNOSIS_EMBED_MODEL - multilingual（デフォルト） | bge-small-en（英語のみ、サイズは半分）
• SUPRAGNOSIS_CONFIG - supragnosis.toml へのパス。ファイルがない場合はスタンドアロンノードになります
• SUPRAGNOSIS_MCP_AUTH - on（デフォルト） | off。off にすると、デーモンのベアラーチェックが無効になります

MCP HTTP デーモンはループバックのみで待ち受け、ベアラートークンを必須とします。この 2 つのガードが別々にあるのは、ループバックが、一般に思われているものとは異なる問いに答えるからです。ループバックによってアクセス範囲が限定されるのは、この ホスト であり、1 人の ユーザー ではありません。そのため、共有マシンでは、そうしなければローカルアカウントを持つ人なら誰でも、このデーモンを通じて observe、review、sync_push を実行できてしまいます。トークン（~/.supragnosis/mcp.token、モード 0600）によって、このインターフェイスへのアクセスを自分だけに限定します。これはビューアーがソケットファイルで実現しているのと同じアクセス制御です。ビューアーは Unix ソケットに移行できますが、MCP クライアントは HTTP を使用するため、デーモンは移行できません。

ビューアーには TCP ポートが一切ありません。モード 0600 がアクセス制御となる Unix ソケット経由で提供され、すべての応答に Content-Security-Policy が含まれます。ループバック以外にフェデレーションをバインドするには、TLS と、参加を許可されたノードまたは公開招待が必要です。どちらかが欠けている場合は起動しません。

2 台目のマシンは、コードを使って参加します。ハブとなるマシンで supragnosis invite を実行し、もう一方で supragnosis join を実行してください（docs/pairing.md）。それぞれが独自のデーモンを維持し、互いに同期します。

pre-0.2 ストアからのアップグレード

v0.1.21 まで、ストアには Cozo が使われていました。このビルドは redb のみを読み込み、未移行の Cozo ストアと並んで空の状態で起動するのではなく、起動を拒否します。まず docs/store-migration.md のセクション 5 を読み、その後、次のコマンドを実行してください。

supragnosis stop
curl -fsSL https://supragnosis.dev/install.sh | sh -s -- --version v0.1.21
supragnosis migrate-store
curl -fsSL https://supragnosis.dev/install.sh | sh
supragnosis start

ライセンス

MIT または Apache-2.0（任意）。LICENSE-MIT と LICENSE-APACHE を参照してください。

別途明記されていない限り、収録を意図して提出されたすべてのコントリビューションは、追加条件なしで上記のデュアルライセンスの対象となります。