context-mgmt

---

name: context-mgmt description: "Context engineering: compaction, progressive disclosure, structured notes via AgentDB. Triggers: tokens, compaction, memory, handoff, summarize, context window." allowed-tools: Read, Bash, Task kernel: kind: methodology version: 1 side_effects: none confirmation: none

Reasoning fidelity is the real metric, not token count. Quality degrades at ~60-70% fill, not at the limit.

<core_principles>

1. COMPACTION: Summarize and reinitialize. Keep architecture decisions, discard noise.
2. STRUCTURED NOTES: AgentDB + active.md persist across context resets.
3. MULTI-AGENT: Delegate research to subagents. They explore, report summaries. Cap the return at ~1,000-2,000 tokens (conclusion + path:line evidence, no raw dumps); the exploration context stays in the subagent.
4. MINIMAL READS: grep/glob to find, then read specific sections.
5. TOOL RESULT CLEARING: Old tool output rarely needs to stay in context. When calling the Claude API directly (not via this harness), prefer the server-side context-management-2025-06-27 beta over hand-rolled truncation: clear_tool_uses_20250919 clears old tool results past a token trigger (client keeps full history, no sync needed), clear_thinking_20251015 clears old thinking blocks while preserving cache hits. Client-side SDK compaction (compaction_control, TypeScript/Ruby) is deprecated; use server-side compact_20260112 (same beta header) for summarization. Ordering: clear_thinking_20251015 must precede clear_tool_uses_20250919 in edits. Set exclude_tools for results that must survive; clearing tool results invalidates the cached prefix, so set clear_at_least so each clear pays for itself. </core_principles>

<token_budget>

• CLAUDE.md: <150 lines (always loaded)
• rules/: <100 lines (always loaded)
• Skills: metadata only at startup, full content on demand
• Commands: only when invoked
• Reference docs: only when skill explicitly reads them </token_budget>

<compaction_protocol>

1. CHECK fill level via /context. (gate: <60% → continue; ≥60% → proceed to step 2)
2. Write critical state: agentdb write-end '{"did":"X","next":"Y","blocked":"Z"}'
3. Commit any uncommitted changes. (gate: clean working tree)
4. Generate handoff if complex work in progress: /kernel:handoff
5. Trigger compaction.
6. POST-COMPACT RESTORE: a. Read active.md for project context. b. Run agentdb read-start for failures, patterns, contracts. c. Check for pending checkpoints to review. </compaction_protocol>

<fidelity_signals> Watch for reasoning degradation BEFORE the token meter shows a problem:

• Hypothesis depth dropping: agent defaults to first idea, stops exploring alternatives
• Backtracking absent: errors patched in place instead of root-caused
• Step count contracting: multi-step plans collapse to one-shot attempts
• Cross-file awareness fading: agent forgets earlier files in the same session
• Inline checks disappearing: agent stops verifying assumptions before acting

Any one of these → compact or hand off NOW, even if /context shows <60% fill. </fidelity_signals>

<what_to_preserve> Never compact away:

• Current task context and goal
• Active decisions and their rationale
• Blocking issues and error states
• File paths currently being worked on
• Uncommitted changes description
• Contract IDs and branch names </what_to_preserve>

<what_to_compact> Aggressively compress:

• Exploratory searches → "searched X, found Y at path:line"
• File reads → "read file, key insight: Z"
• Successful operations → "completed: X"
• Debugging traces → "root cause: X, fix: Y"
• Tool call history → "N tool calls, outcome: X"
• Research context → offload to AgentDB, keep one-line summary </what_to_compact>

<failure_modes>

1. Agent tries too much at once → context exhausted mid-work Fix: Incremental progress with commits at each step.
2. Later agent assumes done prematurely → work incomplete Fix: Explicit done-when criteria with evidence required. </failure_modes>