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,
    **kwargs,
)

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 sync enriched graph context back into sessions.
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.

For the full behavior walkthrough, see Improve.

Parameters

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.

bool

default:"False"

Starts the improvement pipeline asynchronously.

Optional[List[str]]

default:"None"

Restricts improvement to specific named entities or node sets.

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.

bool

default:"False"

Builds the global context index after enrichment. This is skipped when run_in_background=True.

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.

Additional keyword options

Option	Type	What it does
`extraction_tasks`	`list`	Overrides the extraction task set used during enrichment.
`enrichment_tasks`	`list`	Overrides the enrichment task set used during enrichment.
`data`	`Any`	Supplies explicit data to advanced improvement pipelines when supported.
`node_type`	`Type`	Changes which node type the enrichment pass targets.
`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.

Return value

improve() returns the pipeline result from the enrichment pass, the same underlying shape used by legacy memify().

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.

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,
)

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.

​cognee.improve()

​Description

​Parameters

​Additional keyword options

​Return value

​Troubleshooting

​Examples

​Related

cognee.improve()

Description

Parameters

Additional keyword options

Return value

Troubleshooting

Examples

Related