@@ -1,6 +1,6 @@
11 # Context Compression
22
3-Myses in Zoea Nova use a sliding window approach to manage LLM context size. Instead of sending the entire conversation history to the LLM on each turn, Myses send only recent messages plus the system prompt. This keeps inference fast while Myses retain access to older memories through search tools.
3+Zoea Nova uses a loop-based context composition strategy to keep LLM context small and stable. Instead of sending large conversation windows, each LLM request includes only three components: system prompt, a single prompt source, and the most recent tool loop. This guarantees bounded context size (typically 2-10 messages) while the full conversation history remains searchable.
44
55 ## Design
66
@@ -11,19 +11,26 @@ Without compression, Mysis context grows unbounded:
1111 - SpaceMolt gameplay involves frequent tool use (mining, trading, navigation)
1212 - Large contexts slow inference and increase costs
1313 - Eventually hits provider token limits
14+- Traditional sliding windows create orphaned tool results and broken message sequences
1415
15-### The Solution
16+### The Solution: Loop Slices
1617
1718 ```
1819 ┌─────────────────────────────────────────────────────┐
1920 │ LLM Context │
21+│ (Loop-Based Composition) │
2022 ├─────────────────────────────────────────────────────┤
21-│ System Prompt (always included) │
23+│ [1] System Prompt (always first) │
2224 ├─────────────────────────────────────────────────────┤
23-│ Recent Messages (last 20) │
24-│ - User messages │
25-│ - Assistant responses │
26-│ - Tool calls and results │
25+│ [2] Prompt Source (chosen by priority) │
26+│ • Commander direct message │
27+│ • Last commander broadcast │
28+│ • Last swarm broadcast │
29+│ • Synthetic nudge (if no prompts found) │
30+├─────────────────────────────────────────────────────┤
31+│ [3] Latest Tool Loop (if any) │
32+│ • Tool call message (assistant with tools) │
33+│ • All subsequent tool results │
2734 └─────────────────────────────────────────────────────┘
2835
2936 ┌─────────────────────────────────────────────────────┐
@@ -35,92 +42,158 @@ Without compression, Mysis context grows unbounded:
3542 └─────────────────────────────────────────────────────┘
3643 ```
3744
38-## Implementation
45+## Architecture
3946
40-### Constants
47+### Loop Slice Model
4148
42-```go
43-// internal/core/mysis.go
49+A **loop slice** is the atomic unit of tool interaction:
50+1. **Tool call message** (assistant role, contains `[TOOL_CALLS]` prefix)
51+2. **Tool results** (tool role, consecutive messages following the call)
4452
45-// MaxContextMessages limits how many recent messages to include in LLM context.
46-// Value chosen to cover ~2 server ticks worth of activity.
47-const MaxContextMessages = 20
53+The most recent loop slice is always included in context to maintain tool-calling coherence.
4854
49-// Snapshot tools are identified by prefix matching and explicit names:
50-// - Any tool starting with "get_" (e.g., get_ship, get_system, get_poi, get_nearby, get_cargo)
51-// - Explicit: zoea_swarm_status, zoea_list_myses
52-// When multiple results from the same snapshot tool appear in context,
53-// only the most recent one is kept to prevent redundant state data.
54-```
55+### Prompt Source Priority
5556
56-### Context Assembly
57+Prompt sources are user messages that drive Mysis behavior. Priority order:
5758
58-The `getContextMemories()` method assembles context for each LLM call:
59+1. **Commander direct message** (`source="direct"`) - Highest priority, always used if present
60+2. **Last commander broadcast** (`source="broadcast"`, `sender_id=""`) - Commander identified by empty sender_id
61+3. **Last swarm broadcast** (`source="broadcast"`, `sender_id!=""`) - Most recent broadcast from another Mysis
62+4. **Synthetic nudge** (generated, not stored) - Fallback when no prompt sources exist
5963
60-1. Fetch the N most recent memories from SQLite
61-2. Apply snapshot compaction to remove redundant state tool results
62-3. Fetch the system prompt (first system message for the Mysis)
63-4. If system prompt isn't already in compacted memories, prepend it
64-5. Return the assembled context
64+### Context Composition Algorithm
6565
6666 ```go
67+// internal/core/mysis.go:1374-1421
68+
6769 func (m *Mysis) getContextMemories() ([]*store.Memory, error) {
68- recent, err := m.store.GetRecentMemories(m.id, MaxContextMessages)
69- if err != nil {
70- return nil, err
70+ // Fetch recent memories from DB
71+ allMemories := GetRecentMemories(m.id, MaxContextMessages)
72+
73+ result := []
74+
75+ // Step 1: Add system prompt (if available)
76+ system := GetSystemMemory(m.id)
77+ if system != nil {
78+ result.append(system)
7179 }
80+
81+ // Step 2: Select prompt source by priority
82+ promptSource := selectPromptSource(allMemories)
83+ if promptSource == nil {
84+ // Generate synthetic nudge (not stored in DB)
85+ nudge := createEphemeralNudge()
86+ result.append(nudge)
87+ } else {
88+ result.append(promptSource)
89+ }
90+
91+ // Step 3: Extract latest tool loop
92+ toolLoop := extractLatestToolLoop(allMemories)
93+ result.append(toolLoop...)
94+
95+ return result
96+}
97+```
7298
73- // Apply compaction to remove redundant snapshot tool results
74- compacted := m.compactSnapshots(recent)
99+### Loop Extraction
75100
76- system, err := m.store.GetSystemMemory(m.id)
77- if err != nil {
78- // No system prompt - use compacted memories only
79- return compacted, nil
80- }
101+```go
102+// internal/core/mysis.go:1326-1372
81103
82- // Check if system prompt is already first
83- if len(compacted) > 0 && compacted[0].ID == system.ID {
84- return compacted, nil
104+func extractLatestToolLoop(memories []*store.Memory) []*store.Memory {
105+ // Scan backwards (newest first) for most recent tool call
106+ toolCallIdx := findLastToolCallMessage(memories)
107+ if toolCallIdx == -1 {
108+ return nil
85109 }
86-
87- // Prepend system prompt
88- result := make([]*store.Memory, 0, len(compacted)+1)
89- result = append(result, system)
90- result = append(result, compacted...)
91- return result, nil
110+
111+ // Collect tool call + all consecutive tool results
112+ loop := [memories[toolCallIdx]]
113+ for i := toolCallIdx + 1; i < len(memories); i++ {
114+ if memories[i].Role == "tool" {
115+ loop.append(memories[i])
116+ } else {
117+ break // Stop at first non-tool message
118+ }
119+ }
120+
121+ return loop
92122 }
93123 ```
94124
95-### Snapshot Compaction
125+Tool call messages are identified by:
126+- Role: `assistant`
127+- Content prefix: `[TOOL_CALLS]`
96128
97-The `compactSnapshots()` method removes redundant state tool results:
129+## Bounded Size Guarantees
98130
99-- Identifies tool results from snapshot tools (get_ship, get_system, etc.)
100-- Keeps only the most recent result for each snapshot tool
101-- Preserves all non-snapshot messages and tool results
102-- Maintains chronological order
131+The loop slice model provides strict size bounds:
103132
104-Snapshot detection relies on tool call IDs recorded in assistant `[TOOL_CALLS]` memories. Tool results are compacted only when their tool call ID resolves to a snapshot tool name, which avoids misclassifying non-snapshot results that happen to include similar fields.
133+| Component | Typical Size | Max Size |
134+|-----------|--------------|----------|
135+| System prompt | 1 message | 1 message |
136+| Prompt source | 1 message | 1 message |
137+| Tool loop | 1-8 messages | ~15 messages (1 call + max results) |
138+| **Total** | **3-10 messages** | **~17 messages** |
105139
106-This prevents state-heavy tools from crowding out conversation history while ensuring the latest state is always available.
140+This is dramatically smaller than traditional sliding windows (20-50 messages) and eliminates orphaned tool sequencing issues.
107141
108-### Store Methods
142+## Synthetic Nudge Behavior
143+
144+When no prompt source is found in recent memory, a synthetic nudge is generated:
109145
110146 ```go
111-// internal/store/memories.go
147+// internal/core/mysis.go:1398-1409
148+
149+nudgeContent := "Continue your mission. Check notifications and coordinate with the swarm."
150+nudgeMemory := &store.Memory{
151+ Role: "user",
152+ Source: "system",
153+ Content: nudgeContent,
154+ SenderID: "",
155+ CreatedAt: time.Now(),
156+}
157+```
112158
113-// GetSystemMemory retrieves the initial system prompt for a Mysis.
114-func (s *Store) GetSystemMemory(mysisID string) (*Memory, error)
159+**Key properties:**
160+- **NOT stored in database** - Ephemeral automation scaffolding
161+- **Counted for circuit breaker** - Nudge counter increments in ticker loop
162+- **Escalating prompts** - Content changes based on `nudgeFailCount`:
163+ - Attempt 1: "Continue your mission..." (gentle)
164+ - Attempt 2: "You need to respond..." (firm)
165+ - Attempt 3: "URGENT: Respond immediately..." (urgent)
166+ - After 3: Transition to idle state with error
115167
116-// GetRecentMemories retrieves the most recent N memories for a Mysis.
117-func (s *Store) GetRecentMemories(mysisID string, limit int) ([]*Memory, error)
168+### Nudge Circuit Breaker
118169
119-// SearchMemories searches memories by content text (case-sensitive).
120-func (s *Store) SearchMemories(mysisID, query string, limit int) ([]*Memory, error)
170+```go
171+// internal/core/mysis.go:1624-1641
172+
173+if shouldNudge(time.Now()) {
174+ nudgeFailCount++
175+
176+ if nudgeFailCount >= 3 {
177+ setIdle("Failed to respond after 3 nudges")
178+ return
179+ }
180+
181+ nudgeCh <- struct{}{} // Trigger nudge processing
182+}
183+```
121184
122-// SearchBroadcasts searches broadcast messages by content text (case-sensitive).
123-func (s *Store) SearchBroadcasts(query string, limit int) ([]*BroadcastMessage, error)
185+**Counter reset:**
186+- Reset to 0 on successful LLM response (line 616)
187+- Prevents idle Myses from looping indefinitely
188+- Forces transition to idle state after 3 failed nudges
189+
190+### Nudge Intervals
191+
192+```go
193+// internal/constants/constants.go:69-73
194+
195+IdleNudgeInterval = 30 * time.Second // Default idle nudging
196+WaitStateNudgeInterval = 2 * time.Minute // Nudging during wait states
124197 ```
125198
126199 ## Search Tools
@@ -173,44 +246,84 @@ Returns matching reasoning entries with role, source, content, reasoning, and ti
173246 The system prompt instructs Myses to use their captain's log for persistent memory and search tools for older context:
174247
175248 ```
176-## Memory
177-Use captain's log to persist important information across sessions.
178-
179-## Context & Memory Management
180-Your context window is limited. Recent state snapshots are kept, but older messages are removed.
181-If you need information from earlier in the conversation:
182-- Use zoea_search_messages to find past messages by keyword
183-- Use zoea_search_reasoning to find past reasoning by keyword
184-- Use captain's log for persistent notes across sessions
249+## Critical Rules
250+Context is limited - use search tools for older information.
185251 ```
186252
187-The continue prompt also reminds Myses about search tools:
188-
189-```
190-CRITICAL REMINDERS:
191-- If you need past data, use zoea_search_messages or zoea_search_reasoning
192-```
253+The continue prompt also reminds Myses about search tools when generated by nudging logic.
193254
194255 This encourages Myses to:
195256 1. Externalize important information to the game's built-in note system
196257 2. Use search tools to retrieve older context when needed
197-3. Understand that their context window is limited and compacted
258+3. Understand that their context window is minimal and focused
259+
260+## Benefits Over Sliding Windows
261+
262+| Aspect | Loop Slices | Traditional Sliding Window |
263+|--------|-------------|---------------------------|
264+| Size | 2-10 messages | 20-50 messages |
265+| Stability | Always same structure | Variable, depends on history |
266+| Tool coherence | Complete loops guaranteed | Often broken mid-sequence |
267+| Orphaned messages | Never | Common (tool results without calls) |
268+| Context bloat | None | Redundant state snapshots accumulate |
269+| Inference speed | Fast (minimal tokens) | Slower (large context) |
270+
271+## Implementation Details
272+
273+### Constants
274+
275+```go
276+// internal/constants/constants.go:62-64
277+
278+MaxContextMessages = 20 // Window for scanning recent memories
279+```
280+
281+Note: `MaxContextMessages` is the scanning window, NOT the final context size. The loop slice extraction typically produces 2-10 messages regardless of this value.
282+
283+### Store Methods
284+
285+```go
286+// internal/store/memories.go
287+
288+// GetSystemMemory retrieves the initial system prompt for a Mysis.
289+func (s *Store) GetSystemMemory(mysisID string) (*Memory, error)
290+
291+// GetRecentMemories retrieves the most recent N memories for a Mysis.
292+func (s *Store) GetRecentMemories(mysisID string, limit int) ([]*Memory, error)
293+
294+// SearchMemories searches memories by content text (case-sensitive).
295+func (s *Store) SearchMemories(mysisID, query string, limit int) ([]*Memory, error)
296+
297+// SearchBroadcasts searches broadcast messages by content text (case-sensitive).
298+func (s *Store) SearchBroadcasts(query string, limit int) ([]*BroadcastMessage, error)
299+```
198300
199301 ## Tradeoffs
200302
201303 | Aspect | Benefit | Cost |
202304 |--------|---------|------|
203-| Inference speed | Faster responses with smaller context | May lose relevant older context |
204-| Token costs | Lower per-request costs | Search queries add overhead |
305+| Inference speed | Very fast with minimal context | May lose relevant older context |
306+| Token costs | Minimal per-request costs | Search queries add overhead |
205307 | Memory access | Full history searchable | Requires explicit search |
206-| Coherence | Recent context always available | Long-term plans may be forgotten |
308+| Coherence | Recent tool loops always complete | Long-term plans may be forgotten |
309+| Predictability | Same structure every time | Less conversational continuity |
207310
208311 ## Tuning
209312
210-The `MaxContextMessages` constant can be adjusted based on:
313+The loop slice model has minimal tuning surface:
314+
315+- **`MaxContextMessages`**: Scanning window for finding prompt sources and tool loops. Larger values increase DB query cost but provide more history to search. Default: 20 messages (~2 server ticks).
316+- **Prompt source priority**: Fixed order defined by game design (commander > broadcasts > nudge).
317+- **Nudge intervals**: Control how often idle Myses are prompted. Faster intervals increase responsiveness but may interrupt LLM processing.
318+
319+## Migration Notes
320+
321+This architecture replaced the previous snapshot compaction model (v0.4.x) which used a 20-message sliding window with snapshot deduplication. The old model:
322+- Sent 20 recent messages per LLM request
323+- Deduplicated redundant `get_*` tool results
324+- Often broke tool call sequences mid-loop
325+- Created orphaned tool results
211326
212-- **Model context window**: Larger models can handle more messages
213-- **Gameplay pace**: Faster tick rates may need larger windows
214-- **Tool call frequency**: Heavy tool use fills context faster
327+The loop slice model eliminates these issues by composing context from atomic units (system + prompt + loop) rather than arbitrary time windows.
215328
216-Current value of 20 messages covers approximately 2 server ticks of typical gameplay activity.
329+See `documentation/archive/` for historical compaction implementation details.