代理记忆 🧠

一种新颖的代理记忆（Agentic Memory）系统，专为 LLM 代理设计，能够以代理方式动态组织记忆。

注意： 本仓库专门用于复现我们论文中展示的结果。如果您想在构建您的代理时使用 A-Mem 系统，请参考我们的官方实现：A-mem-sys

更多详情，请参阅我们的论文：A-Mem: Agentic Memory for LLM Agents

简介 🌟

大语言模型（LLM）代理在通过外部工具使用处理复杂现实任务方面展示了显著能力。然而，为了有效利用历史经验，它们需要复杂的记忆系统。传统的记忆系统虽然提供了基本的存储和检索功能，但往往缺乏高级的记忆组织能力。

我们的项目引入了一种创新的代理记忆系统，彻底改变了 LLM 代理管理和利用记忆的方式：

核心特性 ✨

• 🔄 基于卡片盒笔记法（Zettelkasten）原则的动态记忆组织
• 🔍 记忆的智能化索引与链接
• 📝 带有结构化属性的综合笔记生成
• 🌐 互联的知识网络
• 🔄 持续的记忆演化与优化
• 🤖 由代理驱动的自适应记忆管理决策

框架 🏗️

工作原理 🛠️

当新记忆被添加到系统中时：

1. 生成带有结构化属性的综合笔记
2. 创建上下文描述和标签
3. 分析历史记忆以寻找相关连接
4. 基于相似性建立有意义的链接
5. 启用动态记忆演化和更新

结果 📊

在六个基础模型上进行的实证实验表明，与现有的最先进（SOTA）基线相比，性能更优。

入门指南 🚀

1. 克隆仓库：

git clone https://github.com/WujiangXu/AgenticMemory.git
cd AgenticMemory

2. 安装依赖项： 选项 1：使用 venv（Python 虚拟环境）

# 创建并激活虚拟环境
python -m venv a-mem
source a-mem/bin/activate  # Linux/Mac
a-mem\Scripts\activate     # Windows

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

选项 2：使用 Conda

# 创建并激活 conda 环境
conda create -n myenv python=3.9
conda activate myenv

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

3. 在 LoCoMo 数据集上运行实验：

选项 A — 原始评估（需要 OpenAI JSON schema 支持）：

python test_advanced.py

选项 B — 鲁棒评估（推荐，适用于任何 LLM 后端）：

鲁棒评估（test_advanced_robust.py）移除了 JSON schema 依赖，并支持 OpenAI API、vLLM 和 Ollama 后端。

# OpenAI 模型
python test_advanced_robust.py --backend openai --model gpt-4o-mini \
    --dataset data/locomo10.json --output results_robust_gpt-4o-mini.json

# vLLM 托管的开源模型（请先启动 vLLM 服务器）
python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2.5-3B-Instruct --port 30000 \
    --dtype float16 --enforce-eager --max-model-len 8192
python test_advanced_robust.py --backend vllm --model Qwen/Qwen2.5-3B-Instruct \
    --dataset data/locomo10.json --output results_robust_qwen3b.json \
    --sglang_port 30000

# Ollama 模型
python test_advanced_robust.py --backend ollama --model qwen2.5:3b \
    --dataset data/locomo10.json --output results_robust_ollama_qwen3b.json

关键参数：

• --retrieve_k: 每次查询检索的记忆数量（默认值：10）。请根据模型调整此参数以获得最佳结果。
• --ratio: 要评估的数据集比例（例如，--ratio 0.1 表示进行 10% 的快速测试）。
• --backend: 可选值为 openai、vllm、ollama。
• --sglang_port: vLLM/SGLang 服务器的端口（默认值：30000）。

4. 运行完整的 k-sweep 以找到每个模型的最佳检索 k 值：

bash run_k_sweep.sh

注意： 为了达到我们在论文中报告的最佳性能，请相应地调整超参数 k 的值。记忆在第一次运行后会被缓存，因此后续的 k-sweep 评估仅重新运行 QA 回答步骤。

类别信息： LoCoMo 数据集包含以下类别：

• 类别 1：多跳（Multi-hop）
• 类别 2：时间（Temporal）
• 类别 3：开放域（Open-domain）
• 类别 4：单跳（Single-hop）
• 类别 5：对抗（Adversarial）

有关类别的更多详情，请参阅 此 GitHub issue。

引用 📚

如果您在研究中使用了此代码，请引用我们的工作：

@inproceedings{xu2025amem,
  title={A-Mem: Agentic memory for llm agents},
  author={Xu, Wujiang and Liang, Zujie and Mei, Kai and Gao, Hang and Tan, Juntao and Zhang, Yongfeng},
  booktitle={Advances in Neural Information Processing Systems},
  year={2025}
}

许可证 📄

本项目采用 MIT 许可证授权。详情请参见 LICENSE 文件。

A-mem 快速上手指南

A-mem 是一种新颖的代理记忆系统，专为 LLM Agent 设计，能够以代理方式动态组织记忆。

⚠️ 重要提示：本仓库主要用于复现论文结果。如果您希望在实际构建 Agent 时使用 A-Mem 系统，请参考官方实现：A-mem-sys。

---

环境准备

• 操作系统：Linux / macOS / Windows
• Python 版本：3.9 及以上
• 前置工具：Git
• 依赖管理：支持 venv 或 Conda

---

安装步骤

1. 克隆仓库

git clone https://github.com/WujiangXu/AgenticMemory.git
cd AgenticMemory

2. 创建并激活虚拟环境

方式一：使用 venv

# 创建虚拟环境
python -m venv a-mem
source a-mem/bin/activate  # Linux/Mac
a-mem\Scripts\activate     # Windows

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

方式二：使用 Conda

# 创建并激活 conda 环境
conda create -n myenv python=3.9
conda activate myenv

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

---

基本使用

推荐使用鲁棒性评估脚本 (test_advanced_robust.py)，它移除了对 JSON Schema 的依赖，支持多种后端（OpenAI, vLLM, Ollama）。

1. 基础测试示例 (OpenAI 模型)

python test_advanced_robust.py --backend openai --model gpt-4o-mini \
    --dataset data/locomo10.json --output results_robust_gpt-4o-mini.json

2. 其他后端示例

vLLM 服务开源模型 (需先启动 vLLM 服务器):

# 启动 vLLM 服务
python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2.5-3B-Instruct --port 30000 \
    --dtype float16 --enforce-eager --max-model-len 8192

# 运行测试
python test_advanced_robust.py --backend vllm --model Qwen/Qwen2.5-3B-Instruct \
    --dataset data/locomo10.json --output results_robust_qwen3b.json \
    --sglang_port 30000

Ollama 模型:

python test_advanced_robust.py --backend ollama --model qwen2.5:3b \
    --dataset data/locomo10.json --output results_robust_ollama_qwen3b.json

3. 常用参数说明

参数	说明
--retrieve_k	每次查询检索的记忆数量 (默认：10)，可根据模型调整
--ratio	评估数据集的比例 (例如 --ratio 0.1 为 10% 快速测试)
--backend	后端类型：openai, vllm, ollama
--sglang_port	vLLM/SGLang 服务器端口 (默认：30000)

4. 超参数优化 (k-sweep)

为了达到论文中的最佳性能，建议运行完整的 k 值扫描：

bash run_k_sweep.sh

注：首次运行后记忆会被缓存，后续的 k-sweep 评估仅重新运行 QA 回答步骤。