simplemem

SimpleMem

意味的な可逆圧縮による、LLM エージェント向けの効率的な生涯メモリーです。

SimpleMem は、照応解析と時間的なアンカリングを用いて、構造化されていない対話をコンパクトで原子的なメモリーユニットに変換します。LoCoMo ベンチマークで F1 スコア 43.24% を達成し、フルコンテキスト方式と比べてトークン数を 30 分の 1 に削減します。

統合方法

ユースケースに合った方法を選んでください。

方法	最適な用途	セットアップ
MCP サーバー（クラウド）	すばやく開始、複数プラットフォーム	設定のみ
MCP サーバー（セルフホスト）	プライバシー、カスタムデプロイ	Docker または Python
Python API（pip install simplemem）	プログラムによる統合	pip/uv
SimpleMem-Cross	セッションをまたぐエージェントメモリー	Python + オーケストレーター

MCP サーバーのセットアップ（推奨）

クラウドサービス

最もすばやく利用を開始できます。mcp.simplemem.cloud のホストサービスを使用します。

1. https://mcp.simplemem.cloud にアクセスします
2. OpenRouter API キーを入力して、認証トークンを取得します
3. MCP クライアントの設定に追加します。

Claude Desktop / Claude Code（~/.claude.json）：

{
  "mcpServers": {
    "simplemem": {
      "url": "https://mcp.simplemem.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Cursor（.cursor/mcp.json）：

{
  "mcpServers": {
    "simplemem": {
      "url": "https://mcp.simplemem.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

セルフホスト（Docker）

プライバシーに配慮したデプロイやカスタムインフラストラクチャ向けです。

git clone https://github.com/aiming-lab/SimpleMem.git
cd SimpleMem/MCP

# Configure environment
export JWT_SECRET_KEY="your-secure-random-secret"
export ENCRYPTION_KEY="your-32-byte-encryption-key!!"

# Run with Docker
docker compose up -d

サーバーが公開するエンドポイント：

• Web UI：http://localhost:8000/
• REST API：http://localhost:8000/api/
• MCP エンドポイント：http://localhost:8000/mcp

セルフホストの詳細なガイドは、references/mcp-setup.md を参照してください。

利用可能な MCP ツール

ツール	用途
memory_add	対話を保存します（原子的な事実に自動圧縮）
memory_add_batch	複数の対話をまとめて保存します
memory_query	保存済みメモリーに対する意味的な質問応答
memory_retrieve	生のメモリーエントリーを取得します
memory_delete	entry_id または ref_id でエントリーを削除します
memory_stats	ストレージの統計情報
memory_clear	すべてのメモリーを削除します（取り消し不可）

Python API

pip または uv でインストールします。

pip install simplemem
# or
uv add simplemem

基本的な使い方

from simplemem import SimpleMemSystem

# Initialize (uses config.py for API settings)
system = SimpleMemSystem(clear_db=True)

# Stage 1: Add dialogues (semantic structured compression)
system.add_dialogue("Alice", "Let's meet at Starbucks tomorrow at 2pm", "2025-11-15T14:30:00")
system.add_dialogue("Bob", "I'll bring the market analysis report", "2025-11-15T14:31:00")

# Finalize atomic encoding
system.finalize()

# Stage 3: Query with intent-aware retrieval
answer = system.ask("When and where will Alice and Bob meet?")
# "16 November 2025 at 2:00 PM at Starbucks"

並列処理

大規模な対話データセットの場合：

system = SimpleMemSystem(
    clear_db=True,
    enable_parallel_processing=True,
    max_parallel_workers=8,
    enable_parallel_retrieval=True,
    max_retrieval_workers=4
)

メモリーの削除

ID でエントリーを削除します。

# Delete by entry_id
system.vector_store.delete_by_id(entry_id="uuid-here")

# Delete by ref_id (application-level reference)
system.vector_store.delete_by_ref_id(ref_id="my-ref")

設定

SimpleMem は、OpenAI 互換の任意の API プロバイダーに対応しています。

# config.py
OPENAI_API_KEY = "your-api-key"         # OpenAI, OpenRouter, or compatible
OPENAI_BASE_URL = None                   # Set for non-OpenAI providers

# Models
LLM_MODEL = "gpt-4.1-mini"              # Or any OpenAI-compatible model
EMBEDDING_MODEL = "Qwen/Qwen3-Embedding-0.6B"  # State-of-the-art retrieval

# Via OpenRouter (multi-provider gateway)
OPENROUTER_API_KEY = "sk-or-..."
LLM_MODEL = "openai/gpt-4.1-mini"       # OpenRouter model path
EMBEDDING_MODEL = "qwen/qwen3-embedding-8b"
EMBEDDING_DIMENSION = 4096

プロバイダーのオプション：

• OpenAI direct - OPENAI_API_KEY を設定します
• OpenRouter - OPENROUTER_API_KEY を設定し、モデル名にプロバイダーをプレフィックスとして付けます
• LiteLLM - マルチプロバイダー抽象化。LITELLM_* 設定で構成します
• Azure OpenAI - OPENAI_BASE_URL を Azure エンドポイントに設定します
• Qwen / local models - OPENAI_BASE_URL をエンドポイントに設定します

設定の詳細は、references/api-reference.md を参照してください。

セッションをまたぐメモリー（SimpleMem-Cross）

SimpleMem-Cross は、会話をまたいで永続するメモリーを実現します。エージェントは、前のセッションのコンテキスト、意思決定、学びを自動的に想起できます。

パフォーマンス： LoCoMo ベンチマークで Claude-Mem を 64% 上回ります（スコア 48 対 29.3）。

簡単な例

from cross.orchestrator import create_orchestrator

async def main():
    orch = create_orchestrator(project="my-project")

    # Start session - previous context injected automatically
    result = await orch.start_session(
        content_session_id="session-001",
        user_prompt="Continue building the REST API",
    )
    print(result["context"])  # Relevant context from past sessions

    # Record events during the session
    await orch.record_message(result["memory_session_id"], "User asked about JWT")
    await orch.record_tool_use(
        result["memory_session_id"],
        tool_name="read_file",
        tool_input="auth/jwt.py",
        tool_output="class JWTHandler: ...",
    )

    # Finalize - extracts observations, generates summary, stores memories
    report = await orch.stop_session(result["memory_session_id"])
    print(f"Stored {report.entries_stored} memory entries")

    await orch.end_session(result["memory_session_id"])
    orch.close()

主な機能

機能	説明
セッションのライフサイクル	完全なイベント追跡を伴う start -> record -> stop -> end
コンテキストの自動挿入	セッション開始時に、トークン予算に合わせた前回セッションのコンテキストを挿入
イベント収集	メッセージ、ツールの使用、ファイルの変更を 3 段階の編集処理付きで収集
観察結果の抽出	意思決定、発見、学びをヒューリスティックに抽出
出典の追跡	すべてのメモリーを元の証拠に紐付け
統合	古いメモリーの減衰、統合、刈り込みを自動実行

API とアーキテクチャの詳細は、references/cross-session.md を参照してください。

3 段階のパイプライン

SimpleMem のアーキテクチャは、意味的な可逆圧縮に基づいています。

ステージ 1：意味的な構造化圧縮

生の対話を、原子的で自己完結したメモリーユニットに変換します。

• 照応解析：「He」を「Bob」に変換
• 時間的なアンカリング：「tomorrow」を「2025-11-16T14:00:00」に変換
• 密度ゲーティング：情報量の少ない内容を除外

Input:  "He'll meet Bob tomorrow at 2pm"
Output: "Alice will meet Bob at Starbucks on 2025-11-16T14:00:00"

ステージ 2：オンラインでの意味統合

書き込み中に関連する断片を統合します。

• 冗長な情報を排除します
• 関連する事実を統一された表現にまとめます
• コンパクトなメモリトポロジーを維持します

ステージ 3：意図を考慮した検索計画

クエリに応じて、複数の視点から並列検索を実行します。

• 意味レイヤー：密なベクトル類似度（1024 次元の埋め込み）
• 語彙レイヤー：BM25 によるキーワード照合
• 記号レイヤー：メタデータによるフィルタリング（人物、場所、タイムスタンプ、エンティティ）
• クエリの複雑さに応じて検索の深さを動的に調整します

詳しいアーキテクチャについては、references/architecture.md を参照してください。

データモデル

各メモリエントリには、次の項目が含まれます。

フィールド	型	説明
entry_id	UUID	一意の識別子
ref_id	String	アプリケーションレベルの参照（削除用）
lossless_restatement	String	自己完結型の原子的事実
keywords	List[str]	BM25 検索用の主要なキーワード
timestamp	ISO 8601	イベントが発生した日時
location	String	場所（自然言語）
persons	List[str]	言及されている人物
entities	List[str]	企業、製品、組織
topic	String	トピックを表す語句
agents	List[str]	エージェントのソース
source	String	出所を示す識別子

トラブルシューティング

埋め込み次元の不一致：

RuntimeError: lance error: Invalid: ListType can only be casted to FixedSizeListType

config の EMBEDDING_DIMENSION がモデルの出力と一致していません。値を更新し、データベースを消去してください：rm -rf data/lancedb/*

API キーが検出されない場合：

• キーが config.py（config.py.example ではありません）に設定されていることを確認してください
• OpenRouter のキーの場合、sk-or- で始まっていることを確認してください
• キーを更新した後、Python を再起動してください

モデルが見つからない場合：

• OpenRouter では完全なプロバイダーパスを使用してください：gpt-4.1-mini ではなく openai/gpt-4.1-mini
• 利用可能なモデルを openrouter.ai/models で確認してください