Teach an Agent From Its Own Tool Traces

Your coding agent has already hit the errors that matter — a test run that failed on a missing dependency, a lint pass that flagged an unused import — and the next run will hit them again unless something remembers what happened. This demo turns that raw tool-call history into guidance the agent can be handed before it starts.

What You’ll Build

Five tool-call traces from one agent working a task — a failing pytest run, a uv sync that fixed it, a passing test run, a file read, and a lint failure — are stored one by one into a session as TraceEntry records. Cognee extracts agent-profile lessons from them as they accumulate, then distillation rewrites the accepted lessons into markdown documents and cognifies them into the dataset, so they outlive the session. The payoff is the last act: recall() returns those lessons as a read-only context block for the agent-profile question “what should I know before running tests in this repo?”, while the same query under the QA profile returns nothing and the raw traces are still retrievable as evidence. The complete runnable script is examples/demos/sessions/agentic_session_context_demo.py — this page walks through its key moments rather than reproducing it.

Features in Play

Agent Session Traces — each tool call becomes a TraceEntry in the session, carrying its parameters, return value, or error message
Sessions and Caching — the session cache holds both the raw traces and the agent-profile guidance extracted from them
Session Distillation — rewrites the accepted guidance into markdown documents and cognifies them into the dataset
Recall — reads the guidance back with scope and context_profile, and the raw traces alongside it as evidence

Before You Start

Complete Quickstart to understand basic operations
Ensure you have LLM Providers configured — lesson extraction and distillation are LLM-backed, so the full run needs one; --offline skips both
The script sets its own environment before importing cognee: CACHING=true, CACHE_BACKEND=fs, AUTO_FEEDBACK=true, ENABLE_BACKEND_ACCESS_CONTROL=false, and LOG_LEVEL=ERROR unless you already set it. The filesystem cache adapter is what stores the session
Run it from a checkout of the cognee repo; it writes agentic_session_context_demo_output.json into the working directory with every snapshot the run took
The run starts by pruning data and system metadata and deleting any previous agentic_demo_session, so point it at a scratch instance rather than memory you want to keep

How It Works

Stage 1: Script the Agent’s Tool Traces

TRACES = [
    {
        "origin_function": "run_tests",
        "status": "error",
        "method_params": {"command": "pytest -q"},
        "error_message": "ModuleNotFoundError: No module named 'dotenv'",
    },
    {
        "origin_function": "run_command",
        "status": "success",
        "method_params": {"command": "uv sync"},
        "method_return_value": "Installed 42 packages in 1.2s",
    },
    {
        "origin_function": "run_tests",
        "status": "success",
        "method_params": {"command": "uv run pytest -q"},
        "method_return_value": "188 passed in 4.1s",
    },
    {
        "origin_function": "read_file",
        "status": "success",
        "method_params": {"path": "pyproject.toml"},
        "method_return_value": "[project] name = 'demo'  # managed with uv",
    },
    {
        "origin_function": "run_lint",
        "status": "error",
        "method_params": {"command": "uv run ruff check ."},
        "error_message": "F401 'os' imported but unused",
    },
]

These five dictionaries stand in for what a real agent’s tool layer would emit: the tool name, whether the call succeeded, its input, and either the return value or the error. The story they tell — bare pytest fails, uv sync fixes it, uv run pytest passes — is the raw material a lesson can be drawn from, and nothing in the run tells the extractor what that lesson is.

Stage 2: Store Each Trace and Extract as You Go

    for index, trace in enumerate(TRACES, start=1):
        before = await snapshot(user)
        await cognee.remember(
            TraceEntry(**trace),
            dataset_name=DATASET_NAME,
            session_id=SESSION_ID,
            self_improvement=False,
            user=user,
        )
        if drive_periodic_extraction:
            await extract_pending_agent_context(
                session_manager=get_session_manager(),
                user_id=str(user.id),
                session_id=SESSION_ID,
                min_new_traces=DEMO_TRACE_EXTRACTION_INTERVAL,
                overlap=DEMO_TRACE_EXTRACTION_OVERLAP,
            )

remember() with a session_id writes each TraceEntry to the session cache rather than the graph. The trace-write path already runs the periodic extraction pass for you on its own interval; the demo calls it directly with DEMO_TRACE_EXTRACTION_INTERVAL = 2 and DEMO_TRACE_EXTRACTION_OVERLAP = 1 so a five-trace run actually shows the pass firing — after traces 2 and 4 — instead of only at the end. The snapshot taken before and after each trace is what lets the run print whether that trace advanced the processed-trace watermark.

Stage 3: Flush the Tail and Distill Into the Graph

        before_flush = await snapshot(user)
        touched_ids = await extract_pending_agent_context(
            session_manager=get_session_manager(),
            user_id=str(user.id),
            session_id=SESSION_ID,
            min_new_traces=1,
        )
        distillation_input = await snapshot(user)
        result = await distill_session(SESSION_ID, dataset=DATASET_NAME, user=user)

Traces 2 and 4 triggered extraction, which leaves the fifth trace — the lint failure — pending. Dropping min_new_traces to 1 forces that tail through, so distillation sees the complete set of lessons. distill_session() then rewrites the accepted guidance into markdown documents and cognifies them into the demo dataset, which is what makes the lessons outlast this session. The script reaches it through its internal module path; in your own code call it as cognee.session.distill_session(), or let improve(session_ids=[...]) run the same distillation as part of a wider pass.

Stage 4: Recall Guidance by Profile

    agent_ctx = await cognee.recall(
        "what should I know before running tests in this repo?",
        scope=["session_context"],
        context_profile="agent",
        session_id=SESSION_ID,
        only_context=True,
        user=user,
    )
    qa_ctx = await cognee.recall(
        "what should I know before running tests in this repo?",
        scope=["session_context"],
        context_profile="qa",
        session_id=SESSION_ID,
        only_context=True,
        user=user,
    )
    raw_traces = await cognee.recall(
        "dotenv",
        scope=["trace"],
        session_id=SESSION_ID,
        only_context=True,
        user=user,
    )

Three recalls against the same session show what the profile does. scope=["session_context"] with context_profile="agent" returns the distilled guidance block, ready to prepend to the next agent run; the identical query under context_profile="qa" comes back empty, because this demo wrote no QA-profile entries. scope=["trace"] reaches past the lessons to the raw evidence they were drawn from, so a lesson about dotenv can be traced back to the call that failed. only_context=True keeps all three as context reads rather than completions.

Stage 5: Prove the Reads Changed Nothing

async def served_state(user) -> dict:
    """Map of agent-lesson id -> last_served_at, to prove recall does not stamp anything."""
    rows = await get_session_manager().get_session_context_entries(
        user_id=str(user.id), session_id=SESSION_ID
    )
    return {
        row.get("id"): row.get("last_served_at")
        for row in rows
        if row.get("context_profile", "qa") == "agent"
    }

The recall act captures this map of agent-lesson id to last_served_at before and after the three queries and compares them. Serving guidance to an agent is a read: nothing is stamped, no entry is aged, and the run prints the comparison so you do not have to take that on faith.

Run It

uv run python examples/demos/sessions/agentic_session_context_demo.py

The run narrates itself on stderr in three acts. Act 1 prints each trace — tool, status, input, and output or error — followed by the session memory after it, with every entry labeled by section, content, confidence, and whether it came from a live trace or a batch LLM pass; traces 2 and 4 are marked as the first and second batch context extraction. Act 2 prints the pending-trace count before and after the final flush, how many context entries it touched, the session memory that distillation consumed, and then the status and full text of each cognified document. Act 3 prints the agent-profile guidance block, the QA-profile result count, the number of raw trace results, and whether recall performed any writes. The run finishes by writing agentic_session_context_demo_output.json and printing its path. Exact lesson wording varies by model.

Offline Mode

uv run python examples/demos/sessions/agentic_session_context_demo.py --offline

--offline runs the same trace capture and recall without any LLM calls: the periodic extraction passes are skipped, Act 2 is skipped entirely, and the only session-memory entries that appear are the deterministic ones written when a failing trace is stored. Use it to see the capture-and-recall shape of the demo without a configured provider — and, in the full run, as the baseline that shows which entries the LLM added.

Agent Session Traces

Recording tool calls as traces and recalling them later.

Session Distillation

How gated session guidance becomes permanent lessons in the graph.

Sessions and Caching

The session cache behind traces, guidance, and the fs backend this demo uses.

Watch a Session Become Permanent Memory

The same distillation loop, driven by a conversation instead of tool traces.

Getting Started

Core Concepts

Setup Configuration

Guides

Examples

CLI

Rust SDK

TypeScript SDK

OSS

Teach an Agent From Its Own Tool Traces

What You’ll Build

Features in Play

Before You Start

How It Works

Stage 1: Script the Agent’s Tool Traces

Stage 2: Store Each Trace and Extract as You Go

Stage 3: Flush the Tail and Distill Into the Graph

Stage 4: Recall Guidance by Profile

Stage 5: Prove the Reads Changed Nothing

Run It

Offline Mode

Agent Session Traces

Session Distillation

Sessions and Caching

Watch a Session Become Permanent Memory

​What You’ll Build

​Features in Play

​Before You Start

​How It Works

​Stage 1: Script the Agent’s Tool Traces

​Stage 2: Store Each Trace and Extract as You Go

​Stage 3: Flush the Tail and Distill Into the Graph

​Stage 4: Recall Guidance by Profile

​Stage 5: Prove the Reads Changed Nothing

​Run It

​Offline Mode

Agent Session Traces

Session Distillation

Sessions and Caching

Watch a Session Become Permanent Memory

What You’ll Build

Features in Play

Before You Start

How It Works

Stage 1: Script the Agent’s Tool Traces

Stage 2: Store Each Trace and Extract as You Go

Stage 3: Flush the Tail and Distill Into the Graph

Stage 4: Recall Guidance by Profile

Stage 5: Prove the Reads Changed Nothing

Run It

Offline Mode