Skip to main content

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.

cognee.agent_memory is a decorator that adds two capabilities to an async agent function: it searches Cognee memory before the function runs and makes the retrieved context available to model calls inside it, and it records the function’s output as a session-backed trace that future calls can retrieve as memory.

​
How It Works

In agent systems, agents and subagents are often just async functions — they receive input, call an LLM, and return a result. The cognee.agent_memory decorator is designed for exactly this pattern. Before the function executes, the decorator searches the configured dataset and provides the result as context inside the function. The function uses that context in its model call — typically by including it in the system prompt. After the function returns, if save_traces=True, the inputs, outputs, and retrieved context are saved into the session-backed trace store for that agent flow. This means the agent’s own execution history becomes searchable memory for future calls.

​
Making the Model Call

The decorator does not call the LLM — the function does. When the function calls LLMGateway.acreate_structured_output(), the gateway automatically prepends the retrieved memory to the text input. No extra code is needed inside the function — calling LLMGateway normally is sufficient. See Agent Memory Quickstart for a working example.

​
When to Use It

The cognee.agent_memory decorator does two things at the function boundary:
  • Retrieval (with_memory=True): before the function runs, Cognee fetches relevant context from the dataset and makes it available to the model call.
  • Trace persistence (save_traces=True): after the function returns, Cognee stores the inputs, outputs, and memory context in the session-backed trace store. Later calls can retrieve those traces as memory, so the agent accumulates context from its own execution history.
Apply it to an agent or subagent function when that function should consistently run with memory, record its executions, or both — without adding that logic inside the function body each time.

​
Memory Sources

There are two ways to populate memory that the decorator can read from: External knowledge — process documents ahead of time:
  1. Store source data with cognee.remember(...).
  2. Optionally deepen that dataset later with cognee.improve(...).
Agent self-memory from traces — enable save_traces=True:
  • After each call, the decorator writes a trace step into session-backed storage for that agent flow. No separate remember() call is needed for that trace persistence step.
  • Subsequent calls can retrieve those prior traces as memory, so the agent builds context from its own execution history.
These two memory sources can be combined: external knowledge comes from the dataset, while agent trace memory comes from the session-backed trace store. If you enable dataset-backed retrieval with with_memory=True, dataset_name must match the dataset where memory exists. When access control is enabled, the user needs both read and write access to that dataset. Session-backed trace memory, by contrast, is scoped by user and session_id.

​
Choosing a Retrieval Query

The decorator requires one of two retrieval query options:
  • memory_query_fixed — one stable query used on every call. Use this when the function always retrieves the same kind of context.
  • memory_query_from_method — takes the query from a named function parameter. Use this when retrieval should change with input.
@cognee.agent_memory(
    memory_query_fixed="What animal does the internal codename refer to?",
    dataset_name="agent_memory_demo",
)
async def answer_with_memory() -> str:
    return await ask_llm("What animal does the internal codename refer to?")
  • with_memory (bool, default True): Enables or disables retrieval.
  • with_session_memory (bool, default False): Includes recent session-trace feedback from the session-backed trace store in the injected memory context.
  • save_traces (bool, default False): Persists execution traces for decorated calls.
  • memory_query_fixed (str, optional): Fixed retrieval query used on every call.
  • memory_query_from_method (str, optional): Name of the function parameter to use as the retrieval query.
  • memory_system_prompt (str, optional): Shapes how retrieved memory is interpreted by the downstream model call.
  • memory_top_k (int, default 5): Number of memory results to retrieve.
  • session_memory_last_n (int, default 5): Number of recent session-trace feedback entries to include when with_session_memory=True.
  • session_id (str, optional): Session key used for session-backed trace retrieval and trace persistence.
  • dataset_name (str, optional): Dataset to retrieve memory from when with_memory=True.
  • user (User, optional): User context for retrieval. Required for multi-user or background-job flows.
The decorated function must be async. memory_query_fixed and memory_query_from_method are mutually exclusive — use exactly one.

Agent Memory Quickstart

End-to-end working example

Datasets

Scope memory retrieval to the right dataset

Search Basics

Direct retrieval without a decorator

Low-Level LLM

LLMGateway for direct model calls