Session Distillation

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), the Self-Improvement Quickstart, and the improve operation.

Improve

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

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.

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

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

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.

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

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.

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 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.

Getting Started

Local UI

Navigating the UI

Cloud Functionality

Agent Integrations

Connections

Reference

Improve

Request body

Error responses

Automatic distillation for agent sessions

Configuration

Turning it down or off

Confirming it happened

​Improve

​Request body

​Error responses

​Automatic distillation for agent sessions

​Configuration

​Turning it down or off

​Confirming it happened

Improve

Request body

Error responses

Automatic distillation for agent sessions

Configuration

Turning it down or off

Confirming it happened