> ## 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.
# Agent Memory Decorator
> Attach Cognee memory retrieval to an async agent function at the function boundary
`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()`](/guides/low-level-llm), 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](/guides/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(...)`](/core-concepts/main-operations/remember).
2. Optionally deepen that dataset later with [`cognee.improve(...)`](/core-concepts/main-operations/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](/core-concepts/multi-user-mode/multi-user-mode-overview) 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.
```python theme={null}
@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?")
```
```python theme={null}
@cognee.agent_memory(
memory_query_from_method="question",
dataset_name="agent_memory_demo",
)
async def answer(question: str) -> str:
return await ask_llm(question)
```
* **`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.
End-to-end working example
Scope memory retrieval to the right dataset
Direct retrieval without a decorator
`LLMGateway` for direct model calls