HutchDB

HutchDB

AI エージェントのためのデータベースです。スキーマ、SQL、構造は不要です。
Claude Code、Codex、Cursor、Hermes、Claw、Grokbot、その他の MCP クライアントが共同で読み書きできる、構造化されたワークスペースです。オープンソースです。

HutchDB とは？

HutchDB Core は、実行するすべてのエージェントに同じ永続的で構造化されたデータを提供する、ヘッドレスのシングルユーザー向け MCP サーバーです。Claude Code、Codex、Cursor、VS Code、またはその他の MCP クライアントを接続すると、セッションをまたいで共有コレクション内のレコードを保存、検索、更新できます。

コレクションでは、スキーマを必須としない Postgres JSONB による全文検索、任意のバリデーション、ビュー定義を利用できます。ダッシュボードも、ログイン画面も、OAuth の手続きもありません。あるのは、MCP エンドポイントと、ご自身で管理する Postgres データベースだけです。

このリポジトリは OSS エンジンです。人とエージェントが同じビジュアルワークスペースを使って作業できるようにしたい場合は、HutchDB Cloud を利用すると、ウェブビュー、公開ページ、ソーシャルログイン、組織内共有が追加されます。以下のCore と Cloud の比較をご覧ください。

どのような用途に使えますか？

エージェントの作業データの保存先として一般的なのは、Markdown ファイルです。TODO.md、メモ用ディレクトリ、文章が詰まったメモリファイルなどです。エージェントが自分用にメモを取るだけなら問題ありません。しかし、絞り込み（「重要度が 2 を超える未解決のバグを開く」）、集計（「ステージ別のパイプラインの価値」）、あるいは 2 つのエージェントが互いの変更を上書きせずに同じリストを更新するといったことを望んだ瞬間に、うまくいかなくなります。

HutchDB では、同じ情報を実際のレコードとして保持します。個別にアドレス指定でき、クエリ可能で、複数のエージェントが同時に安全に読み取り、更新できます。そのため、チャット 1 回分を超えて残しておく必要がある構造化データをエージェントが生成または利用する、あらゆる場面に適しています。よく使われるパターンをいくつか紹介します。

蓄積されるリサーチ。 顧客インタビュー、競合分析、スクレイピングした掲載情報、文献レビューなどです。セッションごとにコレクションへレコードを追加すれば、後のセッションでその全体をクエリできます。

「競合他社 5 社の価格ページを competitor-pricing に保存して、先月から変更があった企業を教えてください。」

通常ならスプレッドシートで管理するトラッカー。 バグ報告、コンテンツカレンダー、求人への応募、在庫、読書リストなどです。スプレッドシートとの違いは、エージェントがタスクの途中でレコードをクエリして更新できることです。

「このバグを重要度 high で bug-reports に記録して、まだ未解決のものをすべて一覧にしてください。」

エージェント間で引き継ぐパイプライン。 あるエージェントがレコードを収集し、別のエージェントが処理し、さらに別のエージェントが結果を報告します。各レコードのステータスフィールドでパイプライン内の位置を示すため、ツール間で何かをコピーする必要はありません。

「ステータスが new の leads レコードをすべて取得し、それぞれの情報を補完して、ステータスを ready-for-outreach に設定してください。」

長期プロジェクトの作業状態。 決定事項、未解決の質問、バックログ項目は、コンテキストウィンドウが閉じた後もクエリ可能な状態で残ります。新しいセッションでは、改めて説明を受ける代わりに、これまでの経緯を尋ねることから始められます。

「先週、価格ページについて何を決めましたか？まだ解決していないことは何ですか？」

繰り返し使えるプレイブック。 定期的な作業（週次レポート、リリースチェックリスト、コンテンツ制作）の手順、入力、現在のステータスを保存しておけば、どのエージェントでも作業を引き継いで実行できます。

「週次指標のプレイブックを実行して、結果を weekly-reports に保存してください。」

これらの用途では、事前にスキーマを設計する必要はありません。コレクションは最初の書き込み時に自動作成され、レコードには任意の JSON を使用できます。「これを HutchDB に保存して」と頼むところから始めれば、接続されているどのエージェントからでも同じレコードをクエリできます。

クイックスタート

注：詳しいドキュメントは hutchdb.com にあります。

1. クローンして起動する（Docker）：

   git clone https://github.com/ExpeditedProjects/hutchdb
   cd hutchdb
   docker compose up
   

   Core がデータベースをマイグレーションし、ポート 3000 で起動します。シングルトンユーザーと個人用組織は、最初のリクエスト時に遅延挿入されます。シード手順はありません。

2. アクセスを制限する（任意ですが、localhost 以外では推奨）— 起動前に API キーを設定すると、すべての MCP 呼び出しでベアラートークンが必須になります。

   export HUTCH_API_KEY="$(openssl rand -hex 32)"
   

   設定しない場合、すべてのリクエストが信頼されます。localhost では問題ありませんが、公開ホストでは適切ではありません。

3. エージェントを接続する。 Claude Code の場合は、MCP 設定に以下を追加します。

   {
     "mcpServers": {
       "hutch": {
         "type": "http",
         "url": "http://localhost:3000/api/mcp",
         "headers": {
           "Authorization": "Bearer YOUR_HUTCH_API_KEY"
         }
       }
     }
   }
   

   Cursor、Codex、VS Code でも同じ HTTP MCP サーバー形式が使えます。url とベアラーヘッダーも同じです。

4. 使ってみる。 コレクションは最初の書き込み時に自動作成されるため、セットアップは不要です。エージェントに話しかけるだけです。

   「このローンチタスクを HutchDB に保存してください。」 「先週、価格リサーチについて何を保存しましたか？」 「bug-reports コレクションをクエリして、タイムアウトに関する記録を探してください。」

5. エンドポイントを確認する（任意）：

   curl -X POST http://localhost:3000/api/mcp \
     -H "Authorization: Bearer $HUTCH_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
   

   hutch_* ツールの一覧（コレクション、レコード、スキーマ、ビュー）が表示されます。

git clone https://github.com/ExpeditedProjects/hutchdb
cd hutchdb
npm install
cp .env.local.example .env.local
# Required: HUTCH_DATABASE_URL
# Optional: HUTCH_API_KEY
npm run db:migrate
npm run dev

Claude Code をローカルの Core インスタンスに接続した場合の一般的なセッションです。

You:    Save each of these customer interviews as a record — tag the ones
        that mention pricing.

Agent:  Stored 9 records in `customer-interviews`, 4 tagged "pricing".

You:    (a week later) Which interviewees complained about onboarding?

Agent:  Querying `customer-interviews`... 3 records match: Dana R.,
        Marcus T., and the anonymous Feb 12 call.

レコードは Postgres JSONB 内の任意の JSON です。包含フィルター、Mongo 形式の演算子（$gt、$in、$exists、$contains、…）、全文検索でクエリできます。構造を強制したい場合は、任意でスキーマを設定できます。データを移動する必要がある場合、コレクションは CSV または JSON としてエクスポートおよびインポートできます。

HutchDB Core と HutchDB Cloud の比較

Core は意図的に小さく設計されています。製品レイヤーを利用したい場合は、HutchDB Cloud を実行するか、Core をフォークして独自のものを構築してください。

claude.ai には OAuth が必要です。 Core には OAuth 認可サーバーが含まれていないため、Core インスタンスを claude.ai（Web）に追加しても、そのままでは動作しません。Claude Code、Cursor、Codex、VS Code はすべて静的ベアラートークンを受け付けるため、問題なく動作します。

アーキテクチャ

• Next.js App Router — 静的なランディングページが 1 つ、MCP ルート（/api/mcp）が 1 つ、REST シードルート（/api/v1/collections）が 1 つあります。それ以外はすべて削除されています。
• Drizzle + Postgres — 各コレクションは JSONB ドキュメントを格納する独自のテーブルです。よく使われるフィールドは自動的にインデックス付き列になり、それ以外のすべては包含演算子と全文検索を使ってクエリされます。コレクションごとのストレージに対応する前のデータベースをアップグレードする場合は、db:migrate の後に npm run storage:cutover を 1 回実行してください。
• MCP サーバー — コレクションツール（コレクションごとの統計を含む）、レコードツール（保存／クエリ／検索／更新／削除／ステータス／変換に加え、CSV／JSON のエクスポートとインポート）、スキーマツール（記述／推論／更新）、ビュー ツールを備えています。クエリはフィルター演算子（$gt／$gte／$lt／$lte／$ne／$in／$nin／$exists／$contains）、フィールドのプロジェクション、件数／最小値／最大値／個別値／合計／平均の集計に対応しています。
• 認証の接続点（src/lib/auth/seam.ts）— 認証処理はここだけにあります。HUTCH_API_KEY が設定されている場合はベアラーキーを確認し、それ以外の場合はシングルトンコンテキストを使用します。
• シングルトンのブートストラップ（src/lib/auth/singleton.ts）— 初回リクエスト時に遅延作成される、1 人のユーザーと 1 つの個人用組織です。

コントリビュート

• バグを見つけましたか？ 再現手順を添えてイシューを作成してください。
• Core の改善に協力したいですか？ PR を歓迎します。コントリビューターには、メンテナーが HutchDB Cloud にデュアルライセンスを適用できるよう、CLA への署名をお願いしています。CONTRIBUTING.md と CLA.md をご覧ください。
• フィードバックやアイデアがありますか？ まずはイシューでお知らせください。どのようなものを構築しているか、ぜひ教えてください。

npm test          # vitest
npm run smoke     # end-to-end smoke test against a running instance:
                  #   SMOKE_BASE_URL=http://localhost:3000 npm run smoke
                  #   (keyed mode: add SMOKE_API_KEY=...)

ライセンス

AGPL v3。