给 AI Agent 装记忆这件事,过去一个月我试过两条路:一条是上下文压缩,把记忆压进上下文窗口省 token;另一条是代码知识图谱,让 Agent 在图谱里找调用关系。但这两条路都有个共同短板——会话结束,记忆就散了。真正持久的「长期记忆」,要求把事实抽成结构存下来,下次开机直接问。
这正是 cognee 要解决的问题。这个项目 2023 年就存在,最近在 GitHub 周榜又涨了 5,500 多颗星,总数 33,394(GitHub API 2026-11-19 实查),Apache-2.0 协议,最新版 1.6.10。仓库在 GitHub,文档在 docs.cognee.ai,PyPI 上可以看全版本历史。它的卖点是「跑本地、不要 API key」:用本地小模型把文本抽成知识图谱加向量索引存盘,之后任何 Agent 都能来查。我这次在 M4 Mac 上把它从安装到问答完整跑了一遍,踩的坑比想象中多,但核心承诺是真的。
它的工作方式:remember、recall、forget、improve
cognee 1.6 把 API 收敛成四个动词:remember 存入并抽取,recall 检索回答,forget 删除,improve 把会话经验沉淀成永久记忆。底层三件套全是文件型数据库——SQLite 做关系存储、LanceDB 做向量、Ladybug 做图——不用装任何服务。没配 LLM key 时,它用本地 GLiNER 模型抽实体关系,用 fastembed 的 bge-small-en-v1.5 做嵌入;配了 key 才会走 LLM 抽取和生成答案。
听起来很省心,实际装起来第一坑就来了。
坑一:安装 32 分钟,还要先装 openssl
pip install cognee 在 M4 上花了我 32 分钟,重依赖(fastembed、lancedb、litellm 一大家子)加起来缓存冲到 2.1GB。装完第一次运行直接报错:Ladybug 图库的二进制依赖 Homebrew 的 OpenSSL 3,本机没有,迁移直接失败。好消息是报错信息写得非常清楚,连解决命令都给了:
brew install openssl@3第二个坑在模型下载。cognee 首次运行要从 HuggingFace 拉 GLiNER 抽取模型(约 800MB)和 bge-small 嵌入模型,我这边直连下载失败,报「Could not load model BAAI/bge-small-en-v1.5 from any source」。老办法解决,加镜像环境变量:
HF_ENDPOINT=https://hf-mirror.com python quickstart.py如果你本机 HuggingFace 直连正常,这步可以省。
无 LLM 模式:能建图谱,但 recall 给的是半成品
配好环境后我先用官方 quickstart 的单句测试跑全本地模式——不设任何 key:
import asyncio, time
import cognee
async def main():
t0 = time.time()
await cognee.remember(
"Marie Curie was born in Warsaw and worked at the University of Paris.",
dataset_name="local_quickstart",
)
print(f"remember took {time.time() - t0:.1f}s")
t1 = time.time()
results = await cognee.recall("Where was Marie Curie born?",
datasets=["local_quickstart"])
print(f"recall took {time.time() - t1:.1f}s")
for r in results:
print(r.text[:200])
asyncio.run(main())实测结果:remember 花了 289 秒——不过这含两个本地模型的首次下载,剔除下载后纯建图在一分钟内;recall 只花 0.1 秒,图谱检索是真快。
但这里有个官方文档没讲透的点:无 LLM 时 recall 返回的不是答案,是一段拼好上下文的提示词半成品。返回的 text 字段长这样:「The question is: Where was Marie Curie born? Answer using this sectioned context… ## Relevant passages…」——它把相关段落、实体、关系都拼好了,就差一个 LLM 来收尾。GLiNER 抽取质量也算合格:marie curie、university of paris、warsaw 三个实体都对,born_in、works_for 两条核心关系也抽出来了。
不过我盯着图谱关系逐条看,发现一条明显的错:「university of paris headquartered in warsaw」——巴黎大学总部在华沙?原文只说居里夫人出生于华沙、工作于巴黎大学,GLiNER 加关系启发式把「出生地」的地理标签错误传染给了另一个实体。所以小模型建图这个事,实体靠得住,关系要人审,直接拿去当事实源有风险。
接上免费模型:三句中文笔记,两个全对的答案
真正好用的形态是「本地嵌入 + 云端 LLM」。我没有 OpenAI key,用 openrouter 的免费模型接。cognee 底层是 litellm,openrouter 要走 custom provider:
export LLM_PROVIDER="custom"
export LLM_MODEL="openrouter/cohere/north-mini-code:free"
export LLM_ENDPOINT="https://openrouter.ai/api/v1"
export LLM_API_KEY="你的openrouter key"
export EMBEDDING_PROVIDER="fastembed"
export EMBEDDING_MODEL="BAAI/bge-small-en-v1.5"
export EMBEDDING_DIMENSIONS="384"这里必须夸一下 cognee 的预检逻辑:我一开始只设了 LLM 没设嵌入,它直接拒绝启动,报错明说「custom provider 下嵌入会静默回退到 OpenAI 默认端点,且不带 key,第一次写入就会在几分钟后报鉴权错」——把「静默失败」提前变成了「启动失败」,这个设计比大多数框架自觉。但它自己的坑也得说:EMBEDDING_PROVIDER=fastembed 之后还必须显式设 EMBEDDING_MODEL 和 EMBEDDING_DIMENSIONS,否则它会拿着默认的 openai/text-embedding-3-large 去 fastembed 里找,直接 ValueError,报错让人摸不着头脑。
配好后我喂了三句自己项目笔记当记忆库:
NOTES = [
"map-draw-vanilla 是 Minilee 用原生 JS 写的高德地图绘图应用,app.js 大约 6900 行,支持图片叠加层和多图层系统。",
"数独123 项目基于 Vite MPA 开发,dev 服务器跑在 5180 端口,最近在修 HMR WebSocket 连接失败的问题。",
"博客 apisitlee.com 的 WordPress 发布走 XML-RPC 端点,wp.newPost 不能传 terms,否则会触发全选 bug。",
]
for note in NOTES:
await cognee.remember(note, dataset_name="project_notes")实测数据:三条 remember 共 87.4 秒(约 29 秒一条,瓶颈在免费模型的抽取调用)。然后是问答环节,这一轮结果让我服气:
- 问「数独123 的 dev 端口是多少?」,3.8 秒返回,答案就一个词:5180;
- 问「博客发布时 wp.newPost 有什么注意事项?」,10.9 秒返回一段话:「不要在 wp.newPost 请求中传递 terms(分类/标签信息),否则会导致全选 bug」——这正是我自己写进发布流程笔记里的原话,检索和复述都准确。
我又加了两道压力题。第一道考语义改写:问「Vite 项目调试端口」——问题里压根没出现「数独123」四个字,它照样答出 5180,说明图谱加向量的混合检索不是摆设。第二道考防幻觉:问一个记忆库里完全没有的问题(我的手游项目目标用户),它老老实实回答「提供的信息中没有提及羊驼向前冲的目标用户」,没有瞎编。免费模型配知识图谱,这两个表现比我预期的都好。
坑二:记忆默认存进 site-packages,搬走只搬一半
这是我这次最想提醒的一个坑。不设任何配置时,cognee 的数据库默认路径长这样:
/private/tmp/cognee-lab/venv/lib/python3.13/site-packages/cognee/.cognee_system/databases对,你的全部记忆存在 Python 虚拟环境的包目录里。pip install 升级 cognee 或重建 venv,记忆可能就没了。解决方案是设 SYSTEM_ROOT_DIRECTORY 环境变量。但实测发现它只搬一半:设了这个变量后 databases 和 pipeline_run_locks 确实搬过去了,可删除数据集时日志里冒出来的清理路径还是 site-packages 下的 .data_storage——原文文本块依然留在包目录里。数据库和原文分开住,备份时容易漏掉一边。稳妥做法是两个位置都检查一遍,或者干脆等官方把路径统一。
坑三:API 命名不统一
小坑但真的会绊人:recall 删数据集用复数 datasets=["..."],forget 用单数 dataset="...",写错了 Python 直接甩 TypeError。另外我试了旧版教程里常见的 cognee.get_graph_data() 想看看图谱规模,1.6.10 里已经不存在了——新 API 收敛成 remember/recall/forget/improve 之后,很多旧教程的代码不能直接抄。
三个不建议使用的场景
实测下来,cognee 值得装,但有三类场景我劝你先想清楚:
- 不想维护本地状态的场景。记忆存在本机文件里,多设备同步、团队共享都得自己搭后端(官方有 Docker 和 Cognee Cloud 方案,我没实测,需人工确认)。
- 对关系准确性零容忍的场景。GLiNER 免费模式会产出「巴黎大学总部在华沙」这种假关系,LLM 抽取模式会好很多但依赖外部 API;医疗、法律这类错一条就出事的领域,必须加人工审核层。
- 追求秒级写入的场景。29 秒一条的写入速度对「读完一篇文档再记忆」没问题,对高频对话场景(每轮对话都要 remember)就太慢了,这种场景更适合先攒会话再批量沉淀——官方的
improve就是干这个的,但我这次没深入测,此部分未实测,需人工确认。
写在最后
一句话总结这次实测:cognee 的「全本地免费记忆」承诺成立,免费模型加本地嵌入的组合能把三句中文笔记变成一个能答题、能拒答、能语义检索的小记忆库;代价是安装链路坑多(openssl、HF 镜像、嵌入配置三件套)和一半的存储路径不一致。如果你的 Agent 正苦于「每次开机都失忆」,它值得花一小时装起来试试。装完记得第一件事:把 SYSTEM_ROOT_DIRECTORY 设到包目录外面。