Builderforce Memory

@seanhogg/builderforce-memory-mcp

@seanhogg/builderforce-memory をあらゆる MCP クライアントに公開します。プラグイン可能な MemoryBackend を使う、トークン節約に特化した単一のツールコアに、3 種類のトランスポートを備えています。

トランスポート	ファクトリー	使用方法	適した用途
インプロセス（Claude Agent SDK）	createMemoryMcpServer(backend)	返される type:"sdk" オブジェクト	利用側の製品が TS で、@anthropic-ai/claude-agent-sdk をインプロセスで実行する場合 — 最低レイテンシー
stdio	runStdio(backend) / npx @seanhogg/builderforce-memory-mcp	{ type:"stdio", command, args }	あらゆる言語／別プロセスの場合。SSM と IndexedDB の依存関係を利用側から切り離せます
HTTP（Streamable）	createMemoryHttpHandler(backend, { authToken })	{ type:"http", url, headers }	マルチテナント／ネットワーク経由（builderforce.ai のホスティング、リモートエージェント）

技術レポートとピアレビュー。 このトランスポートは、Evermind 技術レポートの敵対的な PEER-REVIEW.md でレビューされています。HTTP ハンドラーを公開する前にご注意ください。authToken のチェックは定時間ではない文字列比較（タイミングチャネル）であり、ハンドラーはテナントごとの分離なしに単一の backend を共有しています。そのため、1 つのトークンで全テナントのファクトを読み取れます。上記の「マルチテナント」という注記にかかわらず、実際の分離（トークンから名前空間へのマッピング、定時間比較、レート制限）はまだ実装されていません。Builderforce.ai 統合ギャップ登録簿では EVM-3 として追跡されています。v2026.6.34 で解決済み： HTTP ハンドラーは定時間のトークン比較とテナントごとの名前空間分離を使用するようになりました（PEER-REVIEW.md の解決追補をご覧ください）。

これでトークンを節約できる理由

外部メモリストアを使う目的は、メモリファイル全体をすべてのプロンプトに固定するのではなく、必要に応じて取得することです。効果を得るには想起を選択的にする必要があるため、tools.ts で上限をサーバー側に適用しています。

• memory_recall は順位付けされた上位 K 件（デフォルト 5 件、ハード上限あり）を返し、ストア全体は返しません。
• 各エントリーの内容は、コンテキストに入る前に切り詰められます（デフォルト 500 文字）。
• 「すべて返す」ツールはありません。すべてをダンプする方が、インラインで含めるより高コストです。
• memory_compact は、ローカルの Evermind がすでに吸収したファクトを、1 行のポインタースタブに縮約して、コンテキストを埋め尽くさないようにします。情報は失われません。まず想起プローブに合格する必要があり、元の内容はアーカイブされます（想起すれば引き続き取得できます）。詳細は以下をご覧ください。これはライブストアに直接書き込むため、メモリとディスク上のスナップショットの整合性が保たれます。
• 想起ではハイブリッド融合（BM25 ⊕ オプションの CPU SSM 埋め込み、RRF、MMR）で順位付けした後、重要度（×(0.5+importance)）と 90 日半減期の新しさの減衰で重み付けします。createLocalMemoryStoreBackend({ ranking: false }) を指定すると、これらのシグナルが無効になります。

最近の Claude モデルはツールをより慎重に選ぶため、ツールの説明は「…の場合、回答する前にこれを呼び出す」と具体的に指示しています。説明内のトリガー条件が、ツールを呼び出すべきかどうかの割合を左右します。これにプロンプトキャッシュ（キャッシュ済みプレフィックスを維持できるよう、テナント間でツールセットを同一にする）とコンテキスト編集（古くなった想起ファクトを削除する）を組み合わせると、最大限の効果が得られます。

接続部分

すべて MemoryBackend を使って実装されています。

interface MemoryBackend {
  recall(query: string, topK: number): Promise<RecallHit[]>;  // semantic
  get(key: string): Promise<RecallHit | undefined>;           // exact
  recallByTag(tag: string, limit: number): Promise<RecallHit[]>;
  remember?(input: RememberInput): Promise<void>;             // optional → read-only backends omit
  forget?(key: string): Promise<void>;
}

ローカルの MemoryStoreBackend（@seanhogg/builderforce-memory 経由の IndexedDB）を今すぐリリースし、後からネットワーク対応の builderforce.ai アダプターをツールやトランスポートを一切変更せずに追加できます。

クイックスタート — Claude Agent SDK でのインプロセス利用

import { query } from "@anthropic-ai/claude-agent-sdk";
import { createMemoryMcpServer, createLocalMemoryStoreBackend } from "@seanhogg/builderforce-memory-mcp";

const backend = await createLocalMemoryStoreBackend();          // IndexedDB (fake-indexeddb in Node)
const memory  = await createMemoryMcpServer(backend);           // type:"sdk" config

for await (const msg of query({
  prompt: "What language does this user prefer? Check memory first.",
  options: {
    mcpServers: { builderforce_memory: memory },
    allowedTools: ["mcp__builderforce_memory__*"],             // auto-approve, no prompts
  },
})) {
  if (msg.type === "result" && msg.subtype === "success") console.log(msg.result);
}

スナップショットは共有されます — サーバーが監視します

persistFile を設定すると、ストアはメモリ上に保持され、プロセスの起動期間をまたいで JSON スナップショットが正本になります。他のプロセスもこのファイルを編集するため（BuilderForce VS Code 拡張機能は、取り込んだエントリをその場でスタブに書き換えます）、バックエンドは各操作の前にファイルの状態を確認し、変更されていればディスクから再読み込みします。これを行わないと、編集前の本文を保持したこのサーバーが、次回の書き込み時にその変更を上書きしてしまいます。サーバー自身の書き込みは、反映された時点でスタンプ（mtime + サイズ + コンテンツハッシュ）が付与されるため、定常状態でのコストは stat 1 回だけで、書き込みループも発生しません。

SSM 埋め込みによる想起 — GPU のないヘッドレスホストでも利用可能

モデルを設定していない場合、ローカルバックエンドは字句的に（BM25）想起の順位を付けます。Evermind チェックポイントを指定すると、SSM 埋め込みのコサイン類似度による順位付けが字句的な順位付けと統合されます（Reciprocal Rank Fusion — 密 ⊕ 疎。識別子やエラーコードなどの完全一致も引き続き検出できます）。すべての memory_recall 結果には使用したランカーが記載されるため、字句的な方式へのフォールバックが見過ごされることはありません。

Ranked by: semantic recall (SSM embedding fused with lexical).
Ranked by: lexical recall (fallback - no embedding model loaded).

stdio/HTTP サーバーの実行に GPU は不要です。 EvermindLM は純粋な CPU モデルです。EvermindLM.embed() は、GPU 版の HybridMambaModel.embed() と同じ隠れ状態を平均プーリングして L2 正規化し、同じ仕様で返します。次のように設定してください。

環境変数	意味
BUILDERFORCE_MEMORY_MODEL	evermind-lm を格納した .evermind パッケージへのパス。
BUILDERFORCE_MEMORY_TOKENIZER	そのチェックポイントのトークナイザー JSON。デフォルトは <model>.tokenizer.json です。
BUILDERFORCE_MEMORY_VECTORS	ベクトルキャッシュのパス。デフォルトではメモリスナップショットと同じ場所に保存されます。

ベクトルはプロセスの起動期間をまたいでキャッシュされます（モデルのフィンガープリントが記録されるため、適応済みのチェックポイントではキャッシュが無効になります）。これは、セッションごとに起動するサブプロセスが最初の想起時にストア全体を再埋め込みする場合、そのコストが置き換えられる字句的な順位付けよりも大きくなるためです。

プロセス内でホストする場合は、埋め込み関数を直接渡してください。2 つ目のモデルを起動するのではなく、すでに読み込まれている GPU 版 Evermind ランタイムを再利用します。

const backend = await createLocalMemoryStoreBackend({ runtime: ssmMemoryService.runtime });

いずれの場合も、モデルが適応または蒸留されるにつれて、想起の品質は自動的に向上します。

Experience — Evermind が実行してきたこと（オプトイン）

事実は学習した項目の一種であり、経験は別の一種です。エピソードは記録されたデモ（プログラムと、その中で人が実行した UI 操作手順）、スキルは Train Once がそこからコンパイルするもの（型付きの値はパラメーターになり、シークレットは保存されず、取り消しできないクリックには承認が必要です）、実行は監査証跡を伴う 1 回の実行です。このドメインは @seanhogg/builderforce-memory-engine にあり、このサーバーはそのデータを永続化して公開します。

ツールを登録するには BUILDERFORCE_MEMORY_EXPERIENCE=1 を設定します（Synapse は設定します）。デフォルトでは無効なので、通常のコーディングエージェントのインストールでは、ツールリストに含まれません。

ツール
experience_info	スナップショットファイル、スクリーンショットフォルダー、モデルパス、件数。
experience_forget_all	すべてのエピソード、スクリーンショット、スキル、実行を削除します（confirm: true）。メモリとモデルには影響しません。
episode_save / _list / _get / _forget	デモ。スクリーンショットは episodes/<id>/ に保存され、エピソードとともに削除されます。
skill_preview / _compile / _list / _get / _forget / _schedule、skills_due	Train Once とルーティン。
run_start / _step / _finish / _list / _get	実行とその監査証跡（最新の 500 件を保持）。
experience_train	エンジンの唯一の適応レシピを使い、まだ学習していないすべての手順を対象に、プライベートモデル（BUILDERFORCE_MEMORY_MODEL）を適応させます。以前のモデルは <model>.prev として保持されます。オプトインの curate: true を指定すると、実行の大半が失敗している手順と類似した手順（互いに類似するもの、または直近で学習した 200 件に類似するもの）を先に除外し、除外した手順をそれぞれ一覧表示します。除外された手順は次回に再検討されます。

メモリのスナップショットと同じ場所に experience.json（memory.json とまったく同じようにプロセス間で共有）と episodes/ として保存されます。HTTP ハンドラーのトークンで選択されたテナントには、決して提供されません。

Claude 以外の MCP ホストにもワンショットでインストール

# Auto-detect installed agents and register the memory server into each:
npx -y -p @seanhogg/builderforce-memory-mcp builderforce-memory-install

npx -y -p @seanhogg/builderforce-memory-mcp builderforce-memory-install --host=all
npx -y -p @seanhogg/builderforce-memory-mcp builderforce-memory-install --host=cursor,windsurf

各ホスト固有の設定に stdio サーバーのエントリーを書き込みます。べき等で、.bak バックアップも作成します。対応ホスト：Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、Cline、Gemini CLI、Codex CLI。すべてのエージェントは 1 つの共有ストアを参照します（resolveMemoryFile()：~/.builderforce-memory/memory.json、またはライブストアがそこにある場合は従来の ~/.claude/builderforce-memory/memory.json。--memory-file / BUILDERFORCE_MEMORY_FILE で上書きできます。フックスクリプトも同じ方法で解決します）。そのため、あるエージェントで記憶した事実を別のエージェントでも呼び出せます。--readonly を指定すると書き込みツールが除外されます。--local=<dist/bin/stdio.js> を指定すると、開発用にチェックアウトしたものを実行します。

同じ起動仕様をプログラムから利用することもできます： buildServerSpec() / installMemoryServer()（src/install/ を参照）。

Claude Code：「自動運転メモリコンボ」

サーバーを登録すると、Claude Code でメモリのツールが使えるようになります。Claude Code では、インストーラーがさらにフックも設定するため、メモリがアドバイス型ではなく自動運転型になります（--no-hooks でスキップできます）。

フック	動作
SessionStart	永続メモリの上位項目をまとめたダイジェストを挿入します。
PreCompact	ウィンドウが要約される前に、永続的な学びをフラッシュします。
UserPromptSubmit	コンテキストに応じた想起 — プロンプトに照らしてメモリを評価し、関連する項目を挿入します。そのため、保存された事実はセッション開始時だけでなく、判断の時点で取得されます。
Stop	自律的な記録 — ユーザーの最後のメッセージが永続的な指示または訂正であり、このターンで統合されていない場合、memory_remember を実行するよう指示して停止を BLOCK します。記録は MCP の書き込み経路を通るため、スナップショットとの競合は発生しません。stop_hook_active ガードにより、1 ターンにつき促しは最大 1 回です。

4 つのフックはすべて、生成された依存関係のない 1 つのフックスクリプト（~/.claude/builderforce-memory/bfmem-hook.mjs、4 つのモード）と、付属のスキルを参照します。べき等で、.bak による安全なバックアップにも対応しています。信頼できるソース：src/install/claude-hooks.ts（installClaudeCombo / bfmemHookSource）。

クイックスタート — stdio（任意のプロセス／言語）

npx -y @seanhogg/builderforce-memory-mcp        # serves the local MemoryStore over stdio

mcpServers: {
  builderforce_memory: { type: "stdio", command: "npx", args: ["-y", "@seanhogg/builderforce-memory-mcp"] },
}

環境変数：BUILDERFORCE_MEMORY_DB（データベース名）、BUILDERFORCE_MEMORY_READONLY=1（書き込みツールを無効化）。

クイックスタート — HTTP（マルチテナント）

BUILDERFORCE_MEMORY_TOKEN=secret PORT=8787 npx @seanhogg/builderforce-memory-mcp-http

mcpServers: {
  builderforce_memory: {
    type: "http",
    url: "http://localhost:8787",
    headers: { Authorization: "Bearer secret" },
  },
}

または、任意のバックエンド（将来のリモートバックエンドを含む）に対して、ご自身の Node/Express サーバーで createMemoryHttpHandler(backend, { authToken }) をマウントしてください。

カスタム／リモートバックエンド

MemoryBackend を実装し、任意のトランスポートに渡します。

import { createMemoryMcpServer, type MemoryBackend } from "@seanhogg/builderforce-memory-mcp";

const remote: MemoryBackend = {
  recall:      (q, k)   => bfClient.search(q, k),
  get:         (key)    => bfClient.get(key),
  recallByTag: (t, lim) => bfClient.byTag(t, lim),
  remember:    (input)  => bfClient.put(input),
  forget:      (key)    => bfClient.delete(key),
};
const server = await createMemoryMcpServer(remote);

圧縮ルール（@seanhogg/builderforce-memory-mcp/compaction）

memory_compact が書き込むスタブ形式（[absorbed→Evermind vN] <first line>）は、依存関係のないサブパスとして公開されています。外部の圧縮ツールはこのサブパスからルールをインポートするため、スタブはサーバーのものとバイト単位で同一になり、互いに再度スタブ化することもありません。

ロスレス契約（すべての圧縮ツールが順番に実行する必要がある処理）：

1. planLosslessCompaction(candidates, { probe, version }) — 構造上のルール（planCompaction：スタブをスキップし、エントリーを拡大しない）に加えて、想起プローブを実行します。probeQuestionFor(key, content) は事実を最も特定しやすいトークンを空欄にし、ローカルの Evermind はそのトークンを提示する必要があります（probePasses）。プローブがない場合、または回答が誤っている場合、その事実は圧縮されません（no_probe／probe_failed）。
2. 各書き込みの archive 行をすべてアーカイブします（mergeArchive を defaultArchiveFile(memoryFile) → memory.archive.json に適用）。スタブを書き込む前に、確実に永続化してください。アーカイブはスナップショットの外部にあり、マージのみ行われて削除されないため、スナップショットの書き換え、forget、10,000 エントリー上限を経ても保持されます。
3. スタブを書き込みます。

読み取り時は、スタブがアーカイブされた元の内容に解決されます（RecallHit.content = 全文、RecallHit.stub = 保存されたスタブ）。アーカイブのないスタブは contentLost となり、ツールと Claude Code のフックは CONTENT_LOST_LABEL — 「（内容が失われています — 信頼する前に再確認してください）」 — と表示し、フックはその重要度を下げます。memory_restore（stdio バイナリでは file、それ以外ではインラインの json）は、[{key, content}] または Evermind コーディネーターの [{id, text}] 形式の mem: ダンプからテキストを復元します。キーで照合し（id からは mem: プレフィックスが除かれます）、一致しない場合はスタブのポインターに対して先頭行を照合します。テキストはスタブの隣にアーカイブされるため、トークンの節約は維持されます。

共有ストアファイル（SharedJsonFile：スナップショット、アーカイブ、experience.json）を上書きする際は毎回、以前のバージョンを <file>.bak.1 ～ <file>.bak.3 にローテーションして保存します。

依存関係

@modelcontextprotocol/sdk と zod は必須の依存関係です。@anthropic-ai/claude-agent-sdk （SDK トランスポート）、@seanhogg/builderforce-memory と fake-indexeddb（ローカルバックエンド）は オプションのピア依存関係で、間接的にインポートされます。必要なトランスポート／バックエンドに 応じてインストールしてください。