improve()

Enrich an existing graph and bridge session memory with the v1.0 API

cognee.improve()

async def improve(
    dataset: Union[str, UUID] = "main_dataset",
    *,
    run_in_background: bool = False,
    node_name: Optional[List[str]] = None,
    session_ids: Optional[List[str]] = None,
    build_global_context_index: bool = False,
    build_truth_subspace: bool = False,
    review_conflicts: bool = False,
    **kwargs,
) -> ImproveResult

Description

improve() enriches an existing graph after ingestion.

• Without session_ids, it runs the normal enrichment pass over the dataset.
• With session_ids, it can also apply feedback weights, persist session Q&A, persist agent traces, distill accepted session guidance into session_learnings, and update the calling user’s preference subgraph.
• With build_global_context_index=True, it builds dataset-level summary buckets for graph completion retrieval.
• With build_truth_subspace=True, it builds truth-subspace anchors from distilled session_learnings.
• With review_conflicts=True, it reviews each entity’s facts against the documents and dates they came from and records the facts that disagree.

The default enrichment pass does not project the dataset’s graph into memory: its tasks stream triplets straight from the graph database, so improve() no longer pays a full-graph scan and O(graph size) memory cost on every run. The graph is still projected when you pass your own extraction_tasks or enrichment_tasks without data, because a caller-supplied task may need that projected fragment. Enrichment output is unchanged either way.

Each call runs the same ten named stages in a fixed order. A stage that cannot do anything under the current settings is skipped with a reason instead of running, and the returned ImproveResult reports what each stage did.

For the full behavior walkthrough, see Improve.

Parameters

dataset · Union[str, UUID] · default: "'main_dataset'"

Dataset name or UUID to improve. Requires write permission — a dataset owned by another user must be given as a UUID.

run_in_background · bool · default: "False"

Runs every stage as one background task and returns immediately with an ImproveResult whose status is "running". The task holds the improve lock until the last stage finishes. await result.wait() blocks until it is done and returns the same, now finished, result.

node_name · Optional[List[str]] · default: "None"

Restricts the projected graph fragment to specific named entities or node sets. It only applies when the enrichment pass actually projects the graph — that is, when you supply custom extraction_tasks/enrichment_tasks and no data. The default enrichment pass skips projection, so node_name has no effect there.

session_ids · Optional[List[str]] · default: "None"

Session IDs whose feedback, Q&A content, trace activity, and accepted distilled guidance should be bridged into the permanent graph.

Passing session_ids also runs the user-preference stage, which folds rated turns and stated preferences from those sessions into the calling user’s per-dataset prefers weights and preference text. That stage is a no-op that writes nothing unless PERSONALIZATION_ENABLED is on, and it is best-effort — a failure is logged and never blocks the rest of improve(). See Personalized Memory per User.

build_global_context_index · bool · default: "False"

Builds the global context index after enrichment. It also runs in background mode, as the last stage of the background task.

build_truth_subspace · bool · default: "False"

Opt-in flag that builds the truth subspace from distilled session_learnings — after distillation and before enrichment. Only runs when session_ids is provided, and is best-effort (a build failure is logged and never blocks the rest of improve()). Off by default means no behavior change.

review_conflicts · bool · default: "False"

Opt-in flag that reviews the facts of entities changed since its last run (every entity on the first run), in bounded LLM batches. It stores one FactConflict per disputed attribute and marks each fact it covered current, superseded, or conflicting; chunk, hybrid, and graph-completion search then show those labels and a ## Fact conflicts block. Dates come only from each document’s effective_date metadata (see IMPROVE_EFFECTIVE_DATE_KEY), never from when cognee wrote the edge. Needs a configured LLM and EDGE_EVIDENCE_ENABLED (on by default). IMPROVE_REVIEW_CONFLICTS=true turns it on for every run, including the automatic improve after remember(). It replaces cognify’s removed contradiction detection.

Additional keyword options

Option	Type	What it does
extraction_tasks	list	Overrides the extraction task set used during enrichment. Accepts Task objects, registry task names, or a mix; passed to memify() as they are.
enrichment_tasks	list	Overrides the enrichment task set used during enrichment. Same accepted values as extraction_tasks.
data	Any	Supplies explicit data to advanced improvement pipelines. Skips the graph projection, so node_name/node_type are not applied.
node_type	Type	Changes which node type the projected graph fragment targets. Like node_name, it only applies when the graph is projected.
user	object	Runs the operation under a specific user context.
vector_db_config	dict	Overrides vector database configuration for this call.
graph_db_config	dict	Overrides graph database configuration for this call.
feedback_alpha	float	Controls how strongly session feedback changes graph weights. Defaults to IMPROVE_FEEDBACK_ALPHA.

Return value

improve() returns an ImproveResult with one StageResult per stage, in this order:

Stage	Runs when
feedback_weights	session_ids given and the graph backend supports feedback weights
persist_session_qa	session_ids given
persist_agent_traces	session_ids given
extract_agent_context	session_ids given and auto-feedback is on
distill_sessions	session_ids given
update_user_preferences	session_ids given and PERSONALIZATION_ENABLED is on
build_truth_subspace	session_ids given, build_truth_subspace=True, and the graph backend supports truth states
review_conflicts	review_conflicts=True (or IMPROVE_REVIEW_CONFLICTS=true), an LLM is configured, and EDGE_EVIDENCE_ENABLED is on
triplet_enrichment	Triplet embeddings are enabled, or you pass custom extraction_tasks/enrichment_tasks
global_context_index	build_global_context_index=True

Each StageResult has stage, status, reason, error, counts, and duration_ms. status is one of:

• completed: the stage did its work.
• already_completed: there was nothing new since the last run, for example no_new_entries for Q&A that was already bridged, or no_writes_since_last_improve for enrichment on an unchanged dataset.
• skipped: the stage declined before doing any work. reason says why, for example no_session_ids, opt_in_disabled, personalization_disabled, backend_unsupported, disabled_by_config, or budget_exhausted for a stage that was never attempted because an earlier one ran out of LLM budget.
• errored: the stage failed. error holds the message and the remaining stages still run — unless the failure was an exhausted LLM budget, which stops the run.

ImproveResult.status summarises the run: running for a background run that has not finished, errored if any stage errored, skipped if every stage was skipped, and completed otherwise. Use result.stage("distill_sessions") to look up one stage and result.stage_summary() for a compact name=status string.

result = await cognee.improve(dataset="product_docs", session_ids=["support_chat_7"])
for stage in result.stages:
    print(stage.stage, stage.status, stage.reason or "")

A few outcomes to know about:

• Another improve is already running on the same dataset or on one of the same sessions. Improves for one dataset run one at a time, so the call returns without doing anything, and every stage is skipped with reason lock_held.
• persist_session_qa fails. This is the only stage whose ordinary failure stops the run, because dropping session Q&A would lose data. The exception is re-raised, and the partial result is attached to it as exc.improve_result.
• A stage runs out of LLM budget. A failure that is a provider or gateway 402 ends the whole run, because every later stage would spend one more failing call on it. The stage stays errored, the stages after it are skipped with reason budget_exhausted, no further rerun pass starts, and ImproveResult.status is errored. When persist_session_qa is the stage that hit it, the run still raises, with the partial result on exc.improve_result as usual, and the stages it cut off carry budget_exhausted instead of aborted_by_fatal_stage. If persist_session_qa’s pipeline only reported the budget failure without raising, the run still raises LLMPaymentRequiredError, so the payment-required type reaches the caller either way.
• A long agent trace backlog. persist_agent_traces cognifies each session’s oldest pending trace steps in windows of IMPROVE_TRACE_WINDOW_STEPS, advancing that session’s trace watermark after each window, and stops after IMPROVE_TRACE_WINDOWS_PER_RUN windows in total, counted across all the sessions passed: each round takes one window from every session that still has pending steps. Later improves drain the rest. If a window fails, the stage stops and is errored, but windows persisted earlier in the pass stay persisted, and the next run retries only the failed window. The stage’s counts include windows alongside sessions.
• Code that used the old return value. Earlier releases returned the enrichment pipeline’s result directly, in the same shape as legacy memify(). That value is now under result.memify_run, which is {} when enrichment did not run.

Configuration

These environment variables configure the improve loop:

Variable	Default	What it does
IMPROVE_STAGES_DISABLED	empty	Comma-separated stage names to skip with reason disabled_by_config. An unknown stage name, or persist_session_qa (which can’t be disabled), raises an error that lists the valid names: the API server raises it at startup, the SDK the first time improve’s config is read.
IMPROVE_FEEDBACK_ALPHA	0.1	Learning rate for feedback weights, in (0, 1].
IMPROVE_REVIEW_CONFLICTS	false	Set to true to run the review_conflicts stage on every improve, including the automatic one after remember().
IMPROVE_EFFECTIVE_DATE_KEY	effective_date	The external_metadata key the review_conflicts stage reads a document’s date from.
IMPROVE_TRACE_WINDOW_STEPS	30	Maximum number of agent trace steps the persist_agent_traces stage puts into one persisted document. Must be at least 1.
IMPROVE_TRACE_WINDOWS_PER_RUN	10	Maximum number of trace windows one persist_agent_traces pass cognifies, across all sessions. The rest of the backlog waits for the next improve(). Must be at least 1.
IMPROVE_AUTO_ENABLED	true	Set to false to turn off the automatic improve() after remember(), even when self_improvement=True.
IMPROVE_DEBOUNCE_ENTRIES	1	For remember(session_id=...), run the automatic improve only after this many new session entries since the last one. 0 turns this trigger off.
IMPROVE_DEBOUNCE_SECONDS	0	For remember(session_id=...), run the automatic improve only after this many seconds since the last one. 0 turns this trigger off. When set on its own, the entries trigger steps aside, so the debounce is time-only.

With the defaults there is no debounce, and every remember(session_id=...) call runs an improve. Entries held back by the debounce are not dropped: recall still reads them from the session cache, and the next improve that runs bridges them.

An application that embeds Cognee can also decline a single automatic improve at runtime — when the tenant it serves has no LLM budget left, say — by registering an admission check. See Declining the automatic improve. Explicit improve() calls are never gated by it.

Troubleshooting

Fixing 'PermissionDeniedError' on improve()

The target dataset is resolved and authorized for write once, before any stage runs, so a bad dataset fails the whole call instead of silently enriching your default dataset:

PermissionDeniedError: Request owner does not have necessary permission: [write] for all datasets requested.

Common causes:

• No write grant on the UUID. Read access is not enough — every improvement stage writes. Ask the dataset owner for a write grant; see Access Control Lists.
• The UUID does not exist. Unknown and unauthorized UUIDs are reported identically, so dataset existence is never confirmed to an unauthorized caller. Double-check the UUID against your datasets.
• You passed another user’s dataset name. Names are owner-scoped: improving a name that another user happens to own does not raise — it resolves (or creates) your own dataset with that name and leaves theirs untouched. To improve a dataset owned by someone else, pass its UUID.

improve() on a session returns lock_held

Only one improve() runs at a time for a given dataset or session; a call that finds its keys already claimed does nothing, and every stage of its result is skipped with reason lock_held.

Check rerun_requested before retrying a session-keyed call (session_ids=[...]):

• True — the running improve holds one of your sessions, and your call asked it for one more pass. You do not need to retry. Before releasing the lock, the running improve checks for that request and runs its stages again — every stage is watermark-gated, so the extra pass only touches session entries that arrived in the meantime. That is how entries written while an improve is already running still reach the graph. The extra pass covers only the sessions the running improve holds, so any other sessions you passed are not bridged by it.
• False — the collision was on the dataset only: the holder is a dataset-only run, or a session-keyed run over different sessions in the same dataset. Nothing will cover your entries, so retry later.

A run makes at most 3 passes in total (the first plus up to 2 extra). A request that arrives after the last pass is left for the next improve that claims those sessions, so if that session has ended and no further improve comes, the entries are not bridged.

The running improve reports the extra passes on its own result: stages stays the first pass, and rerun_passes holds one list of stage results per extra pass. status covers all passes, so an errored stage in an extra pass marks the whole run errored.

A dataset-only call (no session_ids) makes no rerun request and always gets rerun_requested=False: a burst of calls on one dataset simply skips, and the running improve’s enrichment is the only one. The lock and the rerun request are in-process, so they only coordinate calls within one worker.

Examples

import cognee

await cognee.improve(
    dataset="product_docs",
    session_ids=["support_chat_7"],
)

await cognee.improve(
    dataset="product_docs",
    session_ids=["support_chat_7"],
    build_truth_subspace=True,
)

await cognee.improve(
    dataset="product_docs",
    build_global_context_index=True,
)

Related

See also Global Context Index for how to use the generated summaries during search, and memify() if you need lower-level control over the legacy enrichment pipeline.