context-management

Context Management

Overview

AI assistant context windows are finite. Long tasks get compacted, earlier decisions are forgotten, and continuity breaks. Context management is the practice of preserving critical information so work survives compaction.

Core principle: If it matters after the current conversation, write it down. Memory is the enemy of continuity.

Iron Law:

EXTERNAL STATE > INTERNAL MEMORY
Write decisions to files. Files survive compaction; conversation memory does not.

When to Use

• Starting a task that will span multiple sessions
• Beginning PLAN mode (decisions must survive to ACT)
• Completing ACT mode (progress must survive to EVAL)
• When conversation is approaching context limits
• Before any context compaction event
• When resuming work after a break

The Context Document (codingbuddy)

The primary context persistence mechanism is docs/codingbuddy/context.md.

docs/codingbuddy/context.md
─────────────────────────────
This file is:
- Created/reset by PLAN mode
- Appended by ACT mode
- Appended by EVAL mode
- Always at a fixed, predictable path
- Safe to read at any point

What Goes in Context

PLAN mode writes:

• Task description
• Key design decisions and their rationale
• Architecture choices
• Dependencies and constraints
• Recommended ACT agent

ACT mode writes:

• Progress milestones completed
• Files created/modified
• Implementation decisions made
• Issues encountered and resolved
• Next steps

EVAL mode writes:

• Quality findings (with severity)
• Security issues found
• Performance observations
• Recommendations for next iteration

Context Document Format

# Context: [Task Title]

## PLAN — [timestamp]
**Task:** [Original task description]
**Primary Agent:** solution-architect
**Recommended ACT Agent:** agent-architect

### Decisions
- Decision 1: [What was decided and why]
- Decision 2: [What was decided and why]

### Notes
- Implementation note 1
- Constraint or dependency to remember

---

## ACT — [timestamp]
**Primary Agent:** agent-architect

### Progress
- [x] Created RulesService with search capability
- [x] Added Tests: 12 passing
- [ ] SSE transport implementation pending

### Notes
- Used glob for file discovery (faster than readdir recursion)
- NestJS module structure: McpModule → RulesModule

---

## EVAL — [timestamp]

### Findings
- [HIGH] Missing rate limiting on /sse endpoint
- [MEDIUM] Test coverage at 72%, below 80% target

### Recommendations
- Add rate limiting middleware
- Add tests for error cases in RulesService