代理记忆 🧠

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

引言 🌟

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

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

注： 本仓库提供了一个便于构建代理的记忆系统。如果您想复现我们论文中展示的结果，请参考：https://github.com/WujiangXu/AgenticMemory

更多详情请参阅我们的论文：A-MEM: LLM代理的代理记忆

核心特性 ✨

• 🔄 基于Zettelkasten原则的动态记忆组织
• 🔍 通过ChromaDB实现记忆的智能索引与链接
• 📝 具有结构化属性的全面笔记生成
• 🌐 相互连接的知识网络
• 🧬 持续的记忆演化与优化
• 🤖 由代理驱动的决策机制，实现自适应的记忆管理

框架 🏗️

工作原理 🛠️

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

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

结果 📊

在六种基础模型上进行的实证实验表明，该系统的表现优于现有的SOTA基准。

快速开始 🚀

1. 克隆仓库：

git clone https://github.com/agiresearch/A-mem.git
cd A-mem

2. 安装依赖： 建议创建并激活虚拟环境：

python -m venv .venv
source .venv/bin/activate  # Windows系统使用：.venv\Scripts\activate

安装包：

pip install .

开发时可以使用可编辑模式安装：

pip install -e .

3. 使用示例 💡

以下是使用代理记忆系统进行基本操作的方法：

from agentic_memory.memory_system import AgenticMemorySystem

# 初始化记忆系统 🚀
memory_system = AgenticMemorySystem(
    model_name='all-MiniLM-L6-v2',  # ChromaDB的嵌入模型
    llm_backend="openai",           # LLM后端（openai/ollama）
    llm_model="gpt-4o-mini"         # LLM模型名称
)

# 添加记忆 ➕
# 简单添加
memory_id = memory_system.add_note("深度学习神经网络")

# 带元数据添加
memory_id = memory_system.add_note(
    content="机器学习项目笔记",
    tags=["ml", "project"],
    category="研究",
    timestamp="202503021500"  # YYYYMMDDHHmm格式
)

# 阅读（检索）记忆 📖
# 根据ID获取记忆
memory = memory_system.read(memory_id)
print(f"内容: {memory.content}")
print(f"标签: {memory.tags}")
print(f"上下文: {memory.context}")
print(f"关键词: {memory.keywords}")

# 搜索记忆
results = memory_system.search_agentic("神经网络", k=5)
for result in results:
    print(f"ID: {result['id']}")
    print(f"内容: {result['content']}")
    print(f"标签: {result['tags']}")
    print("---")

# 更新记忆 🔄
memory_system.update(memory_id, content="关于深度学习的更新内容")

# 删除记忆 ❌
memory_system.delete(memory_id)

# 记忆演化 🧬
# 系统会自动对记忆进行演化，具体步骤如下：
# 1. 利用ChromaDB查找语义关系
# 2. 更新元数据和上下文
# 3. 在相关记忆之间建立连接
# 这些操作会在添加或更新记忆时自动完成！

高级特性 🌟

1. ChromaDB向量存储 📦

   • 高效的向量嵌入存储与检索
   • 快速的语义相似度搜索
   • 自动化的元数据管理
   • 持久化的记忆存储

2. 记忆演化 🧬

   • 自动分析内容之间的关系
   • 根据相关记忆更新标签和上下文
   • 在记忆之间建立语义连接

3. 灵活的元数据 📋

   • 自定义标签和类别
   • 自动提取关键词
   • 自动生成上下文
   • 时间戳追踪

4. 多种LLM后端 🤖

   • OpenAI（GPT-4、GPT-3.5）
   • Ollama（适用于本地部署）

最佳实践 💪

1. 记忆创建 ✨：

   • 提供清晰、具体的内容
   • 添加相关标签以便更好地组织
   • 让系统自动处理上下文和关键词的生成

2. 记忆检索 🔍：

   • 使用具体的查询语句
   • 根据需求调整k值
   • 同时考虑精确匹配和语义匹配

3. 记忆演化 🧬：

   • 允许系统自动演化以整理记忆
   • 定期审查生成的连接
   • 使用一致的标签规范

4. 错误处理 ⚠️：

   • 始终检查返回值
   • 处理可能存在的无效记忆KeyError
   • 对LLM操作使用try-except块

引用 📚

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

@article{xu2025mem,
  title={A-mem: LLM代理的代理记忆},
  author={徐武江、梁祖杰、梅凯、高航、谭俊涛、张永峰},
  journal={arXiv预印本 arXiv:2502.12110},
  year={2025}
}

许可证 📄

本项目采用MIT许可证。详细信息请参阅LICENSE文件。

A-mem 快速上手指南

A-mem 是一个专为大语言模型（LLM）智能体设计的新型代理记忆系统。它基于卡片盒笔记法（Zettelkasten）原则，能够动态地组织、索引和演化记忆，帮助智能体更高效地利用历史经验。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：推荐 Python 3.8 及以上版本
• 前置依赖：
  • git：用于克隆代码仓库
  • pip：Python 包管理工具
  • API Key：若使用 OpenAI 后端，需准备有效的 OPENAI_API_KEY；若使用本地部署，需安装并运行 Ollama。

提示：国内开发者在安装 Python 依赖时，建议指定清华或阿里镜像源以加速下载。

安装步骤

1. 克隆项目

首先，将 A-mem 仓库克隆到本地：

git clone https://github.com/agiresearch/A-mem.git
cd A-mem

2. 创建虚拟环境（推荐）

为了避免依赖冲突，建议创建独立的虚拟环境：

python -m venv .venv
source .venv/bin/activate  # Windows 用户请使用：.venv\Scripts\activate

3. 安装依赖

使用 pip 安装项目依赖。国内用户可添加 -i 参数使用镜像源：

# 标准安装
pip install . -i https://pypi.tuna.tsinghua.edu.cn/simple

# 或者以可编辑模式安装（适合二次开发）
pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

以下是最简单的使用示例，展示如何初始化系统、添加记忆、检索记忆以及更新记忆。

初始化与基础操作

from agentic_memory.memory_system import AgenticMemorySystem

# 1. 初始化记忆系统 🚀
# model_name: ChromaDB 使用的嵌入模型
# llm_backend: LLM 后端 (支持 "openai" 或 "ollama")
# llm_model: 具体的 LLM 模型名称
memory_system = AgenticMemorySystem(
    model_name='all-MiniLM-L6-v2',
    llm_backend="openai",           
    llm_model="gpt-4o-mini"         
)

# 2. 添加记忆 ➕
# 简单添加
memory_id = memory_system.add_note("深度学习神经网络基础")

# 带元数据添加（标签、分类、时间戳）
memory_id = memory_system.add_note(
    content="机器学习项目笔记",
    tags=["ml", "project"],
    category="Research",
    timestamp="202503021500"  # 格式：YYYYMMDDHHmm
)

# 3. 读取/检索记忆 📖
# 通过 ID 获取单条记忆
memory = memory_system.read(memory_id)
print(f"内容：{memory.content}")
print(f"标签：{memory.tags}")
print(f"上下文：{memory.context}")
print(f"关键词：{memory.keywords}")

# 语义搜索（代理式搜索）
results = memory_system.search_agentic("神经网络", k=5)
for result in results:
    print(f"ID: {result['id']}")
    print(f"内容：{result['content']}")
    print(f"标签：{result['tags']}")
    print("---")

# 4. 更新记忆 🔄
memory_system.update(memory_id, content="关于深度学习的更新内容")

# 5. 删除记忆 ❌
memory_system.delete(memory_id)

核心特性说明

• 自动演化：系统在添加或更新记忆时，会自动利用 ChromaDB 分析语义关系，生成标签、上下文，并建立记忆间的关联，无需手动干预。
• 多后端支持：默认配置为 OpenAI，如需本地私有化部署，可将 llm_backend 设置为 "ollama" 并确保本地 Ollama 服务已启动。
• 向量存储：底层使用 ChromaDB 进行高效的向量嵌入存储和相似度检索。