AI State Persistence

Status: Implemented Parent: Session Environment Date: 2026-01-03 Updated: 2026-01-03

Problem Statement

AI working context (todos, notes, progress) exists only in conversation memory. When context resets (new terminal, auto-compact, API call), this state is lost. The AI must re-learn what it was working on.

Current gaps: - VS Code hooks only work in Claude Code terminal - Web app API, CLI, LARS have no hook mechanism - Session agenda exists but requires manual AI discipline to update - No way to transfer AI context between interfaces

Solution: Session-Bound AI State

Extend the Session environment with AI-specific state storage. Four new tools added to Session MCP server:

Tools Implemented

@mcp.tool()
async def ai_state_save(ai_id: str, todos: List[Dict] = None, 
                        working_notes: str = None,
                        context_summary: str = None, 
                        session_id: str = None) -> str:
    """Persist AI working state to session."""

@mcp.tool()
async def ai_state_get(ai_id: str, session_id: str = None) -> str:
    """Retrieve AI working state from session."""

@mcp.tool()
async def ai_state_transfer(from_session: str, to_session: str, 
                             ai_id: str) -> str:
    """Transfer AI state between sessions."""

@mcp.tool()
async def ai_state_list(session_id: str = None) -> str:
    """List all AI states stored in a session."""

Redis Key Structure

sess:{user_id}:{session_id}:ai_state:{ai_id}

Example: sess:u_z1p5:20251228_1847_pjcc:ai_state:claude

State Schema

{
  "ai_id": "claude",
  "updated_at": "2026-01-03T16:57:36-07:00",
  "todos": [
    {"content": "Task description", "status": "in_progress", "activeForm": "Working on task"}
  ],
  "working_notes": "Free-form notes the AI is tracking",
  "context_summary": "Summary of current working context",
  "transferred_from": "previous_session_id",
  "transferred_at": "2026-01-03T17:00:00-07:00"
}

Usage Patterns

1. Save State (Hook or Periodic)

gateway.run([{server:'session', tool:'ai_state_save', args:{
  ai_id: 'claude',
  todos: [...current_todos...],
  working_notes: 'Current focus areas',
  context_summary: 'What I was working on'
}}])

2. Restore State (On Recovery)

gateway.run([{server:'session', tool:'ai_state_get', args:{ai_id: 'claude'}}])

3. Transfer Between Sessions

gateway.run([{server:'session', tool:'ai_state_transfer', args:{
  from_session: 's_pjcc',
  to_session: 's_newid',
  ai_id: 'claude'
}}])

Integration Points

VS Code Hooks (Optional Enhancement)

Hook can call ai_state_save periodically
Not required - AI can call directly

workflow.init Enhancement (Recommended)

Add reminder to check for saved AI state
Include ai_state_get in recovery flow

Web App / API

Call ai_state_save before ending session
Call ai_state_get when starting new session with same context

Implementation Notes

Session server converted to FastMCP (v2.0.0)
21 total tools (17 core + 4 AI state)
State is session-bound, not global
Multiple AIs can have state in same session (claude, gemini, lars)
State persists as long as session data exists