Improve: enrich and index the graph, optionally bridging sessions into it

Run the self-improvement loop over a dataset and report what each stage did.

The nine stages run in a fixed order; each first gates (declines work it cannot do under the current settings, with no LLM calls) and only then runs: feedback_weights, persist_session_qa, persist_agent_traces, extract_agent_context, distill_sessions, update_user_preferences, build_truth_subspace, review_conflicts, global_context_index. Stages 1-7 need sessionIds; stage 7 is opt-in via build_truth_subspace; stages 8 and 9 run by default and can be switched off per call.

Request Parameters

• dataset_name (Optional[str]): Dataset name.
• dataset_id (Optional[UUID]): Dataset UUID.
• extraction_tasks, enrichment_tasks, data, node_name: Deprecated and removed in the next release. Built-in task names still run after the stages (result stage custom_tasks); data and node_name scope them and are ignored without tasks. Use a custom pipeline instead.
• run_in_background (Optional[bool]): Run all stages as one background task and return immediately with status == "running" (default: False).
• build_global_context_index (Optional[bool]): Build the global context index. Omitted or null follows the server’s IMPROVE_GLOBAL_CONTEXT_INDEX (default: true); false skips the stage for this call.
• review_conflicts (Optional[bool]): Review conflicts using source documents and dates. Omitted or null follows IMPROVE_REVIEW_CONFLICTS (default true); skipped without an LLM.
• build_truth_subspace (Optional[bool]): Build the truth subspace from the sessions’ distilled learnings (default: False; needs sessionIds and a backend with truth state).
• feedback_alpha (Optional[float]): Learning rate in (0, 1] for the feedback-weight stage. Omitted means the server’s IMPROVE_FEEDBACK_ALPHA.
• sessionIds (Optional[List[str]]): Session identifiers whose cached memory is bridged into the permanent graph.

Either dataset_name or dataset_id must be provided.

Response

An ImproveResult: status (completed, errored, skipped, running) and one stages[] entry per stage, in order, each with status (completed / already_completed / skipped / errored), a reason when skipped, counts, duration_ms and the pipeline run when the stage is a pipeline. A non-fatal stage error is reported inside the body with a 200; inspect status. A stage that fails because the LLM budget is exhausted ends the run: the stages after it are skipped with reason budget_exhausted.

Error Codes

• 400 Bad Request: Neither dataset_id nor dataset_name provided
• 402 Payment Required: The fatal persist_session_qa stage stopped on an exhausted LLM budget. Same body as the 409 below.
• 409 Conflict: The fatal persist_session_qa stage failed — for a Cognee error the body carries the abort reason and the partial improve_result (what ran before the abort); a non-Cognee error returns a deliberately generic body (details go to the logs, never the wire). Other Cognee errors return their own status codes.