Cognee 实战指南用自托管知识图谱为 AI Agent 构建持久长期记忆【免费下载链接】cogneeCognee is the open-source AI memory platform for agents. Give your AI agents persistent long-term memory across sessions with a self-hosted knowledge graph engine.项目地址: https://gitcode.com/GitHub_Trending/co/cogneeCognee 是当前仓库cognee所承载的开源 AI 记忆平台核心目标是为 AI Agent 提供跨会话的持久长期记忆以任意格式摄取数据构建可自托管的知识图谱让每个 Agent 都能在完整上下文中回忆、连接与行动。本文以仓库根目录 README.md 为骨架结合 cognee/init.py、cognee/api/v1/remember/remember.py、cognee/api/v1/recall/recall.py 等源码实现完整讲解安装、配置、remember/recall/forget/improve四类核心操作、性能调优、Docker 部署与多租户隔离读完后你可以独立把 Cognee 接入自己的 Agent 或应用。Cognee 将向量嵌入、图推理与基于认知科学的本体生成结合起来使文档既能按语义检索又能通过随知识演进而变化的关系相互连接。下面是官方 README 中展示的两条核心路径remember记忆写入与recall记忆召回。Cognee 是什么面向 AI Agent 的开源记忆平台按 README.md 的定义Cognee 是一个开源 AI 记忆平台摄取任意格式的数据Cognee 持续构建一个自托管知识图谱为 Agent 提供跨会话的持久长期记忆。它同时融合了三条技术主线向量嵌入让文档内容可按语义相似度检索图推理在实体与关系层面进行结构化推理与多跳连接认知科学导向的本体生成自动把非结构化文本组织成符合领域语义的概念结构。这意味着文档不仅可被搜索到而且彼此以关系相连并且这些关系会随着知识的持续注入而演化。从源码看整个 Python SDK 的公开入口统一收敛在 cognee/init.py它明确划分了两代 APIV1 API数据管道式add加入数据、cognify处理为知识表示、search按配置的搜索类型查询、delete、update、prune、validate等V2 记忆导向 APIMemory-orientedremember、recall、improve、forget、serve、push、export以及MemoryEntry / QAEntry / TraceEntry / FeedbackEntry等内存条目类型定义于 cognee/memory/entries.py。V2 是 README 快速上手的主线本文也以此为主展开V1 的add/cognify/search作为底层管道仍然开放供需要细粒度控制的场景使用。为什么使用 Cognee四大核心价值README 用四点概括了 Cognee 的定位轻松构建公司大脑Company Brain把来自多个来源的数据统一到一个地方将领域知识赋能给 Agent知识基础设施统一的摄取管道、图/向量混合检索、本地运行、本体锚定ontology grounding、多模态支持持久化且不断学习的 Agent从反馈中学习、上下文管理、跨 Agent 知识共享可靠可信的 AgentAgent 级用户/租户隔离、可追踪性traceability、OTEL 采集器、审计特性。其中从反馈中学习和跨会话持久化正是improve与remember(session_id...)的职责后面会结合源码详细展开。核心操作全景remember、recall、forget、improveCognee 的 API 对外提供四个核心操作README 中给出了完整的最小示例。先看底层语义来自 remember.py 的 docstring 与实现remember(data)写入永久记忆。不带session_id时等价于顺序执行add() cognify() improve()数据被真正落进知识图谱带session_id时则写入会话记忆快速缓存后台异步同步到图谱。recall(query)查询记忆。默认开启auto_route由一个轻量级规则分类器自动挑选最佳搜索策略若指定session_id则先查会话缓存命中则短路返回未命中再回落图谱。forget(dataset)删除记忆按数据集维度清理。improve(dataset)对已有知识图谱做富化——提取并索引三元组嵌入若传入session_ids还会把会话中的反馈权重与 QA 内容桥接进永久图谱。README 中的完整可运行示例可直接保存为 Python 脚本执行import cognee import asyncio async def main(): # Store permanently in the knowledge graph (runs add cognify improve) await cognee.remember(Cognee turns documents into AI memory.) # Store in session memory (fast cache, syncs to graph in background) await cognee.remember(User prefers detailed explanations., session_idchat_1) # Query with auto-routing (picks best search strategy automatically) results await cognee.recall(What does Cognee do?) for result in results: print(result) # Query session memory first, fall through to graph if needed results await cognee.recall(What does the user prefer?, session_idchat_1) for result in results: print(result) # Delete when done await cognee.forget(datasetmain_dataset) if __name__ __main__: asyncio.run(main())remember 的源码级拆解从 remember.py 可以看到remember()的实际分发逻辑远比一行代码复杂其输入类型为Union[BinaryIO, list[BinaryIO], str, list[str], DataItem, list[DataItem], MemoryEntry, MemorySource]并按类型走三条路径MemorySource迁移导入当数据来自 Mem0、Zep/Graphiti、Letta 或 COGX 归档等外部记忆系统时走import_memory_source把历史记忆流式导入永久图谱此时不允许session_id与dataset_id参数类型化记忆条目MEMORY_ENTRY_TYPESQAEntry带问题的问答条目、TraceEntryAgent 工具调用轨迹、FeedbackEntry对回答的反馈打分、SkillRunEntry技能运行评分会短路 addcognify 路径直接写入会话管理器或图谱常规 addcognify其余文本/文件/流走完整的摄取管道。remember()还支持几个实用参数run_in_backgroundTrue后台任务模式立即返回statusrunning的RememberResult之后可以await result阻塞等待完成dry_runTrue仅返回分阶段的 LLM token 用量与粗略成本估算不真正摄取数据、不调用 LLM只支持本地模式的常规输入content_typeskills或code分别按 SKILL.md 技能节点或代码仓库架构图管道处理self_improvementTrue默认cognify 之后自动调用improve()富化图谱三元组嵌入与索引。返回值RememberResult是类 Promise对象可直接print查看摘要如RememberResult(statuscompleted, datasetmain_dataset, elapsed4.2s)可通过.status、.dataset_name、.elapsed_seconds、.content_hash、.items等属性检查细节.raw_result保留cognify()的原始返回{dataset_id: PipelineRunInfo}。recall 的源码级拆解recall.py 展示了召回的多源路由机制recall()根据scope解析出具体数据源列表session、trace、session_context、graph、tools、code每个源由独立的 runner 执行最后合并结果会话记忆_search_session对会话缓存中的 QA 条目做关键词分词打分排序_tokenize取词重叠计数返回_sourcesession标记的结果图谱检索_run_graph调用authorized_search先经route_query规则分类器自动选择搜索类型默认auto_routeTrue置False则回落到HYBRID_COMPLETION再执行权限校验后的混合检索tools 源scope[tools]时执行 text-to-SQL把自然语言问题转成 SQL 查询已授权的外部数据库需TOOL_CALLS_ENABLEDtrue并注册连接code 源scope[code]时针对代码图谱做影响分析等结构化操作。关键参数包括top_k默认 15、datasets/dataset_ids限定搜索范围UUID 优先、system_prompt_path默认answer_simple_question.txt、node_name与node_name_filter_operator实体过滤、response_model结构化输出校验、include_references附带引用。当目标数据集从未跑过任何管道时RECALL_WARMUP_SHORTCIRCUIT会返回一个memory_warming_up标记条目而不是空跑搜索机制。快速开始几分钟跑通 Cognee前置条件Python 3.10 到 3.14README 明确声明的支持范围。第 1 步安装推荐使用uv也可以用pip、poetry或任意 Python 包管理器uv pip install cognee需要额外数据库后端时使用 extras例如全部内存层跑在 Postgres 上pip install cognee[postgres]Turso 则对应pip install cognee[turso]。第 2 步配置 LLMimport os os.environ[LLM_API_KEY] YOUR OPENAI_API_KEY或者创建.env文件仓库提供了完整模板 .env.template。这个模板按分层组织是理解全部配置的权威入口TIER 1 快速启动只设LLM_API_KEY即可其余均有可用默认值SQLite、LanceDB、KuzuDB 三个默认数据库均为文件型无需额外服务TIER 2 常用覆盖LLM 与嵌入模型、数据库提供商DB_PROVIDER、GRAPH_DATABASE_PROVIDER、VECTOR_DB_PROVIDERTIER 3 高级设置结构化输出框架STRUCTURED_OUTPUT_FRAMEWORK默认litellm_native可选instructor/baml、限流LLM_RATE_LIMIT_*、按阶段路由模型LLM_EXTRACTION_MODEL/LLM_SUMMARIZATION_MODEL/LLM_QUERY_MODEL、S3 存储、多租户开关ENABLE_BACKEND_ACCESS_CONTROL默认True等TIER 4 示例提供商覆盖Azure OpenAI含托管身份、本地 Ollama、OpenRouter、DeepInfra、MCP sampling 的完整配置范例。第 3 步运行管道即上一节的四操作示例。若用cognee.serve(url..., api_key...)连接远程 Cognee 实例SDK 调用会自动路由到云端见下文连接 Cognee Cloud。使用 Cognee CLI安装后自带命令行工具与 SDK 一一对应cognee-cli remember Cognee turns documents into AI memory. cognee-cli recall What does Cognee do? cognee-cli forget --all启动本地 UIcognee-cli -ui注意cognee-cli -ui启动的 MCP server 运行在 Docker 容器内需要 Docker Desktop、Colima 或任意兼容 OCI、带可用dockerCLI 的运行时。细节见 Docker Colima Setup。CLI 对应的实现分布在 cognee/cli/commands/如remember_command.py、recall_command.py、forget_command.py、serve_command.py等每个命令的入口解析与参数说明可在其中查看。性能调优三个关键开关README 明确指出Cognee 的默认值偏向记忆质量而非原始延迟有三个开关值得关注AUTO_FEEDBACKfalse移除每次回答后 Cognee 用于自我调优记忆的那一次 LLM 调用。读取会更快更便宜会话记忆本身不受影响当你想让记忆从对话信号中持续改进时再打开。CACHINGfalse完全禁用会话记忆——remember(session_id...)会失效recall()会丢失对话上下文。只有完全不使用会话记忆时才应设置。做基准测试时请保持开启——关掉它等于在剥离记忆层的状态下测试 Cognee。DATASET_QUEUE_ENABLEDfalse移除数据集上的进程内并发保护。能省一点点延迟但多个数据集并行运行时可能引发文件锁泄漏与资源耗尽风险——服务器场景建议保持开启。对应配置在 .env.template 中均有注释说明DATASET_QUEUE_MAX_CONCURRENT默认取DATABASE_MAX_LRU_CACHE_SIZE默认 6它同时限制 Kuzu/LanceDB 子进程工作者的最大存活数量SESSION_TTL_SECONDS默认 6048007 天控制会话缓存生命周期。用 Docker 运行Cognee 每次推送到main分支都会把预构建镜像发布到 Docker Hubcognee/cogneeAPI server与cognee/cognee-mcpMCP server。想快速试用直接使用 minimal docker-compose try-out——一个可直接复制的 compose 文件无需 clone 或构建。方案 ADocker Compose从源码构建cp .env.template .env # then edit .env and set LLM_API_KEY # Start the API server (http://localhost:8000) docker compose up # Optional profiles (combine as needed): docker compose --profile ui up # frontend on http://localhost:3000 docker compose --profile mcp up # MCP server on http://localhost:8001 docker compose --profile postgres up # Postgres/PGVector docker compose --profile neo4j up # Neo4jcognee与cognee-mcp两个服务发布的主机端口不同8000与8001可以同时运行。完整 compose 定义见仓库根目录 docker-compose.yml。方案 B拉取预构建镜像无需 clone# Create a minimal .env in the current directory echo LLM_API_KEYYOUR_OPENAI_API_KEY .env # API server docker run --env-file ./.env -p 8000:8000 --rm -it cognee/cognee:main # MCP server (HTTP transport) docker pull cognee/cognee-mcp:main docker run -e TRANSPORT_MODEhttp --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:mainMCP server 支持stdio、sse、http三种传输模式Docker 环境用TRANSPORT_MODE直接 CLI 则用--transport完整说明见 MCP server README。与 AI Agent 集成Claude Code 插件安装 Cognee memory 插件可以让 Claude Code 获得跨会话的持久记忆。插件会把提示词、工具调用轨迹和助手响应捕获进会话记忆在每个提示词注入相关上下文并在会话结束时将会话记忆同步到永久知识图谱。安装推荐在启动 Claude Code 之前从 shell 执行这样首次claude启动即是干净会话并自动引导记忆# Add the marketplace and install the plugin (one-time, user-scoped) claude plugin marketplace add topoteretes/cognee-integrations claude plugin install cognee-memorycognee # Set env vars for your mode (see below), then launch export LLM_API_KEYsk-... # local mode; or COGNEE_BASE_URL COGNEE_API_KEY for cloud claude本地模式默认插件在本机http://localhost:8011引导一个本地 Cognee API只要求LLM_API_KEYCognee API key 缺失时自动签发export LLM_API_KEYsk-...Cognee Cloud 或远程服务器同时设置COGNEE_BASE_URL与COGNEE_API_KEYexport COGNEE_BASE_URLhttps://your-instance.cognee.ai export COGNEE_API_KEYck_...启动时应当看到 Cognee Memory Connected 系统消息。插件钩入 Claude Code 生命周期SessionStart选择模式并建立身份、UserPromptSubmit注入数据集作用域的上下文、PostToolUse捕获工具轨迹、Stop写入助手回答、PreCompact在上下文重置时保留记忆、SessionEnd触发到永久图谱的最终同步。连接 Cognee Cloud把任意 Python Agent 指向托管 Cognee 实例所有 SDK 调用都会路由到云端import cognee await cognee.serve(urlhttps://your-instance.cognee.ai, api_keyck_...) await cognee.remember(important context) results await cognee.recall(what happened?) await cognee.disconnect()实战用例仓库 examples/ 目录下有更丰富的示例demo、指南、自定义管道、数据库配置。README 给出两个典型场景用例一客户支持 Agent目标基于客户的财务、支持与产品历史等个人数据解决客户问题。用户提问My invoice looks wrong and the issue is still not resolved.Cognee 追踪过去的交互、失败的动作、已解决的案例、产品历史。Agent 回复找到上月解决的 2 个相似账单案例指出是支付与账单系统之间的同步延迟导致并说明已在账户上应用修复。底层发生了什么统一各渠道数据源 → 重建交互时间线并追踪结果 → 检索相似已解决案例 → 映射到最佳解决策略 → 执行后更新记忆避免 Agent 重蹈覆辙。用例二专家知识蒸馏SQL Copilot目标帮助初级分析师通过复用专家级查询、模式与推理来完成任务。用户提问How do I calculate customer retention for this dataset?Cognee 追踪专家 SQL 查询、工作流模式、schema 结构、成功实现。Agent 回复说明资深分析师如何解决类似的留存查询Cognee 将当前 schema 匹配到已知结构并把专家逻辑适配到当前数据集。底层发生了什么从专家 SQL 与工作流中抽取并存储模式 → 将当前 schema 映射到历史结构 → 检索相似任务及其成功实现 → 把专家推理适配到当前上下文 → 用新成功模式更新记忆让初级分析师接近专家水平。把整个记忆层跑在单个 Postgres 上传统上图记忆意味着要运维一整套组件图数据库存关系、向量数据库存嵌入、Redis 存会话、关系型数据库存元数据——在 Agent 记住任何东西之前这些都要先部署、加固并付费。在 cognee 1.0 中可以在单个 Postgres 实例上运行整个记忆层记忆层传统技术栈cognee on Postgres关系Neo4j 或其它图数据库cognee 的 Postgres 图后端嵌入专用向量数据库pgvector会话RedisSQL 会话缓存后端元数据关系型数据库同一个 Postgres⚠️ 警告把 Postgres 用作图存储目前以demo 特性发布生产就绪版本以授权产品形式提供生产环境的图层面请坚持使用图原生后端。Postgres 图存储适合用于演示关系元数据、PGVector 与图状态共用一个 Postgres 服务。图依然存在只是与文本、元数据、嵌入一起存进同一个 Postgres 支撑的记忆层检索在相似性与结构之间切换时不再跨越服务边界。仓库 CI 基准显示 Postgres 检索比分离的图向量方案快约 10%。启用方式pip install cognee[postgres]DB_PROVIDERpostgres VECTOR_DB_PROVIDERpgvector GRAPH_DATABASE_PROVIDERpostgres_demo CACHE_BACKENDpostgres DB_HOSTlocalhost DB_PORT5432 DB_USERNAMEcognee DB_PASSWORDcognee DB_NAMEcognee_db从 .env.template 可以看到更细的选项GRAPH_DATASET_DATABASE_HANDLER支持postgres_graph每数据集一个 Postgres 数据库需 CREATE DATABASE与postgres_graph_shared共享库内每数据集一个 schema只需 CREATE SCHEMACACHE_BACKEND支持 sqlite/postgres/redis/fs/tapes并可显式指定CACHE_DB_URL。关系层、向量层与会话层均可用 Postgres 作为稳妥默认按需随时替换为专用后端图用 Neo4j/Neptune会话用 Redis向量用 pgvector/LanceDB以及社区适配器接入的 Qdrant、ChromaDB、Weaviate、Milvus。本地开发则完全内嵌SQLite、LanceDB、KuzuDB无需启动任何额外服务。部署与多租户隔离README 提供了一键部署矩阵详见 distributed/ 目录下的部署脚本与 worker 配置平台适用场景命令Cognee Cloud托管服务无需维护基础设施注册或await cognee.serve()ModalServerless、自动扩缩、GPU 负载bash distributed/deploy/modal-deploy.shRailway最简单的 PaaS原生 Postgresrailway init railway upFly.io边缘部署持久卷bash distributed/deploy/fly-deploy.shRender简单 PaaS托管 PostgresDeploy to Render 按钮Daytona云沙箱SDK 或 CLI见distributed/deploy/daytona_sandbox.pyIslo隔离云沙箱SDK见distributed/deploy/islo_sandbox.py多租户部署ENABLE_BACKEND_ACCESS_CONTROLtrue默认时每个 userdataset 组合都拥有自己隔离的图数据库与向量数据库。但并非所有后端都支持这种隔离层支持隔离不支持隔离图Ladybug/Kuzu默认、Neo4j*、Postgresdemo、TursoNeptune、远程 Ladybug向量LanceDB默认、PGVector、TursoNeptune Analytics、社区适配器关系—SQLite/Postgres 始终是共享数据库用户、权限、注册表* Neo4j 隔离会在你的 DBMS 内为每个数据集创建一个数据库因此需要支持多数据库的版本Enterprise 或 Aura。图和向量两个后端都必须支持隔离——只要有一个不支持cognee 就会抛出错误并指明不支持的 backend而不会静默回退到共享数据库。要运行不支持的后端请以单租户方式部署并设置ENABLE_BACKEND_ACCESS_CONTROLfalse。该开关的完整语义连同REQUIRE_AUTHENTICATION的覆盖逻辑在 .env.template 中有详细注释。其他语言客户端Rust 与 TypeScript除 Python 外Cognee 还提供官方客户端# Rust cargo add cognee # TypeScript (Node.js 或浏览器) npm install cognee/cognee-tsRust 客户端支持 add、cognify 与 searchTypeScript 客户端同样覆盖这些能力。基准测试BEAM 长上下文评测README 报告了针对 BEAM 长上下文基准的评测结果——该基准考察系统能否在对话持续变化的过程中跟踪长对话比典型的大海捞针式基准更能检验 Agent 记忆。评测仅使用 cognee 默认设置与标准开源功能无自定义模型、无 BEAM 专用管道基准设置cognee此前 SOTAObsidian / RAG 基线BEAM100K tokens0.79按问题路由时 0.80.735~0.33BEAM10M tokens0.670.641~0.33README 强调这些数字是方向性信号而非最终定论完整方法论、注意事项与结论解读见 BEAM preliminary report。进一步探索研究论文团队发表了关于优化知识图谱与 LLM 交互以支持复杂推理的论文Optimizing the Interface Between Knowledge Graphs and LLMs for Complex ReasoningMarkovic et al., 2025。源码入口公共 API 一览见 cognee/init.py四个核心操作的实现分别在 cognee/api/v1/remember/、cognee/api/v1/recall/、cognee/api/v1/improve/、cognee/api/v1/forget/。配置权威全部环境变量及取值范围、默认值、示例见 .env.template会话缓存与 Redis 切换、LLM 提供商接入等更细的说明可参考 docs/ 目录。社区贡献参与贡献的流程见 CONTRIBUTING.md。以上内容确保你从零到一理解并实际运行 Cognee 的完整记忆链路安装配置 → 写入永久/会话记忆 → 多源召回 → 反馈学习 → 调优与生产部署。【免费下载链接】cogneeCognee is the open-source AI memory platform for agents. Give your AI agents persistent long-term memory across sessions with a self-hosted knowledge graph engine.项目地址: https://gitcode.com/GitHub_Trending/co/cognee创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考