context-management

name	context-management
description	Context window auto-management — signals, strategies, and recovery protocol. Detects approaching context limits and guides compact vs checkpoint decisions to prevent lost work.

Context Window Auto-Management

Strategies for detecting, responding to, and recovering from context window pressure. The session-end hook warns when sessions exceed 90 minutes without a .clarc/context.md, prompting a checkpoint.

When to Activate

• Claude suggests /compact or context is nearing capacity
• Session has been running for 90+ minutes
• User is mid-task and worried about context loss
• After recovering from a context reset
• Planning a large multi-file implementation
• Starting a multi-phase refactor that will span more than 20 files so checkpoints are created between phases to prevent losing progress
• Recovering a session after an unexpected compaction wiped the conversation state mid-task and the next steps are unclear
• Setting up a new project to use the .clarc/ memory bank so session-end hooks automatically persist context across restarts

Context Pressure Signals

Warning Signs (Act Proactively)

Signal	Threshold	Action
Session length	> 90 min	Create .clarc/context.md checkpoint
File count in task	> 20 files	Split into phases with checkpoints
Token estimate	> 80% of window	/compact or summarize
Repeated context loads	Same files > 3x	Extract summary to working file
Tool call depth	> 50 in session	/checkpoint create before continuing

Critical Signs (Act Immediately)

• Claude stops referencing earlier conversation correctly
• Responses become repetitive or miss established constraints
• System suggests /compact automatically
• Context compaction triggers mid-task

Strategies

1. Checkpoint Before Compaction

Before running /compact, always checkpoint:

/checkpoint create pre-compact

The checkpoint records:

• Current git SHA
• Files modified so far
• Completed vs remaining tasks

After compaction, restore with:

/checkpoint verify pre-compact
cat .clarc/context.md

2. Memory Bank as Persistent State

.clarc/context.md is the canonical session handoff document (written by session-end hook automatically). Keep it current during long sessions:

# Session Context — 2026-03-09

## Current focus
- Implementing REST API authentication middleware
- Files: src/middleware/auth.ts, tests/unit/auth.test.ts

## Progress
- [x] JWT validation logic
- [x] Unit tests passing
- [ ] Integration test
- [ ] Rate limiting

## Key decisions
- Using RS256 (not HS256) for multi-service JWT
- Middleware runs before route handlers

## Next steps
1. Write integration test (src/tests/integration/auth.test.ts)
2. Add rate limiting (src/middleware/rate-limit.ts)

Update manually at logical milestones or run:

/checkpoint create milestone-name

3. Progressive Summarization

For large tasks spanning many files, summarize as you go:

Working summary pattern:

1. Read N files
2. Summarize findings in one working note
3. Read next N files (use summary, not all N files)
4. Repeat until done

This reduces re-reading costs and fits more analysis in the context window.

4. Phase-Based Implementation

Break large implementations into phases, each fitting in one context window:

Phase 1: Plan + design (separate session or first context)
  Output: docs/specs/feature-plan.md

Phase 2: Core implementation
  Input: feature-plan.md (small, loaded fresh)
  Output: core files

Phase 3: Tests + edge cases
  Input: feature-plan.md + list of core files
  Output: test files

Phase 4: Review + cleanup
  Input: git diff (compact representation)
  Output: final commits

Each phase starts fresh with minimal context load.

Recovery Protocol

When context has been lost or compacted mid-task:

1. Read .clarc/context.md       # Memory Bank (if exists)
2. Run: git log --oneline -10    # Recent commits
3. Run: git diff HEAD            # Current changes
4. Run: git stash list           # Any stashed work
5. Read checkpoint log:
   cat .claude/checkpoints.log
6. Reconstruct state and continue

If .clarc/context.md is up to date, recovery takes < 2 minutes.

Hook Integration

The session-end hook (scripts/hooks/session-end.js) automatically:

• Writes .clarc/context.md at session end (if .clarc/ exists)
• Appends to .clarc/progress.md
• Warns after 90-minute sessions without a context checkpoint

To opt in: mkdir .clarc in your project root.

Context Window Budget

Approximate token budget guidance. Context window size varies by model — check current limits at Anthropic docs. The proportions below apply regardless of the exact window size:

Component	Typical tokens	Notes
System prompt + rules	~8k	Fixed
Conversation history	~40k	Grows over session
Working files	~30k	Keep focused
Tool outputs	~20k	Flush when done
Available for new work	~30k	After 90 min session (assumes ~128k window)

When available budget drops below ~20k: checkpoint + compact.

Token-Efficient vs Token-Heavy Tool Usage

Before: Token-Heavy Pattern

Reading entire files on every step wastes context budget rapidly.

Turn 1: Read src/auth/jwt.ts         (800 tokens)
Turn 2: Read src/auth/jwt.ts again   (800 tokens — forgot it was already loaded)
Turn 3: Read src/middleware/index.ts  (1,200 tokens)
Turn 4: Read src/middleware/index.ts  (1,200 tokens — re-loaded for reference)
Turn 5: Read src/auth/jwt.ts         (800 tokens — needed one function again)
Total wasted re-reads: ~3,800 tokens

Compounded across a 50-file refactor, re-reads alone consume 20–30k tokens.

After: Token-Efficient Pattern

Turn 1: Read src/auth/jwt.ts
        → Write working note: "jwt.ts exports: verifyToken(token), signToken(payload, opts)"

Turn 2: Read src/middleware/index.ts
        → Append to working note: "middleware/index.ts mounts: auth (jwt), rateLimit, cors"

Turn 3: (work continues using the working note — never re-read jwt.ts)

# Working note stays under 200 tokens; replaces thousands of re-read tokens

Rule of thumb: After reading a file, extract the 3–5 facts you need from it into a working note. Use the note for the rest of the session; re-read the file only if you need the exact text (e.g., before an edit).

Recognising Re-Read Waste in Practice

These patterns signal you are re-reading unnecessarily:

• Same file appears twice in recent tool calls with no edit between them
• You read a file "just to check" something you noted earlier
• Each sub-task starts by re-reading the same config or schema file

When you notice this: stop, write a one-paragraph working summary, and continue from the summary.