Agent

DocsAgentObservational Memory

How the agent structures conversation context — observations, reflections, compaction, and recall.

Observational Memory

The agent keeps long conversations useful with observational memory. Rather than relying only on a flat chat transcript, it organizes important work into observations and summaries, then makes room for the next part of the conversation when needed.

Memory Panel

The memory popover in the agent header shows the current memory state and how much context is in use:

Session memory
Active · Observing
Committed obs
214
12.4k tokens
Pending obs
33
1.8k tokens
Reflections
18
2.1k tokens
In flight
obs · cmp
Next observation12.4k/15.0k · 82%
Next compaction8.7k/30.0k · 29%
Next reflection1.8k/8.0k · 22%

Observations and Reflections

An observation records something relevant from your work, such as a request, a file change, a tool result, or an error. Observations can have different levels of relevance so important decisions remain available longer.

A reflection is a higher-level summary built from several observations. For example, a series of file reads and an authentication question may become a concise summary of the authentication flow being explored.

Compaction

Compaction summarizes older conversation context so the agent can continue working within its context limit. It is automatic and is designed to preserve the information needed to continue the task. You can also use Compact or Fork & Compact from the session controls when a conversation has grown large or you want to begin a focused thread.

Choosing When to Compact

  • Use compaction at a natural handoff, such as after finishing a feature or verification pass.
  • Use it during a long active task when older conversation details are no longer needed but recent context still matters.
  • Fork and compact when changing topics and you want a clean session with the useful background carried forward.

Compaction waits for the current agent turn to finish, so it does not interrupt an in-progress response. If the agent is still busy, the request is deferred until it is safe to run.

Recall

When a compacted detail becomes important again, the agent can recall the original context. Summaries help keep the conversation efficient without making earlier work inaccessible.

Troubleshooting Memory

  • The agent seems to lose focus: open the memory popover and compact the session, or start a focused session with Fork & Compact.
  • Compaction is delayed: let the current response finish and try again; compaction does not interrupt active work.
  • The session feels too large: split unrelated work into separate sessions and compact completed phases.
  • Context is still missing: restate the key requirement or point the agent to the relevant file; this gives it a reliable starting point for the next turn.

Best Practices

  • Long sessions are fine — automatic compaction manages context over time.
  • Compact deliberately when you finish a phase or notice the agent losing focus on older context.
  • Fork & Compact large sessions into focused conversations for new topics.
  • Check the memory popover to understand when context is getting full.

Next Steps