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. this preserves more code, tool output, and layout while freeing context for later turns. text-only models continue to use Prime's native compaction.

requirements#

Prime Agent 0.8.1, or a compatible extension API
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.

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 SHA-256 before use.

repeated compactions extend the existing archive under whatever model is active; a model switch only changes which model is recorded as the archive's producer, never the compaction path. if the active model cannot accept images, the next compaction migrates the archive to native text compaction to preserve history safely. request-time notices alert once per compaction when an archive is read by a model without image support. forks copy referenced immutable artifacts into the fork before the next request. 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 carrying as much archive text as that request's budget leaves room for; the migration announces its token estimate and states how much archive text it drops. when the archive cannot fit next to the current messages at all, or the migrating call fails, compaction still runs natively without the archive text and says so, instead of cancelling; the archive file is left untouched.

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#

index.ts is the Prime extension. it intercepts session_before_compact and returns a normal Prime CompactionResult. its context hook expands only the active compaction summary with the ordered archive blocks. it does not patch Prime core or alter other messages.

worker.ts is a 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 worker exchanges bounded JSON over stdin/stdout, validates PNG and archive data, supports cancellation, and uses a watchdog.

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, cjk-safe rendering, model switches and provider-lane flips reading and compacting on the visual path unclamped, migration notices and their token estimates, over-budget native fallback, native migration, cumulative file tracking, artifact collection, manual compaction, automatic compaction, resume, and fork/restart/resume image rehydration through Prime's faux provider.

Configure Feed