Snapcompact & Context Compression
Relevant source files
The following files were used as context for generating this wiki page:
Snapcompact is a specialized context compression system designed for vision-capable Large Language Models (LLMs). Instead of traditional summarization—which requires additional LLM calls and latency—Snapcompact utilizes a local, deterministic process to serialize conversation history into dense PNG frames of pixel-font glyphs. These frames are then read directly by vision models, preserving historical context without consuming massive text token windows or incurring API costs for summarization.
The system is integrated into the oh-my-pi compaction pipeline to manage long-running agent sessions. By rasterizing text into images, the system bypasses traditional text context limits and provides a "visual memory" of previous turns that remains accessible to the agent.
Sources: packages/snapcompact/README.md:3-9, packages/coding-agent/DEVELOPMENT.md:105
Architectural Overview
The compaction architecture is built around a local-first pipeline that transforms discarded conversation history into a structured archive and a set of visual frames. This process is handled by the @oh-my-pi/snapcompact package and integrated into the broader AgentSession lifecycle.
The Compaction Pipeline
The following diagram illustrates the flow of data from raw conversation history to a compressed visual format.
The diagram shows the sequential transformation of text history into image-based context.
Sources: packages/snapcompact/README.md:11-20
Key Components
| Component | Responsibility |
|---|---|
serializeConversation | Converts conversation objects into compact text with character caps on tool results and arguments. |
normalize | Strips ANSI sequences, collapses whitespace, and folds newline runs into block glyphs. |
render / renderMany | Local rasterization of text into PNG frames using native code. |
resolveShape | Selection of provider-optimal image dimensions based on model evaluation. |
Sources: packages/snapcompact/README.md:11-20, packages/snapcompact/README.md:55-65
Provider-Aware Optimization
Snapcompact optimizes the rasterization process based on the specific vision model being used. Different providers (Anthropic, Google, OpenAI) have different billing logic and resolution requirements for image inputs. The resolveShape function ensures the most efficient frame geometry is used for a given model ID.
Supported Shapes and Configurations
| Reader | Default Shape | Optimization Notes |
|---|---|---|
| Anthropic | 6x12-dim | Uses X.org 6x12 glyphs; stopwords are dimmed. Frames are sized up to 1932px for Claude high-res lines. |
doc-8on16-sent-dim | Two-column newspaper layout with sentence-hue ink. Optimized for fixed per-image budgets in Gemini. | |
| OpenAI | 8on16-bw | 8x13 glyphs on 16px patch-aligned pitch; intended for detail: "original" mode. |
Sources: packages/snapcompact/README.md:22-35
Integration with Agent Sessions
Within the oh-my-pi ecosystem, compaction is a lifecycle event managed by the session logic. It is part of the AgentSession and session-tree architecture, ensuring that as branches grow, the context remains manageable.
Context Management Logic
When a context rebuild occurs, the system re-attaches the preserved visual frames to the summary message. This allows the agent to "see" the history of the conversation in its current turn.
The sequence diagram details how Snapcompact interacts with the AgentSession to provide context to the LLM.
Sources: packages/snapcompact/README.md:18-20, packages/coding-agent/DEVELOPMENT.md:105-112
Implementation Details
Snapcompact requires Bun ≥ 1.3.14 and leverages @oh-my-pi/pi-natives for high-performance rasterization and PNG encoding.
// Example of rendering history into image blocks
import { renderMany, compact } from "@oh-my-pi/snapcompact";
// Perform a full compaction pass
const result = await compact(preparation, { model });
// result.summary contains the lead-in and reading guide
// result.preserveData contains the PNG images
Sources: packages/snapcompact/README.md:37-53
Summary of Usage within the Project
Snapcompact serves as the primary mechanism for "Compaction and Branch Summaries" in the omp CLI. It ensures that complex multi-file architectural tasks—which generate significant history—do not crash the agent's context window. By transforming text into pixel-dense images, the system provides a persistent, low-cost memory of past actions, tool outputs, and research findings discovered by explore or librarian agents.
Sources: packages/coding-agent/DEVELOPMENT.md:105, packages/coding-agent/src/prompts/agents/explore.md:1-5, packages/coding-agent/src/prompts/agents/init.md:1-10