Cognee 保姆级部署教程：给 AI 智能体装一个本地长期记忆知识库

Cognee（仓库 topoteretes/cognee，最近提交 2026-10-29）是一个免费开源的 AI 记忆平台：把文档、代码、对话喂进去，它自动抽出实体与关系，建成一张可检索的知识图谱，再让你的 Agent 跨会话记住"上次聊过什么、做过什么决定"。官方最大卖点是——完全本地运行、不需要任何 LLM API Key，用 CPU 上的小模型就能跑。

本文严格对照官方 README 给出 pip、CLI、Docker 三种官方部署方式。

一、项目介绍与适用场景

Cognee 把"记忆"拆成四个动作：

• remember：把文本/代码/会话存进永久记忆；
• recall：从记忆里检索相关上下文；
• improve：用反馈和会话蒸馏把临时经验沉淀成永久知识；
• forget：删除某条记忆或某个数据集。

适用场景：

• 公司大脑：把文档、工单、代码、聊天记录统一进一个共享记忆，团队和 Agent 都能查；
• Agent 跨会话记忆：让你的聊天机器人 / 编程助手记得上次的上下文；
• 领域知识图谱：自定义 ontology，把业务实体和关系结构化。

二、核心功能逐条拆解

1. 无 LLM 本地模式：用 GLiNER 抽取 + 本地 embedding，CPU 就能跑，无需 API Key。
2. 知识图谱：文本自动变成实体、关系、可检索的 chunk。
3. CLI 工具：cognee-cli remember / recall / demo 一行命令操作记忆。
4. 本地 UI：cognee-cli -ui 起一个可视化界面（需 Node.js）。
5. MCP 服务：可作为 MCP server 给 Claude Desktop / Cursor / Cline 等客户端用。
6. 多后端：1.0 起整个记忆层可跑在单 Postgres 上（demo 特性）。
7. 插件生态：Claude Code / Codex 官方插件一键接入。
8. REST API：自带 HTTP 接口，方便其他语言调用。

三、全套官方链接

四、硬件与环境前置要求

官方 README 明确：Python 3.10–3.14。

其他：

• 内存：8 GB 起步（本地小模型吃内存）；
• 磁盘：5 GB（首次下载抽取/embedding 模型）；
• CPU：任意 x86_64；
• 网络：首次运行需下载模型；
• 可选：Docker（API 部署）、Node.js（本地 UI）。

五、多平台部署步骤

5.1 pip / uv 安装（官方 Quickstart）

官方 README 原文：

uv pip install "cognee[gliner]"

gliner extra 会带上无 LLM 模式用的本地抽取模型。普通 pip 用户：

pip install "cognee[gliner]"

5.2 无 LLM 跑通记忆（官方 quickstart.py）

官方 README 给出的完整脚本：

import asyncio

import cognee


async def main():
    # Extract a knowledge graph and embed the text with local models.
    await cognee.remember(
        "Marie Curie was born in Warsaw and worked at the University of Paris.",
        dataset_name="local_quickstart",
    )

    # Retrieve the matching source text; no LLM generates an answer.
    results = await cognee.recall(
        "Where was Marie Curie born?",
        datasets=["local_quickstart"],
    )
    for result in results:
        print(result)


if __name__ == "__main__":
    asyncio.run(main())

保存为 quickstart.py，运行：

python quickstart.py

预期：首次运行下载 GLiNER 与 embedding 模型，之后打印出包含"Warsaw"的检索结果。

官方也提供 CLI 等价命令：

cognee-cli remember "Marie Curie was born in Warsaw." -d local_quickstart
cognee-cli recall "Where was Marie Curie born?" -d local_quickstart

5.3 可选：配置 LLM

官方 README 原文：

import os
os.environ["LLM_API_KEY"] = "YOUR_OPENAI_API_KEY"

或者用仓库根目录的 .env.template 复制成 .env。配了 Key 之后 Cognee 会用 OpenAI 生成回答，没配时只做检索，不影响记忆写入。

5.4 内置 Demo（不下载模型）

官方 README：

cognee-cli demo

加载内置样例数据，跑关键词搜索，无需 API Key、无需下载模型。

5.5 本地 UI

官方 README：

cognee-cli -ui

官方说明：UI 启动器需要 Node.js/npm，其 MCP 服务需要 Docker。

5.6 Docker 部署 API（官方命令）

官方 README 原文：

docker run --rm -it -p 8000:8000 \
  -e LLM_API_KEY="sk-..." \
  -e ENABLE_BACKEND_ACCESS_CONTROL=false \
  -v cognee_storage:/cognee-storage \
  cognee/cognee:main

逐条解释：

• -p 8000:8000：把 API 端口映射到宿主机 8000；
• -e LLM_API_KEY="sk-..."：传 OpenAI Key（不需要生成回答时可省略）；
• -e ENABLE_BACKEND_ACCESS_CONTROL=false：单用户/本地模式，关掉多租户鉴权；
• -v cognee_storage:/cognee-storage：命名卷持久化记忆数据（不加 --rm 退出即丢）；
• cognee/cognee:main：官方镜像，自带 GLiNER 运行时。

预期：容器启动后访问 http://localhost:8000 即可调 REST API。

源码全栈启动（含 UI + MCP）：

git clone https://github.com/topoteretes/cognee.git
cd cognee
cp .env.template .env
docker compose --profile ui --profile mcp up

官方说明默认端口：API 8000、UI 3000、MCP 8001。

六、配置文件全部参数解释

七、启动、后台常驻与开机自启

7.1 前台启动

cognee-cli demo
# 或
python quickstart.py

7.2 Docker 后台常驻

docker run -d --name cognee -p 8000:8000 \
  -e ENABLE_BACKEND_ACCESS_CONTROL=false \
  -v cognee_storage:/cognee-storage \
  cognee/cognee:main

7.3 开机自启（systemd）

[Unit]
Description=Cognee API
After=network.target docker.service

[Service]
Type=simple
ExecStart=/usr/bin/docker start -a cognee
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload && sudo systemctl enable --now cognee

7.4 修改端口

把 -p 8000:8000 左侧改为 9000:8000，重启容器后访问 http://localhost:9000 验证。

八、功能实操教程

第 1 步：按 5.1 装好 cognee[gliner]。 第 2 步：写 quickstart.py 并运行，首次等待模型下载。 第 3 步：终端打印出含 Warsaw 的结果，说明记忆已建。 第 4 步：把 remember 的文本换成你自己的文档（粘贴一段长文本），再用 recall 提问。 第 5 步：运行 cognee-cli demo，观察内置样例。 第 6 步（可选）：按 5.6 起 Docker API，用 curl 调 /api/v1 接口写入和查询记忆。

九、全套报错故障排查

1. 报错：首次运行卡在下载模型。 原因：国内网络拉 HuggingFace 模型慢。 解决：设 HF_ENDPOINT=https://hf-mirror.com 后重试。

2. 报错：ModuleNotFoundError: No module named 'cognee'。 原因：没在虚拟环境里跑。 解决：uv pip install 与 python 用同一个环境。

3. 报错：Docker API 一直 401。 原因：没设 ENABLE_BACKEND_ACCESS_CONTROL=false，默认多租户模式。 解决：本地单机按 5.6 加该环境变量；或设 DEFAULT_USER_PASSWORD 后登录。

4. 报错：cognee-cli: command not found。 原因：pip bin 没进 PATH。 解决：重开终端；或 python -m cognee.cli ...。

5. 报错：Docker 加了 -v 但重启后记忆丢了。 原因：同时用了 --rm，容器一停就删。 解决：去掉 --rm，用 -d 后台跑。

十、升级、回滚与卸载

• 升级：pip install -U "cognee[gliner]"；Docker 用 docker pull cognee/cognee:main。
• 回滚：pip install cognee==<旧版本>。
• 卸载：pip uninstall cognee；删除 Docker 卷 docker volume rm cognee_storage；删除本地数据目录。

十二、进阶：从单文件到团队知识库、与其他记忆系统迁移

批量灌入文档：cognee.remember() 不只支持字符串，官方 API 支持传文件路径与目录。把团队 wiki 导出成 Markdown 目录后，写个循环 remember 进去，几十秒就能建成一张公司知识图谱。

与 Ollama 配合：官方文档有 local Ollama 指南（https://docs.cognee.ai/guides/local-ollama ），把 LLM_API_KEY 留空、改配 Ollama 地址，整个记忆层完全跑在本地，敏感文档不出内网。

从 Mem0 / Letta / Zep / Graphiti 迁移：官方 README 明确支持 COGX 交换格式，一键导入其他记忆系统的数据，迁移成本极低。

UI 可视化图谱：跑 cognee-cli -ui 起本地 UI（需 Node.js），可以在浏览器里直接看到实体之间的连线，方便你检查抽取得准不准。发现错误的关系可以用 cognee.forget() 删掉重建。

生产注意：官方警告 Postgres 单实例图存储是 demo 特性，真上生产要么用 Cognee Cloud 商业版，要么按分布式部署模板（distributed/deploy/README.md）搭多组件栈。

十一、商用许可与合规风险提示

Cognee 采用 Apache-2.0，商用友好。

注意：

1. Postgres 图存储是 demo 特性：官方警告生产级 Postgres 图存储是商业许可产品，不要在生产环境依赖 demo 模式。
2. GLiNER 是演示抽取器：官方明说内置 GLiNER 是 demo，高精度生产版本需联系官方。
3. Cognee Cloud 是托管服务：自托管 OSS 与 Cloud 功能边界以官网为准。

参考链接

• 官方 README：https://github.com/topoteretes/cognee
• 安装文档：https://docs.cognee.ai/getting-started/installation
• 最小 Docker Compose：https://github.com/topoteretes/cognee/blob/main/docs/minimal-docker-compose.md
• MCP 指南：https://docs.cognee.ai/cognee-mcp/mcp-overview