telemem

TeleMem：为 Agentic AI 构建长期记忆与多模态记忆

TeleMem 是一个 Agent 记忆管理层，可作为 Mem0 的高性能即插即用替代方案，只需一行代码（import telemem as mem0），针对涉及多轮对话、角色建模、长期信息存储和语义检索的复杂场景进行了深度优化。

通过独特的上下文感知增强机制，TeleMem 为对话式 AI 提供核心基础设施，带来更高的准确性、更快的性能和更强的角色记忆能力。

基于此，TeleMem 实现了视频理解、多模态推理和视觉问答能力。借助完整的视频帧提取、字幕生成和向量数据库构建流程，AI Agent 可以像处理文本记忆一样，轻松地存储、检索和推理视频内容。

TeleMem 项目的最终目标是：利用 Agent 的事后经验改善其未来判断。

TeleMem，让记忆延续，让智能不断增强。

为什么选择 TeleMem？

• 🎭 真正做好角色记忆 — 唯一能自动构建相互隔离的角色专属记忆档案的开源记忆层，专为角色扮演、陪伴型 AI、NPC 和多人格助手打造。
• 🎬 记忆不止于文本，还涵盖视频 — 完整的视频 → 帧 → 字幕 → 向量数据库流程，并支持 ReAct 风格的多步视频问答。
• 🏠 默认完全本地运行 — 全流程在您的硬件上运行（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（规范版本 2026-07-28）——全部 8 个工具现在均声明了标题、行为注解和结构化输出，同时兼容旧版 MCP 客户端。请参阅 MCP 服务文档。
• [2026-07-11] 🎉 TeleMem v1.8.0 ——“声明即契约”版本：修复角色记忆提取问题，全面支持 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] 🎉 TeleMem v1.4.0 已发布，新增 MCP 支持！
• [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%。
• 速度性能翻倍：借助高效缓冲和批量写入，实现毫秒级语义检索。
• 大幅降低 Token 成本：优化 Token 使用量，在保持相同性能的同时显著降低大模型开销。
• 精准保留角色记忆：自动为每个角色建立独立的记忆档案，避免混淆。
• 自动化视频处理流水线：从原始视频 → 帧提取 → 字幕生成 → 向量数据库，全程自动化
• ReAct 风格的视频问答：通过多步推理 + 工具调用，精准理解视频内容

📌 目录

• 项目简介
• 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"]

特性

• 自动提取记忆：从对话中提取并整理关键信息。
• 语义聚类与去重：使用大模型在语义层面合并相似记忆，减少冲突并提升一致性。
• 角色化记忆管理：为对话中的每个角色建立独立的记忆档案，确保精准隔离和个性化管理。
• 高效异步写入：采用缓冲区 + 批量刷新机制，实现高性能、稳定的持久化。
• 精准语义检索：结合 FAISS + JSON 双重存储，实现快速召回和人类可读的审计能力。

适用场景

• 多角色虚拟 Agent 系统

• 长期记忆 AI 助手（例如客服、陪伴、创意协作助手）

• 虚拟环境中的复杂叙事／世界构建

• 上下文依赖性强的对话场景

• 视频内容问答与推理

• 多模态 Agent 记忆管理

• 长视频理解与信息检索

  

TeleMem 与 Mem0：核心优势

TeleMem 深度重构了 Mem0，着力解决角色化、长期记忆和高性能问题。主要区别如下：

实验结果

数据集

我们在论文 MOOM: Maintenance, Organization and Optimization of Memory in Ultra-Long Role-Playing Dialogues 中构建的 ZH-4O 中文长篇角色对话数据集上进行评估：

• 对话平均长度：每段对话 600 轮
• 场景：日常互动、情节推进、角色关系演变

我们通过问答基准测试评估记忆能力，例如：

{
"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

• 指标：问答准确率

  方法	总体（%）
  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

使用 MiniMax 作为 LLM 提供方

TeleMem 支持通过 OpenAI 兼容 API 使用 MiniMax 作为 LLM 后端。 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 个 token 的上下文窗口，以及文本／图像／视频输入。现有配置会保留其显式指定的模型 ID，包括旧版和自定义模型。
• 区域端点：将 https://api.minimax.io/v1（全球）或 https://api.minimax.cn/v1（中国）用作 openai_base_url；现有的自定义端点值会予以保留。
• 思考：Flash 始终使用自适应思考；若未指定，则推理力度为 max。预设配置将 is_reasoning_model: true，以便 mem0 转发可选的 reasoning_effort（low、medium、high、xhigh 或 max），并省略其较小的默认 token 上限。Flash 不接受禁用思考、reasoning_effort="none"、service_tier 和 reasoning_split=false。详情请参阅 OpenAI 兼容 API 合约。
• 工具历史记录：直接调用 LLM 适配器时，使用 mem0 的 response_callback 捕获完整的 SDK 助手消息，并在下次调用时将其与工具结果一并附加。保留 reasoning_content 和 tool_calls；适配器的简化返回值并非完整的助手消息。
• 温度：Flash 和 M3 会忽略温度设置，并使用固定值 1。
• 嵌入：MiniMax 不提供公开的嵌入 API；请在 embedder 部分配置单独的嵌入器（例如 text-embedding-3-small）。

更多大模型提供方

TeleMem 适用于任何与 OpenAI 兼容的端点。config/ 中附带了可直接使用的配置示例：

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() 方法会将一轮或多轮对话注入记忆系统。

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,
)

🔎 参数说明

返回值为与 mem0 兼容的格式：{"results": [{"id": "...", "memory": "...", "event": "ADD"}, ...]}

🔁 add() 的内部工作流

1. 消息预处理：合并同一发言者连续发送的消息；规范化轮次结构。
2. 多视角摘要：
   • 全局事件摘要
   • 角色 1 的视角（行动、偏好、人际关系）
   • 角色 2 的视角
3. 向量化与相似度搜索：生成嵌入，并检索已有的相似记忆。
4. 批处理：达到缓冲区阈值时，调用大模型对相似记忆进行语义合并。
5. 持久化：双写入 FAISS（用于检索） 和 JSON（用于元数据）。

🎭 多角色演示：examples/multi_npc.py 会让五位酒馆 NPC 共同经历一个场景——一次 add_batch(scene, user_id=[...]) 调用就能为每位 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,
)

🔎 参数说明

返回值为与 mem0 兼容的结构：{"results": [{"id": "...", "memory": "...", "score": ..., ...}, ...]}

🔍 搜索基于 FAISS 向量检索，可实现毫秒级响应。

多模态扩展

除了文本记忆，TeleMem 还进一步扩展了多模态能力。受 Deep Video Discovery 的 Agentic 搜索和工具使用方法启发，我们在 TeleMemory 类中实现了两种核心方法，以支持视频内容的智能存储和语义检索。

添加多模态记忆（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,
)

🔎 参数说明

🔁 add_mm() 内部流程

1. 帧提取：decode_video_to_frames——以配置的 FPS 将视频解码为 JPEG 帧
2. 字幕生成：process_video——使用 VLM（例如 Qwen3-Omni）为每个片段生成详细描述
3. 向量数据库构建：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,
)

🔎 参数说明

🛠️ ReAct 风格的推理工具

search_mm 内部使用 MMCoreAgent，通过 THINK → ACTION → OBSERVATION 循环调用三个专用工具：

多模态示例

运行多模态演示：

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、自定义 Agent——都可以将 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。未明确指定范围的调用默认使用 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 可集成到任何 Agent 框架中，只需进行相同的两次调用——回答前调用 search()，每次交互后调用 add()：

由于 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

开发与贡献

• 欢迎提交问题和拉取请求——请参阅贡献指南了解如何开始。
• 各版本之间的变更记录在变更日志中。
• 对每个 PR，CI 都会在 Python 3.10–3.12 上运行离线测试套件（uv run pytest tests/ -q）。
• 中文文档：README-ZH.md

许可证

Apache 2.0 许可证

致谢

TeleMem 的开发深受开源社区和前沿研究的启发。我们谨向以下项目和团队致以诚挚谢意：

• Mem0
• Memobase
• MOOM
• DVD
• Memento
• Momento-Skills

📑 引用

如果 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：为 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 的“引用此仓库”按钮）。

   

_{mcp-name: io.github.TeleAI-UAGI/telemem}