Brain Memory

brain-connector

Brain Memory Claude コネクター — brain のスコア付きリコールを Claude（ウェブ／デスクトップ／iOS／Cowork）に公開するリモート MCP サーバーです。Anthropic の build-mcp-server ガイダンスに従い、公式の @modelcontextprotocol/sdk を使用して構築されています。設計の根拠は brain-cloud/docs/connector-architecture.md にあります。

このリポジトリに配置されています（npm パッケージには含まれません。website/ と同様に package.json の files から除外されています）。そのため、../src の実際のリコールエンジンを直接再利用できます。脳はひとつ、エンジンはひとつ、インターフェースはふたつです。

ステータス：🟢 本番環境で稼働中 — フェーズ 1 + 2（読み取り + 書き込み）

https://mcp.brainmemory.ai/mcp でデプロイ済みです（brain-cloud の隣にある VPS 上の Node サービス。systemd + nginx + certbot — deploy/ を参照）。claude.ai に追加し、Claude ウェブ + iPhone で動作を確認済みです。ツール：brain_recall、brain_status（読み取り）+ brain_memorize、brain_pin、brain_unpin、brain_forget、brain_verify（書き込み — 書き込み内容は brain-cloud に同期され、ホスト側で確認を求めます）+ brain_use（アカウントの脳を切り替えます）。

本番環境で知っておくべきことが 2 つあります。

• 脳 ↔ Google アカウントは 1 対 1 — コネクターはサインインした Firebase（Google） ID の脳を提供するため、脳はその brain-cloud アカウントにプッシュしておく必要があります。空のアカウント、複数の脳があるアカウント、または誤ったアカウントが、架空の脳として黙って提供されるのではなく、コネクターに表示される仕組みについては、以下のID とアカウントを参照してください。
• セッションは約 1 か月間、サイレントに更新されます — アクセストークンの有効期間は 1 時間ですが、トークンエンドポイントがスライド式の 30 日間の有効期間（CONNECTOR_REFRESH_TTL_MS）を持つローテーション式リフレッシュトークン（OAuth 2.1：1 回限りの使用で、再利用時にはトークンファミリー全体が失効）を発行するため、アクティブなユーザーにログインページが表示されることはありません。各リフレッシュ時には、ログイン時に取得したリフレッシュトークンを使って、サーバー側で Firebase 認証情報も更新されます（securetoken API）。そのため、同期の戻しと TTL による再取得は、従来の約 1 時間の Firebase ID トークンの有効期間を超えても機能し続けます。許可情報と DCR クライアントレジストリは CONNECTOR_STATE_DIR（systemd の StateDirectory）に保存されます。Firebase リフレッシュトークンは CONNECTOR_STATE_KEY を使って保存時に暗号化され、当社のトークンはハッシュ化して保存されるため、デプロイや再起動でユーザーがログアウトすることはなくなりました。ローカル CLI のメモリ（brain cloud push）は、TTL による再取得（CONNECTOR_REPULL_TTL_MS、デフォルトは 120 秒）でアクティブなセッションに自動的に反映されます。クラウドのチェックサムが変わった場合にのみ再取得され、同期されていないローカルの書き込み中には再取得されません。

npm test は型チェックを行い、1 つのサーバー内で一連の処理をエンドツーエンドで検証します。OAuth 2.1 のハンドシェイク全体から、実際のスコア付きリコールまでを確認します（実際のクライアントに合わせ、トークンリクエストは form-urlencoded です）。

① unauthenticated MCP call → 401 + WWW-Authenticate (RFC 9728)
② discovery → AS metadata (RFC 8414), PKCE S256
③ Dynamic Client Registration (RFC 7591)
④ authorize → code (iss + state validated, RFC 9207)
⑤ token → audience-bound Bearer (PKCE verified, RFC 8707)
⑥ MCP initialize + tools/list → [brain_recall, brain_status, brain_use, brain_memorize, brain_pin, brain_unpin, brain_forget, brain_verify]  (official SDK)
⑦ brain_recall(query) → the brain's REAL scored results (relevance + decayed
   strength + spreading activation), identical to the CLI

リコールを CLI と同一に保つ仕組み

エンジンブリッジ（src/engine.ts）は、認証されたユーザーの脳の作業コピーを BRAIN_DIR に指定して、リポジトリの bin/recall.js を実行します。そのため、コネクターのスコアリングは CLI とバイト単位で一致し、再実装は一切ありません。（BRAIN_DIR は CLI にも備わっている同じオーバーライドです。）

実行／テスト

npm install
npm test          # end-to-end Phase 1 proof
npm start         # serve MCP on http://localhost:8788

ツール

ツール	種類	説明
brain_recall	読み取り（readOnlyHint）	クエリに対するランキング付きの想起を、brain エンジンによるスコア順で返します。
brain_status	読み取り（readOnlyHint）	ユーザーの brain の記憶件数と最終更新日時、および使用中の brain に active のマークを付けたアカウント内の brain 一覧を返します。
brain_use	書き込み（idempotentHint）	名前または ID を指定して、コネクターが提供するアカウント内の brain を切り替えます。セッションをまたいで記憶され、brain 間でコピーは行われません。
brain_memorize	書き込み（destructiveHint）	指定された明示的な内容を保存します（会話は保存しません）。すぐに想起できます。
brain_pin / brain_unpin	書き込み（destructiveHint、idempotentHint）	記憶を常時表示される階層に移動、またはそこから移動します。
brain_forget	書き込み（destructiveHint）	記憶をアーカイブします（復元可能です。完全削除ではなく _archived/ に移動します）。
brain_verify	書き込み（destructiveHint）	検証待ちの記憶を一覧表示し、承認するか、アーカイブに移動して却下します。

書き込みでは決定論的な CLI（memorize.js / pin.js / unpin.js / forget.js）を再利用し、その後 syncBack() で brain-cloud に同期します。

ID とアカウント

1 つの brain ↔ 1 つの Google アカウントです。 コネクターは、どのノート PC を使っているかを認識しません。サインインを完了した Firebase（Google）ID に属する brain を提供します。検証済みの uid は決定論的に brain ユーザー（resolveBrainUserId）に対応付けられ、そのユーザーの正規の brain が brain-cloud から取得されます。これは、ユーザーが brain_use で選択した brain、または選択がない場合はアカウント内で最も古い brain です。つまり、ルールは簡単です。CLI の brain cloud が同期するものと同じ Google アカウントで接続し、同じ brain を使ってください（brain cloud brains で CLI がどの brain にリンクされているか確認できます）。

このルールに気付かないまま違反することがないよう、ensureUserBrain は identity シグナルを返し、ツールを通じて表示します。

状況	identity.status	表示される内容
アカウントに Brain Cloud の brain がない	no-cloud-brain	このアカウントには brain がないことを示すメモが表示されます（brain_status 内、および何も見つからなかった場合の brain_recall 内）。Google アカウントを間違えてサインインしたか、利用を始めたばかりの可能性が高いです。
アカウントに brain が1 つだけある	ok	何も表示されません。一般的で曖昧さのないケースです。
アカウントに brain が複数ある	multiple-brains	使用中の brain 名を示すメモが表示されます。brain_status にはすべての brain が一覧表示され、brain_use で切り替えられます。選択内容はユーザーごとに OAuth の状態とともに保持され、後続のセッションでも適用されます。選択した brain が後で削除された場合は、最も古い brain に切り替わります。

これはガイダンスであり、強制ではありません。まだ brain を持たない新規ユーザーでも、空の brain を利用できます。アカウントのリンク（1 つの Google ID で複数の brain を同時に使用できるようにすること）は意図的に先送りされています。一度に 1 つの brain を選ぶには brain_use を使います。

認証

現在は、どちらも実際に動作する 2 つのレイヤーがあります。

1. Claude とコネクター間の OAuth 2.1（src/oauth.ts）：authorize / token / register / metadata、PKCE S256、RFC 8707 の audience バインディング、RFC 9207 の iss に対応します。トークンは src/auth.ts のストアに発行され、/mcp のガードがトークン（audience を含む）を検証します。
2. 人間のユーザーの識別（src/firebase.ts）：/authorize はユーザーを Firebase ログイン（brain-cloud が使用するものと同じプロジェクト）にリダイレクトします。コネクターは ID トークンを サーバー側で、シークレットなしに検証します。Google の公開証明書で RS256 を検証し、aud／iss／ exp を確認するため、必要なのは公開プロジェクト設定だけで、サービスアカウントキーは不要です。検証済みの uid が brain ユーザーに対応付けられ、その後 OAuth コードが発行されます。

FIREBASE_* 環境変数が設定されていない場合、/authorize は固定の開発用ユーザー （STUB:FIREBASE）にフォールバックするため、ブラウザーを使わずにヘッドレステストを実行できます。

Firebase ログインの動作を見る（デモ）

cp .env.example .env      # fill in FIREBASE_API_KEY / AUTH_DOMAIN / PROJECT_ID
npm start                 # http://localhost:8788
# then connect an MCP client (e.g. Claude) to http://localhost:8788/mcp —
# the OAuth flow opens the branded Google sign-in page from /authorize

/authorize からサインインすると、ブランドに合わせた同意／ログインページが表示されます。サインインに成功すると、検証済みの firebase_uid → brain_user_id → brain_dir が解決されます。これによって、コネクターはどのユーザーの brain を提供するかを判断します。（localhost はデフォルトで Firebase の許可済みドメインなので、ローカルでもポップアップサインインが動作します。）

ユーザーごとのストア（src/store.ts）

ensureUserBrain({ userId, brainDir, idToken }) は、プラグイン可能なプロバイダーからユーザーの brain 作業コピーを準備し、その後エンジンがそのコピーを参照します。プロバイダーは CONNECTOR_STORE で指定するか、未指定の場合は推定されます。

• brain-cloud（本番環境）— ユーザーのFirebase ID トークン（brain-cloud のミドルウェアはこれを直接受け付けます）を使って、BRAIN_CLOUD_API_URL（デフォルトは https://api.brainmemory.ai）からユーザーの {brainID}.tar.gz を取得し、tar xzf で brainDir に展開します。ログインのたびに更新されます。
• local（開発環境）— brainDir → $DEV_LOCAL_BRAIN（稼働中の ~/.brain）へのシンボリックリンクを作成し、コネクターを通じて実際の brain を自分のマシンから提供します。
• none — 事前にプロビジョニング済みであることを前提とします（テスト用）。

常に適切に処理されます。brain がまだ見つからない場合は、空の、有効な（参照時に安全な）brain を初期化します。

brain-cloud プロバイダーはストア契約に準拠しているため、セルフホスト可能な brain-store を含め、この契約を実装するあらゆるストアで動作します。同期の戻しは条件付きです（If-Match）。別のデバイスが先にプッシュしていた場合、コネクターは作業コピーを破棄し、ストアの brain からやり直して、書き込みを再適用してから再度プッシュするため、誰かの記憶が上書きされることはありません。

ID プロバイダー（src/identity.ts）

誰がログインしているか、またコネクターがそのユーザーについてストアに提示する情報を、1 つのインターフェースの背後にまとめています。CONNECTOR_IDP で選択します。

• firebase（FIREBASE_* が設定されている場合のデフォルト）— Google サインインです。ストアの認証情報には Firebase ID トークンを使用し、Firebase の更新トークンから更新します。

• static — セルフホスト型ストア向けです。サインインページで、ストアの運用者が発行したトークン（brain-store user add）を入力します。ユーザーが誰であるかはストアが判断します。トークンが誤ってホスト型のデフォルトに送信されないよう、BRAIN_CLOUD_API_URL を明示的に設定する必要があります。ストアでユーザーのトークンをローテーションまたは削除すると、次回のサイレント更新時にそのユーザーのセッションが終了します。

• oidc — 組織の OpenID Connect 発行者（Entra、Google Workspace、Keycloak、Okta）を受け付けるセルフホスト型ストア向けです。/authorize はブラウザーを発行者にリダイレクトし（認可コード + PKCE + nonce）、発行者は /oidc/callback に戻します。ID トークンはストアの認証情報であり、発行者の更新トークンから更新されます。OIDC_ISSUER、OIDC_CLIENT_ID、および明示的な BRAIN_CLOUD_API_URL が必要です。トークンの検証はストア自身（store/lib/oidc.js）が行うため、有効なトークンの定義が両者で食い違うことはありません。発行者が停止すると 503 を返してログイン状態を維持し、失効するとログイン状態を終了します。

プロバイダーが設定されていない場合、本番環境ではコネクターの起動を拒否します。リバースプロキシがループバック上にない場合（たとえば別のコンテナーにある場合）は、CONNECTOR_TRUST_PROXY で名前を指定してください（例：uniquelocal）。true は拒否されます。

次のステップ

• アカウントのリンク — 1 人のユーザーが同時に複数の brain を利用できるようにし（それらすべてを横断して参照）、選択した brain を一度に 1 つだけ提供する方式から変更します。ID とアカウントを参照してください。
• ディレクトリへの提出 — 残りの手動ステップ（テストアカウント、MCPB のパッケージ化、リリース告知）。brain-cloud/docs/connector-architecture.md の §7 にある提出チェックリストを参照してください。