xonecas.io
60255
Zn

Zoea-Nova / commit d8d8d89

docs: document loop slice context composition

Architecture documentation:
- Complete rewrite of CONTEXT_COMPRESSION.md
- Loop slice model with 3-component structure
- Prompt source priority (commander → broadcast → swarm → nudge)
- Loop extraction algorithm
- Bounded size guarantees (3-10 messages typical)
- Synthetic nudge circuit breaker mechanism
- Migration notes from v0.4.x compaction

Code comments:
- Enhanced selectPromptSource docstring (rationale, parameters, returns)
- Enhanced extractLatestToolLoop docstring (behavior, examples)
- Enhanced getContextMemories docstring (composition details, rationale)
- All functions now have comprehensive godoc-style comments

Phase 4 complete - ready for Phase 5 validation.

xonecas2026-02-07 d8d8d8971b8b94bd1bf6085941192613f9692a98 parent 1763141

2 files changed

documentation/architecture/CONTEXT_COMPRESSION.md+201−88
@@ -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.
internal/core/mysis.go+73−3
@@ -1272,6 +1272,19 @@ func (m *Mysis) setIdle(reason string) {
12721272 //
12731273 // The commander is identified by empty sender_id in broadcasts.
12741274 // Memories are expected to be ordered newest-first (from getContextMemories).
1275+//
1276+// Parameters:
1277+// - memories: Slice of memories ordered newest-first, typically from GetRecentMemories
1278+//
1279+// Returns:
1280+// - *store.Memory: The selected prompt source, or nil if no valid user message exists
1281+//
1282+// Rationale:
1283+//
1284+// This priority ensures that direct commands from the commander take precedence
1285+// over broadcasts, and commander broadcasts take precedence over peer messages.
1286+// When no prompt source exists, returning nil signals the caller to generate
1287+// a synthetic nudge to keep the Mysis active.
12751288 func (m *Mysis) selectPromptSource(memories []*store.Memory) *store.Memory {
12761289 if len(memories) == 0 {
12771290 return nil
@@ -1326,10 +1339,31 @@ func (m *Mysis) selectPromptSource(memories []*store.Memory) *store.Memory {
13261339 // extractLatestToolLoop finds the most recent tool-call message (assistant role
13271340 // with tool_calls) and returns it plus all subsequent tool results.
13281341 //
1329-// Returns: [tool-call-message, result1, result2, ...] or empty slice if no tool loop found.
1342+// Parameters:
1343+// - memories: Slice of memories in chronological order (oldest first, newest last)
1344+// as returned by GetRecentMemories
1345+//
1346+// Returns:
1347+// - []*store.Memory: Slice containing [tool-call-message, result1, result2, ...]
1348+// in chronological order, or empty slice if no tool loop found
1349+//
1350+// Behavior:
1351+// - Scans backwards from the end to find the most recent assistant message
1352+// with content prefixed by constants.ToolCallStoragePrefix
1353+// - Collects all consecutive tool role messages that follow the tool call
1354+// - Stops at the first non-tool message (end of loop)
1355+// - Returns empty slice if no tool call is found
1356+//
1357+// Rationale:
1358+//
1359+// By extracting only the latest tool loop, we ensure OpenAI-compatible providers
1360+// receive properly paired tool calls and results without orphaned tool messages.
1361+// This prevents API errors from malformed message sequences.
13301362 //
1331-// The function scans memories backwards from the end (since GetRecentMemories returns
1332-// chronological order: oldest first, newest last) to find the most recent tool call.
1363+// Example:
1364+//
1365+// Given memories: [user_msg, assistant_with_tools, tool_result1, tool_result2, user_msg2]
1366+// Returns: [assistant_with_tools, tool_result1, tool_result2]
13331367 func (m *Mysis) extractLatestToolLoop(memories []*store.Memory) []*store.Memory {
13341368 if len(memories) == 0 {
13351369 return nil
@@ -1374,6 +1408,42 @@ func (m *Mysis) extractLatestToolLoop(memories []*store.Memory) []*store.Memory
13741408 // getContextMemories returns memories for LLM context using loop-based composition.
13751409 // Composes context as: [system prompt] + [chosen prompt source] + [most recent tool loop].
13761410 // This ensures stable, bounded context and eliminates orphaned tool sequencing.
1411+//
1412+// Returns:
1413+// - []*store.Memory: Composed context slice ready for provider conversion
1414+// - error: Database error from GetRecentMemories or GetSystemMemory
1415+//
1416+// Context Composition:
1417+// 1. System prompt (if available) - provides mysis identity and mission
1418+// 2. Prompt source (by priority) - the user message that triggers this LLM turn
1419+// - Commander direct message (highest priority)
1420+// - Commander broadcast
1421+// - Swarm broadcast
1422+// - Synthetic nudge (if no prompt found)
1423+// 3. Latest tool loop (if any) - most recent tool call + all its results
1424+//
1425+// Behavior:
1426+// - Fetches up to constants.MaxContextMessages (20) recent memories
1427+// - Creates synthetic nudge if no valid prompt source exists
1428+// - Nudge memory is NOT stored in database (temporary, in-memory only)
1429+// - Nudge counter increment happens in caller (handleLLMResponse)
1430+//
1431+// Rationale:
1432+//
1433+// Loop-based composition solves the orphaned tool result problem:
1434+// - Sliding window (MaxContextMessages) can split tool call/result pairs
1435+// - By extracting only the latest complete loop, we guarantee proper pairing
1436+// - Bounded context (3 components max) keeps token usage predictable
1437+// - Stable structure prevents OpenAI API errors from malformed sequences
1438+//
1439+// Example context:
1440+//
1441+// [
1442+// {role: system, content: "You are Mysis Alpha..."},
1443+// {role: user, source: direct, content: "Check ship status"},
1444+// {role: assistant, content: "[TOOL_CALLS]call_1:get_ship:{}"},
1445+// {role: tool, content: "Ship health: 100%"}
1446+// ]
13771447 func (m *Mysis) getContextMemories() ([]*store.Memory, error) {
13781448 // Get all recent memories
13791449 allMemories, err := m.store.GetRecentMemories(m.id, constants.MaxContextMessages)