MCP Light Memory

MCP Light Memory

コーディングエージェントや MCP クライアント向けの、軽量でローカルファーストな永続メモリです。
以前の名称は internal-rag

---

これは何ですか？

MCP Light Memory は、コーディングエージェントや MCP クライアント（Warp、OpenCode、JetBrains AI Assistant / PyCharm、Claude Code、Cursor）向けの、軽量でローカルファーストな永続メモリシステムです。チェックポイント＋検索レイヤーとして機能し、複雑な作業をセッションをまたいで再開するために必要な最小限の永続状態を保存します。会話全体をモデルのコンテキストウィンドウに保持する必要はありません。

エージェントがタスクを開始すると、context を呼び出し、過去の関連する決定事項、注意点、制約、仮説を取得します。結果は順位付けされ、重複が除去され、信頼境界が設定されます。タスクを終えると、作業状態がチェックポイントとして保存されます。次のセッションでは、再起動後でもメモリを利用できます。

なぜ使うのですか？

問題	MCP Light Memory による解決方法
エージェントがセッション間で内容をすべて忘れてしまう	Markdown ファイルをディスクに保存し、エージェントは BM25 と任意の埋め込みを使って内容を取得します
セッション履歴全体がコンテキストに収まらない	関連するメモリのみを取得します（トークン予算に合わせ、MMR で多様化）
クラウド依存やプライバシーへの懸念	100％ローカルでオフライン動作し、ネットワーク呼び出しもデーモンもありません
セットアップや依存関係が重い	必須の実行時依存関係はありません（Python 3.8 以降の標準ライブラリのみ）。意味検索を強化する場合は sentence-transformers を任意で利用できます
保存されたメモリを介したプロンプトインジェクション	取得したメモリはすべて、インジェクション警告ヒューリスティック（ADR-015）を備えた trust: untrusted の証拠として明示されます
複数プロジェクトの分離	レジストリの許可リスト、write:false の強制境界、呼び出しごとのサブプロセス分離を備えたルーターを提供します
MCP プロトコルの変遷	新しい 2026-07-28 とレガシーな 2024-11-05…2025-11-25 の両方をサポートします

仕組み（メカニズム）

• Markdown が信頼できる唯一の情報源です。 すべてのメモリは YAML フロントマター（id、type、status、tags、sources、links、valid_from、valid_to、supersedes）を含む .md ファイルです。人が読みやすく、差分を確認でき、永続性があります。
• SQLite は再構築可能なキャッシュです。 BM25/FTS5 インデックス、任意の埋め込みベクトル、使用状況の追跡を格納します。削除しても、すべて Markdown から再構築されます。
• 検索： 純粋な Python による BM25 と任意の密ベクトル埋め込み → RRF 融合 → MMR による多様化 → ポリシーによるブースト（種別／ステータス／時間） → トークン予算に応じた切り詰め。適応モードでは、まず疎検索を行い、結果が弱い場合のみ密検索を行います。
• ライフサイクル： remember → update → supersede（双方向にリンクし、履歴は削除しません）→ forget（アーカイブし、削除はしません）→ timeline（時間軸表示）。過去の状態を検索するには search --at YYYY-MM-DD を使用します。
• 信頼境界： 取得した内容は === BEGIN/END INTERNAL_RAG MEMORY === で囲み、SECURITY NOTICE ヘッダーを付けます。構造化 JSON/MCP では trust: untrusted と、任意の security_flags: ["instruction_like_content"] を付加します。
• 証拠の鮮度： 各結果には、ローカルパス形式の証拠について evidence_state（present／missing／unverifiable）が含まれます。これは取得時に導出され、永続化されません。
• 複数プロジェクト対応ルーター： JSON レジストリを介して、多数のプロジェクトの前段に単一の MCP stdio サーバーを配置します。write:false は子プロセスの起動前に変更を伴うツールをブロックします。呼び出しごとにサブプロセスを分離するため、共有状態はありません。

セットアップ

前提条件

• Python 3.8+（py ランチャー、python、または python3 を使用します。インストーラーは実際のインタープリターを自動検出し、WindowsApps のスタブを拒否します）
• Git（対象のプロジェクトは git リポジトリである必要があります）
• 任意：セマンティック検索の精度を高めるには、pip install sentence-transformers numpy を実行します

現在のバージョンは VERSION ファイルで定義されています。想定される番号をハードコードするのではなく、このファイルを確認するか、mlm.py --version を実行してください。

クイックスタート

このリポジトリを一度クローンし、その後、任意のプロジェクトにインストールします。

# Windows (PowerShell)
git clone https://github.com/PeterPirog/mcp-light-memory.git ~/mcp-light-memory
python ~/mcp-light-memory/install.py . --client warp

# Linux/macOS
git clone https://github.com/PeterPirog/mcp-light-memory.git ~/mcp-light-memory
python3 ~/mcp-light-memory/install.py . --client warp

インストーラーは次の処理を行います。

• スキルファイルをコピーし、INTERNAL_RAG/ と AGENTS.md を作成します
• init + checkpoint + validate を実行します（これにより、直ちに guard が OK になります）
• 安全に実行できる場合は、クライアントの設定に MCP サーバーを自動登録します（それ以外の場合は MANUAL_REQUIRED を報告するか、JetBrains の手順を表示します）
• 検証済み Python インタープリターの絶対パスを書き込みます（Windows の PATH に関する問題の影響を受けません）

python .agents\skills\internal-rag\mlm.py --version   # reports the installed version
python .agents\skills\internal-rag\mlm.py status       # expect: INTERNAL_RAG ready
python .agents\skills\internal-rag\mlm.py guard        # expect: GUARD OK

インストール対応表

インストーラーは1つ、クライアントは4つ、設定スコープは2つです。詳しいガイド：docs/INSTALLATION.md。

クライアント	プロジェクトスコープ	グローバルスコープ
Warp（設定の書き込みは自動。プロジェクトの有効化には承認が必要な場合があります）	install.py . --client warp	install.py . --client warp --global
OpenCode stable (V1)（安全な JSON 設定の書き込みは自動）	install.py . --client opencode	install.py . --client opencode --global
OpenCode 2 (V2, beta)（安全な JSON 設定の書き込みは自動）	install.py . --client opencode2	install.py . --client opencode2 --global
JetBrains AI / PyCharm（IDE の UI で手動設定）	install.py . --client jetbrains	install.py . --client jetbrains --global

• --global はクライアント設定のスコープを変更します（~/.warp/.mcp.json と {repo}/.warp/.mcp.json、~/.config/opencode/opencode.json とプロジェクトの opencode.json の切り替え）。サーバーが参照するのは、インストール先の対象プロジェクトです。
• 複数のリポジトリで1つのグローバル MCP エンドポイントを使う場合は、マルチプロジェクトルーターを使用してください。docs/MCP-MULTI-PROJECT.md。
• JetBrains/PyCharm は完全自動ではなく、設定を支援します。インストーラーが JSON と作業ディレクトリを準備します。Settings → Tools → AI Assistant → MCP でサーバーを追加し、Server level = Project または Global を選択してください。
• インストーラーを使わずにクライアントごとに手動で設定する方法：docs/INSTALLATION.md とクライアント別ページ（Warp · OpenCode）。

ゼロショット：Warp と OpenCode 用のコピー＆ペーストプロンプト

以下のプロンプトをクライアントのエージェントに直接貼り付けられます。C:\Projects\App は実際の対象リポジトリのパスに置き換えてください。

Warp — 1つのプロジェクトにインストール：

Install and configure MCP Light Memory (mcp-light-memory) as an MCP server for project C:\Projects\App in Warp, using project scope. Use the repository https://github.com/PeterPirog/mcp-light-memory. If the tool is not cloned yet, clone it to a stable location outside the project; if it already exists, update it with git pull --ff-only. Apply the canonical installation contract from the repository and run install.py with TARGET_PROJECT=C:\Projects\App and --client warp without --global. Do not force-overwrite an existing configuration. After installation, verify from cwd=C:\Projects\App: mlm.py --version, mlm.py status, and mlm.py guard, and confirm that the Warp configuration contains mcp-light-memory and the C:\Projects\App path. Report success only after MCP REGISTRATION: REGISTERED and successful verification. If Warp requires an additional project activation/toggle/approval, state the exact client-side step and do not claim the server is active before it is completed.

Warp — 1つのプロジェクト用のグローバルクライアント設定：

Install and configure MCP Light Memory (mcp-light-memory) in Warp globally for project C:\Projects\App. Use the repository https://github.com/PeterPirog/mcp-light-memory. If the tool is not cloned yet, clone it to a stable location outside the project; if it already exists, run git pull --ff-only. Apply the canonical installation contract and run install.py with TARGET_PROJECT=C:\Projects\App, --client warp, and --global. Remember: --global means the global Warp client configuration, while the server must still be bound to C:\Projects\App; do not use the multi-project router. After installation, verify from cwd=C:\Projects\App: mlm.py --version, mlm.py status, and mlm.py guard, and confirm that the global Warp configuration contains mcp-light-memory and the C:\Projects\App path. Report success only after MCP REGISTRATION: REGISTERED and successful verification.

OpenCode — 1つのプロジェクトにインストール（stable/V1）：

Install and configure MCP Light Memory (mcp-light-memory) as an MCP server for project C:\Projects\App in OpenCode. By "OpenCode" I mean stable/V1, so use --client opencode, not opencode2. Use the repository https://github.com/PeterPirog/mcp-light-memory. If the tool is not cloned yet, clone it to a stable location outside the project; if it already exists, run git pull --ff-only. Run install.py with TARGET_PROJECT=C:\Projects\App and --client opencode without --global. Do not force-overwrite an existing configuration. If the installer returns MCP REGISTRATION: MANUAL_REQUIRED (for example because opencode.jsonc exists), do not report success: safely edit the JSONC while preserving comments and unrelated settings if you have appropriate file-editing tools; otherwise report the exact manual action required. After real registration, verify from cwd=C:\Projects\App: mlm.py --version, mlm.py status, and mlm.py guard, and confirm that the OpenCode configuration contains mcp-light-memory and C:\Projects\App.

OpenCode — 1つのプロジェクト用のグローバルクライアント設定（stable/V1）：

Install and configure MCP Light Memory (mcp-light-memory) globally in OpenCode for project C:\Projects\App. By "OpenCode" I mean stable/V1, so use --client opencode. Use the repository https://github.com/PeterPirog/mcp-light-memory. If the tool is not cloned yet, clone it to a stable location outside the project; if it already exists, run git pull --ff-only. Run install.py with TARGET_PROJECT=C:\Projects\App, --client opencode, and --global. --global means the global OpenCode client configuration, while the server must still be bound only to C:\Projects\App; do not use the multi-project router. If the installer returns MCP REGISTRATION: MANUAL_REQUIRED, do not report success and follow the safe JSONC instructions. After real registration, verify from cwd=C:\Projects\App: mlm.py --version, mlm.py status, and mlm.py guard, and confirm that the global OpenCode configuration contains mcp-light-memory and the C:\Projects\App path.

OpenCode 2 / V2 では、同じプロンプトを使い、OpenCode 2 / V2 と明記したうえで --client opencode2 を指定してください。その他のバリエーション：docs/ZERO-SHOT-SETUP-PROMPTS.md。

---

設定の詳細

Warp

Warp は MCP サーバー設定を ~/.warp/.mcp.json（グローバル、自動起動）または {repo}/.warp/.mcp.json（プロジェクト単位、Warp のドキュメントに従って手動で切り替える必要があります）から読み込みます。 形式は mcpServers.<name> の下に command、args、working_directory を設定します（必ず設定してください。メモリストアはここを基準に解決されます）。examples/warp.example.json と docs/WARP-SETUP.md を参照してください。

OpenCode stable (V1)

OpenCode はプロジェクトのルートにある opencode.json/.jsonc、または グローバル設定の ~/.config/opencode/opencode.json を読み込みます。V1 のサーバーは mcp.<name> の直下に置きます（servers サブキーはありません）。enabled: true を指定し、command は 配列にします。examples/opencode-legacy.example.json と docs/OPENCODE.md を参照してください。

OpenCode 2（V2、ベータ版）

設定ファイルは同じですが、形式が異なります。mcp.servers.<name> を使用し、command は配列で指定します。また、enabled フィールドはありません（V2 では disabled: true で無効化します）。examples/opencode-v2.example.jsonc と docs/OPENCODE.md を参照してください。

JetBrains AI Assistant / PyCharm

PyCharm は MCP 設定ファイルを自動的には読み込みません。インストーラーが、貼り付け用の JSON と作業ディレクトリを出力します。Settings → Tools → AI Assistant → MCP (STDIO) でサーバーを追加し、Server level = Project or Global を選択してください。examples/jetbrains.example.json を参照してください。

---

マルチプロジェクトルーター

複数のプロジェクトの前段に置く 1 つの MCP 接続です。レジストリの許可リスト、write:false による厳格な境界、呼び出しごとのサブプロセス分離を備えています。

レジストリファイル（projects.json）

{
  "projects": {
    "backend": { "root": "/abs/path/backend", "write": true },
    "shared-lib": { "root": "/abs/path/shared-lib", "write": false }
  }
}

ルーター用の Warp 設定

{
  "mcpServers": {
    "mcp-light-memory-router": {
      "command": "python3",
      "args": ["/abs/path/mcp-light-memory/.agents/skills/internal-rag/irag_mcp_router.py", "--registry", "/abs/path/projects.json"],
      "working_directory": "/abs/path/mcp-light-memory"
    }
  }
}

詳細は docs/MCP-MULTI-PROJECT.md を参照してください。

---

ワークフロー

context --task "current task"
  ↓
recovery, if required (RECOVERY REQUIRED)
  ↓
checkpoint before first change
  ↓
implementation
  ↓
checkpoint after each milestone
  ↓
guard before finishing

主なコマンド（CLI エイリアス：mlm.py または従来の irag.py）：

mlm.py context --task "..."
mlm.py checkpoint --reason "..."
mlm.py search --query "..." --limit 8
mlm.py remember --type decision --title "..." --body "..."
mlm.py show <ref>
mlm.py update <ref> --status superseded
mlm.py status
mlm.py guard
mlm.py validate
mlm.py doctor

パスの対応関係（名称変更：internal-rag → MCP Light Memory）

新しい名前	従来のパス（互換性のため維持）
MCP Light Memory（製品）	internal-rag（非推奨の製品名）
mlm / mlm.py（主な CLI）	irag.py（従来のエイリアス。引き続き動作します）
mcp-light-memory（MCP サーバー名）	internal-rag（従来の名前。設定内でも引き続き使用できます）
mcp-light-memory-router（ルーター名）	internal-rag-router（従来の名前）
INTERNAL_RAG/（ストレージフォルダー。変更なし）	—
.agents/skills/internal-rag/（スキルディレクトリ。変更なし）	—

ディスク上のフォルダー INTERNAL_RAG/ とスキルディレクトリ .agents/skills/internal-rag/ は、移行不要の後方互換性を保つため、意図的に従来の名前のままにしています。docs/MIGRATION-TO-MCP-LIGHT-MEMORY.md を参照してください。

永続メモリ（CRUD）

remember --type decision --title "..." --body "..." --tags "a,b" --evidence "src/x.py:42" --links "decisions/other.md"
show <path-or-id>
show <ref> --section Knowledge
update <ref> --add-tags "new" --append "New evidence: ..."
supersede <ref> --by <new> --reason "..."
forget <ref>              # archives, does not delete
link --from <ref> --to <ref>
timeline --limit 20
status
history

種類：decision、knowledge、constraint、gotcha、failure、hypothesis、session。

タスクスタック（割り込み）

mlm.py push --task "interrupted work" --reason "user-priority"
mlm.py tasks
mlm.py resume
mlm.py forget-task <id>   # drop a specific task
mlm.py forget-task         # clear the whole stack

設定（.irag.yml、任意）

retrieval:
  limit: 10
  mmr_lambda: 0.4
  min_score: 0.3
  embeddings: auto        # auto | on | off
  profile: english-fast   # english-fast (default) | multilingual (PL/EN projects)
  embeddings_model: null  # explicit model overrides the profile
tokens:
  context_budget: 5000
checkpoints:
  auto_archive_sessions: true
  max_task_stack: 24

mlm.py config で有効な設定を確認できます。mlm.py config --init でテンプレートを書き込みます。

任意の埋め込み（検索精度の向上）

pip install -r requirements-optional.txt

パッケージが利用可能で、.irag.yml の embeddings: auto（デフォルト）が設定されている場合、検索では埋め込みを使用し、利用できない場合は BM25 にフォールバックします。実行時には --embeddings on|off|auto で上書きできます。

検索プロファイルは 2 種類あります（docs/EMBEDDINGS.md を参照）。

• english-fast（デフォルト、all-MiniLM-L6-v2）
• multilingual（intfloat/multilingual-e5-small）— ポーランド語と英語を使うプロジェクト向け

オフライン／エアギャップ環境

python pack.py --with-embeddings --profile english-fast
# -> internal-rag-offline-1.8.1.zip   (name from pack.py; 1.8.1 = VERSION file)
# On the air-gapped machine:
unzip internal-rag-offline-*.zip -d internal-rag-offline
pip install --no-index --find-links wheels/ -r requirements-optional.txt
python install.py "/path/to/project" --client <warp|opencode|opencode2|jetbrains>

詳細は docs/OFFLINE.md を参照してください。

プライバシーと Git

デフォルトのインストールモードはローカルのみです。インストーラーはプロジェクトの .gitignore ではなく .git/info/exclude を使用するため、ローカルメモリや統合ファイルが誤ってコミットされることはありません。

プロジェクトを公開する前に：

python .\privacy_check.py "D:\path\to\project"

期待される結果：RESULT: PASS

プロジェクトからの完全な削除

python .\uninstall.py "D:\path\to\project"

アンインストーラーはリポジトリ外にバックアップを作成してから、INTERNAL_RAG とその統合設定を削除します。メモリデータを保持するには --keep-memory を使用してください。

ドキュメント

• インストール · 日常の使い方 · CLI リファレンス
• アーキテクチャ · メモリのライフサイクル · 復旧
• MCP · マルチプロジェクト MCP
• アーキテクチャ決定記録（ADR） · 設定
• 埋め込み · オフライン · Git フック
• プライバシーと Git · アンインストール · トラブルシューティング
• ゼロショットセットアップ用プロンプト · 移行 · ブランディング

対象プロジェクト内の構成

project/
├── AGENTS.md
├── .irag.yml                    # optional config
├── INTERNAL_RAG/
│   ├── WORKING_STATE.md
│   ├── INDEX.md
│   ├── .checkpoint.json
│   ├── decisions/  knowledge/  gotchas/  failures/  hypotheses/  sessions/  archive/
│   └── exports/
├── .agents/skills/internal-rag/
│   ├── SKILL.md
│   ├── mlm.py                   # primary CLI (forwards to irag.py)
│   ├── irag.py                  # core (legacy alias, still the canonical module)
│   ├── irag_embeddings.py       # optional plugin
│   └── irag_hooks.py            # optional git hooks
└── .opencode/                   # OpenCode integration (optional)

情報源の優先順位

1. 現在のユーザー指示、2. 現在のコード／テスト／設定、3. 仕様／ADR、4. 検証済みの記憶、5. セッションメモ、6. 仮説。

記憶は古くなっている場合があります。コードを優先してください。

ライセンス

MIT。

---

変更履歴

1.8.0 — JetBrains の手動セットアップ

• --client jetbrains は、偽の設定ファイルを書き込まなくなりました（PyCharm は MCP 設定ファイルを無視します）。代わりに、そのまま貼り付けられる JSON と IDE メニューの手順を表示します。
• --unregister --client jetbrains は、IDE の UI で削除するよう促すリマインダーを表示します。

1.7.2 — JetBrains の cwd とクライアント固有のメッセージ

• JetBrains：working_directory をヒントとして書き込み、Settings → Tools → AI Assistant → MCP で設定する正確なパスを示す WARNING を表示します。
• クライアント固有の再起動メッセージを表示します（Restart PyCharm / Restart Warp / Restart OpenCode）。
• すぐに確認できるよう、インストール出力に Memory store: <path> を表示します。

1.7.1 — Windows の Python スタブ修正

• detect_python() は WindowsApps の 0 バイトのスタブを除外し、py -0p を優先します。各候補を --version で検証します。
• 登録後の検証：設定を書き込んだ直後に --version を実行し、PASS／FAIL を報告します。
• --unregister は空の設定ファイルと親ディレクトリを削除します（孤立した .warp/.mcp.json の骨組みが GUARD STALE となる問題を修正）。

1.7.0 — MCP Light Memory へのリブランド

• internal-rag から MCP Light Memory（mcp-light-memory）へ全面的にリブランドしました。新しい CLI エイリアス mlm（mlm.py）。ロゴ／アイコン素材。移行ドキュメント。GitHub リブランドチェックリスト。
• 後方互換性：irag.py、INTERNAL_RAG/、旧 MCP サーバー名は非推奨エイリアスとして維持されます。
• リブランドの一貫性を確認するテストを 18 件追加しました。

1.6.1 — v1.6 後の堅牢化

• ミューテーション／ライフサイクルのベンチマーク（11 シナリオ）。信頼境界（ADR-015）：trust: untrusted ＋ security_flags。エビデンスの鮮度（ADR-016）：evidence_state。スケールベンチマーク（100／1k／10k）。ルーターのセキュリティ回帰テスト（＋12 件）。ドキュメントの一貫性テスト。249 件のテストが成功します。

1.6.0 — 検索品質の向上 ＋ MCP 2026-07-28

• メモリー品質ベンチマーク（37 ケース）。MCP 2026-07-28 の新旧両方式に対応（server/discover、_meta、structuredContent、outputSchema）。レジストリの厳格な write。チャンクのプレフィックスにソースを追加。適応型検索。リンクを考慮したコンテキスト。consolidate --prepare。ルーターのレイテンシベンチマーク。ADR-010…016。

1.5.0 — 棄却ゲート ＋ マルチプロジェクトルーター

• 関連性／棄却ゲート（--meta）。FTS5 候補の事前フィルタリング。マルチプロジェクト MCP ルーター。MCP プロトコルの堅牢化（標準出力のみ、SDK で検証済み）。168 件のテスト。

1.4.0 — チャンク分割 ＋ 重複排除 ＋ 時系列ライフサイクル

• セクションを考慮したチャンク分割（スキーマ v3）。SimHash による重複排除。多言語 PL／EN プロファイル。時系列ライフサイクル（valid_from／valid_to／supersedes／--at）。consolidate --dry-run。

1.3.0 — 永続的な埋め込みキャッシュ

• SQLite にチャンク単位の float32 BLOB を保存。複数モデルの共存に対応。index --vacuum／--embed-missing。

1.0.2 — トークン予算 ＋ プライバシー

• トークン予算の適用。古いメモリーの検出。重複の検出。書き込み時のプライバシースキャン。自動チェックポイントタイマー。オフライン／エアギャップ環境用パック。

1.0.0 — 初回リリース

• BM25 ＋ MMR 検索。メモリーの CRUD 全対応。タスクスタック。MCP サーバー（JSON-RPC stdio）。Git フック。診断。エクスポート／インポート。トークン予算。