The fundamental issue isn't compaction itself—it's necessary given finite context windows. Rather, agents lacked mechanisms to store structural understanding outside conversations. Unlike human developers who leverage IDEs and documentation, AI agents had no external reference system. Uncompact was built to fill that gap.

The Solution

Uncompact maintains a persistent code graph that survives compaction events. When agents need codebase structure, they query this graph rather than re-reading files. The critical design principle: the graph must remain current. Stale information undermines agent confidence, so incremental updates trigger on every file save rather than complete rebuilds.

Installation

Setup requires running npm install -g uncompact --foreground-scripts followed by uncompact auth login with a Supermodel API key. The tool auto-registers as a Claude Code hook during initialization, requiring no additional configuration.

Technical Architecture

Instead of rebuilding entire graphs on changes, Uncompact processes only modified files and their immediate graph neighbors. Editing PaymentService.ts triggers re-analysis of that file and connected dependencies—the remaining graph stays unchanged. This approach mirrors incremental compilation principles.

User Experience Impact

Post-compaction, agents can query the graph for structural information ("What calls processPayment?") rather than searching retained context. The graph provides accurate, current answers independent of compaction frequency, enabling seamless context recovery.

Key Lessons

Simplicity matters. Early versions captured excessive detail. Effective versions focus on crucial relationships—the graph should answer structural questions, not replicate the source.

Invisibility enables adoption. Background processes requiring no maintenance drive usage. If developers have to think about the tool, they'll stop using it.

Layered verification works. Graphs indicate where to look; agents still examine actual code for specifics. The graph is a map, not a replacement for reading the territory.