重要提示：在不微调大型语言模型（LLMs）的情况下，对 LLM 代理进行精细调优

一种基于记忆的持续学习框架，可帮助 LLM 代理从经验中不断改进，而无需更新模型权重。

规划器-执行器架构 • 基于案例的推理 • MCP 工具集 • 增强记忆的学习

---

与基线相比，Memento 在 GAIA 验证集和测试集上的表现。	对 Memento 在各类基准测试中的消融研究。
不同记忆设计下的持续学习曲线。	Memento 在未见过的数据集上所取得的准确率提升。

📰 新闻

• [2025.10.05] 我们很高兴地宣布，我们的参数化基于案例的推理推理代码现已正式开源！🎉
• [2025.09.05] 我们新增了支持，可通过 vLLM 将本地 LLM 作为执行器进行部署，请参阅 client/agent_local_server.py。🎉
• [2025.09.03] 我们建立了微信群，以便更轻松地开展协作并交流本项目的相关想法。欢迎加入该群，分享您的见解、提出问题或贡献您的创意！🔥 🔥 🔥 立即加入我们的微信群！
• [2025.08.30] 我们很高兴地宣布，我们的非参数化基于案例的推理推理代码现已正式开源！🎉
• [2025.08.28] 我们创建了一个 Discord 服务器，以使围绕本项目的讨论与协作更加便捷。欢迎加入并分享您的想法、提出问题或贡献创意！🔥 🔥 🔥 加入我们的 Discord！
• [2025.08.27] 感谢您对我们工作的关注！我们将在下周发布 CBR 代码，并在下个月发布参数化记忆代码。我们将持续更新本项目的最新进展。
• [2025.08.27] 我们在 server/ai_crawler.py 中新增了一项新的爬虫 MCP，用于网络爬取以及查询感知的内容压缩，以降低 token 成本。
• [2025.08.26] 我们新增了 SerpAPI（https://serpapi.com/search-api）MCP 工具，帮助您避免使用搜索 Docker，从而加快开发速度。

🔥 核心功能

• 无需更新 LLM 权重。 Memento 将持续学习重新构想为基于记忆的在线强化学习，其基础是增强记忆的 MDP。通过神经网络的案例选择策略来指导行动；经验则通过高效且快速的读写操作被存储并重复利用。
• 两阶段的规划器-执行器循环。 由 CBR 驱动的规划器会将任务分解并检索相关案例；执行器则以 MCP 客户端的身份运行每个子任务，协调工具并回传执行结果。
• 全面的工具生态系统。 通过统一的 MCP 界面，内置支持网页搜索、文档处理、代码执行、图像/视频分析等多种功能。
• 卓越的基准测试表现。 在 GAIA、DeepResearcher、SimpleQA 和 HLE 等基准测试中均取得了具有竞争力的成绩。

---

🧠 核心概念

从经验中学习，而非依赖梯度。 Memento 会将成功与失败的轨迹记录到案例库中，并按值进行检索，以引导规划与执行——从而实现低成本、可迁移且在线的持续学习。

---

🏗️ 架构

核心组件

• 元规划器：利用 GPT-4.1 将高阶查询分解为可执行的子任务。
• 执行器：通过 MCP 工具，使用 o3 或其他模型执行各个子任务。
• 案例记忆：存储最终步骤的元组 (s_T, a_T, r_T)，用于经验回放。
• MCP 工具层：为外部工具和服务提供统一的接口。

工具生态系统

• 网络搜索：通过 SearxNG 实现实时搜索与受控爬取。
• 文档处理：支持多种格式（PDF、Office 文档、图片、音频、视频）。
• 代码执行：配备沙盒化的 Python 工作区，并具备安全管控机制。
• 数据分析：支持 Excel 处理、数学计算。
• 媒体分析：图像标题生成、视频旁白、音频转录。

---

🚀 快速入门

前提条件

• Python 3.11+
• OpenAI API 密钥（或兼容的 API 端点）
• SearxNG 实例用于网络搜索
• FFmpeg（系统级二进制文件，用于视频处理）
• PyTorch 2.0+ 并支持 CUDA（适用于参数化记忆）

📖 如需详细安装指南，请参阅 INSTALL.md

安装

方法 1：使用 uv（推荐方案——快速又现代）

# 克隆仓库
git clone https://github.com/Agent-on-the-Fly/Memento
cd Memento

# 如果尚未安装 uv，可直接运行以下命令
curl -LsSf https://astral.sh/uv/install.sh | sh

# 自动同步依赖并创建虚拟环境
uv sync

# 激活虚拟环境
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

方法 2：使用 pip 与 requirements.txt

# 克隆仓库
git clone https://github.com/Agent-on-the-Fly/Memento
cd Memento

# 创建并激活虚拟环境
python -m venv .venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

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

PyTorch 安装

针对 GPU 支持（参数化记忆推荐方案）：

# CUDA 11.8
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# CUDA 12.1
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# 仅支持 CPU
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

如需更多 PyTorch 安装选项，请访问：https://pytorch.org/get-started/locally/

系统依赖安装

FFmpeg 安装（必需）

FFmpeg 是视频处理功能所必需的。 我们的依赖中包含的 ffmpeg-python 包需要一个系统级的 FFmpeg 二进制文件。

Windows：

# 方法 1：使用 Conda（推荐用于隔离环境）
conda install -c conda-forge ffmpeg

# 方法 2：从官方网站下载
# 访问 https://ffmpeg.org/download.html 并将其添加到 PATH 中

macOS：

# 使用 Homebrew
brew install ffmpeg

Linux：

# Debian/Ubuntu
sudo apt-get update && sudo apt-get install ffmpeg

网页爬取与搜索设置

# 安装并配置 crawl4ai
crawl4ai-setup
crawl4ai-doctor

# 安装 Playwright 浏览器
playwright install

环境变量配置

在创建 .env 文件后，您需要配置以下 API 密钥和服务端点：

#===========================================

# OpenAI API 配置
#===========================================
USE_AZURE_OPENAI=False

OPENAI_API_KEY=your_openai_api_key_here
OPENAI_BASE_URL=https://api.openai.com/v1  # 或者使用您自定义的 API 端点

AZURE_OPENAI_API_KEY=your_azure_openai_api_key_here
AZURE_OPENAI_API_VERSION=your_azure_openai_api_version_here
AZURE_OPENAI_ENDPOINT=your_azure_openai_endpoint_here

#===========================================
# 工具与服务 API
#===========================================
# Chunkr API（https://chunkr.ai/）
CHUNKR_API_KEY=your_chunkr_api_key_here

# Jina API
JINA_API_KEY=your_jina_api_key_here

# ASSEMBLYAI API
ASSEMBLYAI_API_KEY=your_assemblyai_api_key_here

注意：请将 your_*_api_key_here 替换为您的实际 API 密钥。部分服务为可选，具体取决于您计划使用的工具。

SearxNG 设置

若需实现网页搜索功能，请配置 SearxNG： 您可以参考 https://github.com/searxng/searxng-docker/ 来设置 Docker 并使用我们的配置方案。

# 在新终端中
cd ./Memento/searxng-docker
docker compose up -d

基本用法

交互式模式

python client/agent.py

参数化记忆模式（高级模式——带记忆检索器）

参数化记忆使代理能够借助训练有素的神经检索器模型，从过往经验中进行学习。

步骤 1：训练记忆检索器

首先，您需要使用初始训练数据来训练检索器模型：

cd memory

# 训练检索器模型
python train_memory_retriever.py \
  --train training_data.jsonl \
  --output_dir ./ckpts/retriever \
  --use_plan \
  --val_ratio 0.1 \
  --batch_size 32 \
  --lr 2e-5 \
  --epochs 10 \
  --save_best

步骤 2：配置环境变量

在您的 .env 文件中添加以下内容：

# 记忆配置
MEMORY_JSONL_PATH=../memory/memory.jsonl
TRAINING_DATA_PATH=../memory/training_data.jsonl
RETRIEVER_MODEL_PATH=../memory/ckpts/retriever/best.pt
MEMORY_TOP_K=8
MEMORY_MAX_POS_EXAMPLES=8
MEMORY_MAX_NEG_EXAMPLES=8

步骤 3：运行参数化记忆代理

cd client

python parametric_memory.py

---

🔧 配置

模型选择

• 规划器模型：默认采用 gpt-4.1 以支持任务分解
• 执行器模型：默认采用 o3 以实现任务执行
• 自定义模型：支持任何兼容 OpenAI 的 API

工具配置

• 搜索：配置 SearxNG 实例的 URL
• 代码执行：自定义导入白名单及安全设置
• 文档处理：设置缓存目录及处理限制

---

📊 性能

基准测试结果

• GAIA：87.88%（验证集，Pass@3 Top-1）和 79.40%（测试集）
• DeepResearcher：66.6% F1 / 80.4% PM，在 OOD 数据集上实现了 +4.7–9.6 的绝对性能提升
• SimpleQA：95.0%
• HLE：24.4% PM（接近 GPT-5，达到 25.32%）

关键洞察

• 小型、高质量的记忆效果最佳：当检索器的 K=4 时，F1/PM 值达到峰值
• 规划 + CBR 能持续提升性能
• 简洁、结构化的规划方式，优于冗长的决策过程

---

🛠️ 开发

项目结构

Memento/
├── client/                      # 主要代理实现
│   ├── agent.py                # 分层客户端，结合规划器与执行器
│   ├── no_parametric_cbr.py    # 非参数化基于案例推理
│   ├── parametric_memory.py    # 带神经检索器的参数化记忆
│   ├── run_parametric.sh       # 用于参数化模式的便捷脚本
│   └── PARAMETRIC_MEMORY_GUIDE.md  # 详细参数化记忆指南
├── server/                      # MCP 工具服务器
│   ├── code_agent.py           # 代码执行与工作区管理
│   ├── search_tool.py          # 通过 SearxNG 进行网页搜索
│   ├── serp_search.py          # 基于 SERP 的搜索工具
│   ├── documents_tool.py       # 多格式文档处理
│   ├── image_tool.py           # 图片分析与标注
│   ├── video_tool.py           # 视频处理与旁白生成
│   ├── excel_tool.py           # 电子表格处理
│   ├── math_tool.py            # 数学计算
│   ├── craw_page.py            # 网页抓取
│   └── ai_crawler.py           # 查询感知压缩爬虫
├── interpreters/                # 代码执行后端
│   ├── docker_interpreter.py
│   ├── e2b_interpreter.py
│   ├── internal_python_interpreter.py
│   └── subprocess_interpreter.py
├── memory/                      # 记忆组件 / 数据
│   ├── parametric_memory.py        # 基于案例的检索器，用于推理
│   ├── train_memory_retriever.py  # 检索器训练脚本
│   ├── np_memory.py            # 非参数化记忆实用工具
│   ├── retrain.sh              # 用于重新训练的便捷脚本
│   ├── memory.jsonl            # 记忆池（带有标签的案例）
│   ├── training_data.jsonl     # 检索器的训练数据
│   └── ckpts/                  # 模型检查点
│       └── retriever/
│           ├── best.pt         # 最佳性能模型
│           └── last.pt         # 上一阶段的模型
├── data/                        # 样本数据 / 案例
├── searxng-docker/              # SearxNG Docker 配置
├── Figure/                      # 用于 README/论文的图表
├── README.md
├── requirements.txt
├── pyproject.toml
└── LICENSE

添加新工具

1. 在 server/ 目录下创建一个新的 FastMCP 服务器
2. 实现您的工具函数，并确保具备完善的错误处理机制
3. 将工具注册到 MCP 协议中
4. 更新 agent.py 中客户端的服务器列表

自定义解释器

扩展 interpreters/ 模块，以新增多种执行后端：

from interpreters.base import BaseInterpreter

class CustomInterpreter(BaseInterpreter):
    async def execute(self, code: str) -> str:
        # 您的自定义执行逻辑
        pass

---

📋 待办事项

已完成的功能 ✅

• 增加案例库推理：已实现基于参数化记忆的案例检索，并结合神经检索器
• 持续学习流程：自动化收集训练数据并进行模型重新训练

即将推出的功能与改进方向

• 加入用户个人记忆机制：实现用户偏好搜索功能
• 优化工具，新增更多工具：完善现有工具，拓展工具生态系统
• 测试更多新基准：在更多基准数据集上评估性能
• 内存压缩：实施高效的内存剪枝与压缩策略
• 多模态记忆：将记忆扩展至支持图片、视频及其他模态

---

局限性

• 长周期任务：GAIA 第三级任务仍具有挑战性，因为存在复合误差
• 前沿知识：HLE 的性能仅受限于工具本身
• 开源覆盖范围：完全开放的管道中，执行器的验证尚显不足

---

🙏 感谢

• 一些工具包和解释器中的代码源自 Camel-AI。

---

📚 引用

如果《Memento》对您的工作有所帮助，请务必进行引用：

@article{zhou2025mementofinetuningllmagents,
      title={Memento：在不微调大语言模型的前提下，对大语言模型代理进行微调},
      author={周虎驰、陈一航、郭思远、严雪、李金黑、王梓涵、李家耀、张古春、邵坤、杨林毅、王俊},
      journal={arXiv预印本 arXiv: 2508.16153},
      url={https://arxiv.org/abs/2508.16153},
      year={2025}
}

@article{huang2025deep,
  title={深度研究代理：系统性考察与路线图},
  author={黄宇轩、陈一航、张浩政、李康、方萌、杨林毅、李小光、尚立峰、徐松岑、郝建业等},
  journal={arXiv预印本 arXiv:2506.18096},
  year={2025}
}

如需更全面的概览，请参阅我们的调查：GitHub

---

🤝 贡献

我们热烈欢迎各位的贡献！请查看我们的贡献指南，了解以下内容：

• 错误报告与功能请求
• 代码贡献与拉取请求
• 文档改进
• 工具与解释器扩展

---

星星历史

Memento 快速上手指南

Memento 是一个基于记忆的持续学习框架，旨在帮助 LLM 智能体通过经验积累提升能力，而无需更新模型权重。它采用“规划器 - 执行器”架构，结合基于案例的推理（CBR）和 MCP 工具生态，实现低成本、可迁移的在线学习。

1. 环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux, macOS 或 Windows
• Python: 3.11 或更高版本
• GPU (可选但推荐): 如需使用参数化记忆（Parametric Memory）功能，需要支持 CUDA 的 GPU 及 PyTorch 2.0+
• API Key: OpenAI API Key（或兼容的 endpoint，如 Azure OpenAI）
• 外部服务:
  • SearxNG: 用于网络搜索（需部署 Docker 实例）
  • FFmpeg: 系统级二进制文件，用于视频处理
  • Playwright: 用于网页抓取

2. 安装步骤

2.1 克隆项目

git clone https://github.com/Agent-on-the-Fly/Memento
cd Memento

2.2 安装依赖

推荐使用 uv 进行快速安装（国内网络若受阻可尝试方法二）：

方法一：使用 uv (推荐)

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 同步依赖并创建虚拟环境
uv sync

# 激活虚拟环境
source .venv/bin/activate  # Windows: .venv\Scripts\activate

方法二：使用 pip

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 安装依赖 (国内用户可添加清华源加速)
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

安装 PyTorch (如需参数化记忆功能) 根据您的需求选择 CUDA 版本或 CPU 版本：

# CUDA 12.1 (示例)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# 仅 CPU
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

2.3 安装系统依赖

安装 FFmpeg

• Ubuntu/Debian: sudo apt-get update && sudo apt-get install ffmpeg
• macOS: brew install ffmpeg
• Windows: 建议通过 conda 安装 conda install -c conda-forge ffmpeg 或手动下载配置 PATH。

配置网页抓取工具

crawl4ai-setup
crawl4ai-doctor
playwright install

2.4 部署 SearxNG (网络搜索必需)

在项目根目录下启动 SearxNG Docker 容器：

cd ./Memento/searxng-docker
docker compose up -d

2.5 配置环境变量

复制 .env 模板并填入您的 API Key：

cp .env.example .env

编辑 .env 文件，配置关键信息：

# OpenAI 配置
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_BASE_URL=https://api.openai.com/v1

# 可选：其他工具 API (Chunkr, Jina, AssemblyAI 等按需配置)
CHUNKR_API_KEY=your_chunkr_api_key_here
JINA_API_KEY=your_jina_api_key_here

3. 基本使用

3.1 交互式模式 (基础版)

这是最简单的启动方式，智能体将加载默认配置并与您交互：

python client/agent.py

3.2 参数化记忆模式 (进阶版)

如果您希望智能体利用训练好的神经检索器从历史经验中学习，请按以下步骤操作：

第一步：训练记忆检索器

cd memory

python train_memory_retriever.py \
  --train training_data.jsonl \
  --output_dir ./ckpts/retriever \
  --use_plan \
  --val_ratio 0.1 \
  --batch_size 32 \
  --lr 2e-5 \
  --epochs 10 \
  --save_best

第二步：配置记忆路径 在 .env 文件中添加以下配置：

MEMORY_JSONL_PATH=../memory/memory.jsonl
TRAINING_DATA_PATH=../memory/training_data.jsonl
RETRIEVER_MODEL_PATH=../memory/ckpts/retriever/best.pt
MEMORY_TOP_K=8
MEMORY_MAX_POS_EXAMPLES=8
MEMORY_MAX_NEG_EXAMPLES=8

第三步：运行带记忆的智能体

cd client
python parametric_memory.py

---

更多详细配置、工具自定义及开发指南，请参阅项目根目录下的 INSTALL.md 及 client/PARAMETRIC_MEMORY_GUIDE.md。