Cuba Memroys

MemoryIndustry

旧名称は cuba-memorys です。同じデーモン、同じ cuba_* MCP ツールで、製品名が新しくなりました。

AI コーディングエージェントのための長期記憶です。 エージェントが検索し、推論し、修正内容を反映できるナレッジグラフを提供する MCP サーバーです。これにより、セッションをまたいでコードベースの内容を忘れなくなります。

Rust で記述され、PostgreSQL + pgvector を利用しています。MCP ツールは 31 個（CUBA_DOCS=1 の場合は 32 個）、CLI コマンドは 28 個です。以下の数値はすべて、v0.12 以降、実際に公称どおりの測定を行うようになったベンチマークで測定されています。（以前のベンチマークはそうではありませんでした。測定と、嘘をついていたベンチマークをご覧ください。）

インストール

pip install memory-industry        # or: npm install -g memory-industry
claude mcp add memory-industry -- memory-industry

# Previous names still install the same binary:
#   pip install cuba-memorys
#   npm install -g cuba-memorys

セットアップはこれだけです。初回起動時に Docker 経由で PostgreSQL 18 + pgvector コンテナを用意し、スキーマを初期化します。Docker を起動しておく必要があります。 cuba-memorys コマンドもバイナリエイリアスとして引き続き利用できます。

{
  "mcpServers": {
    "memory-industry": {
      "command": "memory-industry"
    }
  }
}

{
  "mcpServers": {
    "memory-industry": {
      "command": "memory-industry",
      "env": { "DATABASE_URL": "postgresql://user:pass@localhost:5432/brain" }
    }
  }
}

cuba-memorys serve                      # 127.0.0.1:8787 by default
cuba-memorys serve 127.0.0.1:9000       # or pick the address

{
  "mcpServers": {
    "memory-industry": {
      "type": "http",
      "url": "http://127.0.0.1:8787/mcp",
      "headers": { "Mcp-Client-Id": "editor-window-1" }
    }
  }
}

cuba-memorys models all          # embeddings + NLI + reranker + runtime
cuba-memorys models embed        # just the embeddings model (~113 MB)
cuba-memorys models all --gpu    # GPU runtime, if you have one
cuba-memorys doctor              # confirms what loaded

memory-industry cache migrate            # the plan: touches nothing
memory-industry cache migrate --apply    # moves it

GPU ランタイムの取得は、まだ半分にすぎません。バイナリ自体を --features cuda を指定してビルドする必要があります。そうしないと gpu::configure() がプロバイダーを登録せず、再ランキングは CPU で実行されます。これは仮定の話ではありません。6コアのノート PC で cargo run --release --example rerank_bench を実行して測定した、候補50件の再ランキングにかかる時間です。

どちらの場合もランキングは同じです。CPU と GPU は候補ごとに一致し、スコアの小数点以下5桁目だけが異なります。任意のマシンで rerank_bench を実行すると、再ランキングが予算内に収まるか、処理がひそかに破棄されているかを確認できます。また、cuba-memorys doctor では、このビルドに GPU プロバイダーがあるかどうかが表示されます。

このセクションには以前、「すべてのモデルがひそかに CPU で実行される」と記載されており、--features cuda を指定してビルドすれば3つすべてが GPU で実行されるかのような印象を与えていました。しかし、GPU で実行されるのは再ランキングだけでした。 埋め込みモデルは INT8 に動的量子化されており、96個の DynamicQuantizeLinear と144個の MatMulInteger を使います。CUDA プロバイダーはどちらにもカーネルを登録しないため、ビルド方法にかかわらず ONNX Runtime はこれらを CPU に割り当てます。このセッションに CUDA を登録しても効果はなく、モデルが一度も計算に使わない VRAM アリーナの分だけコストがかかっていました。全544 MBの重みがホスト RAM に置かれている間、374 MiB が確保されたままでした。 NLI クロスエンコーダーは逆の問題を抱えています。FP32 のまま固定されています。mDeBERTa は FP16 をサポートしないと上流で説明されており、INT8 ビルドでは確信度の高い誤った含意判定が返されるためです。

そこでモデルごとに配置を決定するようになり、GPU を要求するのは再ランキングのみになりました。測定に使った 6 GB の GPU カードでは、デーモンの VRAM 使用量は検索中に 5228 MiB から2950 MiBへ、アイドル時には0へと減りました。以下のメモリ使用量に記載されているオプトインの2つの手順を実行すると、1460 MiB まで減少します。

個別の環境変数（CUBA_DOCS、CUBA_RERANKER_PATH、…）は、常にプリセットより優先されます。

実際の動作

ほとんどのメモリサーバーは、埋め込み機能を後付けしたキー・バリューストアです。このサーバーは、心理学の文献で別々のものとして扱われ、減衰の仕方も異なるとされているため、4種類のメモリをモデル化します。

手続き記憶を、9番目の観察タイプではなく独立したテーブルにしているのには、特別な理由があります。ACT-R では、宣言的記憶（アクセスによって強化）と手続き記憶（成功によって強化）を分けています。観察として扱うと、失敗し続けるために頻繁に参照されるレシピほど重要度が上がってしまいます。評価にはウィルソン下限を用いるため、1/1 の成功は 0.21、47/50 は 0.84 となり、初回の幸運な成功が実績を上回ることはありません。

検索

3つのシグナル（全文検索、BM25（ts_rank_cd）、pgvector HNSW）を対象に、ハイブリッド RRF 融合（k=60、Cormack 2009）を行います。さらに、クエリのシャノンエントロピーが高まるにつれて、キーワード重視からセマンティック重視へと切り替わる、エントロピーに基づく重み付けを適用します。

回答はデフォルトで**compact形式**で返されます。キーを省略形にし、コンテンツは1200文字で切り詰めます。トークン数を30%削減し、nDCG はわずかに向上します — ID がスコア付けされた221件の質問で測定したところ、対応のある95%区間は[+0.0024, +0.0166]、改善幅は+0.0090でした。形式によって、順位付けされるドキュメントが変わることはありません。変わるのは、スコア付けされる前に、レスポンスのトークン予算内にいくつのドキュメントが収まるかです。デフォルトの5000トークン予算では、詳細形式は5286トークンを必要とするため末尾が切り捨てられますが、コンパクト形式は3723トークンで収まり、最後まで保持できます。ブランチごとのスコア内訳をすべて確認するには、"format": "verbose"を渡してください。

実際に検証する検証機能

cuba_faro mode=verify は、主張を保存されている情報と照合します。以前は、取得した証拠との コサイン類似度 で主張をスコア付けしていましたが、これはうまく機能しません。類似度が測るのはテキストの 話題 であって、何を主張しているか ではないからです。「cuba-memorys は Rust で書かれている」と「…Java で書かれている」は、ベクトル空間ではほぼ同じです。実際のコーパスで測定したところ、誤った主張のスコアは 0.61、正しい主張は 0.59 でした。

含意は類似度とは別の問いであり、読み取る ものが必要です。ローカルのクロスエンコーダーが各証拠を supports ／ contradicts ／ unrelated と判定するようになり、信頼度は各判定から導出されます。各判定には、その証拠の類似度に応じた重みが付けられます。同じコーパスでの結果は次のとおりです。

話題に沿っていることは、裏付けにはなりません。また、unrelated はどちらの側にも加算されません。

判定器は mDeBERTa-v3-base-xnli で、ONNX 上でローカル実行されます。100 言語に対応し、判定あたり約 50 ms で、API キーもネットワーク接続もコストも不要です。ここではこれが重要です。このコーパスの約 75% はスペイン語であり、最初に選ばれがちな英語専用の NLI モデルでは、4 件中 3 件のメモリを気付かれないまま正しく処理できません。cuba-memorys models nli でインストールしてください。読み込まれたかどうかは cuba-memorys doctor で確認できます。

このモデルがない場合、検証は LLM にフォールバックします（サンプリングを使う MCP クライアント独自のモデル、ローカルの claude CLI、または Anthropic API）。そのいずれも使えない場合は、判定を捏造するのではなく、正直に unknown を返します。

この機能が行わないことが 2 つあります。証拠が弱い場合に主張を確定することはありません。含意には 0.80 を超える必要がありますが、矛盾には 0.60 で十分です。誤った記憶を確定することと、正しい記憶を疑うことは、同じコストの誤りではないためです。また、判定できない場合には、最も大きな数値を返すのではなく、その旨を伝えます。3 クラスのヘッドで argmax を取ると、まったくの誤りである主張に対しても supports を平然と返してしまいます。実際にそうなっていました。

キャリブレーション済みの棄却

分布外ゲートは、コーパスでは回答できないクエリを拒否します。しきい値は根拠のない定数ではありません。Ledoit-Wolf 共分散縮小とコンフォーマル分位点を組み合わせ、cuba-memorys calibrate --dataset <questions.jsonl> --apply で独自のコーパスを使ってキャリブレーションし、結果を保存します（データセットは必須です。指定しないとコマンドは拒否されます）。（理論上の χ² しきい値では、回答可能なクエリが100% 拒否されました。 ここでは分布フリーのキャリブレーションは、あれば望ましいという程度のものではありません。）

git を介したマシン間の同期

CUBA_MODE=red を使うと、2 台のマシンで 1 つのデータベースを共有できます。互いに接続できないマシン向けには、もう 1 つの方法として cuba_sync があります。グラフをコミット可能な JSON として書き出し、もう一方のマシンで読み込みます。

cuba-memorys sync export            # write the bundle under .memory-industry/ (or $CUBA_SYNC_DIR)
cuba-memorys sync import            # read one back in
cuba-memorys sync diff              # entities on disk vs entities in the database
cuba-memorys sync status            # which bundles this machine has already imported
cuba-memorys hook install           # export after every commit, import after every checkout, merge and rebase

同じ 4 つの操作は cuba_sync action=export|import|diff|status です。バンドルは、各エンティティの観測情報を含む JSON ファイル 1 つずつに加え、episodes/YYYY-MM/、errors/、decisions/、relations.json、projects.json、tombstones.json、manifest.json で構成されます。対象はアクティブなプロジェクトと、プロジェクトに紐付いていないすべての情報です。ただし、--scope all を指定した場合はすべてが対象になります。埋め込みベクトルは指定しない限り含まれません（--with-embeddings）。埋め込みベクトルはバイト数の大部分を占め、再計算できるためです。バンドルは一度だけインポートされます。また、マニフェストのハッシュはバンドル内のすべてのファイルの内容を対象とするため、変更されていないバンドルはスキップされます。一方、手編集されたエンティティファイルは、何もせずに処理を終えるのではなく、新しいバンドルとして扱われます。エクスポートでは、内容が変更されたファイルのみを書き出します。前回のエクスポート以降に誰も書き込んでいないデータベースをエクスポートしても、manifest.json を含め、何も更新されません。そのため、exported_at はバンドルが最後に変更された時刻になります。 hook install はマージ後とリベース後にもインポートします。 4つのフックを書き込みます。post-commit はエクスポート、post-checkout はインポート、post-merge はインポート、post-rewrite はリベース後にインポートします。git は git merge では最初の2つを実行せず、git rebase（独自のコミットがあるブランチでの git pull --rebase が実行するもの）では post-merge を実行しません。そのため、最後の2つがないと、マージまたはリベースされたバンドルがデータベースに反映されず、次のコミットでデータベースがその内容を上書きして、相手側の行が失われていました。githooks(5) によると、post-rewrite は「コミットを書き換えるコマンド（--amend を指定して呼び出された git-commit と git-rebase）によって呼び出され」、最初の引数は amend または rebase です。amend の後は何もしません。修正されたコミットはこのマシン自身のエクスポートだからです。git がマージ中に停止している間は post-merge は実行されません。それを完了するコミットには親が2つあり、そのコミットでは post-commit がエクスポートの前に解決結果をインポートします。これより前にインストールしましたか？ もう一度 hook install を実行してください。

hook install は解決したディレクトリを記録します。 各フックは、install が解決したディレクトリを CUBA_SYNC_DIR に設定します。相対パスは、実行したディレクトリではなくリポジトリのルートから解決されます。IDE、GUI クライアント、または cron ジョブから実行されたコミットにはそれぞれ独自の環境があり、固定値がないと、そのコミットはマージドライバーが参照していない場所にエクスポートしてしまうためです。変数を変更したら、もう一度 hook install を実行してください。最初のブロックを残すのではなく、自身のブロックを置き換えます。.gitattributes の行は、git が照合する唯一の方法で書き込まれます。つまり、作業ツリーのトップからの相対パスで、/ を使い、. や .. を含めません（名前に空白がある場合は引用符で囲みます）。また、以前のインストールが残した行は置き換えます。以前は ./dir、絶対パス、Windows の data\sync がそのまま書き込まれていたため照合されず、added と報告されていました。CUBA_SYNC_DIR がリポジトリの外にある場合でも、フックはインストールされ、共有フォルダーへのエクスポートとインポートを行います。ただし、git は作業ツリーの外にあるファイルをマージしないため、マージドライバーも行もありません。install はその旨を表示します。.gitattributes: skipped — <path> is outside this repo; git never merges it

マージドライバーは認識できるものをマージし、それ以外はユーザーに委ねます。 エンティティ、リレーション、プロジェクト、エピソード、エラー、決定は、同期ディレクトリ内での配置（entities/<file>、relations.json、episodes/<YYYY-MM>/<file>、…）によって認識され、ディレクトリ名にかかわらず ID でマージされます。tombstones.json は (table_name, row_id) をキーにした1つのセットとしてマージされます。両ブランチの削除はそれぞれ1回ずつ反映され、同じ行を両方が削除している場合は、後の削除が優先されます。facts.json、procedures.json、artifacts.json、source_trust.json は、インポート時の競合判定に使われるキー（fact_id、id、(path, project_id)、source）でマージされます。両方に行がある場合は、後のものが保持されます。具体的には、オープンなファクトよりクローズ済みのファクト、プロシージャのより新しい updated_at（成功回数と失敗回数は2つのうち大きい方）、アーティファクトのより新しい CRDT クロック、ソースの信頼度の各カウントは最大値が保持されます。manifest.json は、両方の側で project_id、with_embeddings、embedding_dim、embedding_model、schema_version が一致する場合、こちら側の内容でマージされます。これらはインポートがファイルと照合せずに処理する項目です。残りは派生情報で、次の sync export で書き換えられます。いずれかの値が異なる場合は競合となり、メッセージにはフィールド名が示されます。embeddings.bin.zst、その他のファイル、両側のいずれかが全体を解析できないファイル、またはこのビルドが認識しないフィールドを含むファイルがあると、終了コードが0以外になり、git は競合状態のままにします。以前は何も書き込まずに終了コード0を返していたため、git は「マージ済み」と判断し、マーカーもないままこちら側を保持して相手側を破棄していました。 削除はすぐに伝播し、巻き添えが発生する場合はそこで止まります。 行を削除するとトゥームストーンが記録され、受信側では指定された ID だけが正確に削除されます。以前は、削除の到着が遅かったのではなく、取り消されていました。ピアにその行が残っていたため、エクスポートされ、次のラウンドトリップで戻ってきたのです。エンティティのトゥームストーンは、エンティティを削除すると、それに紐づくすべてのものがカスケード削除されるため、危険です。このマシンに、送信側が指定していないそのエンティティ配下の観測やエピソードがない場合に限って適用されます。それ以外の場合は保留され、tombstones_withheld で報告されます。向こう側に子が 3 つあるエンティティのトゥームストーンによって、こちら側で 300 個が削除されてはなりません。

そして、バンドルが気づかれないままデータを消し去ることはありません。 バンドル内のトゥームストーンによって、25 行以上、かつこのマシンの観測の 10% 超が削除される場合、インポートは拒否され、confirm=true を求めます。リモートからの全消去と、大規模な正当な整理は見分けがつきません。違いは、それを意図したかどうかだけです。下限値は比率と同じくらい重要です。観測が 1 つだけのデータベースでは、割合だけを条件にすると、その 1 件を削除するのにも確認が必要になります。通常の整理でも発動するガードは、誰もが confirm=true を通すようになり、結局何も守らなくなります。

conflict=merge はコンテンツをマージせず、そのことを明示するようになりました。 merge と skip は同じポリシーです。こちらにない行は取り込まれ、行がすでに存在していて内容が異なる場合は、先にこちらにあったものが優先され、受信したテキストは破棄されます。変わったのは、これまでのように何も報告されないことです。インポートではそのような行がカウントされ、ID と処理内容の注記とともに diverged として報告されます。conflict=overwrite では受信したバージョンが採用され、置き換えたバージョンは previous_versions に保持されます（新しいものから 20 件を保持）。また、内容が変わった場合は埋め込みをクリアするため、その行は、もはや含まれていない意味によって検索可能な状態ではなくなります。

どちらのポリシーでも、カウンターはマージされます。 エンティティの importance と access_count、そしてリレーションの strength は、どちらか一方からもう一方へコピーされる値ではありません。それぞれのマシンが、独自の強化と独自のたどり方を通じて値を増やします。2 つの値のうち大きい方が採用されるため、冪等です。同じバンドルを 2 回インポートしても値は増えません。（合計すれば「両方のマシンで数えた」という状態をより忠実に表せますが、再インポートで値が二重になるため、数値を壊さないルールの方を優先します。）

どちらのマシンなのか。 各インストールでは、初回のマイグレーション時にそれぞれのデータベース内で UUID が生成されます。1 行に保存され、再起動後も変わらず、仕組み上重複しません。マニフェストにも含まれるため、バンドルから生成元のマシンを特定できます。CUBA_NODE_NAME は従来どおり、人が読めるラベルを意味し、origin_node に保存されます。これは識別子ではなく、識別子にもなり得ません。2 台のマシンが両方とも pop-os と名付けられるのが、最もありがちな結果だからです。

クロックはピアに必要な変更で進み、ローカルのノイズでは進みません。 観測の version が進むのは、内容、タイプ、信頼度、証拠レベル、またはタグが実際に変わったときだけで、それ以外では進みません。減衰処理では importance と last_accessed が変わり、reembed ではベクトルが置き換えられます。どちらかでクロックが進むと、変更されていないグラフがエクスポートのたびに送られ、2 台のマシンは何もないことについて話し続けることになります。同じ内容で行を書き換えてもクロックは進まないため、冪等な再インポートによって、合意している状態から新たな競合が生まれることもありません。

古いバンドルも引き続きインポートできます。 フォーマットは SCHEMA_VERSION 2 です。競合ルールでクロックを比較するにはファイル内にクロックが必要なため、version、updated_at、origin_node、previous_versions、evidence、verification、trust が含まれるようになりました。それ以前に書き出されたバンドルも引き続きインポートできます。新しいフィールドはすべてデフォルト値が設定され、v1 の観測は asserted として取り込まれます。これは、それ以上に強い主張をしていなかったファイルに対する誠実な解釈です。 受信したバンドル内で認証情報のように見えるものは、信頼済みとしてではなく quarantined として保存されます。cuba_eco で昇格させるまで、cuba_faro と cuba_expediente からは除外されます。インポートでは、プッシュ権限を持つ誰もが書き込めるリポジトリから JSON を読み込むためです。

読み取り専用のピア。 CUBA_PEER_TOKEN で利用できるのは、さらに5つの動詞だけです。pull はバンドルをどこにも書き込まず、応答として返します。ファイル単位でページ分割され（limit、offset）、各ページの上限は3 MBです。ページ間で manifest_hash が変わった場合は中断してください。これは、このノードが転送中に書き換えられ、ページが異なる状態を示していることを意味します。ピアトークンで実行できる唯一の書き込み操作が notify です。別のマシンが何かを学習したことを示す、2000文字以内の短い summary に node_id／node_name のタグを付けて記録します。これは次回の cuba_jornada start と status に表示され、対応する manifest_hash を持つバンドルがインポートされると自動的に閉じられます。通知がグラフに加わることはありません。もう一方の機能である conflicts は、2台のマシンで内容が一致しない行を両方のテキストとともに一覧表示します。resolve id=… keep=ours|theirs|both で1件を解決できます。keep=both（デフォルト）では、このマシンのテキストを現行のものとして残し、もう一方を previous_versions に記録するため、何も破棄されません。一方、theirs では、ここにはもう存在しないテキストを説明していた埋め込みもクリアされます。fetch はそのもう一方の機能で、ローカルマシンで実行します。HTTP 経由でピアの pull をページ単位で取得し、ファイルを配置して、あらゆるバンドルに対するものと同じ検証を行ってインポートし、ピアのマニフェストハッシュを記録します。そのため、変更がなければ次回の fetch はトランザクションを開始する前に終了します。エクスポートではデフォルトで埋め込みを省略し、pull ではデフォルトで埋め込みを含めます。ベクトルを含まないテキストを受け取ったピアは、再埋め込みが完了するまで受信した内容を検索できません。GPU のないマシンでは再埋め込みに時間がかかり、逐次処理になります。また、モデルや次元がこのマシンと一致しないバンドルは、異なるベクトル空間のベクトルでインデックスがひそかに埋め尽くされることがないよう、拒否されます。

壊れたときにも知らせてくれます

$ cuba-memorys doctor
[  ok  ] migrations           49 aplicadas, ninguna dirty
[  ok  ] embedding_dim        runtime 1024-d == columna vector(1024)
[  ok  ] runtime_role         'cuba_app' sin superuser — RLS y audit efectivos
[ warn ] binary_freshness     4 proceso(s) MCP corren un binario más viejo que el de disco

これは、ハイブリッド検索エンジンの障害がクラッシュではないために存在します。ベクトル検索の分岐が停止し、何の症状もないまま検索がひそかに語彙検索へ切り替わるのが、実際の障害モードです。サーバーは埋め込みの次元が一致しない場合、起動を拒否するようになりました。また、検索では分岐に障害が発生すると、応答に degraded: true が設定されます。

CLI：LLM を介さずに使える自分の記憶

コマンドは23個です。memory-industry --help ですべて確認できます。

dedupe — 文字列が異なれば、別のエンティティです

cuba_alma create は ON CONFLICT (name) を使って挿入します。そのため、1つのプロジェクトが Mapupita-Web、Mapupitta-Web（誤字）、Mapupita Web、mapupita…に分散し、いずれか1つを検索しても、ほかの名前は見つかりません。実際の266エンティティのグラフでは、158個（59%）にリレーションが1つもありませんでした。PageRank や複数ホップ検索では、存在しないも同然でした。

マージを決める基準は、埋め込みの重心ではありません。一見よさそうな案ですが、これは誤りです。M-Codes Reference Guide と G-Codes Reference Guide の重心間のコサイン類似度は 0.811 です。1つのドメインを扱うコーパスでは、重心の類似度が示すのは ドメイン であって、エンティティ ではありません。しきい値を0.80にすると、異なる2つのCNCガイドが取り返しのつかない形でマージされていたでしょう。

そのため、--apply がマージするのは確実に同一と証明できるもののみです（大文字小文字と区切り文字を正規化した後に同一になるもの）。誤字や類似した名前は表示され、--judge で1つずつ判定します。古い名前は brain_entity_aliases に記録されるため、情報は失われません。古い名前で検索しても、引き続き解決できます。

31個のツール

キューバ文化にちなんだ名前です。cuba-memorys はすべてのツールを公開します。または、CUBA_TOOL_PROFILE=lean を設定すると、日常的に使う13個のコアツールに cuba_tools と cuba_call を加えたツールを公開します。つまり、31個中15個を公開し、カタログを49%縮小しながら、機能を一切失うことなく、残りのツールも必要に応じて利用できます。

ナレッジグラフ — cuba_alma（エンティティ） · cuba_cronica（観察事項、エピソード、タイムライン） · cuba_puente（型付きリレーション、探索、リンク予測） · cuba_ingesta（一括インポート）

検索 — cuba_faro（ハイブリッドRRF、検証、MMRによる多様化、OOD時の棄権）

エラー記憶 — cuba_alarma（報告） · cuba_remedio（解決） · cuba_expediente（過去のエラーを検索し、以前に失敗したアプローチの場合は警告）

セッションと意思決定 — cuba_jornada（セッションのライフサイクル、差分） · cuba_decreto（アーキテクチャ上の決定） · cuba_proyecto（プロジェクトごとの分離） · cuba_pre_compact（/compact 後も維持）

手順 — cuba_receta（Wilson下限で順位付けされたレシピ）

認知 — cuba_reflexion（ギャップ検出） · cuba_hipotesis（アブダクション推論） · cuba_contradiccion（意味上の競合） · cuba_juez（LLM判定） · cuba_centinela（先行トリガー） · cuba_calibrar（ベイズ校正、情報源の信頼性）

メンテナンス — cuba_zafra（減衰、枝刈り、マージ、PageRank、Leidenコミュニティ） · cuba_eco（RLHFフィードバック） · cuba_vigia（健全性、ドリフト、中心性） · cuba_forget（GDPRによる消去） · cuba_archivo（CFR-21ハッシュチェーン監査ログ） · cuba_pizarra（作業メモリー） · cuba_sync（マシン間のGit対応エクスポート／インポート。削除の伝播とリモート消去ガードに対応）

メタ — cuba_tools（検出） · cuba_call（呼び出し）

設定

フットプリント

メモリサーバーはインフラストラクチャです。使用していないときも動作しています。これが計測された 6 GB のノート PC 用 GPU では、以前は起動時から 5228 MiB の VRAM、つまりカードの 93% を占有しており、他の GPU プログラムが起動できなくなっていました。NVIDIA ドライバーはチャネル作成時に NV_ERR_NO_MEMORY を返しており、これはゲームや GPU アクセラレーション対応ターミナルが失敗する原因です。

以下の数値のうち 2 つはデフォルトとして出荷され、2 つは 1 行の設定が必要です。この表は、あたかも無償で得られたかのように最良の数値を引用するのではなく、それらを区別して示しています。

デフォルト列のすべては出荷されるコードです。CUBA_RERANK_CHUNK=4 は 1 つの環境変数です。最後の列はさらに、以下で説明する再ビルドされたリランカーが必要です。そのいずれも機能を削除していません。

これを実現したのは 4 つのことです。

プロセス単位ではなくモデル単位の配置。 GPU で高速化されるのはリランカーのみです — INT8 のエンベッダーは高速化できず、FP32 の NLI は、時折実行され 150～400 ms を許容するジャッジのために 1 ギガバイトの VRAM を費やす価値はありません。アリーナの上限はセッション単位であるため、6 GB のカードで 3 つのセッションが CUDA を要求するのは、失敗を待つだけの 3 倍のオーバーコミットです。

倍々で増えるのを止める CUDA アリーナ。 ArenaExtendStrategy::NextPowerOfTwo は ONNX Runtime のデフォルトであり、セッションが要求した量ではなく 2 のべき乗で予約します。

リランカーは最初のバッチでロードされます。 ソケットアクティベーションでは、デーモンはリランクするよりもはるかに頻繁に起動し、それらの起動の多くは save に応答するだけです。

誰も要求していないときには動作していないデーモン。 CUBA_IDLE_SHUTDOWN_SECS に加えて systemd の .socket ユニット: ソケットがポートを所有し、デーモンは最初の実際の接続で起動し、アイドルウィンドウの後に終了します。終了は通常の経路を通ります — serve が戻り、バックグラウンドのドレインが処理中の埋め込み書き込みをフラッシュし、sqlx がプールを閉じます — なぜならプロセスを直接終了するとそれらの書き込みが黙って失われるからです。

# ~/.config/systemd/user/memory-industry.socket
[Socket]
ListenStream=127.0.0.1:8787
Accept=no

[Install]
WantedBy=default.target

# ~/.config/systemd/user/memory-industry.service (abridged)
[Service]
Type=exec
ExecStart=%h/.local/bin/memory-industry serve 127.0.0.1:8787
# Every knob — CUBA_IDLE_SHUTDOWN_SECS, the per-model devices — lives in the env file, never here.
EnvironmentFile=%h/.config/memory-industry/memory-industry.env
# An idle shutdown exits 0 — Restart=always would bounce it straight back up.
Restart=on-failure

VRAM はまだ半分にすぎませんでした。重みはホストメモリにも存在し、その消費量は以前はマシンのスペックに関係なく固定でした。cargo run --release --features cuda --example mem_bench で計測、デーモン停止状態、6 GB のノート PC GPU 上での結果は次のとおりです。

常駐メモリは 1941 MiB 付近で落ち着きますが、ピークは 2677 です。これは 1,1 GB の ONNX ファイルをロードすると、その後に残る重みに加えて一時的なメモリが必要になるためです。収まらなければならないのは定常状態ではなく、このピーク値です。

計測を行ったマシンでは問題ありません。しかし 4 GB のノート PC ではそうはいかず、MemoryHigh=4500M で制限された systemd ユニット下では 2,56 GiB のスワップ が発生することが確認されています。MemoryHigh はプロセスを kill せず、メモリを回収します。そして回収とはスワップへのページングです。

これを再実行する場合に知っておく価値のある落とし穴が 2 つあります。mem_bench は nvidia-smi --query-compute-apps を使って VRAM を自身の PID に帰属させます。memory.used を読むとカード上の他のすべてのプロセスの分も計上されてしまうためです。これにより、最初の試行では「プロセス起動時」に 3590 MiB が表示されましたが、それはゲームとデスクトップシェルのものでした。また、デーモン自身の環境で実行してください。CUBA_RERANKER_PATH を未設定にすると fused でない アーティファクトを黙ってロードし、ウォームアップが CPU 上で 3,7 秒から 131 秒になります。

そこでデーモンは起動時にマシンを読み取り、レベルを選択するようになりました。このために新しく作られたものは何もありません。3 つのデグラデーションはすべてすでに存在し、テスト済みです。

レベルの選び方。 予算は min(cgroup 制限, システムの利用可能量) − 768 MiB のヘッドルームで、cgroup の値が優先されます。このマシンでは /proc/meminfo が 7,16 GB の利用可能量を報告しますが、デーモンの cgroup は 4,39 GiB に制限しています。/proc を信じると、カーネルがすでにページングを始めている制限に対して 2,6 GiB の重みをロードすることになります。リーダーは cgroup のルートからリーフまでたどり、見つけた中で最も厳しい memory.max または memory.high を採用します。制限は通常、祖先に設定されているためです。

次にモデルは計測された価値の順に適合されます。まずエンベッダー、次にリランカー (+93% nDCG なのでジャッジより優先)、そして NLI です。

計画は減らすことしかできません。 すべての設定値はデーモンがすでに使用していた値で上限が決まるため、余裕のあるマシンではレベルは full となり何も変わりません。デグラデーションは下方向にしか進みません。

あなたは常に有利です。 これらを手動で設定した場合、その値はそのまま維持されます。レギュレーターは隙間を埋めるものであり、決定を上書きするものではありません。

CUBA_EMBED_INTRA_THREADS   CUBA_RERANK_INTRA_THREADS   CUBA_NLI_INTRA_THREADS
CUBA_RERANK_CHUNK          CUBA_GPU_MEM_LIMIT_MB       CUBA_OOD_FIT_LIMIT
CUBA_DB_MAX_CONNECTIONS

予算に関係なくモデルを強制的にオフにするには、存在しないパスを指定します — CUBA_RERANKER_PATH=/nonexistent または CUBA_NLI_PATH=/nonexistent。これはレギュレーター自身が使用しているのと同じ仕組みです。

何を決定したかを確認するには cuba-memorys doctor を実行してください。読み取り値とその結果の計画を報告し、レベルが minimal に落ちたときには警告を出します。計画は起動時にも、その背後にあるマシンの完全な読み取り値とともにログに記録されます。

リランカーの成果物

公開されている bge-reranker-v2-m3 ONNX は、グラフ融合の前に FP16 へ変換されているため、785 個の Cast ノードが内部に残っています。ONNX Runtime はロード時にその一部を取り戻します（2023 → 897 ノード、49 個の SkipLayerNormalization）が、Gelu を融合することはできず、コールドスタートのたびに同じ処理を繰り返します。FP32 エクスポートから再ビルドし、先に融合すると：

python -m onnxruntime.transformers.optimizer \
  --input model.onnx --output model.onnx \
  --model_type bert --num_heads 16 --hidden_size 1024 \
  --opt_level 1 --use_gpu --float16

実際の検索でのトップ 10 の順序は同一で、fused_score の差は最大 0,0029 です。実際のバッチ形状での合成ロジットでは、Pearson ≥ 0,9997 で、すべてのバッチで順位も同じです。

Attention は融合されませんが、これはここでは修正できません。 is_fully_optimized: Attention (or MultiHeadAttention) not fused が、opt_level 0、1、2、99 のいずれでも、FP16 の成果物とクリーンな FP32 の成果物の両方で発生します。エクスポートは動的形状のサブグラフ（Shape → Gather → Unsqueeze → Concat → Reshape）から Q/K/V のリシェイプを構築し、AttentionFusion は num_heads と head_size を読み取るために定数形状の Reshape を必要とします。そのため、静的形状を使って再エクスポートしない限り、flash/efficient attention は利用できないままです。誰かがこれに午後を費やす前に知っておく価値があります。

測定結果 — そして嘘をついていたベンチマーク

v0.12 まで、このセクションには 「ここにあるすべての数値は仮定ではなく測定されたものです」 という一文があり、そこにあるすべての数値は間違っていました。ベンチマークには 3 つの欠陥があり、それを突き止めるのに 2 つの公開された結論が犠牲になりました。

クエリが 10 件しかありませんでした。 95% 区間はおよそ ±0.12 で、検出できる最小の効果は約 0.25 nDCG でした。それより小さい差についての主張は、小数点をまとったノイズでした。

関連性は部分文字列一致で判定されていました。 結果のテキストがマーカー単語を単に含んでいれば正解とみなされたため、「postgres」に言及したあらゆる観察が、postgres に関するあらゆる質問への正解としてスコアされました。それが何かに答えているかどうかは関係ありません。これはキーワードの存在を測っているのであって検索を測っているのではなく、ベンチマーク全体を字句ベースの枝に傾け、ベクトルの枝に不利にしています。

nDCG は存在するものではなく、検索されたものに対して正規化されていました。 コーパスに 5 件の関連文書があり、2 件が見つかった場合、「理想の」順位はその 2 件とされました。そのため、答えの 60% を取り逃したシステムが満点の 1.0 を獲得しました。（しかも R@10 = 3.125 がこのファイルに記載されていました。再現率は割合です。）

本当の数値は 0.894 ではありません。221 件の id スコア付きクエリでは nDCG@10 = 0.50 [95% CI 0.44–0.56] です。システムが悪くなったのではありません。0.894 だったことなど一度もないのです。

それがもたらした代償

• 「クロスエンコーダー・リランカーは何ももたらさない」 — それは一度も実行されていませんでした。 連鎖した 3 つのバグ：faro が呼び出しを if let Ok(..) で包んでエラーを握りつぶしていた；XLM-RoBERTa であるモデルに token_type_ids を渡していた（そんなものはない）；f16 ロジットを f32 として読んでいた。出力がリランキングなしと「ビット単位で同一」だったのは、リランキングが何も変えなかったからではなく、そもそも実行されていなかったからです。修正済みで、現在は適切に測定されています。

• 連想検索は実際に劣化します — ただし、古い証拠（n=10 で −0.03）ではそれを示せませんでした。ペアードブートストラップ（正しい検定：両方のアームで同じクエリ）を用いた新しいデータセットでは、区間は [−0.051, −0.018] で、ゼロに触れることはありません。0 件のクエリを改善し、23 件を悪化させます。判断は正しかったが、その根拠は正しくなかったのです。検出力はより多くのデータにあったのではなく、正しい検定を使うことにあったのです。

何が生き残るか、正直に再測定

基盤

開発

git clone https://github.com/LeandroPG19/Memorys.git
cd Memorys/rust && cargo build --release

# On an NVIDIA machine, build this way instead — without it the reranker spends
# its whole budget for a ranking that gets discarded. It accelerates the
# reranker only; see Footprint for why the other two models stay on the CPU.
cargo build --release --features docs,cuda

./scripts/demo.sh                  # runs on a throwaway Postgres it removes on exit
./scripts/merge-gate.sh            # local CI 100% — sole merge judge (see docs/gate.md)
./scripts/como-el-ci.sh todo       # same SIL
./scripts/quality-gate.sh          # second judge: CRAP + mutants of rust/src in the diff
cargo run --release --example rerank_bench   # does the reranker fit its budget here?

公開はタグ駆動です。LeandroPG19/Memorys の v* が GitHub Release バイナリ（5 プラットフォーム）、PyPI ホイール（memory-industry と cuba-memorys エイリアス）、npm（memory-industry と cuba-memorys エイリアス）、および MCP レジストリ（io.github.LeandroPG19/memory-industry）をトリガーします。テストが Cargo.toml、package.json、pyproject.toml、server.json を固定しているため、これらのバージョンはずれることがありません。

ライセンス

Apache-2.0 — 使用、変更、配布、販売、クローズド製品への組み込みが可能です。コピーレフト義務はありません。このライセンスは特許権も明示的に付与しており、これが法務部門が気にする部分です。

著者

Leandro Perez G. — @LeandroPG19