crewAI 记忆架构短时记忆、长时记忆与实体记忆的层级设计本文基于 crewAI v1.11.0深入解析 crewAI 统一记忆系统的架构设计、配置方式和生产实践。一、为什么 Agent 需要记忆想象一个没有记忆的研究助手每次你问他一个问题他都从零开始不记得上次你说过重点关注中国市场数据不知道他上周已经调研过的那家公司每次交互都在重复建立上下文。这就是没有记忆的 Agent 的现状——它是个高效的失忆症患者。记忆系统让 Agent 能够跨 Task 保持上下文当前任务可以利用同一 Crew 中之前任务的信息跨会话积累经验今天的工作经验可以在明天的任务中发挥作用建立实体知识库记住关键人物、公司、概念的属性形成持久化的知识图谱二、crewAI 的统一记忆系统crewAI v1.11.0 对记忆架构进行了重大升级——用一个统一的Memory类替代了之前分散的短期、长期、实体记忆类型。这个设计的核心思想让 LLM 智能决定如何存储而不是让开发者手动分类。fromcrewaiimportMemory,Crew# 启用记忆的最简单方式crewCrew(agents[researcher,analyst],tasks[task1,task2],memoryTrue# 使用默认配置启用统一记忆系统)三、记忆三层架构的内部实现虽然对外暴露的是统一接口但 crewAI 内部依然维护了三种记忆行为通过权重参数区分3.1 短时记忆行为特征时效性高近期信息权重大随时间衰减 ───────────────────────────────────────────── 控制参数 recency_weight ─ 时效性权重默认 0.3 recency_half_life_days ─ 半衰期默认30天 衰减模型 权重 0.5 ^ (age_days / half_life_days) 1天前的记忆0.5 ^ (1/30) ≈ 0.977几乎不衰减 7天前的记忆0.5 ^ (7/30) ≈ 0.858 30天前的记忆0.5 ^ (30/30) 0.500半衰减 90天前的记忆0.5 ^ (90/30) 0.125大幅衰减适用场景配置fromcrewaiimportMemory# 偏向短时记忆适合实时信息处理场景short_term_memoryMemory(recency_weight0.5,# 提高时效性权重recency_half_life_days7,# 7天半衰减更快遗忘旧信息)3.2 长时记忆行为特征重要信息持久保存不受时间衰减影响 ───────────────────────────────────────────── 控制参数 importance_weight ─ 重要性权重默认 0.2 LLM 自动判断重要性 保存时LLM 分析内容推断范围、类别、重要性得分0-1 召回时重要性高的记忆获得更高召回权重适用场景配置# 偏向长时记忆适合积累专业知识的研究型 Agentlong_term_memoryMemory(importance_weight0.4,# 提高重要性权重recency_half_life_days365,# 1年半衰减长期保留)3.3 实体记忆行为实体记忆通过**层级范围Hierarchical Scopes**实现类似文件系统的路径结构记忆范围层级 /global ← 全局范围所有 Agent 共享 /project/alpha ← 项目级范围 /agent/researcher ← Agent 专属范围 /task/market_analysis ← 任务级范围 /entity/openai ← 实体范围特定公司/人物/概念 /entity/openai/products ← 实体子范围fromcrewaiimportMemory memoryMemory()# 手动存储实体记忆通常由 Agent 自动触发memory.remember(contentOpenAI 于2026年3月发布 GPT-5.4具备原生计算机操控能力,scope/entity/openai,importance0.9# 高重要性长期保留)# 召回实体相关记忆memoriesmemory.recall(queryOpenAI 最新发布了什么模型,scope/entity/openai# 限定在 OpenAI 实体范围内搜索)四、记忆召回的复合评分算法crewAI 的记忆召回不是简单的向量相似度检索而是综合三个维度打分召回评分 语义相似度 × w1 时效性 × w2 重要性 × w3 其中 语义相似度 ─ 查询与记忆内容的向量余弦相似度 时效性 ─ 基于存储时间的衰减得分 重要性 ─ LLM 分析内容时给出的重要性评分 默认权重可配置 w1语义 0.5 w2时效 0.3 w3重要 0.2自定义权重示例fromcrewaiimportMemory# 分析型 Agent更关注重要性对时效性要求低analysis_memoryMemory(semantic_weight0.5,recency_weight0.1,# 降低时效性权重importance_weight0.4,# 提高重要性权重)# 新闻监控 Agent时效性最重要news_memoryMemory(semantic_weight0.4,recency_weight0.5,# 提高时效性权重importance_weight0.1,recency_half_life_days1# 1天半衰减)五、记忆存储后端crewAI 支持多种存储后端可根据部署环境选择5.1 默认本地存储crewCrew(agents[researcher],tasks[task1],memoryTrue# 默认使用本地文件存储)# 记忆存储在 ~/.crewai/memory/ 目录下适合本地开发、单实例部署5.2 自定义 Memory 实例fromcrewaiimportMemory# 自定义存储路径memoryMemory(storage_path/data/crew_memory,# 自定义存储路径embedder{provider:openai,config:{model:text-embedding-3-small}})crewCrew(agents[researcher],tasks[task1],memorymemory# 使用自定义 Memory 实例)5.3 集成外部向量数据库对于需要大规模记忆存储和多实例共享的场景可以集成向量数据库# 使用 Chroma轻量级适合中小规模fromcrewaiimportMemory memoryMemory(embedder{provider:openai,config:{model:text-embedding-3-large}},# 配置 Chroma 作为向量存储后端storage{type:chroma,config:{host:localhost,port:8000,collection_name:crew_memories}})六、记忆隔离多租户场景的关键在 SaaS 平台或多用户场景中不同用户的 Agent 必须使用隔离的记忆空间defcreate_crew_for_user(user_id:str)-Crew:为每个用户创建独立记忆空间的 Crewuser_memoryMemory(storage_pathf/data/memories/{user_id},# 用户级隔离存储# 或通过 scope 参数限定范围)researcherAgent(role个人研究助手,goal帮助用户进行专业研究,backstory...)crewCrew(agents[researcher],tasks[task],memoryuser_memory)returncrew# 每个用户使用独立的 Crew 和记忆空间user_crew_1create_crew_for_user(user_001)user_crew_2create_crew_for_user(user_002)# 两个 Crew 的记忆完全隔离七、无状态模式何时关闭记忆以下场景建议关闭记忆# 批量数据处理每条数据独立处理不需要跨任务记忆batch_crewCrew(agents[processor],tasks[process_task],memoryFalse# 无状态提升性能)# 结果处理速度更快每次执行完全可重现# 并行处理多个相同 Crew 并行运行时避免记忆污染asyncdefprocess_batch(items:list):tasks[]foriteminitems:crewCrew(agents[processor],tasks[task],memoryFalse)tasks.append(crew.akickoff(inputs{item:item}))returnawaitasyncio.gather(*tasks)八、记忆整合避免重复记忆的自动去重crewAI 记忆系统内置了智能去重机制保存新记忆时的流程 │ ▼ 计算与现有记忆的语义相似度 │ ├─ 相似度 阈值默认0.92 │ │ │ ▼ │ 自动合并更新现有记忆保留更高重要性的版本 │ └─ 相似度 阈值 │ ▼ 创建新记忆条目这个机制防止了知识库因重复信息膨胀而降低检索效率。九、实战给研究 Agent 配置最优记忆fromcrewaiimportAgent,Task,Crew,Memory# 针对长期研究项目优化的记忆配置research_memoryMemory(# 重视重要信息的长期留存importance_weight0.4,recency_weight0.2,semantic_weight0.4,# 较长的半衰减期适合长期研究recency_half_life_days90,# 使用高质量 Embedding 模型embedder{provider:openai,config:{model:text-embedding-3-large}})researcherAgent(role资深技术研究员,goal持续追踪AI领域前沿进展积累专业知识库,backstory你是AI领域的独立研究员 已经积累了3年的技术调研经验。 你特别擅长发现跨领域的技术联系。,memoryTrue# Agent 级别开启记忆)tech_research_crewCrew(agents[researcher,analyst,writer],tasks[research_task,analysis_task,writing_task],memoryresearch_memory,# 使用自定义记忆配置verboseTrue)# 随着时间积累这个 Crew 会越来越聪明# 它会记住哪些信息源可靠、哪些技术方向有价值、用户的偏好风格十、小结crewAI 的统一记忆系统设计体现了让 AI 做决策让开发者设参数的哲学LLM 负责判断什么重要、内容属于什么类别开发者通过权重参数调整记忆的时效偏向和重要性偏向存储后端可以灵活替换适应不同的部署规模三个关键决策点是否启用记忆批量处理用 False持续学习型 Agent 用 True权重如何调整实时信息场景提高时效性权重专业知识积累场景提高重要性权重如何隔离多租户场景必须通过存储路径或 scope 做隔离系列导航上一篇crewAI 流程可视化与调试执行链路追踪与性能剖析下一篇crewAI Knowledge 与 RAGChroma/Qdrant 向量知识库集成基于 crewAI v1.11.0 官方文档撰写于 2026 年 3 月
crewAI 记忆架构：短时记忆、长时记忆与实体记忆的层级设计
crewAI 记忆架构短时记忆、长时记忆与实体记忆的层级设计本文基于 crewAI v1.11.0深入解析 crewAI 统一记忆系统的架构设计、配置方式和生产实践。一、为什么 Agent 需要记忆想象一个没有记忆的研究助手每次你问他一个问题他都从零开始不记得上次你说过重点关注中国市场数据不知道他上周已经调研过的那家公司每次交互都在重复建立上下文。这就是没有记忆的 Agent 的现状——它是个高效的失忆症患者。记忆系统让 Agent 能够跨 Task 保持上下文当前任务可以利用同一 Crew 中之前任务的信息跨会话积累经验今天的工作经验可以在明天的任务中发挥作用建立实体知识库记住关键人物、公司、概念的属性形成持久化的知识图谱二、crewAI 的统一记忆系统crewAI v1.11.0 对记忆架构进行了重大升级——用一个统一的Memory类替代了之前分散的短期、长期、实体记忆类型。这个设计的核心思想让 LLM 智能决定如何存储而不是让开发者手动分类。fromcrewaiimportMemory,Crew# 启用记忆的最简单方式crewCrew(agents[researcher,analyst],tasks[task1,task2],memoryTrue# 使用默认配置启用统一记忆系统)三、记忆三层架构的内部实现虽然对外暴露的是统一接口但 crewAI 内部依然维护了三种记忆行为通过权重参数区分3.1 短时记忆行为特征时效性高近期信息权重大随时间衰减 ───────────────────────────────────────────── 控制参数 recency_weight ─ 时效性权重默认 0.3 recency_half_life_days ─ 半衰期默认30天 衰减模型 权重 0.5 ^ (age_days / half_life_days) 1天前的记忆0.5 ^ (1/30) ≈ 0.977几乎不衰减 7天前的记忆0.5 ^ (7/30) ≈ 0.858 30天前的记忆0.5 ^ (30/30) 0.500半衰减 90天前的记忆0.5 ^ (90/30) 0.125大幅衰减适用场景配置fromcrewaiimportMemory# 偏向短时记忆适合实时信息处理场景short_term_memoryMemory(recency_weight0.5,# 提高时效性权重recency_half_life_days7,# 7天半衰减更快遗忘旧信息)3.2 长时记忆行为特征重要信息持久保存不受时间衰减影响 ───────────────────────────────────────────── 控制参数 importance_weight ─ 重要性权重默认 0.2 LLM 自动判断重要性 保存时LLM 分析内容推断范围、类别、重要性得分0-1 召回时重要性高的记忆获得更高召回权重适用场景配置# 偏向长时记忆适合积累专业知识的研究型 Agentlong_term_memoryMemory(importance_weight0.4,# 提高重要性权重recency_half_life_days365,# 1年半衰减长期保留)3.3 实体记忆行为实体记忆通过**层级范围Hierarchical Scopes**实现类似文件系统的路径结构记忆范围层级 /global ← 全局范围所有 Agent 共享 /project/alpha ← 项目级范围 /agent/researcher ← Agent 专属范围 /task/market_analysis ← 任务级范围 /entity/openai ← 实体范围特定公司/人物/概念 /entity/openai/products ← 实体子范围fromcrewaiimportMemory memoryMemory()# 手动存储实体记忆通常由 Agent 自动触发memory.remember(contentOpenAI 于2026年3月发布 GPT-5.4具备原生计算机操控能力,scope/entity/openai,importance0.9# 高重要性长期保留)# 召回实体相关记忆memoriesmemory.recall(queryOpenAI 最新发布了什么模型,scope/entity/openai# 限定在 OpenAI 实体范围内搜索)四、记忆召回的复合评分算法crewAI 的记忆召回不是简单的向量相似度检索而是综合三个维度打分召回评分 语义相似度 × w1 时效性 × w2 重要性 × w3 其中 语义相似度 ─ 查询与记忆内容的向量余弦相似度 时效性 ─ 基于存储时间的衰减得分 重要性 ─ LLM 分析内容时给出的重要性评分 默认权重可配置 w1语义 0.5 w2时效 0.3 w3重要 0.2自定义权重示例fromcrewaiimportMemory# 分析型 Agent更关注重要性对时效性要求低analysis_memoryMemory(semantic_weight0.5,recency_weight0.1,# 降低时效性权重importance_weight0.4,# 提高重要性权重)# 新闻监控 Agent时效性最重要news_memoryMemory(semantic_weight0.4,recency_weight0.5,# 提高时效性权重importance_weight0.1,recency_half_life_days1# 1天半衰减)五、记忆存储后端crewAI 支持多种存储后端可根据部署环境选择5.1 默认本地存储crewCrew(agents[researcher],tasks[task1],memoryTrue# 默认使用本地文件存储)# 记忆存储在 ~/.crewai/memory/ 目录下适合本地开发、单实例部署5.2 自定义 Memory 实例fromcrewaiimportMemory# 自定义存储路径memoryMemory(storage_path/data/crew_memory,# 自定义存储路径embedder{provider:openai,config:{model:text-embedding-3-small}})crewCrew(agents[researcher],tasks[task1],memorymemory# 使用自定义 Memory 实例)5.3 集成外部向量数据库对于需要大规模记忆存储和多实例共享的场景可以集成向量数据库# 使用 Chroma轻量级适合中小规模fromcrewaiimportMemory memoryMemory(embedder{provider:openai,config:{model:text-embedding-3-large}},# 配置 Chroma 作为向量存储后端storage{type:chroma,config:{host:localhost,port:8000,collection_name:crew_memories}})六、记忆隔离多租户场景的关键在 SaaS 平台或多用户场景中不同用户的 Agent 必须使用隔离的记忆空间defcreate_crew_for_user(user_id:str)-Crew:为每个用户创建独立记忆空间的 Crewuser_memoryMemory(storage_pathf/data/memories/{user_id},# 用户级隔离存储# 或通过 scope 参数限定范围)researcherAgent(role个人研究助手,goal帮助用户进行专业研究,backstory...)crewCrew(agents[researcher],tasks[task],memoryuser_memory)returncrew# 每个用户使用独立的 Crew 和记忆空间user_crew_1create_crew_for_user(user_001)user_crew_2create_crew_for_user(user_002)# 两个 Crew 的记忆完全隔离七、无状态模式何时关闭记忆以下场景建议关闭记忆# 批量数据处理每条数据独立处理不需要跨任务记忆batch_crewCrew(agents[processor],tasks[process_task],memoryFalse# 无状态提升性能)# 结果处理速度更快每次执行完全可重现# 并行处理多个相同 Crew 并行运行时避免记忆污染asyncdefprocess_batch(items:list):tasks[]foriteminitems:crewCrew(agents[processor],tasks[task],memoryFalse)tasks.append(crew.akickoff(inputs{item:item}))returnawaitasyncio.gather(*tasks)八、记忆整合避免重复记忆的自动去重crewAI 记忆系统内置了智能去重机制保存新记忆时的流程 │ ▼ 计算与现有记忆的语义相似度 │ ├─ 相似度 阈值默认0.92 │ │ │ ▼ │ 自动合并更新现有记忆保留更高重要性的版本 │ └─ 相似度 阈值 │ ▼ 创建新记忆条目这个机制防止了知识库因重复信息膨胀而降低检索效率。九、实战给研究 Agent 配置最优记忆fromcrewaiimportAgent,Task,Crew,Memory# 针对长期研究项目优化的记忆配置research_memoryMemory(# 重视重要信息的长期留存importance_weight0.4,recency_weight0.2,semantic_weight0.4,# 较长的半衰减期适合长期研究recency_half_life_days90,# 使用高质量 Embedding 模型embedder{provider:openai,config:{model:text-embedding-3-large}})researcherAgent(role资深技术研究员,goal持续追踪AI领域前沿进展积累专业知识库,backstory你是AI领域的独立研究员 已经积累了3年的技术调研经验。 你特别擅长发现跨领域的技术联系。,memoryTrue# Agent 级别开启记忆)tech_research_crewCrew(agents[researcher,analyst,writer],tasks[research_task,analysis_task,writing_task],memoryresearch_memory,# 使用自定义记忆配置verboseTrue)# 随着时间积累这个 Crew 会越来越聪明# 它会记住哪些信息源可靠、哪些技术方向有价值、用户的偏好风格十、小结crewAI 的统一记忆系统设计体现了让 AI 做决策让开发者设参数的哲学LLM 负责判断什么重要、内容属于什么类别开发者通过权重参数调整记忆的时效偏向和重要性偏向存储后端可以灵活替换适应不同的部署规模三个关键决策点是否启用记忆批量处理用 False持续学习型 Agent 用 True权重如何调整实时信息场景提高时效性权重专业知识积累场景提高重要性权重如何隔离多租户场景必须通过存储路径或 scope 做隔离系列导航上一篇crewAI 流程可视化与调试执行链路追踪与性能剖析下一篇crewAI Knowledge 与 RAGChroma/Qdrant 向量知识库集成基于 crewAI v1.11.0 官方文档撰写于 2026 年 3 月
