872b0adb48
Split flat docs/ into user-docs/ (guides, config, troubleshooting) and dev/ (ADRs, architecture, extension guides, proposals). Updated docs/README.md index to reflect new paths.
2.2 KiB
2.2 KiB
State Machine & Context Management
The Fundamental Tension
The agent needs to understand the whole project to make good decisions, but any single context window degrades with too much information — not just from token limits but from attention dilution.
Layered Memory Architecture (Universal Agreement)
Project Manifest (always loaded, <1000 tokens)
↓
Task Context (per-task, relevant files + specs)
↓
Retrieval Layer (pull-based, on-demand)
↓
Ground Truth (filesystem, git, actual code)
| Layer | Content | Access Pattern | Token Impact |
|---|---|---|---|
| Working Context (L1) | Current task + 3–5 relevant files | Dynamically assembled per LLM call | 8k–25k tokens |
| Session/Episodic (L2) | Compressed history + recent decisions | Auto-summarized at transitions | Summary only |
| Project Semantic (L3) | Full codebase summaries, dependency graph, ADRs | Vector + Graph retrieval | Pointers only |
| Ground Truth (L4) | Actual files, git history, test results | Agent reads via tools | Zero in prompt |
The State Machine
The agent should always be in one explicit state:
PLAN → IMPLEMENT → TEST → DEBUG → VERIFY → DOCUMENT
Critical transitions that matter:
- Task completion: Defined by automated tests passing + acceptance criteria met
- Stuck detection: Triggered by repeated failed attempts or missing information
- Plan revision: Triggered when completed tasks reveal wrong assumptions
Key Principles
- Summarize aggressively between phases. Don't carry full implementation context forward — carry compressed summaries: what was built, what decisions were made, what interfaces were created.
- Pull-based, not push-based context. Don't preload everything the agent might need. Let it ask for what it discovers it needs.
- Use structured state for reliability. Natural language summaries drift. Use JSON/typed configs for anything the system needs to track. Reserve natural language for reasoning.
- The filesystem is external memory. The codebase itself is the most detailed representation of current state. Hold understanding about code in context, not the code itself.