improve

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, triplet_enrichment, global_context_index. Stages 1-7 need sessionIds; stages 7 and 9 are opt-in via the build* flags.

Request Parameters

extraction_tasks (Optional[List[str]]): Tasks for graph/data extraction.
enrichment_tasks (Optional[List[str]]): Tasks for graph enrichment.
data (Optional[str]): Custom input data. Uses existing graph when omitted.
dataset_name (Optional[str]): Dataset name.
dataset_id (Optional[UUID]): Dataset UUID.
node_name (Optional[List[str]]): Filter to specific named entities.
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 after enrichment (default: False).
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.

Error Codes

400 Bad Request: Neither dataset_id nor dataset_name provided
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.

POST

api

improve

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

curl --request POST \
  --url https://{tenant}.aws.cognee.ai/api/v1/improve \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "extractionTasks": [],
  "enrichmentTasks": [],
  "data": "<string>",
  "datasetName": "<string>",
  "datasetId": "",
  "nodeName": [],
  "runInBackground": false,
  "buildGlobalContextIndex": false,
  "buildTruthSubspace": false,
  "feedbackAlpha": 0.5,
  "sessionIds": []
}
'

import requests

url = "https://{tenant}.aws.cognee.ai/api/v1/improve"

payload = {
    "extractionTasks": [],
    "enrichmentTasks": [],
    "data": "<string>",
    "datasetName": "<string>",
    "datasetId": "",
    "nodeName": [],
    "runInBackground": False,
    "buildGlobalContextIndex": False,
    "buildTruthSubspace": False,
    "feedbackAlpha": 0.5,
    "sessionIds": []
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "status": "completed",
  "dataset_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "dataset_name": "<string>",
  "session_ids": [
    "<string>"
  ],
  "stages": [
    {
      "stage": "<string>",
      "status": "completed",
      "reason": "<string>",
      "error": "<string>",
      "counts": {},
      "duration_ms": 0,
      "run": {
        "status": "<string>",
        "pipeline_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "dataset_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "dataset_name": "<string>",
        "payload": null,
        "data_ingestion_info": [
          "<unknown>"
        ]
      }
    }
  ],
  "memify_run": "<unknown>",
  "background": false,
  "finished": true,
  "error": "<string>",
  "rerun_requested": false,
  "rerun_passes": [
    [
      {
        "stage": "<string>",
        "status": "completed",
        "reason": "<string>",
        "error": "<string>",
        "counts": {},
        "duration_ms": 0,
        "run": {
          "status": "<string>",
          "pipeline_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "dataset_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "dataset_name": "<string>",
          "payload": null,
          "data_ingestion_info": [
            "<unknown>"
          ]
        }
      }
    ]
  ]
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

extractionTasks

string[] | null

Example:

[]

enrichmentTasks

string[] | null

Example:

[]

data

string | null

datasetName

string | null

datasetId

Example:

""

nodeName

string[] | null

Example:

[]

runInBackground

boolean | null

default:false

buildGlobalContextIndex

boolean | null

default:false

buildTruthSubspace

boolean | null

default:false

feedbackAlpha

number | null

Required range: 0 < x <= 1

sessionIds

string[] | null

Example:

[]

Response

Successful Response

One entry per stage, in registry order, for one improve() run.

status summarises the stages: running while a background run is still going, errored when any stage errored, skipped when every stage was skipped (a lost lock claim, an unchanged graph with nothing opted in), completed otherwise. await result.wait() blocks on a background run and returns the same, now finished, object.

status

enum<string>

required

read-only

Available options:

completed,

errored,

skipped,

running

dataset_id

string<uuid> | null

dataset_name

string | null

session_ids

string[]

stages

StageResult · object[]

Show child attributes

memify_run

any

background

boolean

default:false

finished

boolean

default:true

error

string | null

rerun_requested

boolean

default:false

rerun_passes

StageResult · object[][]

Show child attributes

⌘I

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

curl --request POST \
  --url https://{tenant}.aws.cognee.ai/api/v1/improve \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "extractionTasks": [],
  "enrichmentTasks": [],
  "data": "<string>",
  "datasetName": "<string>",
  "datasetId": "",
  "nodeName": [],
  "runInBackground": false,
  "buildGlobalContextIndex": false,
  "buildTruthSubspace": false,
  "feedbackAlpha": 0.5,
  "sessionIds": []
}
'

import requests

url = "https://{tenant}.aws.cognee.ai/api/v1/improve"

payload = {
    "extractionTasks": [],
    "enrichmentTasks": [],
    "data": "<string>",
    "datasetName": "<string>",
    "datasetId": "",
    "nodeName": [],
    "runInBackground": False,
    "buildGlobalContextIndex": False,
    "buildTruthSubspace": False,
    "feedbackAlpha": 0.5,
    "sessionIds": []
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "status": "completed",
  "dataset_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "dataset_name": "<string>",
  "session_ids": [
    "<string>"
  ],
  "stages": [
    {
      "stage": "<string>",
      "status": "completed",
      "reason": "<string>",
      "error": "<string>",
      "counts": {},
      "duration_ms": 0,
      "run": {
        "status": "<string>",
        "pipeline_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "dataset_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "dataset_name": "<string>",
        "payload": null,
        "data_ingestion_info": [
          "<unknown>"
        ]
      }
    }
  ],
  "memify_run": "<unknown>",
  "background": false,
  "finished": true,
  "error": "<string>",
  "rerun_requested": false,
  "rerun_passes": [
    [
      {
        "stage": "<string>",
        "status": "completed",
        "reason": "<string>",
        "error": "<string>",
        "counts": {},
        "duration_ms": 0,
        "run": {
          "status": "<string>",
          "pipeline_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "dataset_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "dataset_name": "<string>",
          "payload": null,
          "data_ingestion_info": [
            "<unknown>"
          ]
        }
      }
    ]
  ]
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Getting Started

auth

add

cognify

memify

search

permissions

datasets

ontologies

settings

visualize

schema

skills

configuration

delete

validate

update

responses

llm

sync

users

checks

health

agent management

agent connections

activity

sessions

remember

recall

improve

forget

slack

integrations

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

Request Parameters

Response

Error Codes

Authorizations

Body

Response