Skip to main content

What this example shows

A minimal guide to running a self-improvement pass over existing memory so session-only content becomes part of the permanent dataset. In the current API, this flow goes through improve(). Before you start:
  • Complete Quickstart to understand basic operations
  • Ensure you have LLM Providers configured
  • Have an existing dataset or be ready to create one with remember()
  • Have session content you want to bridge into permanent memory

What Self-Improvement Does

  • Works on an existing dataset instead of re-ingesting all source data
  • Bridges session memory into the permanent graph when you pass session_ids
  • Distills accepted session guidance into session_learnings when the session has durable, gated lessons
  • Improves later recall() results with what the session taught, plus structures such as the global context index

Code in Action

Step 1: Store Permanent Memory

This creates durable graph memory in demo_dataset. Setting self_improvement=False keeps the example focused on the explicit improve() call later.

Step 2: Store Session-only Memory

This writes the Bohr fact into session memory under demo_session instead of immediately pushing it into the permanent graph.

Step 3: Recall Before Improvement

At this point, the permanent dataset may not yet know about the session-only Bohr fact, so the recall result can be empty or incomplete.

Step 4: Bridge and Enrich with Improve

This runs the improvement pass for demo_dataset, bridging the gap between short-term (session) memory and long term (permanent) memory by pulling in the specified session and enriching the graph. If the session accumulated durable guidance during conversation, the same pass can also distill accepted lessons into session_learnings.

Step 5: Recall After Improvement

After improve() finishes, the permanent dataset can answer from the newly bridged session content.

What Changed in Your Graph

After improve() completes, the dataset can include:
  • Session-derived content from demo_session persisted into the permanent graph
  • Distilled session-learning documents tagged as session_learnings, when the session contains accepted guidance
  • Better downstream recall for facts that were previously only available in the session
  • dataset (str, default: "main_dataset") — the dataset to improve.
  • session_ids (Optional[List[str]]) — session IDs whose cached memory should be bridged into the permanent graph.
  • run_in_background (bool, default: False) — if True, returns immediately and runs improvement asynchronously.
  • node_name (Optional[List[str]]) — deprecated and ignored unless you also pass the deprecated custom tasks; passing it raises a FutureWarning.
  • feedback_alpha (float, default depends on runtime config) — controls how strongly session feedback affects graph weighting when feedback data exists.

Customizing Tasks (Deprecated)

extraction_tasks and enrichment_tasks are deprecated and will be removed in the next release; passing them raises a FutureWarning. They run as an extra custom_tasks stage after the built-in stages. To run your own tasks over a dataset, use run_custom_pipeline() instead.

What Happens Under the Hood

When session_ids are provided, the improvement flow can:
  • apply feedback-based weighting updates to graph elements used during retrieval
  • persist session memory into the permanent graph
  • persist agent trace steps and distill accepted session guidance into session_learnings

Additional Information

  • Runnable guide script available on our GitHub
  • An advanced end-to-end script touring the whole memory API — remember(), recall(), improve(), and forget(), including session-aware recall() — is also on our GitHub. Unlike the examples above, it leaves self_improvement at its default (True), so its session remember() calls also bridge into the permanent graph in the background; its explicit improve() call is still what enriches its scientists dataset, because the session calls default to main_dataset.
  • No visible change after improve() — make sure the session ID you pass actually contains session memory and that self_improvement=False did not leave the content unbridged.
  • Empty recall results after improvement — verify that you are recalling against the same dataset you improved.
  • Error: no graph data found — create the base dataset first with cognee.remember(..., dataset_name=...).
  • LLM errors — verify that your LLM provider is configured correctly. See LLM Providers.
  • Permission errors — the user must have write access to the target dataset. See Permissions.
This updated example uses one permanent fact and one session-only fact for demonstration. In practice, you can bridge larger sessions and enable opt-in stages such as build_truth_subspace on the same dataset.

Improve

Understand the current improvement workflow

Remember

Store permanent and session memory

Persistent Memory Across Sessions

Learn how session memory behaves before improvement