moai-foundation-context

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: moai-foundation-context
description: >
  Manages context window optimization, session state persistence, and
  token budget allocation for multi-agent workflows. Use for token
  budget management, context limits, or session handoff across agents.
license: Apache-2.0
compatibility: Designed for Claude Code
allowed-tools: Read, Grep, Glob, mcp__context7__resolve-library-id, mcp__context7__get-library-docs
user-invocable: false
metadata:
  version: "3.1.0"
  category: "foundation"
  status: "active"
  updated: "2026-01-11"
  modularized: "false"
  tags: "foundation, context, session, token-optimization, state-management, multi-agent"
  aliases: "moai-foundation-context"
  replaces: "moai-core-context-budget, moai-core-session-state"

# MoAI Extension: Progressive Disclosure
progressive_disclosure:
  enabled: true
  level1_tokens: 100
  level2_tokens: 5000

# MoAI Extension: Triggers
triggers:
  keywords: ["token", "context", "session", "budget", "optimization", "handoff", "state", "memory", "/clear", "context window", "token limit", "session persistence", "context management", "multi-agent"]
  agents:
    - "manager-spec"
    - "manager-ddd"
    - "manager-strategy"
    - "manager-quality"
    - "manager-docs"
    - "manager-project"
  phases:
    - "plan"
    - "run"
    - "sync"
---

## Quick Reference

Enterprise Context and Session Management - Unified context optimization and session state management for Claude Code with 200K token budget management, session persistence, and multi-agent handoff protocols.

Core Capabilities:

- 200K token budget allocation and monitoring
- Session state tracking with persistence
- Context-aware token optimization
- Multi-agent handoff protocols
- Progressive disclosure and memory management
- Session forking for parallel exploration

When to Use:

- Session initialization and cleanup
- Long-running workflows exceeding 10 minutes
- Multi-agent orchestration
- Context window approaching limits exceeding 150K tokens
- Model switches between Haiku and Sonnet
- Workflow phase transitions

Key Principles:

Avoid Last 20%: Performance degrades in final fifth of context window.

Aggressive Clearing: Execute /clear every 1-3 messages for SPEC workflows.

Lean Memory Files: Keep each file under 500 lines.

Disable Unused MCPs: Minimize tool definition overhead.

Quality Over Quantity: 10% relevant context beats 90% noise.

---

## Implementation Guide

### Features

- Intelligent context window management for Claude Code sessions
- Progressive file loading with priority-based caching
- Token budget tracking and optimization alerts
- Selective context preservation across /clear boundaries
- MCP integration context persistence

### When to Use

- Managing large codebases exceeding 150K token limits
- Optimizing token usage in long-running development sessions
- Preserving critical context across session resets
- Coordinating multi-agent workflows with shared context
- Debugging context-related issues in Claude Code

### Core Patterns

Pattern 1 - Progressive File Loading:

Load files by priority tiers. Tier 1 includes CLAUDE.md and config.json which are always loaded. Tier 2 includes current SPEC and implementation files. Tier 3 includes related modules and dependencies. Tier 4 includes reference documentation loaded on-demand.

Pattern 2 - Context Checkpointing:

Monitor token usage with warning at 150K and critical at 180K. Identify essential context to preserve. Execute /clear to reset session. Reload Tier 1 and Tier 2 files automatically. Resume work with preserved context.

Pattern 3 - MCP Context Continuity:

Preserve MCP agent context across /clear by storing the agent_id. After /clear, context is restored through fresh MCP agent initialization.

## Core Patterns Detail

### Pattern 1: Token Budget Management

Concept: Strategic allocation and monitoring of 200K token context window.

Budget Breakdown: System Prompt and Instructions take approximately 15K tokens at 7.5%, including CLAUD