60255
Zn
Zoea-Nova / files
Zoea-Nova / documentation / architecture / GAME_STATE_CACHE_DESIGN.md
8.2 KB
1# Game State Cache Design 2 3## Problem 4 5Myses are stuck in a loop of re-requesting game state every turn: 6 71. **Turn N:** Mysis calls `get_status`, `get_ship`, `get_map` → receives 190 KB of data 82. **Turn N+1:** Synthetic nudge starts new turn 9 - Historical context contains old snapshots (compressed) 10 - LLM doesn't trust "stale" data 11 - Calls `get_status` again → another 190 KB 123. **Repeat forever:** Massive payloads every turn, hits 10-iteration limit 13 14**Root cause:** LLMs can't tell if snapshot data is from 1 turn ago or 10 turns ago. They re-request to be safe. 15 16## Solution: Incremental Game State Cache 17 18Build and maintain game state incrementally as the mysis plays. Show state with recency metadata so LLM knows when to update. 19 20### Core Concept 21 22**Store game state snapshots per in-game username (not per mysis):** 23 24- Mysis can switch accounts → state follows the account 25- Each mysis has its own game account (SpaceMolt enforces one connection per account) 26- State persists when mysis switches between different game accounts 27- Account logout → clear that account's state 28 29**Include state in context with delta metadata:** 30 31``` 32Current Game State (updated 2 ticks ago): 33 Player: VoidWanderer 34 Credits: 5,000 35 Location: Sol System > Asteroid Belt Alpha 36 Ship: Cargo Hauler (Hull: 85%, Fuel: 60%) 37 Cargo: 45/100 (Iron Ore x30, Copper Ore x15) 38 39To update: call get_status, get_ship, get_notifications 40``` 41 42**Benefits:** 43 44- 190 KB payload appears ONCE when first fetched 45- Subsequent turns show compact summary with recency 46- LLM knows "2 ticks ago" vs "50 ticks ago" → makes informed decisions 47- State persists across mysis restarts 48- No pollution when switching accounts 49 50## Architecture 51 52### Database Schema 53 54```sql 55-- New table: game_state_snapshots 56CREATE TABLE game_state_snapshots ( 57 id TEXT PRIMARY KEY, 58 username TEXT NOT NULL, -- In-game username (e.g., "VoidWanderer") 59 tool_name TEXT NOT NULL, -- Tool that produced this state (e.g., "get_status") 60 content TEXT NOT NULL, -- Full JSON response from tool 61 game_tick INTEGER, -- Game tick when captured (from response) 62 captured_at INTEGER NOT NULL, -- Unix timestamp when stored 63 UNIQUE(username, tool_name) -- One snapshot per tool per username 64); 65 66CREATE INDEX idx_game_state_username ON game_state_snapshots(username); 67``` 68 69### State Lifecycle 70 71**1. Tool Call Interception** 72 73- When mysis calls `get_status`, `get_ship`, `get_map`, etc. 74- After receiving response, extract username from result 75- Store full response in `game_state_snapshots` table 76- Upsert: replace old snapshot for this username+tool 77 78**2. Context Composition** 79 80- Before building LLM context, check if mysis has active game account 81- If logged in, fetch all snapshots for that username 82- Build compact state summary with recency metadata 83- Include summary in system prompt or as synthetic user message 84 85**3. State Invalidation** 86 87- On `logout`: Delete all snapshots for that username 88- On `register`: Create new username entry 89- On `login`: Switch to existing username's snapshots 90- On action (travel, mine, attack): Mark affected snapshots as stale 91 92### State Summary Format 93 94```markdown 95## Current Game State 96 97**Account:** VoidWanderer (Solarian Empire) 98**Last Updated:** 2 ticks ago (12 seconds) 99 100### Status (get_status - 2 ticks ago) 101 102- Credits: 5,000 103- Location: Sol System > Asteroid Belt Alpha 104- Ship: Cargo Hauler 105- Docked: No 106 107### Ship (get_ship - 2 ticks ago) 108 109- Hull: 85/100 110- Shield: 50/50 111- Fuel: 60/100 112- Cargo: 45/100 113 - Iron Ore x30 114 - Copper Ore x15 115 116### System (get_system - 5 ticks ago) 117 118- Sol System (Solarian Empire) 119- POIs: Earth, Mars, Asteroid Belt Alpha, Station Alpha 120- Connections: Alpha Centauri, Barnard's Star 121 122### Map (get_map - 50 ticks ago) 123 124- 487 systems cached 125- Use get_map to refresh full galaxy data 126 127**Note:** Call get_notifications to see events since last update. 128**Stale data:** get_map is 50 ticks old - consider refreshing if planning long journey. 129``` 130 131### Recency Calculation 132 133```go 134type GameStateSnapshot struct { 135 ToolName string 136 Content string 137 GameTick int // From game response 138 CapturedAt time.Time // When we stored it 139} 140 141func (s *GameStateSnapshot) RecencyMessage(currentTick int) string { 142 if currentTick > 0 && s.GameTick > 0 { 143 ticksAgo := currentTick - s.GameTick 144 if ticksAgo == 0 { 145 return "just now" 146 } 147 return fmt.Sprintf("%d ticks ago (%d seconds)", ticksAgo, ticksAgo*10) 148 } 149 150 // Fallback to wall clock time 151 elapsed := time.Since(s.CapturedAt) 152 if elapsed < time.Minute { 153 return fmt.Sprintf("%.0f seconds ago", elapsed.Seconds()) 154 } 155 return fmt.Sprintf("%.0f minutes ago", elapsed.Minutes()) 156} 157``` 158 159## Implementation Plan 160 161### Phase 1: Database & Storage 162 1631. Add `game_state_snapshots` table to schema 1642. Create `GameStateCache` struct in `internal/core/game_state.go` 1653. Implement CRUD operations: Store, Get, Delete, List 166 167### Phase 2: Tool Interception 168 1691. Modify MCP proxy to intercept snapshot tool responses 1702. Extract username from tool results (parse JSON) 1713. Store snapshots in database with game tick 1724. Handle login/logout/register to manage username association [Dont break exisitng account re-use logic!] 173 174### Phase 3: Context Integration 175 1761. Add `GetGameStateSummary(username)` method 1772. Modify `getContextMemories()` to include state summary 1783. Format summary with recency metadata 1794. Add to system prompt or as synthetic message 180 181### Phase 4: Staleness Detection 182 1831. Track which actions invalidate which snapshots 1842. Mark snapshots as "stale" after relevant actions 1853. Prompt LLM to refresh stale data 1864. Example: After `travel`, mark `get_status` as stale 187 188### Phase 5: Partial Updates 189 1901. Implement merge logic for partial state updates 1912. Handle tools that return partial state (e.g., `get_notifications`) 1923. Merge new data into existing snapshots without replacing entire snapshot 1934. Track which fields were updated and when 194 195### Phase 6: Testing & Refinement 196 1971. Test with account switching (mysis changes between different game accounts) 1982. Verify state persists across mysis restarts 1993. Verify state isolation between different game accounts 2004. Test partial update merging 2015. Measure context size reduction 2026. Tune staleness thresholds 203 204## Edge Cases 205 206### Account Switching (Single Mysis, Multiple Accounts) 207 208- Mysis logs out of Account A, logs into Account B 209- Account A's state preserved in DB 210- Account B's state loaded (or empty if new) 211- No pollution between accounts 212 213### Stale Data After Actions 214 215- After `travel`: `get_status` location is stale 216- After `mine`: `get_ship` cargo is stale 217- After `buy`: `get_status` credits are stale 218- Mark affected snapshots, prompt refresh 219 220### No Active Account 221 222- Mysis not logged in → no game state available 223- Context shows: "Not logged in. Use register or login." 224- After login, state appears 225 226### Tick Synchronization 227 228- Game tick comes from tool responses 229- If tick not in response, fall back to wall clock time 230- Recency still useful: "30 seconds ago" vs "5 minutes ago" 231 232## Expected Impact 233 234### Context Size Reduction 235 236- **Before:** 190 KB `get_map` every turn 237- **After:** 190 KB once, then 2 KB summary per turn 238- **Savings:** ~95% reduction in repeated data 239 240### Iteration Limit 241 242- **Before:** 10 iterations spent processing map data 243- **After:** 1-2 iterations for decision making 244- **Result:** Myses can complete multi-step plans 245 246### LLM Decision Quality 247 248- **Before:** "I don't know current state, better check" 249- **After:** "State is 2 ticks old, still fresh, proceed" 250- **Result:** More decisive, less redundant tool calls 251 252### State Persistence 253 254- Mysis restart → state preserved for its game account 255- Account switch → correct state loaded for new account 256- Each mysis operates independently with its own game account 257- State keyed by username ensures proper isolation 258 259## Migration Path 260 2611. No backwards migration, new db required. 262 263## Success Metrics 264 265- **Tool call frequency:** Reduce `get_*` calls by 80%+ 266- **Iteration limits:** Reduce "Max tool iterations" warnings by 90%+ 267- **Context size:** Reduce average context from 191 KB to <20 KB 268- **Decision speed:** Myses complete actions in 2-3 iterations vs 10 269- **State accuracy:** LLMs make decisions with correct recency awareness