SoupNet-oss

Soup.netはAIエージェントのための共有メモリです。あなたと一緒に働くエージェントが、判断の瞬間をその場で記録し、次のセッションや別のツール、あるいはプロジェクトに参加する協力者のエージェントにそれを持ち帰ります。レシピブックは自動的に構築されます。

保存の単位はレシピです。構造化され、証拠に裏付けられた1つの判断 — 「[役割]として[目標]に取り組む際、[理由]のために[X]を好む」 という形式に、逐語的な裏付けとなる引用が付きます。エージェントはレシピチェックを通じてこれを使います。これは、副作用が追記のみであるセマンティック検索です。エージェントはあなたの好みに関する現在の仮説で検索し、証拠付きの過去の判断を受け取り、その仮説自体が将来のエージェントが見つけられるトレースになります。何も上書きされることはなく、チェックのたびに次のチェックがより賢くなります — これはアリがフェロモンの痕跡を強化するのと同じ仕組み（スティグマジー）です。

なぜ

AIエージェントはますます大きな作業を単独で完了するようになり、しかもあなたは1つだけを使うわけではありません。新しいセッションは毎回新しいエージェントであり、ツールごとに別のエージェントがあり、協力者もそれぞれ自分のエージェントを持ち込みます。それぞれがあなたの回答を、別々に、ゼロから必要とします。希少なリソースはあなた自身です。

ほとんどのエージェントメモリは、特定ベンダーのエコシステム内で事実や会話状態を保存します。Soup.netは判断そのものを、それをスコープする文脈と証拠とともに保存し、あなたとともに残ります — Claude Code、ChatGPT、Gemini、あるいはあなたのチームが社内で作ったカスタムエージェントを問わず移植可能です。過去の判断は指示ではなく文脈として戻ってきます。エージェントは古い事実を再生する代わりに、現在のタスクと照らし合わせて判断を評価します。

すべてのチェックが日付入りの追記専用トレースを残すため、観測可能性も無料で手に入ります。エージェントがあなたに代わって行使した判断の、検査可能なログが1つ得られるのです。エージェントがチェックインの間隔を長くして実行されるようになっても、その記録こそがあなたをドライバーズシートに留めておくものです。

Soup.netは独自のワークフローで開発されています。それを構築するAIエージェントは、作業中に設計判断をメンテナーのコーパスにレシピチェックとして記録します — つまり、システムの設計履歴はシステム内に生き、それを拡張するエージェントは、自分が変更しているコードを形作った判断を取得するのです。

レシピマップは、人間がそのコーパスの成長を観察する方法です。レシピは意味的類似性によってクラスタリングされ、あなたが選んだ任意の2つの概念軸に投影されます。

Related MCP server: memmd-mcp

フィールドデータ

2026年半ばに、メンテナーの実際の作業でフィールド評価が実施されました — 2つのプロジェクト、サブエージェント群を生成するコーディネーターエージェント、すべてのエージェントが判断の瞬間にチェックし、各チェックが何をもたらしたかを自己報告するよう指示されました。正直な範囲: 開発者1名、3ヶ月のコーパスに対する3日間のフィードバック期間、すべてClaudeファミリーのエージェント。観察研究であり、ベンチマークではありません。

• 64の異なるエージェントセッションで178回のチェックが行われ、1つの結合可能なログに記録されました。

• チェックの68%が過去の判断を確認し、エージェントは人間を中断せずに作業を続けました。

• チェックの約4.5%がエージェントの行動を変更しました。設計上まれですが、その裾野に価値が集中します。最も顕著なケースは、エージェントの慎重だが誤った「このインデックスは削除」という結論が人間によって異議を唱えられ、再テストされ、覆され、将来のエージェントが再導出できないように恒久的に記録されたことでした。

• 監査された12件中12件の高影響ケースが生のコーパスに対して有効であり、矛盾するものはありませんでした。

• コスト: チェックあたり約1〜3KBの返却コンテキスト、4〜6KBのセッションブリーフィング、0.15〜0.36秒のウォームチェックレイテンシ。

同じ評価から判明した既知の失敗モード: 自己報告は一度も「ノー」と言いませんでした（すべてのパーセンテージを上限として扱ってください）; 若いコーパスでは約10回に1回のチェックで何も返りません（これはシーディングであり、失敗ではありません）; セッション終了時のバッチチェックは、ほとんどがエージェント自身の新しいトレースを取得します。締めくくりの儀式ではなく、判断の瞬間にチェックしてください。そして正直なギャップが1つ: プレーンURLパスはChatGPT（ウェブ）、Gemini、Claudeで動作確認済みですが、これまでの計測されたフィールド行はすべてClaude Code内のClaudeファミリーエージェントからのものであり、クロスベンダーの有効性の数値はまだ存在しません。別のハーネスから実行する場合、あなたが最初の実データを生成することになります。

試す

• ホステッド — 無料、新規登録受付中: soup.net。このサイトは、ウェブ専用チャットボットからフルMCPクライアントまで、使用するあらゆるエージェント向けのワンクリックブリーフィングを生成します。claude.aiでは、Connectors Directoryのリストからワンクリックで接続できます（Freeを含むすべてのプラン）。

  ウェブチャットボットパスはフォールバックではなく第一級のインターフェースです。MCPを持たないエージェントは生成されたリンクを通じて参加します — レシピチェックは、エージェントが構築するか人間がクリックするURLです。ChatGPT（ウェブ）、Gemini、Claudeで動作確認済みで、無料ティアも含みます。

• セルフホスト — MITライセンス、意図的に地味なスタック（Postgres 17 + pgvector、Hono、React）。コアのチェックパスではサーバー上でLLMは実行されません。エージェントはすでに実行されている場所で推論を行い、サーバーはストレージとベクトル検索を行います。（オプションのプレミアム機能 — デフォルトでオフ、ユーザーごとにオプトイン — はサーバーサイドのLLM呼び出しを1回使用します。docs/planning/premium-llm-features.mdを参照。）埋め込みはデフォルトでGoogleのGemini APIを使用します（AI Studioキーで動作します。決定的なスタブプロバイダーがAPI呼び出しゼロで開発とテストをカバーします）が、セルフホスターはキーなしで完全にローカルで実行できます — プロセス内CPU、または任意のローカル/v1/embeddingsサーバー（下記のローカル/オフライン埋め込み）に対して。Geminiはオプションのプレミアム機能にのみ必要になります。クイックスタートは下記。どちらの場合も、コーパスは単一のJSONファイルとしてエクスポートされます（サインインしてGET /auth/me/export）— そしてインポートも可能です: POST /importは同じファイルを生のリクエストボディとして受け入れます（サインイン済みの人間のみ）。これにより、コーパスはインスタンス間を移動したり、バックアップから復元したり、新しいレシピブックに再構築したりできます。デフォルトではインポートは新しいレシピブックを作成します（?book_name=で命名）; 既存のブックにインポートするには?book=<slug|id>を渡します。自分のコーパスの再インポートは冪等です（正確なIDのアップサート — 再アップロードではすでに存在するものはスキップされます）; インスタンス上の他の誰かに属するIDを持つコーパスをインポートすると、新しいIDが生成され、旧→新のマッピングが報告されるため、これは移植ツールであり、バイト単位の同一復元ではありません（IDなしで行が到着してもインポートは可能です）。インポートはコンテンツアドレス型ベクトルキャッシュを通じて非同期に再埋め込みされるため、インスタンスが以前に埋め込んだテキストはプロバイダー呼び出しコストがゼロです — また、アカウントを削除してもその共有キャッシュは保持されるため、同じコーパスの再プロビジョニングは無料のままです。

MCP対応エージェントをホステッドサービスに1行で接続します:

claude mcp add --transport http soupnet https://mcp.soup.net/mcp --header "Authorization: Bearer YOUR_KEY"

詳細

• docs/benchmarks.md — PERMA、SWE-Lancer、π-Benchにわたる管理されたベンチマーク結果（要約 + ベンチマークごとの詳細ページ）。上記のフィールドデータを補完します

• docs/design-thinking.md — プロダクトビジョン、ユーザーアーキタイプ、レシピチェックシナリオ

• docs/architecture/overview.md — システムトポロジー、3つのエージェントサーフェス、データモデルの概要

• docs/architecture/ranking-engine.md — check_recipeランキングエンジン: 目標、パイプラインの段階別詳細、拡張ポイント、仮説レジスタ

• docs/planning/pivot-search-as-logging.md — 検索をロギングとして使うピボット（決定履歴）

• docs/engineering-principles.md — すべての設計判断を支配する13の原則

• docs/backlog.md — 現在の作業キュー。完了項目はdocs/backlog-completed.mdに

• docs/adr/ — 日付とステータス行付きのアーキテクチャ決定

• docs/testing-plan.md、docs/workflows/security.md — テストと監査の仕組み

各ドキュメントの先頭セクションには、その目的と近隣のドキュメントとの違いが記載されています。新しいドキュメントを追加する場合は、同じことを行い、このセクションにリンクしてください。

クイックスタート

cp .env.example .env
# Edit .env: set JWT_SECRET (openssl rand -hex 32), DEV_USERNAME, DEV_PASSWORD.
# GEMINI_API_KEY is optional locally — leave EMBEDDINGS_PROVIDER=stub for tests.

docker compose up --build -d    # postgres + backend (with in-process embedding worker) + mailpit
npm run dev:frontend            # Vite SPA on :5273 (separate terminal)

http://localhost:5273を開く — ログインし、レシピチェックリンクを生成して、レシピのチェックを開始します。

ローカル開発用のMailpit Web UI: http://localhost:8625

ローカル/オフライン埋め込み

セマンティック検索には埋め込みプロバイダーが必要で、EMBEDDINGS_PROVIDERによってプロセス全体で選択されます。デフォルト（gemini）はGoogleを呼び出します。stubは開発/テスト用に決定的なフェイクベクトルを返します。さらに2つのプロバイダーにより、セルフホスターは外部APIもキーもなしで実際のセマンティック検索を実行できます:

• local — @huggingface/transformersによるプロセス内CPUモデル（デフォルトはbge-small-en-v1.5）。EMBEDDINGS_PROVIDER=localを設定するだけ — モデル（約23MB）が一度ダウンロードされます。最も摩擦が少なく、試用やCIに適しています。

• openai-compatible — 任意のローカルOpenAIスタイルの/v1/embeddingsサーバーを指すため、すでに実行しているツールでより強力なモデルを提供できます:

  EMBEDDINGS_PROVIDER=openai-compatible
  EMBEDDINGS_BASE_URL=http://localhost:8080/v1   # llama.cpp: llama-server -m <model>.gguf --embedding --pooling mean
  EMBEDDINGS_MODEL=<the id the server reports>
  # EMBEDDINGS_API_KEY=...                        # optional bearer, if your server requires one

  LM Studio（http://localhost:1234/v1）、Ollama（ollama pull nomic-embed-text → http://localhost:11434/v1）、Hugging Face TEIはすべて同じように動作します — 任意の/v1/embeddingsエンドポイント。Soup.netが独自のコンテナで実行されている場合、localhostはコンテナを意味します: host.docker.internalまたはホストIPを使用してください。

2つの注意点。 デプロイメントごとに1つの埋め込みプロバイダー — 異なるモデルからのベクトルは異なるセマンティック空間に存在し、決して混在されないため、プロバイダーやモデルを切り替えるとコーパスの再埋め込みが必要になります（それまで検索は空の結果にフェイルセーフします）。また、モデルのネイティブ次元は3072以下（またはMRL対応）である必要があります。内部的には、3072未満のベクトルは既存のhalfvec(3072)列にゼロパディングされます。これはコサインに対して証明可能なロスレスです — 設計、数学、終了基準は**ADR-0023とdocs/planning/local-embedding-provider.md**にあります。

リポジトリ構成

これはリポジトリ全体のオリエンテーションマップです。独自のREADME（またはトップドキュメントに明記された目的）を持つサブディレクトリは詳細を担い、このマップはそれらにリンクします。

apps/backend       Hono HTTP server (port 3101) — auth, REST API, /check recipe page,
                   remote MCP endpoint (/mcp), plus in-process pg-boss embedding consumers
                   (src/embedding-worker/). See ADR-0020, ADR-0021.
apps/frontend      Vite React SPA (port 5273) — dashboard, recipe map, admin pages
apps/mcp-server    Stdio MCP server (bundled as soupnet.mcpb for Claude Desktop)

packages/db        Drizzle schema + migrations — single claimnet schema, single source of truth
packages/domain    Business logic, ranking rules, shared agent-facing copy (no I/O)
packages/contracts Zod schemas + OpenAPI registry (mostly pre-pivot shapes; new routes inline-validate)
packages/client-sdk REST API client wrapper
packages/api-client Auto-generated React Query hooks (regenerated from contracts)
packages/config    Shared tsconfig, ESLint config

docs/              Top level: design-thinking.md, engineering-principles.md, testing-plan.md,
                   backlog.md + backlog-completed.md (the cross-session work queue)
docs/adr/          Architecture decision records — dated, with status lines
docs/architecture/ How the code works: overview, search algorithms, data model (generated)
docs/planning/     Validated proposals ready (or nearly ready) to implement
docs/rough-notes/  Dated working notes, meant to rot — see its README for the contract
                   and the fidelity ladder (rough-notes → planning → adopted docs/ADRs)
docs/workflows/    Repeatable processes (security audit cycle, etc.)
docs/connectors/   Connector-facing docs (claude.ai directory submission material)
docs/legal/        Privacy policy + ToS source material

scripts/           Dev/ops one-offs: test-ci-local.mjs (the canonical gate), cleanup,
                   data-model doc generation, QA harnesses

MCPセットアップ

主要なパスはStreamable HTTP上のリモートMCPです（ステートレス、ADR-0021）。エージェントをバックエンドの/mcpエンドポイントにAPIキーをBearerトークンとして指定して接続します — ローカルで実行する場合（http://localhost:3101/mcp）も、デプロイ済みインスタンス（https://mcp.soup.net/mcp）に対して実行する場合も同じように動作します。

2つの認証経路、1つのエンドポイント。 APIキーBearer（下記）は、キーを貼り付けるのが自然な開発者ツールに適しています。チャット形式のクライアント（claude.ai、ChatGPT Developer Mode、Mistral Le Chat、Perplexity）は、同じ /mcp URL に OAuth 2.1 で接続します。サーバーは RFC 8414 メタデータ（/.well-known/oauth-authorization-server と /oauth-protected-resource）、動的クライアント登録（RFC 7591、POST /oauth/register）、レシピブックごとの同意画面を備えた PKCE-S256 認可、およびリフレッシュトークンのローテーション（apps/backend/src/routes/oauth.ts）を実装しています。claude.ai では、Soup.net は Anthropic Connectors Directory に掲載されたコネクタであり、claude.ai/directory/soupnet からワンクリックで接続でき、Free を含むすべての Claude プランで利用可能です。クライアント別の手順書: docs/connectors/index.md（soup.net/info/connect で表示）。

1. APIキーを生成する — SPA にログインし、API keys を開き、日次またはスコープ付きキーを作成し、生の値をコピーします。

2. サーバーを追加する。 Claude Code では1行で完了します:

claude mcp add --transport http soupnet http://localhost:3101/mcp --header "Authorization: Bearer YOUR_KEY"

HTTP-MCP クライアントは、設定スキーマでの呼び名が何であれ、同じ3つの情報を使用します:

{
  "mcpServers": {
    "soupnet": {
      "type": "http",
      "url": "http://localhost:3101/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}

クライアント別の設定ブロック（Codex、VS Code、Google Antigravity、mcp-remote または apps/mcp-server/ 内の stdio サーバー経由の Claude Desktop）は、/docs/mcp-setup のガイドにあります。これは自分のインスタンスで提供されるか、ダッシュボードからアクセスするとキーが事前入力されたホスト版として提供されます。フォークされたコピーではなく、1つの生きたページです。

3. クライアントを再起動する（または Claude Code で /mcp を実行）と、新しいサーバーが認識されます。利用可能なツール: check_recipe、get_briefing、list_my_recipe_books、update_recipe_book_description。

ツールの契約は読み取り＋追記のみです。更新や削除の表面はないため、混乱した（またはプロンプトインジェクションされた）エージェントはトレースを追加できても、記録を破壊したり書き換えたりすることは絶対にできません。MCP サーバーをセキュリティ態勢の観点で評価するなら、知っておく価値があります。

開発

前提条件: Node 24 LTS、npm ≥ 10、Docker

Docker ですべてを起動:

docker compose up --build -d    # postgres + backend + worker
npm run dev:frontend             # Vite dev server (separate terminal)

またはバックエンドをホットリロード付きでローカル実行:

docker compose up -d postgres    # just the database
npm run build:packages           # build internal packages
source .env && npm run dev:backend   # Hono with tsx watch on :3101
npm run dev:frontend             # Vite on :5273

データベースマイグレーション:

cd packages/db
npx drizzle-kit generate         # generate migration from schema changes
# migrations auto-apply at backend startup

テスト

npx vitest run                    # all tests (.env auto-loaded by vitest config)
npx vitest watch                  # watch mode
npm run test:ci                   # clean reproduction of CI (fresh DB on :5534, no Gemini)

統合テストは実行中の Docker バックエンドにアクセスするため、docker compose up -d を起動したままにしてください。

統合テストはライブデータベースにテストデータを作成します（@test.local メールアドレスのユーザー、専用のレシピブック内）。テストトレースはレシピブックにスコープされ、個人の検索結果には表示されません。蓄積されたテストデータをクリーンアップするには:

npx tsx scripts/cleanup-test-data.ts           # clean up
npx tsx scripts/cleanup-test-data.ts --status  # just show counts

カバレッジの期待値とテストカテゴリについては、docs/testing-plan.md を参照してください。

公開版とホスト版

これはオープンソースのコードベースです。ホスト版のデプロイ固有の詳細（Terraform、運用ランブック、AWS トポロジ）は、単一の運用者のインフラ選択に固有であり、一般的に有用ではないため、別のプライベートなコンパニオンリポジトリにあります。

このリポジトリに何が属するかの判断基準: 自社インフラでこのスタックを自己ホストする人がこのコンテンツを必要とするか？ はいなら、ここにあります。特定のホストデプロイに固有なら、ここにはありません。

アプリケーションはデプロイ環境に依存しません — 必要なのは Postgres 17 と pgvector、および .env.example の環境変数だけです。コンテナプラットフォームにも依存しません。ローカルでは Docker Compose、本番ではそれ以外（Kubernetes、ECS、Fly、Hetzner）です。

主要ルール

• ルートハンドラや React コンポーネントにビジネスロジックを置かない — サービスを使用する

• データベースを直接編集しない — 常に Drizzle マイグレーションを使用する

• 型のみのインポートには import type { ... } を使用する。any ではなく unknown を使用する

• docs/engineering-principles.md を参照

このプロジェクトの背後にいる人間

Soup.net の多く（コード、ドキュメント、この README の一部）は AI エージェントによって書かれています。そのすべては、1人の検証可能な人間によって指示・レビュー・責任を負っています: Andy Forest、30年の経験を持つシステムアーキテクト兼開発者です。最近の活動: Scratch Foundation の AI プラットフォームアーキテクト。10年にわたり Steamlabs（85万人以上の若い学習者に実践的な AI 教育を提供したカナダの非営利団体）を運営。Make: AI Robots（O'Reilly、日本語訳あり）の共著者。LiteLLM コントリビューター。

Soup.net が存在するのは、彼が多くのエージェントを実行しており、自分の判断をエージェント間で存続させたかったからです。この README が説明する説明責任モデル（エージェントが作業を行い、人間がそれに責任を負う）は、このリポジトリ自体が構築されているモデルです。

ライセンスと商標

このリポジトリのコードとドキュメントは MIT License の下でライセンスされています。

Soup.net の名称、ロゴ、ワードマーク、ブランドイラスト資産は、soup.net のホストサービスを識別するものであり、MIT 許諾の対象外です。コードをフォークし、自己ホストし、自由に構築してください — ただし、公開インスタンスは独自の名称とブランディングで提供してください。