Agentic Memory 🧠

一种用于 LLM Agent 的新型智能记忆系统，能够以 Agent 的方式动态组织记忆。

注意： 本仓库专为复现论文结果而设计。如果您希望在构建 Agent 时使用 A-Mem 系统，请参考我们的官方实现：A-mem-sys

欲了解更多详细信息，请参阅我们的论文：A-Mem: Agentic Memory for LLM Agents

简介 🌟

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

我们的项目引入了一种创新的 Agentic Memory（智能记忆） 系统，彻底改变了 LLM Agent 管理和利用记忆的方式：

（此处插入对比图：传统记忆系统（上）与我们提出的智能记忆系统（下）。我们的系统支持动态记忆操作以及 Agent 与记忆之间灵活的交互。）

核心特性 ✨

🔄 基于 Zettelkasten 原则的动态记忆组织
🔍 智能化的记忆索引与关联
📝 具备结构化属性的全面笔记生成
🌐 互联的知识网络
🔄 持续的记忆演进与优化
🤖 用于自适应记忆管理的 Agent 驱动决策

框架 🏗️

（此处插入框架图：展示了 LLM Agent 与记忆组件之间动态交互的智能记忆系统框架。）

工作原理 🛠️

当向系统添加新记忆时：

生成带有结构化属性的全面笔记
创建上下文描述和标签
分析历史记忆以寻找相关联系
基于相似度建立有意义的链接
实现记忆的动态演进与更新

实验结果 📊

在六个基础模型上进行的实证实验表明，与现有的 SOTA 基准相比，本系统表现出优越的性能。

快速开始 🚀

克隆仓库：

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

安装依赖：方案 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

在 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）。

运行完整的 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 others},
  booktitle={NeurIPS},
  year={2025}
}

WujiangXu/A-mem