MGI-Mind

MGI-Mind

英語 | ロシア語 | 中国語

最新リリース：v2.8.2 · 変更履歴 · ディスカッション · 課題 · 貢献

AI アシスタント向けのローカルな長期記憶です。Rust 製の単一バイナリ、ローカルの Qdrant ベクターデータベース、ローカルの ONNX モデルで構成されています。MCP に対応しているため、Claude Code などのアシスタントが自分で記憶を読み書きできます。通常の CLI としても使えます。

事実を平易な言葉で保存し、保存時の言葉が一つも含まれないクエリで呼び出します。セマンティック検索が意図を照合します。アシスタントは MCP 経由で同じ mind_search を自分で実行します。vhs docs/demo.tape で再生成できます。

アシスタント内での同じやり取り：

You:  what was the deploy server again?

Assistant (calls mind_search "deploy server"):
  -> "Deploy server is 10.0.0.5:8080, SSH as deploy@, key in vault"  (source: infra.md)

You:  right, thanks

データが外部に出ることはありません。埋め込み、検索、再ランキング、保管庫はすべてローカルで動作します。クラウドアカウント、API キー、テレメトリーは不要です。

---

目次

• 概要
  • 有効性モデル
• 使う理由
• クイックスタート
• 使い方
• 仕組み
• コマンドリファレンス
• 設定
• 言語と再ランキングモデル
• 埋め込みモデルの変更
• トラブルシューティング
• セキュリティ
• ステータスと監査
• プロジェクト構成
• ライセンス

概要

MGI-Mind は、あなたとアシスタントの間で動作します。会話の進行に合わせてアシスタントが短いメモ（「記憶」）や事実を書き込み、必要なときに関連するものを呼び出します。

単なる保存ではなく、検索も可能です。

• ハイブリッド検索。 各記憶は 2 種類のベクトルとして保存されます。意味を捉える密ベクトル（multilingual-e5-base、768 次元）と、単語を正確に検索する疎な単語頻度ベクトル（TF-IDF、BM25 方式）です。クエリは両方の検索を実行し、逆順位融合で結果を統合します。「The server box」は密ベクトル検索で「deploy host」を見つけます。一方、fossilize_replay は疎ベクトル検索で、完全一致するトークンを含むメモを見つけます。
• クロスエンコーダーによる再ランキング。 統合後の上位候補を bge-reranker-base で再評価します。このモデルはクエリと各文章をまとめて読み、ベクトル同士を比較するよりも高精度です。デフォルトで有効で、英語に最適化されています。他の言語でのトレードオフについては、言語と再ランキングモデルを参照してください。
• 常時稼働する単一プロセス。 mgimind mcp 自体が MCP サーバーです。セッション中は稼働し続け、モデルは一度だけ読み込まれてメモリ上で保持されるため、検索の所要時間は毎回モデルを再読み込みする場合の時間ではなく、数ミリ秒です。

検索機能に加えて、構造化された事実を扱うナレッジグラフ、セッションをまたいだ継続性を保つエージェントごとのセッションログ、そしてターミナルからのみアクセスできる暗号化保管庫があります。

有効性モデル

ハイブリッド検索は基本機能であり、ほとんどの記憶ツールに何らかの形で備わっています。より見つけにくいのは、古くなったり、矛盾したり、自己強化したりする信念でストアが固まらないようにする仕組みです。これらは主に自動で動作します。

• 決闘ルール。 新しい事実が同じ主語と述語について既存の事実と矛盾する場合、2つ目の書き込みは2つ目の「真実」を積み重ねるのではなく、1つ目との決着をつけます。定着した事実（依存する事実の数、確認回数、経過時間が多いもの）は維持されます。新たな強い事実はそれを覆し、敗れた事実を非表示のstaleステータスに弱めます。判断が拮抗する場合は、係争中とマークするか、隔離に回します。確認はリアルタイムで累積します。同じトリプルを再度主張すると、その事実自身のconfirmations_countが増えるため、数回確認済みの事実は、新たな矛盾が1つだけあっても覆されにくく（覆すのではなく係争中になります）、未確認で新しい事実はこれまでどおり簡単に覆ります。dependantsは引き続きmigrate-v14 dependants --applyのバックフィルによってのみ追加されます。安価なリアルタイム生成処理（書き込みのたびにグラフを走査することになるため）は実装されていません。何も削除されないため、監査ログには敗れた事実が残ります。staleになった敗者が再提案されると、現在の事実を相手に改めて決闘します。その際、最初からやり直すのではなく、元のcreated_atと確認履歴を保持します。通常のmind_fact addの内部で自動的に行われます。
• 疑念ウィンドウ。 定着した事実は、常に自らを再正当化する必要があります。事実のクエリごとに、現在のコンテキストがその事実の記録時のコンテキストからどれほど変化したかを測定します。変化した状態での検索が5回連続すると、その事実は、依然として有効な事実より優先されなくなります。コンテキストに沿った検索が1回でもあれば、カウントはリセットされます。非表示になることも削除されることもありません。異方性のある埋め込み空間では、生のコサイン類似度でトピックを区別できないため、ドリフトはコーパス平均を除去したベクトルで測定されます（下記のmgimind calibrateを参照）。現在のコンテキストは実行中プロセス自身の直近のクエリに基づくため、ウォーム状態のmgimind mcpまたはserve-httpセッション内で適用されます。単発のCLIコマンドにはまだコンテキストがないため、事実がペナルティを受けることはありません。この機能はシャドウモードで提供されます。ドリフトは測定・記録されますが、独自のストアの数値に基づいてdoubt_drift_thresholdを設定し、doubt_drift_modeを"enforce"に切り替えるまでは、事実に変化はありません。また、バックグラウンド処理で、しばらく検索されていない定着済みの事実を個別に再検証します。ツール呼び出し中には実行しないこと、ティックごとの上限を設けること、負荷に応じて実行頻度を調整することを厳守します。
• 継承による割引。 mind_contextのブリーフィング（セッション開始時にセッションが受け取る情報）は、提示するすべての事実に、そのプロセス内で継承されたことを示すマークを付けます。決闘の挑戦側がそうした継承済み事実の再提案である場合、つまりエージェントがリアルタイムで独自に再確認したのではなく、伝えられた内容を繰り返している場合、その挑戦の重みは半分になります。エージェントが実際にリアルタイムで事実を再主張し、矛盾なく登録された時点で、このフラグは解除されます。同一ソースからの確認を繰り返すたびに重みを低くする単一ソース減衰には（diversity_weighted_count）という式がありますが、現時点でそれを呼び出す処理はありません。まだ実装されておらず、現時点では「相互確認できない」という保証もありません。
• 事実の2つの時間軸。 記録時刻（created_at／valid_until：ストアが値を学習／廃止した時点）は、置き換えの連鎖とともに二時点管理されます。述語はmind_predicateで、単一値（現在値は1つ）、時間的単一値（現在値は1つですが、以前の値も保持され、mind_historyで日付を指定して検索可能）、または複数値として登録できます。置き換えられた値はデフォルトのランキングでは非表示になりますが、消去されません。任意の第2の軸である世界時刻（追加時に設定可能なvalid_from）は、ストアが事実を知った時点ではなく、世界でその事実が真になった時点を記録します。as_ofとworld_time=trueを指定したmind_fact action=queryは、この軸に基づいて特定時点のクエリを解決します。valid_fromがない場合は、事実ごとに記録時刻を使用します。既存の事実を移行する必要はありません。単にvalid_fromを持たない状態となり、これまでとまったく同じように動作します。
• 明示的な無効化は取り消せません。 mind_fact action=invalidateは後戻りできない操作です。その後に同じトリプルを再追加しようとしても、ひそかに復活させるのではなく、拒否されます（判定結果はinvalidated）。元に戻す唯一の方法はmind_fact action=restoreです。
• 型付きの結果シグナル。 mind_outcomeは、記憶された修正が実際に機能したことを（test_passed、code_compiled、user_confirmed、cited_by）で記録します。実際の成功は記憶の重みを高め、手順を検証済みとしてマークします。失敗は無視されるのではなく、重みを下げます。 これらは研究段階のメカニズムであり、調整定数は現在も調整中です（duel.rs／ doubt.rs の TODO(phase-4-calibration) マーカーは、その事実を正直に示しています）。重要なのはその仕組みです。記憶が自らと議論し、持ちこたえられなくなったものの評価を下げることで、際限なく蓄積するのを防ぎます。

mgimind calibrate は、その仕組みが意図どおりに動作するかを測定します。現実的な対立状況のコーパスを実際の決闘の計算式に通し、期待される結果に至った件数を報告します。新たな裏付けのない主張では根付いた信念を覆せず、CI シグナルなら覆せること、繰り返しだけの場合は上書きせずに共存することを確認します。現在、15 件中 14 件のシナリオが意図どおりに一致しています。一致しなかった 1 件は理由とともに表示され、隠されることはありません。また、このテストスイートは CI で実行されます。さらに、疑念ウィンドウのドリフト分布も報告します。このレポートが存在するのは、実際に測定した結果があったからです。ドリフトのしきい値は 0.4 でした。384 次元の MiniLM 空間で選ばれ、デフォルトモデルが 768 次元の multilingual-e5 になった後もそのまま使われていました。実際のストアで 400 件の記憶と全 79800 組のペアを測定したところ、未加工のコサイン類似度は 0.666～0.972 で推移し、しきい値は一度も発動しませんでした。コーパスの平均ベクトルのノルムは 0.884 で、コサイン類似度のほぼすべてを、ほとんどの埋め込みに共通する成分が占めていました。中心化によって測定を補正し、calibrate は、埋め込み空間間で引き継がれた定数ではなく、独自のストアで生じるドリフトからしきい値を提案します。

これは有効性モデルの仕組みを測定するもので、検索再現率（R@k、BENCHMARKS.md を参照）とは別です。この 2 つは異なる数値であり、同じ表に載せるべきではありません。

なぜ導入するのか

メモリのないアシスタントは、セッションのたびに同じコンテキストを尋ね、昨日の作業を土台にできません。一般的な回避策は、ユーザー自身がメモ、タグ、フォルダーを管理することですが、アシスタントはそれらを意味で検索できません。

MGI-Mind が Obsidian や Notion と異なる点は、何を書き留めるかをシステムが決め、ユーザーは決めないことです。 MCP サーバーはアシスタントの作業をリアルタイムで読み取り、関連性ゲートを通じて事実、決定事項、修正内容をストアに振り分けます。ユーザーが分類したり、タグ付けしたり、何を保存する価値があるかを判断したりする必要はありません。シグナルの弱い候補は、検索を汚染するのではなく、隔離レイヤーに保存されます（再度主張すれば復元できます）。

代表的な代替手段との比較は次のとおりです。

• 通常のメモ（Obsidian、Notion）。 個人用ノートとしては優れていますが、アシスタントは意味で検索できず、.md ファイルのフォルダーでは、どのキー入力も同じ重要度で扱われます。
• 単純なベクターデータベース。 セマンティック検索はできますが、完全一致検索、再ランキング、重複排除、セッション、事実、シークレットの処理、関連性ゲート、手続き的メモリはありません。これらはすべて自分で組み立てる必要があります。
• ホスト型メモリ API。 データは他者のサーバー上に置かれます。内部の確認、重複排除の挙動、関連性ゲートが実際にどのように動作しているかを把握できません。

MGI-Mind は、これらの機能を組み合わせたローカル版です。ハイブリッド検索と再ランキング、関連性ゲート、重複排除、事実、セッション、手続き的メモリ（「エラー → 修正」のプレイブック）、ターミナル専用のボールトを備え、すべてを自分で実行する単一のバイナリで提供します。

評価に関する注意点です。BENCHMARKS.md では検索再現率（LongMemEval-S の R@k、API ゼロ、LLM による判定なし）を報告しています。質問に対して、正解のセッションが上位 k 件に含まれていたかを測定します。デフォルトの CPU 設定では、R@5 ≈ 98% です。これは、他のメモリツールが公開している QA 正解率とは異なる指標です（それらは検索結果に対して回答生成器と判定器を実行します）。そのため、同じ表に並べないでください。これは証拠を検索できたかを測定するものであり、その後 LLM が正しく回答したかを測定するものではありません。mgi-mind には回答生成のステップがないため、検索再現率が実際に評価できる指標です。

正直なところ、差別化要因である妥当性モデル（決闘ルール、疑念期間、旧情報の置き換え）は、検索再現率では検証できません。代わりに、これを検証するものが 2 つあります。mgimind calibrate は、動作が意図に沿っているかを確認します（現在 14/15。ご自身でも実行してください）。これは読者が期待する動作を機構が実現していることを示すものであり、定数が実データに対して調整済みであることを示すものではありません。外部の信念改訂ベンチマークは古く、予備的な部分実行のみが存在します（N=155、約32%、benchmark/results/ に生の判定結果があります）。これは main 上の足場ではなく、あるブランチのハーネスによって、縮小したデータセットで生成されたものであり、決闘ルールがまだ壊れていた時期の可能性もあります。詳しい注意事項は BENCHMARKS.md を参照してください。妥当性モデルは、形状が検証されていて定数はまだ調整されていない設計上の機構として捉えてください。外部データで有効性が証明されたものではありません。

クイックスタート

Docker（1 つのコマンドで脳全体を起動）

イメージにはバイナリ、同梱の Qdrant、ONNX ランタイム、モデルが含まれているため、何もインストールせずにオフラインで実行できます。

docker run -p 8765:8765 madgodinc/mgi-mind

起動時にベアラートークンが表示されます。そのトークンを使って、Python クライアント または任意のエージェントを http://localhost:8765 に接続します。ボリュームを使って再起動後もメモリを保持し、安定したトークンを設定するには、次のようにします。

docker run -p 8765:8765 -e MGIMIND_TOKEN=your-token \
  -v mgimind-data:/data madgodinc/mgi-mind

エージェントに接続する

エージェントに recall と remember の 2 つのツールを渡すと、プロセス終了後もメモリが保持されます。サーバーを起動し、Python クライアント をインストールした状態で、次のようにします。

from mgimind import Memory

mem = Memory()                         # MGIMIND_URL / MGIMIND_TOKEN from the env
mem.add("Prod DB is Postgres 16 on db-prod:5432")
for hit in mem.search("prod database"):  # structured results: id, score, author
    print(hit["score"], hit["content"])

このラッパーが統合のすべてです。LangGraph、Pydantic AI、OpenAI Agents SDK、raw HTTP（任意の言語）のコピーしてすぐに使える例は、docs/integrations にあります。エディタークライアントでは MCP と stdio も引き続き使用できます。HTTP のインターフェースは、エージェントフレームワーク向けの入口です。

npm（任意の MCP クライアント）

Node.js 18 以降では、npm パッケージがリリースの SHA-256 と照合したうえで、お使いのプラットフォーム向けのビルド済みバイナリをインストールします。

npx -y mgi-mind init          # creates ~/mgimind
npx -y mgi-mind doctor --fix  # downloads Qdrant and the models
claude mcp add mgimind -- npx -y mgi-mind mcp

ほかのクライアントでは、MCP 設定に同じコマンドを指定します： "command": "npx", "args": ["-y", "mgi-mind", "mcp"]。

ネイティブインストール

コマンドは 1 つです。インストーラーはバイナリを PATH に配置し、init と doctor --fix を実行します（Qdrant、ONNX Runtime、モデルを取得します）。または、コーディングエージェントに AI_INSTRUCTIONS.md を使って mgi-mind をインストールするよう伝えてください。インストール後の使い方だけでなく、インストール自体についても説明しています。

Linux / macOS：

curl -fsSL https://raw.githubusercontent.com/madgodinc/mgi-mind/main/install.sh | sh

Windows（PowerShell）：

irm https://raw.githubusercontent.com/madgodinc/mgi-mind/main/install.ps1 | iex

完了すると、表示されたコマンドでサーバーが Claude Code に登録されます：

claude mcp add mgimind -- /home/you/.local/bin/mgimind mcp

mgimind mcp は MCP サーバーそのものです。セッション全体を通して実行され、モデルを読み込み済みの状態に保ち、初回使用時にバンドルされた Qdrant を起動します。プロトコルを把握できるよう、アシスタントに AI_INSTRUCTIONS.md を一度提示してください（セッションを記録する、回答前に検索する、秘密情報には Vault を使う）。

doctor --fix はモデルを ~/mgimind/ にダウンロードします。モデルは埋め込みモデル（multilingual-e5-base、量子化 ONNX、約 270 MB）とリランカー（bge-reranker-base、量子化 ONNX、約 280 MB）です。ONNX Runtime と Qdrant バイナリは mgimind バイナリ自体の隣に配置されます。そのため、不足しているライブラリがあると doctor に報告された場合、それは ~/mgimind/ ではなく <install dir>/ に関するものです。

インストーラーフラグ

• INSTALL_DIR=/opt/mgimind curl ... | sh：~/.local/bin 以外の場所にインストールします。
• MGIMIND_TAG=v2.8.2 curl ... | sh：latest の代わりに、特定のリリースを指定します。
• SKIP_DOCTOR=1 curl ... | sh：バイナリの配置だけを行います。後で自分で init と doctor --fix を実行してください。

手動インストール（インストーラーを使わない場合）

スクリプトをシェルにパイプしたくない場合は、お使いの OS 向けのリリース tarball をリリースから取得し、mgimind を PATH に配置してから、次を実行します：

mgimind init
mgimind doctor --fix
claude mcp add mgimind -- /absolute/path/to/mgimind mcp

CLI から試してみてください（同じバイナリをアシスタントなしでも使えます）：

mgimind create work
mgimind add work "Deploy server is 10.0.0.5:8080, SSH as deploy@"
mgimind search "how do I reach the deploy box"

OS ごとの注意事項

• Linux x86_64、macOS arm64 と x86_64、Windows x86_64：すべてのリリースにビルド済みバイナリがあります。インストーラーが適切なものを選びます。
• macOS の PATH：zsh には ~/.local/bin が含まれないため、インストーラーは export PATH の行を ~/.zshrc に追記し、その旨を通知します。mgimind を入力する前に、新しいターミナルを開いてください。インストーラーに dotfiles を変更させず、自分で行を追加するには MGIMIND_NO_PROFILE=1 を設定します。
• macOS Intel と ONNX Runtime：1.24 では osx-x86_64 が廃止されたため、Intel Mac には ONNX Runtime 1.23.0 が、それ以外には 1.24.2 がインストールされます。バイナリは C API 23 を要求し、どちらのランタイムもこれを提供します。
• macOS の初回実行時の隔離属性：インストーラーが解除しますが、ブラウザー経由でダウンロードしたバイナリには xattr -d com.apple.quarantine /path/to/mgimind を実行する必要があります。リリースはアドホック署名されており、公証されていません。Sequoia 以降では、右クリックして「開く」を選ぶ方法はコマンドラインバイナリでは機能しなくなったため、xattr を使うか、「システム設定」→「プライバシーとセキュリティ」で一度許可してください。
• Windows：署名されていない mgimind.exe に対して SmartScreen が警告を表示する場合があります（「Windows によって PC が保護されました」）。**「詳細情報」→「実行」**を選択してください。ウイルス対策ソフトがバイナリやダウンロードしたモデルを隔離する場合もあります。mgimind doctor が、ダウンロード済みと報告したファイルが見つからないと表示する場合は、ウイルス対策ソフトで mgimind.exe と %USERPROFILE%\mgimind フォルダーを許可してから、mgimind doctor --fix を再実行してください。SmartScreen の警告をなくすコード署名は、今後の予定に含まれています。

ソースからビルド

Rust ツールチェーン（rustup）が必要です。それ以外の依存関係はありません。

git clone https://github.com/madgodinc/mgi-mind.git
cd mgi-mind
cargo build --release                  # binary: target/release/mgimind

続いて target/release/mgimind init && target/release/mgimind doctor --fix を実行し、 claude mcp add mgimind -- /absolute/path/to/target/release/mgimind mcp で登録します。

使用方法

手動（CLI）：

mgimind add notes "Mom's birthday is March 14, she likes peonies" --source personal
mgimind search "when is my mother's birthday"
#  1. [notes] (score: 0.94) Mom's birthday is March 14, she likes peonies
#     source: personal

mgimind fact add "user" "prefers" "Rust"
mgimind fact query "user"
#   user -> prefers -> Rust

mgimind history --limit 3              # the three most recent memories
mgimind stats                          # counts per library, facts, sessions

矛盾時の決着ルール。 2つの事実が矛盾し、述語が Single または TemporalSingle の場合、2つ目の追加時に最初の事実との矛盾を解決し、事実が積み重なるのを防ぎます。

# Tell the system this predicate has one current value at a time:
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call",
  "params":{"name":"mind_predicate","arguments":
    {"action":"register","predicate":"lives_in",
     "cardinality":"TemporalSingle"}}}' \
  | mgimind mcp

mgimind fact add "Alice" "lives_in" "Prague"
mgimind fact add "Alice" "lives_in" "Dublin"
mgimind fact query "Alice"
#   Alice -> lives_in -> Dublin
# (Prague is preserved as history, queryable via mind_history / audit log
#  but hidden from default ranking.)

読み取り時に決着ルールが適用されなかった v1.7 より前のインストールから移行した場合は、mgimind migrate-v14 redo-duels --apply を一度実行して、従来の矛盾を正規の回答に統合してください。この処理は冪等で、デフォルトではドライランです。

アシスタント経由（MCP）。 接続したら、話しかけるだけです。

You:  remember that the staging DB password is in the vault under "staging-db"
Assistant: (mind_add) saved. The secret itself stays in your terminal vault, not here.

You:  what database are we using on staging?
Assistant: (mind_search "staging database") Postgres 16, host db-staging.internal:5432

検索結果は段階別に返されるため、アシスタントはトークンを効率よく使えます。--tier 1 は約100文字のスニペット、--tier 2（デフォルト）は約500文字、--tier 3 は全文です。

ストアを確認する

mgimind brain はメモリをグラフとして描画します。メモリ、事実、領域をコアとして表し、それらをつなぐリンクを表示し、ストアの変更に合わせて脈動します。ループバックのみにバインドされ、URLとともに表示されるトークンが必要です。

コントロール画面として扱ってください。制限のないビューアーは DELETE /api/memories/:id、PATCH /api/node/:id、隔離状態からの昇格も受け付けるため、そのポートにトークン付きでアクセスできるものはストアを変更できます。書き込みできないビューアーを使うには、許可リストに限定して起動してください。

mgimind viewer --libraries work,personal

この設定では、すべての変更系ルートに加え、すべてのライブラリにまたがるルート（グラフ、監査、パルス、取り込みフィード）も403でフェイルクローズします。mgimind brain はフラグを受け付けないため、常に制限のない形式で起動します。

仕組み

  your AI assistant
        |  MCP (JSON-RPC over stdio)
        v
  mgimind mcp  (one Rust process: MCP server + embedder, models stay warm)
        |  starts on first use
        v
  Qdrant (local, loopback only)
        |
        one "memories" collection, two vectors per point:
        dense (e5, meaning) + sparse (TF-IDF, exact terms)

ストレージ。 すべてのメモリは1つの Qdrant コレクションに保存されます。各ポイントの library フィールドで名前空間（仕事、個人、プロジェクトなど）を分け、クエリでは1つのライブラリに絞り込むことも、すべてを横断して検索することもできます。ポイントの ID は library + content の UUIDv5 であるため、同じテキストを2回追加すると同じポイントが上書きされ、重複や競合は発生しません。created_at の日時インデックスにより、history はスキャンせずに最新の N 件を直接返します。

埋め込み。 テキストは ONNX Runtime を使ってローカルで埋め込まれます。デフォルトは多言語対応の multilingual-e5-base（768次元）で、英語に強く、複数の言語が混在するテキストにも対応します。埋め込みモデルはモデルを認識し、プーリング（mean または CLS）、token_type_ids 入力、クエリ／パッセージのプレフィックスはすべて設定可能なため、モデルを切り替えるのにコードの変更は不要です。入力は512トークンまでに制限されます。add は長いテキストをチャンクに分割するため、上限を超えた部分が気づかないうちに失われることはありません。

検索。 クエリは一度だけ埋め込まれます。Qdrant は1回の Query API 呼び出しで密な最近傍検索と疎な検索を実行し、RRF で統合します。再ランキングが有効な場合は、上位の rerank_top_k 件の候補がクロスエンコーダーによって再スコアリングされ、並べ替えられます。library フィルターが指定されている場合は、両方の検索に適用されます。

安全性。 ダウンロード時に、固定された SHA-256 ハッシュとの照合を行います（フェイルクローズ）。Qdrant はループバックのみにバインドされ、API キーを必須にすることもできます。ボールトはターミナルからのみ操作でき、マスターパスワードと復号されたシークレットが MCP チャネルを通ることはありません。ファイルへの書き込みはアトミックです（一時ファイル、fsync、名前変更、ディレクトリの fsync）。そのため、クラッシュしても旧ファイルか新ファイルのどちらかが残り、破損することはありません。

コマンドリファレンス

メモリ

コマンド	機能
mgimind add <library> <content> [--source <tag>]	メモリを保存します。長いテキストはチャンクに分割され、保存したチャンク数が表示されます。
mgimind search <query> [--library <l>] [--limit N] [--tier 1|2|3]	ハイブリッド検索を行い、再ランキングします。Tier によって返されるテキストの量が決まります。
mgimind history [--limit N]	新しいものから順に、直近のメモリを表示します。
mgimind delete <library> <id>	IDを指定して1件のメモリを削除します（IDは検索結果に表示されます）。
mgimind context	セッション開始時に使う簡潔なブリーフィングを表示します。前回のセッション、最近の事実、ライブラリが含まれます。

ライブラリ

コマンド	内容
mgimind create <name>	ライブラリを登録します。
mgimind list	ライブラリを一覧表示します。
mgimind drop <name>	ライブラリと、そのすべての記憶を削除します。
mgimind stats	ライブラリごとの件数、ファクト、セッション、Vault の状態を表示します。

ナレッジグラフ

コマンド	内容
mgimind fact add <subject> <predicate> <object> [--valid-from <date>]	ファクトのトリプルを保存します。同じトリプルを再登録すると、重複を追加する代わりに確認回数が増えます。明示的に無効化されたトリプルは、復元せずに拒否します。--valid-from では、現実の世界でいつそのファクトが真になったかを任意で指定できます。
mgimind fact query <term> [--as-of <date>] [--world-time] [--history]	主語、述語、目的語のいずれかに指定した語句を含むファクトを検索します。--as-of では指定した時点の状態を確認できます（デフォルトは記録時刻で、--world-time を指定すると valid_from に切り替わります）。
mgimind fact invalidate <id>	ファクトを論理削除します（ディスク上には保持され、無効としてマークされ、クエリ結果には表示されなくなります）。
mgimind fact restore <id>	無効化を取り消します。復元する唯一の方法です。

スキル

手順は「これが壊れました。前回は何をして直しましたか」に答えます。スキルは「これから X をします。X を行う際の決まりはありますか」に答えます。同じストレージと同じ結果シグナルを使いますが、異なるタイミングで、作業の前にタスクに照らしてマッチングします。 コンテキストのレンダリングにはカタログ（名前とトリガー）が含まれるため、アシスタントは検索しなくても何があるかを把握でき、該当するスキルの本文だけを取得できます。

コマンド	内容
mgimind skill set <name> --when <trigger> --body <text>	スキルを書き込みます。名前が識別子となるため、同じ名前で再度書き込むと、履歴を保持したまま編集されます。--body-file <path> を指定すると、ファイルから本文を読み込みます。
mgimind skill match <task> [--limit N]	タスクに適用できるスキルを、関連性とこれまでの実績に基づいて順位付けして表示します。
mgimind skill list / mgimind skill show <name>	カタログ、または指定したスキルの全内容を表示します。
mgimind skill outcome <name> [--failed] [--verify]	スキルを適用した結果を記録します。--verify には、推測ではなく決定的なシグナルが必要です。
mgimind skill rm <name>	スキルと、その結果履歴を削除します。

セッション

コマンド	内容
mgimind session start --agent <name>	エージェントのセッションログを開始します。
mgimind session end --agent <name> --summary <text>	要約を付けてセッションを終了します。
mgimind session last [--agent <name>]	直近のセッションを表示します（任意で指定したエージェントのセッションに限定できます）。

Vault（ターミナルのみ）

コマンド	内容
mgimind vault store <key> <value> [--category c] [--desc d]	暗号化されたシークレットを保存します。
mgimind vault get <key>	シークレットを取得します（マスターパスワードの入力後、確認を求めます）。
mgimind vault list	キー名を一覧表示します（値は表示されません）。
mgimind vault delete <key>	シークレットを削除します。

サービスとデータ

コマンド	説明
mgimind mcp	stdio 経由の MCP サーバーとして実行します（アシスタントが接続する先です）。1 つのプロセスを起動したままにし、Qdrant を自動的に起動します。
mgimind serve / mgimind stop	同梱の Qdrant を手動で起動／停止します（必要になることはほとんどありません。mcp が自動で処理します）。
mgimind migrate [--purge]	従来のライブラリごとのコレクションを、単一の memories コレクションに再埋め込みします。冪等です。--purge を指定すると、完了後に古いコレクションを削除します。
mgimind relibrary --from <lib> --to <lib> (--source-match <re> | --content-match <re> | --ids-file <path>) [--apply]	メモリーを別のライブラリに移動します。ポイント ID はコンテンツアドレス方式のため、移動先の ID が再計算され、元のベクトルとペイロードがそのまま引き継がれ、cited_by の参照が付け替えられた後、元のポイントが削除されます。デフォルトではドライランです。移動先の ID が無関係なコンテンツですでに使われている場合は、上書きせずに報告します。中断後に再実行しても安全です。
mgimind backup <file> / mgimind restore <file>	データディレクトリを gzip+tar でバックアップ／復元します。Qdrant が応答する場合、qdrant/storage をそのままコピーするのではなく、各コレクションを独自のスナップショット API 経由で取得するため、同時書き込みによってバックアップが破損することはありません。models/ は常に除外されます（doctor --fix で再ダウンロードできます）。--encrypt を指定すると、同じアーカイブを AES-256-GCM で暗号化します。
mgimind export [--format json|md] [--output <dir>]	メモリーをファイルにエクスポートします。md では、チャンクに分割されたドキュメントの断片を順番どおりに結合し、1 つのブロックに戻します。
mgimind import <obsidian|markdown> <path> [--library <l>]	Markdown ファイルのフォルダーを再帰的にインポートし、チャンクに分割します。
mgimind doctor [--fix]	ヘルスチェックを実行します。--fix を指定すると、不足しているものをダウンロードします。

設定

設定は ~/mgimind/config.json にあります。検索結果に影響するフィールドは次のとおりです。

フィールド	デフォルト	説明
model_name	multilingual-e5-base	models/ 内の埋め込みモデルのディレクトリです。
vector_size	768	埋め込みの次元数です。モデルと一致している必要があります。
pooling	mean	mean（e5、MiniLM）または cls（一部の XLM-R モデル）です。
uses_token_type_ids	false	BERT 系モデルでは true、XLM-R／e5 では false です。
query_prefix / passage_prefix	query: / passage:	e5 ではこれらが必要です。不要なモデルでは空にします。
rerank_enabled	true	クロスエンコーダーによる再ランキングを有効にします。下記の言語に関する注記を参照してください。
rerank_model	bge-reranker-base	models/ 内の再ランキングモデルのディレクトリです。
rerank_top_k	20	limit 件を返す前に取得して再ランキングする候補数です。
qdrant_port	6334	Qdrant の gRPC ポートです。
qdrant_http_port	none	backup／restore のスナップショットと doctor のレポートで使用する、Qdrant の REST ポートです。未設定の場合、Qdrant の標準のポート組み合わせに従い qdrant_port - 1 として導出されます。サーバーがこの組み合わせに従わない場合にのみ設定してください。
qdrant_api_key	none	設定すると、Qdrant の起動時にこのキーが使われ、クライアントが認証を行います。

言語とリランキングモデル

デフォルトのスタックは英語向けに調整されています。アシスタント自体が最も得意とする言語であり、モデルの性能も最も高いためです。英語を優先するプロジェクトには、この設定をおすすめします。

知っておいていただきたい点をいくつか挙げます。

• 埋め込みモデル（multilingual-e5-base）は、実際に多言語に対応しています。英語のクエリでロシア語のメモが見つかり、その逆も可能です。検索だけでも言語をまたいで適切に機能します。
• デフォルトのリランキングモデル（bge-reranker-base）は、英語向けに調整されています。英語の順位付けは向上しますが、ロシア語（およびその他の英語以外の言語）では順位付けの品質が低下します。デフォルト設定で英語が優先されるのはここだけです。
• コンテンツの大部分がロシア語（またはその他の英語以外の言語）の場合： rerank_enabled = false に設定してください。ハイブリッドの密ベクトル検索と疎ベクトル検索だけでも、これらの言語は適切に順位付けされます。品質を下げるのは英語向けに調整されたリランキングモデルです。または、より強力な多言語対応のリランキングモデルに切り替えてください。
• リランキングではクエリごとにクロスエンコーダーの推論が必要です。CPU のみの環境で 20 件の候補を処理する場合、約 1～2 秒かかります。検索を高速化するには、rerank_top_k を小さくするか、リランキングを無効にしてください。

埋め込みモデルの変更

モデルを切り替えると通常はベクトルの次元数が変わるため、既存のメモリを再度埋め込む必要があります。

1. まずバックアップを作成します：mgimind backup ~/mgi-backup.tar.gz。
2. 新しいモデルに合わせて、config.json の model_name、vector_size、pooling、uses_token_type_ids およびプレフィックスを設定します。
3. mgimind doctor --fix を実行してモデルをダウンロードします。ピン留めされているのは同梱のデフォルトモデルのみです。カスタムモデルのダウンロード時には「integrity not verified（整合性未検証）」の警告が表示されます。厳密な検証を行う場合は、integrity.rs でその SHA-256 をピン留めしてください。
4. mgimind migrate を実行して、新しいモデルを使い、保存されたテキストからすべてのデータを再度埋め込みます。

トラブルシューティング

• 「Model not found ... run doctor --fix」： モデルが ~/mgimind/models/ にありません。mgimind doctor --fix を実行してください。
• 「invalid expand shape」／推論エラー： 通常、入力が 512 トークンを大幅に超えています。add は自動的にチャンク化します。ライブラリを直接呼び出す場合は、先にチャンク化してください。
• 検索が遅い： CPU 上でリランキングモデルを実行しているためです。rerank_top_k を小さくするか、rerank_enabled = false に設定してください。モデルは mgimind mcp プロセスの実行中はメモリ上に保持されるため、セッション中に読み込みコストがかかるのは最初の検索だけです。
• インストール直後にツールが失敗する： mgimind doctor を実行してください（アシスタントから mind_doctor を呼び出せます）。不足しているもの（Qdrant が実行されていない、モデルがダウンロードされていない、ONNX Runtime がない、AV によってファイルが隔離されているなど）が正確に報告され、--fix を指定すると可能なものがダウンロードされます。
• 次元数の不一致に関する警告： コレクション内のベクトルと vector_size が一致していません。通常はモデルを変更した後に発生します。mgimind migrate で再度埋め込んでください。
• ロシア語の検索結果が適切でない： rerank_enabled = false に設定してください（上記の言語に関する説明を参照）。
• mgimind の実行中に VPN、トンネル、またはプロキシが動作しなくなる： mgimind doctor を実行し、ネットワークの使用状況を確認してください。mgimind のすべてのポートはループバックにのみバインドされ、mgimind はルート、DNS、ファイアウォールの設定を変更しないため、トンネルの外へトラフィックを流すことはありません。mgimind と同時に起動するものを確認してください。Docker Desktop と WSL2 はそれぞれ独自の仮想アダプターを追加します。また、厳格なルーティングを行う TUN クライアントでは、アダプターが出現または消失したときにトンネルが切断されることがあります。

セキュリティ

• ONNX Runtime（linux-x64）、Qdrant、デフォルトモデル（e5 とリランキングモデル）のダウンロードは、ピン留めされた SHA-256 と照合して検証されます（検証に失敗した場合は処理を中断します）。その他のプラットフォームやカスタムモデルについては、無条件に信頼するのではなく警告が表示されます。
• Qdrant は 127.0.0.1 のみにバインドされ、API キーに対応しています。
• ボールトには AES-256-GCM を使用し、Argon2id から導出したキーで暗号化します（ライブラリをアップグレードしてもロックアウトされないよう、パラメーターをピン留めしています）。操作はターミナル内でのみ行われるため、マスターパスワードと復号された秘密情報が MCP チャネルを経由することはありません。mind_vault_* MCP ツールが返すのはターミナルでの操作手順であり、秘密情報そのものではありません。
• ファイルへの書き込みはアトミックに行われ、ディレクトリーも fsync されます。そのため、クラッシュ時に残るのは古いファイルか新しいファイルのどちらかであり、破損したファイルが残ることはありません。

ネットワークの接続範囲

mgi-mind が開くすべてのソケットは、ループバックにバインドされます。

コンポーネント	ポート	バインド先
Qdrant HTTP	qdrant_http_port。デフォルトでは qdrant_port - 1 から算出	127.0.0.1
Qdrant gRPC	qdrant_port。デフォルトは 6334	127.0.0.1
mind_visualize	4173	127.0.0.1
mgimind viewer	ランダム。起動時に表示	127.0.0.1
mgimind serve-http	ランダム、または --port	--host を指定しない限り 127.0.0.1

別のインターフェースにバインドする方法は serve-http --host だけです（Docker の -p マッピングではこの指定が必要です）。また、ループバック以外のホストを指定する場合は、 --agent-token も渡さないと拒否されます。

mgimind はドライバーをインストールせず、ネットワークアダプターを追加せず、ルート、 DNS、ファイアウォールの設定も変更しません。mgimind doctor はすべてのポートを 実際にプローブして、この接続範囲を表示します。そのため、この説明は信頼するだけでなく、 自分で確認できます。

ステータスと監査

現在のバージョン：2.8.2（v1.0.0 以降、semver に準拠した安定版）。0.x 系では 基盤を構築しました。監査ログと一時的なビューアー（0.10）、隔離レイヤーと ベストエフォートの検索ポリシー（0.11）、ビューアーの強化（0.12）、セッションの 稼働状態（0.13）、手続き型メモリー（0.14。LongMemEval-S と、20 の公開リポジトリから 作成した 227 組のエラー→修正データセットでベンチマークを実施）を追加しました。 1.x 系では妥当性モデルを追加しました。これには、決闘ルール、疑いの期間とその バックグラウンド再テスト、二時相的な事実の置き換え、信頼度スコア、型付きの結果シグナル （mind_outcome）のほか、インストールモード別の CPU／GPU プロファイルが含まれます。

MCP のインターフェースは 2.0 へのメジャーバージョンアップまで追加のみです。 ライブツール 29 個に加え、互換性維持のため非推奨のエイリアス 15 個を残しています。 2.x 系では名称変更や削除はありません。新しい動詞（直近では mind_skill）が追加される 場合があります。その他の 1.0 の契約には、非対称な「Qdrant の現在値 → md の記述」の 差分照合と、MGIMIND_MODEL_VARIANT={cpu|gpu|auto} の切り替えがあります。

このプロジェクトではコード監査を実施しました。各問題について、修正箇所または 保留した理由は AUDIT_STATUS.md に記載されています。 CHANGELOG.md には 1.x 系の各リリースの履歴と v1.7 の候補セクションが 記載されています（1.0 より前のリリースについては CHANGELOG-ARCHIVE.md を参照してください）。 ROADMAP.md には、次のリリースに向けて確定している内容と、v3.0 の 時点でも候補にとどまる方針が記載されています。

プロジェクトの構成

src/
  cli.rs         command dispatch and output rendering
  storage.rs     Qdrant: single collection, hybrid search, history, stats, migrate, chunking
  embedder.rs    ONNX embedding (model-aware pooling, prefixes, 512-token cap)
  reranker.rs    cross-encoder reranking
  knowledge.rs   knowledge-graph facts + cardinality + supersession
  duel.rs        duel rule: resolve contradicting facts (flip / contested / quarantine)
  doubt.rs       doubt window + background active re-test of entrenched facts
  activity.rs    recent-query buffer, corpus mean (centering), origin-context store
  confidence.rs  per-fact confidence score (dependants / confirmations / signals)
  outcome.rs     typed external signals (test_passed, code_compiled, ...) into weight
  procedure.rs   procedural memory: learn / recall / outcome
  ingest.rs      auto-extract & ingest candidates
  relevance.rs   relevance gate (length, blacklists, decision markers, token novelty)
  retrieval_policy.rs  search-before-answer classifier
  provenance.rs  cited external snippets with mandatory source
  extractor.rs   optional local LLM extraction (off by default)
  consolidate.rs merge duplicates, report cold entries
  md_reconcile.rs md import as reconcile with "md wins"
  audit.rs       append-only audit log for memory/fact/procedure/skill
                 writes, updates, deletes and quarantine transitions (not
                 pinned blocks, kv, vault, or sessions yet)
  http_api.rs    loopback HTTP surface for multi-agent access
  viewer.rs      ephemeral local HTTP viewer (axum, static frontend baked in)
  pulse.rs       live graph pulses for the viewer
  session.rs     per-agent session files
  secrets.rs     secret-scrub on the write path
  vault.rs       encrypted secret vault (terminal only)
  mcp.rs         MCP server over stdio (hand-rolled JSON-RPC; warm in-process models)
  config.rs      configuration + install-mode profiles
  integrity.rs   pinned SHA-256 hashes for downloads
  util.rs        atomic writes, verified downloads
  (plus migrate, install-mode, access/decay, and bench harnesses)
tests/
  cli_integration.rs   black-box tests against a real Qdrant (CLI + MCP round-trip)
  http_integration.rs  the multi-agent HTTP surface end to end

ライセンス

Apache-2.0。詳細は LICENSE を参照してください。