xonecas.io
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