Agentic Memory 🧠

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

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

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

简介 🌟

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

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

（此处应为对比图：传统记忆系统（上）与我们提出的 Agent 化记忆系统（下）。我们的系统支持动态记忆操作以及灵活的 Agent 与记忆交互。）

核心功能 ✨

• 🔄 基于 Zettelkasten 原则的动态记忆组织
• 🔍 智能的记忆索引与关联
• 📝 生成带有结构化属性的综合笔记
• 🌐 互联的知识网络
• 🔄 持续的记忆演化与精炼
• 🤖 由 Agent 驱动的决策，实现自适应记忆管理

框架 🏗️

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

工作原理 🛠️

当向系统添加新记忆时：

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 评估只会重新运行问答步骤。

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

• Category 1: Multi-hop（多跳）
• Category 2: Temporal（时序）
• Category 3: Open-domain（开放域）
• Category 4: Single-hop（单跳）
• Category 5: Adversarial（对抗性）

关于类别的更多详细信息，请参考 此 GitHub issue。

引用 📚

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

@inproceeding