基于 Kimi K3 的 Mem0 Agent（LOCOMO 基准）

源文件：chapter3/mem0/README.md

基于 Kimi K3 的 Mem0 Agent（LOCOMO 基准）

一个将 Mem0 记忆框架与 Kimi K3 语言模型相结合的进阶 AI Agent 实现，专为 LOCOMO（长上下文多智能体）基准设计。

概览

本项目实现了一个先进的对话式 AI Agent，具备以下特点：

• 持久化记忆：使用 Mem0 框架在多次会话间管理长期记忆
• 先进语言模型：集成 Kimi K3 模型（具备 100 万 token 上下文窗口；实验中将用量限制在更小的预算内）
• LOCOMO 基准：在长上下文多智能体通信任务上评估 Agent 表现
• 多会话支持：在多次会话间维持上下文与一致性
• 多智能体协作：支持多个共享记忆的 Agent 协同工作

特性

核心能力

• 动态记忆管理：自动抽取、整合并检索相关信息
• 上下文保持：跨会话、跨 Agent 维持对话上下文
• 性能指标：跟踪一致性、连贯性、响应时间与记忆利用率
• 灵活后端：支持本地与云端两种记忆存储

基准场景

LOCOMO 基准包含五类场景：

1. 协同规划：多个 Agent 共同规划复杂项目
2. 信息共享：Agent 跨会话共享并整合信息
3. 问题求解：带记忆留存的多步问题求解
4. 谈判协商：带立场跟踪的多轮谈判
5. 教学相长：带进度跟踪的教学对话

安装

前置条件

• Python 3.8 或更高版本
• Kimi API 密钥（来自 Moonshot AI）
• 可选：Mem0 云端 API 密钥（用于云存储）

安装步骤

1. 克隆仓库：

cd projects/week2/mem0
​

2. 安装依赖：

pip install -r requirements.txt
​

3. 配置环境变量：

cp env.example .env
# 编辑 .env，填入你的 API 密钥和配置
​

所需环境变量：

• KIMI_API_KEY：你的 Kimi K3 API 密钥
• MODEL_NAME：模型名（默认：kimi-k3）。这里填的是 Moonshot 原始模型
  id（如 kimi-k3、kimi-k2.5、kimi-k2.6），直接透传给 API——切勿
  使用 provider/model 这种斜杠形式；Mem0 配置的是指向 Moonshot
  base_url 的 openai provider，会把字符串原样转发，写成 kimi/k3 会返回
  "Not found the model"。
• MEMORY_BACKEND：存储后端（local/cloud）
• MAX_TOKENS：最大 token 上限（默认：128000）

快速开始

基本用法

运行快速入门示例，观察 Agent 的实际表现：

python quickstart.py
​

它会演示：

• 带记忆的基础对话
• 跨会话的记忆持久化
• 多智能体协作

记忆管线演示（提取—对比—决策）

最能体现 Mem0 价值——其 ADD / UPDATE / DELETE /
NOOP 管线以及跨会话召回——的是 demo 模式：

python main.py --mode demo --user-id demo_user
​

它复现了书中（chapter3.md）的核心示例：用户先说自己住在北京，后续又说搬到了上海，
Mem0 通过 UPDATE（修订已有记忆）来解决冲突，而不是存下两条互相矛盾的记录。
其间还会通过语义检索召回一条已存记忆，展示记忆被"后续使用"。同一流程也对应
quickstart.py 中的 memory_pipeline_example()，由 python quickstart.py 首先运行。

直接操作记忆的命令行

Mem0 的记忆 API 被直接暴露出来，让你无需对话循环也能观察每一步管线决策。
所有参数都有中文 --help（python main.py --help）：

# ADD — 写入一段对话/一句话；打印 ADD/UPDATE/DELETE 事件
python main.py --mode memory --op add   --text "我住在北京，是一名后端工程师" --user-id u1

# SEARCH — 语义召回
python main.py --mode memory --op search --query "这个用户住在哪里？" --user-id u1

# GET-ALL — 列出所有已存记忆（可选导出为 JSON）
python main.py --mode memory --op get-all --user-id u1 --output mem.json

# HISTORY — 某条记忆 id 的变更/审计轨迹（展示随时间的 UPDATE/DELETE）
python main.py --mode memory --op history --memory-id <id>

# DELETE — 按 id 删除一条记忆
python main.py --mode memory --op delete --memory-id <id>
​

关键参数：--op {add,search,get-all,history,delete}、--text、--query、
--memory-id、--user-id、--agent-id、--model（覆盖 MODEL_NAME）、
--output（将结果写入 JSON）。--text 既接受原始字符串，也接受 JSON
消息列表的文件路径。

上述操作、demo 模式以及对话模式都需要可用的 LLM
API 密钥（KIMI_API_KEY）和向量库——Mem0 的事实抽取和语义检索都是在线模型调用。
没有密钥时，CLI 会解析参数后报告缺失的密钥；不会伪造任何记忆输出。

交互模式

启动一个交互式对话会话：

python main.py --mode interactive
​

交互模式下的可用命令：

• help - 显示可用命令
• memories - 显示已存记忆
• metrics - 显示性能指标
• save - 保存对话状态
• load - 加载之前的状态
• new - 开始新会话
• exit - 退出程序

批处理

从 JSON 文件批量处理多段对话：

python main.py --mode batch --input conversations.json --output results.json
​

输入格式：

[
  {
    "session_id": "session_001",
    "user_id": "user_001",
    "agent_id": "agent_001",
    "turns": [
      "第一条用户消息",
      "第二条用户消息"
    ]
  }
]
​

运行 LOCOMO 基准

完整基准

运行完整的 LOCOMO 基准评测：

python experiment.py --scenarios 10 --output results/
​

它会：

1. 生成并运行 10 个基准场景
2. 评估 Agent 在每个场景上的表现
3. 计算指标（一致性、连贯性、记忆利用率）
4. 生成带可视化的详细报告

基准指标

基准评估内容包括：

• 一致性得分：Agent 保持信息一致的程度
• 连贯性得分：回答的相关性与逻辑流畅度
• 记忆留存：记忆存储与检索的有效性
• 响应时间：每轮平均生成时间
• 上下文利用率：Agent 利用可用上下文的能力

解读结果

结果以 JSON 格式保存，结构如下：

{
  "config": {...},
  "scenarios": [
    {
      "scenario": {...},
      "sessions": [...],
      "overall_metrics": {
        "avg_consistency": 0.92,
        "avg_coherence": 0.88,
        "memory_utilization": 42
      }
    }
  ],
  "overall_metrics": {...}
}
​

架构

组件

1. Agent 模块（agent.py）

   • Mem0Agent：集成记忆的主 Agent 类
   • KimiK3Client：Kimi K3 模型 API 客户端
   • AgentContext：会话上下文管理

2. 配置（config.py）

   • KimiConfig：Kimi 模型设置
   • Mem0Config：记忆系统配置
   • LOCOMOConfig：基准参数

3. 实验框架（experiment.py）

   • LOCOMOBenchmark：基准实现
   • 场景生成与评估
   • 指标计算与报告

记忆系统

Mem0 框架提供：

• 向量存储：基于嵌入的高效语义检索
• 记忆整合：自动抽取关键信息
• 上下文检索：智能检索相关记忆
• 多层级组织：用户级、Agent 级、会话级记忆

进阶用法

自定义场景

通过修改 experiment.py 创建自定义基准场景：

custom_scenario = {
    "type": "custom_type",
    "description": "Your scenario description",
    "topics": ["topic1", "topic2"],
    "context_requirements": ["requirement1", "requirement2"]
}
​

记忆后端

本地存储（Chroma）

config.mem0.backend = "local"
config.mem0.vector_store_config = {
    "provider": "chroma",
    "config": {
        "collection_name": "my_collection",
        "path": "./data/chroma_db"
    }
}
​

云端存储（Mem0 Cloud）

config.mem0.backend = "cloud"
config.mem0.api_key = "your_mem0_api_key"
​

性能调优

通过调整以下配置优化性能：

• MAX_TOKENS：调低以获得更快响应
• TEMPERATURE：调低以获得更稳定的输出
• context_window_size：在上下文与速度之间权衡
• 记忆检索上限：在 _prepare_messages() 中调整

故障排查

常见问题

1. API 密钥错误

   • 确认 .env 中已设置 KIMI_API_KEY
   • 检查 API 密钥的有效性与权限

2. 记忆后端问题

   • 本地模式：确认对 ./data/ 有写权限
   • 云端模式：确认 MEM0_API_KEY 正确

3. 性能问题

   • 调低 MAX_TOKENS 以加快响应
   • 使用本地记忆后端降低延迟
   • 调整基准运行中的批大小

调试模式

开启详细日志：

export LOG_LEVEL=DEBUG
python main.py
​

开发

项目结构

mem0/
├── agent.py           # 核心 Agent 实现
├── config.py          # 配置管理
├── experiment.py      # LOCOMO 基准
├── main.py           # 主入口
├── quickstart.py     # 示例演示
├── requirements.txt  # 依赖
├── env.example      # 环境变量模板
└── README.md        # 文档
​

测试

运行测试（如可用）：

pytest tests/
​

贡献

1. Fork 仓库
2. 创建功能分支
3. 做出修改
4. 如适用则补充测试
5. 提交 Pull Request

性能基准

在标准硬件上的典型性能指标：

• 平均响应时间：1-3 秒
• 记忆检索：<100ms
• 一致性得分：0.85-0.95
• 连贯性得分：0.80-0.90
• 记忆利用率：每会话 20-100 条

局限性

• API 调用需要联网
• 记忆存储随用量增长（建议定期清理）
• 上下文窗口限制在 128K token
• 响应质量受模型可用性影响

许可证

本项目是 AI Agent Book 训练材料的一部分。

致谢

• Mem0 框架由 Mem0 AI 提供
• Kimi K3 模型由 Moonshot AI 提供
• LOCOMO 基准的长上下文评估理念

支持

如有问题或疑问：

• 查阅故障排查章节
• 参考 quickstart.py 中的示例代码
• 参见 AI Agent Book 主文档

OpenRouter 通用回退 / Universal OpenRouter fallback

This experiment now supports a universal OpenRouter fallback for its chat LLM.

• If the primary provider key (e.g. MOONSHOT_API_KEY / KIMI_API_KEY / OPENAI_API_KEY / DOUBAO_API_KEY …) is present, behavior is unchanged.
• Else if OPENROUTER_API_KEY is set, the chat LLM is automatically routed through OpenRouter (https://openrouter.ai/api/v1). Model names are mapped automatically: gpt-*/o1-* → openai/…, claude-* → anthropic/claude-opus-4.8, kimi-* → moonshotai/kimi-k2.6, ids already containing / are kept as-is, and other provider-native ids (e.g. doubao-*) fall back to openai/gpt-5.6-luna. Set OPENROUTER_MODEL to force a specific OpenRouter model id.
• Else a clear error lists the accepted keys.

Add OPENROUTER_API_KEY=... to your .env (see env.example) to enable it.

Note: mem0's embedder still uses OpenAI embeddings (OpenRouter has no embeddings endpoint), so OPENAI_API_KEY is still required for storing/retrieving memories. The OpenRouter fallback only covers the chat LLM (fact extraction, ADD/UPDATE/DELETE decisions, and answering).