面向大型语言模型代理的高效终身记忆——文本与多模态

以语义无损压缩技术存储、压缩并检索长期记忆。现新增对文本、图像、音频及视频的多模态支持。兼容Claude、Cursor、LM Studio等多种平台。

适用于任何支持MCP或Python集成的AI平台

Claude Desktop

Cursor

LM Studio

Cherry Studio

PyPI软件包

+ 任意MCP 客户端

🇨🇳 中文 • 🇯🇵 日本語 • 🇰🇷 한국어 • 🇪🇸 Español • 🇫🇷 Français • 🇩🇪 Deutsch • 🇧🇷 Português
🇷🇺 Русский • 🇸🇦 العربية • 🇮🇹 Italiano • 🇻🇳 Tiếng Việt • 🇹🇷 Türkçe

🚀 快速入门 • 🌟 概述 • 📈 结果 • 🧠 Omni-SimpleMem • 📦 安装 • 🔄 跨会话记忆 • 🔌 MCP服务器 • 📝 引用

🔥 最新消息

• [04/02/2026] 🧠 Omni-SimpleMem——多模态记忆现已上线！ SimpleMem现支持文本、图像、音频及视频记忆。在LoCoMo（F1=0.613，提升47%）和Mem-Gallery（F1=0.810，提升51%）两项基准测试中，均超越现有最佳水平。Omni-SimpleMem为您的代理带来最先进的多模态终身记忆功能。查看Omni-SimpleMem →
• [02/09/2026] 🚀 跨会话记忆上线——性能比Claude-Mem提升64%！ SimpleMem现支持跨对话的持久化记忆。在LoCoMo基准测试中，SimpleMem相比Claude-Mem实现了64%的性能提升。您的代理现在能够自动回忆起先前会话中的上下文、决策及学习成果。查看跨会话文档 →
• [01/20/2026] SimpleMem现已上架PyPI！ 📦 您可直接通过pip install simplemem进行安装。查看软件包使用指南 →
• [01/19/2026] 为SimpleMem技能新增本地内存存储功能！ 💾 SimpleMem技能现可在Claude Skills中支持本地内存存储。
• [01/18/2026] SimpleMem现已支持Claude Skills！ 🚀 您可在claude.ai中使用SimpleMem实现跨对话的长期记忆。请前往mcp.simplemem.cloud注册账号、配置Token，并导入该技能！
• [01/14/2026] SimpleMem MCP服务器现已上线且开源！ 🎉 位于mcp.simplemem.cloud的云端记忆服务已正式启用。可通过可流式传输的HTTP MCP协议与LM Studio、Cherry Studio、Cursor以及Claude Desktop等平台集成。查看MCP文档 →
• [01/08/2026] 🔥 欢迎加入我们的Discord和微信交流群，共同协作、交流想法！
• [01/05/2026] SimpleMem论文已在arXiv上发表！

📑 目录

• 🚀 快速入门
• 🌟 概述
• 📈 结果
• 📝 SimpleMem：文本记忆
• 🧠 Omni-SimpleMem：多模态记忆
• 📦 安装
• 🐳 Docker
• 🔌 路由工具
• 🔄 会话间记忆
• 🔌 MCP 服务器
• 🗺️ 路线图
• 📊 评估
• 📝 引用

🚀 快速入门

🧠 理解基本工作流程

从高层次来看，SimpleMem 是一个用于基于 LLM 的智能体的长期记忆系统。其工作流程包含三个简单步骤：

1. 存储信息——对话或事实被处理并转化为结构化的原子级记忆。
2. 索引记忆——通过语义嵌入和结构化元数据对存储的记忆进行组织。
3. 检索相关记忆——当收到查询时，SimpleMem 会根据语义而非关键词来检索最相关的信息。

这种设计使 LLM 智能体能够保持上下文、高效地回忆过往信息，并避免重复处理冗余的历史记录。

🎓 基本使用方法

SimpleMem 提供了一个统一的入口点 simplemem_router。默认的 mode="auto" 会根据你调用的方法自动检测应使用哪个后端，无需手动配置：

import simplemem_router as simplemem

mem = simplemem.create()  # mode="auto" — 后端由首次调用决定

你首次调用的方法决定了所使用的后端：

import simplemem_router as simplemem

mem = simplemem.create()  # 自动模式

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

import simplemem_router as simplemem

mem = simplemem.create()  # 自动模式

# add_image() → 自动选择多模态后端
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()

💡 小贴士：自动模式会根据你的数据选择最轻量的后端。如果你更倾向于明确指定模式，也可以直接使用 mode="text" 或 mode="omni"。

🚄 高级：并行处理

对于大规模对话处理，可以启用并行模式：

import simplemem_router as simplemem

mem = simplemem.create(
    mode="text",
    clear_db=True,
    enable_parallel_processing=True,  # ⚡ 并行构建记忆
    max_parallel_workers=8,
    enable_parallel_retrieval=True,   # 🔍 并行执行查询
    max_retrieval_workers=4
)

💡 专业提示：并行处理可显著降低批量操作的延迟！

🌟 概述

SimpleMem 是一系列高效的记忆框架——用于文本的 SimpleMem 和用于多模态（文本、图像、音频、视频）的 Omni-SimpleMem——基于 语义无损压缩，旨在解决 LLM 智能体长期记忆效率 的根本挑战。与现有系统不同，后者要么被动积累冗余上下文，要么依赖昂贵的迭代推理循环，SimpleMem 通过三阶段流水线最大化了 信息密度 和 token 利用率：

关于多模态记忆，请参阅下方的 Omni-SimpleMem。

SimpleMem 架构：(1) 语义结构化压缩过滤掉低效对话，将有价值的信息窗口转化为紧凑、与上下文无关的记忆单元。(2) 在线语义合成在写入过程中整合相关片段，保持记忆拓扑的紧凑性和连贯性。(3) 意图感知检索规划推断搜索意图，调整检索范围和查询形式，实现多视角并行检索和 token 效率高的上下文构建。

🏆 性能对比

SimpleMem 以极低的 token 开销（约 550）实现了卓越的 F1 分数（43.24%），位于理想左上角位置。

速度对比演示

SimpleMem 与基线：实时速度对比演示

📈 结果

📊 基准测试结果（LoCoMo）

🧠 Omni-SimpleMem 结果

📝 SimpleMem：文本记忆

1️⃣ 语义结构化压缩

SimpleMem 在 LLM 生成过程中集成了一种 隐式语义密度门控机制，用于过滤冗余的交互内容。系统将原始对话流重新构建为 紧凑的记忆单元——包含已解析的核心指代和绝对时间戳的自洽事实。每个单元通过三种互补的表示方式进行索引，以实现灵活的检索：

✨ 示例转换：

- 输入：  "他明天下午两点会见鲍勃"  [❌ 相对、模糊]
+ 输出： "爱丽丝将于 2025 年 11 月 16 日 14:00:00 在星巴克会见鲍勃"  [✅ 绝对、原子]

2️⃣ 在线语义合成

与依赖异步后台维护的传统系统不同，SimpleMem 在写入阶段 实时进行合成。相关记忆单元会在当前会话范围内被合成为更高层次的抽象表示，从而允许重复或结构相似的经历被 立即去噪并压缩。

✨ 示例合成：

- 片段 1： "用户想要咖啡"
- 片段 2： "用户喜欢燕麦奶"
- 片段 3： "用户喜欢热的"
+ 整合后： "用户喜欢热燕麦奶咖啡"

这种主动合成确保了记忆拓扑结构保持紧凑，避免冗余碎片化。

3️⃣ 意图感知检索规划

不同于固定深度的检索，SimpleMem 利用 LLM 的推理能力生成一个 全面的检索计划。给定查询时，规划模块会推断出 潜在的搜索意图，以动态确定检索范围和深度：

$${ q_{\text{sem}}, q_{\text{lex}}, q_{\text{sym}}, d } \sim \mathcal{P}(q, H)$$

随后，系统会跨语义、词汇和符号索引执行 并行多视角检索，并通过基于 ID 的去重合并结果：

📈 结果：F1 得分为 43.24%，且所需 token 数量仅为全上下文方法的 三十分之一。

Omni-SimpleMem 将 SimpleMem 扩展至 统一的多模态记忆——支持文本、图像、音频和视频体验，并在所有五种经过测试的 LLM 后端中均表现出最先进的准确性。

其构建基于三大原则：选择性摄入（针对每种模态的熵驱动过滤）、渐进式检索（FAISS 和 BM25 混合搜索，结合金字塔式 token 预算扩展）以及 知识图谱增强（多跳跨模态推理）。

📖 完整文档、基准测试及架构详情：Omni-SimpleMem →

📦 安装

📝 新手须知

• 请确保您使用的 Python 3.10 是活动环境中的版本，而不仅仅是全局安装的版本。
• 必须在运行任何记忆构建或检索操作之前配置好兼容 OpenAI 的 API 密钥，否则初始化可能会失败。
• 使用非 OpenAI 提供商（如 Qwen 或 Azure OpenAI）时，请务必在 config.py 中验证模型名称和 OPENAI_BASE_URL。
• 对于大型对话数据集，启用并行处理可以显著缩短记忆构建时间。

📋 需求

• 🐍 Python 3.10
• 🔑 兼容 OpenAI 的 API（OpenAI、Qwen、Azure OpenAI 等）

🛠️ 设置

# 📥 克隆仓库
git clone https://github.com/aiming-lab/SimpleMem.git
cd SimpleMem

# 📦 安装依赖
pip install -r requirements.txt

# ⚙️ 配置 API 设置
cp config.py.example config.py
# 根据您的 API 密钥和偏好编辑 config.py

⚙️ 配置示例

# 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 和用户数据库）会持久化到主机卷中。

先决条件

• Docker 和 Docker Compose

快速运行

# 从仓库根目录
docker compose up -d

• Web UI: http://localhost:8000/
• REST API: http://localhost:8000/api/
• MCP（SSE）: http://localhost:8000/mcp/sse?token=

数据存储在主机的 ./data 目录中（自动创建）。

自定义配置

1. 复制环境模板并编辑：

   cp .env.example .env
   # 编辑 .env：设置 JWT_SECRET_KEY、ENCRYPTION_KEY、LLM_PROVIDER、模型 URL 等
   

2. 使用该环境文件运行：

   docker compose --env-file .env up -d
   

在主机上使用 Ollama

当 LLM_PROVIDER=ollama 且 Ollama 在您的机器上运行（而非在 Docker 容器中）时，请在 .env 文件中设置：

LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://host.docker.internal:11434/v1

在 Linux 系统上，host.docker.internal 会通过 Compose 文件自动启用。

常用命令

docker compose logs -f simplemem   # 实时查看日志
docker compose down                 # 停止并移除容器

📖 如需自行部署 MCP 服务器（Docker 或裸金属环境），请参阅 MCP 文档。

🔌 路由器工具

路由器采用基于注册表的工厂模式——后端仅在请求时才会被延迟加载，并且会在实例化前检查依赖项是否满足。

import simplemem_router as simplemem

# 列出所有已注册的模式
simplemem.list_modes()
# {'text': '单模态文本记忆，支持语义无损压缩',
#  'omni': '多模态记忆——文本、图像、音频、视频（Omni-SimpleMem)'}

# 检查某模式的依赖项是否已满足
simplemem.is_available("omni")  # True / False

# 检查自动选择的模式
mem = simplemem.create()
print(mem.mode)  # "auto"（待定）、"text" 或 "omni"

# 注册自定义后端
simplemem.register(
    mode="my_backend",
    module_path="my_package.memory",
    class_name="MyMemorySystem",
    description="自定义记忆后端",
    required_deps=["my_package"],
)
mem = simplemem.create(mode="my_backend")

❓ 常见设置问题与故障排除

如果您在首次设置或运行 SimpleMem 时遇到问题，请检查以下常见情况：

1️⃣ API 密钥未检测到

• 确保您的 API 密钥已在 config.py 中正确设置。
• 对于兼容 OpenAI 的提供商（如 Qwen、Azure 等），请确认 OPENAI_BASE_URL 是否配置正确。
• 更新密钥后，请重启 Python 环境。

2️⃣ Python 版本不匹配

• SimpleMem 需要 Python 3.10。
• 使用以下命令检查您的 Python 版本：

  python --version
  

🔄 跨会话记忆 (文本记忆)

SimpleMem-Cross 在 SimpleMem 的基础上扩展了持久化的跨对话记忆功能。智能体可以回忆起之前会话中的上下文、决策和观察结果，从而实现对话间的连续性，而无需手动重新注入上下文。

主要特性

快速示例

from cross.orchestrator import create_orchestrator

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

    # 开始会话——自动注入先前的上下文
    result = await orch.start_session(
        content_session_id="session-001",
        user_prompt="继续构建 REST API",
    )
    print(result["context"])  # 来自先前会话的相关上下文

    # 在会话中记录事件
    await orch.record_message(result["memory_session_id"], "用户询问关于 JWT 的问题")
    await orch.record_tool_use(
        result["memory_session_id"],
        tool_name="read_file",
        tool_input="auth/jwt.py",
        tool_output="class JWTHandler: ...",
    )

    # 结束会话——提取观察结果、生成摘要并存储记忆
    report = await orch.stop_session(result["memory_session_id"])
    print(f"已存储 {report.entries_stored} 条记忆")

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

架构

智能体框架（Claude Code / Cursor / 自定义）
                    |
     +--------------+--------------+
     |                             |
钩子/生命周期适配器      HTTP/MCP API（FastAPI）
     |                             |
     +--------------+--------------+
                    |
           CrossMemOrchestrator
                    |
  +-----------------+------------------+
  |                 |                  |
会话管理器  上下文注入器  整合优化
（SQLite）         （按预算打包） （衰减/合并/修剪）
  |                 |                  |
  +---------+-------+                  |
            |                          |
   跨会话向量存储（LanceDB） <--+

模块参考

📖 更多详细的 API 文档，请参阅 跨会话 README。

🔌 MCP 服务器 (文本记忆)

SimpleMem 可作为一款基于模型上下文协议（MCP）的云端记忆服务提供，能够与 Claude Desktop、Cursor 等兼容 MCP 的 AI 助手无缝集成。

🌐 云服务: mcp.simplemem.cloud — 或者您也可以使用 Docker 在本地自建 MCP 服务器。

主要特性

快速配置

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

📖 更多详细的设置说明和自建指南，请参阅 MCP 文档。

🗺️ 路线图

Omni-SimpleMem 基础设施 —— 将多模态记忆引入所有共享组件：

• Omni 跨会话记忆（文本 + 图像 + 音频 + 视频持久化）
• Omni MCP 服务器（通过 MCP 协议实现多模态记忆）
• Omni Docker 支持
• Omni PyPI 包（pip install omni-simplemem）
• Omni Claude Skills 集成

核心改进：

• 流式摄取，用于实时记忆更新
• 多智能体之间的记忆共享
• 基准测试扩展（更多多模态基准）

欢迎贡献！请开一个 issue 进行讨论。

📊 评估

🧪 运行基准测试

# 🎯 完整 LoCoMo 基准测试
python test_locomo10.py

# 📉 子集评估（5 个样本）
python test_locomo10.py --num-samples 5

# 💾 自定义输出文件
python test_locomo10.py --result-file my_results.json

🔬 复现论文结果

请使用 config.py 中的精确配置：

• 🚀 高性能：GPT-4.1-mini、Qwen3-Plus
• ⚙️ 高效：Qwen2.5-1.5B、Qwen2.5-3B
• 🔍 嵌入：Qwen3-Embedding-0.6B（1024 维）

📝 引用

如果您在研究中使用了 SimpleMem，请引用以下内容：

@article{simplemem2025,
  title={SimpleMem: 针对 LLM 智能体的高效终身记忆},
  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 预印本 arXiv:2601.02553},
  year={2025},
  url={https://github.com/aiming-lab/SimpleMem}
}

@article{omnisimplemem2026,
  title   = {Omni-SimpleMem：自主研究引导的终身多模态智能体记忆发现},
  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 预印本 arXiv:2604.01007},
  year    = {2026},
}

📄 许可证

本项目采用 MIT 许可证——详情请参阅 LICENSE 文件。

🙏 致谢

我们感谢以下项目和团队：

• 🔍 嵌入模型：Qwen3-Embedding - 业界领先的检索性能
• 🗄️ 向量数据库：LanceDB - 高性能列式存储
• 📊 基准测试：LoCoMo - 长上下文记忆评估框架

SimpleMem 快速上手指南

SimpleMem 是一个专为 LLM Agent 设计的高效长期记忆系统，支持文本及多模态（图像、音频、视频）数据的存储、压缩与检索。它通过语义无损压缩技术，帮助 Agent 跨会话保留关键上下文，显著提升信息密度与召回效率。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：Python 3.9 或更高版本
• 前置依赖：
  • pip (Python 包管理工具)
  • 若使用多模态功能，建议安装对应的多媒体处理库（如 pillow, pydub 等，通常由包自动处理或按需安装）
• 网络环境：首次安装需访问 PyPI 官方源。国内用户可配置清华或阿里镜像源以加速下载。

安装步骤

1. 配置国内镜像源（推荐）

为了获得更快的下载速度，建议在安装前临时指定国内镜像源：

# 使用清华大学镜像源
pip install simplemem -i https://pypi.tuna.tsinghua.edu.cn/simple

或者永久配置：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

2. 安装 SimpleMem

执行以下命令安装最新稳定版：

pip install simplemem

基本使用

SimpleMem 提供了统一的入口 simplemem_router，默认开启 auto 模式。该模式会根据你调用的第一个方法自动判断后端：

• 调用对话相关方法（如 add_dialogue）→ 自动启用 Text 模式（纯文本记忆）。
• 调用多模态方法（如 add_image, add_audio）→ 自动启用 Omni 模式（多模态记忆）。

场景一：文本记忆（自动模式）

适用于记录对话、事实陈述等纯文本信息。

import simplemem_router as simplemem

# 创建实例，mode="auto" 会根据后续调用自动选择后端
mem = simplemem.create()

# 添加对话记录
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?")
print(answer)
# 输出示例："16 November 2025 at 2:00 PM at Starbucks"

场景二：多模态记忆（自动模式）

适用于混合了文本、图片、音频或视频的复杂场景。

import simplemem_router as simplemem

# 创建实例
mem = simplemem.create()

# 添加多模态数据（自动切换至 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()

进阶：开启并行处理

如果需要处理大规模对话数据，可以启用并行模式以显著降低延迟：

import simplemem_router as simplemem

mem = simplemem.create(
    mode="text",
    clear_db=True,
    enable_parallel_processing=True,  # 启用并行记忆构建
    max_parallel_workers=8,           # 设置构建线程数
    enable_parallel_retrieval=True,   # 启用并行查询
    max_retrieval_workers=4           # 设置查询线程数
)