Skip to main content
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 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 as an AgentTrace in the same dataset. 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 as an AgentTrace node in the dataset. 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 the dataset the decorator reads from: External knowledge — process documents ahead of time:
  1. Add source data with cognee.add(...).
  2. Build memory with cognee.cognify(...).
Agent self-memory from traces — enable save_traces=True:
  • After each call, the decorator writes an AgentTrace record directly as a graph node in the dataset. No add() or cognify() step is needed.
  • Subsequent calls can retrieve those prior traces as memory, so the agent builds context from its own execution history.
Both paths write to the same dataset and can be combined. If you pass dataset_name, it must match the dataset where memory exists. When access control is enabled, the user needs both read and write access to that dataset.

​
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.
  • 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.
  • dataset_name (str, optional): Dataset to retrieve memory from.
  • 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