Memory Arbiter Mcp

Memory Arbiter MCP

英語 | 中国語

Memory Arbiter は、AI エージェント向けの信頼できるローカルな事実レイヤーです。単なる共有メモリではなく、最新で、信頼でき、追跡可能で、安全に利用できる共有事実を提供します。MCP 経由で公開されるローカル SQLite サービスであり、4 つの製品ツール、エビデンスに基づく想起、競合に関する助言通知、ユーザーが承認するガバナンスを備えています。すべての事実はローカル SQLite に一度だけ保存され、呼び出し可能なすべてのモデルはローカルで実行されます。

現在のリリース：0.17.2（claims チャネルを廃止した mDeBERTa の 3 クラス判定器、remember および workspace-govern アクションで workspace が必須、workspaces ビュー、アップグレード後の行ベクトル自動バックフィル、プロジェクト全体のレビュー修正ウェーブ）。

信頼できる理由

• 完全な唯一の信頼できる情報源。 すべてのメモリには、元のテキスト全体が保持されます。エビデンスベクトル、全文検索、ランキングはすべて 派生 インデックスであり、再構築可能で、唯一のコピーになることはありません。
• すべての書き込みに来歴情報を付与。 各メモリには source_type、source_ref、event_time、ingest_time が記録されます。user_confirmed ラベルは、ユーザーが明示的に確認した事実に限り、慣例として使用します。技術的に強制される保護は、ラベル付け後に適用されます。user_confirmed のメモリは、ひそかな編集から保護されます。
• 信頼レベル。 normal／protected／locked の保護レベルにより、エージェントがロックされた内容をひそかに上書きできないようにします。memory_govern(confirm) は、アクションごとにユーザーの承認を得た場合に限り、メモリを user_confirmed に昇格させます。
• 完全なバージョン履歴。 編集のたびにバージョンを上げて memory_history に追記し、旧事実をひそかに置き換えるのではなく、追跡可能な状態に保つために supersede チェーンを使用します。
• イベントごとに競合レコードを 1 件作成。 単一の conflicts テーブルに、各 1 対多の競合イベントについて、不変の検出スナップショット、値のグループ、判定、適用結果が保存されます。判定器は勝者を提案せず、メモリを編集することもありません。
• 承認されたガバナンス。 状態を変更する memory_govern アクションはすべて、ユーザーがその特定のアクションを確認した後に、アクションごとの authorized=true を必要とします。
• ローカルのみ。 埋め込みはローカルの GGUF モデルで実行されます。オプションの競合判定器は、ローカルの mDeBERTa チェックポイント（CPU）です。外部への呼び出しは、オプションの PyPI 更新チェックのみで、update_check.enabled=false により無効化できます。

ベンチマーク：LoCoMo-Refined

LoCoMo-Refined で評価しました （全 1,382 問、公式判定器 Qwen3-14B）：

構成	全体	テキストのみ
mema + writer-agent（deepseek-v4.1-flash writer、公開ルール）	61.00%	65.62%
mema verbatim（書き込みパスで LLM を使用せず、発話と event_time をそのまま使用）	43.13%	49.48%

背景：Mem0 の完全なパイプラインのスコアは 48.91% です（ベンチマーク作成者がテキストのみを再採点）。書き込みパスで LLM を使わない mema 単体でも、これと同等のスコアを達成します。writer-agent を使うと、リーダーボードのテキストのみを基準とした場合、mema は 2 位になります。 書き込みパスでは、再生した 20 件の会話全体で 552 件の意味的な競合も検出しました（自己学習した mDeBERTa 判定器を、配布時のまま実行）。

完全な方法論、アブレーション（回答者の独立性と 82% の情報上限を含む）、再現手順、提出ファイルについては、 evals/locomo/RESULTS.md を参照してください。

インストールとクイックスタート

AI エージェントでインストール

ターミナルにアクセスできる Codex、Claude Code、Cursor、または別のコーディングエージェントに、次の内容を貼り付けてください：

Read the latest README at https://github.com/billy12151/memory-arbiter-mcp.
Install and configure the latest mema release for my operating system and current AI client.
Preserve any existing config and database; do not overwrite or delete existing data.
Ask me before choosing between materially different install modes, changing existing config,
or performing any destructive or privileged action. When finished, run mema doctor and report
the install method, config path, database path, client integration, and verification result.

エージェントは、この README を信頼できる情報源として扱い、uvx、core、vec、semantic-local のいずれかを選ぶ前にローカル環境を確認し、安全な選択を推測できない場合はユーザーに入力を求める必要があります。インストールが正常に完了したといえるのは、mema doctor を実行し、警告があれば報告した後です。

手動でインストール

# One command: package + deps + embedding model + config.json (resumable downloads, ModelScope fallback)
curl -fsSL https://memarbiter.cn/install.sh | bash

または、次の手順を実行します。

pip install "memory-arbiter-mcp[vec,semantic-local]"  # core + sqlite-vec + local GGUF runtime
mema setup --install   # downloads the embedding GGUF (~330MB, resumable); the mDeBERTa judge is a separate manual install
mema doctor            # verify

--install を付けない mema setup は案内のみを行います。~/.config/memory-arbiter/config.json を書き込み、pip やネットワークには触れずに環境を自己チェックします。--install は実行モードです（pip が追加パッケージをインストールし、中断後の再開とミラーへのフォールバックに対応して埋め込み GGUF モデルをダウンロードし、設定ファイルも自動で書き込みます）。0.15.0 以降、設定はファイルのみで行い、ユーザーが設定できる項目は全 28 個です（設定を参照）：パス、ID、ワークスペース／分離、update_check.enabled、include_size、埋め込みモデル、オプションの意味的競合判定用 mDeBERTa 判定器（mdeberta_ckpt。以下を参照）、Console LLM ワークベンチ独自のエンドポイント（llm.*、0.18.0）、MCP のトランスポート／ホスト／ポートです。リファレンスの examples/memory-arbiter.config.example.json には、各キーの説明とともに同じ簡潔な設定項目が記載されています。続いて、examples/*.mcp.json を使って MCP クライアントを接続し、mema でサーバーを起動します。

機能が不足している場合（例：モデルが一度もダウンロードされていない場合）、すべてのツール応答に、mema setup --install による解決方法を示す永続的な縮退モードのバナーが表示されます。また、各エージェントの最初の呼び出しには機能のヘルスカードが含まれます。インストールが不完全な状態が、気づかれないまま完全な状態として扱われることはありません。

サーバーを起動するには、IDを明示的に設定する必要があります。config.json、または起動コンテキストの環境変数 MEMORY_ARBITER_CLIENT／MEMORY_ARBITER_AGENT_ID で client と agent_id を設定してください（stdio の examples/*.mcp.json エントリーでは env を使って設定します）。組み込みのデフォルト値はありません。どちらか一方でも空欄の場合、サーバーは起動を拒否します。stdio では、この設定済みIDがプロセスレベルの呼び出し元IDとして帰属情報に使用されます。memory(action="remember") の data では agent_id／client を受け付けません。streamable-http では、以下で説明するリクエストごとのヘッダーから呼び出し元IDを取得します。

デフォルトは引き続き stdio です。複数のクライアントで1つのローカルサーバーを共有するには、mcp.transport に streamable-http を設定するか（または、維持されている6つの起動コンテキスト変数の1つである MEMORY_ARBITER_MCP_TRANSPORT=streamable-http を設定し）、http://127.0.0.1:8000/mcp に接続します。各クライアントの MCP サーバーエントリーには、固定の X-Mema-Client および X-Mema-Agent-Id ヘッダーを設定する必要があります。詳しくは examples/streamable-http.mcp.json を参照してください。クライアントはすべての HTTP MCP リクエストでこれらのヘッダーを自動的に送信します。エージェントが個々のツール呼び出しにIDを追加する必要はありません。IDの欠落、空欄、無効、重複、または不一致は、デフォルト値へのフォールバックではなく拒否されます。コミュニティ向け HTTP モードは localhost のみにバインドされます。また、これらのヘッダーは出所を示す参考情報であり、認証やマルチテナント分離には使えません。

日常的なループは4つの呼び出しで構成されます。再利用可能な事実を remember で記録し、find で想起し、正確な情報を read で検索し、より新しい情報源が既存の現行メモリに置き換わる場合は update で更新します（同じ唯一の情報源について、アクティブなコピーを2つ作成しないでください）。remember には workspace が必要です（0.17.1）。まず memory_review(view="workspaces") を呼び出して既存のバケットを一覧表示し、次に既存の正式名を渡します。'default' はグローバルプールです。新しい名前を渡すのは、新しいバケットを意図的に作成する場合に限ります。次のルールを任意のエージェントに設定してください。

{"action":"help","data":{"topic":"agent_onboarding"}}

4つのツール

• memory：remember、find、batch_find、read、batch_read、update、judge、status、help
• memory_review：読み取り専用のヘルスチェック、競合グループ／詳細、履歴、期限切れメモリ、監査、エンティティ
• memory_govern：明示的に承認された廃止、競合プランの適用／解決、確認、ワークスペースのガバナンス
• memory_repair：根拠の再構築、広範な競合のスキャン／記録、履歴の整理、エンティティの割り当て、保留中メモリの有効化、バックアップの再生、意味処理ランタイムの制御、通知のライフサイクル すべての製品呼び出しは、エンベロープ {ok, mode, warnings, degraded, data} を返します。操作固有の action_required、next_action、replan、レコードは data の下に格納されます。成功した呼び出しでは、トップレベルに notices 配列が追加されることもあります。各通知はそれぞれ独自の action_required と、通知オブジェクト内に機械可読な呼び出しを持ちます。汎用のトップレベル action_required を探さないでください。

batch_find は1回の呼び出しで最大8件のクエリを実行し、ページを統合します（memory_id で重複排除し、各項目には matched_query_ids／best_query_id が付与されます。per_query はクエリごとの統計を報告します）。複数トピックのタスクでは、これにより5～10回のツールとの往復を1回に置き換えられます。0.15.9以降、find は該当なしの場合も正直に示します。何も想起できないクエリは、言い換えのヒント付きで空のページを返し（最近のメモリーを詰め込むことはありません）、調整済み関連度の下限値（8.1）を下回る候補はクエリ想起ページに一切表示されません。その結果、「関連しているように見えるが、実際は違う」引用が減ります。

find はインデックスページです。デフォルト（content_mode="preview"、0.15.10）では、各結果にメタデータに加えて content_chars（全文の長さ。read にかかるコストに相当）と、最大8個の {head, offset} セグメントからなる上限付きの outline が含まれます。これらのオフセットは read と同じスパン座標系を共有するため、span=[offset, offset+N] でそのセグメントの該当部分を取得できます。キーワードクエリの形式（0.17.0）： スペースで区切られた短いCJK語（各4文字以下。例：向量 唯一键 冲突）からなるクエリはキーワードとして認識されます。クエリと意味的に近く、内容または件名にキーワードのいずれかを含む（単語全体の部分文字列一致）メモリーは、より上位に表示されます。候補プールを増やしすぎるトピック全般に関する語は無視され、キーワードがどこにも出現しない場合は無理に一致させず、代わりにクエリを言い換えます。内容の深さは、選択肢が1つだけの列挙型です。content_mode="hits" を指定すると hit_spans が追加されます。これはベクトルが一致した単位を、ソースから切り出した {text, start_offset, end_offset} として示します（span=[start,end] を指定した read は、まさにそのテキストを返します）。ヒットスパンが切り詰められることはありません。統合されたヒットが内容の50％以上をカバーする場合、項目は全文に切り替わり、hit_spans は注釈として保持されます。ベクトルヒットがない項目は、通常のプレビュー形式のままです。hit_window=N（デフォルトは0）を指定すると、各ヒットの前後にある完全な文をN文ずつ追加します（追加された文には matched=false のマークが付きます）。hit_spans はクエリ想起ページにのみ表示され、ブラウズ／フィルターページには表示されません。古いバージョンに対するヒットは stale_hit_spans マーカーと再クエリの警告を付けて除外されます（編集直後はエビデンスインデックスの更新が遅れることがあります）。content_mode="full" は全文を返します（以前の include_content=true は0.15.10で削除されており、呼び出しは移行先を示すメッセージとともに明示的に失敗します）。スコアは同じページ内でのみ比較できます。先頭ページに該当する結果がない場合は、深いページを取得するのではなく、クエリを言い換えるか tags_filter を追加してください。フィルターなしのクエリ想起では total_estimate=null／has_more=false が返されますが、フィルター付きの想起では正確な件数が維持されます。size ブロックは実際に返されたページを計測します。returned_chars／returned_count と、設計時にQwen2.5トークナイザーを基準に調整された決定論的なバケット表推定器（heuristic_v1）による tokens_estimate が含まれます（これは調整時の参照にすぎません。0.17.1以降、Qwenのランタイムは同梱されていません）。純粋な中国語の文章では約30％、純粋な英語では約17％多めに見積もられます。推定値も推定された割合も同じ基準に基づくため、削減量の比較は有効です。0.15.6以降、同じ size ブロックがすべての想起インターフェースで返されます。read（返されたレコードを計測し、スパンウィンドウを含みます）、memory_review の expired と history（結果リストを計測します）にも含まれます。これらはすべて、グローバル設定キー include_size（デフォルトは true）で制御されます。各ブロックの display_hint は、報告する想起コストを示す指示とともにトークン数を繰り返し表示します。include_size=false にすると、すべての表示がまとめて無効になります。また、find の以前の呼び出しごとの include_size パラメーターは警告付きで無視されます。unresolved_conflict_count は、ページ内の項目が未解決または適用中の競合グループに直接該当する場合にのみ表示され、そのページ内の該当項目数を示します。

想起の仕組み

語彙チャネルとエビデンスチャネルは独立して想起され、逆順位融合によってメモリごとに統合された後、信頼度、新しさ、フィルター、ワークスペースによる調整が適用されます。

• 語彙：コンテンツに対する FTS5 と、subject/tags に対する LIKE を使用します。ベクトルが利用できない場合に限り、コンテンツに対する範囲制限付き LIKE アンカーチャネルが実行されます（0.16.10 以降の縮退経路）。
• エビデンス：書き込み経路のジョブが、subject（先頭の subject 行）、文、テーブル行から行セグメントを導出します（0.17.0：従来のユニットテーブルは廃止され、行ベクトルが唯一のエビデンスチャネルになりました）。インデクサーは事実を抽出したり、エンティティを推論したり、モデルを呼び出したりせず、保存されたソースを分割するだけです。エビデンスのヒットにはソースのオフセットが含まれます。memory(action="read", data={"memory_id": 42, "span":{"start":120,"end":640}}) は、切り出されたソースウィンドウと data.span.{start,end,total_chars} のみを返します。span を省略すると、ソース全体が読み込まれます。span の境界は厳密な整数であり、0 <= start < end を満たす必要があります。また、end はコンテンツの長さで切り詰められます。100 行を超えるテーブルセグメントは全体が対象外になります（行ベクトルもペア検出も行われず、レシートでは table_rows_exempted と表示されます）。

競合グループと通知

エビデンス KNN は文レベルの近傍を想起しますが、競合の真偽は判断しません。0.17.1 以降、決定論的なファネル（文の事前フィルター、メモリレベルのスクリーニング、コサイン類似度の範囲、ルールによるエビデンス）を通過した各候補ペアは、オプションのローカル mDeBERTa エンコーダーによって判定されます（3 クラス：conflict／no_conflict／possible_conflict と、メカニズムヘッド）。判定器は 2 つの行テキストのみを、メタデータもプロンプトエンジニアリングもなしで確認し、キャリブレーション済みの確率を返します。

• conflict が P ≥ semantic_conflict.mdeberta_notice_min_prob（デフォルト 0.8。0.17.2 以降の v58_ep3_fp16 本番用ペア）の場合 → 通常の重大度の通知。
• possible_conflict が P(conflict)+P(possible_conflict) ≥ semantic_conflict.mdeberta_possible_min_susp（デフォルト 0.7。0.17.2 以降）の場合 → 重大度 info の通知（グレーゾーンの参考情報であり、action_required はありません）。しきい値を下回るペアは通知されず、件数（model_possible_below_gate）に記録されます。
• no_conflict → 問題なしとして通知せず、レシートに記録されます。

判定器は、どちらを優先するか決めたり、スケジュール済みスキャンを抑制したり、メモリを編集したりすることはありません。

ゲートは意図的に 2 つ設けられています。

• スケジュール済みスキャンは広範囲です。 memory_repair(task="scan_candidates") は決定論的な KNN／ルールの候補を保持します。スキャン経路ではモデルを実行せず、エージェントが候補を確認します。include_duplicates=true は引き続き単一ページのスポットチェックであり、そのページについて record_conflict と互換性のあるメンバー全件を確認します。重複をすべてスキャンするには、別タスクの memory_repair(task="scan_duplicates") を使用してください。このタスクは、サーバー側で全ページを集約し、グローバルな上限 200 ペアを適用します。外部レビュアーは、スナップショットの重複排除を有効にするため、トリアージした候補をすべて record_conflict(status="open"|"not_a_conflict") で記録します。
• 書き込み時の通知は判定器のゲートを通ります。 ユーザーに表示される通知には、判定器が設定された確率しきい値以上で conflict と判定すること（または、同一キーで値が異なる場合の決定論的な直接判定）が必要です。スロットの識別には workspace + subject とペアハッシュの差分アンカーを使用します（決定論的な直接経路では実際の属性を保持します）。これに満たない場合は通知せず、後続のスキャンレビューに回します。同一メモリ内の検出結果は常に保留状態になり、スキャン側の高性能モデルが否定判定を行います。同期配信の待機時間（設定可能な semantic_conflict.notice_sync_wait_ms。デフォルト 3000、範囲 0–5000）が制御するのは通知を添付するタイミングのみであり、検出結果は変わりません。 スケジュール済みタスクを設定します。 mema は設計上、内部タイマーを搭載していません。パイプラインの価値ループはエージェント側の判断で終わるため、エージェントを起動するのは外部スケジューラーです。0.16.0 の spec v2 では、v1 のページ駆動型トリアージループが置き換えられています。1 時間ごとのタスクで memory_repair(task="scan_pipeline", data={"action": "kick"}) を complete=true になるまで繰り返し実行します（サーバーがライブラリを自ら走査し、メモリごとのウォーターマークに基づいて全件スキャンか増分スキャンかを判断し、疑わしい項目をすべてエージェント専用の判断キューに登録します。通知やユーザー向けの競合リストには登録しません）。その後、memory_repair(task="scan_queue", data={"action": "page"})／action="submit" でキューを処理します（サーバー側で参照元から登録します。却下の場合は抑制元として登録し、確認の場合はエージェントが slot_key と表示値のみを指定します）。毎日 memory_review(view="doctor") も実行してください。scan_candidates は手動／診断用のチャネルとしてのみ残ります。conflicts.spec_drift は、再構築が必要な v1 時代のタスクを示します。スキャン対象のアンカーを含むページで next_anchor_memory_id=null が返されるたびに、完了した全件スキャンの境界として、scan_log.jsonl に軽量な監査行が 1 行追加されます。それまでは、エージェントに scan_never_run／scan_stale のガイダンス通知が表示されます。また、doctor は、再構築がまだ必要な状態（conflicts.scan_required）や、スキャンが 14 日を超えて停止している状態（conflicts.scan_stale）を通知します。タスクを実行すると、どちらの通知も自動的に表示されなくなります。プラットフォームに依存しない完全な仕様は memory(action="help", data={"topic": "scheduled_tasks"}) です。

単一の conflicts テーブルには、1 件の多対多イベントと、その不変のメンバー／値スナップショットが保存されます。公開ライフサイクルは open → applying → resolved で、not_a_conflict は終了状態のトリアージ結果です。memory(action="judge") は競合のリビジョンを CAS で固定し、選択した値と実行計画を記録して、状態を applying に移します。返された各 memory_govern(action="apply_conflict_action") を、明示的な認可と最新のリビジョンを指定して順番に実行してください。計画されたメンバー操作がすべて完了した後に限り、認可済みの resolve_conflict を呼び出します。use_as_resolution の対象には、選択した値グループを保持するメンバーを指定する必要があります。デフォルトの判断では、メモリ内の誤ったデータを訂正します。古い主張を保持するメンバーには update_current_claim または append_superseded_context を計画し、ユーザーが履歴記録の保持を明示的に求めた場合に限り、preserve_historical_record を使用してください。一部の操作に失敗した場合、状態は applying のままです。data.action_required="replan_conflict" の場合は、グループ／メンバーを読み直し、現在のリビジョンと置き換え後の計画を指定して、認可済みの memory_govern(action="replan_conflict") を呼び出してください。根拠確認に失敗した update_current_claim は、選択した値がメンバーの内容にそのまま現れるように再編集する（保存される機械正規化済みの形式です。複数語のフレーズの場合、その正規化文字列自体が必要です）か、グループの value_groups から選んだ置き換え後の chosen_value を渡すことで復旧できます（0.15.15。chosen_value を置き換えると、明示的に固定されていない限り、解決値の保持先も新しい値グループに移ります）。再計画では以前の計画履歴が保持されます。古くなった事前計算済みのステップを再試行しないでください。

ワークスペース

ワークスペースの正規化は、すべての isolation モードで実行され、アクセス制御とは別のものです。none ではワークスペース ACL は適用されません。ワークスペースを省略するとライブラリ全体が対象となり、明示的に指定すると正規化されたうえで、その読み取りの範囲が限定されます。weak では、弱いランキング／ヒント信号が追加されます（固定の二値ナッジです。連続的なベクトル距離の重み付けは、調整可能な設定ではなくなりました）。strict では、近似一致を黙って統合することはありません。新しいワークスペースは、認可された memory_go(confirm_pending_workspace) によって有効化されるまで pending のままです。Strict の可視性では、ガード付きベクトル受け入れ（0.15.0 以降は常に有効な固定定数）を使用します。ワークスペースに依存する想起／読み取り／修復操作、競合／通知ワークフロー、コンソールのコンテンツ／件数表示は、共通の受け入れ済みセットを使用します。このセットには、呼び出し元の正規名と、デフォルトプール、短い名前、汎用部分文字列の各ガード適用後にコサイン類似度が 0.25 のしきい値以下となるすべての正規名が含まれます。セマンティックランタイム制御、バックアップの再生、doctor、設定などのプロセス全体に関わるメンテナンスは、ワークスペースを範囲とするコンテンツ表示ではありません。ベクトルがない場合や sqlite-vec が劣化した場合は、呼び出し元の正規名との完全一致にフォールバックします。予約済みの default プールは保護されており、strict のプロジェクトスコープからは見えません。自動ベクトル正規化が影響するのは、メモリの workspace_canonical のみです。サポートされているワークスペース管理機能は、rename、migrate、ID による移動（move_memories_workspace）、保留中の確認、レジストリ全体の確認です。内部のリダイレクト／否定判定状態は、古い名前の再分割と、抑制された候補の再表示を防ぎますが、ユーザー向けのワークフローではありません。

正規ワークスペースを登録する最初の書き込みが成功すると、none／weak では、ブロックされないトップレベルの workspace_review 通知と、data.write_hints.new_workspace_detected が返されます。認可された confirm_workspaces を実行する前に、重複の可能性を確認してください。strict では、代わりに既存のブロックを伴う action_required=confirm_new_workspace フローが返され、重複に関するブロックされない通知は出力されません。

想起ブラックリスト（0.15.5）

recall_blacklist.jsonl（データベースファイルと同じ場所）に記載されたワークスペースは、スコープを指定しない find 想起（デフォルトのアンビエントプール）から除外されます。1 行につきワークスペース名を 1 つだけ記載します。空行と # コメントは無視されます。編集内容は次回の find から反映されます。ファイルがない場合は、組み込みのデフォルト（mema-twin の設定用バケットである mema-twin）が適用されます。空のファイルを作成すると、何も除外されません。ファイルを作成すると、デフォルトの内容は完全に置き換えられます。

フィルタリングされないもの：明示的に指定した workspace 引数（ブラックリストに載っている場合も含む）、strict isolation、フィルター主導の想起（空のクエリ + tags_filter／時刻／source_type）、期限切れ監査の経路、書き込み時の重複排除、競合スキャン、ID による読み取りです。除外判定では正規ワークスペース列と raw ワークスペース列の両方を照合するため、正規名がずれた行も検出されます。doctor は有効なリスト（recall.blacklist）を報告します。

Console：ガバナンスとナレッジワークベンチ（0.18.0）

memory-arbiter console を実行すると、ローカルのブラウザーコンソールが開きます（127.0.0.1 のみ）。

• ガバナンス：概要、メンバーを横並びで確認できる競合レビュー、doctor、読み取り専用の設定。
• ナレッジベースタブ：ナレッジベースに含めるメモリを選別します （ワンクリックで追加／削除、ドキュメントから抽出された候補プール、検索して追加）。 メンバーシップは専用の kb_member 列で管理されるため、エージェントがタグを書き換える際に誤って メンバーシップを削除することはありません。ワークスペース → タグの順に参照でき、 レンダリング済みの Markdown 本文と、1 ホップの関連グラフを表示できます。
• LLM 学習ワークベンチ：OpenAI 互換 API を持ち込んで利用できます（Settings でベース URL／ API キー／モデル／コンテキスト予算を設定します。これらはローカルに保存され、コンソールの バックエンド経由でプロキシされ、ページに公開されることはありません。キーは設定ファイルに 平文で保存されるため、ファイルの所有者だけがアクセスできるようにしてください。書き込み処理では 0600 が強制されます）。選択したメモリに対するワンクリック学習アクションは 6 種類です。 要約、アウトライン、クイズ、ファインマン式の解説、自分へのクイズ、タイムラインに加え、 自由形式のプロンプトも利用できます。出力は標準の書き込みパイプラインを通じて、 メモリとして保存できます（agent_id=console として帰属します）。

isolation=strict では、コンソールは一度に 1 つのワークスペースだけを表示します （バケット間の回避経路はありません）。デフォルトの none モードでは、「All workspaces」を 選択してください。

mema の運用

• mema doctor [--json|--deep] — 読み取り専用のヘルスチェックです。--deep は GGUF モデルを読み込み、稼働中の埋め込み次元を確認します。workspace.review は、レビュー済みスナップショットに含まれない正規レコードがある場合に警告します（CLI の終了コードは 1）。まず重複レコードの名前変更または統合を行い、その後、明示的なリストを指定せずに認可済みの memory_govern(confirm_workspaces) を呼び出して現在のレジストリをスナップショットに記録すると、このチェックは合格に戻ります。他に警告が残っていない場合にのみ、CLI 全体の終了コードは 0 になります。
• mema console — 127.0.0.1 上の読み取り専用ローカルコンソールです。
• memory(action="status") — local_text_evidence のカバレッジ、vec_index_state、プロセス内のインデックスキュー、キューの破棄や再起動、および check_degradation.last_reason を含む semantic_conflict の実行時情報を表示します。
• memory_repair のメンテナンスタスク：rebuild_evidence（ドライラン後にバッチ実行します。埋め込みモデルの変更後はインデックスが state=mismatch を報告し、再構築によって自動的に ready に戻ります）、semantic_control（status/pause/resume/enable/unload/disable）、replay_backup（ドライラン後に認可済みの実行）、cleanup_history、set_entity、activate_pending、scan_duplicates（1 回の呼び出しで全ライブラリを対象に近似重複を検索します。対象は軽量ペア 200 件までです。include_quotes=true を指定すると、検出のきっかけとなった証拠の引用が追加されます）。

証拠キューとセマンティックキューはプロセス内にあるため、クラッシュや強制終了によってキュー内の作業が失われることがあります。キューの深さから永続的なカバレッジを推測しないでください。再起動後、または証拠処理で busy／破棄の通知があった場合は、local_text_evidence のカバレッジを確認し、ドライランの結果が空になり、ベクトル状態が ready になるまで rebuild_evidence を実行してください。セマンティックワーカーのキューの破棄は、スケジュール済みの scan_candidates パスで復旧します。rebuild_evidence では復旧しません。証拠の再構築は冪等な派生インデックスの修復です。未処理だった競合候補や通知を復旧するのはスキャンです。

古いデータベースからのアップグレード

0.14.8 へのアップグレードに関する警告： 現在のランタイム起動時に受け入れられるスキーマ世代は workspace_state_v1 のみです。conflict_groups_v2 と local_text_evidence_v1、および旧形式の claim／memory-vector／section-vector データベースは、変更せずに拒否されます。公開されているサイドバイサイド方式の mema upgrade を実行してください。すべてのスキーマ移行では vector_effect=preserve|rebuild が宣言されます。2 世代前までのエビデンスからの移行では、現在のモデルが利用可能かどうかにかかわらず、ベクトルのペイロードが保持されます。互換性は別途評価されます。設定された埋め込み空間が異なる場合は state=mismatch が記録され、ベクトルの読み取りが無効になり、後から memory_repair(rebuild_evidence) で修復されます。どちらの経路でも、現在のワークスペースのリダイレクト／否定判定状態が集約され、廃止されたワークスペース判定イベント台帳は破棄されます。

サイドバイサイドコピーでは、メモリーの内容／履歴、バックアップの再生レシート、ワークスペースの正準データと現在のリダイレクト／否定判定状態、および監査データが保持されます。廃止されたワークスペース判定イベント台帳はコピーされません。保持移行では、FTS／エビデンス／ベクトルのペイロードが変更されずに複製され、競合ドメインのみがトランザクション内で再構築されます。ベクトルの健全性や空間の不一致が、構造移行の結果に影響することはありません。再構築移行では、エビデンスとベクトルが再生成されます。どちらの経路でも、新しい conflicts／通知状態は意図的に空の状態で開始され、古い conflicts、追記専用の conflict_judgments、または semantic_notices の履歴はコピーされません。現在の矛盾は、スケジュールされたライブラリ全体のスキャンで再検出する必要があります。

再構築後、ステータス／doctor は、永続的なスキャンエポックとともに conflict_scan_required=true を報告します。このフラグを CAS でクリアできるのは、アップグレード時にアクティブだったメモリーの集合全体を対象とし、一致する検出器バージョンを使用した全件スキャンが成功した場合のみです。部分ページ、失敗したスキャン、古い検出器によるスキャンではクリアされません。ターゲットが公開されるのは、行／フィンガープリントの検査が完了し、PRAGMA wal_checkpoint(TRUNCATE) が成功し、ターゲットの WAL／SHM サイドカーファイルが削除された後のみです。完全再構築経路では、対象となるエビデンスがすべて揃っていることも必要です。ソースデータベースは削除されません。

# Preview only.
mema upgrade --dry-run

# Stop every mema MCP client/worker. Make a WAL-safe rollback backup:
sqlite3 /absolute/path/to/memory.sqlite3 "PRAGMA wal_checkpoint(TRUNCATE);"
cp /absolute/path/to/memory.sqlite3 /absolute/path/to/memory.pre-0.14.sqlite3

# Migrate and switch the standard JSON config.
mema upgrade

# Restart the MCP client and verify.
mema doctor --json

After the upgrade, the first server start launches a daemon thread that backfills sentence row vectors automatically; watch progress in `mema doctor` (`rows.coverage`) or `memory(action="status")`. With no embedding model configured the backfill stays pending and resumes once the model is available — nothing to run by hand.

完全なエビデンス再構築経路には、sqlite-vec、設定済みで読み取り可能なローカル GGUF 埋め込みモデル、llama-cpp-python（GGUF 埋め込みも実行するため、semantic-local extra をインストールしてください）、書き込み可能なターゲットディレクトリ、および十分な空きディスク容量が必要です。保持移行では、どちらのモデルも読み込まず、ベクトルが完全であることも必要としません。ベクトルの互換性は個別に報告され、互換性のない保持データには mismatch が設定されます。オプションの競合判定チェックポイント自体は、移行の前提条件ではありません。コマンドは、確認を求める前に、選択したモード、ベクトルへの影響／互換性、メモリー数、推定ベクトル処理量、空きディスク容量、ソース、ターゲットを報告します。

上記の明示的なチェックポイント処理が重要なのは、ライブ WAL フレームが存在する状態でメインの .sqlite3 ファイルだけをコピーしても、完全なバックアップにならないためです。代わりに、停止する前に SQLite のオンライン .backup コマンドを使用してください。wal_checkpoint(TRUNCATE) が 0 以外の busy カウントを報告した場合は中止してください。mema upgrade も切り替え前に新しいターゲットのチェックポイント処理と検証を行いますが、オペレーターがソースをロールバックするためのコピーは作成しません。

古いデータベースは削除されません。標準の JSON 設定はバックアップされ、完全な検証が済んだ後にのみ切り替えられます。環境変数による db_path の上書きは、手動での対応事項として報告されます。設定を編集せずに構築と検証を行うには、--no-switch を使用してください。--yes は対話型の確認と、すべての書き込み側／ワーカーが停止しており、古い競合／判定／通知の履歴が恒久的に除外されることへの確認を両方とも省略します。プロセスの停止、ソースのチェックポイント処理、バックアップの作成は行いません。診断用には、低レベルの mema migrate-vnext コマンドも引き続き使用できます。新しいデータベースが通常運用で正常に動作するまで、古いデータベースを保持してください。新しいデータベースに書き込みが受け入れられた場合は、それらの新しいレコードを先に考慮せずに切り戻さないでください。

設定

設定は 0.15.0 以降、ファイルのみで行います。調整可能な項目はすべて ~/.config/memory-arbiter/config.json（または、起動コンテキスト変数 MEMORY_ARBITER_CONFIG が指すファイル）に保存されます。mema setup を実行すると、初期テンプレートが書き込まれます。エンジンパラメーター、タイムアウト、しきい値、上限値は固定定数です（memory_arbiter/constants.py）。

ユーザー向けの設定項目は全部で 28 個です（0.15.14：semantic_conflict.n_gpu_layers を追加し、semantic_conflict.max_notice_pairs と policy_path を削除。0.17.1：claims.required、semantic_conflict.model_path、n_gpu_layers を削除し、4 つの semantic_conflict.mdeberta_* キーを追加。0.17.2：semantic_conflict.mdeberta_possible_min_susp を追加。0.18.0：6 つの llm.* キーを追加）。

{
  "db_path": "~/.local/share/memory-arbiter/memory.sqlite3",
  "backup_jsonl": "~/.local/share/memory-arbiter/memory.backup.jsonl",
  "client": "your-client",
  "agent_id": "your-agent-id",
  "workspace": "default",
  "isolation": "none",
  "update_check": { "enabled": true },
  "include_size": true,
  "embedding": {
    "model_path": "~/.local/share/memory-arbiter/models/embedding.gguf",
    "auto_query": true,
    "auto_write": true
  },
  "semantic_conflict": {
    "enabled": true,
    "mdeberta_ckpt": "~/.local/share/memory-arbiter/models/mdeberta-v58_ep3_fp16.pt",
    "mdeberta_notice_min_prob": 0.8,
    "mdeberta_possible_min_susp": 0.7,
    "on_write": "async",
    "notice_sync_wait_ms": 3000
  },
  "llm": {
    "base_url": "",
    "model": "",
    "api_key": "",
    "max_context_tokens": 0,
    "max_output_tokens": 8192,
    "timeout_seconds": 120
  },
  "mcp": {
    "transport": "stdio",
    "http": { "host": "127.0.0.1", "port": 8000 }
  }
}

設定	目的
db_path	現在の SQLite データベース
backup_jsonl	SQLite に書き込めない場合の追記専用フォールバック
client / agent_id	必須の呼び出し元 ID。組み込みのデフォルト値はありません。どちらかが空白の場合、サーバーは起動を拒否します
workspace / isolation	デフォルトのワークスペースと、none／weak／strict のワークスペース動作
update_check.enabled	オプションの単発バックグラウンド PyPI 検出（デフォルトは true）。唯一のネットワーク呼び出しです。通知はキャッシュまたは抑制され、自動アップグレードは行われません
include_size	リコールのサイズブロックに対するグローバルスイッチ（v0.15.6）：オンの場合、find／read／expired／history のすべてに {returned_chars, returned_count, tokens_estimate} が付加されます。オフの場合、いずれにも付加されません
embedding.model_path	ローカルの GGUF 埋め込みモデル。このモデルを指定することが、sqlite-vec によるエビデンスのリコールを有効にする唯一の方法です
embedding.auto_query / auto_write	クエリ／書き込み時に自動で埋め込みを作成します（デフォルトは true）
semantic_conflict.mdeberta_ckpt	書き込み時の競合判定に使うローカルの mDeBERTa チェックポイント（0.17.2 での切り替え以降は v58_ep3_fp16、約531MB、別途配布）。設定すると自動的に有効になり、起動時に読み込まれて常駐します（CPU fp32）。まず mdeberta エクストラをインストールしてください。下記のモデルダウンロードに関する注記を参照してください
semantic_conflict.enabled	明示的な無効化スイッチ。未設定で mdeberta_ckpt が設定されている場合は有効になり、明示的に false を指定した場合はそれが優先されます
semantic_conflict.on_write	書き込み時の検出：async（デフォルト）または off
semantic_conflict.notice_sync_wait_ms	書き込み応答がコミット後のチェックを待ち、その結果を応答に含める時間（v0.15.8、デフォルトは 3000、範囲は 0–5000）。0 の場合、書き込み応答は待機しません。バッチ取り込みではチェックが引き続き非同期で実行され、通知は後続の応答で配信されます
semantic_conflict.mdeberta_model_dir	config.json とトークナイザーディレクトリ。デフォルトは <ckpt dir>/mdeberta-base
semantic_conflict.mdeberta_notice_min_prob	通常の重大度の通知における P(conflict) の下限（デフォルトは 0.8。0.17.2 以降の v58_ep3_fp16 の本番ペア）。これを下回るペアはカウントされますが、通知されません
semantic_conflict.mdeberta_possible_min_susp	info 重大度のグレーゾーン通知における P(conflict)+P(possible_conflict) の下限（デフォルトは 0.7、v0.17.2。exam と LoCoMo のゴールドコーパスで調整済み）。これを下回るペアはカウントされ（model_possible_below_gate）、通知されません。0 にすると、v0.17.2 より前のゲートなしの動作に戻ります
semantic_conflict.mdeberta_batch	判定のバッチサイズ（デフォルトは 0＝自動。デバイスの階層に応じて設定されます：GPU（Apple Silicon／NVIDIA）では16、CPUでは8。明示的に >0 を指定すると階層設定を上書きします。起動時のプローブはありません）
mcp.transport	stdio（デフォルト）またはオプトインの streamable-http ローカルホストサーバー
mcp.http.host / port	ローカルの HTTP エンドポイント。ホストはループバックに制限され、デフォルトは 127.0.0.1:8000 です。エンドポイントパスは /mcp に固定されています
llm.base_url / llm.model / llm.api_key	Console LLM 学習用ワークベンチ専用の OpenAI 互換エンドポイント（0.18.0、すべてオプション。空の場合、ワークベンチは利用できません）。ローカルにプレーンテキストで保存されます。書き込み時には設定ファイルに 0600 が強制適用され、キーはコンソールバックエンド経由でのみプロキシされ、ページには公開されません
llm.max_context_tokens	ワークベンチの1回の呼び出しに対する素材の予算（デフォルトは 0＝自動、範囲は 0–10,000,000）
llm.max_output_tokens	生成上限（デフォルトは 8192、範囲は 1–1,000,000）。思考モードのモデルが出力予算を使い切らないように設定されています
llm.timeout_seconds	リクエストごとのタイムアウト（デフォルトは 120、範囲は 1–3600）。値は書き込み時と再読み込み時に同じように制限されます

examples/memory-arbiter.config.example.json を参照してください。 知っておくべき仕様：埋め込み次元はモデル自体から決まります。データベースには現在有効な次元が記録され、異なる次元のモデルに切り替えると、起動時にベクトルテーブルが自動的に削除され、新しい次元で再構築されます（証拠全体の再構築は一度だけ行われます）。ランキング方式は固定のハイブリッド方式（語彙検索＋証拠の融合）で、ランキング方式を切り替える設定はありません。HTTP リクエストの処理はステートレスで、リクエストボディの上限は 4 MB です。

起動コンテキストとして残る環境変数は 6 つです：MEMORY_ARBITER_CONFIG、MEMORY_ARBITER_DB_PATH、MEMORY_ARBITER_BACKUP_JSONL、MEMORY_ARBITER_MCP_TRANSPORT、MEMORY_ARBITER_CLIENT、MEMORY_ARBITER_AGENT_ID。これらはプロセスのコンテキスト（どの設定ファイル、どの DB、どのトランスポート、どの ID を使用するか）を選択します。同じ項目の値が設定ファイルにある場合は、設定ファイルの値が優先されます。それ以外の MEMORY_ARBITER_* 変数は読み取られなくなりました。古い環境変数が設定されていると、mema doctor、コンソールの設定ページ、memory(action="status") に「読み取られなくなりました」という警告が表示されます。同様に、削除されたファイルキーには「設定できなくなりました」という警告が表示され、無視されます。docs/INTEGRATION.md には、0.14 から 0.15 へのキー移行表があります。

HTTP モード：1 つのローカルサーバーを共有する

stdio（デフォルト）ではバックグラウンドプロセスは不要です。各 MCP クライアントが、それぞれ独立した短命の子プロセスとして mema を起動します。複数のクライアントが接続する、1 つの長時間稼働するローカルサーバーが必要な場合にのみ、streamable-http に切り替えてください。

	stdio（デフォルト）	streamable-http
mema の起動方法	各クライアントが子プロセスを起動します	1 つの永続プロセスを実行し、クライアントが接続します
バックグラウンドプロセスの必要性	いいえ	はい — そうしないとターミナルを閉じたときに終了します
クライアント設定	コマンド＋引数	URL＋固定のリクエストヘッダー 2 つ
適した用途	1 人、1 クライアント	1 台のマシンで複数のクライアントが 1 つのメモリーストアを共有する場合

設定方法：

1. 設定：~/.config/memory-arbiter/config.json で mcp.transport を "streamable-http" に設定します（または MEMORY_ARBITER_MCP_TRANSPORT=streamable-http を設定します）。
2. 実行を継続する：mema には組み込みのデーモン機能がありません。プロセスマネージャーを使用してください。macOS では、examples/com.memory-arbiter.mema.plist の launchd テンプレートを使うと、ロード時に起動し、クラッシュ時に再起動し、/tmp/mema.{out,err}.log にログを記録します（__MEMA_BIN__ を which mema が出力する絶対パスに置き換え、~/Library/LaunchAgents/ に配置してから launchctl load を実行してください）。手軽に試す場合は、tmux new -d -s mema 'mema' を使用できます。
3. クライアント：examples/streamable-http.mcp.json をコピーし、X-Mema-Client と X-Mema-Agent-Id を記入します。

注：mema は MCP セッションではなく SQLite にメモリーとセマンティック通知の状態を保持するため、HTTP リクエストの処理はステートレスです（0.15.0 以降、変更されていない固定仕様です）。そのため、サービスを再起動しても、クライアントが期限切れのサーバーセッションを保持することはありません。非同期に作成されたセマンティック通知は、これまでと同様に SQLite から取得され、後続の正常なツール応答に添付されます。プロセスの再起動で中断される可能性があるのは、通知がまだ永続化されていないワーカージョブだけです。

クライアントはすべての HTTP MCP リクエストに固定ヘッダーを自動的に付与します。エージェントが個々のツールの data に ID を追加してはなりません。追加すると拒否されます。ID が欠落している場合、空の場合、重複している場合、または競合している場合は、デフォルト値にフォールバックせず、フェイルクローズで拒否されます（400）。サービスはループバックインターフェイスのみにバインドされます。これらのヘッダーは情報の出所を示すものであり、認証ではありません。launchd はシェルの PATH を引き継がず、~ も展開しないため、ProgramArguments と、config.json の GGUF model_path には絶対パスを指定してください。

localhost HTTP 経由の Claude Desktop／Claude Code

Claude のローカル MCP 設定では、stdio コマンドが起動します。別の mema プロセスを起動する代わりに、実行中の mema HTTP サービスを 1 つ再利用するには、~/.claude.json の mcpServers に次のエントリーを 1 つ追加します（現在の Claude Desktop／Cowork と Claude Code のインストールでは、このユーザーレベルのファイルが共有される場合があります）。

{
  "mcpServers": {
    "memory-arbiter": {
      "command": "/opt/homebrew/bin/npx",
      "args": [
        "-y",
        "[email protected]",
        "http://127.0.0.1:8000/mcp",
        "--allow-http",
        "--transport", "http-only",
        "--header", "X-Mema-Client:claude",
        "--header", "X-Mema-Agent-Id:claude",
        "--silent"
      ],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
        "NO_PROXY": "127.0.0.1,localhost"
      }
    }
  }
}

お使いのマシンで which npx を実行して確認した絶対パスを使用してください。mema／memory-arbiter-mcp を直接起動する古い memory-arbiter エントリーがある場合は削除してください。そうしないと、Claude が 2 つ目のサーバープロセスを起動する可能性があります。ファイルを変更した後は、Claude Desktop を完全に終了して再起動し、Claude Code のセッションも再起動してください。mcp-remote はサードパーティ製のブリッジです。上記の固定バージョンは、mema で動作確認済みの設定です。お使いの Claude が別の Desktop MCP ファイルを使用する場合は、代わりに同じエントリーをそちらに配置してください。ただし、両方に登録しないでください。

コンフリクト判定モデル（mDeBERTa、任意）

書き込み時のコンフリクト判定には、1 回限りの手動インストールが必要です（約 531MB の fp16 チェックポイントは PyPI に含まれていません）。

1. pip install memory-arbiter-mcp[mdeberta] を実行します（torch CPU wheel 約 200MB と transformers）。
2. mini-clash のリリース成果物から、mdeberta-v58_ep3_fp16.pt（約 531MB、fp16 の重み）と mdeberta-base ディレクトリ（config.json と tokenizer、数 MB）をダウンロードします。
3. config.json の semantic_conflict.mdeberta_ckpt に .pt ファイルのパスを指定します（起動時に自動で有効化され、事前読み込みされます。mdeberta_model_dir のデフォルトは、チェックポイントと同じ階層にある mdeberta-base フォルダーです）。

mema doctor は依存関係、チェックポイントのダイジェスト、判定モデルのラベル仕様を検証します。未設定の場合、書き込み時の調停は無効になります（scan／Agent のフォールバックには影響しません）。ONNX＋INT8（より小型で、torch 不要）は今後のリリースで対応予定です。

劣化時の動作

• sqlite-vec または埋め込みモデルがない場合も、語彙による再現とメモリのガバナンスは継続します。エビデンスのインデックス作成は利用できません。
• mDeBERTa 判定モデル（追加パッケージ／チェックポイント／設定）がない場合、書き込み時の調停は無効になります（通知は一時停止します）。スケジュールされた scan は、決定論的な KNN／ルールのベースライン候補を引き続き返します。
• SQLite を利用できない、または書き込みできない場合、書き込みが成功したときに限り、追記専用の JSONL エンベロープを使用します。JSONL に含まれるのはメモリレコードと選択された canonical であり、内部リダイレクトや否定判定は含まれません。ワークスペースの判定状態を保持するには、SQLite データベースを保持するか、アップグレードしてください。

開発

uv run pytest -q
python scripts/sync_version.py --check

開発中は、パッケージ／ドキュメントが未リリースの開発バージョンを記載する一方で、MCP Registry マニフェストである server.json は直近のリリースバージョンのままになる場合があります。リリース準備の一環として scripts/sync_version.py がこれを更新し、--check によって不一致を防ぎます。

中国語の要約

Memory Arbiter（迷码）は、AI エージェント向けのローカルな信頼できる事実レイヤーです。各事実の完全な原文は 1 件だけ保存し、ベクトルと検索は再構築可能な派生インデックスとして扱います。コンフリクト scan は広い条件で候補を取得し、書き込み時の notice は mDeBERTa の 3 分類判定で処理します（0.17.1 以降、すべてのファネルゲートを維持）。単一の conflicts テーブルで一対多のイベントを保持し、ライフサイクルは open → applying → resolved または not_a_conflict です。判定後は judge → apply_conflict_action → resolve_conflict の順にガバナンスを行います。none/weak/strict のいずれもワークスペースを正規化します。strict では guarded vector admission を使用し、default プールはプロジェクトのスコープに入りません。workspace_state_v1 へのアップグレードでは、古い conflict／judgment／notice の履歴と古い workspace decision event ledger が消去され、epoch 付きの全データベース scan を完了する必要があります。中国語の完全なドキュメントは README.zh-CN.md をご覧ください。また、INTRO.md と docs/INTEGRATION.zh-CN.md も参照してください。