Read Cache & Structure Maps

Relevant source files

The following files were used as context for generating this wiki page:

• skills/token-optimizer/scripts/measure.py
• skills/token-optimizer/SKILL.md
• plugins/token-optimizer/skills/token-optimizer/references/implementation-playbook.md
• plugins/token-optimizer/skills/token-optimizer/references/optimization-checklist.md
• plugins/token-optimizer/skills/token-optimizer/references/agent-prompts.md
• plugins/token-optimizer/skills/token-optimizer/examples/claude-md-optimized.md

Read Cache and Structure Maps represent the architectural approach within the Token Optimizer project to manage how information is ingested and stored by Claude Code. The system focuses on minimizing redundant file reads and optimizing the structural layout of core configuration files to maximize the efficiency of prompt caching mechanisms. By deduplicating unchanged re-reads and tiered information layering, the project aims for a 5-15% context recovery.

The primary goal is to ensure that static, stable data is cached effectively (Tier 1), while volatile or task-specific data (Tier 2 and Tier 3) is loaded on demand. This prevents frequent cache invalidation caused by small changes in frequently updated sections of the context.

Sources: SKILL.md, references/optimization-checklist.md:33-46

Architecture and Tiered Storage

The project implements a tiered architecture for structure maps, specifically targeting CLAUDE.md. This strategy categorizes information based on its volatility and necessity during a session to maintain stable cache prefixes.

Tiered Architecture Components

Tier	Type	Content Description	Token Target
Tier 1	Static	Identity, critical rules, key paths, model routing.	~4,500 tokens / 300 lines
Tier 2	On-Demand	Workflows, domain documentation, specific tool configs.	Loaded via skills/commands
Tier 3	Explicit	Full guides, templates, detailed standards.	File references only

Sources: references/implementation-playbook.md:14-20, references/optimization-checklist.md:38-46

Data Flow for Prompt Caching

Prompt caching relies on stable prefixes. If volatile content is mixed with stable content at the beginning of a file, every change invalidates the cache for all subsequent turns. The structure map architecture mandates placing static content first and volatile content last.

Read Cache Mechanisms

The Token Optimizer manages redundant file reads through hook-based intercepts and native version-aware optimizations.

Version-Aware Read Deduplication

In versions v2.1.86+, Claude Code natively deduplicates unchanged re-reads using a compact line-number format. For these versions, the Token Optimizer disables redundant read_cache.py hooks to eliminate overhead.

• Hook: read_cache.py (PreToolUse)
• Variable: TOKEN_OPTIMIZER_READ_CACHE=0 (disables hook if native dedup is detected)
• Verification: python3 $MEASURE_PY read-cache-stats --session current

Sources: references/implementation-playbook.md:214-222

Smart Compaction and Checkpoints

While standard compaction is lossy, the project uses a "Structure Map" approach to session continuity called Smart Compaction. This involves checkpointing critical session state to disk before a compaction event occurs.

Optimization Scripts and Metrics

The measure.py script serves as the primary tool for auditing and managing the read cache and structure maps.

Key Monitoring Functions

• report: Authoritative gate for runtime detection and initial context overhead measurement.
• collect: Executed via the SessionEnd hook to gather usage data into a local SQLite database (trends.db).
• read-cache-stats: Specifically monitors the efficiency of read deduplication.
• quality: Analyzes session logs to identify "stale reads" (files read and subsequently edited) and "tool result bloat."

Sources: SKILL.md, references/optimization-checklist.md:353-370

Quality Signals in Structure Maps

The "Structure Map" is evaluated for quality based on several signals that indicate context rot:

Signal	Impact
Stale Read Ratio	Files read then edited; outdated content consumes space.
Tool Result Bloat	Large results never referenced again in conversation.
Decision Density	Ratio of substantive exchanges to overhead/confirmations.
Compaction Depth	Level of information loss due to repeated compaction events.

Sources: references/optimization-checklist.md:359-370

Implementation Playbook for Structures

Implementing optimized structure maps requires specific consolidation steps for CLAUDE.md and MEMORY.md.

CLAUDE.md Consolidation Steps

1. Identify: Use agent-prompts.md for the CLAUDE.md Auditor to find verbose sections (>50 lines).
2. Layering: Move workflow-specific instructions to local skills.
3. Reference Refactoring: Replace @imports (which pull entire files into every message) with on-demand skill calls or Tier 3 references.
4. Restructuring: Ensure identity and model routing appear in the static (cached) prefix.

Sources: references/implementation-playbook.md:12-25, references/agent-prompts.md:17-48

MEMORY.md Deduplication

The structure map for MEMORY.md is restricted by a 200-line auto-load cap.

• Action: Remove content duplicating CLAUDE.md (Key Paths, personality).
• Action: Condense verbose operational history to only the current applicable rules.
• Action: Move detailed topic notes to specific files in a dedicated memory/ directory to avoid truncation.

Sources: references/implementation-playbook.md:33-45, references/optimization-checklist.md:49-57

Summary

Read Cache and Structure Maps are the project's primary defense against context window saturation. By moving from monolithic configuration files to a tiered, on-demand architecture, the system leverages prompt caching for stable data while maintaining session continuity through disk-based checkpoints. Version-aware monitoring ensures that these optimizations complement Claude Code's native features without adding unnecessary processing overhead.