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

源文件：chapter3/memobase/README.md

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

一个具备精细记忆管理的进阶 AI Agent 实现，由 Kimi K3 模型驱动，并在 LOCOMO（长上下文与记忆优化）基准上评估。

本目录下有两条线，请勿混淆：

1. 真正的 Memobase 框架演示（profile_demo.py）——使用真实的
   开源 Memobase SDK（pip install memobase，包 memobase>=0.0.27）
   连接到正在运行的 Memobase 服务。这是书中第 3 章描述的 Memobase
   Profile（结构化用户属性）+ Event Memory（时间线）划分的标准演示。
   参见 Memobase Profile + Event 演示。
2. 手写的记忆 Agent（agent.py / main.py）——一个自包含、
   受 Memobase 启发 的 MemoryStore（情景 / 语义 / 程序 / 工作
   记忆，pickle 持久化），直接调用 Kimi K3。它不需要 Memobase
   服务，只要一个 KIMI_API_KEY。下面的 --mode 命令
   （interactive / benchmark / demo / task）都驱动这个 Agent。

特性

先进的记忆管理

• 多种记忆类型：

  • 情景记忆：存储具体的任务经验与交互
  • 语义记忆：维护通用知识与事实
  • 程序记忆：学习并存储问题求解模式
  • 工作记忆：管理短期的任务上下文

• 记忆操作：

  • 超过阈值时自动压缩记忆
  • 记忆整合与模式抽取
  • 基于重要性的衰减与留存
  • 相关记忆聚类
  • 基于相关性与时新的高效检索

Kimi K3 模型集成

• 使用 Kimi K3，一个约 2.8 万亿参数的 Mixture-of-Experts 模型
• 每次前向传播激活 320 亿参数
• 针对智能体能力优化，包括：
  • 高级工具使用
  • 多步推理
  • 代码合成
  • 长上下文理解（128k token）

LOCOMO 基准

跨多个任务类别的综合评估：

• 多轮推理：跨多次交互的复杂问题求解
• 长上下文问答：从长文档中抽取信息
• 任务规划：项目与资源规划能力
• 知识整合：跨领域的综合与分析
• 工具使用：有效利用外部工具与 API

安装

1. 克隆仓库：

cd projects/week2/memobase
​

2. 安装依赖：

pip install -r requirements.txt
​

3. 设置环境变量：

cp env.example .env
# 编辑 .env 并加入你的 Kimi API 密钥
​

配置

编辑 config.py 进行自定义：

• 模型参数（temperature、max tokens 等）
• 记忆设置（阈值、留存策略）
• 基准配置
• 日志级别

用法

交互模式

一边构建并使用记忆，一边与 Agent 对话：

python main.py --mode interactive
​

交互模式下的可用命令：

• /help - 显示可用命令
• /memory - 显示记忆统计
• /clear - 清空工作记忆
• /reset - 重置对话（保留长期记忆）
• /learn - 触发记忆整合
• /exit - 退出交互模式

基准模式

运行 LOCOMO 基准评测：

# 运行完整基准
python main.py --mode benchmark

# 运行特定类别
python main.py --mode benchmark --category multi_turn_reasoning

# 运行有限数量的任务
python main.py --mode benchmark --num-tasks 5
​

演示模式

运行预置的演示场景：

python main.py --mode demo
​

演示内容包括：

• 跨对话的记忆留存
• 从经验中学习
• 长交互中的上下文管理

单任务模式

执行一个特定任务：

python main.py --mode task --task "Plan a 7-day trip to Japan with a $3000 budget"
​

其他选项

• --api-key KEY - 覆盖环境变量中的 API 密钥
• --no-memory - 以空记忆库启动
• --verbose - 开启详细日志

Memobase Profile + Event 演示（真实 SDK）

profile_demo.py 使用真实的开源 Memobase SDK，展示其两种
记忆结构：Profile（主题 → 子主题 → 内容，例如
basic_info→城市、work→职位、interest→游戏偏好）和 Event Memory（一条
用于"我们什么时候讨论过预算？"这类问题的时间线）。它遵循
Memobase 的缓冲管线：insert（写入用户缓冲）→
flush（触发一次 LLM 抽取）→ profile / event / context（召回）。

前置条件：一个运行中的 Memobase 服务 + 抽取用的 LLM

Memobase 的记忆抽取在服务端完成，因此演示需要可访问的
Memobase 服务（客户端本身不调用 LLM）：

• 自托管：参见 memodb-io/memobase
  （docker compose）。默认端点 http://localhost:8019，默认 token
  secret。抽取模型在服务端的 .env /
  config.yaml 中配置，而非由本客户端设置（--model 仅供参考）。
• 云端：从 https://www.memobase.io 获取 project_url + api_key。

通过 --project-url / --api-key 或
MEMOBASE_PROJECT_URL / MEMOBASE_API_KEY 环境变量让客户端指向服务（参见
env.example）。

运行

pip install -r requirements.txt          # 安装 memobase SDK

# 针对运行中的服务做端到端演示（内置示例对话）：
python profile_demo.py

# 离线预览——展示对话 + 管线，但不联网，也不伪造结果：
python profile_demo.py --dry-run

# 记忆生成后的单步操作：
python profile_demo.py --op profile      # 召回结构化用户画像
python profile_demo.py --op event        # 召回事件时间线
python profile_demo.py --op context      # 拼装好的记忆上下文字符串
python profile_demo.py --input chat.json --output result.json
​

如果没有可达的服务，演示会给出一条可操作的提示（指向
--dry-run 或 --project-url）后退出，而不是凭空编造记忆输出。

架构

记忆库（agent.py）

MemoryStore 类管理不同的记忆类型，具备：

• 基于 pickle 的持久化存储
• 记忆压缩与聚类
• 基于重要性的检索
• 基于时间的衰减机制

Agent 核心（agent.py）

MemobaseAgent 类提供：

• 带记忆上下文的消息处理
• 从任务结果中学习
• 记忆感知的响应生成
• 性能指标跟踪

基准系统（locomo_benchmark.py）

LOCOMOBenchmark 类实现：

• 任务生成与管理
• 响应评估指标
• 分类别评分
• 结果持久化与分析

记忆管理策略

压缩

当记忆超过阈值时：

1. 按重要性与时新对记忆排序
2. 保留高重要性记忆
3. 将低重要性记忆压缩为聚类
4. 把聚类摘要存为压缩记忆

整合

在空闲或被触发整合时：

1. 对所有记忆施加衰减
2. 移除重要性极低的记忆
3. 从情景记忆中抽取模式
4. 由模式生成程序记忆

检索

处理查询时：

1. 按内容检索相关记忆
2. 取回近期的情景记忆
3. 纳入适用的程序知识
4. 格式化记忆以便纳入上下文

基准结果

结果保存在 benchmark_results/ 中，包含：

• 任务级得分与耗时
• 分类别的性能指标
• 记忆使用统计
• 详细的错误日志

开发

添加自定义工具

通过修改 Agent 类来扩展自定义工具：

def add_tool(self, tool_name, tool_function):
    # 添加工具注册逻辑
    pass
​

自定义记忆类型

在 config.py 中添加新的记忆类型：

MEMOBASE_CONFIG["memory_types"].append("custom_type")
​

扩展基准

在 locomo_benchmark.py 中添加自定义基准任务：

self.tasks.append(BenchmarkTask(
    id="custom_001",
    category="custom_category",
    query="Your custom task query",
    expected_capabilities=["capability1", "capability2"]
))
​

性能优化

记忆效率

• 批量执行记忆操作以获得更好性能
• 对大型记忆库使用压缩
• 实施周期性整合
• 任务完成后清空工作记忆

响应延迟

• 预取可能用到的记忆
• 缓存嵌入计算结果
• 对记忆检索使用并行处理
• 优化上下文窗口使用

故障排查

常见问题

1. API 密钥错误：

   • 确认 .env 中已设置 KIMI_API_KEY
   • 核实 API 密钥有效性

2. 记忆溢出：

   • 调整配置中的 MAX_MEMORY_ENTRIES
   • 启用更激进的压缩
   • 手动触发整合

3. 性能缓慢：

   • 调低 MODEL_MAX_TOKENS
   • 在配置中启用缓存
   • 使用分类别基准

贡献

欢迎贡献！可改进的方向：

• 更多记忆压缩算法
• 更强的检索机制
• 新的基准类别
• 性能优化
• 工具集成

许可证

MIT License - 详情见 LICENSE 文件

致谢

• Kimi K3 模型由 Moonshot AI 提供
• Memobase 框架理念
• LOCOMO 基准设计灵感

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.