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

# improve()

> Enrich an existing graph and bridge session memory with the v1.0 API

# cognee.improve()

```python theme={null}
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](/core-concepts/main-operations/improve).

## Parameters

<ParamField path="dataset" type="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.
</ParamField>

<ParamField path="run_in_background" type="bool" default="False">
  Starts the improvement pipeline asynchronously.
</ParamField>

<ParamField path="node_name" type="Optional[List[str]]" default="None">
  Restricts improvement to specific named entities or node sets.
</ParamField>

<ParamField path="session_ids" type="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.
</ParamField>

<ParamField path="build_global_context_index" type="bool" default="False">
  Builds the [global context index](/core-concepts/further-concepts/global-context-index) after enrichment. This is skipped when `run_in_background=True`.
</ParamField>

<ParamField path="build_truth_subspace" type="bool" default="False">
  Opt-in flag that builds the [truth subspace](/guides/truth-subspace-reranking) 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.
</ParamField>

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

<Accordion title="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:

  ```text theme={null}
  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](/core-concepts/multi-user-mode/permissions-system/acl).
  * **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**.
</Accordion>

## Examples

```python theme={null}
import cognee

await cognee.improve(
    dataset="product_docs",
    session_ids=["support_chat_7"],
)
```

```python theme={null}
await cognee.improve(
    dataset="product_docs",
    session_ids=["support_chat_7"],
    build_truth_subspace=True,
)
```

```python theme={null}
await cognee.improve(
    dataset="product_docs",
    build_global_context_index=True,
)
```

## Related

See also [Global Context Index](/core-concepts/further-concepts/global-context-index) for how to use the generated summaries during search, and [memify()](/python-api/memify) if you need lower-level control over the legacy enrichment pipeline.