cognee-cli

---
name: cognee-cli
description: Use when the user wants to drive cognee from the terminal with cognee-cli — remember/recall/forget/improve memory commands, managing datasets and config, or database migrations.
---

# Use the cognee CLI

`cognee-cli` ships with the package (entry point in `cognee/cli/_cognee.py`;
each command lives in `cognee/cli/commands/`). Every command has
`--help` for its flags, but only a few (`memify`, `eval`, `serve`, `push`,
`migrate`) include usage examples — for the memory commands use the examples
in this file. Needs `LLM_API_KEY` configured, same as the SDK.

## Core flow

The memory commands are the primary surface as of cognee 1.x:

```bash
cognee-cli remember "Your text here"         # also accepts file paths / URLs
cognee-cli remember ./docs --dataset-name my_project
cognee-cli recall "Your question"            # query the graph
cognee-cli recall "keyword" --query-type CHUNKS
cognee-cli forget --all                      # wipe local state
```

`remember` is ingest + graph build in one step (`add` + `cognify` under the
hood); `--background`/`-b` runs the cognify stage in the background, and
`--dry-run` estimates LLM tokens/cost without ingesting. `recall` takes
`--datasets`/`-d`, `--top-k`/`-k` (default 10), and `--session-id`/`-s`.

`forget` targets `--dataset`, `--dataset-id`, `--data-id` (needs a dataset), or
`--everything`/`--all` — one unified command covering what `delete`, `prune`,
and `empty_dataset` used to do separately.

> **`forget --all` does not ask for confirmation.** It deletes every dataset
> immediately, even on a non-interactive stdin. The legacy `delete --all`
> prompts `Delete ALL data from cognee? [y/N]` first, so switching to `forget`
> silently drops that safety net — script it with care.

`--query-type` accepts 10 of the SDK's 20 `SearchType` values — the list in
`cognee/cli/config.py:SEARCH_TYPE_CHOICES`: HYBRID_COMPLETION, GRAPH_COMPLETION,
RAG_COMPLETION, CHUNKS, CHUNKS_LEXICAL, SUMMARIES, CODE, CYPHER, GRAPH_REPORT,
SKILLS. The rest (TEMPORAL, TRIPLET_COMPLETION, GRAPH_COMPLETION_COT,
AGENTIC_COMPLETION, NATURAL_LANGUAGE, …) are SDK-only, e.g.
`cognee.recall(q, query_type=SearchType.TEMPORAL)`.

When `--query-type` is omitted the CLI uses `HYBRID_COMPLETION`
(`DEFAULT_SEARCH_TYPE`), whereas the SDK's `cognee.recall()` auto-routes
between search types. `--top-k` defaults to 10 on the CLI and 15 in the SDK.

## Session memory and enrichment

Session entries are currently written from the SDK — `cognee.remember(...,
session_id="chat_1")` — not the CLI (`cognee-cli remember` has no session
flag). The CLI side of session memory is reading and bridging:

```bash
cognee-cli recall "question" -s chat_1       # session cache first: without -d/-t
                                             # this searches the session directly
cognee-cli sessions get                      # retrieve session Q&A history
cognee-cli improve -d my_project -s chat_1   # bridge session content into the graph
cognee-cli improve -d my_project             # enrich/index the graph (no session)
cognee-cli feedback ...                      # attach feedback to results
```

`improve` also takes `--node-name`, `--feedback-alpha` (learning rate in
(0, 1]; default `IMPROVE_FEEDBACK_ALPHA`, 0.1), `--build-global-context-index`,
`--build-truth-subspace` (both opt-in stages; the truth subspace needs
`-s`), and `--background`/`-b`. It prints one line per stage — name, status
(`completed` / `already_completed` / `skipped` / `errored`) and the skip
reason (e.g. `no_session_ids`, `lock_held`, `triplet_embedding_disabled`).
`remember`/`improve` build their graphs through `cognify()`, so cognify-level
settings (e.g. `CONTRADICTION_DETECTION=true`) apply to them too.

## Legacy / lower-level commands

`add`, `cognify`, `search`, `memify`, and `delete` still ship and are what the
memory commands call underneath. Use them only to drive a single stage in
isolation; prefer `remember`/`recall`/`forget`/`improve` otherwise.

```bash
cognee-cli add "text" && cognee-cli cognify  # what `remember` does in one step
cognee-cli search "question"                 # `recall` minus routing/scope/session sources
cognee-cli memify -d my_project              # custom extraction/enrichment tasks
cognee-cli delete --all                      # superseded by `forget --all`
```

## Management

```bash
cognee-cli datasets list                     # dataset operations
cognee-cli config get [key] [--show-secrets] # view one/all settings (API keys masked by default)
cognee-cli config set <key> <value>          # set + persist to ./.env in the cwd
cognee-cli config unset <key>                # reset a key to its default (also persisted)
cognee-cli -ui                               # launch API server + UI (see cognee-server skill)
cognee-cli serve --url http://localhost:8000 # connect CLI/SDK to a running instance
```

## Relational DB migrations (Alembic)

```bash
cognee-cli upgrade        # apply migrations
cognee-cli downgrade
cognee-cli history
cognee-cli current
```

Typically needed after version upgrades when the server refuses to start on
an old schema.

## Gotchas

- The CLI initializes cognee lazily; the first command in a fresh environment
  is slow (DB + model setup), later ones are fast.
- `remember` (and `add`) without `--dataset-name` targets the default dataset
  `main_dataset`; `recall`/`search` operate across your accessible datasets
  unless a dataset is given.
- `forget` refuses to run bare — pass `--dataset`, `--dataset-id`, `--data-id`
  (with a dataset), or `--everything`/`--all`.
- Session commands (`recall -s`, `sessions get`, `improve -s`) require
  `CACHING=true` (the default) — with it off, session reads return nothing and
  SDK session writes raise. To cut read latency and token cost while keeping
  session memory, `cognee-cli config set AUTO_FEEDBACK false` — by default
  cognee makes one structured-output LLM call per answered query to self-tune
  its memory.
- `memify` requires one of the arguments -d/--dataset-name --dataset-id
- `config set`/`config unset` write to the `.env` file in whatever directory
  you run the command from (creating it if missing). `config reset` (reset
  *all* keys) is still not implemented.
- **Which `.env` actually wins is not always the cwd one.** At import, cognee
  calls `dotenv.load_dotenv(override=True)`, which resolves relative to the
  *cognee package location*, not your working directory. In a source/editable
  checkout (`uv pip install -e .`) a `.env` at the repo root therefore shadows
  the `.env` in the directory you ran from — and because `override=True`, it
  also beats variables you `export`ed. Symptom: `config set` appears to do
  nothing, or the CLI connects to a backend you thought you had overridden.
  To test against different settings, move the repo `.env` aside, or set
  values programmatically after import (`cognee.config.set_*`). (Under
  `python -c` the cwd `.env` does win, because dotenv falls back to the cwd
  when `__main__` has no `__file__` — which is why the same command can
  behave differently as a script vs. `-c`.)