@@ -0,0 +1,269 @@
1+# Game State Cache Design
2+
3+## Problem
4+
5+Myses are stuck in a loop of re-requesting game state every turn:
6+
7+1. **Turn N:** Mysis calls `get_status`, `get_ship`, `get_map` → receives 190 KB of data
8+2. **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
12+3. **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+
18+Build 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+```
32+Current 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+
39+To 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
56+CREATE 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+
66+CREATE 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
134+type GameStateSnapshot struct {
135+ ToolName string
136+ Content string
137+ GameTick int // From game response
138+ CapturedAt time.Time // When we stored it
139+}
140+
141+func (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+
163+1. Add `game_state_snapshots` table to schema
164+2. Create `GameStateCache` struct in `internal/core/game_state.go`
165+3. Implement CRUD operations: Store, Get, Delete, List
166+
167+### Phase 2: Tool Interception
168+
169+1. Modify MCP proxy to intercept snapshot tool responses
170+2. Extract username from tool results (parse JSON)
171+3. Store snapshots in database with game tick
172+4. Handle login/logout/register to manage username association [Dont break exisitng account re-use logic!]
173+
174+### Phase 3: Context Integration
175+
176+1. Add `GetGameStateSummary(username)` method
177+2. Modify `getContextMemories()` to include state summary
178+3. Format summary with recency metadata
179+4. Add to system prompt or as synthetic message
180+
181+### Phase 4: Staleness Detection
182+
183+1. Track which actions invalidate which snapshots
184+2. Mark snapshots as "stale" after relevant actions
185+3. Prompt LLM to refresh stale data
186+4. Example: After `travel`, mark `get_status` as stale
187+
188+### Phase 5: Partial Updates
189+
190+1. Implement merge logic for partial state updates
191+2. Handle tools that return partial state (e.g., `get_notifications`)
192+3. Merge new data into existing snapshots without replacing entire snapshot
193+4. Track which fields were updated and when
194+
195+### Phase 6: Testing & Refinement
196+
197+1. Test with account switching (mysis changes between different game accounts)
198+2. Verify state persists across mysis restarts
199+3. Verify state isolation between different game accounts
200+4. Test partial update merging
201+5. Measure context size reduction
202+6. 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+
261+1. 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