1. 为什么AI代理需要一个真正的记忆引擎做过AI代理项目的人多半都经历过这个场景用户上周明确说过“我对花生过敏”这周再问餐厅推荐代理照样推了一家主打花生酱的店。不是模型不够聪明而是它压根没记住。大语言模型本身是无状态的每次对话都是一张白纸上下文窗口再大也扛不住长期交互的累积。这就是记忆引擎要解决的核心问题。cognee这个开源方案本质上是在给AI代理装一套“外挂大脑”。它做的事情可以拆成三层第一层是把对话、文档、结构化数据统一转成向量和图的混合表示第二层是用图结构维护实体之间的关系比如“用户A-过敏-花生”这条边第三层是提供检索接口让代理在需要的时候按语义或按关系把记忆捞出来。相比单纯用向量数据库做RAGcognee多了一张知识图谱这让它在处理“谁和谁有关系”“什么时候发生的”这类问题上明显更稳。这套方案适合谁如果你正在做客服机器人、个人助理、多轮任务型代理或者任何需要跨会话保持状态的AI应用cognee值得花时间研究。它不绑定特定模型OpenAI、本地部署的模型都能接对中小团队比较友好。下面我会从整体设计、核心细节、实操搭建、问题排查四个维度把这套记忆引擎拆开讲清楚。2. 整体架构设计与方案选型思路2.1 记忆引擎的三层结构拆解cognee的架构不是拍脑袋定的它对应的是人类记忆的三种形态。第一层是短期记忆对应对话的原始文本存在关系型数据库里保证不丢数据。第二层是语义记忆把文本切片后做embedding存进向量库负责“意思相近就能找到”。第三层是结构化记忆用图数据库存实体和关系负责“顺着线索找到关联信息”。这三层不是并列的而是有先后依赖。原始文本进来后先做实体抽取和关系抽取抽出来的三元组进图库同时文本切片进向量库。检索的时候cognee会先走向量召回一批候选再用图结构做扩展和过滤最后把结果拼成上下文喂给模型。这个“向量召回图扩展”的组合是它比纯RAG更准的关键。为什么不用纯向量方案我实测过一个案例用户问“我上次说的那个项目现在什么进度”。纯向量检索会把“项目”这个词匹配到一堆无关文档因为它不知道“上次说的那个项目”具体指哪个。但图库里如果之前存了“用户-提及-项目X”这条边就能直接定位到项目X再顺着边找它的状态节点。这就是结构化记忆的价值。2.2 为什么选cognee而不是自己造轮子自己搭一套记忆系统不是不行但有几个坑很难绕。第一是实体抽取的稳定性你得处理同义词、指代消解、时间归一化这些做起来比想象中费时间。第二是图和向量的同步文本更新了图里的节点和边也得跟着更新手动维护很容易出现数据不一致。第三是检索策略的调优什么时候走向量、什么时候走图、怎么融合打分这些需要大量实验。cognee把这些脏活累活封装好了提供统一的add和search接口。你只管往里灌数据它负责抽取、存储、索引。而且它是开源的核心逻辑都能看到遇到问题可以改源码不像闭源方案那样只能等官方更新。对于想快速验证记忆功能的团队这个方案能省掉至少两到三周的基建时间。2.3 六套代码的划分逻辑标题里说的“6套代码”指的是cognee使用流程中的六个核心模块不是六个独立的项目。这六块分别是环境与依赖初始化、数据接入与预处理、实体与关系抽取、向量与图双写、检索与上下文组装、代理集成与调用。每一块都有对应的代码示例可以单独跑通也可以串起来用。这种划分方式的好处是你可以按需取用。比如你已经有向量库了只想补图结构那就重点看第三和第四块。如果你是从零开始那就六块都过一遍。下面我会按这个顺序把每块的核心代码和背后的设计意图讲透。3. 核心细节解析与实操要点3.1 数据接入别把什么都往里塞cognee支持多种数据源文本、PDF、JSON、甚至数据库连接都能接。但这里有个实操心得不是所有数据都值得进记忆引擎。我见过有人把整个知识库全灌进去结果检索时噪音太大反而拉低了准确率。合理的做法是分层接入。高频访问、需要跨会话记住的内容比如用户偏好、任务状态、关键决策优先接入。低频的、一次性的、查完就扔的内容走普通RAG就行没必要进图库。cognee的add接口支持打标签你可以用标签区分数据的重要级别检索时按标签过滤。代码层面接入的核心是cognee.add()。它接受文本或文件路径内部会自动做分块和清洗。分块大小默认是512个token这个值可以调。我的经验是对话类数据用256到384比较合适因为对话轮次短块太大反而把无关内容混进来。文档类数据可以用512到1024保持语义完整性。import cognee import asyncio async def ingest_data(): # 接入对话记录 await cognee.add( 用户提到对花生过敏推荐餐厅时需避开含花生的菜品, dataset_nameuser_preferences ) # 接入文档 await cognee.add( /path/to/project_doc.pdf, dataset_nameproject_knowledge ) asyncio.run(ingest_data())注意dataset_name这个参数很关键它相当于给数据分文件夹。检索时可以指定只在某个dataset里搜能大幅减少无关结果。别把所有数据都塞进默认dataset。3.2 实体抽取图结构的地基实体抽取是cognee最核心的环节也是最容易出问题的地方。它默认用LLM来做抽取因为规则匹配覆盖不了开放域。抽取的prompt里会要求模型输出“主体-关系-客体”的三元组比如“用户-过敏-花生”。这里有个坑LLM抽取的稳定性受温度参数影响很大。温度设高了同一段文本每次抽出来的实体可能不一样设低了又可能漏掉一些隐含关系。我的建议是把抽取用的温度固定在0.1到0.2之间牺牲一点多样性换稳定性。cognee允许你自定义抽取的prompt如果你有特定领域的实体类型可以在prompt里加few-shot示例效果会明显提升。另一个要点是实体消解。同一个东西可能有多种说法比如“花生”“花生酱”“peanut”如果不做归一化图里会出现多个节点关系就断了。cognee内置了简单的消解逻辑但复杂场景下还是得自己加规则。我通常会在抽取后加一步后处理用embedding相似度把同义实体合并。3.3 双写机制向量和图怎么同步cognee的数据写入是“双写”的文本切片进向量库三元组进图库。这两步是异步的但cognee保证了最终一致性。实操中要注意的是如果图库写入失败向量库可能已经写进去了这时候需要有个补偿机制。我的做法是在add之后加一个校验步骤查一下图库里有没有对应的节点。如果没有就重新触发抽取。cognee的API返回里带了任务状态可以轮询检查。虽然多了一步但能避免“搜得到文本但找不到关系”的尴尬情况。向量库的选择上cognee默认支持几种常见的向量数据库。小规模场景用内存版就行数据量上到十万条以上建议换成持久化的方案。图库方面它默认用的是轻量级的图存储如果关系特别复杂可以换成更专业的图数据库。切换的方式是改配置文件不用动业务代码。3.4 检索策略向量召回加图扩展检索是记忆引擎的出口直接决定代理的回答质量。cognee的检索分两步先用向量相似度召回一批候选节点再以这些节点为起点在图里做N跳扩展。N默认是2意思是找直接关联和间接关联的节点。这个N值很讲究。设成1只能找到直接关系比如“用户-过敏-花生”设成2能找到“用户-过敏-花生-属于-坚果类”信息更丰富但噪音也更多。我的经验是事实型查询用1跳推理型查询用2跳再大就容易引入无关信息了。检索结果会拼成一段上下文格式是“实体-关系-实体”的文本描述。这段文本会跟原始对话一起喂给模型。这里要注意上下文的长度控制cognee默认会截断但截断策略可以调。我通常会把图检索的结果放在前面因为结构化信息密度高模型更容易抓住重点。async def search_memory(query): results await cognee.search( query_textquery, dataset_nameuser_preferences, hops2, top_k5 ) return results提示top_k控制向量召回的候选数量设太小可能漏掉关键节点设太大则图扩展的计算量飙升。5到10之间是比较平衡的范围。4. 实操过程与核心环节实现4.1 环境搭建与依赖安装先把基础环境跑起来。cognee是Python包建议用3.10以上的版本低版本有些异步特性支持不好。虚拟环境用venv或conda都行我习惯用venv轻量。python -m venv cognee_env source cognee_env/bin/activate # Windows用 cognee_env\Scripts\activate pip install cognee安装完之后要配置LLM和embedding模型。cognee默认走OpenAI的接口如果你用本地模型需要改配置文件。配置项包括API key、base url、模型名称。embedding模型建议选维度在768到1536之间的维度太低语义区分度不够太高存储和计算成本上去了。配置文件的路径通常在用户目录下的.cognee文件夹里。第一次运行时会自动生成模板你填好之后保存就行。这里有个细节抽取用的LLM和最终生成回答用的LLM可以分开配。抽取任务对模型的理解能力要求高可以用大一点的模型生成回答可以用小模型省成本。4.2 数据灌入与预处理实战环境好了之后先灌一批测试数据。我建议从对话记录开始因为对话数据最能体现记忆引擎的价值。准备一段多轮对话里面包含用户偏好、任务状态、时间信息然后调add接口。灌入之后cognee会在后台跑抽取任务。这个过程是异步的你可以用cognee.get_status()查进度。抽取完成后图库里应该能看到实体和关系。我通常会写个小脚本把图里的节点和边打印出来肉眼检查一下抽取质量。预处理阶段有个容易被忽略的点时间信息的处理。对话里经常出现“昨天”“上周”“下个月”这种相对时间如果不转成绝对时间图里的时间关系就没法做推理。cognee内置了时间归一化的逻辑但覆盖不全。我的做法是在灌入前先用正则把相对时间替换成绝对时间再交给cognee。4.3 检索调优与上下文组装检索调优是个反复迭代的过程。我的方法是准备一组测试问题每个问题都有预期答案然后跑检索看召回结果对不对。如果召回不准先查向量库的embedding质量再查图扩展的跳数设置。上下文组装这块cognee默认会把检索结果按相关性排序后拼接。但模型对上下文的顺序敏感重要的信息放前面效果更好。我一般会手动重排一下把图检索的结构化结果放最前面向量召回的文本片段放后面。另外如果检索结果里有冲突信息比如两个节点说的时间不一致要在上下文里标注出来让模型自己判断。async def build_context(query): results await cognee.search(query_textquery, hops2) # 结构化结果优先 structured [r for r in results if r[type] graph] unstructured [r for r in results if r[type] vector] context \n.join([r[text] for r in structured unstructured]) return context4.4 代理集成与调用闭环最后一步是把记忆引擎接到代理里。代理的流程通常是接收用户输入先查记忆把记忆和输入一起给模型模型生成回答再把这轮对话写回记忆。这个闭环里写回的记忆要包含用户的原始输入和代理的回答这样下次才能检索到。集成的代码不复杂关键是要处理好异步。cognee的写入是异步的如果代理要求低延迟可以先把回答返回给用户写入操作放后台队列慢慢跑。但这样有个风险如果写入失败记忆就丢了。我的做法是加一个重试队列写入失败的任务进队列定时重试。调用频率上也要注意。不是每轮对话都需要查记忆简单的事实问答可以直接走模型。我的策略是涉及用户偏好、历史状态、跨会话信息的问题才查记忆其他走普通流程。这样能省不少检索开销。5. 常见问题与排查技巧实录5.1 抽取结果不稳定怎么办这是被问得最多的问题。同一段文本跑两次抽取结果不一样。原因通常是LLM的温度参数没固定或者prompt里的示例不够明确。解决办法是把温度锁死在0.1然后在prompt里加三到五个few-shot示例覆盖你关心的实体类型。如果还是不稳定可以考虑换抽取模型。有些小模型在特定领域的抽取上反而比大模型稳因为大模型容易“过度理解”把没明说的关系也抽出来。我试过用专门做信息抽取的模型准确率比通用模型高不少。5.2 检索召回率低怎么调召回率低一般有三个原因embedding质量差、分块策略不合理、图扩展跳数不够。排查顺序是先看embedding用几个已知相似的句子测一下余弦相似度如果相似句的分数低于0.7说明embedding模型不行得换。分块策略的问题更隐蔽。如果块切得太碎一个完整的意思被切成两半检索时两边都召不回。我的经验是对话数据按轮次切文档数据按段落切别用固定长度硬切。cognee支持自定义分块函数可以按你的数据特点来。图扩展跳数不够的情况表现为“明明图里有关系但检索没带出来”。这时候把hops从1调到2试试。如果调到2还是不行检查一下图里的边是不是方向反了或者关系类型没匹配上。5.3 数据更新后记忆不同步这个问题在频繁更新的场景里很常见。用户改了偏好但图里还是旧的关系。cognee的更新是追加式的不会自动删除旧节点。所以你需要自己维护一个更新逻辑新数据进来时先查图里有没有冲突的旧关系有的话标记为失效或直接删除。我的做法是给每个关系加一个时间戳检索时只取最新时间戳的关系。这样不用删数据也能保证记忆是最新的。cognee的图存储支持自定义属性加时间戳不难。5.4 性能瓶颈排查速查表现象可能原因排查方法解决方向写入慢抽取模型响应慢看抽取任务的耗时日志换小模型或加缓存检索慢图扩展跳数过大打印每跳的节点数降低hops或加过滤条件内存高向量库全量加载看内存占用曲线换持久化向量库结果不准实体消解没做好检查图里的重复节点加同义合并规则上下文超长检索结果太多统计拼接后的token数调低top_k或加截断这张表是我踩坑之后整理的基本覆盖了八成以上的常见问题。遇到新问题先往这几个方向靠能省不少排查时间。5.5 几个容易被忽略的细节第一个是冷启动问题。记忆引擎刚上线时图里是空的检索效果很差。这时候可以先用一批种子数据灌进去比如常见的用户偏好模板让图先有个基础结构。第二个是多用户隔离。如果代理服务多个用户记忆必须按用户隔离否则A的偏好会污染B的推荐。cognee的dataset机制可以做隔离但要在检索时严格带上用户标识别漏了。第三个是记忆的过期策略。不是所有记忆都值得永久保留。临时性的信息比如“用户今天心情不好”过几天就没用了。我通常会设一个TTL超过时间的记忆自动降权或删除。cognee本身没有TTL机制得自己在应用层做。6. 记忆引擎的扩展方向与个人体会这套方案跑通之后能扩展的方向不少。往深了做可以加记忆的重要性打分让代理优先记住关键信息。往宽了做可以接多模态数据把图片和音频也纳入记忆。cognee的架构是支持扩展的核心的抽取和检索接口都可以替换成自定义实现。我自己在实际项目里最大的体会是记忆引擎的价值不在于技术多复杂而在于它让代理的行为变得可预期。没有记忆的代理每次对话都像第一次见面用户得反复交代背景。有了记忆之后代理能记住上下文交互体验的提升是立竿见影的。但记忆也不是越多越好噪音记忆反而会干扰判断。所以接入数据时要克制宁缺毋滥。最后分享一个小技巧调试记忆引擎时把图结构可视化出来看比看日志直观得多。cognee支持导出图数据用常见的图可视化工具打开一眼就能看出实体抽取和关系连接的问题。这个习惯帮我省了很多排查时间。
1. 为什么AI代理需要一个真正的记忆引擎做过AI代理项目的人多半都经历过这个场景用户上周明确说过“我对花生过敏”这周再问餐厅推荐代理照样推了一家主打花生酱的店。不是模型不够聪明而是它压根没记住。大语言模型本身是无状态的每次对话都是一张白纸上下文窗口再大也扛不住长期交互的累积。这就是记忆引擎要解决的核心问题。cognee这个开源方案本质上是在给AI代理装一套“外挂大脑”。它做的事情可以拆成三层第一层是把对话、文档、结构化数据统一转成向量和图的混合表示第二层是用图结构维护实体之间的关系比如“用户A-过敏-花生”这条边第三层是提供检索接口让代理在需要的时候按语义或按关系把记忆捞出来。相比单纯用向量数据库做RAGcognee多了一张知识图谱这让它在处理“谁和谁有关系”“什么时候发生的”这类问题上明显更稳。这套方案适合谁如果你正在做客服机器人、个人助理、多轮任务型代理或者任何需要跨会话保持状态的AI应用cognee值得花时间研究。它不绑定特定模型OpenAI、本地部署的模型都能接对中小团队比较友好。下面我会从整体设计、核心细节、实操搭建、问题排查四个维度把这套记忆引擎拆开讲清楚。2. 整体架构设计与方案选型思路2.1 记忆引擎的三层结构拆解cognee的架构不是拍脑袋定的它对应的是人类记忆的三种形态。第一层是短期记忆对应对话的原始文本存在关系型数据库里保证不丢数据。第二层是语义记忆把文本切片后做embedding存进向量库负责“意思相近就能找到”。第三层是结构化记忆用图数据库存实体和关系负责“顺着线索找到关联信息”。这三层不是并列的而是有先后依赖。原始文本进来后先做实体抽取和关系抽取抽出来的三元组进图库同时文本切片进向量库。检索的时候cognee会先走向量召回一批候选再用图结构做扩展和过滤最后把结果拼成上下文喂给模型。这个“向量召回图扩展”的组合是它比纯RAG更准的关键。为什么不用纯向量方案我实测过一个案例用户问“我上次说的那个项目现在什么进度”。纯向量检索会把“项目”这个词匹配到一堆无关文档因为它不知道“上次说的那个项目”具体指哪个。但图库里如果之前存了“用户-提及-项目X”这条边就能直接定位到项目X再顺着边找它的状态节点。这就是结构化记忆的价值。2.2 为什么选cognee而不是自己造轮子自己搭一套记忆系统不是不行但有几个坑很难绕。第一是实体抽取的稳定性你得处理同义词、指代消解、时间归一化这些做起来比想象中费时间。第二是图和向量的同步文本更新了图里的节点和边也得跟着更新手动维护很容易出现数据不一致。第三是检索策略的调优什么时候走向量、什么时候走图、怎么融合打分这些需要大量实验。cognee把这些脏活累活封装好了提供统一的add和search接口。你只管往里灌数据它负责抽取、存储、索引。而且它是开源的核心逻辑都能看到遇到问题可以改源码不像闭源方案那样只能等官方更新。对于想快速验证记忆功能的团队这个方案能省掉至少两到三周的基建时间。2.3 六套代码的划分逻辑标题里说的“6套代码”指的是cognee使用流程中的六个核心模块不是六个独立的项目。这六块分别是环境与依赖初始化、数据接入与预处理、实体与关系抽取、向量与图双写、检索与上下文组装、代理集成与调用。每一块都有对应的代码示例可以单独跑通也可以串起来用。这种划分方式的好处是你可以按需取用。比如你已经有向量库了只想补图结构那就重点看第三和第四块。如果你是从零开始那就六块都过一遍。下面我会按这个顺序把每块的核心代码和背后的设计意图讲透。3. 核心细节解析与实操要点3.1 数据接入别把什么都往里塞cognee支持多种数据源文本、PDF、JSON、甚至数据库连接都能接。但这里有个实操心得不是所有数据都值得进记忆引擎。我见过有人把整个知识库全灌进去结果检索时噪音太大反而拉低了准确率。合理的做法是分层接入。高频访问、需要跨会话记住的内容比如用户偏好、任务状态、关键决策优先接入。低频的、一次性的、查完就扔的内容走普通RAG就行没必要进图库。cognee的add接口支持打标签你可以用标签区分数据的重要级别检索时按标签过滤。代码层面接入的核心是cognee.add()。它接受文本或文件路径内部会自动做分块和清洗。分块大小默认是512个token这个值可以调。我的经验是对话类数据用256到384比较合适因为对话轮次短块太大反而把无关内容混进来。文档类数据可以用512到1024保持语义完整性。import cognee import asyncio async def ingest_data(): # 接入对话记录 await cognee.add( 用户提到对花生过敏推荐餐厅时需避开含花生的菜品, dataset_nameuser_preferences ) # 接入文档 await cognee.add( /path/to/project_doc.pdf, dataset_nameproject_knowledge ) asyncio.run(ingest_data())注意dataset_name这个参数很关键它相当于给数据分文件夹。检索时可以指定只在某个dataset里搜能大幅减少无关结果。别把所有数据都塞进默认dataset。3.2 实体抽取图结构的地基实体抽取是cognee最核心的环节也是最容易出问题的地方。它默认用LLM来做抽取因为规则匹配覆盖不了开放域。抽取的prompt里会要求模型输出“主体-关系-客体”的三元组比如“用户-过敏-花生”。这里有个坑LLM抽取的稳定性受温度参数影响很大。温度设高了同一段文本每次抽出来的实体可能不一样设低了又可能漏掉一些隐含关系。我的建议是把抽取用的温度固定在0.1到0.2之间牺牲一点多样性换稳定性。cognee允许你自定义抽取的prompt如果你有特定领域的实体类型可以在prompt里加few-shot示例效果会明显提升。另一个要点是实体消解。同一个东西可能有多种说法比如“花生”“花生酱”“peanut”如果不做归一化图里会出现多个节点关系就断了。cognee内置了简单的消解逻辑但复杂场景下还是得自己加规则。我通常会在抽取后加一步后处理用embedding相似度把同义实体合并。3.3 双写机制向量和图怎么同步cognee的数据写入是“双写”的文本切片进向量库三元组进图库。这两步是异步的但cognee保证了最终一致性。实操中要注意的是如果图库写入失败向量库可能已经写进去了这时候需要有个补偿机制。我的做法是在add之后加一个校验步骤查一下图库里有没有对应的节点。如果没有就重新触发抽取。cognee的API返回里带了任务状态可以轮询检查。虽然多了一步但能避免“搜得到文本但找不到关系”的尴尬情况。向量库的选择上cognee默认支持几种常见的向量数据库。小规模场景用内存版就行数据量上到十万条以上建议换成持久化的方案。图库方面它默认用的是轻量级的图存储如果关系特别复杂可以换成更专业的图数据库。切换的方式是改配置文件不用动业务代码。3.4 检索策略向量召回加图扩展检索是记忆引擎的出口直接决定代理的回答质量。cognee的检索分两步先用向量相似度召回一批候选节点再以这些节点为起点在图里做N跳扩展。N默认是2意思是找直接关联和间接关联的节点。这个N值很讲究。设成1只能找到直接关系比如“用户-过敏-花生”设成2能找到“用户-过敏-花生-属于-坚果类”信息更丰富但噪音也更多。我的经验是事实型查询用1跳推理型查询用2跳再大就容易引入无关信息了。检索结果会拼成一段上下文格式是“实体-关系-实体”的文本描述。这段文本会跟原始对话一起喂给模型。这里要注意上下文的长度控制cognee默认会截断但截断策略可以调。我通常会把图检索的结果放在前面因为结构化信息密度高模型更容易抓住重点。async def search_memory(query): results await cognee.search( query_textquery, dataset_nameuser_preferences, hops2, top_k5 ) return results提示top_k控制向量召回的候选数量设太小可能漏掉关键节点设太大则图扩展的计算量飙升。5到10之间是比较平衡的范围。4. 实操过程与核心环节实现4.1 环境搭建与依赖安装先把基础环境跑起来。cognee是Python包建议用3.10以上的版本低版本有些异步特性支持不好。虚拟环境用venv或conda都行我习惯用venv轻量。python -m venv cognee_env source cognee_env/bin/activate # Windows用 cognee_env\Scripts\activate pip install cognee安装完之后要配置LLM和embedding模型。cognee默认走OpenAI的接口如果你用本地模型需要改配置文件。配置项包括API key、base url、模型名称。embedding模型建议选维度在768到1536之间的维度太低语义区分度不够太高存储和计算成本上去了。配置文件的路径通常在用户目录下的.cognee文件夹里。第一次运行时会自动生成模板你填好之后保存就行。这里有个细节抽取用的LLM和最终生成回答用的LLM可以分开配。抽取任务对模型的理解能力要求高可以用大一点的模型生成回答可以用小模型省成本。4.2 数据灌入与预处理实战环境好了之后先灌一批测试数据。我建议从对话记录开始因为对话数据最能体现记忆引擎的价值。准备一段多轮对话里面包含用户偏好、任务状态、时间信息然后调add接口。灌入之后cognee会在后台跑抽取任务。这个过程是异步的你可以用cognee.get_status()查进度。抽取完成后图库里应该能看到实体和关系。我通常会写个小脚本把图里的节点和边打印出来肉眼检查一下抽取质量。预处理阶段有个容易被忽略的点时间信息的处理。对话里经常出现“昨天”“上周”“下个月”这种相对时间如果不转成绝对时间图里的时间关系就没法做推理。cognee内置了时间归一化的逻辑但覆盖不全。我的做法是在灌入前先用正则把相对时间替换成绝对时间再交给cognee。4.3 检索调优与上下文组装检索调优是个反复迭代的过程。我的方法是准备一组测试问题每个问题都有预期答案然后跑检索看召回结果对不对。如果召回不准先查向量库的embedding质量再查图扩展的跳数设置。上下文组装这块cognee默认会把检索结果按相关性排序后拼接。但模型对上下文的顺序敏感重要的信息放前面效果更好。我一般会手动重排一下把图检索的结构化结果放最前面向量召回的文本片段放后面。另外如果检索结果里有冲突信息比如两个节点说的时间不一致要在上下文里标注出来让模型自己判断。async def build_context(query): results await cognee.search(query_textquery, hops2) # 结构化结果优先 structured [r for r in results if r[type] graph] unstructured [r for r in results if r[type] vector] context \n.join([r[text] for r in structured unstructured]) return context4.4 代理集成与调用闭环最后一步是把记忆引擎接到代理里。代理的流程通常是接收用户输入先查记忆把记忆和输入一起给模型模型生成回答再把这轮对话写回记忆。这个闭环里写回的记忆要包含用户的原始输入和代理的回答这样下次才能检索到。集成的代码不复杂关键是要处理好异步。cognee的写入是异步的如果代理要求低延迟可以先把回答返回给用户写入操作放后台队列慢慢跑。但这样有个风险如果写入失败记忆就丢了。我的做法是加一个重试队列写入失败的任务进队列定时重试。调用频率上也要注意。不是每轮对话都需要查记忆简单的事实问答可以直接走模型。我的策略是涉及用户偏好、历史状态、跨会话信息的问题才查记忆其他走普通流程。这样能省不少检索开销。5. 常见问题与排查技巧实录5.1 抽取结果不稳定怎么办这是被问得最多的问题。同一段文本跑两次抽取结果不一样。原因通常是LLM的温度参数没固定或者prompt里的示例不够明确。解决办法是把温度锁死在0.1然后在prompt里加三到五个few-shot示例覆盖你关心的实体类型。如果还是不稳定可以考虑换抽取模型。有些小模型在特定领域的抽取上反而比大模型稳因为大模型容易“过度理解”把没明说的关系也抽出来。我试过用专门做信息抽取的模型准确率比通用模型高不少。5.2 检索召回率低怎么调召回率低一般有三个原因embedding质量差、分块策略不合理、图扩展跳数不够。排查顺序是先看embedding用几个已知相似的句子测一下余弦相似度如果相似句的分数低于0.7说明embedding模型不行得换。分块策略的问题更隐蔽。如果块切得太碎一个完整的意思被切成两半检索时两边都召不回。我的经验是对话数据按轮次切文档数据按段落切别用固定长度硬切。cognee支持自定义分块函数可以按你的数据特点来。图扩展跳数不够的情况表现为“明明图里有关系但检索没带出来”。这时候把hops从1调到2试试。如果调到2还是不行检查一下图里的边是不是方向反了或者关系类型没匹配上。5.3 数据更新后记忆不同步这个问题在频繁更新的场景里很常见。用户改了偏好但图里还是旧的关系。cognee的更新是追加式的不会自动删除旧节点。所以你需要自己维护一个更新逻辑新数据进来时先查图里有没有冲突的旧关系有的话标记为失效或直接删除。我的做法是给每个关系加一个时间戳检索时只取最新时间戳的关系。这样不用删数据也能保证记忆是最新的。cognee的图存储支持自定义属性加时间戳不难。5.4 性能瓶颈排查速查表现象可能原因排查方法解决方向写入慢抽取模型响应慢看抽取任务的耗时日志换小模型或加缓存检索慢图扩展跳数过大打印每跳的节点数降低hops或加过滤条件内存高向量库全量加载看内存占用曲线换持久化向量库结果不准实体消解没做好检查图里的重复节点加同义合并规则上下文超长检索结果太多统计拼接后的token数调低top_k或加截断这张表是我踩坑之后整理的基本覆盖了八成以上的常见问题。遇到新问题先往这几个方向靠能省不少排查时间。5.5 几个容易被忽略的细节第一个是冷启动问题。记忆引擎刚上线时图里是空的检索效果很差。这时候可以先用一批种子数据灌进去比如常见的用户偏好模板让图先有个基础结构。第二个是多用户隔离。如果代理服务多个用户记忆必须按用户隔离否则A的偏好会污染B的推荐。cognee的dataset机制可以做隔离但要在检索时严格带上用户标识别漏了。第三个是记忆的过期策略。不是所有记忆都值得永久保留。临时性的信息比如“用户今天心情不好”过几天就没用了。我通常会设一个TTL超过时间的记忆自动降权或删除。cognee本身没有TTL机制得自己在应用层做。6. 记忆引擎的扩展方向与个人体会这套方案跑通之后能扩展的方向不少。往深了做可以加记忆的重要性打分让代理优先记住关键信息。往宽了做可以接多模态数据把图片和音频也纳入记忆。cognee的架构是支持扩展的核心的抽取和检索接口都可以替换成自定义实现。我自己在实际项目里最大的体会是记忆引擎的价值不在于技术多复杂而在于它让代理的行为变得可预期。没有记忆的代理每次对话都像第一次见面用户得反复交代背景。有了记忆之后代理能记住上下文交互体验的提升是立竿见影的。但记忆也不是越多越好噪音记忆反而会干扰判断。所以接入数据时要克制宁缺毋滥。最后分享一个小技巧调试记忆引擎时把图结构可视化出来看比看日志直观得多。cognee支持导出图数据用常见的图可视化工具打开一眼就能看出实体抽取和关系连接的问题。这个习惯帮我省了很多排查时间。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
