prime-snapcompact #

visual archive compaction for Prime Agent, powered by @oh-my-pi/snapcompact.

instead of reducing an old conversation to text alone, the extension keeps an ordered plaintext and image archive while freeing context for later turns. a composable preparation extension keeps readable reasoning for compatible models, removes image bytes, drops orphaned tool results, keeps the newest three tool-result bodies, and replaces older bodies with placeholders. Claude-family targets omit replayed reasoning because Anthropic rejects prior assistant reasoning presented as transcript text. text-only models continue to use Prime's native compaction over the same projected history.

requirements #

• Prime Agent with composable session_before_compact preparation middleware (current Prime main; released 0.8.1 is too old)
• Bun 1.3.14 or newer
• npm, to install the locked runtime dependency

extensions run with your full user permissions. review the source before installing it.

install #

from a clone #

git clone REPOSITORY_URL prime-snapcompact
cd prime-snapcompact
npm ci --omit=dev
prime-agent package install .

package install . records the local checkout in ~/.prime/agent/settings.json. keep the checkout in place while the package is installed. choose one install method: leaving another copy under ~/.prime/agent/extensions/snapcompact/ loads the extension twice.

for one project only, run this from that project instead:

prime-agent package install /absolute/path/to/prime-snapcompact --local

directly from git #

Prime can clone and update a hosted repository itself:

prime-agent package install https://HOST/OWNER/prime-snapcompact

when Prime installs a git package, it also installs the package's runtime dependencies.

manual global install #

Prime also auto-discovers extension directories under ~/.prime/agent/extensions/:

git clone REPOSITORY_URL ~/.prime/agent/extensions/snapcompact
cd ~/.prime/agent/extensions/snapcompact
npm ci --omit=dev

restart Prime after installation. if Prime is already running, /reload loads the extension without a restart.

use #

SnapCompact is enabled by default for models whose input supports images. automatic and plain /compact operations use it. text-only models use Prime's native text compaction.

check or change the current session with:

/snapcompact status
/snapcompact on
/snapcompact off
/snapcompact gc

• status shows whether SnapCompact is enabled and whether the active model accepts images.
• on and off change the current session only.
• gc removes unreferenced SnapCompact artifacts for the current session.
• /compact your custom instructions deliberately uses native text compaction, so Prime keeps the documented custom-instruction behavior.

startup environment variables:

variable	meaning
PRIME_SNAPCOMPACT=0	disable new visual archives by default
PRIME_SNAPCOMPACT_BUN=/path/to/bun	use a specific Bun executable

storage and fallback #

artifacts live in Prime's native per-session artifact tree. session JSONL entries contain only small versioned references. artifact files use mode 0600, have bounded size, and are checked with no-follow regular-file reads, size, and SHA-256 on every use. symlinked artifact files or directory components are rejected. protected writes hold the checked directory inode through an exclusive no-follow final-file write.

these checks catch corruption, stale paths, and static symlink mistakes. they are not a sandbox against another process running as the same user, which can already read, move, or delete Prime's session files directly. stop active Prime processes before manually rearranging the artifact tree.

repeated compactions extend the existing archive. reasoning retention follows the active model on each pass. archives record whether their frames contain reasoning; switching such an archive to Claude uses sanitized text rather than replaying reasoning-bearing images. legacy archives are served as sanitized text until their next compaction. a truncated legacy archive exposes only its sanitized oldest text edge because its discarded middle may have split a serialized tool result; projection-version 3 archives apply reasoning policy and mask results before any visual slicing. interactive and CLI --fork sessions copy referenced immutable artifacts into the fork before the next request. CLI parent files must be canonical UUID-named Prime sessions whose header ID matches the filename; copied artifacts still pass size and SHA-256 checks. unreferenced files are collected after startup and compaction, or manually with /snapcompact gc.

if the SnapCompact worker fails, the first visual compaction falls back to native text compaction. an existing archive migrates to native text only when its complete recoverable text fits safely. otherwise compaction is cancelled and the prior archive remains intact.

request-time frame selection respects the model context window, provider image limits, estimated visual tokens, base64 size, and other images already present in the request. omissions are stated in model-visible text.

implementation #

projection.ts is a compaction preparation extension, loaded before index.ts by package.json. it returns replacement discard-side message groups through Prime's composable session_before_compact middleware contract. handlers run in load order, so SnapCompact receives the latest projection; the raw session entries remain untouched. older Prime hosts ignore preparation-return values, and unrelated handlers on those hosts do not inherit the projection, so index.ts projects its own input defensively and the requirements above still apply.

index.ts layers SnapCompact on the projected preparation and returns a normal Prime CompactionResult. the Bun worker turns that projected history into an ordered plaintext-and-image archive, then writes the archive as a separately integrity-checked artifact and stores only its reference in session history. for an image-capable model, the context hook replaces only the active compaction summary with the summary, bounded oldest/newest text edges, and selected ordered PNG frames; text-only or incompatible targets receive sanitized text instead. it does not patch Prime core or alter other messages. cancellation before persistence leaves the prior archive intact. custom /compact instructions deliberately take Prime's native text path, while a worker failure uses native text compaction when the archive can be recovered safely; otherwise the operation is cancelled rather than destroying the archive.

worker-v3.ts is the current one-shot Bun process. SnapCompact 18.0.8 exports TypeScript and uses Bun-native dependencies, so Prime's Node/Jiti runtime cannot safely load that dependency graph directly. the versioned worker exchanges bounded JSON over stdin/stdout, records whether an archive contains reasoning, validates PNG and archive data, supports cancellation, and uses a watchdog. older loaded extension instances can continue draining through their matching immutable workers.

worker protocol entrypoints are immutable. worker.ts remains as the v1 compatibility entrypoint for Prime processes that loaded an older index.ts before an in-place package update. a future protocol change must add worker-v4.ts and repoint the new index rather than overwrite a worker that an existing process can still call.

development #

install the exact development toolchain and run the full suite:

npm ci
env -u NO_COLOR FORCE_COLOR=0 npm test

set PRIME_AGENT_ROOT when Prime is not installed at /opt/homebrew/lib/node_modules/prime-agent:

PRIME_AGENT_ROOT=/path/to/prime-agent env -u NO_COLOR FORCE_COLOR=0 npm test

the suite type-checks both runtimes and covers initial and repeated archives, provider-aware reasoning retention, Claude-safe model switches, cjk-safe rendering, model-switch budgets, native migration, cumulative file tracking, artifact collection, manual compaction, automatic compaction, resume, and fork/restart/resume image rehydration through Prime's faux provider.