Operations

What cognee-rust does: the remember / recall / improve / forget memory API and the underlying add / cognify / memify / search pipeline.

What cognee-rust does. The primary surface is the memory API — remember, recall, improve, forget — four high-level operations that compose the lower-level pipeline (add → cognify → memify → search). Every operation is reachable from each interface (CLI, language bindings, and the HTTP server, which is not part of the cognee-rs repository) — see Tools. API/type detail lives in rustdoc (cargo doc --no-deps --open); this page is the conceptual map.

The memory API

Cognee’s primary surface is four operations that turn raw input into queryable, self-improving memory. They live in the cognee api module (cognee::api::{remember, recall, improve, forget}) and surface as the always-built cognee-cli verbs remember / recall / improve / forget.

input ──remember──▶ memory (graph + vectors, optionally session)
query ──recall────▶ auto-routed answers
        improve───▶ enriched / bridged memory
        forget────▶ removed memory

remember

Stores input as memory: it runs add + cognify and then, by default, the improve enrichment pass. Accepts inline text and/or file paths.

• Session memory — pass a --session-id to scope the turn to a session (session-backed QA history).
• Permanent graph memory — omit --session-id and the input is persisted as permanent, graph-backed memory.

remember ≈ add + cognify + improve. rustdoc: api::remember.

recall

Queries memory with auto-routing: when no query type is given, recall picks an appropriate retrieval strategy automatically. It is session-aware (reads session history when given a --session-id) and graph-backed. Results are returned to the caller (printed to stdout by the CLI).

recall ≈ auto-routed search. rustdoc: api::recall.

improve

Enriches memory and bridges sessions: runs the feedback/enrichment improvement stages over the graph (memify-style triplet enrichment plus feedback weighting). When session IDs are supplied it also distills each session’s Q&A into curated, entity-anchored “session-learnings” lesson documents (tagged with the session_learnings node-set) and cognifies them into the permanent graph. Can target specific sessions or graph nodes and tune the feedback weight. rustdoc: api::improve.

forget

Removes memory: a whole dataset, a specific data item, or everything. Cascades across the relational, graph, and vector backends and file storage. rustdoc: api::forget.

Lower-level pipeline

The memory API composes these building blocks. They remain available directly when you need fine-grained control over each stage. The classic flow is:

raw data ──add──▶ stored + deduplicated ──cognify──▶ knowledge graph + vectors ──search──▶ answers

add (ingest)

Streams input, computes a content hash, deduplicates, and persists the data plus metadata. Accepts text, file paths, and HTTP(S) URLs (fetched and routed by MIME type). URL fetches refuse private, loopback, link-local, carrier-grade NAT (100.64.0.0/10), multicast and unspecified addresses, including IPv4-mapped IPv6 forms. This applies to IP-literal URLs, to hostnames that resolve only to such addresses, and to every redirect hop. A blocked URL fails at once with an invalid-URL error and is not retried. HTTP_PROXY / HTTPS_PROXY / ALL_PROXY (and NO_PROXY) are honoured; when a proxy is used, the proxy resolves the target hostname, so only IP-literal targets are checked. Deterministic UUID5 IDs make the same content + owner reproducible across SDKs. Pipeline: cognee-ingestion (AddPipeline).

cognify (knowledge-graph extraction)

Turns stored data into a knowledge graph in five stages: classify documents → chunk text → extract entities/relationships (LLM, batched) and summarize (conditional) — one fused stage running both concurrently over the same chunks, matching Python’s extract_graph_and_summarize → add data points (six vector collections + provenance to the relational DB) → extract DLT FK edges. Configurable via CognifyConfig (chunk strategy, custom prompts/schemas, temporal mode). Pipeline: cognee-cognify (cognify() / cognify_datasets()).

The add data points stage embeds and writes each vector collection in windows of about 16 MiB of vector data (cognee_vector::write_window_points, around 2,700 points at 1536 dimensions), so memory on the write path does not grow with the corpus. By default the generated vectors are not kept in the result: CognifyResult.embeddings is empty unless CognifyConfig::with_retained_embeddings(true) (field retain_embeddings, default false) is set. The vectors are in the vector store either way, and CognifyResult.embedding_count reports how many chunk, entity and summary embeddings the run generated. Code that read embeddings.len() should read embedding_count instead.

When a cognify run fails

A chunk or a file the pipeline cannot process is not a bare error: the chunking, graph-extraction and summarization stages collect their failures, and the run result carries a report naming which file, which chunk, which stage and what went wrong. CognifyResult.failures carries it on success; CognifyError::RunFailed carries the same report when the run failed.

What happens to what the run already wrote is decided at the end, from two independent settings — when to stop (FailFast, the default, or RunToEnd) and what to sweep (WholeRun, the default, FailedItems, or Nothing). The full matrix is in Cognify failure handling; the end states are:

• Default (FailFast + WholeRun). The run stops at the first failed batch — not the first failed file, see below — everything it created is removed, the run is recorded ERRORED and the call returns Err. The store converges to its pre-run state — what earlier runs completed is untouched, because the sweep selects only rows naming this run. Python’s default, in execution and in end state.
• FailedItems below the failure ratio. The run completes. Only the failed files’ contributions are removed; the files that finished are kept, indexed and marked complete; and the call returns Ok with the failed-file list in the report, so the next run knows exactly what to redo.
• FailedItems over the ratio escalates to a whole-run sweep and an errored run — a large enough share of failed chunks means something systemic, not one bad file.
• Nothing removes nothing. The escape hatch (code only — not selectable from the environment).

Under FailFast a run partitions its files three ways at the abort point: complete (every chunk extracted — persisted and marked), failed (at least one chunk failed) and unreached (never attempted). Only complete files are persisted, which is what keeps a data item all-or-nothing; failed and unreached files are indistinguishable to the next run and are simply redone.

The abort point is a batch boundary, not a file boundary, and how much work FailFast actually saves depends on how big that batch is. Graph extraction stops after the batch that contained the failure — chunks_per_batch, default 2000, so a dataset under 2000 chunks is one batch and every extraction call is dispatched before the failure is noticed. Temporal extraction stops after data_per_batch, default 20 files. Summarization has no batch loop: it stops dispatching as soon as a fatal failure comes back, but the calls already in flight (up to max_parallel_extractions) are neither cancelled nor discarded. FailFast is an upper bound on wasted spend, not a promise of none.

A sweep deliberately keeps anything still claimed from outside its scope: an entity a surviving file also produced, an artifact another run or another dataset also names, or a row written before ownership tracking existed. The worst case is a surplus artifact that keeps an owner, never an artifact with no owner at all.

That claim is recorded even when the artifact is not written. Graph extraction filters out edges the graph already holds, so a file cognified in a later run adds no second copy of an edge an earlier file created — but it still records ownership of it. Without that row the earlier file would be the edge’s only owner, and deleting it would take the edge’s vectors away from a file that still references it. Ownership is per (dataset, data item): an edge shared across two datasets is still governed by each dataset’s own exclusivity check, the same limitation entity ownership has.

One caveat. Cancellation is swept, unlike Python — though there is no caller-facing cancel handle on cognify() today, and simply dropping the future runs no sweep at all.

All of the above applies to the temporal pipeline too: it records ownership of its events, timestamps, intervals and entity nodes before it writes them, its two LLM passes collect failures rather than swallowing them, and a failed temporal run converges the same way.

For a run that was killed (not failed in-process), see Single-process startup recovery and cognee-cli pipeline-unblock / edge-reindex in the CLI Reference.

Re-cognifying is now incremental

incremental_loading is on by default and now does what it says. A successful run marks each data item it finished, in Python’s own pipeline_status format, and the next run skips the marked items before it builds a pipeline — no classification, no chunking, no LLM calls.

Behaviour change: re-cognifying an already-complete dataset is a no-op, returning Ok with already_completed = true. Deployments that relied on cognify re-processing everything on every call will see it “stop doing anything”; set with_incremental_loading(false) to restore the previous behaviour.

A failed run marks nothing, and a sweep clears the markers of whatever it rolled back, so the next run redoes exactly the work that was lost.

Both branches share one marker key, matching Python, so a cognify() and a temporal cognify() over the same dataset are no-ops for each other. Turn incremental loading off to build both graphs over one dataset. See Completion markers and incremental loading.

memify (graph enrichment)

Standalone, idempotent enrichment: reads the existing graph, builds Triplet objects from every edge ("source → relationship → target"), embeds them, and indexes them into the Triplet/text vector collection for SearchType::TripletCompletion. Pipeline: cognee-cognify (memify()).

search (retrieval)

Unified orchestration across 16 retrieval strategies selected by SearchType (crates/search/src/types/search_type.rs): GraphCompletion (default), GraphCompletionCot, GraphCompletionContextExtension, GraphSummaryCompletion, TripletCompletion, RagCompletion, Chunks, Summaries, Temporal, Cypher, NaturalLanguage, FeelingLucky, Feedback, CodingRules, ChunksLexical, HybridCompletion (combines vector search over chunks/summaries/entities/edge-facts and 1-hop graph-neighborhood expansion around matched entities, then answers via LLM completion; tuning knobs in Configuration: hybrid retriever knobs). The CLI’s -t/--query-type exposes only a subset — see CLI Reference. Entry: cognee-search (SearchBuilder / SearchOrchestrator).

Additional operations

These live in the cognee api module (and DatasetManager):

Operation	What it does	rustdoc
delete	Cascading removal of data/datasets across relational → graph → vector → file storage (with dry-run preview).	cognee-delete DeleteService
update	Re-ingest changed data and re-cognify the affected subset.	api::update
prune	Reset system or all state (prune_system / prune_data).	api::prune
visualize	Render the graph to a single-file d3.js HTML page (Graph / Schema / Memory / Semantic tabs + inspector).	cognee-visualization
export	Write the graph as a COGX archive — the portable format Python cognee re-imports, locally or by uploading the packed .cogx.tar.gz to its remember endpoint.	cognee-migration

Operation → interface map

Operation	CLI	HTTP route	Binding method
remember	cognee-cli remember	POST /api/v1/remember	remember()
recall	cognee-cli recall	POST /api/v1/recall	recall()
improve	cognee-cli improve	POST /api/v1/improve	improve()
forget	cognee-cli forget	POST /api/v1/forget	forget()
add	cognee-cli add	POST /api/v1/add	add()
cognify	cognee-cli cognify	POST /api/v1/cognify	cognify()
add + cognify	cognee-cli add-and-cognify	(two calls)	—
memify	cognee-cli memify	POST /api/v1/memify	memify()
search	cognee-cli search	POST /api/v1/search	search()
delete	cognee-cli delete	POST /api/v1/delete	delete*()
update	(via run-sequence)	POST /api/v1/update	update()
visualize	cognee-cli visualize	POST /api/v1/visualize	visualize()
export	cognee-cli export	(none yet)	exportCogx() (Java only)

CLI flags and feature gates: tools/cli. HTTP request/response shapes: documented with the server, which is not part of the cognee-rs repository (see HTTP Server Tools). Binding method names per language: tools/bindings.