simplemem

SimpleMem

通过语义无损压缩，为大模型 Agent 提供高效的终身记忆。

SimpleMem 将非结构化对话转换为紧凑、原子化的记忆单元，并进行共指消解和时间锚定。在 LoCoMo 基准测试中，它的 F1 达到 43.24%，所需 Token 比完整上下文方法少 30 倍。

集成方式

选择适合你使用场景的方式：

方式	最适合	配置
MCP 服务（云端）	快速上手，支持多平台	仅需配置
MCP 服务（自托管）	隐私保护，自定义部署	Docker 或 Python
Python API（pip install simplemem）	编程式集成	pip/uv
SimpleMem-Cross	跨会话 Agent 记忆	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 界面：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 直连 - 设置 OPENAI_API_KEY
• OpenRouter - 设置 OPENROUTER_API_KEY，并在模型名称前加上提供商前缀
• LiteLLM - 多提供商抽象层，通过 LITELLM_* 设置进行配置
• Azure OpenAI - 将 OPENAI_BASE_URL 设置为你的 Azure 端点
• Qwen / 本地模型 - 将 OPENAI_BASE_URL 设置为你的端点

完整配置请参阅 references/api-reference.md。

跨会话记忆（SimpleMem-Cross）

SimpleMem-Cross 支持跨对话的持久记忆。Agent 可以自动回忆之前会话中的上下文、决策和经验。

性能： 在 LoCoMo 基准测试中，得分为 48，相较于 Claude-Mem 的 29.3 提高了 64%。

快速示例

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，并完整跟踪事件
自动注入上下文	在会话开始时注入基于 Token 预算的先前会话上下文
事件收集	消息、工具使用、文件更改，并进行 3 层脱敏
观察提取	使用启发式方法提取决策、发现和经验
来源追踪	每条记忆都链接回源证据
整合	自动衰减、合并和清理旧记忆

完整 API 和架构请参阅 references/cross-session.md。

三阶段流水线

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]	Agent 来源
source	String	来源标识符

故障排除

嵌入维度不匹配：

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

配置中的 EMBEDDING_DIMENSION 与模型的输出不匹配。请更新该值并清空数据库：rm -rf data/lancedb/*

未检测到 API 密钥：

• 确认密钥已设置在 config.py 中（而非 config.py.example）
• 对于 OpenRouter 密钥，请确保其以 sk-or- 开头
• 更新密钥后重新启动 Python

找不到模型：

• OpenRouter 请使用完整的提供方路径：openai/gpt-4.1-mini，而非 gpt-4.1-mini
• 在 openrouter.ai/models 查看可用模型