MemPalace のデプロイ＆実戦：忘れない AI の記憶システムを作る

中級者向け · 約 20 分 · MemPalace の完全なデプロイ手順を身につけ、Palace の階層構造を理解し、MCP を使って任意の AI に記憶システムを接続する方法を学びます。

---

対象読者

1〜3 年の開発経験があり、Claude Code / Cursor / Copilot などの AI コーディングツールをすでに使っている方。AI が長期プロジェクトでも文脈の記憶を維持し、毎回ゼロから始める必要がなくなるようにしたい方。

---

必須の依存関係と環境

• Python：3.9+
• コア依存関係：chromadb>=0.5.0,<0.7、pyyaml>=6.0
• インストール方法：pip install mempalace または uv pip install mempalace
• OS：macOS / Linux / Windows（WSL でも可）
• ストレージ：ChromaDB（ベクトルDB）+ SQLite（ナレッジグラフ）。すべてローカル保存で、ネットワーク不要

---

完全なプロジェクト構造

mempalace/
├── mempalace/                 # コア Python パッケージ
│   ├── cli.py                 # CLI エントリーポイント。mine/search/init などへルーティング
│   ├── mcp_server.py          # MCP サーバー。19 個のツールを公開
│   ├── knowledge_graph.py     # 時系列ナレッジグラフ（SQLite）
│   ├── palace_graph.py        # Palace ナビゲーション図（BFS 探索、トンネル発見）
│   ├── convo_miner.py         # 対話マイニング。Q&A ごとに分割
│   ├── miner.py               # プロジェクトファイルのマイニング。段落で分割
│   ├── searcher.py            # セマンティック検索（ChromaDB）
│   ├── normalize.py           # 5 種類の対話形式を標準化
│   ├── dialect.py             # AAAK 圧縮方言
│   ├── layers.py              # 4 層の記憶スタック（L0-L3）
│   ├── onboarding.py          # 初期化ガイド
│   ├── entity_detector.py     # 人名/プロジェクト名を自動検出
│   └── split_mega_files.py    # 分割・統合する会話ファイル
├── hooks/                     # Claude Code の自動保存フック
│   ├── mempal_save_hook.sh     # 15 メッセージごとに自動保存
│   └── mempal_precompact_hook.sh  # コンテキスト圧縮の直前に緊急保存
├── benchmarks/               # 再現可能なベンチマーク（LongMemEval / LoCoMo）
│   ├── longmemeval_bench.py
│   ├── locomo_bench.py
│   └── BENCHMARKS.md
└── examples/
    ├── basic_mining.py
    └── mcp_setup.md

---

手順を一つずつ

Step 1：インストール

pip install mempalace

最小 Python バージョンは 3.9 です。インストール後に利用できることを確認：

mempalace --version

---

Step 2：記憶の宮殿を初期化

mempalace init ~/projects/myapp

init コマンドはガイド手順を起動し、順番に次を尋ねます：

• よく一緒に協力する相手（wing 設定に追加）
• 作業しているプロジェクト（プロジェクトごとに wing）
• AI としてのあなたのアイデンティティ（L0 層へ書き込み）

ガイドが完了すると、2 つの設定ファイルが生成されます：

• ~/.mempalace/config.json — グローバル設定（palace のパスなど）
• ~/.mempalace/wing_config.json — wing とキーワードのマッピング

生成される wing_config.json は概ね次のようになります：

{
  "default_wing": "wing_general",
  "wings": {
    "wing_kai": { "type": "person", "keywords": ["kai", "kai's"] },
    "wing_driftwood": { "type": "project", "keywords": ["driftwood", "analytics", "saas"] }
  }
}

AI を起動するたびに L0 + L1（約 170 tokens）を読み込むだけで、あなたの世界がどんな構造になっているかが分かります。

---

Step 3：データをマイニングする

MemPalace はデータソースに応じて、2 つのマイニングモードをサポートしています。

モード A：プロジェクトファイルをマイニング（コード、ドキュメント、ノート）

mempalace mine ~/projects/myapp

miner がディレクトリを再帰的にスキャンし、段落で分割して ChromaDB に保存し、Drawer には元の内容を格納します。

モード B：対話のエクスポートをマイニング（Claude/ChatGPT/Slack）

# 基本的な使い方
mempalace mine ~/chats/ --mode convos

# wing を指定しておく（後でプロジェクトで絞り込みやすくする）
mempalace mine ~/chats/ --mode convos --wing myapp

# 自動分類を有効化（意思決定、嗜好、マイルストーン、問題、感情の文脈）
mempalace mine ~/chats/ --mode convos --extract general

convo_miner は Q&A ごとに対話を分割し、room の所属を自動検出します（room_detector_local.py の 70+ モード照合を使用。API は不要）。

---

Step 4：セマンティック検索で検証

マイニングが完了したら、試しに検索してみましょう：

mempalace search "why did we switch to GraphQL"

wing フィルタを追加して、特定のプロジェクト内だけを検索：

mempalace search "auth decision" --wing driftwood

さらに精密にするには room フィルタも追加：

mempalace search "auth decision" --wing driftwood --room auth-migration

返ってくるのは Drawer 内の原文（verbatim）で、要約はなく情報損失もありません。ChromaDB はベクトル検索を行い、Closet は構造化要約を返します。

---

Step 5：MCP サービスを接続する

MCP（Model Context Protocol）によって、MemPalace を任意の AI のツールとして公開できます。1 回の設定で永続的に有効になります。

Claude Code への接続：

claude mcp add mempalace -- python -m mempalace.mcp_server

設定が完了すると、Claude Code は自動的に 19 個のツールを利用可能にし、AI は必要に応じて自分で mempalace_search を呼び出します。あなたが手作業で検索する必要はありません。

Gemini CLI への接続：

# 参考：examples/gemini_cli_setup.md
claude mcp add mempalace -- python -m mempalace.mcp_server

Gemini CLI は MCP のサポートがより充実しており、save hooks も自動設定できます。

MCP ツール一覧（19 個）：

AI は mempalace_status の返答から自動的に AAAK の文法と記憶プロトコルを学び、あなたが prompt を手動設定する必要はありません。

---

Step 6：Claude Code の Auto-Save Hooks を設定する

Claude Code の Hooks を使うと、MemPalace が会話のたびに自動で記憶を保存できます。

~/.claude/settings.json（Claude Code のグローバル設定）を編集し、次を追加：

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/mempalace/hooks/mempal_save_hook.sh"
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/mempalace/hooks/mempal_precompact_hook.sh"
          }
        ]
      }
    ]
  }
}

2 つのフックの違い：

• Stop：15 メッセージごとに 1 回発火し、構造化保存――テーマ、意思決定、引用、コード変更までをすべて記録し、同時に L1 層（重要な事実層）を再構築します。
• PreCompact：コンテキスト圧縮の前に発火。圧縮中に重要なコンテキストが失われるのを避けるため、まだ保存されていない記憶を緊急で救出します。

---

Step 7：Palace の構造を理解する

MemPalace の中核となる抽象は「記憶の宮殿（メモリー・パレス）」です。古代ギリシャの演説家の記憶術を参考にし、空間構造でフラットな検索インデックスを置き換えます。

  WING: kai (person)

    ┌──────────┐  ──hall──  ┌──────────┐
    │ auth-mig │            │ security  │
    └────┬─────┘            └──────────┘
         │
         ▼
    ┌──────────┐      ┌──────────┐
    │  Closet  │ ───▶ │  Drawer  │  ← 原文はここにある
    └──────────┘      └──────────┘

  TUNNEL（wing 間の接続）:
  kai/auth-mig  ←→  driftwood/auth-mig  ←→  priya/auth-mig

Wings：1 人、または 1 つのプロジェクト。記憶の主な分類先です。各 wing の下に複数の rooms を置けます。

Rooms：wing 内の具体的なテーマ。例：auth-migration、ci-pipeline、pricing。同名の room が別 wing に存在する場合、自動的に tunnel を生成します。

Halls：記憶タイプの回廊。各 wing には同じ hall の集合が用意されます：

• hall_facts — 固定された意思決定
• hall_events — 会話、マイルストーン、デバッグの過程
• hall_discoveries — ブレイクスルーと新しい洞察
• hall_preferences — 習慣、好み、意見
• hall_advice — 推奨と解決策

Closets：要約層。原文が置かれている場所（Drawer）を指します。原文は失われず、ナビゲート可能な構造が 1 層追加されるだけです。

Drawers：原文の保管場所。MemPalace の raw verbatim モードはここから原文を読み取り、ベクトル検索を行うことで 96.6% R@5 を達成しています。

---

Step 8：Knowledge Graph の時系列関係を使う

ChromaDB に保存されるのは原文のベクトルで、Knowledge Graph（SQLite）に保存されるのは構造化された事実トリプルです。両者は補完関係にあります。

from mempalace.knowledge_graph import KnowledgeGraph

kg = KnowledgeGraph()

# 事実を追加（有効期限つき）
kg.add_triple("Kai", "works_on", "Orion", valid_from="2025-06-01")
kg.add_triple("Maya", "assigned_to", "auth-migration", valid_from="2026-01-15")
kg.add_triple("Maya", "completed", "auth-migration", valid_from="2026-02-01")

# Kai は現在何をしているか
print(kg.query_entity("Kai"))
# → [Kai → works_on → Orion (current)]

# 2026-01-20 の時点での状況（この時点では Maya は auth-migration をまだ完了していない）
print(kg.query_entity("Maya", as_of="2026-01-20"))
# → [Maya → assigned_to → auth-migration]

# Orion プロジェクトのタイムライン
print(kg.timeline("Orion"))
# → 時系列順に並べた事実のチェーン

# Maya がプロジェクトを変更したので、古い事実を無効化
kg.invalidate("Maya", "assigned_to", "auth-migration", ended="2026-02-01")
# これで query_entity("Maya") は auth-migration を返さない

Facts の有効期間の窓（valid_from / ended）は MemPalace の中核機能です。履歴状態を問い合わせるときに「当時何が起きたか」を教えてくれ、「今何が起きているか」を見せるのではありません。

---

Step 9：記憶スタックの 4 層アーキテクチャ

MemPalace の検索戦略は 4 層で構成され、上に行くほど軽量、下に行くほど精密です：

AI の起動のたびに、まず L0 + L1（mempalace wake-up）を読み込みます。170 tokens で完全なコンテキストの背景が構築されます。話題が特定の room をトリガーしたときだけ L2 を読み込み、明示的に質問したときだけ L3 の全量 ChromaDB 検索が実行されます。

これが MemPalace のコストが非常に低い理由です――$10/年の検索コストに対して、$507/年の要約ソリューション。

---

よくある問題の切り分け

Q1：検索結果が空だが、内容が存在しているはず

次の 3 ステップで確認：

# 1. wing と room 名が正しいことを確認
mempalace list-wings
mempalace list-rooms --wing myapp

# 2. 対象範囲を広げる（wing/room を指定せず全体検索）
mempalace search "キーワード"   # --wing を付けない

# 3. ChromaDB に本当に書き込まれているか確認
mempalace status            # drawer 総数が 0 かどうかを見る

mempalace status が 0 の drawer を示す場合、マイニング手順が成功していない可能性があります。対話ファイルの形式が対応されていないことが考えられます（現在対応：Claude Code JSONL、Claude.ai JSON、ChatGPT JSON、Slack JSON、plain text）。

Q2：ChromaDB のコレクション名の衝突

デフォルトのコレクション名は mempalace_drawers です。複数回 init したり、別ディレクトリで実行したりすると衝突する可能性があります。~/.mempalace/config.json でパスを明示的に指定してください：

{
  "palace_path": "/custom/path/to/palace",
  "collection_name": "mempalace_drawers"
}

その後、--palace <path> で上書き：

mempalace search "query" --palace /custom/path/to/palace

Q3：MCP 接続に失敗する

まず MCP サービスが正しく起動できるか手動で検証：

python -m mempalace.mcp_server
# 通常は何も出力されず、前面（フォアグラウンド）で待機する
# Ctrl+C で終了

ModuleNotFoundError が出る場合は、正しくインストールされているか確認：

pip show mempalace

仮想環境を使っている場合は、Claude Code の MCP 設定に記載された Python パスが正しいことを確認してください：

which python   # 正しい python パスを取得
claude mcp add mempalace -- /path/to/python -m mempalace.mcp_server

Q4：MCP ツールの呼び出しは正常だが結果が期待と違う

AI が mempalace_search を呼び出すとき、wing/room パラメータは Palace 構造の最大効果を得るために正確に一致している必要があります。prompt で AI に適切なフィルタを使わせてください：

When searching for project-specific memories, always pass --wing <project>.
When searching for a specific topic, always pass --room <room-name>.

Q5：Hook スクリプトが発火しない

# Claude Code の hooks が有効になっているか確認
claude doctor

settings.json の hooks パスが絶対パスになっていることを確認してください。相対パスは Claude Code の作業ディレクトリによって解釈が失敗する場合があります。

Q6：ナレッジグラフの時系列クエリが意図しない結果を返す

時系列クエリは as_of パラメータの形式に依存します。日付は YYYY-MM-DD 形式である必要があります：

# 誤った形式
kg.query_entity("Kai", as_of="2026/03/01")

# 正しい形式
kg.query_entity("Kai", as_of="2026-03-01")

また、事実を add_triple で追加するときに valid_from も正しい形式になっているか確認してください。そうでない場合、時系列ウィンドウが有効になりません。

---

追加の読み物 / 進む方向

AAAK の実験的な圧縮層

AAAK は損失型の圧縮方言で、正規表現による置換で重複するエンティティをコードに圧縮します。大規模（同一プロジェクトが数百回言及される）なケースでは token コストを節約できますが、現時点では raw verbatim モード（96.6%）のほうが AAAK モード（84.2%）より優れています。適用先は、長時間にわたる多会話で、重複エンティティが密なプロジェクトです。

Specialist Agents：複数 Agent の記憶隔離

各 Agent には独立した wing と AAAK 日記があります：

~/.mempalace/agents/
  ├── reviewer.json    # コード品質、パターン、バグ
  ├── architect.json   # アーキテクチャの意思決定、トレードオフ
  └── ops.json         # デプロイ、障害、基盤インフラ

AI は palace 実行時に動的に agent を発見するため、CLAUDE.md に何かを設定を書く必要はありません。

ベンチマークの再現

benchmarks/ ディレクトリに、LongMemEval と LoCoMo の再現スクリプト一式があります：

python benchmarks/longmemeval_bench.py

全工程で API key は不要です。M2 Ultra 上で 5 分以内に 500 問を実行し、96.6% の再現性を検証します。

他システムとの横断比較

MemPalace は、ゼロの API 呼び出しで最高得点に到達した唯一のソリューションです。