源码系统概览
文章正文
MemHarness 是 KnowledgeXLab 开源的大模型记忆训练框架，关注的是智能体在多轮任务里怎么记住有用的东西。
它没有停留在提示词层面，而是把记忆的写入、检索、剪枝和强化学习训练全都做成了可运行的工程。
对想复现记忆类智能体训练流程的团队来说，这份源码的参考价值集中在训练闭环上。
源码简介
仓库主体由 agent_system、verl、run_scripts、tests 几个部分组成，文件数接近一千个。
verl 目录是训练底座，提供 PPO 主训练入口、FSDP 微调训练器、生成与评测入口以及分布式通信工具。
agent_system 目录承载智能体侧逻辑，其中 memory 子模块提供了一个本地记忆服务。
这个记忆服务对外暴露批量写入、语义检索、更新、剪枝、清空和随机采样等接口，围绕 memories 路径组织。
environments 目录内置了 ALFWorld 与 WebShop 两套交互环境，WebShop 还带了一整套网页端模拟站点。
训练链路上能看到 step_with_memory 与 build_memory_message_and_event 这类函数，负责把记忆拼进对话上下文再回传训练信号。
run_scripts 目录给出了针对不同环境的训练启动脚本，配置项通过 YAML 与命令行参数注入。
适用场景
适合研究智能体长期记忆机制的团队，直接拿现成的记忆服务与训练闭环做对照实验。
适合做强化学习训练的工程同学，参考它在 verl 基础上扩展多轮交互采样的方式。
适合评测方向的使用者，利用内置环境验证记忆策略在不同任务上的表现差异。
也适合作为教学案例，完整展示一个训练框架从环境、采样到奖励回传的组织方式。
功能亮点
记忆服务独立成模块，写入与检索走统一接口，替换向量后端相对容易。
支持记忆剪枝与随机采样，能配合实验设计控制记忆库规模。
训练侧基于 verl，PPO、SFT、生成与评测入口齐全，分布式相关工具也比较完整。
内置两套交互环境，省去自己搭建评测场景的时间成本。
环境依赖按场景拆成了多个安装分支，避免所有依赖挤在一个环境里互相冲突。
脚本化程度高，训练参数集中在启动脚本里，改实验配置不用翻源码。
技术架构与部署指南
| 维度 | 本套源码 | 同类通用方案 |
|---|---|---|
| 技术栈 | 前端：WebShop 环境自带少量 HTML 页面模板用于模拟购物站点，项目本身不提供管理后台界面 后端：Python |
依具体方案选型，需自行搭建与维护 |
| 部署方式 | 先用 git 拉取仓库，再用 conda 创建一个 Python 3.12 的独立环境。 | 多托管于第三方平台或订阅云服务 |
| 功能侧重 | 记忆服务独立成模块，写入与检索走统一接口，替换向量后端相对容易。 | 功能通用，定制深度有限 |
| 数据归属 | 数据自持，部署在自有服务器，不出站 | 数据通常留存于服务商侧 |
| 成本模式 | 获取后自主部署，无持续授权费用 | 通常按订阅或调用量计费 |
技术栈与运行环境
前端：WebShop 环境自带少量 HTML 页面模板用于模拟购物站点，项目本身不提供管理后台界面
后端：Python 实现，基于 verl 强化学习训练栈，记忆服务以本地 HTTP 服务形式对外提供接口
数据库：记忆数据依赖向量检索后端，仓库中通过检索服务配置文件指定连接信息
运行环境：Linux 服务器加 GPU 环境，建议 Python 3.12，通过 conda 分环境安装
其他依赖：PyTorch、datasets、faiss、flash-attn、Flask、FastAPI 等，依赖清单分列在多个 requirements 文件中
安装与部署提示
先用 git 拉取仓库，再用 conda 创建一个 Python 3.12 的独立环境。
在主环境里执行可编辑安装，把项目本体和基础依赖装好。
ALFWorld 与 WebShop 需要各自克隆一份环境再单独装依赖，避免版本互相打架。
记忆检索服务需要先按配置文件启动，训练脚本才能正常访问检索接口。
训练通过 run_scripts 目录下的脚本启动，显存需求较高，单卡跑小规模实验前先调低批量。
实验记录默认可以接入 wandb，不需要的话在配置里关掉即可。
截图与演示说明
这是项目的开篇示意图，概括说明记忆在多轮智能体任务里承担的作用。
这张是整体框架图，可以对照 agent_system 与 verl 两个目录理解记忆服务和训练器的分工。
这是主实验结果对比图，反映不同记忆策略在内置环境上的成绩差异。
这张是分布外任务的结果图，用于说明方法迁移到新场景时的表现，属于论文侧材料而非部署界面。
常见问题
问：跑这套框架需要什么样的机器？
训练环节依赖 GPU，显存越大越好，纯 CPU 环境只能做很小规模的调试。
问：记忆服务能单独用吗？
可以，memory 模块本身是独立服务，接口清晰，能剥离出来接自己的智能体。
问：为什么要建多个 conda 环境？
ALFWorld 与 WebShop 的依赖和主训练环境存在版本冲突，官方做法就是分环境安装。
问：能直接商用吗？
许可证允许，但训练框架属于实验性工程，落地前需要自行做稳定性和合规评估。
安全风险提示
特别提示：本源码未检测安全风险文件，下载后请务必进行安全审计，删除恶意代码后再部署使用！
下载说明
本源码采用 Apache-2.0 许可，下载后可用于学习研究与本地实验复现。
源码仅供学习研究、测试部署和二次开发参考，商用前请自行确认授权、版权和安全风险。
训练框架涉及分布式通信与对象序列化，源码中沿用了上游 verl 的 pickle 反序列化与命令行调用写法，仅建议在可信的内网集群运行。
环境依赖体积较大，部署前请预留足够磁盘与显存资源。
GitHub项目开源地址：https://github.com/KnowledgeXLab/MemHarness