CrewAI 记忆系统与 Planning

QuibblerAgentQuibblerAgent 2026-11-18 约 17 分钟 25 次阅读

第 2 篇给研究员装上搜索工具之后,三角色流水线仍旧是"失忆"的:上一轮审稿员圈出的"少写排比、多给代码示例",这一轮写手照犯不误——kickoff 一结束,全部上下文就地蒸发,纠错经验无从沉淀。工具解决 Agent"看外面"的问题,记忆解决"记住过去"的问题,两样凑齐,流水线才算有积累。

本篇是《CrewAI 由浅入深》第 3 篇,入门篇收官。全文按"演进 → 最小配置 → 后端替换 → 生效机制 → Planning → 取舍 → 实战"展开,版本口径同前两篇:CrewAI v1.15.41,2026 年 11 月。


1、从四层拆分到统一 Memory

网上大量 CrewAI 记忆教程开头就是四张脸:短期记忆记执行内上下文、长期记忆跨运行沉淀、实体记忆记人物地点、用户记忆按人隔离。这不是杜撰——早期版本确实把 memory 参数拆成 short_term_memory、long_term_memory、entity_memory 等独立配置项,每层各自的实现与存储。但四层的底座其实同构:全部都是"文本向量化后存取检索",拆四层带来的主要是四份配置面与四套心智负担,换来的是"分层"这个产品化想象。

于是官方做了收敛:Memory 官方文档明确写着,单一 Memory 类取代了原先的短期、长期、实体与外部记忆四种独立类型。旧的分层诉求并没有消失,而是换了一种更便宜的机制来承载——scope() 作用域把记忆组织成一棵树,slice() 能把多个分支拼成一个只读或可写视图。旧的四种记忆在新模型里的去向对比如下:

旧分层 职责 统一后的归属
短期记忆 记住本次执行内的任务上下文 Memory 默认行为,自动完成
长期记忆 跨运行持久沉淀经验 Memory 加默认落盘存储
实体记忆 记住人物、地点等实体 scope 作用域子树
用户记忆 按用户隔离偏好 scope 与 slice 划分视图

架构层面的配套变化发生在 v1.15.40:GitHub Releases 该版说明写得直白——把 chromadb 从嵌入函数层移除。这一刀切断的是嵌入与存储的捆绑:嵌入模型由 embedder 配置决定,存储后端走可插拔协议,各自独立更换。旧教程里"通过 LangChain vector store 适配 ChromaDB、FAISS"的玩法在当前官方文档里已查无此项,照抄必踩版本坑——这也是本节花一整节讲演进的原因:记忆是 CrewAI 近期变动最大的子系统,版本对不上,教程全作废。

2、最小配置跑通记忆

统一之后,开启记忆的门槛降到了一行。给第 1 篇的三角色 Crew 加上 memory=True:

from crewai import Crew, Process

crew = Crew(
    agents=[researcher, writer, reviewer],
    tasks=[research_task, write_task, review_task],
    process=Process.sequential,
    memory=True,  # 一行开启,默认嵌入与存储
    verbose=True,
)

result = crew.kickoff(inputs={"topic": "CrewAI 记忆系统"})

memory=True 的语义是"全部用默认":框架自建一个 Memory() 实例,默认嵌入走 OpenAI 的 text-embedding-3-large(3072 维,因此需要 OPENAI_API_KEY),默认存储用嵌入式 LanceDB,数据落在项目下的 .crewai/memory 目录。也正因为默认落盘,第二次 kickoff 时上次执行的关键结论已经在库里等着被召回——记忆的持久化不需要任何额外配置。

想要更细的控制,就把 True 换成一个配置好的 Memory 实例:memory=Memory(...),嵌入、存储、评分权重都在构造参数里调,这正是第 3 节的内容。日常维护有两个入口:代码里 crew.reset_memories(command_type="memory") 清空记忆,命令行 crewai reset-memories -m 等效;crewai memory --storage-path ./my_memory 则提供一个 TUI 浏览器直接翻看记忆库里存了什么。

3、嵌入与存储后端

3.1、换嵌入模型

先澄清一个高频误会:不少资料与 AI 摘要会说"用 EmbeddingConfig 类配置嵌入"——当前版本没有这个类,嵌入配置就是一个普通字典,传给 Memory 的 embedder 参数。换成 Ollama 本地嵌入的写法如下:

from crewai import Crew, Memory

memory = Memory(
    embedder={
        "provider": "ollama",  # 本地嵌入,不再依赖 OpenAI 密钥
        "config": {"model_name": "mxbai-embed-large"},
    }
)

crew = Crew(agents=[researcher, writer, reviewer],
            tasks=[research_task, write_task, review_task],
            memory=memory)

embedder 接收字典、预构建的嵌入函数或 None(用默认),provider 覆盖主流厂商,常用的几个如下:

provider 说明
openai 默认,text-embedding-3-large
ollama 本地运行,零密钥依赖
azure 需在 config 里给 deployment_id
google-generativeai 谷歌系嵌入
sentence-transformer 本地开源模型

换嵌入模型有个必须知道的坑:向量维度随模型变。默认是 3072 维,如果记忆库里存的是旧模型(如 1536 维的 text-embedding-3-small)算出的向量,新旧混用会维度不匹配。官方给的解法是换模型后执行 crewai reset-memories -m 清库重来,或锁定旧模型不升级。

3.2、换存储后端

默认的 LanceDB 是嵌入式数据库,单机零部署,原型阶段完全够用。往上走有两个方向。第一个只换位置:Memory(storage="/data/crew_memory") 传一个路径字符串,$CREWAI_STORAGE_DIR 环境变量也能达成同样效果,底层仍是内置存储。第二个换实现:实现 StorageBackend 协议(crewai.memory.storage.backend 模块),把自家的向量库、Redis、MySQL 包装成后端传入:

from crewai import Memory
from crewai.memory.storage.backend import StorageBackend

# 其一:字符串路径,仅换落盘位置,仍是内置存储
memory = Memory(storage="/data/crew_memory")

# 其二:自定义后端,按协议实现读写检索接口
class MyBackend(StorageBackend):
    """把自研存储包装成 CrewAI 记忆后端"""

memory = Memory(storage=MyBackend())

生产可用的现成选项是 MongoDB:官方生态的 crewai-mongodb-memory 包提供 MongoDBStorageBackend,装包即用。存储层的选型标准与任何向量检索场景一致——并发写入、多实例共享、运维成熟度,CrewAI 侧不再附加约束,这正是 v1.15.40 那一刀切捆的好处。

4、记忆在执行中如何生效

配置讲完,机制要落地到一句可验证的话:记忆的生效点是每个任务的执行前后。任务开始前,框架用当前任务描述作为查询去 recall 相关历史记忆,命中内容注入该任务的上下文;任务结束后,本次执行的关键结论与事实被 remember 写回记忆库。写入是非阻塞的,每次 recall 与 kickoff 收尾都会先执行 drain_writes() 排空写队列再读,保证不读到陈旧数据。

召回不是简单的相似度 Top-K,而是复合评分:语义相似度权重 0.5、新近度权重 0.3、重要性权重 0.2,其中新近度按 30 天半衰期衰减——一个月前的老结论会自然让位给上周的新结论。整条链路画出来:

flowchart LR A[kickoff 启动] --> B[按任务描述召回记忆] B --> C[命中内容注入上下文] C --> D[Agent 执行任务] D --> E[关键结论写回记忆] E --> F[下一任务或下次运行] F --> B

解读:闭环的最后一段是"下次运行"——因为默认存储落盘,这个循环跨进程、跨天成立,这正是长期记忆的全部秘密。多 Agent 场景还可以划领地:Agent(memory=memory.scope("/agent/researcher")) 给研究员一份私有作用域,memory.slice(scopes=[...], read_only=True) 再把公司知识库拼成只读视图,记忆树天然承担了旧模型里实体记忆与用户记忆的隔离职责。

5、Planning 开关

记忆管"带着过去跑",Planning 管"先想后跑"。Crew 加 planning=True 后,Planning 官方文档描述的行为是:任务执行前,全部 Crew 信息(角色、目标、任务清单)先交给规划组件,它逐任务生成分步计划,并把计划追加进该任务的 description,然后才轮到正式执行;每次 kickoff 计划都会重新生成。源码层面,这个规划组件叫 CrewPlanner,它内部再组装一个专职规划的内部 Crew——PlannerCrew——去产出计划,本质是用一个小 Crew 规划大 Crew。

写法与效果示例如下:

crew = Crew(
    agents=[researcher, writer, reviewer],
    tasks=[research_task, write_task, review_task],
    process=Process.sequential,
    memory=True,
    planning=True,  # 先规划再执行
    planning_llm="deepseek/deepseek-chat",  # 显式指定规划模型
    verbose=True,
)

planning_llm 必须显式给的动机在官方文档里有专门警告:默认规划模型是 OpenAI 系,即使你的 Agent 全用别家模型,不配 OpenAI 密钥也会在规划阶段直接报错。两种执行的差异整理如下:

维度 默认执行 planning=True
启动动作 直接进入首个任务 先逐任务生成分步计划
任务描述 你写的原始描述 追加了该任务的计划
执行稳定性 依赖模型自由发挥 步骤显式,复杂任务更稳
额外成本 无 多一轮规划调用与时延

经验判断:三步以内的小任务,规划是画蛇添足;任务描述长、多工具配合、模型偏弱的场景,规划收益明显。另有一个易混点要提醒:Agent 也有一级 Agent(planning=True) 参数,那是另一套"计划-执行"推理循环,与 Crew 级规划互不相干,看日志时别认错了对象。

6、什么时候不需要记忆

记忆不是免费午餐,开错了比不开更糟。判断标准只有一条:这次执行能否复用历史。常见场景的建议如下:

场景 建议
同类任务反复运行 开记忆,沉淀风格与事实
一次性单跑流水线 不开,省检索与 token
多主题批量处理 不开或隔离,防互相污染
生产多实例部署 必换持久后端,本地盘会丢

单次流水线开记忆,纯属白付两笔钱:每个任务前多一轮向量检索的时延,命中内容注入上下文的 token。多主题批量(kickoff_for_each 跑十个主题)更危险——A 主题的调研结论被召回进 B 主题的上下文,记忆变成串味器。默认嵌入还附带 OpenAI 密钥与计费依赖,本地化部署别忘了先按 3.1 节换嵌入。真发生了污染,crewai reset-memories -m 一键清库,代价是历史经验全部归零——防大于治。

7、实战:流水线记住风格

回到系列主线,给三角色内容流水线加上跨次运行的风格记忆。改动只有两处:Crew 加 memory=True,写手任务描述里显式留出"调用历史"的口子:

write_task = Task(
    description="基于调研要点写一篇 800 字左右的博客初稿。"
                "先回忆历史审稿反馈(文风、结构、篇幅偏好),"
                "本次写作全部遵守。主题:{topic}。",
    expected_output="遵守历史反馈的博客初稿",
    agent=writer,
)

crew = Crew(
    agents=[researcher, writer, reviewer],
    tasks=[research_task, write_task, review_task],
    process=Process.sequential,
    memory=True,  # 长期记忆跨 kickoff 持久
    verbose=True,
)

任务描述那句"先回忆历史审稿反馈"不是仪式性措辞——记忆召回由框架自动完成,但模型是否认真利用召回内容,取决于任务描述有没有提出要求。留这个口子,检索结果才从"上下文里的摆设"变成"写作的约束"。

验证方法:同一主题连跑两遍。第一遍结束后,审稿员的修改意见(少排比、多代码示例之类)已写进记忆;第二遍开着 verbose=True 观察,写手任务执行前的日志里能看到记忆召回的痕迹,最终初稿应当直接体现上一轮的反馈。再换相近主题跑第三遍,风格偏好依然生效——经验完成了从"单次执行"到"这个 Crew 的工作资产"的迁移。

8、总结

本文把 CrewAI 的记忆与规划两个开关讲透了。记忆侧:旧的四层拆分已统一为单一 Memory 类,scope 与 slice 承接原来的隔离诉求;memory=True 一行启用,默认 OpenAI 嵌入加 LanceDB 落盘;换嵌入是 embedder 字典(没有 EmbeddingConfig 这个类),换存储是 StorageBackend 协议;生效机制是任务前召回、任务后写回,复合评分 0.5 语义、0.3 新近度、0.2 重要性。规划侧:planning=True 让 CrewPlanner(内部用 PlannerCrew)先逐任务出分步计划再执行,planning_llm 要显式配,否则默认找 OpenAI 要密钥。取舍上记住一句话:能复用历史才开记忆,单次流水线不开。

三个练习留给读者:

  • 给第 1 篇的三角色 Crew 加 memory=True,同主题连跑两遍,对比输出与召回日志的差异
  • 按 3.1 节把嵌入换成 Ollama 本地模型,验证脱离 OPENAI_API_KEY 后记忆仍然工作
  • 开 planning=True 重跑一次,读一遍生成的分步计划,再对比有无规划时终稿质量的差异

入门篇到此收官:第 1 篇立住三要素,第 2 篇装上工具,本篇加上记忆与规划,一副多角色系统的骨架已经完整。进阶篇从第 4 篇开始讲 Flows——官方生产叙事的主角,Crew 之上的工作流骨架。对于想继续深入的工程师,建议先把本篇实战跑出"第二遍记得第一遍"的体感,再往 Flows 走。

相关推荐

​Jev 详解:不做生成的判断模型
精选AI

​Jev 详解:不做生成的判断模型

Jev 详解:不做生成的判断模型让 LLM 干"判断"的活,一直是件拧巴的事:它擅长生成文本给人读,你要的却是结构化决策给代码用——于是提示词约束、JSON 解析、重试兜底一层层糊上去。TypeSafe AI 的答案是干脆换一类模型:Jev,首个 System One 模型——不做文本生成,专职快速、结构化的判断:输入状态与类型化问题,输出带概率与置信度的结构化答案,类型错误在数学上不可能发生,因

759
网站被注入恶意脚本排查实录:AI 辅助安全分析实战
置顶 精选AI

网站被注入恶意脚本排查实录:AI 辅助安全分析实战

网站被注入恶意脚本排查实录:AI 辅助安全分析实战某天收到华为云监管反馈,称个人博客网站存在色情违规界面。作为技术博主,这简直是晴天霹雳——网站一直正常运行,怎么会突然出现这类问题?经过排查发现,网站被注入了恶意跳转脚本。本文记录完整的排查过程,重点分享如何借助 AI 快速定位问题并修复,希望能给遇到类似情况的开发者提供参考。1、问题发现与初步排查收到监管反馈后,第一时间打开网站检查。首页看起来完

441
博客七周年:AI 一天完成整体重构
全站置顶 精选AI

博客七周年:AI 一天完成整体重构

博客从 2019 年国庆用 Xiuno BBS 搭建,到 2026 年国庆整整七年。868 篇文章、53 条评论、6060 个代码块,这次与 AI Agent 结对,一天完成从 PHP 论坛到 Next.js 的整体重构与无损迁移。

415