> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Session Distillation

> Endpoint and automatic triggers for bridging agent sessions into permanent memory

**Session distillation** bridges a conversation from the short-lived session cache into your permanent knowledge graph: it weights existing memories by the session's feedback, persists the Q\&A and agent traces, distills durable guidance into reusable lessons (`session_learnings`), and enriches the graph so future sessions recall from it. Surfaced in the UI as **Self-improvement**.

This page covers the Cloud endpoint and how it fires automatically for connected agents. For the concept and SDK walkthroughs, see [Session Distillation (guide)](/guides/session-distillation), the [Self-Improvement Quickstart](/guides/self-improvement-quickstart), and the [`improve`](/core-concepts/main-operations/improve) operation.

## Improve

**`POST /api/v1/improve`** — Enrich the graph and, when `session_ids` is passed, bridge those sessions into it.

```bash theme={null}
curl -X POST https://your-tenant.aws.cognee.ai/api/v1/improve \
  -H "X-Api-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"dataset_name": "project_memory", "session_ids": ["conversation_1"], "run_in_background": true}'
```

Without `session_ids`, the call runs default graph enrichment only. With `session_ids`, it runs the full session-to-graph pipeline described above for each session.

### Request body

| Parameter                    | Type      | Description                                                                                                                                                                                            |
| ---------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `dataset_name`               | string    | Target dataset name. Provide this **or** `dataset_id`.                                                                                                                                                 |
| `dataset_id`                 | UUID      | Target dataset UUID, alternative to `dataset_name`.                                                                                                                                                    |
| `session_ids`                | string\[] | Sessions to bridge into the permanent graph. Omit to run enrichment only.                                                                                                                              |
| `run_in_background`          | boolean   | Run the cognify-heavy pipelines asynchronously. Default `false`. With `session_ids`, the distillation stages still run inside the request, so the call can take minutes — use a generous read timeout. |
| `build_global_context_index` | boolean   | Build the global context index after enrichment. Default `false`. **Skipped in background mode** (ordered background chaining is not supported).                                                       |
| `node_name`                  | string\[] | Restrict enrichment to specific named entities.                                                                                                                                                        |

<Note>
  Either `dataset_name` or `dataset_id` is required. `extraction_tasks`, `enrichment_tasks`, and `data` are power-user overrides most callers never set.
</Note>

### Error responses

| Status | Meaning                                                                                                                                                              |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Neither `dataset_name` nor `dataset_id` was provided.                                                                                                                |
| `402`  | Insufficient credits to run improve — the tenant's prepaid budget cannot cover the estimated cost. Raised pre-flight, before any work starts. Add credits and retry. |
| `409`  | `{"error": "An error occurred during graph improvement."}` — an unexpected server error interrupted the improve run.                                                 |
| `420`  | The pipeline run itself completed with an error; the response body carries the failed run's details.                                                                 |

## Automatic distillation for agent sessions

You rarely call this endpoint directly. When you connect a coding agent through the [Agent Integrations](/cognee-cloud/agent-integrations/index), the plugin fires it for you.

The Cognee coding-agent plugins (Claude Code, Codex) run session distillation for you — you never call `improve()` by hand. A distillation pass fires on three triggers:

| Trigger                | When it fires                | How                                                                                                                                                                                                                                                                            |
| ---------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Session end**        | You quit the agent           | The `SessionEnd` hook drains buffered turns into the server session cache, then fires `POST /api/v1/improve` for the session id in the background. A launch-exit watcher covers exits where the hook never fires — a hard exit, or Codex CLI shutdowns that skip `SessionEnd`. |
| **Every N tool calls** | Long sessions, incrementally | A per-session counter fires an improve every `COGNEE_AUTO_IMPROVE_EVERY` stored tool calls/stops (default **150**), so a long session bridges into the graph without waiting for the end.                                                                                      |
| **On idle**            | The session goes quiet       | A background idle watcher polls every `COGNEE_IDLE_POLL` seconds and fires an improve after `COGNEE_IDLE_THRESHOLD` seconds of inactivity, then waits at least `COGNEE_IMPROVE_COOLDOWN` seconds before the next idle run.                                                     |

<Note>
  Overlapping triggers are safe. A per-session improve **lock** on the server serializes concurrent runs, and unchanged session content **dedups server-side by content hash** — so a repeat improve over content that hasn't changed is a cheap no-op, not duplicated work.
</Note>

### Configuration

All triggers are tuned through environment variables read by the plugin. The defaults are chosen so distillation stays out of your way; you rarely need to change them.

| Variable                        | Default                             | What it controls                                                                                                                                                                                   |
| ------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `COGNEE_AUTO_IMPROVE_EVERY`     | `150`                               | Stored tool calls/stops between automatic mid-session improves                                                                                                                                     |
| `COGNEE_IDLE_THRESHOLD`         | `60`                                | Seconds of inactivity before an idle improve fires                                                                                                                                                 |
| `COGNEE_IMPROVE_COOLDOWN`       | `600`                               | Minimum seconds between idle improve runs                                                                                                                                                          |
| `COGNEE_IDLE_POLL`              | `10`                                | How often the idle watcher checks for inactivity                                                                                                                                                   |
| `COGNEE_IMPROVE_SUBMIT_TIMEOUT` | `420` (Claude Code) / `180` (Codex) | Read timeout for the improve POST (distillation runs inside the request). The Claude Code plugin raises this to `420` at startup to clear cognee's LLM-retry floor; Codex uses the `180` fallback. |
| `COGNEE_IDLE_DISABLED`          | *unset*                             | Set to `1` / `true` to turn off the idle-watcher trigger entirely                                                                                                                                  |

<Tip>
  The plugin READMEs document additional advanced knobs — timing (poll deadlines, busy-retry intervals for a held session lock), session-sync retries, and the update-notification variables (`COGNEE_UPDATE_CHECK`, `COGNEE_UPDATE_CHECK_INTERVAL`). You almost never need them — reach for the table above first.
</Tip>

### Turning it down or off

* **Stop idle-triggered improves:** set `COGNEE_IDLE_DISABLED=1` before launching the agent. Session-end and per-turn improves still run.
* **Reduce mid-session improves:** raise `COGNEE_AUTO_IMPROVE_EVERY` to a large value so the per-turn trigger effectively never fires within a session.
* **Session-end distillation always runs** when the plugin is active — it's how a finished session reaches permanent memory.

### Confirming it happened

* **Cloud UI:** the **Self-improvement** card at the top of a session on the [Sessions page](/cognee-cloud/ui/sessions#self-improvement) shows the status of the last graph enrichment and the dataset it wrote to.
* **Plugin hook log:** each automatic run emits an `improve_fired` event you can grep for when debugging (in local SDK mode, where the plugin calls the library directly instead of the HTTP endpoint, look for `auto_improve_fired` instead).
* **`improve-unsupported.json` marker:** if this file appears in the plugin's shared state directory (24h TTL), the server rejected the improve endpoint and the plugin fell back to the legacy `remember` bridge for that window — a signal the server predates session-aware improve.