在智能体（Agent）的设计中，记忆（Memory） 是不可或缺的组成部分。没有记忆的智能体，就像一条只能看眼前一步的鱼：它能游动，却无法真正理解自己所处的环境，也无法在长时间的交互中保持一致性。而在 LlamaIndex 框架中，记忆管理为多智能体（Multi-Agent）系统带来了持久性、上下文感和推理的深度。
一、为什么智能体需要记忆？
当我们构建 LlamaIndex Agents 时，往往会遇到以下需求：
1、上下文延续
用户提问可能是连续的，例如：
“请告诉我《西游记》的作者。”
“那他和《红楼梦》有什么关系？”
如果没有记忆，智能体在第二个问题中无法理解“他”指的是谁。
2、个性化与长期交互
一个优秀的智能体不仅要记住一次会话中的上下文，还要能在长期使用中保持“个性化”，例如记住用户的偏好、常问的问题、领域背景。
3、复杂任务协作
在 Orchestrator（编排器）调用多个专家 Agent 时，记忆能记录先前的任务结果，避免重复计算和无效调用。
换句话说，记忆就是智能体的“第二大脑”，帮助它在时间的长河中保持连续性与理性。
二、LlamaIndex 中的记忆模块
强大的 LlamaIndex 框架为我们提供了非常便捷的记忆管理模块。开发者无需从零开始构建复杂的记忆系统，只需几行代码，就能为你的 Agent 配置不同类型的记忆。
LlamaIndex 的记忆模块核心思想是：在每一次与 Agent 的交互中，自动地、智能地将对话历史加载到提示 (Prompt) 中，这样大语言模型 (LLM) 在生成下一步的回应或行动时，就能“看到”之前的对话内容。
1. LlamaIndex记忆组件架构
LlamaIndex提供了三种主要的记忆组件类型：
Memory类 - 核心记忆管理器，可以管理短期和长期记忆
MemoryBlock类 - 记忆块，用于存储和处理特定类型的记忆
ChatMemoryBuffer类 - 已弃用，被更灵活的Memory类替代
2. 核心记忆组件 - Memory类
Memory类是LlamaIndex中最主要的记忆组件，它提供了以下功能：
短期记忆管理 ：维护一个FIFO队列的ChatMessage对象
长期记忆管理 ：当短期记忆超过限制时，将消息刷新到长期记忆块
记忆检索 ：合并短期和长期记忆，提供完整的上下文
基本使用方法：
from llama_index.core.memory import Memory# 创建基本记忆实例memory = Memory.from_defaults(session_id="my_session",token_limit=40000, # 令牌限制token_flush_size=1000, # 刷新大小chat_history_token_ratio=0.7, # 聊天历史令牌比例)
3. 记忆块类型 - MemoryBlock
LlamaIndex提供了三种主要的记忆块类型：
（1） StaticMemoryBlock（静态记忆块）
用于存储固定的、不变的信息：
from llama_index.core.memory import StaticMemoryBlockstatic_block = StaticMemoryBlock(name="core_info",static_content="My name is Logan, and I live in Saskatoon. I work at LlamaIndex.",priority=0,)
（2） FactExtractionMemoryBlock（事实提取记忆块）
使用LLM从对话中提取关键事实：
from llama_index.core.memory import FactExtractionMemoryBlockfact_block = FactExtractionMemoryBlock(name="extracted_info",llm=Settings.llm, # 用于提取事实的LLMmax_facts=50, # 最大事实数量priority=1,)
（3） VectorMemoryBlock（向量记忆块）
使用向量存储进行语义检索的记忆块：
from llama_index.core.memory import VectorMemoryBlockfrom llama_index.vector_stores.chroma import ChromaVectorStoreimport chromadb# 创建向量存储client = chromadb.EphemeralClient()vector_store = ChromaVectorStore(chroma_collection=client.get_or_create_collection("test_collection"))vector_block = VectorMemoryBlock(name="vector_memory",vector_store=vector_store,embed_model=Settings.embed_model,similarity_top_k=2, # 检索的相似文档数量retrieval_context_window=5, # 检索上下文窗口priority=2,)
4. 组合使用记忆组件
将多个记忆块组合使用，创建强大的记忆系统：
from llama_index.core.memory import Memory, InsertMethod# 定义记忆块blocks = [StaticMemoryBlock(name="core_info",static_content="My name is Logan, and I live in Saskatoon. I work at LlamaIndex.",priority=0,),FactExtractionMemoryBlock(name="extracted_info",llm=Settings.llm,max_facts=50,priority=1,),VectorMemoryBlock(name="vector_memory",vector_store=vector_store,embed_model=Settings.embed_model,priority=2,),]# 创建组合记忆系统memory = Memory.from_defaults(session_id="my_session",token_limit=30000,chat_history_token_ratio=0.02, # 低比例，更多内容刷新到长期记忆token_flush_size=500,memory_blocks=blocks,insert_method=InsertMethod.USER, # 插入方法，可以是USER或SYSTEM)
5. 在代理中使用记忆组件
将LlamaIndex的记忆组件与智能体Agents结合使用：
from llama_index.core.agent.workflow import FunctionAgentfrom llama_index.core.llms import ChatMessageasync def agent_with_memory_example():# 创建记忆系统memory = Memory.from_defaults(session_id="my_session",token_limit=30000,chat_history_token_ratio=0.7,token_flush_size=1000,)# 创建代理agent = FunctionAgent(tools=[multiply_tool, add_tool, weather_tool, search_tool],llm=Settings.llm,system_prompt="你是一个有用的助手，可以使用提供的工具来回答问题和执行任务。",)# 模拟对话queries = ["你好，我叫小明","记住我的名字","我的名字是什么？","计算 203 乘以 45","计算 304.3 乘以 2.1",]for query in queries:# 使用记忆运行代理response = await agent.run(user_msg=query, memory=memory)print(f"用户: {query}")print(f"助手: {response}")print("-" * 40)# 查看记忆内容chat_history = await memory.aget()print(f"记忆中的消息数量: {len(chat_history)}")
6. 手动管理记忆
除了在代理中使用，您还可以手动管理记忆：
from llama_index.core.llms import ChatMessage# 添加消息到记忆await memory.aput_messages([ChatMessage(role="user", content="Hello, world!"),ChatMessage(role="assistant", content="Hello, world to you too!"),])# 获取当前记忆chat_history = await memory.aget()for msg in chat_history:print(f"{msg.role}: {msg.content}")# 获取所有记忆all_messages = await memory.aget_all()print(f"总消息数: {len(all_messages)}")# 清除记忆memory.reset()
7. 实际应用示例
以下是一个使用LlamaIndex记忆组件的完整示例：
安装包：
pip install llama-index-vector-stores-chroma
核心代码：
# ================== 初始化 大模型 Langfuse ==================from common.bedrock_model_loader import model_loadersimport common.langfuse_init_client# ================== 初始化大模型 Langfuse end ==================import asynciofrom llama_index.core.agent.workflow import FunctionAgentfrom llama_index.core.memory import Memory, VectorMemoryBlock, FactExtractionMemoryBlockfrom llama_index.core.llms import ChatMessagefrom llama_index.vector_stores.chroma import ChromaVectorStoreimport chromadbfrom fun_coll import *class LlamaIndexConversationalAgent:"""使用LlamaIndex记忆组件的对话代理"""def __init__(self, tools, system_prompt: str):# 创建向量存储client = chromadb.EphemeralClient()vector_store = ChromaVectorStore(chroma_collection=client.get_or_create_collection("conversation_collection"))# 定义记忆块blocks = [FactExtractionMemoryBlock(name="facts",# llm=Settings.llm,max_facts=100,priority=1,),VectorMemoryBlock(name="vector_memory",vector_store=vector_store,# embed_model=Settings.embed_model,similarity_top_k=3,priority=2,),]# 创建记忆系统self.memory = Memory.from_defaults(session_id="conversation_session",token_limit=40000,chat_history_token_ratio=0.7,token_flush_size=1000,memory_blocks=blocks,insert_method="user",)# 创建代理self.agent = FunctionAgent(tools=tools,# llm=Settings.llm,system_prompt=system_prompt,)async def run(self, query: str) -> str:"""运行代理，使用LlamaIndex记忆"""# 运行代理，自动使用记忆response = await self.agent.run(user_msg=query, memory=self.memory)return str(response)# 使用示例async def llamaindex_conversational_agent_example():# 创建系统提示system_prompt = """你是一个有用的助手，可以使用提供的工具来回答问题和执行任务。你有对话记忆能力，可以记住之前的对话内容，提供连贯的交互体验。"""# 创建对话代理agent = LlamaIndexConversationalAgent(tools=[multiply_tool, add_tool, weather_tool, search_tool],system_prompt=system_prompt,)# 模拟对话queries = ["你好，我叫小明","记住我的名字","我的名字是什么？","计算乘法我需要传入什么样的数字","计算乘法可以传0吗？","203 和 45","304.3 和 2.1",]for query in queries:response = await agent.run(query)print(f"用户: {query}")print(f"助手: {response}")print("@-=====----======-------=====#####@@" )if __name__ == "__main__":asyncio.run(llamaindex_conversational_agent_example())
结果：
用户: 你好，我叫小明助手: 你好，小明！很高兴认识你。有什么我可以帮助你的吗？@-=====----======-------=====#####@@用户: 记住我的名字助手: 好的，我已经记住你的名字是小明。有什么我可以为你做的吗？用户: 我的名字是什么？助手: 你的名字是小明。还有什么我可以帮助你的吗？@-=====----======-------=====#####@@用户: 计算乘法我需要传入什么样的数字助手: 要使用乘法计算工具，你需要提供两个数字。这两个数字可以是整数或小数。例如，你可以输入 `multiply(3, 5)` 来计算 3 和 5 的乘积，或者输入 `multiply(2.5, 3.5)` 来计算 2.5 和 3.5 的乘积。如果你有具体的数字需要计算，请告诉我，我可以帮你进行计算。@-=====----======-------=====#####@@用户: 计算乘法可以传0吗？助手: 可以的，你可以传入0来进行乘法计算。根据乘法的性质，任何数乘以0都等于0。例如，你可以输入 `multiply(0, 5)` 或 `multiply(3, 0)`，结果都会是0。如果你有具体的数字需要计算，请告诉我，我可以帮你进行计算。@-=====----======-------=====#####@@fun_coll- multiply 中的参数：a=203, b=45用户: 203 和 45助手: 203 和 45 的乘积是 9135。还有什么我可以帮助你的吗？@-=====----======-------=====#####@@fun_coll- multiply 中的参数：a=304.3, b=2.1用户: 304.3 和 2.1助手: 304.3 和 2.1 的乘积是 639.03。还有什么我可以帮助你的吗？@-=====----======-------=====#####@@
LlamaIndex内置的记忆组件提供了强大、灵活的记忆管理功能。通过使用Memory类和各种MemoryBlock，您可以轻松实现短期和长期记忆管理、语义检索、事实提取等高级功能，而无需自己实现这些复杂的逻辑。
三、参数详解
1、Memory的核心参数说明
self.memory = Memory.from_defaults( session_id="conversation_session", token_limit=40000, # 总令牌限制 chat_history_token_ratio=0.7, # 聊天历史占用的令牌比例 token_flush_size=1000, # 触发刷新到长期记忆的令牌大小 memory_blocks=blocks, # 记忆块配置 insert_method="user", # 插入方法)
token_limit（总令牌限制）
作用 ：设置记忆系统可以使用的最大令牌数
影响 ：当对话历史接近此限制时，系统会自动管理记忆
示例 ：设置为40000，意味着记忆系统最多保留40000个令牌的对话内容
chat_history_token_ratio（聊天历史令牌比例）
作用 ：控制短期记忆中聊天历史占用的令牌比例
影响 ：值越大，保留的对话轮次越多；值越小，越早将对话转移到长期记忆
示例 ：设置为0.7，表示70%的令牌空间用于存储最近的对话历史
token_flush_size（刷新令牌大小）
作用 ：当短期记忆达到此大小时，触发将部分对话刷新到长期记忆
影响 ：值越小，越频繁地将对话转移到长期记忆
示例 ：设置为1000，当短期记忆达到1000个令牌时，会触发刷新操作
2、记忆块配置
FactExtractionMemoryBlock（事实提取记忆块）FactExtractionMemoryBlock(name="facts",llm=Settings.llm,max_facts=100, # 最大提取事实数量priority=1, # 优先级)
max_facts ：控制从对话中提取的事实数量，影响长期记忆的容量
VectorMemoryBlock（向量记忆块）
VectorMemoryBlock( name="vector_memory", vector_store=vector_store, embed_model=Settings.embed_model, similarity_top_k=3, # 检索时的相似文档数量 priority=2,)
similarity_top_k ：控制从向量记忆中检索的相关对话数量
总结
LlamaIndex的记忆系统通过分层机制控制对话轮次：
短期记忆 ：由 chat_history_token_ratio 控制，保留最近的对话内容
长期记忆 ：通过 token_flush_size 触发，将重要对话转移到向量存储
事实记忆 ：提取关键事实，永久保存重要信息
想要控制对话轮次，可以调整以下参数：
增加对话轮次 ：增大 token_limit 和 chat_history_token_ratio
减少对话轮次 ：减小 token_limit 和 chat_history_token_ratio ，或增大 token_flush_size
平衡记忆 ：调整 max_facts 和 similarity_top_k 来控制长期记忆的容量和检索精度
通过这些参数的组合使用，可以精确控制LlamaIndex记忆系统中的对话轮次和记忆管理行为。
本文可与《LlamaIndex的Memory使用说明》结合起来看。
