Agent Session Traces

Record what a decorated function did on each call, and recall those traces later

A minimal guide to agent session traces: decorate a function with cognee.agent_memory(save_session_traces=True), call it a couple of times, then recall what happened — including calls that raised an error.

Before You Start

• Complete Quickstart to understand basic operations
• Ensure you have LLM Providers configured — the initial remember() call needs one, even though tracing itself does not
• Read Persistent Memory Across Sessions first — this guide assumes you already know what session_id is and how it works

Code in Action

import asyncio

import cognee

SESSION_ID = "agent_demo"


@cognee.agent_memory(
    session_id=SESSION_ID,
    with_memory=False,
    with_session_memory=False,
    save_session_traces=True,
    session_trace_summary=False,
)
async def lookup_teammate_status(name: str) -> str:
    statuses = {"Alice": "available"}
    if name not in statuses:
        raise ValueError(f"No status on file for {name!r}")
    return statuses[name]


async def main():
    await cognee.remember(
        "Alice and Bob are teammates.",
        self_improvement=False,
    )

    status = await lookup_teammate_status("Alice")
    print(f"Alice's status: {status}")

    try:
        await lookup_teammate_status("Bob")
    except ValueError as error:
        print(f"Expected error for Bob: {error}")

    alice_traces = await cognee.recall(
        query_text="Alice",
        session_id=SESSION_ID,
        scope="trace",
    )
    for trace in alice_traces:
        print(
            f"[{trace.status}] {trace.origin_function}({trace.method_params}) "
            f"-> {trace.method_return_value or trace.error_message}"
        )

    bob_traces = await cognee.recall(
        query_text="Bob",
        session_id=SESSION_ID,
        scope="trace",
    )
    for trace in bob_traces:
        print(
            f"[{trace.status}] {trace.origin_function}({trace.method_params}) "
            f"-> {trace.method_return_value or trace.error_message}"
        )

    other_session_traces = await cognee.recall(
        query_text="Alice",
        session_id="a_different_session",
        scope="trace",
    )
    print(f"Traces found in a fresh session: {len(other_session_traces)}")


if __name__ == "__main__":
    asyncio.run(main())

What Just Happened

Step 1: Bootstrap Cognee and Decorate the Function

@cognee.agent_memory(
    session_id=SESSION_ID,
    with_memory=False,
    with_session_memory=False,
    save_session_traces=True,
    session_trace_summary=False,
)
async def lookup_teammate_status(name: str) -> str:
    statuses = {"Alice": "available"}
    if name not in statuses:
        raise ValueError(f"No status on file for {name!r}")
    return statuses[name]

await cognee.remember(
    "Alice and Bob are teammates.",
    self_improvement=False,
)

The remember() call runs once, before anything else, purely to make sure Cognee’s database and default user exist — the decorated function itself never reads this fact back, because with_memory=False. save_session_traces=True is what turns tracing on — without it, the decorator would still run the function but record nothing. with_memory=False and with_session_memory=False keep this example focused on traces alone: no graph memory lookup, no conversation-history retrieval, just “what happened when this function ran.” session_trace_summary=False skips the LLM-generated summary Cognee would otherwise attempt for each trace.

Step 2: Call It Once Successfully

status = await lookup_teammate_status("Alice")
print(f"Alice's status: {status}")

"Alice" is in statuses, so the function returns normally. Behind the scenes, the decorator records this call’s trace with status="success" and the returned value — automatically, without you constructing any trace object yourself.

Step 3: Call It Again With an Error

try:
    await lookup_teammate_status("Bob")
except ValueError as error:
    print(f"Expected error for Bob: {error}")

"Bob" is not in statuses, so the function raises ValueError. The decorator still records this call’s trace — this time with status="error" and the error message — then re-raises the exception, which is why the call is wrapped in try/except here.

Step 4: Recall the Traces

alice_traces = await cognee.recall(
    query_text="Alice",
    session_id=SESSION_ID,
    scope="trace",
)

scope="trace" tells recall() to search recorded traces instead of the knowledge graph or conversation history. Trace search matches by keyword across each trace’s function name, parameters, return value, and error message — query_text="Alice" matches the first call because "Alice" appears in its parameters. Each result exposes origin_function, status, method_params, method_return_value, and error_message, so both the successful call and the failed one are fully inspectable.

Step 5: Confirm Isolation Between Sessions

other_session_traces = await cognee.recall(
    query_text="Alice",
    session_id="a_different_session",
    scope="trace",
)
print(f"Traces found in a fresh session: {len(other_session_traces)}")

The same query against a session_id that never ran lookup_teammate_status returns an empty list — traces are scoped per session, just like the conversation history covered in Persistent Memory Across Sessions.

Traces vs. Other Session Concepts

Traces vs. conversation history

A trace records one function call — its inputs, status, and outcome. Conversation history (covered in Persistent Memory Across Sessions) records question/answer turns from recall(). Both live in the same session cache and are scoped by session_id, but they answer different questions: “what did this code do?” vs. “what did we discuss?”

Traces vs. memory_context and automatic guidance

This guide keeps with_memory=False and with_session_memory=False so the decorated function never reads graph memory or session history back — it only writes traces. Enabling those flags (as examples/guides/agent_memory_quickstart.py does) lets a decorated function use memory during its own execution, which is a separate, more advanced concept from recording that the call happened.

Traces vs. graph persistence

Traces recorded here stay in the session cache — this guide sets no option that writes them to the permanent knowledge graph. Two mechanisms bridge them: improve(session_ids=...), the on-demand path covered in Session Distillation, and persist_session_trace_after=N on the decorator itself, which memifies the recent traces into the graph every Nth trace (see Persistent Agent Memory Quickstart). Both are out of scope for this guide.

Persistent Memory Across Sessions

Learn the session-cache concept traces are built on

Persistent Agent Memory Quickstart

See traces combined with session memory and graph memory