command-center/omp-docs/core/snapcompact.md

type, title, description, resource, tags, verified, timestamp

type	title	description	resource	tags	verified	timestamp
concept	OMP Snapcompact — Bitmap-Frame Compaction	How snapcompact archives session history as bitmap frames, what shape frank-archon resolves to, the measured recall/billing table behind the fleet's settings, and the models.yml knobs that actually exist.	https://github.com/can1357/oh-my-pi/tree/main/packages/snapcompact	omp compaction snapcompact frank-archon	2026-10-27	2026-10-27

OMP Snapcompact — Bitmap-Frame Compaction

Snapcompact is omp's automatic-maintenance method that replaces the LLM summarizer call with a local, deterministic archival pass: discarded history is serialized, whitespace-collapsed, and printed onto dense PNG frames of pixel-font glyphs that a vision-capable model reads back directly. No model, key, or network is involved, so it also serves overflow recovery. It runs only when the current model's row declares input including image; otherwise maintenance advances to the next method in compaction.methodOrder.

Fleet position (agent/config.yml): methodOrder: [shake, snapcompact, soft, handoff, remote] — deterministic, lossless-first. Shake elides heavy blocks to artifact:// references before anything is archived; snapcompact then archives what shake couldn't reclaim; the lossy LLM lanes (soft/handoff/remote via frank-zealot) should never be reached while a vision endpoint is active.

Shape resolution for the fleet

The frame shape (font grid + pitch + frame width) resolves from the model id against a measured table, falling back to the wire API family when the id is unmeasured:

Matcher	Shape	Frame
claude (fable/mythos)	11on16-bw	1932px
claude	11on16-bw	1568px
gemini	8on22-bw	2048px
gpt / codex	8on22-bw	1568px
kimi	8on22-bw	1568px
glm	8on16-bw	1568px
openai-completions wire (unmeasured id)	8on22-bw	1568px

There is no qwen matcher: frank-archon (radiance, Qwen3.8 vision tower, openai-completions wire) resolves via the wire fallback to 8on22-bw @1568px — which is 56 clean 28px token-rows for a Qwen-style ViT. snapcompact.shape stays auto; forcing a variant would bypass the font-aware CJK escape hatch (silver16-bw).

Measured recall and billing (frank-archon, 2026-10-27)

A 212,916-char tool-traffic transcript with 8 planted unique facts was sent to frank-archon four ways (probe: @oh-my-pi/snapcompact renderer, production request shape, omp 18.12.5-era bundle):

Leg	Frames	Billed prompt tokens	Recall
Plain text baseline	—	63,066	8/8
auto = 8on22-bw	14	33,533	8/8
forced 8on16-bw	11	24,364	6/8 (dropped characters)
forced 11on16-bw	14	33,533	6/8 (dropped characters)

Laws this established:

• The default shape is the accurate one for the fleet. The Qwen3.8 FP8 tower OCRs 8on22-bw pixel fonts with full recall; both denser grids drop single characters inside identifiers — matching upstream's toolbench finding (spacing-tuned cells won everywhere; dense prose-era shapes erase line structure).
• Bitmap archive ≈ 47 % of the billed tokens of raw text at equal recall.
• True radiance billing is ~2,400 tokens/frame; the harness charges a blind 5,024 floor. Unpriced custom endpoints get FRAME_TOKEN_ESTIMATE (5,024) per frame in archive sizing, so archives plan roughly half the frames the window actually fits. This is conservative (never overflows) and costs recall-per-compaction.

The knobs that exist (and the one that doesn't)

• imageCountBudget: 16 (top-level models.yml row field, set on frank-archon): the catalog never matches custom providers, so the unknown-provider floor of 5 images per request silently caps archives. Radiance accepted 14 frames in one probe request; 16 leaves margin. Real frame count stays bounded by the sizing law below.
• imageTokenization is catalog-only (compiled KDL compat rules; no user-row key reaches the pricing path). A custom row cannot mark frames verified or price them — until upstream prices openai-completions vision, custom-endpoint archive capacity is count-bound.
• Archive sizing law: frames get half the room left under the compaction threshold after system prompt, tools, and kept recent turns; the compacted result targets ≤ 60 % of threshold, and post-compaction headroom must reach the 80 % recovery band.
• snapcompact.systemPrompt: none and snapcompact.toolResults: false stay off fleet-wide: imaging inline text is a token-cost lever that routes always-loaded instructions through the OCR path — accuracy-negative.

The 85 % trigger law

compaction.thresholdPercent: 85 on frank-archon is load-bearing for the max_tokens clamp documented in agent/models.yml: 170,000 est × 1.03 + 16,384 ≤ 200,000. At 95 % the clamp squeezes output to ~6 k near the trigger and the worst-case request overshoots the window, so radiance refuses and compaction reroutes through the overflow-recovery emergency path instead of the planned threshold pass.

Follow-ups

• frank-dragoon / frank-zealot rows carry the same unpriced vision towers; the count budget and probe apply to them but are unmeasured there.
• Re-run the probe after the next upstream snapcompact/omp release (renderer and shape table move under us).