telemem について
TeleMemは、長期記憶やキャラクターごとの記憶、動画記憶を必要とする対話システム向けのエージェントメモリレイヤーです。mem0互換APIやセマンティック検索、動画処理パイプラインを備え、ローカルでも動作します。
主な機能
- 01対話からの記憶情報の自動抽出
- 02キャラクター別の記憶プロファイル
- 03セマンティッククラスタリングと重複排除
- 04FAISSとJSONによる保存・検索
- 05動画フレーム・字幕・ベクトルの処理
- 06mem0互換API
活用シーン
- 01ロールプレイエージェントのキャラクター設定維持
- 02長い対話からの事実検索
- 03動画内容の保存と検索
- 04既存のMem0コードへのメモリ導入
MCP 対応
TeleMemは、MCPクライアント向けに8つのメモリツールを備えたMCPサーバーを提供します。`uvx telemem`でサーバーを登録できます。
設定
ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。
uvx telememOPENAI_API_KEYシークレットAPI key for the default OpenAI LLM/embedder (not needed with a local TELEMEM_CONFIG)TELEMEM_CONFIGPath to a TeleMem YAML/JSON config, e.g. the fully-local Ollama + FAISS setup (config/config.ollama.yaml)TELEMEM_DEFAULT_USER_IDDefault memory scope when tool calls omit user_id/agent_id/run_id (default: telemem-mcp)ローカルサーバーにはマシン上の実行環境(Node.js 18 以上など)が必要です。設定ファイルの場所はクライアントごとに異なります。
ツール
ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。
詳細
TeleMem:エージェント型 AI のための長期・マルチモーダルメモリの構築
このプロジェクトが役に立ったら、最新情報を受け取るために GitHub で ⭐️ を付けてください。
🤝 コントリビューションを歓迎します!お気軽に issue を作成するか、プルリクエストを送信してください。
TeleMem は、複雑な複数ターンの対話、キャラクターのモデリング、長期的な情報保存、セマンティック検索のシナリオに深く最適化された、エージェントメモリ管理レイヤーです。1 行のコード(import telemem as mem0)で導入できる、Mem0 の高性能なドロップイン置換として使用できます。
独自のコンテキスト認識型拡張メカニズムにより、TeleMem は会話型 AI に、より高い精度、より高速なパフォーマンス、より強力なキャラクターメモリ機能を備えたコアインフラストラクチャを提供します。
この基盤の上に、TeleMem は動画理解、マルチモーダル推論、視覚的な質問応答機能を実装しています。動画フレーム抽出、キャプション生成、ベクトルデータベース構築という一連のパイプラインにより、AI エージェントはテキストのメモリと同じように、動画コンテンツを簡単に保存、検索、推論できます。
TeleMem プロジェクトの究極の目標は、_エージェントの回顧を活用して、その先見性を高めること_です。
TeleMem は、記憶を受け継ぎ、知性を育みます。
TeleMem を選ぶ理由
- 🎭 適切なキャラクターメモリ — キャラクターごとに分離されたメモリプロファイルを自動構築する唯一のオープンソースメモリレイヤーです。ロールプレイ、コンパニオン AI、NPC、複数のペルソナを持つアシスタント向けに設計されています。
- 🎬 テキストだけでなく、動画にも対応するメモリ — 動画 → フレーム → キャプション → ベクトル DB の完全なパイプラインと、ReAct 形式の複数ステップ動画 QAを備えています。
- 🏠 デフォルトで完全ローカル — お使いのハードウェア上で、Qwen と FAISS を使ってエンドツーエンドで動作します。クラウドサービスも有料プランもなく、データがマシンの外部に送信されることもありません。
- 🔌 mem0 互換 API —
add()/search()は同じ引数を受け付け、同じ{"results": [...]}形式を返すため、既存の Mem0 コードをそのまま使用できます。
📢 最新情報
- [2026-08-15] 🎉 TeleMem v1.10.0 では、初の DeepSeek Harness サポートが追加されました。オプトイン方式の Cordis/MCP パッチにより、
uvxで TeleMem を起動し、8 つすべてのメモリツールをmcp__telemem__*として登録し、プロバイダー設定を安全に転送します。MCP サーバーのドキュメントをご覧ください。 - [2026-08-06] 🎉 TeleMem v1.9.0 は最新の MCP 標準に対応しました。公式 MCP Python SDK v2(spec 2026-07-28)に移行し、8 つすべてのツールでタイトル、動作アノテーション、構造化出力を宣言しながら、従来の MCP クライアントとの互換性も維持しています。MCP サーバーのドキュメントをご覧ください。
- [2026-07-11] 🎉 TeleMem v1.8.0 — 「claims = contracts」リリースです。キャラクターメモリ抽出の修正、
infer=False/prompt/memory_typeの完全な反映、オフラインで実行できる契約テストスイート、テレメトリーのデフォルト無効化、そして 複数 NPC のデモ を追加しました! - [2026-06-12] 🎉 TeleMem v1.7.1 が 公式 MCP レジストリで公開されました。インストール不要でメモリサーバーを実行できます:
uvx telemem!また、評価の原則と、ベースラインを組み込んだ LongMemEval ハーネスも追加されました。 - [2026-06-12] 🎉 TeleMem が PyPI で公開されました:
pip install telemem!v1.6.0 では Ollama/DeepSeek/Kimi の設定、LangChain と LlamaIndex のサンプル、そしてドキュメントサイトが追加されました。 - [2026-06-12] 🎉 TeleMem v1.5.0 をリリースしました。mem0 の完全なドロップイン API、軽量なコアインストール、CI を追加しました!
- [2026-06-11] 🎉 MCP サポートを備えた TeleMem v1.4.0 をリリースしました!
- [2026-01-28] 🎉 TeleMem v1.3.0 をリリースしました!
- [2026-01-22] 🎉 TeleMem のテクニカルレポートを第 4 版に更新しました!
- [2026-01-13] 🎉 TeleMem のテクニカルレポートが arXiv で公開されました!
- [2026-01-09] 🎉 TeleMem v1.2.0 をリリースしました!
- [2025-12-31] 🎉 TeleMem v1.1.0 をリリースしました!
- [2025-12-05] 🎉 TeleMem v1.0.0 をリリースしました!
🔥 研究のハイライト
- メモリ精度を大幅に向上:ZH-4O 中国語マルチキャラクター長時間対話ベンチマークで 86.33% の精度を達成し、Mem0 を 19% 上回りました。
- 処理速度が 2 倍に向上:効率的なバッファリングとバッチ書き込みにより、ミリ秒単位のセマンティック検索を実現しました。
- トークンコストを大幅に削減:トークン使用量を最適化し、LLM のオーバーヘッドを大幅に抑えながら同等の性能を実現しました。
- キャラクターメモリを正確に保持:各キャラクターの独立したメモリプロファイルを自動で構築し、混同を防ぎます。
- 動画処理パイプラインを自動化:生動画からフレーム抽出、キャプション生成、ベクトルデータベースへの登録までを完全に自動化します。
- ReAct スタイルの動画 QA:複数段階の推論とツール呼び出しにより、動画の内容を正確に理解します。
📌 目次
- プロジェクトの紹介
- TeleMem と Mem0:主な利点
- 実験結果
- クイックスタート
- プロジェクト構成
- 主な機能
- マルチモーダル拡張
- MCP サーバー
- フレームワーク連携
- データストレージの説明
- テレメトリとプライバシー
- 開発と貢献
- 謝辞
- 引用
プロジェクトの紹介
TeleMem は、キャラクターを考慮した要約 → セマンティッククラスタリングによる重複排除 → 効率的な保存 → 高精度な検索という、綿密に最適化されたパイプラインを通じて、会話型 AI が長期的なやり取りの中で安定した、自然で一貫性のある世界観とキャラクター設定を維持できるようにします。
flowchart LR
A["Dialogue<br/>messages"] --> B["Character-aware<br/>summarization<br/>(global + per-character)"]
B --> C["Embedding +<br/>similar-memory<br/>retrieval"]
C --> D["Write buffer<br/>(batch flush)"]
D --> E["LLM semantic<br/>clustering & fusion"]
E --> F[("FAISS index +<br/>JSON metadata")]
Q["Query"] --> S["Vector search<br/>+ rerank"]
F --> S
S --> R["results"]
特長
- メモリの自動抽出:対話から重要な事実を抽出し、構造化します。
- セマンティッククラスタリングと重複排除:LLM を使用して類似したメモリを意味的に統合し、矛盾を減らして一貫性を高めます。
- キャラクタープロファイル別のメモリ管理:対話内の各キャラクターに個別のメモリアーカイブを構築し、正確な分離とパーソナライズされた管理を実現します。
- 効率的な非同期書き込み:バッファーと一括フラッシュの仕組みを採用し、高性能で安定した永続化を実現します。
- 高精度なセマンティック検索:FAISS と JSON の二重ストレージを組み合わせ、高速な想起と人が読める監査可能性を実現します。
適用シナリオ
-
複数のキャラクターを扱う仮想エージェントシステム
-
長期記憶を備えた AI アシスタント(例:カスタマーサービス、コンパニオン、創作コパイロット)
-
仮想環境における複雑な物語や世界構築
-
文脈への依存度が高い対話シナリオ
-
動画コンテンツの QA と推論
-
マルチモーダルエージェントのメモリ管理
-
長時間動画の理解と情報検索

TeleMem と Mem0:主な利点
TeleMem は、キャラクター性の表現、長期記憶、高性能の課題に対応するため、Mem0 を大幅に再構成しています。主な違いは次のとおりです。
| 機能の側面 | Mem0 | TeleMem |
|---|---|---|
| 複数キャラクターの分離 | ❌ 非対応 | ✅ キャラクターごとに独立したメモリプロファイルを自動作成 |
| 要約の品質 | 基本的な要約 | ✅ 重要なエンティティ、アクション、タイムスタンプを網羅する文脈対応型・キャラクター重視のプロンプト |
| 重複排除の仕組み | ベクトル類似度によるフィルタリング | ✅ LLM ベースのセマンティッククラスタリング:LLM を介して類似したメモリを統合 |
| 書き込み性能 | ストリーミングによる単一書き込み | ✅ 一括フラッシュと並行処理:書き込みを 2~3 倍高速化 |
| ストレージ形式 | SQLite / ベクトル DB | ✅ FAISS と JSON メタデータへの二重書き込み:高速検索と人が読める形式 |
| マルチモーダル機能 | 画像からテキストへの変換のみ | ✅ 動画マルチモーダルメモリ:動画処理パイプライン全体と ReAct による複数ステップの推論 QA |
実験結果
データセット
論文 MOOM: Maintenance, Organization and Optimization of Memory in Ultra-Long Role-Playing Dialogues で構築された ZH-4O 中国語長編キャラクター対話データセットを用いて評価します。
- 平均対話長:会話あたり 600 ターン
- シナリオ:日常的なやり取り、プロットの進行、変化するキャラクター間の関係
メモリ機能は、次のような QA ベンチマークを用いて評価しました。
{
"question": "What is Zhao Qi's nickname for Bai Yulan? A Xiaobai B Xiaoyu C Lanlan D Yuyu",
"answer": "A"
},
{
"question": "What is the relationship between Zhao Qi and Bai Yulan? A Classmates B Teacher and student C Enemies D Neighbors",
"answer": "B"
}
実験構成
-
LLM:Qwen3-8B(思考モード無効)
-
埋め込みモデル:Qwen3-Embedding-8B
-
指標:QA 精度
手法 全体(%) RAG 62.45 Mem0 70.20 MOOM 72.60 A-mem 73.78 Memobase 76.78 TeleMem 86.33
クイックスタート
インストール
pip install telemem # core (text memory)
pip install "telemem[mcp]" # + MCP server
pip install "telemem[video]" # + video/multimodal pipeline
pip install "telemem[all]" # everything
開発環境
uv を使用します(推奨 — コミット済みの uv.lock から .venv を作成し、再現可能な環境を構築します)。
uv sync --all-extras # install TeleMem (editable) + all extras, incl. MCP
uv run python examples/quickstart.py
または、conda + pip を使用します。
# Create and activate virtual environment
conda create -n telemem python=3.10
conda activate telemem
# Install from source (editable), with the extras you need
pip install -e ".[all]"
使用例
OpenAI API キーを設定します。
export OPENAI_API_KEY="your-openai-api-key"
# python examples/quickstart.py
import telemem as mem0
memory = mem0.Memory()
messages = [
{"role": "user", "content": "Jordan, did you take the subway to work again today?"},
{"role": "assistant", "content": "Yes, James. The subway is much faster than driving. I leave at 7 o'clock and it's just not crowded."},
{"role": "user", "content": "Jordan, I want to try taking the subway too. Can you tell me which station is closest?"},
{"role": "assistant", "content": "Of course, James. You take Line 2 to Civic Center Station, exit from Exit A, and walk 5 minutes to the company."}
]
memory.add(messages=messages, user_id="Jordan")
results = memory.search("What transportation did Jordan use to go to work today?", user_id="Jordan")
for hit in results["results"]: # same result shape as mem0
print(hit["memory"])
Memory() は、mem0ai から引き継いだデフォルトのプロバイダー設定を使用します。このリポジトリのローカル Qwen + FAISS 構成を使用するには、config/config.yaml を明示的に読み込みます。
from telemem.utils import load_config
import telemem as mem0
config = load_config("config/config.yaml")
memory = mem0.Memory(config=config)
実行可能なサンプルでも、TELEMEM_CONFIG を通じて同じ構成を使用できます。
TELEMEM_CONFIG=config/config.yaml python examples/quickstart.py
LLM プロバイダーとして MiniMax を使用する
TeleMem は、OpenAI 互換 API を介して LLM バックエンドとして MiniMax をサポートしています。
すぐに使用できるサンプル構成が config/config.minimax.yaml に用意されています。
export MINIMAX_API_KEY="your-minimax-api-key"
export OPENAI_API_KEY="your-openai-api-key" # still needed for embeddings
from telemem.utils import load_config
import telemem as mem0
config = load_config("config/config.minimax.yaml")
memory = mem0.Memory(config=config)
MiniMax の使用に関する主なポイント:
- LLM:
MiniMax-M3.1-Flash(デフォルト)またはMiniMax-M3を使用できます。どちらもコンテキストウィンドウは 1,000,000 トークンで、テキスト/画像/動画の入力に対応しています。既存の構成では、レガシーモデルやカスタムモデルを含め、明示的に指定されたモデル ID が維持されます。 - リージョン別エンドポイント:
openai_base_urlには、https://api.minimax.io/v1(グローバル)またはhttps://api.minimax.cn/v1(中国)を使用します。既存のカスタムエンドポイント値は維持されます。 - 思考:Flash は常にアダプティブ思考を使用し、指定がない場合は推論の強度が
maxになります。プリセットではis_reasoning_model: trueが設定されているため、mem0 は省略可能なreasoning_effort(low、medium、high、xhigh、max)を転送し、小さなデフォルトのトークン上限を省略します。Flash では、思考の無効化、reasoning_effort="none"、service_tier、reasoning_split=falseはサポートされません。詳しくは OpenAI 互換 API の仕様 をご覧ください。 - ツール履歴:LLM アダプターを直接呼び出す場合は、mem0 の
response_callbackを使って SDK のアシスタントメッセージ全体を取得し、次の呼び出し時にツールの結果とともに追加してください。reasoning_contentとtool_callsの両方を保持してください。アダプターの簡略化された戻り値は、アシスタントメッセージ全体ではありません。 - 温度:固定値 1 を使用する Flash と M3 では無視されます。
- 埋め込み:MiniMax は公開埋め込み API を提供していません。
embedderセクションで別の埋め込みモデル(例:text-embedding-3-small)を設定してください。
その他の LLM プロバイダー
TeleMem はあらゆる OpenAI 互換エンドポイントで動作します。すぐに使える設定例が config/ に用意されています。
| プロバイダー | 設定ファイル | LLM | 埋め込み | 備考 |
|---|---|---|---|---|
| Ollama(完全ローカル) | config.ollama.yaml | 任意のローカルモデル(例:qwen3:8b) | nomic-embed-text、ローカル | API キー不要、クラウド不要 — すべてお使いのマシン上で実行されます |
| DeepSeek | config.deepseek.yaml | deepseek-chat / deepseek-reasoner | 外部(例:OpenAI) | DEEPSEEK_API_KEY + OPENAI_API_KEY |
| Moonshot (Kimi) | config.moonshot.yaml | kimi-k2-0905-preview | 外部(例:OpenAI) | .cn と .ai のエンドポイントに対応 |
| MiniMax | config.minimax.yaml | MiniMax-M3.1-Flash / MiniMax-M3 | 外部(例:OpenAI) | 上記のセクションを参照 |
TELEMEM_CONFIG=config/config.ollama.yaml python examples/quickstart.py # 100% local memory
プロジェクト構成
ディレクトリ構成を展開/折りたたむ
telemem/
├── assets/ # Documentation assets and figures
├── baselines/ # Baseline implementations for comparative evaluation
│ ├── RAG # Retrieval-Augmented Generation baseline
│ ├── MemoBase # MemoBase memory management system
│ ├── MOOM # MOOM dual-branch narrative memory framework
│ ├── A-mem # A-mem agent memory baseline
│ └── Mem0 # Mem0 baseline implementation
├── config/
│ ├── config.yaml # TeleMem default configuration
│ └── config.minimax.yaml # MiniMax provider example configuration
├── data/ # Small sample datasets for evaluation or demonstration
├── examples/ # Code examples and tutorial demos
│ ├── quickstart.py # Quick start
│ ├── quickstart_mm.py # Quick start (multimodal)
│ ├── mcp_client.py # Quick start over MCP (stdio client)
│ ├── mcp_config.json # MCP config snippet for Claude Desktop / Cursor
│ └── deepseek-harness.cordis.yml # DeepSeek Harness memory patch
├── docs/
│ ├── MCP.md # MCP server reference
│ └── TeleMem_Tech_Report.pdf
├── telemem/ # Telemem code
│ └── mcp/ # Model Context Protocol server
├── tests/ # Telemem test
├── README.md # English README
├── README-ZH.md # Chinese README
└── pyproject.toml # Python environment
主な機能
メモリの追加(add)
add() メソッドは、1 つ以上の対話ターンをメモリシステムに追加します。
def add(
self,
messages,
*,
user_id: Optional[str] = None,
agent_id: Optional[str] = None,
run_id: Optional[str] = None,
metadata: Optional[Dict[str, Any]] = None,
infer: bool = True,
memory_type: Optional[str] = None,
prompt: Optional[str] = None,
batch: bool = False,
)
🔎 パラメーターの説明
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
messages | str or List[Dict[str, str]] | ✅ はい | 1 つの発話、または role(user/assistant)と content を含む対話メッセージのリスト |
user_id | Optional[str] | ❌ いいえ | メモリを関連付けるキャラクター/ユーザー。TeleMem は**user_id ごとに独立したメモリプロファイル**を保持します。省略すると、共有の会話イベントメモリとして保存されます |
agent_id / run_id | Optional[str] | ❌ いいえ | mem0 互換の追加スコープ(例:セッションごとに 1 つの run_id) |
metadata | Optional[Dict[str, Any]] | ❌ いいえ | 各メモリとともに保存される任意のメタデータ |
infer | bool | ❌ いいえ | LLM で重要な事実を抽出します(デフォルト:True)。False にすると、LLM を呼び出さずにメッセージ内容をそのまま保存します |
memory_type | Optional[str] | ❌ いいえ | mem0 のパイプラインで手続きメモリを作成するには "procedural_memory" を指定します。会話メモリの場合は省略します |
prompt | Optional[str] | ❌ いいえ | カスタム抽出プロンプト(最適化されたデフォルトをシステムプロンプトとして置き換えます) |
batch | bool | ❌ いいえ | 高スループットのバッチ処理パイプライン(add_batch)を使用します |
戻り値は mem0 互換の形式です:{"results": [{"id": "...", "memory": "...", "event": "ADD"}, ...]}
🔁 add() の内部ワークフロー
- メッセージの前処理:同じ話者からの連続するメッセージを統合し、ターン構造を正規化します。
- 複数の視点からの要約:
- 全体的なイベントの要約
- キャラクター 1 の視点(行動、好み、人間関係)
- キャラクター 2 の視点
- ベクトル化と類似検索:埋め込みを生成し、類似する既存のメモリを取得します。
- バッチ処理:バッファーのしきい値に達すると、LLM を呼び出して類似するメモリを意味的に統合します。
- 永続化:**FAISS(検索用)とJSON(メタデータ用)**に二重書き込みします。
🎭 複数キャラクターのデモ:examples/multi_npc.py では、5 人の酒場の NPC が 1 つのシーンを体験します。
add_batch(scene, user_id=[...])を 1 回呼び出すと、各 NPC に非公開のメモリプロファイルが作成され、共有の"events"ワールドステートも作成されます。その後、各 NPC はそれぞれの視点からシーンを思い出します。
メモリの検索(search)
コンテキストを考慮した想起により、意味ベースのベクトル検索で関連するメモリを取得します。
def search(
self,
query: str,
*,
user_id: Optional[str] = None,
agent_id: Optional[str] = None,
run_id: Optional[str] = None,
limit: int = 100,
filters: Optional[Dict[str, Any]] = None,
threshold: Optional[float] = None,
rerank: bool = True,
)
🔎 パラメーターの説明
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
query | str | ✅ はい | 自然言語によるクエリ |
user_id | Optional[str] | ❌ いいえ | 検索対象のキャラクター/ユーザープロファイル。共有イベントメモリ(疑似ユーザー "events")も常に検索されます |
agent_id / run_id | Optional[str] | ❌ いいえ | mem0 互換の追加スコープフィルター |
limit | int | ❌ いいえ | 結果の最大数(デフォルト:100) |
threshold | Optional[float] | ❌ いいえ | 類似度のしきい値(0~1。省略した場合は自動調整されます) |
filters | Dict[str, Any] | ❌ いいえ | カスタムフィルター(例:キャラクター、時間範囲による絞り込み) |
rerank | bool | ❌ いいえ | 結果を再ランキングするかどうか(デフォルト:True) |
戻り値は mem0 互換の形式です:{"results": [{"id": "...", "memory": "...", "score": ..., ...}, ...]}
🔍 検索には FAISS ベクトル検索を使用し、ミリ秒単位で応答します。
マルチモーダル拡張機能
テキストメモリに加えて、TeleMem はマルチモーダル機能もさらに拡張しています。Deep Video Discovery のエージェント型検索とツール使用のアプローチに着想を得て、動画コンテンツのインテリジェントな保存と意味検索に対応する 2 つの主要なメソッドを TeleMemory クラスに実装しました。
| メソッド | 説明 |
|---|---|
add_mm() | 動画を検索可能なメモリに変換します(フレーム抽出 → キャプション生成 → ベクトルデータベース) |
search_mm() | 自然言語を使用して動画コンテンツを検索します。ReAct スタイルの複数ステップ推論に対応しています |
マルチモーダルメモリの追加(add_mm)
def add_mm(
self,
video_path: str,
output_dir: str,
clip_secs: int | None = None,
emb_dim: int | None = None,
subtitle_path: str | None = None,
)
🔎 パラメーターの説明
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
| video_path | str | ✅ はい | 元動画ファイルのパス。例:"video/3EQLFHRHpag.mp4" |
| output_dir | str | ✅ はい | 出力ルートディレクトリ。生成物は frames/、captions/、vdb/ サブディレクトリに書き込まれます |
| clip_secs | int | ❌ いいえ | 予約済みパラメーター。クリップの長さは現在 config.vlm["CLIP_SECS"] から読み込まれます |
| emb_dim | int | ❌ いいえ | 埋め込み次元。デフォルトでは設定から読み込まれます |
| subtitle_path | str | ❌ いいえ | 字幕ファイルのパス(.srt)。省略可能です |
🔁 add_mm() の内部処理
- フレーム抽出:
decode_video_to_frames- 設定された FPS で動画を JPEG フレームにデコードします - キャプション生成:
process_video- VLM(例:Qwen3-Omni)を使用して、各クリップの詳細な説明を生成します - ベクトルデータベースの構築:
init_single_video_db- 意味検索用の埋め込みを生成します
💡 スマートキャッシュ:処理段階の出力先ファイルがすでに存在する場合、計算リソースを節約するため、その段階は自動的にスキップされます。
戻り値の例
{
"output_dir": "/abs/path/to/output_dir"
}
マルチモーダルメモリの検索(search_mm)
def search_mm(
self,
question: str,
output_dir: str,
max_iterations: int = 15,
)
🔎 パラメーターの説明
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
| question | str | ✅ はい | 質問文(A/B/C/D の選択式形式に対応) |
| output_dir | str | ✅ はい | add_mm で使用したものと同じ出力ルートディレクトリ。captions/*/captions.json が 1 つ、vdb/*/*_vdb.json が 1 つだけ含まれている必要があります |
| max_iterations | int | ❌ いいえ | MMCoreAgent の推論の最大反復回数(デフォルト:15) |
🛠️ ReAct スタイルの推論ツール
search_mm は内部で MMCoreAgent を使用し、3 つの専用ツールによる THINK → ACTION → OBSERVATION のループを実行します。
| ツール名 | 機能 |
|---|---|
global_browse_tool | 動画のイベントやテーマの全体像を取得します |
clip_search_tool | 意味クエリを使用して特定のコンテンツを検索します |
frame_inspect_tool | 特定の時間範囲内のフレームの詳細を調べます |
マルチモーダルの例
マルチモーダルデモを実行します:
python examples/quickstart_mm.py
初回実行時に、フレーム、キャプション、VDB JSON が選択した output_dir の下に生成されます。リポジトリには小さなサンプル動画が含まれています。キャプションと動画データベースを生成するには、これらのアーティファクトがすでにローカルにない限り、VLM と埋め込みサービスの設定が必要です。
コードの完全な例:
import telemem as mem0
from pathlib import Path
from telemem.mm_utils.core import extract_choice_from_msg
# Initialize
memory = mem0.Memory()
# Define paths
repo_root = Path(__file__).resolve().parents[1]
video_path = repo_root / "data" / "samples" / "video" / "3EQLFHRHpag.mp4"
video_name = video_path.stem
output_dir = video_path.parent
# Step 1: Add video to memory (auto-processing)
vdb_json_path = output_dir / "vdb" / video_name / f"{video_name}_vdb.json"
if not vdb_json_path.exists():
result = memory.add_mm(
video_path=str(video_path),
output_dir=str(output_dir),
)
print(f"Video processing complete: {result}")
else:
print(f"VDB already exists: {vdb_json_path}")
# Step 2: Query video content
question = """The problems people encounter in the video are caused by what?
(A) Catastrophic weather.
(B) Global warming.
(C) Financial crisis.
(D) Oil crisis.
"""
messages = memory.search_mm(
question=question,
output_dir=str(output_dir),
max_iterations=15,
)
# Extract final answer
answer = extract_choice_from_msg(messages)
print(f"Answer: ({answer})")
MCP サーバー
TeleMem には Model Context Protocol(MCP)サーバーが含まれているため、MCP 対応クライアント(Claude Desktop、Claude Code、Cursor、カスタムエージェントなど)から TeleMem を長期記憶として利用できます。
pip install telemem
telemem-mcp # stdio (default)
telemem-mcp --transport streamable-http # Streamable HTTP on :8421
TELEMEM_CONFIG=config/config.yaml telemem-mcp # custom TeleMem config
uvx telemem # zero-install run (stdio)
公式 MCP Python SDK v2 を基盤とするこのサーバーは、古いクライアントとの互換性を保ちながら、現在の MCP 仕様(2026-07-28)を実装しています。すべてのツールで、タイトル、動作アノテーション(読み取り専用/破壊的操作のヒント)、構造化出力を宣言しています。
このサーバーは、add_memory、search_memories、get_memories、get_memory、update_memory、delete_memory、delete_all_memories、memory_history の 8 つのツールを公開しています。スコープが明示されていない呼び出しでは、デフォルトで TELEMEM_DEFAULT_USER_ID(telemem-mcp)が使用されます。破壊的な一括削除では、常に明示的なスコープが必要です。
Claude Desktop / Cursor の設定(examples/mcp_config.json):
{
"mcpServers": {
"telemem": {
"command": "telemem-mcp",
"env": {
"TELEMEM_CONFIG": "/absolute/path/to/config/config.yaml",
"OPENAI_API_KEY": "sk-..."
}
}
}
}
または、stdio 経由でプログラムから実行できます。クイックスタートの流れを MCP ツール呼び出しで行います:
python examples/mcp_client.py
ツールの詳細なリファレンス、トランスポート、クライアントの設定については、docs/MCP.md を参照してください。
フレームワークとの統合
TeleMem は、回答前に search()、各やり取りの後に add() を呼び出すという同じ 2 つの呼び出しで、あらゆるエージェントフレームワークに組み込めます:
| フレームワーク | 例 | インストール |
|---|---|---|
| LangChain | examples/langchain_memory.py | pip install langchain-core langchain-openai |
| LlamaIndex | examples/llamaindex_memory.py | pip install llama-index-llms-openai |
| Claude Desktop / Cursor / あらゆる MCP クライアント | MCP サーバー | pip install "telemem[mcp]" |
TeleMem は mem0 API と互換性があるため、Mem0 の OSS クライアント向けに作成されたフレームワークアダプターも、telemem.Memory を指定すれば使用できます。
データストレージ
テキストメモリのストレージ
TeleMem は、セッションとキャラクターごとに整理された構造化ストレージを ./faiss_db/ の下に自動で作成します:
faiss_db/
├── session_001_events.index
├── session_001_events_meta.json
├── session_001_person_1.index
├── session_001_person_1_meta.json
├── session_001_person_2.index
└── session_001_person_2_meta.json
📄 メタデータの例(_meta.json)
{
"summary": "Characters discussed the upcoming action plan.",
"sample_id": "session_001",
"round_index": 3,
"timestamp": "2024-01-01T00:00:00Z",
"user": "Jordan" // Only present in person_*.json
}
すべてのメモリには、監査やデバッグに役立つよう、要約、ラウンド番号、タイムスタンプ、キャラクターが含まれます。
マルチモーダルメモリのストレージ
TeleMem は、動画関連のストレージファイルを .data/samples/video/ ディレクトリに生成します:
video/
├── frames/
│ └── <video_name>/
│ └── frames/
│ ├── frame_000001_n0.00.jpg
│ ├── frame_000002_n0.50.jpg
│ └── ...
├── captions/
│ └── <video_name>/
│ ├── captions.json # Clip descriptions + subject registry
│ └── ckpt/ # Checkpoint for resume
│ ├── 0_10.json
│ └── 10_20.json
└── vdb/
└── <video_name>/
└── <video_name>_vdb.json # Semantic retrieval vector database
📄 captions.json の構造
{
"0_10": {
"caption": "The narrator discusses climate data, showing melting glaciers..."
},
"10_20": {
"caption": "Scene shifts to coastal communities affected by rising sea levels..."
},
"subject_registry": {
"narrator": {
"name": "narrator",
"appearance": ["professional attire"],
"identity": ["climate scientist"],
"first_seen": "00:00:00"
}
}
}
テレメトリとプライバシー
TeleMem 自体はテレメトリを収集しません。基盤となる mem0ai ライブラリには匿名化された PostHog 使用状況テレメトリが含まれていますが、TeleMem ではデフォルトで無効になっています
(すでに設定されていない限り、import telemem によって MEM0_TELEMETRY=False が設定されます)。
再度有効にするには:
export MEM0_TELEMETRY=true
開発と貢献
- Issue とプルリクエストを歓迎します。始めるには、貢献ガイドをご覧ください。
- リリース間の変更は変更履歴で追跡されています。
- CI では、すべての PR を対象に、Python 3.10~3.12 でオフラインテストスイート(
uv run pytest tests/ -q)を実行します。 - 中国語ドキュメント:README-ZH.md
ライセンス
謝辞
TeleMemの開発は、オープンソースコミュニティと最先端の研究から多大な影響を受けています。以下のプロジェクトとチームに心より感謝申し上げます。
📑 引用
TeleMemが研究や開発に役立った場合は、arXiv論文を引用してください。
Chunliang Chen, Ming Guan, Xiao Lin, Jiaxu Li, Luxi Lin, Qiyi Wang, Xiangyu Chen, Jixiang Luo, Changzhi Sun, Dell Zhang, Xuelong Li. TeleMem: Building Long-Term and Multimodal Memory for Agentic AI. arXiv:2601.06037, 2026. https://arxiv.org/abs/2601.06037
@article{chen2026telemem,
title = {TeleMem: Building Long-Term and Multimodal Memory for Agentic AI},
author = {Chen, Chunliang and Guan, Ming and Lin, Xiao and Li, Jiaxu and Lin, Luxi and Wang, Qiyi and Chen, Xiangyu and Luo, Jixiang and Sun, Changzhi and Zhang, Dell and Li, Xuelong},
journal = {arXiv preprint arXiv:2601.06037},
year = {2026},
url = {https://arxiv.org/abs/2601.06037}
}
引用情報はCITATION.cffでもご確認いただけます(GitHubの「このリポジトリを引用」ボタン)。
このプロジェクトが役に立った場合は、⭐️を付けてください。スターを付けると、GitHubフィードで最新情報も確認できます。
Bloo-Mind AI LtdとTeleAIのUbiquitous AGIチームが❤️を込めて開発しました。
mcp-name: io.github.TeleAI-UAGI/telemem
コメント
AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。
