Session Brain

The BrainManager class manages session-scoped context through a brain.md file stored in .voyager/brain.md.

Lifecycle

session_start  → load()          → inject into system context
turn_end       → update()        → append loop status, observations
session_compact → compact()      → summarize and prune stale entries
session_end    → persist()       → write final state to disk

Interface

interface BrainManager {
  load(): BrainState
  update(entry: BrainEntry): void
  compact(): void
  persist(): void
  getStatus(): BrainStatus
}
 
interface BrainState {
  content: string
  lastUpdated: Date
  entryCount: number
  compacted: boolean
}
 
interface BrainEntry {
  type: 'observation' | 'decision' | 'loop_status' | 'reflection'
  content: string
  timestamp: Date
  source?: string
}
 
interface BrainStatus {
  loaded: boolean
  path: string
  sizeBytes: number
  entryCount: number
  lastCompaction: Date | null
}

Key Methods

`load()`

Reads .voyager/brain.md into memory. Returns a BrainState object. If the file doesn't exist, returns an empty state with compacted: false.

`update(entry)`

Appends a BrainEntry to the in-memory brain. Each entry is formatted as a markdown section with type, timestamp, and content. Called on turn_end to capture loop status and observations.

`compact()`

Summarizes accumulated entries, prunes stale or redundant observations, and rewrites the brain file. Triggered by session_compact events to keep context window usage efficient.

`persist()`

Writes the current brain state to .voyager/brain.md. Called at session end to ensure no context is lost.

⚠️

The brain file is the single source of truth for session context. External edits to .voyager/brain.md while a session is active may cause inconsistencies. Always go through the BrainManager API.

Storage Format

The brain file uses standard markdown with timestamped sections:

# Nity Brain — Session Context
 
## Observation — 2026-03-21T14:30:00Z
Task: Implement auth flow
Decision: Chose JWT over sessions for stateless API
Outcome: Tests passing, 3 iterations
 
## Loop Status — 2026-03-21T14:35:00Z
Iteration: 4/10
Circuit breaker: CLOSED
Progress: Steady — 2 files modified

Overview Episode Recording