cognee CLI 完全实战指南：用 cognee-cli 在终端驱动 AI 记忆全生命周期

导读

cognee 是面向 Agent 的开源 AI 记忆平台，其自带的命令行工具 cognee-cli 让你无需编写 Python 代码，即可在终端中完成"记忆写入（remember）→ 图谱查询（recall）→ 图谱增强（improve）→ 记忆清除（forget）"的完整闭环。本文以仓库内的官方 CLI 技能文档（.claude/skills/cognee-cli/SKILL.md）为骨架，结合命令实现源码，系统讲解每个子命令的用法、参数语义、底层调用链与常见陷阱，读完即可在真实环境中把 cognee 当作一台"可命令行的长期记忆服务器"来使用。

一、CLI 的定位与入口

cognee-cli 随 Python 包一起分发，程序入口在 cognee/cli/_cognee.py，每个子命令独立存放于 cognee/cli/commands/ 目录（remember_command.py、recall_command.py、forget_command.py、improve_command.py、config_command.py、datasets_command.py、sessions_command.py、migrate_command.py 等）。

从入口源码可以看到 CLI 的几个关键设计：

• 惰性初始化：_discover_commands() 动态导入命令类，避免在解析参数阶段就触发 cognee 的完整初始化，因此"第一次命令慢、后续命令快"是设计使然（见 cognee/cli/_cognee.py）。
• 统一的运行来源标记：main() 调用 set_operation_origin(ORIGIN_CLI)，让所有 CLI 发起的操作在 pipeline_runs 中记录 origin="cli"，便于与 SDK、API 调用的来源区分。
• 每个命令都有 --help 及示例：官方建议优先使用 --help 确认参数，而不是凭记忆猜测 flag 拼写。入口还集成了 rich_argparse（若已安装）提供带 Markdown 渲染的富文本帮助。
• 全局参数：除子命令外，入口还提供 --version、--debug（打印完整堆栈）、-ui（启动 Web UI）、--user-id（多 Agent 隔离，每个 ID 拥有独立的会话历史与权限）、--api-url / --api-key / --api-token（将命令委托给运行中的 Cognee API 服务器，这是文件型数据库下并发/多 Agent 场景的正确模式）。

运行任何命令前，需要与 SDK 一样配置 LLM_API_KEY（可通过 cognee-cli config set llm_api_key <key> 或环境变量设置）。

二、核心记忆流程：remember / recall / forget / improve

cognee 1.x 起，记忆类命令成为 CLI 的主战场。四个命令覆盖了记忆的"写入—查询—删除—增强"四个阶段：

cognee-cli remember "Your text here"         # 也接受文件路径 / URL
cognee-cli remember ./docs --dataset-name my_project
cognee-cli recall "Your question"            # 查询知识图谱
cognee-cli recall "keyword" --query-type CHUNKS
cognee-cli forget --all                      # 清空本地状态

2.1 remember：一步完成"摄取 + 建图"

remember 本质是 add（摄取）+ cognify（构建知识图谱）两步的合并。查看 remember_command.py 的实现可见其完整参数面：

参数	说明	默认值
data（位置参数）	文本内容、文件路径、文件 URL、S3 路径；传多个时以列表形式整体传入 cognee.remember()	必填
--sample-data	摄取随包捆绑的快速开始样例（cognee/cli/samples/quickstart.txt），适合首次冒烟测试，仍需要 LLM_API_KEY；不能与显式 data 参数混用	关闭
--dataset-name / -d	目标数据集名称	main_dataset
--chunk-size	每个 chunk 的最大 token 数，不指定则自动计算	自动
--chunker	文本分块策略，可选 TextChunker / LangchainChunker / CsvChunker（枚举定义见 config.py）	TextChunker
--chunks-per-batch	每个任务批次处理的 chunk 数量	自动
--background / -b	让 cognify 阶段在后台运行（add 始终先完成）	关闭
--dry-run	只估算 LLM token 用量与成本，不摄取数据、不发起 LLM 调用	关闭

实现细节：--chunker 的 LangchainChunker 与 CsvChunker 在导入失败时会回退到 TextChunker 并给出警告；--dry-run 时命令只打印估算结果而不写入；成功结束后会打印 Dataset ID、处理条目数、内容哈希与耗时，并提示下一步使用 recall/search 查询。

2.2 recall：查询知识图谱

recall 是面向记忆查询的入口，支持按数据集、Top-K、会话等维度检索。核心参数：

• --datasets / -d：限定数据集（可多个）；不指定则跨所有你有权访问的数据集检索。
• --top-k / -k：返回结果上限，默认 10。
• --session-id / -s：会话 ID。单独使用（不加 -d 且不加 -t）时直接检索会话缓存；与 -d/-t 搭配时把会话历史并入搜索上下文。
• --query-type / -t：搜索模式，见下节。
• --system-prompt：自定义 LLM 搜索类型的系统提示词文件；未指定时用默认的 answer_simple_question.txt。
• --output-format / -f：json / pretty / simple，默认 pretty。

从 recall_command.py 可以看到输出逻辑的细节：json 与 simple 面向脚本消费（不会混入额外提示行），pretty 面向人类阅读；当结果带 _source == "session" 标记时按会话问答对渲染，否则按搜索类型渲染（GRAPH_COMPLETION/RAG_COMPLETION/HYBRID_COMPLETION 显示 Response，CHUNKS 显示 Chunk 列表）。空结果时 pretty 模式会给出下一步建议，帮助快速排障。

2.3 forget：统一删除语义

forget 把旧版 delete、prune、empty_dataset 的职责统一为一个命令，目标选择非常灵活：

cognee-cli forget --dataset my_project       # 按名称删数据集
cognee-cli forget --dataset-id <uuid>        # 按 UUID 删数据集
cognee-cli forget --dataset my_project --data-id <uuid>   # 删数据集内单个条目
cognee-cli forget --everything               # 或 --all：删除全部数据集与数据

注意 forget_command.py 中的校验逻辑：--dataset 与 --dataset-id 不能同时给出；四个目标参数（--everything/--all、--dataset、--dataset-id、--data-id）至少要指定一个，否则命令直接拒绝执行并提示。--data-id 必须搭配数据集参数使用。

危险操作警示：forget --all 不会请求确认，即使在非交互式 stdin 下也会立即删除所有数据集。而旧版 delete --all 会先弹出 Delete ALL data from cognee? [y/N] 确认提示。切换到 forget 等于悄悄丢掉了这层安全网——脚本化使用时务必谨慎，建议在调用前自行实现确认/备份逻辑。

2.4 improve：对已有图谱进行增强与补全

improve 是 memify 的记忆化别名，在既有知识图谱上运行增强任务（补充上下文、规则与关联），并支持把会话内容桥接进持久图谱：

cognee-cli improve -d my_project             # 无会话：增强/索引图谱
cognee-cli improve -d my_project -s chat_1   # 将会话内容桥接进图谱
cognee-cli improve --node-name "Alice" -d my_project   # 只针对特定实体

参数面（见 improve_command.py）：

• --dataset-name / -d（默认 main_dataset）与 --dataset-id（UUID，二选一，--dataset-id 优先）
• --node-name：过滤到特定命名实体（可多个）
• --session-ids / -s：指定会话 ID（可多个），把这些会话的反馈与 Q&A 内容桥接进永久图谱
• --feedback-alpha：反馈权重更新的学习率，默认 0.1
• --background / -b：后台运行

由于 remember/improve 都经由 cognify() 建图，cognify 级别的配置同样生效，例如 CONTRADICTION_DETECTION=true 这类设置会对二者起作用。

三、搜索类型：CLI 的 7 个选项与 SDK 的完整枚举

CLI 的 --query-type 只开放 7 种搜索类型，定义在 cognee/cli/config.py 的 SEARCH_TYPE_CHOICES：

GRAPH_COMPLETION, HYBRID_COMPLETION, RAG_COMPLETION,
CHUNKS, SUMMARIES, CODE, CYPHER, GRAPH_REPORT

这 7 个取自 SDK 的 SearchType 枚举（见 cognee/modules/search/types/SearchType.py），但 SDK 枚举远不止这些——还包括 TRIPLET_COMPLETION、GRAPH_COMPLETION_DECOMPOSITION、NATURAL_LANGUAGE、TEMPORAL、CODING_RULES、CHUNKS_LEXICAL、AGENTIC_COMPLETION 等。CLI 未开放的类型只能从 SDK 侧调用，例如：

import cognee
from cognee.modules.search.types import SearchType

await cognee.recall(query_text="去年夏天的会议", query_type=SearchType.TEMPORAL)

另一个重要的默认值差异：

• CLI 默认 --query-type 为 GRAPH_COMPLETION（由 DEFAULT_SEARCH_TYPE = "HYBRID_COMPLETION" 兜底前的文档描述可知，recall 命令的帮助文本与默认行为以 GRAPH_COMPLETION 语义为准——实际实现中 recall_command 未显式指定时使用 DEFAULT_SEARCH_TYPE，即 HYBRID_COMPLETION，可通过 --help 确认当前版本行为）。
• SDK 的 cognee.recall() 在省略 query_type 时自动路由，无需显式选择。

提示：recall 命令的 --help 中默认值说明以 HYBRID_COMPLETION 为准，两个版本间行为可能演进，务必以你安装版本的 cognee-cli recall --help 输出为准。

四、会话记忆与增强：CLI 侧只读 + 桥接

会话条目（session entries）目前只能从 SDK 写入——cognee.remember(..., session_id="chat_1")，而 cognee-cli remember 没有会话 flag。CLI 在会话记忆上的角色是"读取与桥接"：

cognee-cli recall "question" -s chat_1       # 会话缓存优先：不加 -d/-t 时直接搜索该会话
cognee-cli sessions get                      # 检索会话 Q&A 历史
cognee-cli improve -d my_project -s chat_1   # 把会话内容桥接进知识图谱
cognee-cli improve -d my_project             # 无会话：仅增强/索引图谱
cognee-cli feedback ...                      # 给结果附加反馈

cognee-cli recall -s chat_1 的"会话直查"模式判定逻辑在 recall_command.py：当 --session-id 存在且既没有 --datasets 也没有显式 --query-type 时，触发会话缓存关键词匹配；否则进入图谱/混合搜索并把会话历史并入上下文。

cognee-cli sessions get（见 sessions_command.py）支持 -n/--last-n（只看最近 N 条）与 -f/--format（pretty / json），pretty 模式下逐条打印 Q/A、反馈评分与反馈文本，json 模式便于脚本解析。

五、遗留 / 底层命令：单阶段驱动的逃生通道

add、cognify、search、memify、delete 仍然随包发布，且正是记忆命令的底层实现。它们适用于"只驱动某一个独立阶段"的场景，其余情况优先使用 remember/recall/forget/improve：

cognee-cli add "text" && cognee-cli cognify  # 等价于 remember 的一步式拆解
cognee-cli search "question"                 # 相当于去掉路由/作用域/会话来源的 recall
cognee-cli memify -d my_project              # 自定义抽取/增强任务
cognee-cli delete --all                      # 已被 forget --all 取代（注意确认行为差异）

特别提醒：memify 必须提供 -d/--dataset-name 或 --dataset-id 其中之一，否则拒绝执行。delete 命令（delete_command.py）在删除前会先展示"即将删除的数据集/条目/用户数量"预览并要求确认，--all 模式的确认文案为 Delete ALL data from cognee? [y/N]，也可用 --force/-f 跳过确认。

六、管理命令：数据集、配置、连接

6.1 数据集操作

cognee-cli datasets list                     # 列出可访问的数据集（ID/名称/创建时间）
cognee-cli datasets create my_project        # 创建数据集并自动授予 read/write/share/delete 权限
cognee-cli datasets data <dataset-uuid>      # 查看数据集内的数据条目
cognee-cli datasets status <uuid> [uuid...] [--pipelines cognify_pipeline]  # 查看管线运行状态
cognee-cli datasets graph <dataset-uuid> -o graph.json   # 导出知识图谱 JSON
cognee-cli datasets delete <dataset-uuid> [-f]           # 按 ID 删除数据集

其中 datasets create 的权限处理在 datasets_command.py 中可以看到：创建后会依次授予 read、write、share、delete 四种权限，并在同名数据集已存在时直接返回既有 ID。

6.2 配置管理

cognee-cli config get [key] [--show-secrets]  # 查看全部或单个设置；API key 默认掩码显示
cognee-cli config list                        # 列出可用配置键
cognee-cli config set <key> <value>           # 设置并持久化到当前目录的 ./.env
cognee-cli config unset <key> [-f]            # 把某键重置为默认值（同样持久化）
cognee-cli config reset [-f]                  # 重置全部键（注意：尚未完整实现）

config_command.py 的实现要点：

• config set 会把值先按 JSON 解析（成功则为布尔/数字/列表等类型），失败则当作字符串；随后调用 cognee.config.set(key, value, persist=True) 写入 .env，并提示新建或更新的文件路径。
• config unset 采用"映射回默认值再 set"的方式实现，覆盖的键包括 llm_provider（默认 openai）、llm_model（默认 gpt-5-mini）、llm_api_key、llm_endpoint、graph_database_provider（默认 ladybug）、vector_db_provider（默认 lancedb）、vector_db_url、vector_db_key、chunk_size（默认 1500）、chunk_overlap（默认 10）。未知键会报错并列出可用键。
• config reset（重置所有键）目前仍未实现，只会打印提示。

6.3 连接运行中的实例

cognee-cli -ui                               # 启动 API 服务器 + Web UI（后端 8000、MCP 8001、前端 3000）
cognee-cli serve --url http://localhost:8000 # 让 CLI/SDK 连接到一个运行中的实例

-ui 由 cognee/cli/_cognee.py 的 UiAction 触发，会调用 start_ui() 拉起前端、后端与 MCP 三个进程，并注册 SIGINT/SIGTERM/SIGHUP 信号处理器，Ctrl+C 时依次停掉 Docker 容器（若涉及）与子进程组。serve（serve_command.py）支持两种模式：默认云模式走 Auth0 设备码授权并自动发现租户；--url 指定直连本地或远程实例，--api-key 用于云实例鉴权，--logout 清除已保存的凭据。入口层还提供 --api-url/--api-key/--api-token 全局参数，把命令委托给远端 API（X-Api-Key 或 Authorization: Bearer），这是文件型数据库（SQLite、Ladybug、LanceDB）下多 Agent 并发访问的正确姿势。

七、关系型数据库迁移（Alembic 风格）

cognee-cli upgrade        # 应用待执行的迁移
cognee-cli downgrade      # 回退数据迁移到指定修订（'base' 或 slug），会重写数据
cognee-cli history        # 列出数据迁移链（最新在前）
cognee-cli current        # 显示各数据库当前 stamp 的迁移修订（含最近失败信息）
cognee-cli stamp          # 仅设置迁移修订号而不运行迁移（用于修复记账状态）

这组命令由 migrate_command.py 提供，通常在版本升级后、服务器因旧 schema 拒绝启动时使用。迁移脚本本体位于 cognee/alembic/versions/（涉及用户/数据集/权限/图谱/管线等数十个修订版本）。

八、常见陷阱（Gotchas）与排障

把文档中列出的陷阱与源码细节结合，整理成一份实战检查单：

1. 首条命令慢是正常的：CLI 惰性初始化 cognee，全新环境的第一条命令要做数据库与模型初始化，之后会明显变快。
2. 默认数据集是 main_dataset：remember（以及 add）不带 --dataset-name 时写入 main_dataset；recall/search 默认跨所有可访问数据集，除非显式指定。
3. forget 裸跑会拒绝执行：必须提供 --dataset、--dataset-id、--data-id（需配合数据集）或 --everything/--all。
4. 会话命令依赖 CACHING=true：recall -s、sessions get、improve -s 需要会话缓存开启（默认开启）。若关闭，会话读取返回空、SDK 会话写入直接报错。想降低读取延迟与 token 成本但保留会话记忆，可执行 cognee-cli config set AUTO_FEEDBACK false——默认情况下 cognee 对每条已回答查询都会发起一次结构化输出 LLM 调用来做自我调优（AUTO_FEEDBACK），关闭它可显著省钱。
5. config set/config unset 写入的是"运行命令时所在目录"的 .env（不存在则创建）；config reset（全部重置）尚未实现。
6. 真正生效的 .env 未必是当前目录那个：这是最隐蔽的坑。cognee 在 import 时会调用 dotenv.load_dotenv(override=True)，该调用以 cognee 包所在位置为基准解析相对路径，而不是你的工作目录。在源码/可编辑安装（uv pip install -e .）下，仓库根目录的 .env 会遮蔽你运行命令所在目录的 .env，并且因为 override=True，它还会覆盖你 export 的环境变量。症状表现为：config set 看似没生效，或 CLI 连接到了你以为已经覆盖掉的后端。应对方法：
   • 测试不同配置时，把仓库根目录的 .env 移开；
   • 或在 import 之后用代码设置（cognee.config.set_*）。
   • 特殊情形：在 python -c 下运行时，当前目录的 .env 反而会赢，因为 __main__ 没有 __file__ 时 dotenv 回退到 cwd——这解释了为什么同一条命令以脚本方式执行与 -c 方式执行可能行为不一致。

九、从 CLI 到 SDK：何时切换

CLI 适合快速验证、脚本化批处理与运维管理；当需要以下能力时建议切换到 SDK：

• 使用 CLI 未开放的搜索类型（如 TEMPORAL、NATURAL_LANGUAGE、AGENTIC_COMPLETION 等完整枚举）；
• 需要 cognee.remember(..., session_id=...) 写入会话条目；
• 需要精细的编程式配置（cognee.config.set_*）或在 import cognee 之后动态调整设置。

两者共享同一套 LLM_API_KEY 与认知管线，remember/recall/forget/improve 在 CLI 与 SDK 间行为一一对应，可以从 CLI 起步、按需无缝过渡到 SDK。

结语

cognee-cli 把 Agent 长期记忆平台的核心操作收敛成了几组高密度命令：remember 一步完成摄取建图，recall 支持图谱/会话双通道检索，improve 持续增强图谱质量，forget 以统一语义管理数据生命周期，再加上数据集、配置、迁移、连接等管理命令，足以支撑从开发调试到生产运维的完整场景。使用前请务必通读 cognee-cli --help 与各子命令的 --help，重点关注 forget --all 的免确认风险与 .env 加载顺序的坑，即可安全、高效地在终端驾驭 cognee 的记忆引擎。