> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.rightbrain.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.rightbrain.ai/_mcp/server.

# Memory & context

> Choose a Rightbrain agent memory strategy, manage context pressure, and interpret context and compaction telemetry.

An agent's context is the working material available to its model during a run. It can include the agent instruction, the current message, conversation history, files, tool declarations and results, and activated [Skills](/docs/concepts/skills).

Context affects behavior, latency, and cost. Memory controls how conversation history is retained as a session grows.

## What enters context

Different sources enter at different times:

* **Instructions** define the agent's standing goal and decision boundaries.
* **Messages and history** carry the current request and prior session turns.
* **Tools** contribute declarations that tell the model what it may call. Tool results add data after a call.
* **Skills** contribute short discovery metadata first. Their instructions and reference files load only when activated.
* **Files** include uploaded inputs and run-scoped files produced by tools.

Expose only the tools and Skills the agent needs. A larger tool surface increases declaration tokens and makes tool selection less precise. Put stable transformations behind [Tasks](/docs/concepts/tasks), and use an output formatter Task when the final result needs a typed contract.

## Memory strategies

Memory strategy is part of an [agent revision](/docs/production/revisions).

| Strategy         | Retention                                                       | Use when                                                                            |
| ---------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `null` / omitted | Loads the available session history without a retention policy. | Sessions are short and bounded.                                                     |
| `sliding_window` | Keeps the most recent `max_events`.                             | Recent turns matter more than older detail.                                         |
| `compaction`     | Summarizes older events while retaining recent events verbatim. | Long-running sessions must preserve earlier decisions without carrying every event. |

`max_turns` is separate from memory. It limits how many runs may continue one session; memory strategy controls the history loaded when each run starts.

## Compaction

Compaction can run on a cadence and under token pressure. Its configuration includes:

| Field                   | Effect                                                                                      |
| ----------------------- | ------------------------------------------------------------------------------------------- |
| `compaction_interval`   | Runs cadence-based compaction after a configured number of invocations.                     |
| `overlap_size`          | Keeps recent events verbatim alongside the summary.                                         |
| `token_threshold_ratio` | Overrides the token-pressure threshold as a fraction of the effective model context window. |
| `event_retention_size`  | Controls how many raw events remain when token-pressure compaction runs.                    |

When a fallback model is configured, the effective context window uses the smaller supported window so a failover can continue with the retained history.

Compaction is another model operation. It can add tokens, credits, and latency, which are reported separately from foreground reasoning.

## Interpret context telemetry

Agent run detail exposes `context_usage`:

* Provider totals report observed token usage.
* The estimated breakdown attributes input to instructions, messages, history, files, Tasks, Skills, MCP tools, Integrations, and registered tools.
* Runtime-component detail shows which resources were registered and what they contributed.
* Metadata indicates whether provider usage was complete or estimation was truncated.

The breakdown is attribution, not a context-window meter. An agent may call its model several times in one run, so cumulative run input cannot be subtracted from one model context window to calculate remaining capacity.

## Observe compaction

Compaction is visible in the same evidence as the rest of a run:

* SSE and retained run events include `memory_compaction` events.
* `phase_timings` records compaction duration and trigger metadata.
* Model usage separates `reasoning` from `memory_compaction`.
* Token and credit reports show the operational cost over time.

Use [Observability & audit](/docs/production/observability) to inspect this evidence, and [Run agents via API](/docs/api/run-agents) for the event contract.

## Related

#### [Agents](/docs/concepts/agents)

Choose tools, execution mode, turn limits, and session behavior.

#### [Skills](/docs/concepts/skills)

Keep reusable guidance available through progressive disclosure.

#### [Observability & audit](/docs/production/observability)

Inspect context attribution, phases, tokens, and credits.

#### [Fallbacks & reliability](/docs/production/fallbacks)

Configure the alternate model whose context limit also applies.