SimpleMem ロゴ

## LLMエージェントのための効率的な生涯記憶 — テキスト & マルチモーダル意味的ロスレス圧縮による長期記憶の保存・圧縮・検索。テキスト、画像、音声、動画のマルチモーダルサポートを追加。

MCP（テキストメモリ）またはPython統合（完全マルチモーダル）をサポートするあらゆるAIプラットフォームで動作

_{Claude Desktop}

_Cursor

_{LM Studio}

_{Cherry Studio}

_{PyPI パッケージ}

_{+ その他すべての MCP
クライアント}

[🇬🇧 English](../../README.md) • [🇨🇳 中文](./README.zh-CN.md) • **🇯🇵 日本語** • [🇰🇷 한국어](./README.ko.md) • [🇪🇸 Español](./README.es.md) • [🇫🇷 Français](./README.fr.md) • [🇩🇪 Deutsch](./README.de.md) • [🇧🇷 Português](./README.pt-br.md)
[🇷🇺 Русский](./README.ru.md) • [🇸🇦 العربية](./README.ar.md) • [🇮🇹 Italiano](./README.it.md) • [🇻🇳 Tiếng Việt](./README.vi.md) • [🇹🇷 Türkçe](./README.tr.md)
[![Project Page](https://img.shields.io/badge/🎬_INTERACTIVE_DEMO-Visit_Our_Website-FF6B6B?style=for-the-badge&labelColor=FF6B6B&color=4ECDC4&logoColor=white)](https://aiming-lab.github.io/SimpleMem-Page)

[🚀 クイックスタート](#-クイックスタート) • [🌟 概要](#-概要) • [📦 インストール](#-インストール) • [🔌 MCP サーバー](#-mcp-サーバーテキストメモリ) • [📊 再現](#-論文結果の再現) • [📝 引用](#-引用)

## 🔥 ニュース - **[05/21/2026]** 📦 **統合 `simplemem` パッケージ — インポート一つで自動ルーティング！** SimpleMem、Omni-SimpleMem、EvolveMem が単一のパッケージに統合されました。`from simplemem import SimpleMem` は最初に呼び出すメソッドに応じてテキストまたはマルチモーダルバックエンドを自動選択し、`simplemem.optimize(...)` は EvolveMem の自己進化ループを活用します。`pip install -e .` でワンステップインストール。 - **[05/14/2026]** 🧬 **EvolveMem (v3.0) — AutoResearch による自己進化型メモリ！** 検索インフラ自体が LLM 駆動のクローズドループ診断により自己進化します。LoCoMo では最強のベースラインを **+25.7% 相対的**に上回り、MemBench では **+18.9% 相対的**に上回ります。システムは元の設計には存在しなかった全く新しい検索次元を発見します。[EvolveMem を見る →](../../EvolveMem/) - **[04/02/2026]** 🧠 **Omni-SimpleMem (v2.0) — マルチモーダルメモリ登場！** SimpleMem が **テキスト、画像、音声 & 動画** のメモリをサポートするようになりました。**LoCoMo で新 SOTA 達成 (F1=0.613, +47%)** および **Mem-Gallery (F1=0.810, +51%)** を従来の最高性能を超えて達成。[Omni-SimpleMem を見る →](../../OmniSimpleMem/) - **[02/09/2026]** 🚀 **クロスセッションメモリ — Claude-Mem を 64% 上回る！** [クロスセッションドキュメントを見る →](../../cross/README.md) - **[01/20/2026]** 📦 **SimpleMem が PyPI で利用可能になりました！** `pip install simplemem` でインストール。[パッケージ利用ガイドを見る →](../PACKAGE_USAGE.md) - **[01/14/2026]** 🎉 **SimpleMem MCP サーバーが稼働開始！** [mcp.simplemem.cloud](https://mcp.simplemem.cloud) でクラウドホスティング。[MCP ドキュメントを見る →](../../MCP/README.md) - **[01/05/2026]** SimpleMem 論文が [arXiv](https://arxiv.org/abs/2601.02553) で公開されました！ --- ## 📑 目次 - [🚀 クイックスタート](#-クイックスタート) - [🌟 概要](#-概要) - [📦 インストール](#-インストール) - [🐳 Docker](#-docker-で実行) - [🔌 MCP サーバー](#-mcp-サーバーテキストメモリ) - [📊 論文結果の再現](#-論文結果の再現) - [🗺️ ロードマップ](#️-ロードマップ) - [📝 引用](#-引用) --- ## 🚀 クイックスタート ### 🧠 基本的なワークフローの理解大まかに言えば、SimpleMem は LLM ベースのエージェントのための長期記憶システムとして機能します。ワークフローは三つのシンプルなステップで構成されています： 1. **情報を保存する** — 対話や事実が処理され、構造化されたアトミックなメモリに変換されます。 2. **メモリをインデックスする** — 保存されたメモリが意味埋め込みと構造化メタデータを使って整理されます。 3. **関連メモリを検索する** — クエリが行われると、SimpleMem はキーワードではなく意味に基づいて最も関連性の高い保存情報を検索します。この設計により、LLM エージェントはコンテキストを維持し、過去の情報を効率的に思い出し、冗長な履歴を繰り返し処理することを避けられます。 ### 🎓 基本的な使い方 SimpleMem は単一の `simplemem` パッケージとして提供されます。デフォルトの `mode="auto"` は、呼び出す内容に基づいてどのバックエンドを使用するかを **自動検出** します — 手動設定は不要です： ```python from simplemem import SimpleMem mem = SimpleMem() # mode="auto" — バックエンドは最初の呼び出しで決まる ``` 最初に呼び出すメソッドがバックエンドを決定します： | 最初の呼び出し | 選択されるバックエンド | 理由 | |:--|:--|:--| | `add_dialogue()` | **テキスト** (SimpleMem) | 対話ベース API → テキストモード | | `add_text()` / `add_image()` / `add_audio()` / `add_video()` | **Omni** (Omni-SimpleMem) | マルチモーダル API → omni モード |

**📝 Auto → テキスト** (純テキスト入力) ```python from simplemem import SimpleMem mem = SimpleMem() # auto mode # add_dialogue() → テキストバックエンドが自動選択 mem.add_dialogue( "Alice", "Bob, let's meet at Starbucks tomorrow at 2pm", "2025-11-15T14:30:00", ) mem.add_dialogue( "Bob", "Sure, I'll bring the market analysis report", "2025-11-15T14:31:00", ) mem.finalize() answer = mem.ask("When and where will Alice and Bob meet?") # → "16 November 2025 at 2:00 PM at Starbucks" ```

**🧠 Auto → Omni** (マルチモーダル入力) ```python from simplemem import SimpleMem mem = SimpleMem() # auto mode # add_image() → omni バックエンドが自動選択 mem.add_text( "User loves hiking in the Rocky Mountains.", tags=["session_id:D1"], ) mem.add_image("photo.jpg", tags=["session_id:D1"]) mem.add_audio("voice_note.wav", tags=["session_id:D1"]) result = mem.query("What does the user enjoy?", top_k=5) for item in result.items: print(item["summary"]) mem.close() ```

> **💡 ヒント**: Auto モードはデータに合った最も軽量なバックエンドを選択します。必要に応じて `mode="text"` または `mode="omni"` を明示的に指定することもできます。 --- ### 🧬 上級：検索設定の最適化開発用データセットでオフラインに検索ハイパーパラメータを調整し、結果として得られた `Config` を推論に展開します。これは EvolveMem の自己進化ループの薄いラッパーです： ```python import simplemem from simplemem import SimpleMem, load_config # mem はメモリが既に構築済みのファイナライズされた SimpleMem インスタンス dev_questions = [ ("When is the meeting?", "2pm tomorrow at Starbucks"), ("What should Bob prepare?", "market analysis report"), ] config = simplemem.optimize(mem, dev_questions, max_rounds=3) config.save("my_config.json") # 後で、最適化された設定で展開 config = load_config("my_config.json") mem = SimpleMem(config=config) ``` > EvolveMem は開発用の質問に対して LLM 駆動の評価 → 診断 → 提案 → ガードサイクルを実行し、グローバルな検索フラグ（top_k、フュージョンモード、回答検証、リフレクションラウンドなど）を調整します。ベンチマークアダプターとカテゴリ別オーバーライドを持つ完全なスタンドアロン版については [`EvolveMem/`](../../EvolveMem/) を参照してください。 --- ### 🚄 上級：並列処理大規模な対話処理には、並列モードを有効にします： ```python from simplemem import create mem = create( mode="text", clear_db=True, enable_parallel_processing=True, # ⚡ 並列メモリ構築 max_parallel_workers=8, enable_parallel_retrieval=True, # 🔍 並列クエリ実行 max_retrieval_workers=4 ) ``` > **💡 プロヒント**: 並列処理はバッチ操作のレイテンシを大幅に削減します！ --- ## 🌟 概要 **SimpleMem** は LLM エージェントのための統合メモリスタックであり、一つの原則に基づいて構築されています：*意味的にロスレスな* メモリを高い情報密度で保存することで、エージェントがより多くを思い出しながら大幅に少ないトークンで済むようにすること。このパッケージは、同じ原則を共有しながらも問題の異なる部分を攻略する三つの研究をまとめています。 ### 📝 SimpleMem: 効率の核（テキスト）ほとんどのメモリシステムは悪いトレードオフを強いられています。生の対話履歴を受動的に蓄積するか（冗長でトークンを大量消費）、または高価な推論ループでノイズをフィルタリングするか（遅くてコストがかかる）のどちらかです。SimpleMem は代わりに三段階パイプラインで対話を圧縮します： | ステージ | 何をするか | |:--|:--| | **1. 意味的構造化圧縮** | 非構造化された対話をコンパクトなメモリユニット（共参照が解決され絶対タイムスタンプを持つ自己完結した事実）に蒸留し、柔軟な検索のために複数の補完的なビューでインデックスします。 | | **2. オンライン意味合成** | セッション内の関連コンテキストを統合された抽象表現にマージし、クエリ時ではなくメモリ構築時に冗長性を除去します。 | | **3. 意図認識型検索計画** | クエリの背後にある検索意図を推測し、何を検索するかを決定して精密でコンパクトなコンテキストを組み立てます。 | LoCoMo ベンチマークでは、推論時のトークン消費を約 30 分の 1 に削減しながら、先行システムと比較して平均 F1 スコアが 26.4% 向上します。メカニズムの詳細（ハイブリッドインデックス層、圧縮例、検索計画）：[**SimpleMem テキストメモリ →**](../text-memory.md)。 ### 🧠 Omni-SimpleMem: マルチモーダルメモリ（テキスト、画像、音声、動画） Omni-SimpleMem は圧縮優先の哲学を四つのモダリティに拡張し、三つの原則に基づいて構築されています：**選択的取り込み**（モダリティごとのエントロピー駆動フィルタリング）、**段階的検索**（ピラミッドトークンバジェット拡張を伴うハイブリッド FAISS + BM25）、**知識グラフ拡張**（マルチホップクロスモーダル推論）。手作業で設計されるのではなく、そのアーキテクチャは二つのベンチマーク上で約 50 の実験を実行した自律的な研究パイプラインによって *発見* されました。このパイプラインは、ヒューマンループなしで失敗モードを診断し、アーキテクチャの変更を提案し、データパイプラインのバグを修復しさえしました。注目すべきことに、バグ修正とアーキテクチャの変更はハイパーパラメータ調整をすべて合わせたものよりも大きく貢献し、システムを素朴なベースラインから LoCoMo と Mem-Gallery の両方で最先端の状態へと引き上げました。完全なドキュメント：[**Omni-SimpleMem →**](../../OmniSimpleMem/)。 ### 🧬 EvolveMem: 自己進化型検索 EvolveMem は、ほぼすべてのメモリシステムが共有する盲点を解消します：保存されたコンテンツは進化しますが、*検索* 機構（スコアリング関数、フュージョン戦略、回答生成ポリシー）はデプロイ後に凍結されたままです。EvolveMem はクローズドループ AutoResearch プロセス（**評価 → 診断 → 提案 → ガード → 繰り返し**）を実行し、LLM が質問ごとの失敗を診断して設定変更を提案します。リグレッション時の自動ロールバックと停滞時の探索インセンティブでガードされています。元の設計にはない新しい検索次元（クエリ分解、エンティティスワップ、回答検証）を発見し、LoCoMo を最強のベースラインと比較して 25.7% 相対的に改善し、その進化した設定はベンチマーク間で正の転移を示します。完全なドキュメント：[**EvolveMem →**](../../EvolveMem/)。 ### 三つがどのように組み合わさるか `from simplemem import SimpleMem` でマルチモーダルバックエンドへの自動ルーティングを持つテキストコアが得られ、`simplemem.optimize(...)` で EvolveMem があなた自身のデータ向けに検索を調整します。一つのパッケージ、一つのメンタルモデル：ロスレスに圧縮し、意図で検索し、システムが自己改善し続けるようにします。 --- ## 📦 インストール ### 📝 初めてのユーザーへの注意事項 - グローバルにインストールされているだけでなく、**アクティブな環境で Python 3.10+ を使用** していることを確認してください。 - OpenAI 互換の API キーは、**メモリ構築や検索を実行する前に設定** する必要があります。そうしないと初期化が失敗する場合があります。 - OpenAI 以外のプロバイダー（Qwen や Azure OpenAI など）を使用する場合は、`config.py` のモデル名と `OPENAI_BASE_URL` の両方を確認してください。 - 大規模な対話データセットの場合、並列処理を有効にするとメモリ構築時間を大幅に削減できます。 ### 📋 要件 - 🐍 Python 3.10+ - 🔑 OpenAI 互換 API（OpenAI、Qwen、Azure OpenAI など） ### 🛠️ セットアップ ```bash # 📥 リポジトリをクローン git clone https://github.com/aiming-lab/SimpleMem.git cd SimpleMem # 📦 依存関係をインストール（固定バージョン） pip install -r requirements.txt # — または — 編集可能なパッケージとしてインストール pip install -e . # デフォルト: テキスト + マルチモーダル + エボルバー pip install -e ".[server]" # + MCP / HTTP サーバー (mcp, fastapi, ...) pip install -e ".[all]" # 開発ツールを含むすべて # ⚙️ API 設定を構成 cp config.py.example config.py # config.py を API キーと設定で編集 ``` ### ⚙️ 設定例 ```python # config.py OPENAI_API_KEY = "your-api-key" OPENAI_BASE_URL = None # または Qwen/Azure 向けカスタムエンドポイント LLM_MODEL = "gpt-4.1-mini" EMBEDDING_MODEL = "Qwen/Qwen3-Embedding-0.6B" # 最先端の検索 ``` --- ## 🐳 Docker で実行 **MCP サーバー** は一貫した隔離された環境のために Docker で実行できます。データ（LanceDB とユーザー DB）はホストボリュームに永続化されます。 ### 前提条件 - [Docker](https://docs.docker.com/get-docker/) および [Docker Compose](https://docs.docker.com/compose/install/) ### クイック実行 ```bash # リポジトリルートから docker compose up -d ``` - **Web UI:** http://localhost:8000/ - **REST API:** http://localhost:8000/api/ - **MCP (SSE):** http://localhost:8000/mcp/sse?token=<TOKEN> データはホスト上の `./data` に保存されます（自動的に作成されます）。 ### カスタム設定 1. 環境テンプレートをコピーして編集します： ```bash cp .env.example .env # .env を編集: JWT_SECRET_KEY、ENCRYPTION_KEY、LLM_PROVIDER、モデル URL などを設定 ``` 2. env ファイルを指定して実行します： ```bash docker compose --env-file .env up -d ``` ### ホスト上の Ollama を使用する `LLM_PROVIDER=ollama` で Ollama がマシン上（Docker 内ではなく）で動作している場合、`.env` に以下を設定します： ```bash LLM_PROVIDER=ollama OLLAMA_BASE_URL=http://host.docker.internal:11434/v1 ``` Linux では、`host.docker.internal` は Compose ファイルを通じて自動的に有効になります。 ### 便利なコマンド ```bash docker compose logs -f simplemem # ログを追跡 docker compose down # コンテナを停止・削除 ``` > 📖 MCP サーバーのセルフホスティング（Docker またはベアメタル）については [MCP ドキュメント](../../MCP/README.md) を参照してください。 --- ## 🔌 MCP サーバー *(テキストメモリ)* SimpleMem は Model Context Protocol (MCP) を通じた **クラウドホスト型メモリサービス** として利用可能で、Claude Desktop、Cursor、その他の MCP 互換クライアントなどの AI アシスタントとのシームレスな統合を可能にします。 **🌐 クラウドサービス**: [mcp.simplemem.cloud](https://mcp.simplemem.cloud) — または [Docker](#-docker-で実行) を使用してローカルで MCP サーバーをセルフホスティング。 ### 主な機能 | 機能 | 説明 | |---------|-------------| | **Streamable HTTP** | JSON-RPC 2.0 を使用した MCP 2025-03-26 プロトコル | | **マルチテナント分離** | トークン認証によるユーザーごとのデータテーブル | | **ハイブリッド検索** | 意味検索 + キーワードマッチング + メタデータフィルタリング | | **プロダクション最適化** | OpenRouter 統合による高速レスポンスタイム | ### クイック設定 ```json { "mcpServers": { "simplemem": { "url": "https://mcp.simplemem.cloud/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } } ``` > 📖 詳細なセットアップ手順とセルフホスティングガイドについては [MCP ドキュメント](../../MCP/README.md) を参照してください --- ## 📊 論文結果の再現論文の LoCoMo / MemBench / Mem-Gallery の数値を再現します。各柱はそれ自身のディレクトリにベンチマークランナーを持っています。まずベンチマーク追加依存関係をインストールしてください：`pip install -e ".[benchmark]"`。 ### 📝 SimpleMem（テキスト）— LoCoMo リポジトリルートから実行： ```bash python test_locomo10.py # 完全な LoCoMo ベンチマーク python test_locomo10.py --num-samples 5 # クイックサブセット python test_locomo10.py --result-file my_results.json ``` ### 🧬 EvolveMem — 自己進化 + LoCoMo / MemBench `EvolveMem/` ディレクトリから実行（[`EvolveMem/README.md`](../../EvolveMem/README.md) を参照）： ```bash cd EvolveMem python run_evolution.py --data data/locomo10.json --max-rounds 7 python run_benchmark.py locomo --sample 0 --initial weak --max-rounds 3 python run_benchmark.py membench --agent FirstAgent --max-rounds 3 ``` ### 🧠 Omni-SimpleMem — LoCoMo / Mem-Gallery `OmniSimpleMem/` ディレクトリから実行（[`OmniSimpleMem/README.md`](../../OmniSimpleMem/README.md) を参照）： ```bash cd OmniSimpleMem python benchmarks/locomo/run_locomo.py --data-path /path/to/locomo10.json --model gpt-4o ``` --- ## 🗺️ ロードマップ統合チャネル別の現在の機能： | 機能 | Python (`pip install`) | MCP サーバー（Claude Desktop、Cursor など） | |:--|:--:|:--:| | テキストメモリ | ✅ | ✅ | | マルチモーダル（画像 / 音声 / 動画） | ✅ | ⬜ 計画中 | | `optimize()` 自己進化型検索 | ✅ | ⬜ 計画中 | ギャップを埋めるための計画的な作業（MCP サーバーはスタンドアロンのマルチテナントテキストサービスです。これらは実際の機能であり、ドキュメントの修正ではありません）： - [ ] **MCP 経由のマルチモーダル。** `memory_add_image` / `memory_add_audio` / `memory_add_video` ツールを追加。ファイルアップロードパス（base64 または URL、MCP はローカルファイルパスを渡せないため）、Omni-SimpleMem ストレージバックエンドのマルチテナント対応、サーバー側のビジョン/音声モデルアクセスが必要。 - [ ] **MCP 経由の EvolveMem。** `optimize()` を MCP ツールとして公開。マルチモーダルよりも実現可能（テキスト入力、JSON 設定出力、ファイル転送なし）ですが、MCP リトリーバーは現在、EvolveMem が進化させる約 10 次元のうち `semantic_top_k` / `keyword_top_k` のみをサポートしています。残りのノブ（structured top_k、フュージョンモード/重み、エンティティスワップ、クエリ分解、回答検証）をサポートするための MCP リトリーバーの拡張、テナントの保存メモリに対して進化ループを実行するアダプター、テナントごとの設定永続化、非同期実行（ループは LLM 負荷が高く、同期リクエストはタイムアウトする）が必要。 - [ ] **Docker** は MCP サーバーがサポートした時点で両方を自動的に継承（マルチモーダル依存関係をイメージに追加し、Omni ストレージボリュームを追加）。完全なマルチモーダルと自己進化型検索には、今すぐ Python API を使用してください（[クイックスタート](#-クイックスタート)を参照）。 --- ## 📝 引用 SimpleMem を研究に使用する場合は、以下を引用してください： ```bibtex @article{simplemem2026, title={SimpleMem: Efficient Lifelong Memory for LLM Agents}, author={Liu, Jiaqi and Su, Yaofeng and Xia, Peng and Zhou, Yiyang and Han, Siwei and Zheng, Zeyu and Xie, Cihang and Ding, Mingyu and Yao, Huaxiu}, journal={arXiv preprint arXiv:2601.02553}, year={2026}, url={https://arxiv.org/abs/2601.02553} } ``` ```bibtex @article{evolvemem2026, title={EvolveMem: Self-Evolving Memory Architecture via AutoResearch for LLM Agents}, author={Liu, Jiaqi and Ye, Xinyu and Xia, Peng and Zheng, Zeyu and Xie, Cihang and Ding, Mingyu and Yao, Huaxiu}, journal={arXiv preprint arXiv:2605.13941}, year={2026}, url={https://arxiv.org/abs/2605.13941} } ``` ```bibtex @article{omnisimplemem2026, title = {Omni-SimpleMem: Autoresearch-Guided Discovery of Lifelong Multimodal Agent Memory}, author = {Liu, Jiaqi and Ling, Zipeng and Qiu, Shi and Liu, Yanqing and Han, Siwei and Xia, Peng and Tu, Haoqin and Zheng, Zeyu and Xie, Cihang and Fleming, Charles and Ding, Mingyu and Yao, Huaxiu}, journal = {arXiv preprint arXiv:2604.01007}, year = {2026}, } ``` --- ## 📄 ライセンスこのプロジェクトは **MIT ライセンス** の下でライセンスされています — 詳細は [LICENSE](../../LICENSE) ファイルを参照してください。 --- ## 🙏 謝辞以下のプロジェクトとチームに感謝します： - 🔍 **埋め込みモデル**: [Qwen3-Embedding](https://github.com/QwenLM/Qwen) - 最先端の検索性能 - 🗄️ **ベクターデータベース**: [LanceDB](https://lancedb.com/) - 高性能なカラム型ストレージ - 📊 **ベンチマーク**: [LoCoMo](https://github.com/snap-research/locomo) - 長期コンテキストメモリ評価フレームワーク