---
title: "MIRIXとは？6種類のメモリで動くLLMエージェント記憶システムの仕組み・導入手順・グラフメモリ"
url: "https://www.issoh.co.jp/tech/details/10751/"
published: 2026-01-27
updated: 2026-11-11
categories: ["AIエージェント・MCP"]
publisher: "株式会社一創"
---

# MIRIXとは？6種類のメモリで動くLLMエージェント記憶システムの仕組み・導入手順・グラフメモリ

MIRIX（Multi-Agent Memory System for LLM-Based Agents）は、LLMエージェントに長期記憶を持たせるための記憶システムです。2025年7月に[arXivのMIRIX論文（2507.07957）](https://arxiv.org/abs/2507.07957)が公開され、同じチームが[GitHubの公式リポジトリ Mirix-AI/MIRIX](https://github.com/Mirix-AI/MIRIX)でApache-2.0のOSSとして実装を公開しています。記憶を6種類に分け、種類ごとに専任のエージェントが書き込みと検索を受け持つ点が、1つのベクトルストアに事実を積む方式との違いです。

この記事では、論文の設計とベンチマークの数字を表のまま読み直し、そのうえで現行版の導入手順を扱います。MIRIXは2025年12月のv0.1.6でデスクトップアプリから「メモリAPI」へ方針を変え、2026年11月7〜9日にはmainにグラフメモリ（Neo4j）とAPI認証の強化が入り、同じ9日にその評価をまとめた後続論文MIRIX-2.0も公開されました。READMEどおりに進めると詰まる箇所は、リポジトリとPyPIの実物で確かめています。数値と版は2026年11月11日時点のものです。

## まとめ：MIRIXの要点と現行版の状況

- **中身**：Core・Episodic・Semantic・Procedural・Resource・Knowledge Vaultの6メモリを、6つのMemory Managerと1つのMeta Memory Managerが分担して管理します（論文ではChat Agentを加えて計8エージェント）。
- **検索の特徴**：応答の前にエージェントが「トピック」を生成し、6メモリから各上位10件を自動で引いてシステムプロンプトに差し込みます（Active Retrieval）。ユーザーが「記憶を検索して」と指示する必要はありません。
- **ベンチマーク**：1本目の論文ではLOCOMOで85.38%（gpt-4.1-mini、LLM-as-a-Judge）。同条件のZepは79.09%、全文を入れるFull-Contextは87.52%で、Open Domainの設問だけはZepとLangMemを下回ります。2026年11月9日の後続論文MIRIX-2.0では、グラフとAutoDreamを加えた構成がLoCoMo 91.4%・LongMemEval-S 72.6%です（判定条件が違うため1本目とは比べられません）。
- **現行版**：Docker（PostgreSQL＋pgvector、Redis、APIサーバー）で動くメモリAPIです。2026年11月にmainへ、EpisodicとSemanticを超グラフで索引するグラフメモリ（既定はオフ）が入りました。PyPIの最新は `mirix` 0.1.7（2026-02-01）のままです。
- **導入時の注意**：2026年11月9日以降のmainは、`.env` に3つのシークレットを書かないと `docker compose up` が止まります。Docker Hubのサーバーイメージは2025年12月22日から更新されていません。READMEの `pip install mirix-client` はPyPIに無く失敗し、コード例は同期で書かれていますがmainのクライアントは非同期です。

## 論文・OSS・クラウドの3つの形態と公開の経緯

MIRIXという名前は、論文で提案された設計と、それを実装したOSS、運営元が提供するホスト型サービス（app.mirix.io）の3つを指します。論文の著者はYu Wang（UCSD）とXi Chen（NYU Stern）の2名で、所属表記はMIRIX AIです。READMEの謝辞には、メモリ部分の土台に[Letta](https://github.com/letta-ai/letta)（旧MemGPT）のフレームワークを使ったと書かれています。

| 日付         | 出来事                           | 形態               |
| ---------- | ----------------------------- | ---------------- |
| 2025-07-09 | v0.1.0公開（macOS用dmg）           | 画面監視型デスクトップアプリ   |
| 2025-07-10 | arXiv 2507.07957v1 投稿         | 論文               |
| 2025-08-08 | v0.1.2：Python SDKをPyPIで公開     | アプリ＋SDK          |
| 2025-12-25 | v0.1.6：メモリAPIへ転換              | API＋クラウド＋ダッシュボード |
| 2026-02-01 | PyPI `mirix` 0.1.7            | クライアントSDK        |
| 2026-10-27 | セッション単位のスキル学習をmainへ           | API              |
| 2026-11-08 | グラフメモリ（Neo4j）をmainへ統合         | API              |
| 2026-11-09 | API認証とメモリ整合性の修正               | API              |
| 2026-11-09 | arXiv 2611.12068（MIRIX-2.0）投稿 | 論文               |

1本目の論文は[MIRIX論文v1（HTML版）](https://arxiv.org/html/2507.07957v1)のまま改訂されておらず、グラフメモリとAutoDreamの評価は別の論文（MIRIX-2.0）として出ています。論文の実験はデスクトップアプリ時代の実装で行われたもので、評価コードは `public_evaluation` ブランチに残っています。GitHubのリリースはv0.1.6（プレリリース）が最後で、2026年10月以降の変更はタグの付かないmainにだけ入っています。論文の数字、PyPI版、mainの挙動は、それぞれ別の版の話として読む必要があります。

## 6種類のメモリの役割と保存フィールド

論文は、既存の記憶システムの多くが「1つの平らなストアに履歴を全部入れる」構造のため、検索が非効率で不正確になると指摘しています。MIRIXは入力を性質ごとに6つのメモリへ振り分け、メモリごとに異なるフィールドで保存します。

| メモリ             | 保存するもの          | 主なフィールド                                         |
| --------------- | --------------- | ----------------------------------------------- |
| Core            | 常に参照する人格とユーザー情報 | persona／human の2ブロック                            |
| Episodic        | 時刻付きの出来事        | event\_type, summary, details, actor, timestamp |
| Semantic        | 時刻に依存しない概念・人物   | name, summary, details, source                  |
| Procedural      | 手順・ワークフロー       | entry\_type, description, steps                 |
| Resource        | 文書・画像・音声の書き起こし  | title, summary, resource\_type, content         |
| Knowledge Vault | 逐語で残す機密情報       | entry\_type, source, sensitivity, secret\_value |

Core MemoryはMemGPTの設計を引き継いだもので、容量の90%を超えると要約し直す処理が走ります。EpisodicとSemanticの違いは時刻の有無です。「3月5日10時15分に経費精算を提出した」はEpisodic、「Johnはサンフランシスコに住むジョギング好きの友人」はSemanticに入ります。Semanticは概念として上書きされない限り残り続けます。

Knowledge Vaultには住所・電話番号・APIキーなど、要約すると意味を失う値を逐語で保存します。sensitivityが `high` のエントリはアクセス制御の対象で、通常の検索結果からは除外されます。

## メタメモリマネージャーと6つのメモリマネージャーの分担

種類の違う6メモリを1つのエージェントで管理するのは難しいため、MIRIXはメモリごとに専任のMemory Managerを置き、振り分けをMeta Memory Managerに任せます。書き込みと読み出しで流れが異なります。

### 書き込み：Meta Memory Managerによる振り分けと並列更新

新しい入力が来ると、まずメモリベースを自動検索し、その結果と入力をMeta Memory Managerに渡します。Meta Memory Managerは、どのメモリが関係するかを判断して該当するMemory Managerへ回します。各Memory Managerは自分のメモリを並列に更新し、重複を避けたうえで完了を報告する流れです。

1回の更新で、Meta Memory Managerへの呼び出しが1回、各Memory Managerへの呼び出しが0〜6回発生します。関数呼び出しが多い設計なので、論文はLOCOMOの実験でgpt-4o-miniではなくgpt-4.1-miniを選んでいます。Berkeley Function Calling Leaderboardのmulti-turn精度が22.12対29.75だったことが理由です。

### 読み出し：Active Retrievalによるトピック生成と自動検索

Mem0やMemGPTでは、記憶の検索を明示的に起動しないと、モデルが学習済みの古い知識で答えてしまいます。論文の例では、ユーザーが以前「TwitterのCEOはLinda Yaccarino」と伝えていても、会話履歴から消えた後に「TwitterのCEOは？」と聞くと「Elon Musk」と答えます。

Active Retrievalはこれを2段階で防ぎます。まずエージェントが入力から「CEO of Twitter」のような現在のトピックを生成します。次にそのトピックで6メモリから各上位10件を取り出し、`<episodic_memory>` のように出典メモリのタグを付けてシステムプロンプトに差し込みます。これとは別に、`embedding_match`・`bm25_match`・`string_match` の3つの検索関数があり、エージェントが状況に応じて選びます。現行のREADMEは、PostgreSQLネイティブのBM25全文検索とベクトル類似度検索の併用を掲げています。ただしmainのPostgreSQL向け全文検索は、BM25そのものではなくPostgreSQLの `ts_rank_cd`（語の近さを加味した順位付け）で並べ、テキスト検索設定は `'english'` 固定です。BM25とベクトル検索を組み合わせる考え方は[ハイブリッド検索の仕組みとRRFの実装](/tech/details/8014/)で詳しく扱っています。

## ベンチマーク結果の読み方：ScreenshotVQAとLOCOMO

アブストラクトの「精度35%向上・ストレージ99.9%削減」「LOCOMOで85.4%」は、どちらも論文のTable 1・Table 2から読むと条件が付きます。以下の表の数値は論文の表からの転記です。採用判断に使う前に比較対象を確認してください。

### ScreenshotVQA：比較相手はRAGと長文脈のGemini

ScreenshotVQAは論文チームが作ったデータセットです。CS・物理専攻の博士課程学生3名のPC画面を1秒ごとに撮影し（直前と類似度0.99超の画像は除外）、5,886枚・18,178枚・5,349枚を集めました。質問は3名が自分で作った計87問です。既存の記憶システム（Letta・Mem0）は画像を扱えないため、比較相手はSigLIPで上位50枚を引くRAGと、256×256に縮小した直近3,600枚をそのまま入れる長文脈方式です。回答生成には、MIRIXを含む全方式で `gemini-2.5-flash-preview-04-17` を使っています。

| 手法             | 平均精度   | 平均ストレージ  |
| -------------- | ------ | -------- |
| Gemini（長文脈）    | 0.1166 | 236.70MB |
| SigLIP@50（RAG） | 0.4410 | 15.07GB  |
| MIRIX          | 0.5950 | 15.89MB  |

「35%向上」は0.4410から0.5950への相対値で、絶対値では15.4ポイントの差です。「99.9%削減」は、元解像度（2K〜4K）の画像を全部持つSigLIPと、抽出した情報だけを入れたSQLiteファイルの比較です。MIRIXは元画像を保存しないため、後から画面の細部を問い直すことはできません。容量の削減は、元データを捨てて要約を残す設計から来る結果だと理解してください。

### LOCOMO：85.38%の内訳とOpen Domainの弱さ

LOCOMOは10本の長い会話（平均約600発話・2万6千トークン）に、会話ごとに約200問を付けたベンチマークです。MIRIXは会話の原文を見ずに、記憶から取り出した情報だけで答えます。判定はGPT-4.1によるLLM-as-a-Judgeで、回答不能を問うadversarialカテゴリはMem0の論文にならって除外しています。

| 手法（gpt-4.1-mini） | Single Hop | Multi-Hop | Open Domain | Temporal | Overall |
| ---------------- | ---------- | --------- | ----------- | -------- | ------- |
| RAG-500          | 37.94      | 37.69     | 48.96       | 61.83    | 51.62   |
| Mem0             | 62.41      | 57.32     | 44.79       | 66.47    | 62.47   |
| LangMem          | 74.47      | 61.06     | 67.71       | 86.92    | 78.05   |
| Zep              | 79.43      | 69.16     | 73.96       | 83.33    | 79.09   |
| MIRIX            | 85.11      | 83.70     | 65.62       | 88.39    | 85.38   |
| Full-Context     | 88.53      | 77.70     | 71.88       | 92.70    | 87.52   |

差が最も大きいのはMulti-Hopで、Zepより14.54ポイント高く、Full-Contextも上回ります。論文は、ばらばらの発言を「Carolineは4年前に故郷のスウェーデンから引っ越した」のような統合済みの出来事として保存するためだと説明しています。一方、Open Domainは65.62でZep（73.96）とLangMem（67.71）を下回ります。論文自身も、長期にわたる推論ではRAGに頼る検索がボトルネックになると認めています。

本文の主張と表の数字には食い違いがあります。本文は「LangMemを8ポイント以上上回る」「Multi-Hopで全ベースラインを24ポイント以上上回る」と書いていますが、表から計算するとLangMemとの差は7.33ポイント、Multi-HopでZepとの差は14.54ポイントです。この2つの主張は論文要約サイトでもそのまま転載されています。また、ベースラインは各1回、MIRIXとFull-Contextは3回の平均です。引用するときは表の値を使ってください。

### 後続論文MIRIX-2.0：グラフとAutoDreamの効果

2026年11月9日に、後続論文[MIRIX-2.0: Multi-Agent Memory System（arXiv 2611.12068）](https://arxiv.org/abs/2611.12068)が公開されました。著者にはYu Wangが含まれ、実装として同じGitHubリポジトリを示しています。6種類の記憶を持つエージェント群はそのままに、EpisodicとSemanticを来歴付き超グラフで索引する構成（下のグラフメモリ）と、重複した錨を後から統合するAutoDreamを評価しています。比較は、フラットな記憶（M0＝MIRIX-1.0）、グラフ（M1）、グラフ＋AutoDream（M2）の3構成です。

| 手法                          | LoCoMo Overall | Multi-hop | Temporal | Open | Single-hop | LongMemEval-S |
| --------------------------- | -------------- | --------- | -------- | ---- | ---------- | ------------- |
| mem0                        | 82.9           | 80.5      | 80.4     | 66.7 | 86.6       | 56.3          |
| HyperMem                    | 91.0           | 91.1      | 84.4     | 76.0 | 95.2       | 58.3          |
| MIRIX-1.0（M0）               | 85.7           | 83.3      | 85.0     | 70.8 | 88.3       | 58.8          |
| MIRIX-2.0（M1、グラフ）           | 88.4           | 89.0      | 86.0     | 71.9 | 91.1       | 70.0          |
| MIRIX-2.0（M2、グラフ＋AutoDream） | 91.4           | 91.8      | 89.4     | 74.0 | 94.1       | 72.6          |

グラフ化でLoCoMoは2.7ポイント、LongMemEval-S（300問）は11.2ポイント上がり、AutoDreamでさらに3.0ポイントと2.6ポイント上がっています。ただしLoCoMoでHyperMemとの差は0.4ポイントで、Open DomainとSingle-hopはHyperMemの方が高い値です。評価条件も1本目の論文と違います。回答と抽出はgpt-4.1-mini、埋め込みはtext-embedding-3-small、判定はgpt-4o-miniの3回多数決で、mem0は1本目の62.47に対してここでは82.9です。2つの論文の数字は並べて比べないでください。

コスト面の記述もあります。長文書のQAでは、グラフを作るM1の取り込み時間がM0の3.8〜4.0倍、回答の待ち時間もM0より長くなりました。論文自身が「グラフ検索はフラットな検索より本質的に安いわけではない」と書いています。M2のAutoDreamは統合の呼び出しがさらに加わり、その総コストは測られていません。

## Letta・Mem0・Zepとの記憶設計の違い

論文は既存方式を、知識グラフ型（Zep、Cognee）と、テキスト断片をベクトルDBに入れるフラット型（Letta、Mem0、ChatGPTのメモリ）に分けています。MIRIXは、記憶の種類を細かく分けてエージェントが振り分ける点と、画面キャプチャなどの画像入力を扱う点で、両方と異なります。

| 方式            | 記憶の分け方               | 画像入力        | 検索の起動         |
| ------------- | -------------------- | ----------- | ------------- |
| MIRIX         | 6種類＋専任エージェント         | 対応（画面キャプチャ） | トピック生成で自動     |
| Letta（MemGPT） | core／recall／archival | 論文では非対応扱い   | エージェントが明示的に呼ぶ |
| Mem0          | 入力から抽出した事実           | 論文では非対応扱い   | 明示的に呼ぶ        |
| Zep           | 時系列の知識グラフ            | 不得手と記述      | クエリで検索        |

この比較は論文執筆時（2025年7月）の記述に基づきます。MIRIX自身も2026年11月にグラフメモリを取り込んだため、「フラット型か知識グラフ型か」という区分は現行版ではオプションの違いになりました。Mem0もv3で破壊的変更が入り、API・構成とも論文時点から変わっています（[mem0とは？v3の破壊的変更・旧版のSQLインジェクションとAIエージェントに記憶を持たせる実装](/tech/details/17640/)）。短期記憶と長期記憶の切り分けなど、製品に依存しない設計判断は[エージェントメモリとは？短期記憶と長期記憶の設計・実装判断を実装者向けに解説](/tech/details/16053/)で整理しています。

## v0.1.6以降のメモリAPI版の構成

v0.1.6（GitHub上はプレリリース扱い）のリリースノートは、MIRIXを「どのエージェントにも組み込める専用のメモリシステム」と位置付け直しました。破壊的変更として、デスクトップアプリがmainから外され、クラウド利用にはAPIキーが必須になりました。画面を監視する旧アプリは `desktop-agent` ブランチに残っていますが、リリースノートで非推奨とされています。READMEの冒頭には今も「Screen Activity Tracking」が機能として並んでいますが、画面を自動で撮影して送るアプリ部分はmainに含まれず、画像を取り込むにはクライアントから送る必要があります。

mainの `docker-compose.yml` は、PostgreSQL（`ankane/pgvector:v0.5.1`、5432番）、Redis Stack（6379番）、APIサーバー（8531番）、ダッシュボード（5173番）を立ち上げます。2026年11月9日の修正で、これらの公開ポートはすべて `127.0.0.1` に限定され、Redisにはパスワード認証が付きました。ダッシュボードで発行したAPIキーをクライアントに渡す流れは変わりません。ホスト型のapp.mirix.ioを使えば自前のインフラは要りませんが、記憶を外部サービスに預けることになる点は前提として押さえてください。

LLMの設定例は、mainの `mirix/configs/examples` にAzure・Claude・Gemini・OpenAIの4系統が用意されています。記憶の重複や矛盾を整理する `auto_dream` は、`core`・`episodic`・`semantic`・`resource`・`procedural`・`knowledge`・`experience`（Episodic・Semantic・Knowledge Vaultをまとめて処理）の7モードです。Procedural Memoryは、ツール実行の失敗と修正の記録から「スキル」を抽出する方式に作り替えられ、`procedural` モードでは `last_n_sessions` で直近のセッションからスキルを蒸留します。

## 導入手順とREADMEの落とし穴：Docker・PyPI版・mainの違い

READMEのクイックスタートは、Dockerでバックエンドを起動し、`pip install mirix-client` でクライアントを入れる3ステップです。2026年11月11日時点で、この3ステップには3つの食い違いがあります。サーバー側は必須シークレットとイメージの版、クライアント側はパッケージ名と同期・非同期の書き方です。

### Dockerの起動：必須シークレット3つとイメージの版

11月9日の修正で、`docker-compose.yml` は `MIRIX_PG_PASSWORD`・`MIRIX_REDIS_PASSWORD`・`MIRIX_JWT_SECRET_KEY` を必須にしました。READMEの手順1は `docker compose up -d --pull always` だけで、この設定に触れていません。mainのコミット98ebb81で `.env` を置かずに `docker compose config` を実行すると（Docker Compose 5.6.0）、次のエラーで終了コード1になりました。

```
error while interpolating services.mirix_api.environment.[]: required variable MIRIX_PG_PASSWORD is missing a value: Set MIRIX_PG_PASSWORD in .env
error while interpolating services.mirix_api.environment.[]: required variable MIRIX_REDIS_PASSWORD is missing a value: Set MIRIX_REDIS_PASSWORD in .env
error while interpolating services.mirix_api.environment.[]: required variable MIRIX_JWT_SECRET_KEY is missing a value: Set MIRIX_JWT_SECRET_KEY in .env
error while interpolating services.mirix_db.environment.[]: required variable MIRIX_PG_PASSWORD is missing a value: Set MIRIX_PG_PASSWORD in .env
error while interpolating services.redis.environment.[]: required variable MIRIX_REDIS_PASSWORD is missing a value: Set MIRIX_REDIS_PASSWORD in .env
```

リポジトリの `docker/env.example` を `.env` にコピーし、3つの値を別々に生成すると設定の検証は通りました（終了コード0）。JWTのシークレットは32文字以上が必要で、旧版の既定値 `change-this-to-a-secure-secret-key` はサーバーが拒否します。`openssl rand -hex 32` は64文字を返すので条件を満たします。

```
git clone https://github.com/Mirix-AI/MIRIX.git && cd MIRIX
git checkout 98ebb81c7f457a15661518242bbec5c40deb409e
cp docker/env.example .env
for k in MIRIX_PG_PASSWORD MIRIX_REDIS_PASSWORD MIRIX_JWT_SECRET_KEY; do
  sed -i.bak "s|^$k=.*|$k=$(openssl rand -hex 32)|" .env
done
docker compose config -q && echo OK
# 11月の変更を含むサーバーを使うなら、リポジトリからビルドする
docker compose up -d --build
```

もう1つはイメージの版です。composeはAPIサーバーに `yuwucsd/mirix-api:latest` を指定していますが、Docker Hub上のこのタグとダッシュボードのタグは2025年12月22日の更新が最後です（Docker HubのAPIが返す `last_updated` で確認）。READMEの `--pull always` で取得するのはv0.1.6前後のサーバーで、グラフメモリ、セッション単位のスキル学習、11月の認証修正は含まれません。現行mainの機能を使うときは、上の例のように `--build` でリポジトリからイメージを作ります。この記事の検証は設定の検証までで、ビルドとサーバーの起動は実行していません。

### クライアントの入れ方：PyPI版 mirix 0.1.7 とmainの差

`mirix-client` は2026年11月11日時点でもPyPIに存在せず（JSON APIが404）、配布されているのは[PyPIのmirix配布ページ](https://pypi.org/project/mirix/)にあるパッケージ名 `mirix` です。最新は2026年2月1日の0.1.7で、その後のmainの変更は入っていません。PyPI版とmainではクライアントの書き方が違います。

| 項目                  | PyPI mirix 0.1.7         | main（2026-11-09）            |
| ------------------- | ------------------------ | --------------------------- |
| インストール              | pip install mirix==0.1.7 | リポジトリから導入                   |
| 呼び出し方式              | 同期                       | 非同期（await）                  |
| クライアント生成            | MirixClient(…)           | await MirixClient.create(…) |
| add の session\_id   | なし（TypeError）            | あり                          |
| auto\_dream         | なし                       | あり                          |
| \_\_version\_\_ の表記 | 0.1.7                    | 0.1.0（未更新）                  |

Python 3.11の仮想環境に `mirix==0.1.7` を入れてシグネチャを確認すると、READMEの例にある `session_id` を `add()` に渡した時点で `TypeError: MirixClient.add() got an unexpected keyword argument 'session_id'` になります。PyPI版では次のように `session_id` を外して呼びます（Python 3.10以上が必要です）。確認したのはクライアント側のシグネチャまでで、サーバーへの書き込みと検索は実行していません。

モデル名は、READMEとmainの `mirix_gemini.yaml` が2026年11月8日に `gemini-3.6-flash` と `gemini-embedding-001` へ更新されました。それまで書かれていた `gemini-2.0-flash` は2026年6月1日、`text-embedding-004` は2026年1月14日に、Gemini APIでの提供を終えています（[Gemini APIの非推奨スケジュール](https://aistudio.google.com/docs/deprecations)による）。同じ表で `gemini-embedding-001` の停止予定は2028年5月14日です。同じ日のmainの修正で、Gemini 3系が関数呼び出しで返す思考シグネチャ（thought signature）を保存して送り返すようになりました。Gemini 3系をMIRIXで使うなら、この修正を含むmainのサーバーを使ってください。

```
from mirix import MirixClient

client = MirixClient(api_key="your-mirix-api-key", base_url="http://localhost:8531")

config = {
    "llm_config": {
        "model": "gemini-3.6-flash",
        "model_endpoint_type": "google_ai",
        "api_key": "your-google-api-key",
        "model_endpoint": "https://generativelanguage.googleapis.com",
        "context_window": 1_000_000,
    },
    "embedding_config": {
        "embedding_model": "gemini-embedding-001",
        "embedding_endpoint_type": "google_ai",
        "api_key": "your-google-api-key",
        "embedding_endpoint": "https://generativelanguage.googleapis.com",
        "embedding_dim": 768,
    },
}
client.initialize_meta_agent(config=config)

client.add(
    user_id="demo-user",
    messages=[
        {"role": "user", "content": [{"type": "text", "text": "来週の定例は木曜15時に移動"}]},
        {"role": "assistant", "content": [{"type": "text", "text": "記録しました"}]},
    ],
)

print(client.retrieve_with_conversation(
    user_id="demo-user",
    messages=[{"role": "user", "content": [{"type": "text", "text": "定例はいつ？"}]}],
    limit=5,
))
```

`add()` は既定で `async_add=True` のため、サーバー側のキューで非同期に処理されます。呼んだ直後に検索しても、まだ記憶に入っていないことがあります。メモリの種類を指定して探すときは `search(user_id, query, memory_type="episodic", search_method="bm25")` を使います。`search_method` は `bm25`（既定）か `embedding` です。

日本語の記憶を `bm25` で探すときは注意が要ります。MIRIXの全文検索は `to_tsvector('english', …)` で語を切りますが、この設定は空白と記号で区切るため、空白の無い日本語の文は丸ごと1語になります。手元のPostgreSQL 18.6で確かめた結果は次のとおりです。

```
select to_tsvector('english','来週の定例は木曜15時に移動');
-- '来週の定例は木曜15時に移動':1

select to_tsvector('english','来週の定例は木曜15時に移動') @@ to_tsquery('english','定例');
-- f（一致しない）

select to_tsvector('english','The weekly sync moved to Thursday 3pm') @@ to_tsquery('english','sync');
-- t
```

MIRIXは3文字以上の検索語に前方一致も付けますが、文の途中にある語は前方一致でも拾えません。日本語中心のデータでメモリの種類を指定して探すなら、`search_method="embedding"` を指定する方が確実です。

### main版の非同期クライアントとauto\_dream

`session_id` と `auto_dream` を使うには、取得したMIRIXリポジトリのルートで `python -m pip install -e .` を実行し、その環境から非同期クライアントを呼びます。mainの `mirix/client/remote_client.py` では `initialize_meta_agent`・`add`・`retrieve_with_conversation` などがすべて `async def` で、クライアントはクラスメソッド `create` で生成します。リポジトリ内の `samples/run_client.py` も `asyncio.run()` で動かしています。READMEの同期スタイルの例をmainで実行すると、コルーチンが返るだけで処理は走りません。また、mainの `add()` は `initialize_meta_agent()` を先に呼んでいないと「Meta agent not initialized」の `ValueError` を送出します。書き込みの可否は、APIキーを発行したサーバー側のクライアントに登録された `write_scope` で決まります。`create()` の `write_scope` 引数はサーバーへ送られますが、APIキー認証では登録済みの値が優先され、権限は変わりません。サーバー側の `write_scope` が空のクライアントは読み取り専用で、検索以外のPOSTは403（Client has read-only access）で拒否されます。ダッシュボードで最初に登録したユーザーのクライアントには `admin` スコープが付きます。

```
import asyncio
from mirix import MirixClient

async def main():
    # 書き込めるかどうかはAPIキー側のクライアントに登録された write_scope で決まる
    client = await MirixClient.create(
        api_key="your-mirix-api-key", base_url="http://localhost:8531"
    )
    await client.initialize_meta_agent(config=config)  # 上の例と同じ設定の辞書
    await client.add(
        user_id="demo-user",
        messages=[
            {"role": "user", "content": [{"type": "text", "text": "Deploy the service."}]},
            {"role": "tool", "name": "kubectl_apply", "content": "error: forbidden (missing RBAC)"},
            {"role": "assistant", "content": [{"type": "text", "text": "RBACを直して再デプロイしました"}]},
        ],
        session_id="sess-demo-001",
    )
    # dry_run=True は対象件数の確認だけで、記憶は書き換えない
    print(await client.auto_dream(user_id="demo-user", mode="experience", dry_run=True))

asyncio.run(main())
```

11月9日の修正以降、APIはJWTかAPIキーで必ず認証し、クライアントIDや組織IDのヘッダーだけでは通りません。既存のデータベースでmainへ上げる場合は、READMEにあるスキル化用の8本と、グラフメモリ用の `migrate_add_graph_provenance_columns.sql` の計9本のSQLを手で流します。起動時に作られるのは不足しているテーブルだけで、既存テーブルへの列追加はされないためです。未適用のまま起動すると、サーバーは必要なスクリプト名を表示して起動を拒否します。

## グラフメモリ（Neo4j）を有効にする手順

2026年11月8日にmainへ統合されたグラフメモリは、EpisodicとSemanticの記憶をNeo4j上の「来歴付き超グラフ（provenance hypergraph）」として索引する仕組みです。人物や物などのエンティティを錨（anchor）にし、抽出した事実を、各エンティティの役割を名前付きの辺でつないだn項の枠（frame）として保存します。どの枠にも、元になった記憶の行への引用が付きます。有効にすると、EpisodicとSemanticの検索はグラフ経由になり、`auto_dream` は保存済みの記憶を書き換えずにグラフ上で重複した錨を統合します。

既定はオフで、オフのときは従来どおりPostgreSQLだけのフラットな記憶として動きます。有効にする手順は[リポジトリのGRAPH\_MEMORY.md](https://github.com/Mirix-AI/MIRIX/blob/main/evals/GRAPH%5FMEMORY.md)とREADMEに次のようにあります。

1. `.env` に8文字以上の `MIRIX_NEO4J_PASSWORD` を書く（Neo4jに既定のパスワードは無い）。
2. `docker compose --profile graph up -d` でNeo4j 5.26（APOC付き）を起動する。Neo4jは5.23以上が必要で、それより古いサーバーはグラフ用のクエリ構文 `CALL (a, row) { ... }` を受け付けない。
3. サーバーをPythonで直接動かす場合は、`pip install -e .` の後に `pip install "neo4j>=5.20,<6"` でドライバーを入れる。
4. サーバーに `MIRIX_ENABLE_GRAPH_MEMORY=true` を設定する。Pythonで直接起動したサーバーの既定接続先は `bolt://localhost:7687`、Docker Compose内のAPIサーバーは `bolt://neo4j:7687`（サービス名）で、既定ユーザーはどちらも `neo4j`。
5. 既存のデータベースなら `migrate_add_graph_provenance_columns.sql` を流す。

埋め込みの次元は揃える必要があります。PostgreSQL側は全ベクトルを4096次元までゼロ埋めして保存しますが、Neo4jのベクトル索引は `MIRIX_NEO4J_VECTOR_DIM`（既定1536）の次元で作られ、グラフに送るベクトルは `embedding_config` の `embedding_dim` で切り詰められます。上の例のように `embedding_dim` を768にするなら、`MIRIX_NEO4J_VECTOR_DIM` も768にします。ただし98ebb81の `docker-compose.yml` はこの変数をAPIコンテナへ渡していないため、`.env` に書くだけでは効きません（`.env` に768を書いて `docker compose config` を出力しても、この変数は現れませんでした）。Dockerで動かすときは `mirix_api` の `environment` に `MIRIX_NEO4J_VECTOR_DIM=${MIRIX_NEO4J_VECTOR_DIM:-1536}` を足し、コンテナを作り直します。グラフメモリを有効にした状態の `auto_dream` は、リクエストで `graph_only` を `false` にしない限りグラフの整理だけを行います。Neo4jのデータモデルとCypherは[Neo4jとは？グラフデータベースの構造とCypher・エディション選定](/tech/details/15996/)で解説しています。

リポジトリにはLoCoMoとMemoryAgentBenchでフラット記憶（M0）、グラフ（M1）、グラフ＋AutoDream（M2）を比べる評価手順が用意されています。READMEに比較結果の数値はありませんが、同じM0／M1／M2の比較は上の後続論文MIRIX-2.0に載っています。論文の条件はgpt-4.1-miniと英語のベンチマークなので、日本語のデータや別のモデルで効果が同じとは限りません。取り込み時間が増える点も含めて、自分のデータで評価手順を回して確かめてください。

## MIRIXの採用を見送るべき場面

MIRIXの設計は「記憶の種類を分けて、自動で振り分けて、自動で引く」ことに価値があります。逆に言えば、次の条件に当てはまるなら、より単純な方式の方が運用しやすいはずです。

- **APIの安定性が必要な本番システム**：最後のリリースはv0.1.6のプレリリースで、その後の変更はタグの無いmainに直接入っています。2026年11月の1週間だけでグラフメモリの統合、必須シークレットの追加、マイグレーションの追加が重なりました。PyPI版・Docker Hubのイメージ・mainの3つも揃っていません。コミット単位で版を固定し、上げるたびに検証できる体制が無いなら見送るのが妥当です。
- **LLM呼び出しの回数とコストを抑えたい場合**：1回の書き込みでMeta Memory Managerと最大6つのMemory Managerが関数呼び出しを行います。グラフメモリを有効にすると、事実の抽出と索引の処理がさらに加わります（後続論文の長文書QAでは、取り込み時間がグラフ無しの3.8〜4.0倍）。会話量が多いサービスでは、事実を抽出して1つのストアに入れる方式の方が呼び出し回数を予測しやすくなります。
- **認証情報を記憶に入れる運用**：Knowledge VaultはAPIキーやパスワードを逐語で保存する設計です。LLMが振り分けを判断する経路に秘密情報を流すと、プロンプトインジェクションや記憶の汚染で漏れる経路が増えます。11月9日の修正で、削除済みの記憶が検索に残る問題や、数値の違う記憶が誤って統合される問題も直されたばかりです。秘密情報はシークレットマネージャーに置き、記憶には参照名だけを残す方が安全です（攻撃の手口は[メモリポイズニングとは？AIエージェントの記憶汚染の手口・事例と防御策](/tech/details/12532/)を参照）。

一方で、ユーザーごとの出来事・手順・知識が混ざって蓄積し、「先週何を話したか」と「どうやるか」を区別して引きたいパーソナルアシスタントや社内エージェントには、6分割の設計が合います。LOCOMOのMulti-HopとTemporalで強いのはこの用途です。記憶の設計を含めたエージェントの構築を外部に相談するなら、[AIエージェント開発の支援](/service/ai/agent/)も選択肢になります。複数のエージェントに役割を分ける構成そのものの考え方は[マルチエージェントとは？仕組み・構成パターンと採用判断](/tech/details/13604/)にまとめています。

## 論文が描く応用構想：ウェアラブルと記憶マーケットプレイス

論文の第2章は、実装済みの機能とは別に2つの構想を挙げています。1つはAIグラスやAIピンなどのウェアラブル端末への組み込みで、Knowledge Vaultは端末内、Resource Memoryのような大きな記憶はクラウドに置くハイブリッド構成を想定しています。もう1つは「Agent Memory Marketplace」で、エンドツーエンド暗号化と分散ストレージの上で、個人の記憶を共有・取引する構想です。どちらも論文時点の提案で、2026年11月時点のリポジトリには対応する実装はありません。

## よくある質問

### MIRIXの論文はどこで読めますか？

arXivの2507.07957（タイトル「MIRIX: Multi-Agent Memory System for LLM-Based Agents」）で全文を読めます。2025年7月10日投稿のv1が最新で、ライセンスはCC BY 4.0です。評価コードと各手法の予測結果は、GitHubの `public_evaluation` ブランチで公開されています。グラフメモリとAutoDreamを評価した後続論文は、2026年11月9日公開のarXiv 2611.12068（MIRIX-2.0: Multi-Agent Memory System）です。

### MIRIXは無料で使えますか？

OSS本体はApache License 2.0なので、ライセンス料はかかりません。自前で動かす場合のサーバー費用は利用者の負担です。さらに、記憶の振り分けと検索にLLMと埋め込みモデルを呼ぶため、OpenAIやGeminiなどのAPI料金は別にかかります。ホスト型のapp.mirix.ioの料金は公式サイトで確認してください。

### GitHubにあったデスクトップアプリはまだ使えますか？

v0.1.6でmainから外れ、`desktop-agent` ブランチに移りました。リリースノートで非推奨とされており、配布されたdmgはv0.1.3（2025-08-23）のApple Silicon版が最後です。画面を監視して記憶を作る使い方は、現行のmainでは提供されていません。

### pip install mirix-client が失敗するのはなぜですか？

READMEに書かれた `mirix-client` というパッケージがPyPIに存在しないためです。PyPIで配布されているのは `mirix`（2026年2月1日公開の0.1.7が最新）で、インポート名は `from mirix import MirixClient` です。READMEのコード例にある `session_id` や `auto_dream` を使うにはmain版が必要で、mainのクライアントは `await` で呼びます。

### MIRIXとLetta（MemGPT）はどういう関係ですか？

READMEの謝辞によると、MIRIXのメモリ部分はLettaのフレームワークを土台に作られています。Core Memoryのpersona／humanブロックもMemGPT由来の設計です。違いは、Lettaのcore・recall・archivalの3区分を6種類に細分化し、種類ごとに専任のエージェントを置いた点と、検索を自動で起動するActive Retrievalにあります。

## 関連記事

- [エージェントメモリとは？短期記憶と長期記憶の設計・実装判断を実装者向けに解説](/tech/details/16053/)
- [mem0とは？v3の破壊的変更・旧版のSQLインジェクションとAIエージェントに記憶を持たせる実装](/tech/details/17640/)
- [メモリポイズニングとは？AIエージェントの記憶汚染の手口・事例と防御策](/tech/details/12532/)
- [Neo4jとは？グラフデータベースの構造とCypher・エディション選定を実装視点で解説](/tech/details/15996/)
- [ハイブリッド検索とは？RAGでBM25とベクトル検索を統合する仕組み・RRF・製品別の実装](/tech/details/8014/)

---

出典: [MIRIXとは？6種類のメモリで動くLLMエージェント記憶システムの仕組み・導入手順・グラフメモリ](<https://www.issoh.co.jp/tech/details/10751/>)（株式会社一創）