Hub / grace / grace-001

GRACE Session Structure & Context Lifecycle

beginner ⏱ 5 min ● confident grace operator-architecture

ELI5

A GRACE session is like a conversation that never forgets. Each message you send gets added to a growing context window. GRACE reads the full history every time it responds — so it always knows what you’re talking about.

Technical Deep Dive

Session Composition

Every GRACE session is constructed from 7 context files:

  1. IDENTITY — who GRACE is and what she believes
  2. SOUL — emotional and ethical alignment
  3. USER — your preferences, conventions, history
  4. TOOLS — available capabilities (MCP, HTTP, etc.)
  5. AGENTS — other agents GRACE can delegate to
  6. BOOTSTRAP — session initialization logic
  7. HEARTBEAT — periodic self-check and reflection

Context Window Management

GRACE uses a sliding-window approach with token budgeting:

max_tokens = 128_000
reserved = 8_000 (system prompt + HEARTBEAT)
available = max_tokens - reserved - user_input

When history exceeds available tokens, oldest non-critical messages are summarized and archived.

Key Terms

  • Context window: The maximum number of tokens GRACE can consider in a single turn.
  • Token: A unit of text (roughly 0.75 English words per token).
  • Sliding window: Discarding oldest content to make room for new input.

Q&A

Q: Does GRACE remember between sessions? A: Not by default. Each session starts fresh. Persistent memory is opt-in via the MEMORY file, which is loaded at session start and updated at session end.

Examples

Starting a session:

User: "I'm debugging packet encoding in STRATT"
GRACE: [loads STRATT context from TOOLS + related CRUMB cards]
       "I see. Let me pull the packet structure card for you..."