Compress CLAUDE.md Files to Reduce System Prompt Bloat in Claude Code

Optimizing Claude Context Usage

Claude Code injects CLAUDE.md files into every conversation as system prompt context, including project-level CLAUDE.md, global files at ~/.claude/CLAUDE.md, and persistent memory system files. Every character in these files consumes context that Claude processes before addressing user requests, potentially reducing performance when signal-to-noise ratio is low.

The Compression Approach

The author proposes stripping human-readable decoration and keeping only machine-readable signal using these rules:

• Strip markdown decoration: Headers (##), bold (**), italic (*), horizontal rules (---)
• Collapse prose to notation: Use compact key-value pairs or pipe-delimited lists instead of explanatory sentences
• Remove redundant framing: Eliminate sentences like "This section contains..." or "The following table shows..."
• Deduplicate cross-file context: Keep identical information in one canonical location
• Compress table formatting: Replace verbose markdown tables with compact notation

Before and After Examples

Directory Index Table Example:

Before (markdown table):

## Directories
| Directory | What | When to read |
|-------------|-----------------------------|---------------------------------------|
| src/ | Application source code | Working on application logic |
| infra/ | Terraform and Ansible files | Modifying infrastructure |
| docs/ | Architecture documentation | Understanding system design |
| scripts/ | Deployment and utility scripts | Running or editing deploy workflows |

After compression:

Dirs: src/=application source | infra/=terraform+ansible | docs/=architecture docs | scripts/=deploy+utility scripts

Memory System Instructions Example:

Before:

## Memory System
Persistent memory lives at `/path/to/memory/`.
**Session start**: Read `memory/_index.md` to re-establish context when doing substantive work in this repo.
**During work** — Write to memory when something significant happens:
- A discovery or non-obvious finding → append to `memory/discoveries.md`
- A new skill applied or learned → update `memory/skills.md`

After compression:

Memory: /path/to/memory/
session-start: read _index.md for substantive work
during-work (write on significant events only, signal not noise):
discovery → append memory/discoveries.md
skill learned → update memory/skills.md

Compression Results

The author achieved the following reductions across files:

• _index.md: 3,560 → 2,036 characters (43% reduction)
• discoveries.md: 11,260 → 5,609 characters (50% reduction)
• interests.md: 4,315 → 2,561 characters (41% reduction)
• skills.md: 16,176 → 5,353 characters (67% reduction)
• career-timeline.md: 17,882 → 5,027 characters (72% reduction)
• ~/.claude/CLAUDE.md: 2,350 → 1,495 characters (36% reduction)

Total compressed memory system: 60,264 characters with roughly 60-70% reduction across the board. The project CLAUDE.md compressed even more aggressively.