- 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 (demo, eval, serve,
push, upgrade, downgrade, stamp, and search with one CODE example)
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:
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 replacing the older delete and
empty-dataset paths. --memory-only (with a dataset) drops the graph and
vectors but keeps the raw files, so the data can be rebuilt.
forget --alldoes not ask for confirmation. It deletes every dataset immediately, even on a non-interactive stdin. The legacydelete --allpromptsDelete ALL data from cognee? [y/N]first, so switching toforgetsilently 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, 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:
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 --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 (--node-name is deprecated: it warns and is
ignored). It prints one line per stage — name, status
(completed / already_completed / skipped / errored) and the skip
reason (e.g. no_session_ids, opt_in_disabled).
remember/improve build their graphs through cognify(), so cognify-level
settings (e.g. PROVENANCE_TRACKING=true) apply to them too.
Legacy / lower-level commands
add, cognify, search, 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.
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 delete --all # superseded by `forget --all`
Management
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
Database migrations
cognee has two migration chains: the relational schema (Alembic, in
cognee/alembic/) and the graph/vector data chain (slugs registered in
cognee/modules/migrations/registry.py). Both run automatically — at API
server startup and on the first write (remember, add, cognify,
improve, …) in an SDK/CLI process — unless ENABLE_AUTO_MIGRATIONS=false.
So you rarely need these commands; they are for inspecting state, disabled
auto-migration, and rollbacks. There is no migrate command.
cognee-cli current # stamped revision per database (per dataset
# with access control on)
cognee-cli history # the data-migration chain, newest first
cognee-cli upgrade # relational to head, then data chain to head
cognee-cli upgrade <slug> # data chain up to and including <slug>
cognee-cli upgrade --alembic <rev> # pin the relational (Alembic) target
cognee-cli downgrade <slug|base> # REWRITES DATA; revision is required,
# prompts unless --force; --dataset <uuid>
# (repeatable) limits it
cognee-cli stamp <head|base|slug> # set the stored revision WITHOUT running
# anything; prompts unless --force;
# --dataset <uuid> (repeatable) limits it
The positional revision is always a data-chain slug; the relational
target goes through --alembic. downgrade leaves the relational schema
alone unless you pass --alembic. upgrade runs even when
ENABLE_AUTO_MIGRATIONS=false. --alembic-path (or COGNEE_ALEMBIC_PATH)
points at a custom Alembic scripts directory.
Gotchas
- The CLI initializes cognee lazily; the first command in a fresh environment is slow (DB + model setup), later ones are fast.
remember(andadd) without--dataset-nametargets the default datasetmain_dataset;recall/searchoperate across your accessible datasets unless a dataset is given.forgetrefuses to run bare — pass--dataset,--dataset-id,--data-id(with a dataset), or--everything/--all.- Session commands (
recall -s,sessions get,improve -s) requireCACHING=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. config set/config unsetwrite to the.envfile in whatever directory you run the command from (creating it if missing).config reset(reset all keys) is still not implemented.- Which
.envactually wins is not always the cwd one. At import, cognee callsdotenv.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.envat the repo root therefore shadows the.envin the directory you ran from — and becauseoverride=True, it also beats variables youexported. Symptom:config setappears to do nothing, or the CLI connects to a backend you thought you had overridden. To test against different settings, move the repo.envaside, or set values programmatically after import (cognee.config.set_*). (Underpython -cthe cwd.envdoes 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.)