/context-doctor

name: Context Doctor
id: context-doctor
description: Identify and repair degradation in system prompt, external memory, and skills preventing you from following instructions or remembering information as well as you should.

Context Doctor

Your context is what makes you *you* across sessions. You are responsible for managing it (along with memory subagents). It includes:

• Your system prompt and memories (contained in `system/`)
• Your external memory (contained in the memory filesystem)
• Your skills (procedural memory)

Over time, context can degrade — bloat and poor prompt quality erode your ability to remember the right things and follow instructions properly. This skill helps you identify issues with your context and repair them collaboratively with the user.

**IMPORTANT**: Your edits of your system instructions should be **conservative**. Do NOT make assuptions about what parts of the system prompt are critical. The system prompt defines who you are, so significant modifications to its structure can have unintended consequences. Focus on making minimal changes to meet the token budget, and to effectively link out to external memory.

Operating Procedure

Step 1: Identify and resolve context issues

Explore your memory files to identify issues. Consider what is confusing about your own prompts and context, and resolve the issues.

Below are additional common issues with context and how they can be resolved:

System prompt bloat

Memories compiled into the system prompt (contained in `system/`) should take up about 10% of the total context size (usually ~15-20K tokens). This is a soft target, not a hard requirement.

Use the built-in CLI to evaluate token usage of the system prompt:

letta memory tokens --format json --quiet

The command reports `total_tokens` and per-file estimates for `system/`. It is only a measurement tool; decide whether to intervene based on the actual context and the guidance below.

**Why detail is load-bearing (read this before cutting anything)**: In-context detail does more than carry information. It does at least four things, and byte-counting sweeps only see the first: 1. **Information** — the literal facts stated 2. **Attention anchoring** — makes certain topics feel important to the model when it's reasoning 3. **Semantic priming** — raises the prior on codebase-specific patterns ("this codebase has weird X, don't assume defaults") 4. **Reasoning templates** — past examples become heuristics for new bugs; rationale in "why" prose becomes scaffolding

Compression preserves (1). It destroys (2), (3), (4). That's why a compressed prompt can make an agent measurably worse at codebase-specific reasoning even though the explicit facts are all "still there" in reference files.

**Reference links (`[[path]]`) are NOT equivalent to in-context presence.** They're latent until the agent actively fetches them. An agent only fetches when it already knows it doesn't know. The priming cues that tell it *when* it doesn't know are in the system prompt itself — they can't be replaced by links.

**When to intervene**: Only if the system prompt is *meaningfully* over target. At or near the target, leave it alone. Every edit risks removing content that was doing work you can't see. A prompt that feels "a bit long" is almost always better than one that's been aggressively trimmed.

**Modifying the system prompt**: Make **MINIMAL** changes required to cut the token count of the system prompt if needed. The goal preserve the existing behavior while cutting down the token count. Focus on reducing redundancy or compressing - rather than offloading entire sections to external memory.

• Preserve persona-defining content (who you are, how you communicate)
• Preserve user identity or preferences (e.g. the human's name, their stated goals)
• Maintain the existing distribution of detail: compression should be applied evenly across all topics. If the original prompt was 50% about a specific issue, the new prompt should also be 50% about that issue.
• Only reduce noise and improve structure - if compression must result in information loss, preserve lost details into external memory

Context redundancy and unclear organization

The context in the memory filesystem should have a clear structure, with a well-defined purpose for each file. Memory file descriptions should be precise and non-overlapping. Their contents should be consistent with the description, and have non-overlapping content to other files.

**Questions to ask**:

• Do the descriptions make clear what file is for what?
• Do the contents of the file match the descriptions? (you can ask subagents to check)

**Solution**: Read all memory files (use subagents for efficiency), then:

• Consolidate redundant files
• Reorganize files and rewrite descriptions to have clear separation of concerns
• Avoid duplication by referencing common files from multiple places (e.g. `[[reference/api]]`)
• Rewrite unclear or low-quality content

Invalid context format

Files in the memory filesystem must follow certain structural requirements:

• Must have a `system/persona.md`
• Must NOT have overlapping file and folder names (e.g. `system/human.md` and `system/human/identity.md`)
• Must follow specification for skills (e.g. `skills/{skill_name}/`) with the format:

skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

**Solution**: Reorganize files to follow the required structure

Poor use of progressive disclosure

Only critical information should be in the system prompt, since it's passed on every turn. Use progressive disclosure so that context only *sometimes* needed can be dynamically retrieved.

Files that are outside of `system/` are not part of the sy