feat: Selective context loading via ContextRouter hook to reduce 83KB base context

[jlacour-git]

Problem

Related: #678

PAI v3.0 injects ~83KB of context at SessionStart via LoadContext.hook.ts. The Algorithm spec alone (v1.5.0.md) is 78,606 bytes. On Opus with a 200K token window, this means ~25K tokens (~12-15%) consumed before the user types anything. With hook outputs, steering rules, relationship context, and active work listings, the real baseline is 25-33%.

This is a significant regression from v2.5, where the Algorithm spec was much smaller. Issue #678 reports users seeing 78% context usage after a single interaction.

The core issue: every interaction pays the full 83KB cost, regardless of whether a greeting, a skill invocation, or a deep algorithm task is being performed.

Proposal: Tiered Context Loading via a ContextRouter Hook

Split context loading into two stages:

Stage 1: SessionStart — Core Context Only (~10-15KB)

LoadContext.hook.ts injects only what every interaction needs:

• Identity (principal name, DA name, voice ID)
• Minimal format rules (the 3 format modes: FULL / ITERATION / MINIMAL)
• Effort level selection table
• Phase names (OBSERVE → LEARN) without full phase details
• AI Steering Rules
• A routing instruction: "Full Algorithm details will be provided based on task classification"

Stage 2: UserPromptSubmit — Selective Injection (~0-70KB)

A new ContextRouter.hook.ts classifies each prompt and injects only the relevant Algorithm sections:

Classification	Extra Context Loaded	Estimated Size
Greeting / acknowledgment	Nothing	0 KB
Skill invocation	Skill system docs	~3 KB
Standard algorithm task	ISC rules + phase details	~25 KB
Extended+ algorithm task	Full Algorithm + PRD + capabilities	~70 KB

Classification can be keyword-based (fast, no AI inference needed):

• Starts with greeting words → greeting
• Contains /skillname → skill invocation
• Contains "Extended"/"Advanced"/"Deep" or is complex → full spec
• Default → standard

Implementation Path

1. Split the Algorithm monolith. The v1.5.0.md component (78KB) contains conceptually modular sections that are already separated by headers: ISC system, phase definitions, PRD template, loop mode, agent teams, capability registry. Split these into separate component files (e.g., algorithm-core.md, algorithm-isc.md, algorithm-prd.md, algorithm-capabilities.md, algorithm-loop.md, algorithm-teams.md).

2. Modify RebuildPAI.ts to produce multiple output files (or one combined file plus individual section files) instead of a single monolithic SKILL.md.

3. Create ContextRouter.hook.ts as a UserPromptSubmit hook that classifies and injects.

4. Slim down LoadContext.hook.ts to only inject the core ~10KB.

Estimated Impact

Interaction Type	Current	Proposed	Reduction
Greeting	83 KB	~10 KB	88%
Skill invocation	83 KB	~13 KB	84%
Standard task	83 KB	~35 KB	58%
Extended+ task	83 KB	~80 KB	~4%
Weighted average	83 KB	~25 KB	~70%

Additional Benefit: Deterministic Documentation Loading

Currently, SKILL.md's "Context Loading" section instructs the LLM to read additional files (PAISYSTEMARCHITECTURE.md, MEMORYSYSTEM.md, etc.) when relevant. This is non-deterministic — the LLM may or may not follow the instruction. Moving these reads into the ContextRouter hook makes them deterministic: if the prompt mentions "memory", the hook injects MEMORYSYSTEM.md content directly.

Risks & Mitigations

• Misclassification: If the router under-classifies, the LLM lacks needed context. Mitigation: default to "standard" (not minimal), and include an escape hatch instruction in core context: "If you need full Algorithm details not present in your current context, state this and they will be provided on the next turn."
• Cross-references: Algorithm sections reference each other (ISC rules reference PRD template). Mitigation: include brief summaries/pointers in each section, and load dependent sections together.
• Latency: Keyword matching adds negligible latency (<5ms). AI-based classification would add ~300ms — not recommended for v1.

Happy to submit a PR for this if there's interest.

[jlacour-git]

Update: Active local testing underway

I've implemented and am actively testing this locally. Here's where things stand:

What's built:

• build-tiers.ts splits SKILL.md into 3 tiers by section (core 14KB, phases 40KB, advanced 29KB)
• ContextRouter.hook.ts (UserPromptSubmit) classifies prompts via keyword matching (<25ms) and injects the appropriate tier
• LoadContext.hook.ts loads the slim core tier at SessionStart when enabled
• Single-field toggle in settings.json (contextRouter.enabled) with instant rollback

Measured savings:

Interaction	Before	After	Reduction
Greeting	95 KB	27 KB	71%
Standard task	95 KB	68 KB	28%
Extended+ task	95 KB	96 KB	~0%

Current status: Running in my daily workflow. Will report back on any classification misses or behavioral regressions after a few days of use.

Happy to turn this into a PR if there's interest after testing confirms stability.

[jlacour-git]

Update: 2-day real-world results

ContextRouter has been running in daily use for 2 days (Feb 18–20). Here are the measured results:

📊 ContextRouter Stats
───────────────────────────────────────────────────────
Period: 2/18/2026 → 2/20/2026 (2 days)
Total interactions: 52

Tier          Count    Saved      Avg/prompt
───────────────────────────────────────────────────────
standard         40     1626.3 KB       40.7 KB
extended         12      151.3 KB       12.6 KB
───────────────────────────────────────────────────────

💾 Total context saved:    1.74 MB
📉 Average savings/prompt: 34.2 KB (42.7%)
📈 Would-have-loaded:      4.07 MB
✅ Actually loaded:        2.33 MB

Key takeaways:

• 42.7% average context savings across 52 real interactions
• 1.74 MB total context avoided in 2 days of normal use
• No greeting-tier hits — my usage pattern is mostly standard/extended, so savings come from not loading advanced-tier content on standard prompts
• Zero classification misses or behavioral regressions observed so far
• Keyword classifier runs in <25ms — no perceptible latency

The savings scale linearly with usage. At this rate, that's ~25+ MB/month of unnecessary context avoided.

Still happy to turn this into a PR once the architecture direction for 3.1 stabilizes (per discussion #731).

[nbost130]

Data point: local SKILL.md sizes and lazy-loading candidates

Our local PAI build (v1.8.1 Algorithm) produces a SKILL.md of ~85KB. The Algorithm spec alone is ~1,170 lines. Combined with steering rules, documentation routing, and capability matrix, it's substantial.

Sections that could be lazy-loaded (not needed until specific phases):

Section	~Size	Needed When	Lazy-Load Signal
PRD Template + Integration	~15KB	Only when creating/continuing PRDs	OBSERVE detects new or continuing work
Capability Registry (25 capabilities)	~8KB	OBSERVE capability audit	Always needed — keep loaded
ISC Requirements + Quality Gate	~5KB	OBSERVE ISC creation	Always needed — keep loaded
Loop Worker Mode	~4KB	Only in algorithm.ts -m loop	mode: "loop" in invocation
Agent Teams / Swarm	~3KB	Only when spawning teams	User says "team"/"swarm" or Extended+
Plan Mode Integration	~2KB	Only at Extended+ effort level	Effort level >= Extended

Conservative estimate: ~24KB could be deferred without affecting Standard effort level runs (which are ~80% of usage). That's a ~28% reduction in base context.

Implementation thought: Rather than a ContextRouter hook that makes load-time decisions, the Algorithm template itself could use conditional includes — {{IF_EXTENDED}}...{{/IF_EXTENDED}} blocks that RebuildPAI.ts strips based on a runtime effort-level hint. Simpler than hook-based routing and deterministic.

[badosanjos]

Supporting the ContextRouter proposal. Additional context from upstream: the 83KB injection isn't only a budget issue — it directly accelerates a Claude Code compaction bug that destroys hook-injected content.

Claude Code treats <system-reminder> blocks from SessionStart hooks as summarizable conversation history (claude-code #27954, #24460). After compaction, PAI identity, response format, and security rules can be lost. Starting at 12–15% context consumed means this happens earlier in sessions.

Two suggestions for the ContextRouter design:

1. PostCompact re-injection. Even with tiered loading, compaction will eventually fire. Critical Tier 0 context (identity, security, format) needs automatic re-injection. No postCompact hook exists yet upstream (claude-code #3537), but a health-check pattern could approximate it.

2. Enforcement layer. Opus 4.6 has a documented instruction-following regression (claude-code #24991). Text-based instructions alone aren't reliable — the ContextRouter should be complemented by programmatic enforcement for critical behaviors per Discussion #695.

Full upstream analysis: #792

[kaimagnus]

Addressed in v4.0.0 — the complete skill reorganization and context system overhaul cut startup context from ~38% to ~19%. The CLAUDE.md template system (BuildCLAUDE.ts) generates a lean bootstrap file, and skills are loaded on-demand via context routing rather than all at once. Thanks for the analysis.

👉 Releases page