Observational Memory

The agent maintains conversation context through an observational memory system. Instead of a flat chat log, memory is structured into observations, reflections, and explicit compaction — keeping the agent effective over long sessions.

Memory Panel

The memory popover in the agent header shows live statistics:

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

Every interaction produces an observation — a structured record with:

  • Content — what happened (message sent, tool executed, file read/written, error)
  • Relevance — low, medium, high, or critical
  • Timestamp — when it occurred
  • Pending flag — whether it's been committed to the reflection system

The protocol tracks both committed and pending observations with token counts.

Reflections

The agent periodically generates reflections — higher-level summaries that compress multiple observations:

Observations: "Read src/auth/login.ts", "Read src/auth/middleware.ts", "User asked about auth"
      ↓
Reflection: "Exploring authentication flow. Key files: login.ts, middleware.ts."

Each reflection includes supportingObservationIds — the observations it was derived from.

Compaction

Compaction frees context space by summarizing older observations into reflections. It's automatic and preserves key information.

The memory protocol tracks:

  • Thresholds — token limits for observation, compaction, and reflection triggers
  • Progress — tokens consumed since the last observation boundary and since last compaction
  • Phases — observing → compacting → reflecting → pruning

Manual compaction is available via POST /api/sessions/:id/compact.

Memory Modes

ModeWhen
ActiveAgent is running and observing interactions
PassiveIdle, not actively collecting observations

Recall

When precise details from a compacted observation are needed, the agent uses recall to recover the original source context. Compaction never loses information — it's always recoverable.

Memory Details

Full memory details are available via the details dialog in the popover, or via API:

GET /api/sessions/:id/memory          → status (mode, phase, counts, thresholds, progress)
GET /api/sessions/:id/memory/details  → observations + reflections with content
POST /api/sessions/:id/compact         → trigger manual compaction

Best Practices

  • Long sessions are fine — automatic compaction handles token budgets
  • Manual compact when you feel the agent is losing focus on older context
  • Fork & Compact large sessions into focused new sessions for new topics
  • Check memory via the popover to see how much context is in use

Next Steps