用 Docker 快速上手 Cognee单文件体验、API 服务与全栈 Compose 部署指南【免费下载链接】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本篇技术指南以 Cognee 仓库内的cognee-docker技能文档为主线系统讲解如何用 Docker 运行这个开源 AI 记忆平台从「预构建镜像 单个docker-compose.yml」的零克隆快速体验到仓库内完整 Compose 文件的按需 profile 全栈部署API、前端、MCP、Postgres、Neo4j并深入拆解remember/recall记忆 API 的调用语义、search_type自动路由行为与关键环境变量。读完你不仅能在一分钟内起一个可用的记忆服务还能理解数据持久化、认证开关、数据库选型等生产落地要点。一、概述Cognee 的三种 Docker 使用方式Cognee 是面向 Agent 的开源 AI 记忆平台通过自托管的知识图谱引擎为 Agent 提供跨会话的长期记忆项目定位见仓库 README.md。围绕 Dockercognee-docker技能文档位于 .claude/skills/cognee-docker/SKILL.md定义了三种典型场景预构建镜像快速试用不克隆、不构建用cognee/cognee:main镜像加一个文件跑起 API 服务容器内启动 API 服务直接调用/api/v1/remember、/api/v1/recall等记忆 API 完成「写入记忆 → 查询记忆」闭环仓库全栈 Compose 部署从源码构建通过--profile按需叠加前端 UI、MCP 服务器、Postgres 与 Neo4j 数据库。下文按「由浅入深」的顺序依次展开。文档详细配套说明见 docs/minimal-docker-compose.md。二、最快路径预构建镜像 单文件 Compose2.1 前置条件Docker 且带 Compose 插件Docker Desktop、Colima 或任何 OCI 兼容运行时macOS 上的 Colima 配置见 docs/docker-colima-setup.md一个 OpenAI API Key镜像默认的 LLM 与 embedding 提供方均为 OpenAI。2.2 一个可复制的docker-compose.yml在空目录中保存以下文件services: cognee: image: cognee/cognee:main ports: - 8000:8000 environment: LLM_API_KEY: ${LLM_API_KEY:?set LLM_API_KEY to your OpenAI API key} # Single-user try-out: no auth, shared local databases. # Remove this line (or set it to true) for multi-tenant mode, # which requires authentication on every API call. ENABLE_BACKEND_ACCESS_CONTROL: false三个关键点的含义image: cognee/cognee:main直接使用官方预构建镜像无需build。镜像基于python:3.12-slim-bookworm以非 root 用户uid/gid 1000运行并将/cognee-storage/system与/cognee-storage/data作为默认存储目录烘焙进镜像见 DockerfileLLM_API_KEY: ${LLM_API_KEY:?set LLM_API_KEY to your OpenAI API key}${VAR:?msg}是 Compose 的必填校验语法未设置该变量时docker compose up会直接报错提示避免启动后才发现缺 KeyENABLE_BACKEND_ACCESS_CONTROL: false关闭后端访问控制进入单用户免认证模式。该变量默认值为true见 .env.template多租户模式下每次 API 调用都要求认证单用户试用必须显式关闭。2.3 启动与健康检查export LLM_API_KEYsk-... # OpenAI key (default LLM embedding provider) docker compose up服务启动后先验证健康状态curl http://localhost:8000/health返回正常后即可打开交互式 API 文档http://localhost:8000/docs。镜像在构建时已内置 HEALTHCHECKcurl -f http://localhost:8000/health见 Dockerfiledocker compose ps也可以观察容器健康状态。2.4 第一次记忆写入与查询echo Cognee turns documents into AI memory. note.txt # remember ingest build the graph in one call (multipart form) curl -X POST http://localhost:8000/api/v1/remember -F datanote.txt -F datasetNamemain_dataset # recall query it (JSON) curl -X POST http://localhost:8000/api/v1/recall -H Content-Type: application/json \ -d {query: What does Cognee do?, datasets: [main_dataset]}/api/v1/remember使用multipart/form-datadata字段传文件或文本datasetName指定数据落到的数据集名称一步完成「摄取ingest 构建知识图谱cognify」/api/v1/recall使用 JSONquery为自然语言问题datasets限定检索范围。若该数据集尚未经过任何 pipeline 处理recall 的图检索通道会返回memory_warming_up标记条目而非报错对应 recall.py 中的 warm-up 短路逻辑。2.5 remember/recall 与底层端点legacy APIremember与recall并不是独立实现而是对更细粒度端点的封装传统三段式/api/v1/add摄取、/api/v1/cognify构建图、/api/v1/search检索仍然存在remember/recall底层正是调用它们只有当你需要单独执行某一阶段时才直接使用 legacy 端点。例如 docs/minimal-docker-compose.md 中展示了分步调用add→cognify→search的完整流程/api/v1/improve基于反馈改进记忆与/api/v1/forget删除记忆补齐了记忆 API 的完整生命周期。2.6 请求字段的命名兼容snake_case 与 camelCase 通用所有请求/响应 DTO 同时接受snake_case与camelCase两种字段命名。其机制在 cognee/api/DTO.pyOutDTO与InDTO的model_config中同时配置了alias_generatorto_camel与populate_by_nameTrue。前者让 Pydantic 自动为每个字段生成驼峰别名后者允许按字段本名snake_case填充。因此下面的写法完全等价{search_type: GRAPH_COMPLETION, query: What does Cognee do?, datasets: [main_dataset]} {searchType: GRAPH_COMPLETION, query: What does Cognee do?, datasets: [main_dataset]}三、深入理解 recall 的 search_typeGRAPH_COMPLETION 与自动路由这是使用记忆 API 时最容易困惑的一点值得单独展开。3.1 端点的默认行为向后兼容/api/v1/recall以query接收问题出于向后兼容其search_type默认值为GRAPH_COMPLETION。也就是说不传search_type时问题会走固定策略GRAPH_COMPLETION。3.2 传search_type: null启用自动路由显式传入search_type: null可以退出固定策略、启用自动路由auto-routing这也是 Python SDK 中cognee.recall()的默认行为。两者的差异是真实可感的{query: Why does X?}使用GRAPH_COMPLETION作答同样的查询把search_type置为null则会路由到GRAPH_COMPLETION_COTChain-of-Thought 变体。在源码层面自动路由由 query_router.py 实现它以一组(pattern, search_type, weight)规则对问题文本打分why/how类因果问题会匹配到GRAPH_COMPLETION_COTrecall.py 中的auto_route参数默认True控制 SDK 侧是否启用该分类器——query_type未指定且auto_routeFalse时则退化为HYBRID_COMPLETION。注意 API 端点与 SDK 的默认值不同这是刻意的设计端点保持向后兼容SDK 面向新用法默认自动路由。提示当前 get_recall_router.py 的注释显示端点search_type字段的默认值为HYBRID_COMPLETION与技能文档描述的GRAPH_COMPLETION存在版本演进差异。实际行为以你所部署镜像/分支版本为准但「传null即启用自动路由」这一约定在两端是一致的。四、数据持久化把记忆存到容器之外默认情况下所有数据关系数据库、向量库、图数据库文件都存放在容器内部删除容器即删除数据。要跨重启保留记忆需要同时做两件事通过环境变量把 Cognee 的数据目录指到挂载点用命名卷named volume持久化。services: cognee: image: cognee/cognee:main ports: - 8000:8000 environment: LLM_API_KEY: ${LLM_API_KEY:?set LLM_API_KEY to your OpenAI API key} ENABLE_BACKEND_ACCESS_CONTROL: false DATA_ROOT_DIRECTORY: /cognee-data/data SYSTEM_ROOT_DIRECTORY: /cognee-data/system volumes: - cognee_data:/cognee-data volumes: cognee_data:DATA_ROOT_DIRECTORY数据文件根目录向量库、文件索引等SYSTEM_ROOT_DIRECTORY系统文件根目录图数据库、迁移文件等两个目录均指向挂载在/cognee-data的命名卷cognee_data之下。镜像默认使用基于文件的本地数据库SQLite 关系库 LanceDB 向量库 Ladybug 图库因此无需额外启动任何数据库服务即可运行这也是单文件方案能成立的原因。更完整的变量说明见 .env.template。五、全栈部署从仓库源码构建 Compose Profiles当需要前端、MCP 服务器或专业数据库时使用仓库根目录的 docker-compose.yml该文件从源码构建镜像而不是拉取预构建镜像。5.1 准备与基础启动在仓库根目录执行需要.env文件至少包含LLM_API_KEY可复制.env.template后填写docker compose up # API server only, port 8000 docker compose --profile ui up # frontend on port 3000 docker compose --profile mcp up # MCP server on port 8001 docker compose --profile postgres --profile neo4j up # databases主服务cognee的关键配置见 docker-compose.yml项值/说明端口8000:8000API5678:5678debugpy 调试端口DEBUGtrue时生效存储命名卷cognee_system:/cognee-storage/system、cognee_data:/cognee-storage/data环境变量DEBUGfalse、ENVlocal、LOG_LEVELINFODB_PROVIDER默认sqliteDB_HOST默认host.docker.internalCORSCORS_ALLOWED_ORIGINS默认*生产环境务必覆盖为具体域名.env.template健康检查curl -f http://localhost:8000/health间隔 30s启动宽限 40s资源上限CPU 4 核、内存 8GBdeploy.resources.limits网络共享cognee-networkextra_hosts将host.docker.internal解析到宿主机主服务还以只读方式挂载了源码目录./cognee:/app/cognee与.env.env:/app/.env:ro前者服务于开发热重载生产部署可移除如需从宿主机摄取本地文件可取消# - /path/to/your/data:/data的注释。5.2 各 profile 服务明细前端 UI--profile ui构建cognee-frontend目录映射3000:3000通过NEXT_PUBLIC_BACKEND_API_URL默认http://localhost:8000指向 API。注意 compose 文件中的注释提示前端仍在完善中若需要 UI 环境也可以把 Cognee MCP Server 接入 Cursor / Claude Desktop / VS Code经 Cline/Roo。MCP 服务器--profile mcp构建 cognee-mcp 目录宿主机端口8001:8000容器内仍监听 8000以--no-migration启动TRANSPORT_MODEsse。它与主服务共享同一对存储卷这正是「API 与 MCP 共享记忆」的关键——两者都以 uid 1000 运行避免卷权限冲突见 Dockerfile 中的非 root 用户设计。Postgres--profile postgrespgvector/pgvector:pg17镜像用户/密码/库名均为cognee/cognee/cognee_db端口5432数据持久化在postgres_data命名卷compose e2e 测试依赖该卷保证重建容器后数据不丢。启用该 profile 后主服务需设置DB_PROVIDERpostgres与DB_HOSTpostgrescompose 内服务名。Neo4j--profile neo4jneo4j:5.26镜像固定 5.x兼容 neo4j Python driver 5.28,6认证neo4j/pleaseletmein端口7474HTTP与7687Bolt并预装apoc与graph-data-science插件。启用后需设置GRAPH_DATABASE_PROVIDERneo4j等变量见 .env.template。此外仓库还提供了Redis--profile redisredis:7-alpine6379appendonly 开启与RedisInsight5540profile用于会话缓存的 Redis 后端场景对应.env.template中CACHE_BACKENDredis配置。5.3 容器与宿主机数据库的网络互通当 Cognee 运行在容器内、而数据库跑在宿主机上时使用DB_HOSThost.docker.internal。compose 文件通过extra_hosts: host.docker.internal:host-gateway让容器能够访问宿主机docker-compose.yml.env.template与 docker-compose.yml 中DB_HOST的默认值也正是host.docker.internal。六、镜像的构建与运行细节源码视角仓库根目录 Dockerfile 采用多阶段构建依赖阶段基于ghcr.io/astral-sh/uv:python3.12-bookworm-slim用uv sync按锁文件uv.lock安装依赖UV_COMPILE_BYTECODE1启用字节码编译以显著缩短冷启动时间COGNEE_EXTRAS构建参数可追加可选依赖组运行阶段python:3.12-slim-bookworm创建非 root 用户cogneeuid/gid 1000预建并授权/cognee-storage/{system,data}目录——这两个目录就是镜像默认的SYSTEM_ROOT_DIRECTORY与DATA_ROOT_DIRECTORY也是 compose 命名卷的挂载目标入口ENTRYPOINT [/app/entrypoint.sh]容器启动时执行迁移等初始化逻辑。七、环境变量与配置要点对接.env.template仓库根目录的 .env.template 是官方配置清单按 Tier 分层组织。与 Docker 部署最相关的几组1. LLM 与 EmbeddingTier 1/2LLM_API_KEY是唯一必填项其余均有可用默认值镜像对 LLM 和 embedding 都默认 OpenAI。只配置其一、另一个保持默认时未配置的那个仍然走 OpenAI——所以要么保留有效的 OpenAI Key要么把两个 provider 都显式配置如切到 Anthropic/Gemini/Ollama 时需同时设置LLM_PROVIDER、LLM_MODEL、LLM_ENDPOINT与对应的EMBEDDING_*变量本地模型示例Ollama见 .env.template。2. 认证与多租户Tier 3 SecurityENABLE_BACKEND_ACCESS_CONTROL总开关。true默认 多租户模式按用户/数据集隔离数据库且 API 需认证false 单用户共享数据库且关闭认证REQUIRE_AUTHENTICATION仅对认证要求的显式覆盖。false在ENABLE_BACKEND_ACCESS_CONTROLtrue时被忽略多租户强制认证启动时记录警告启动日志会输出auth posture: ...行方便确认实际生效的认证姿态生产多租户部署还应修改FASTAPI_USERS_JWT_SECRET默认不安全的super_secret。3. 数据库Tier 2/3DB_PROVIDER默认sqlite、DB_HOST、DB_PORT、DB_NAME、DB_USERNAME、DB_PASSWORD关系库连接GRAPH_DATABASE_PROVIDER默认kuzu可选neo4j等与VECTOR_DB_PROVIDER默认lancedb可选pgvector等图库与向量库独立选型。4. 其他与容器相关的变量HTTP_PORT/BIND_ADDRESS容器内 API 绑定地址与端口entrypoint 默认值CORS_ALLOWED_ORIGINS生产环境务必从*收紧为具体域名LOG_LEVEL、COGNEE_LOGS_DIR等日志控制项。八、常见坑Gotchas认证默认开启ENABLE_BACKEND_ACCESS_CONTROL未设置时默认为true每个 API 调用都需要认证——单用户试用方案将其显式置为false正是为了绕过这一点OpenAI 双默认镜像默认 LLM 与 embedding 都用 OpenAI。只配一个 provider 时另一个仍是 OpenAI务必保留有效 OpenAI Key 或同时配置两者数据在容器内不加DATA_ROOT_DIRECTORY/SYSTEM_ROOT_DIRECTORY与命名卷时删除容器即删除全部记忆数据容器 ↔ 宿主数据库Cognee 在容器内、数据库在宿主机时DB_HOST要用host.docker.internalcompose 已通过extra_hosts提供解析存储卷权限主服务与 MCP 服务共享存储卷两者都以 uid 1000 运行若用docker run手动指定用户或改用其他镜像需保证卷目录可写。九、进阶方向切换其他 LLM 提供方Anthropic、Gemini、Ollama、Azure OpenAI 等按 .env.template 的 Tier 4 示例设置LLM_PROVIDER/LLM_MODEL/LLM_ENDPOINT等变量生产多租户ENABLE_BACKEND_ACCESS_CONTROLtrue默认要求认证并按用户/数据集隔离数据对外暴露 API 前请先审阅 .env.template 中的安全变量JWT 密钥、API Key 哈希、CORS完整 Compose 方案仓库 docker-compose.yml 中的 profile 组合ui、mcp、postgres、neo4j、redis可自由叠加按需构建最小可用栈其他部署形态参考 deployment/Helm Chart与 distributed/deployModal、Fly、Railway、Render 等平台部署模板。通过本文的方案你可以从「一个文件跑通记忆 API」起步逐步演进到「API 前端 MCP 图数据库」的完整自托管记忆栈为 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/cognee创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 用 Docker 快速上手 Cognee：单文件体验、API 服务与全栈 Compose 部署指南
用 Docker 快速上手 Cognee单文件体验、API 服务与全栈 Compose 部署指南【免费下载链接】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本篇技术指南以 Cognee 仓库内的cognee-docker技能文档为主线系统讲解如何用 Docker 运行这个开源 AI 记忆平台从「预构建镜像 单个docker-compose.yml」的零克隆快速体验到仓库内完整 Compose 文件的按需 profile 全栈部署API、前端、MCP、Postgres、Neo4j并深入拆解remember/recall记忆 API 的调用语义、search_type自动路由行为与关键环境变量。读完你不仅能在一分钟内起一个可用的记忆服务还能理解数据持久化、认证开关、数据库选型等生产落地要点。一、概述Cognee 的三种 Docker 使用方式Cognee 是面向 Agent 的开源 AI 记忆平台通过自托管的知识图谱引擎为 Agent 提供跨会话的长期记忆项目定位见仓库 README.md。围绕 Dockercognee-docker技能文档位于 .claude/skills/cognee-docker/SKILL.md定义了三种典型场景预构建镜像快速试用不克隆、不构建用cognee/cognee:main镜像加一个文件跑起 API 服务容器内启动 API 服务直接调用/api/v1/remember、/api/v1/recall等记忆 API 完成「写入记忆 → 查询记忆」闭环仓库全栈 Compose 部署从源码构建通过--profile按需叠加前端 UI、MCP 服务器、Postgres 与 Neo4j 数据库。下文按「由浅入深」的顺序依次展开。文档详细配套说明见 docs/minimal-docker-compose.md。二、最快路径预构建镜像 单文件 Compose2.1 前置条件Docker 且带 Compose 插件Docker Desktop、Colima 或任何 OCI 兼容运行时macOS 上的 Colima 配置见 docs/docker-colima-setup.md一个 OpenAI API Key镜像默认的 LLM 与 embedding 提供方均为 OpenAI。2.2 一个可复制的docker-compose.yml在空目录中保存以下文件services: cognee: image: cognee/cognee:main ports: - 8000:8000 environment: LLM_API_KEY: ${LLM_API_KEY:?set LLM_API_KEY to your OpenAI API key} # Single-user try-out: no auth, shared local databases. # Remove this line (or set it to true) for multi-tenant mode, # which requires authentication on every API call. ENABLE_BACKEND_ACCESS_CONTROL: false三个关键点的含义image: cognee/cognee:main直接使用官方预构建镜像无需build。镜像基于python:3.12-slim-bookworm以非 root 用户uid/gid 1000运行并将/cognee-storage/system与/cognee-storage/data作为默认存储目录烘焙进镜像见 DockerfileLLM_API_KEY: ${LLM_API_KEY:?set LLM_API_KEY to your OpenAI API key}${VAR:?msg}是 Compose 的必填校验语法未设置该变量时docker compose up会直接报错提示避免启动后才发现缺 KeyENABLE_BACKEND_ACCESS_CONTROL: false关闭后端访问控制进入单用户免认证模式。该变量默认值为true见 .env.template多租户模式下每次 API 调用都要求认证单用户试用必须显式关闭。2.3 启动与健康检查export LLM_API_KEYsk-... # OpenAI key (default LLM embedding provider) docker compose up服务启动后先验证健康状态curl http://localhost:8000/health返回正常后即可打开交互式 API 文档http://localhost:8000/docs。镜像在构建时已内置 HEALTHCHECKcurl -f http://localhost:8000/health见 Dockerfiledocker compose ps也可以观察容器健康状态。2.4 第一次记忆写入与查询echo Cognee turns documents into AI memory. note.txt # remember ingest build the graph in one call (multipart form) curl -X POST http://localhost:8000/api/v1/remember -F datanote.txt -F datasetNamemain_dataset # recall query it (JSON) curl -X POST http://localhost:8000/api/v1/recall -H Content-Type: application/json \ -d {query: What does Cognee do?, datasets: [main_dataset]}/api/v1/remember使用multipart/form-datadata字段传文件或文本datasetName指定数据落到的数据集名称一步完成「摄取ingest 构建知识图谱cognify」/api/v1/recall使用 JSONquery为自然语言问题datasets限定检索范围。若该数据集尚未经过任何 pipeline 处理recall 的图检索通道会返回memory_warming_up标记条目而非报错对应 recall.py 中的 warm-up 短路逻辑。2.5 remember/recall 与底层端点legacy APIremember与recall并不是独立实现而是对更细粒度端点的封装传统三段式/api/v1/add摄取、/api/v1/cognify构建图、/api/v1/search检索仍然存在remember/recall底层正是调用它们只有当你需要单独执行某一阶段时才直接使用 legacy 端点。例如 docs/minimal-docker-compose.md 中展示了分步调用add→cognify→search的完整流程/api/v1/improve基于反馈改进记忆与/api/v1/forget删除记忆补齐了记忆 API 的完整生命周期。2.6 请求字段的命名兼容snake_case 与 camelCase 通用所有请求/响应 DTO 同时接受snake_case与camelCase两种字段命名。其机制在 cognee/api/DTO.pyOutDTO与InDTO的model_config中同时配置了alias_generatorto_camel与populate_by_nameTrue。前者让 Pydantic 自动为每个字段生成驼峰别名后者允许按字段本名snake_case填充。因此下面的写法完全等价{search_type: GRAPH_COMPLETION, query: What does Cognee do?, datasets: [main_dataset]} {searchType: GRAPH_COMPLETION, query: What does Cognee do?, datasets: [main_dataset]}三、深入理解 recall 的 search_typeGRAPH_COMPLETION 与自动路由这是使用记忆 API 时最容易困惑的一点值得单独展开。3.1 端点的默认行为向后兼容/api/v1/recall以query接收问题出于向后兼容其search_type默认值为GRAPH_COMPLETION。也就是说不传search_type时问题会走固定策略GRAPH_COMPLETION。3.2 传search_type: null启用自动路由显式传入search_type: null可以退出固定策略、启用自动路由auto-routing这也是 Python SDK 中cognee.recall()的默认行为。两者的差异是真实可感的{query: Why does X?}使用GRAPH_COMPLETION作答同样的查询把search_type置为null则会路由到GRAPH_COMPLETION_COTChain-of-Thought 变体。在源码层面自动路由由 query_router.py 实现它以一组(pattern, search_type, weight)规则对问题文本打分why/how类因果问题会匹配到GRAPH_COMPLETION_COTrecall.py 中的auto_route参数默认True控制 SDK 侧是否启用该分类器——query_type未指定且auto_routeFalse时则退化为HYBRID_COMPLETION。注意 API 端点与 SDK 的默认值不同这是刻意的设计端点保持向后兼容SDK 面向新用法默认自动路由。提示当前 get_recall_router.py 的注释显示端点search_type字段的默认值为HYBRID_COMPLETION与技能文档描述的GRAPH_COMPLETION存在版本演进差异。实际行为以你所部署镜像/分支版本为准但「传null即启用自动路由」这一约定在两端是一致的。四、数据持久化把记忆存到容器之外默认情况下所有数据关系数据库、向量库、图数据库文件都存放在容器内部删除容器即删除数据。要跨重启保留记忆需要同时做两件事通过环境变量把 Cognee 的数据目录指到挂载点用命名卷named volume持久化。services: cognee: image: cognee/cognee:main ports: - 8000:8000 environment: LLM_API_KEY: ${LLM_API_KEY:?set LLM_API_KEY to your OpenAI API key} ENABLE_BACKEND_ACCESS_CONTROL: false DATA_ROOT_DIRECTORY: /cognee-data/data SYSTEM_ROOT_DIRECTORY: /cognee-data/system volumes: - cognee_data:/cognee-data volumes: cognee_data:DATA_ROOT_DIRECTORY数据文件根目录向量库、文件索引等SYSTEM_ROOT_DIRECTORY系统文件根目录图数据库、迁移文件等两个目录均指向挂载在/cognee-data的命名卷cognee_data之下。镜像默认使用基于文件的本地数据库SQLite 关系库 LanceDB 向量库 Ladybug 图库因此无需额外启动任何数据库服务即可运行这也是单文件方案能成立的原因。更完整的变量说明见 .env.template。五、全栈部署从仓库源码构建 Compose Profiles当需要前端、MCP 服务器或专业数据库时使用仓库根目录的 docker-compose.yml该文件从源码构建镜像而不是拉取预构建镜像。5.1 准备与基础启动在仓库根目录执行需要.env文件至少包含LLM_API_KEY可复制.env.template后填写docker compose up # API server only, port 8000 docker compose --profile ui up # frontend on port 3000 docker compose --profile mcp up # MCP server on port 8001 docker compose --profile postgres --profile neo4j up # databases主服务cognee的关键配置见 docker-compose.yml项值/说明端口8000:8000API5678:5678debugpy 调试端口DEBUGtrue时生效存储命名卷cognee_system:/cognee-storage/system、cognee_data:/cognee-storage/data环境变量DEBUGfalse、ENVlocal、LOG_LEVELINFODB_PROVIDER默认sqliteDB_HOST默认host.docker.internalCORSCORS_ALLOWED_ORIGINS默认*生产环境务必覆盖为具体域名.env.template健康检查curl -f http://localhost:8000/health间隔 30s启动宽限 40s资源上限CPU 4 核、内存 8GBdeploy.resources.limits网络共享cognee-networkextra_hosts将host.docker.internal解析到宿主机主服务还以只读方式挂载了源码目录./cognee:/app/cognee与.env.env:/app/.env:ro前者服务于开发热重载生产部署可移除如需从宿主机摄取本地文件可取消# - /path/to/your/data:/data的注释。5.2 各 profile 服务明细前端 UI--profile ui构建cognee-frontend目录映射3000:3000通过NEXT_PUBLIC_BACKEND_API_URL默认http://localhost:8000指向 API。注意 compose 文件中的注释提示前端仍在完善中若需要 UI 环境也可以把 Cognee MCP Server 接入 Cursor / Claude Desktop / VS Code经 Cline/Roo。MCP 服务器--profile mcp构建 cognee-mcp 目录宿主机端口8001:8000容器内仍监听 8000以--no-migration启动TRANSPORT_MODEsse。它与主服务共享同一对存储卷这正是「API 与 MCP 共享记忆」的关键——两者都以 uid 1000 运行避免卷权限冲突见 Dockerfile 中的非 root 用户设计。Postgres--profile postgrespgvector/pgvector:pg17镜像用户/密码/库名均为cognee/cognee/cognee_db端口5432数据持久化在postgres_data命名卷compose e2e 测试依赖该卷保证重建容器后数据不丢。启用该 profile 后主服务需设置DB_PROVIDERpostgres与DB_HOSTpostgrescompose 内服务名。Neo4j--profile neo4jneo4j:5.26镜像固定 5.x兼容 neo4j Python driver 5.28,6认证neo4j/pleaseletmein端口7474HTTP与7687Bolt并预装apoc与graph-data-science插件。启用后需设置GRAPH_DATABASE_PROVIDERneo4j等变量见 .env.template。此外仓库还提供了Redis--profile redisredis:7-alpine6379appendonly 开启与RedisInsight5540profile用于会话缓存的 Redis 后端场景对应.env.template中CACHE_BACKENDredis配置。5.3 容器与宿主机数据库的网络互通当 Cognee 运行在容器内、而数据库跑在宿主机上时使用DB_HOSThost.docker.internal。compose 文件通过extra_hosts: host.docker.internal:host-gateway让容器能够访问宿主机docker-compose.yml.env.template与 docker-compose.yml 中DB_HOST的默认值也正是host.docker.internal。六、镜像的构建与运行细节源码视角仓库根目录 Dockerfile 采用多阶段构建依赖阶段基于ghcr.io/astral-sh/uv:python3.12-bookworm-slim用uv sync按锁文件uv.lock安装依赖UV_COMPILE_BYTECODE1启用字节码编译以显著缩短冷启动时间COGNEE_EXTRAS构建参数可追加可选依赖组运行阶段python:3.12-slim-bookworm创建非 root 用户cogneeuid/gid 1000预建并授权/cognee-storage/{system,data}目录——这两个目录就是镜像默认的SYSTEM_ROOT_DIRECTORY与DATA_ROOT_DIRECTORY也是 compose 命名卷的挂载目标入口ENTRYPOINT [/app/entrypoint.sh]容器启动时执行迁移等初始化逻辑。七、环境变量与配置要点对接.env.template仓库根目录的 .env.template 是官方配置清单按 Tier 分层组织。与 Docker 部署最相关的几组1. LLM 与 EmbeddingTier 1/2LLM_API_KEY是唯一必填项其余均有可用默认值镜像对 LLM 和 embedding 都默认 OpenAI。只配置其一、另一个保持默认时未配置的那个仍然走 OpenAI——所以要么保留有效的 OpenAI Key要么把两个 provider 都显式配置如切到 Anthropic/Gemini/Ollama 时需同时设置LLM_PROVIDER、LLM_MODEL、LLM_ENDPOINT与对应的EMBEDDING_*变量本地模型示例Ollama见 .env.template。2. 认证与多租户Tier 3 SecurityENABLE_BACKEND_ACCESS_CONTROL总开关。true默认 多租户模式按用户/数据集隔离数据库且 API 需认证false 单用户共享数据库且关闭认证REQUIRE_AUTHENTICATION仅对认证要求的显式覆盖。false在ENABLE_BACKEND_ACCESS_CONTROLtrue时被忽略多租户强制认证启动时记录警告启动日志会输出auth posture: ...行方便确认实际生效的认证姿态生产多租户部署还应修改FASTAPI_USERS_JWT_SECRET默认不安全的super_secret。3. 数据库Tier 2/3DB_PROVIDER默认sqlite、DB_HOST、DB_PORT、DB_NAME、DB_USERNAME、DB_PASSWORD关系库连接GRAPH_DATABASE_PROVIDER默认kuzu可选neo4j等与VECTOR_DB_PROVIDER默认lancedb可选pgvector等图库与向量库独立选型。4. 其他与容器相关的变量HTTP_PORT/BIND_ADDRESS容器内 API 绑定地址与端口entrypoint 默认值CORS_ALLOWED_ORIGINS生产环境务必从*收紧为具体域名LOG_LEVEL、COGNEE_LOGS_DIR等日志控制项。八、常见坑Gotchas认证默认开启ENABLE_BACKEND_ACCESS_CONTROL未设置时默认为true每个 API 调用都需要认证——单用户试用方案将其显式置为false正是为了绕过这一点OpenAI 双默认镜像默认 LLM 与 embedding 都用 OpenAI。只配一个 provider 时另一个仍是 OpenAI务必保留有效 OpenAI Key 或同时配置两者数据在容器内不加DATA_ROOT_DIRECTORY/SYSTEM_ROOT_DIRECTORY与命名卷时删除容器即删除全部记忆数据容器 ↔ 宿主数据库Cognee 在容器内、数据库在宿主机时DB_HOST要用host.docker.internalcompose 已通过extra_hosts提供解析存储卷权限主服务与 MCP 服务共享存储卷两者都以 uid 1000 运行若用docker run手动指定用户或改用其他镜像需保证卷目录可写。九、进阶方向切换其他 LLM 提供方Anthropic、Gemini、Ollama、Azure OpenAI 等按 .env.template 的 Tier 4 示例设置LLM_PROVIDER/LLM_MODEL/LLM_ENDPOINT等变量生产多租户ENABLE_BACKEND_ACCESS_CONTROLtrue默认要求认证并按用户/数据集隔离数据对外暴露 API 前请先审阅 .env.template 中的安全变量JWT 密钥、API Key 哈希、CORS完整 Compose 方案仓库 docker-compose.yml 中的 profile 组合ui、mcp、postgres、neo4j、redis可自由叠加按需构建最小可用栈其他部署形态参考 deployment/Helm Chart与 distributed/deployModal、Fly、Railway、Render 等平台部署模板。通过本文的方案你可以从「一个文件跑通记忆 API」起步逐步演进到「API 前端 MCP 图数据库」的完整自托管记忆栈为 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/cognee创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考