Note
CCR compression proxy + absorptive preview pipeline for Hermes Agent. Up to 610× compression on the standard corpus (132× overall), ~10 ms end-to-end, type-aware classifier, TOML-driven templates, config auto-reload (default on). One binary. Zero dependencies. Millions of tokens saved.
Aphrodite ships as a Hermes plugin (Rust dylib + standalone proxy binary). No Rust toolchain is required for the common path.
Terminal
git clone https://github.com/PlayForm/Aphrodite-Hermes.git
cd Aphrodite-Hermes
ln -s "$(pwd)" ~/.hermes/plugins/aphrodite
bash download.sh # explicit setup step: binary + dylib from GitHub Releases
cd ..
hermes plugins enable aphrodite
hermesBinaries are never shipped in the repository and register() never downloads:
run the explicit setup step bash download.sh (or pwsh ./download.ps1 on
Windows) from the plugin clone, which fetches the aphrodite binary and the
dylib from releases into
~/.hermes/aphrodite/binaries/ with SHA-256 verification. If the binaries are
missing, the plugin logs the setup command and stays disabled until they are
present.
Important
Use the Hermes plugin method on Windows too - run pwsh ./download.ps1
(native PowerShell) as the explicit setup step instead of download.sh. See
docs/install/windows.md.
Prefer a source checkout (Option A above) for the Hermes plugin - it is a git
folder by design, and cargo install alone does not ship the plugin code.
The two routes are alternatives: if you install via git clone, you do not need
cargo install, and vice versa.
Terminal (binary + config only)
cargo install aphrodite # proxy binary
cargo install aphrodite-hermes # dylib + helper bin
aphrodite setup # runtime home under ~/.hermes/aphrodite + hooks-only loader in ~/.hermes/plugins/aphroditecargo install copies only [[bin]] targets into ~/.cargo/bin/ and never
links the plugin into Hermes. aphrodite setup writes the hooks-only loader
(plugin.yaml + __init__.py) into ~/.hermes/plugins/aphrodite, registers
the plugin, and keeps everything else (binaries, config, state) under
~/.hermes/aphrodite/ - or follow Option A (git clone + ln -s).
Terminal
git clone https://github.com/PlayForm/Aphrodite.git
cd Aphrodite
git submodule update --init --recursive
cargo build --release -p aphrodite -p aphrodite-hermesThe proxy sits in front of an upstream LLM API, so it needs that API's key -
Hermes' own provider config is not reused. api_key resolves
[[proxies]] api_key → [defaults] api_key → APHRODITE_API_KEY, and the
proxy refuses to start when the chain resolves empty
(no API key configured - set APHRODITE_API_KEY env var or api_key in aphrodite.toml).
export APHRODITE_API_KEY=sk-... # env var
aphrodite setup --api-key sk-... # or write it through setup# ~/.hermes/aphrodite/aphrodite.toml
[defaults]
api_key = "sk-..." # or per listener: [[proxies]] api_keycurl -s 127.0.0.1:9797/health
# {"status":"healthy","ccr":true,"mode":"cache","version":"1.8.1","fill_pct":90.0,...}
curl -s 127.0.0.1:9797/version
# 1.8.1
curl -s 127.0.0.1:9798/stats
# {"mode":"token","proxy":"aphrodite","ccr_backend":"enabled","tool_relay_enabled":true,...}Inside a session the same information arrives as tools: aphrodite_stats
(proxy health, engine status, inline store size) and aphrodite_rebuild
(binary and dylib version plus a rebuild hint).
Every file read, build, code search, or browser open floods the agent's context with raw output - compilation logs, accessibility trees, JSON blobs. The agent spends its budget reading noise instead of reasoning.
Aphrodite intercepts output before it reaches the LLM and replaces it with a compact, structured preview. The agent sees ~15 tokens of metadata instead of hundreds - and retrieves the full content only when it actually needs it.
Pipeline
ANY OUTPUT ────────► Aphrodite ────────► Agent (preview, not raw)
│
├─ build log → [build:2E 5W 210L | error[E0432]: ...]
├─ cargo test → [test:220 pass 0 fail 1 ignored | 0.31s]
├─ terminal → [terminal:14L exit code: 0]
├─ Rust file → [code:3fns|2structs fn main() 414L]
├─ Python file → [code:2fns|1class def handle() 87L]
├─ grep/ripgrep → [grep:4 hits in 3 files | src/x.rs:12 ...]
├─ search_files → [search:15 hits in 3 files | src/x.rs:12 ...]
├─ git status → [git:2M 1A 1D 3?? | src/x.rs +N more]
├─ git log → [gitlog:2 commits | abc1234 fix... → def5678 feat...]
├─ diff → [diff:2F +7/-3 12L | src/main.rs Cargo.toml]
├─ ls / find → [ls:12 files 0 dirs | .rs×10]
├─ JSON blob → [json:30 keys 1L | status, error, ...]
├─ web page → [html:8h 42a 3img 342L | Aphrodite Docs]
├─ compiler err → [error:2L 120B | error: could not compile ...]
├─ app log → [log:12L 540B | [INFO aphrodite] proxy starting]
└─ plain text → [text:3L 50B | first line hint ...]
Agent decides:
• Preview is enough → skip retrieval, keep reasoning
• Needs detail → aphrodite_retrieve(hash) → full content
Four fast layers (classification 40-123 ns; whole compress step sub-millisecond):
- Classify - type-aware classifier identifies content.
- Preview - enriched, type-aware previews produced automatically.
- Store - BLAKE3 → SQLite/in-memory →
<<<CCR:hash|type|size>>>marker. - Decide - agent reads preview, retrieves only when needed.
The context engine's pre_llm_call hook auto-compresses overflowing middle
turns to CCR as the session fills, so the agent never hits the context
ceiling.
A real session against this repository. The markers and preview lines below are verbatim - this README was written by an agent whose context looked exactly like this.
ls at the repo root - 32 entries, 377 bytes:
<<<CCR:c5e9b7d52756100736cf1c40ccd36b2e9b718841|ls|377>>>
[ls:32 files 0 dirs | .toml×6 .md×5 .lock×2]
find . -name '*.md' - 172 paths, 3,984 bytes:
<<<CCR:958522eb61f963cd9f4ce24ff21490b583fdb166|ls|3984>>>
[ls:172 files 0 dirs | .md×172]
ls crates/aphrodite/src - 34 files across 9 directories, 640 bytes:
<<<CCR:14b3d51415867039316d2c80f540123db86cf891|ls|640>>>
[ls:34 files 9 dirs | .rs×22]
Three tool calls, 5,001 bytes of listings, 279 characters in context - 18x less. The agent knows how many files, which directories, and which extensions - the shape of the answer - without holding a single path. When a path matters it asks for it:
aphrodite_retrieve("14b3d51415867039316d2c80f540123db86cf891")
{"found": true, "source": "ccr", "hash": "14b3d51415867039316d2c80f540123db86cf891",
"content": "builtin_directives\ncatalog.rs\nchain_split.rs\nconfig\n..."}
The size field is the price of that call: 640 bytes re-enter context when the
marker resolves, zero when it does not. Markers persist for the whole session,
so deferring is free and retrieving is always one call away.
One turn, end to end:
- Session start -
on_session_startboots the engine, seeds the active directive set into~/.hermes/aphrodite/directives/, and health-checks the proxies. - Tool call -
pre_tool_calldecides dispatch: prefetch-aware, and slow terminal or process calls are auto-backgrounded bypoll_worker. - Tool result -
transform_tool_result(ortransform_terminal_outputfor shell) classifies, previews, stores, and relays the marker. - Before the model call -
pre_llm_callinjects the active directives within[flow] budget_chars, and archives overflowing middle turns to CCR once the session passesengine_threshold_pct. - After the model call -
post_llm_callrecords savings and updates the adaptive threshold EMA. - Retrieval - whenever the agent asks:
aphrodite_retrieve(hash)returns the stored bytes unchanged.
Nothing is rewritten retroactively. A marker stored in turn 3 is the same marker in turn 40, and the content behind it never changed - which is why retrieval is always safe.
Directives are short behavioral instructions injected each turn and swappable mid-conversation. Seven ship inside the binary:
| Directive | Focus |
|---|---|
focus |
Targeted execution, marker-aware retrieval |
foresight |
Anticipate and prefetch; never wait on I/O |
lazy |
Defer work, activate on demand, never busy-spin |
lazy-eval |
Accumulate markers, resolve on demand |
explore |
Read broadly, prefetch aggressively |
cleanup |
Catalog, summarize, verify nothing is left behind |
ccr-handling |
How to read markers and retrieve the content behind them |
[directives] active = [...] selects the set - an empty list seeds focus +
foresight + lazy - and aphrodite_directive swaps it mid-session.
Directives change what the model does with markers; they never change the
marker format.
- TOML templates -
[templates.preview.<family>.<ctype>]format strings,[templates.marker]format + hint,[templates.prompts]prompt templates, and[templates.reverse]ctype→key remap. Per preview the resolution isfamily[ctype]→reverse[ctype]→family[_default]→ the hardcoded builder;[previews] model_familyselects the family (defaultcode_first). - Auto-expand -
[compression] auto_expand/auto_expand_limit(default limit 102400; the shipped example enables it) resolve markers inline in the proxy and on the hook side as the session fills. - Context engine -
engine_threshold_pct/engine_protect_first/engine_protect_last/engine_min_msgsdrive middle-turn archiving to CCR plus theengine_offloadprompt injection, so sessions never hit the context ceiling (defaults: threshold 30, protect 2+5, min 8). - Live containers -
APHRODITE_LIVE_CONTAINERenv or[compression] live_container = trueemits instant CCR markers with thelivetype and progressive chunked retrieval with ETA. - Rhai scripting - optional
scriptingCargo feature (rhai pinned 1.25.1) for scripted pipeline extensions. - Prompt knobs -
retrieve_guidance,ccr_marker_hint,catalog_intent_hintsare wired; caps viaAPHRODITE_RECURSIVE_DEPTH/recursive_depth(default 5) andAPHRODITE_MAX_REQUEST_BODY_SIZE/max_request_body_size.
Aphrodite classifies every blob of tool output before compressing it - errors
stay visible while verbose logs get squeezed. The classifier (preview.rs,
wrapping the Headroom content_detector) returns one type per invocation,
first match wins, and each type carries its own compression threshold tier.
| Content type | Detected from | Enriched preview shape |
|---|---|---|
build / build_output / build_error |
Compiling / Finished / running / test first line |
[build:1E 1W 142L | error[E0432]: unresolved import ...] (first error message) |
diff |
diff --git / @@ - / +++ / --- headers |
[diff:2F +7/-3 12L | src/main.rs Cargo.toml +N more] (first file names) |
git (status) |
porcelain status codes (M/A/D/R/??/UU, majority) |
[git:2M 2A 1D 3?? | src/x.rs src/y.rs +5 more] (code tallies + paths) |
gitlog |
commit <hash> blocks + Author: |
[gitlog:2 commits | abc1234 fix... → def5678 feat...] (first→last hash/subject) |
ls / dir |
ls -l mode strings / bare path tokens (majority) |
[ls:3 files 2 dirs | .rs×2 .md×1] (counts + top extensions) |
test / test_output |
test result: / === RUN / pytest / jest summaries |
[test:220 pass 0 fail 1 ignored | 0.31s] (or | FAIL name on failure) |
grep / ripgrep |
path:line:match hits (majority) |
[grep:4 hits in 3 files | src/preview.rs:12 ...] (hits, files, first location) |
code_rust |
fn/impl/struct/enum + (-> or & or use) |
[code:3fns|2structs fn main() 414L] (structure map + first signature) |
code_python |
def + (import/class/from/self.) |
[code:2fns|1class def handle() 87L] |
code_go |
(func/package) + import ( |
[code:4fns func main() 210L] |
code_js / code_ts |
(function/const/=>) + (import/export) |
[code:3fns export default 145L] |
code (generic) |
fn/def/class/import fallback |
[code:2fns 96L] |
search |
search-result JSON (total_count + query) |
[search:15 hits in 3 files | src/x.rs:12 ...] |
json / json_array |
starts with { / [ and parses as JSON |
[json:5items 3L] or [json:30 keys 1L | status, error, ...] |
tool_output |
JSON containing exit_code or "status" |
[tool_output:1L 58B | {"exit_code": 0, "output": "ok"}] |
terminal |
shell/exit-code traces (hook override) | [terminal:14L exit code: 0] (exit code / last output line) |
error |
first-line error/Error/Traceback/panic |
[error:2L 120B | error: could not compile `aphrodite`] |
log |
[INFO/WARN/ERROR/DEBUG/TRACE] or timestamp prefix |
[log:12L 540B | [2026-09-15T10:00:00Z INFO aphrodite] ...] |
linter |
error[E/error:/warning:/clippy/tsc |
[linter:4L 260B | error[E0308]: mismatched types] |
text (fallback) |
unrecognized content | [text:3L 50B | some unrecognizable prose here] (first non-empty line) |
Note
When the classifier only reaches a generic bucket (text/terminal/log),
an Aphrodite-side semantic detector (detect_semantic_type) upgrades it to
the high-signal shapes - git, gitlog, grep, ls, test - before the
preview is built. Detection is conservative (line-prefix patterns, majority
votes), so ordinary prose is never mis-tagged.
Full taxonomy: docs/classification/content-types.md.
Each type maps to a compression threshold group - the higher the multiplier, the longer content stays visible in context before being compressed:
| Tier | Types | Multiplier |
|---|---|---|
| Error | error |
×8 |
| Code | code_rust, code_python, code_go, code_js, code |
×1.0 (scaled by code_multiplier) |
| Diff / tracked | diff, git, text |
×2 |
| Default | tool_output, json, everything else |
×1 |
| Noisy (BASE) | linter, build_output, log |
×1 (never halved) |
Compressed content becomes a CCR marker. Every retrieval entry point
(aphrodite_retrieve, /retrieve, resolve) accepts the marker body
directly, with or without the |type|size suffix:
[build:1E 1W 142L | error[E0432]: unresolved import ...]
<<<CCR:0e3a5c9f2b8d4e6a1c3f5b7d9e0a2c4b6d8f0a1e|build|1420>>>
- Hash - full 40-char lowercase BLAKE3 digest (
[0-9a-f]{40}). - Type - one of the content types above.
- Size - original byte count.
- Preview - the enriched preview line above the marker, so the agent can decide without retrieving.
Aphrodite compresses output in two modes:
| Mode | How it intercepts | Coverage |
|---|---|---|
| Plugin | Hermes hooks (transform_tool_result, transform_terminal_output, context engine) intercept output directly - no API round-trip |
File reads, terminal output, search results, browser snapshots, every tool result |
| Proxy | Reverse proxy between any client and an LLM API; Chat Completions responses compressed via CCR; tool relay for bidirectional calls | OpenAI-compatible clients, Claude, any LLM API |
Repository
crates/aphrodite/ ← Core engine (binary + cdylib)
main.rs ← CLI entry, version intercept, config bootstrap
lib.rs ← Crate surface shared by the binary and the cdylib
proxy.rs ← HTTP proxy: classify → compress → store → preview; SSE pass-through; tool relay
hooks.rs ← transform_tool_result, transform_terminal_output, session/LLM hooks
retrieve.rs ← /retrieve endpoint + retrieval plumbing
templates.rs ← TOML template resolution (preview/marker/prompts/reverse)
stage2.rs ← Semantic reduction (JSON minify, build, diff, code)
session.rs ← Session state, turn history
catalog.rs ← CCR catalog listing (TOC, tool formats)
prefetch.rs ← Background file prefetch → CCR
poll_worker.rs ← Auto-backgrounding of slow tool calls
chain_split.rs ← Opt-in fine-grained command splitting
flow.rs / home.rs ← Plugin bootstrap and runtime-home resolution
debug.rs ← Per-session debug switch
scripting.rs ← Optional Rhai scripting feature
preview/ ← Type detection + enriched preview builders
detect.rs type.rs lang.rs input.rs state.rs
builders/ detectors/ line/ text/
marker/ ← Marker parsing, formatting, hash normalization (parse.rs, format.rs)
resolve/ ← Recursive marker resolution (expand, one, recursive, filter)
struct_extract/ ← Code structure maps (rust, python, go, js)
config/ ← TOML schema, env overrides, multi-proxy resolution (cli.rs, env.rs, proxy.rs)
config_loader.rs ← Dylib-side config load + auto-reload
state/ ← AppState: counters, store, markers, files, events, chain-split
directives/ ← Directive registry (model, load, build, builtin, action)
setup/ ← `aphrodite setup`: dylib install, verify, macOS wiring
builtin_directives/ ← Shipped directive markdown (focus, foresight, cleanup, explore, lazy, lazy-eval, ccr-handling)
crates/aphrodite-hermes/ ← Hermes bridge (cdylib)
lib.rs ← FFI surface, hook dispatch
tools.rs ← 13 tool dispatch handlers
schemas.rs ← JSON Schema definitions
directives.rs ← Directive FFI
debug.rs ← Debug FFI
bin/setup-helper.rs ← Setup helper binary
plugins/aphrodite/ ← Thin Python loader (ctypes FFI) + plugin manifest
__init__.py ← loads the dylib, registers hooks / tools / engine
_bindings.py ← Generated ctypes bindings (cbindgen → ctypesgen)
plugin.yaml ← Manifest: 6 hooks, 13 tools, context engine
BINARY_VERSION ← Distribution pointer for the binary release
download.sh / download.ps1 ← Binary + dylib fetch from GitHub Releases
layout_check.py / layout_schema.json ← Runtime-home layout contract
Plugin mode
Tool executes → output intercepted by hook
↓
classify → preview → store (SQLite / in-memory / inline)
↓
Agent ← [type:enriched preview] (not raw output)
↓
aphrodite_retrieve(hash) → full content (only when needed)
Proxy mode
Client → Aphrodite (:9797 / :9798) → Upstream LLM API
↓
compress Chat Completions response
↓
Client ← CCR markers replace raw content
| Listener | Port | CCR backend | Threshold | Tool relay | Best for |
|---|---|---|---|---|---|
| Cache | :9797 | In-memory (DashMap, 10K entries) | >8 KB | No | Speed, transient sessions |
| Token | :9798 | SQLite (persistent) | >1 KB | Yes | Durability, tool relay |
Six Hermes hooks drive the plugin (provides_hooks in plugin.yaml):
| Hook | Role |
|---|---|
on_session_start |
Engine bootstrap, directive seeding, proxy health check |
transform_tool_result |
Compress every tool result before it reaches the LLM |
transform_terminal_output |
Compress terminal output with exit-code context |
pre_llm_call |
Inject directives, compress overflowing middle turns |
post_llm_call |
Capture savings, update adaptive thresholds |
pre_tool_call |
Prefetch-aware dispatch, auto-background slow calls |
The proxy exposes loopback-only management routes (auth via
APHRODITE_MGMT_TOKEN when set; /health and /metrics are exempt):
| Route | Method | Role |
|---|---|---|
/health |
GET | Liveness probe (public) |
/health/upstream |
GET | Upstream API probe (60s cache) |
/version |
GET | Binary version (CARGO_PKG_VERSION) |
/stats |
GET | JSON counters, EMA, per-type compression |
/stats/db |
GET | CCR store statistics |
/metrics |
GET | Prometheus text format (loopback only) |
/history |
GET | Request history |
/retrieve |
POST | Resolve <<<CCR:hash|type|size>>> markers |
/ccr/create |
POST | Programmatic CCR creation |
/ccr/list |
GET | Catalog listing |
/ccr/{hash} |
DELETE | Evict an entry |
/reload |
POST | Re-apply live [compression] fields from aphrodite.toml |
/tool/relay |
POST | Bidirectional tool relay (token mode) |
Note
All compression logic lives in the Rust dylib; Python is a thin FFI loader. The dylib is loaded once per process - there is no live reload. A rebuilt dylib takes effect only after the Hermes session is restarted.
Note
plugins/aphrodite/ is a separate repo
(PlayForm/Aphrodite-Hermes),
tracked here as a git submodule.
Thirteen tools ship with the plugin:
| Tool | Description |
|---|---|
aphrodite_retrieve |
Resolve <<<CCR:hash|type|size>>> markers |
aphrodite_compress |
Compress content via CCR with type hint |
aphrodite_stats |
Proxy health, engine status, inline store size |
aphrodite_rebuild |
Report binary/proxy version + a rebuild hint (never rebuilds itself) |
aphrodite_files |
Tracked file references, grouped by tool |
aphrodite_diff |
Conversation turn history with summaries |
aphrodite_search |
Search CCR store by keyword or type |
aphrodite_directive |
List/swap/add/remove/reset behavioral directives |
aphrodite_test |
Smoke test suite: quick (1 sample), full (3 samples) |
aphrodite_catalog |
Full CCR catalog with hashes, types, sizes, previews |
aphrodite_reclassify |
Retroactive metadata enrichment for unclassified CCR |
aphrodite_prefetch |
Read + compress files on demand; markers returned inline |
aphrodite_prefetch_status |
Live prefetch schedule: loading, ready, errors |
Typical calls:
aphrodite_retrieve(hash) → the full content behind a marker
aphrodite_catalog() → every marker this session, with previews
aphrodite_search("preview builder") → find a stored entry by keyword or type
aphrodite_compress(content, type) → compress content the agent already holds
aphrodite_stats() → proxy health, engine status, savings
aphrodite_directive(action: "list") → current directive set, swappable in place
Configuration lives in aphrodite.toml. Two shipped files must stay in sync:
aphrodite.toml.example (repo root - the copy-from example) and
crates/aphrodite/templates/aphrodite.toml (embedded in the binary and
written by aphrodite setup, which substitutes {cache_port}/{token_port}).
Two independent parsers read the file:
- the Rust HTTP proxy (
config/proxy.rs, active when anaphrodite.tomlis found):[[proxies]],[defaults], the four live-reload thresholdstool_threshold_token/tool_threshold_cache/inline_threshold/code_multiplier,[compression] auto_expand/auto_expand_limit,[previews] preview_max_chars(default0= unlimited previews), and the[templates.*]sections via the/reloadhandler; - the Hermes dylib session (
config_loader.rs): the[compression]engine/auto-expand/live-container/chain-split/poll keys,[defaults] model/api_url,[flow] budget_chars,[directives] active,[prompts] session_injectplus the prompt knobs (retrieve_guidance,ccr_marker_hint,catalog_intent_hints),[templates.*](preview / marker / prompts / reverse), and[previews] preview_max_chars.
Edit + save (or POST /reload) re-applies the four proxy thresholds, the
preview cap, and the template registrations immediately; the dylib re-applies
config fields on change when auto_reload = true (the shipped default).
aphrodite.toml (key subset - the shipped files document every key)
[defaults]
api_url = "https://api.openai.com" # APHRODITE_API_URL > TOML > fallback
model = "default-model" # APHRODITE_MODEL > TOML > fallback
ccr_ttl_seconds = 3600
[compression]
engine_threshold_pct = 30 # dylib: fill% that triggers middle-turn archiving (compiled-in fallback 45); 0 = never, 100+ = engine-off escape hatch
engine_protect_first = 2 # dylib: head turns always kept visible
engine_protect_last = 5 # dylib: tail turns always kept visible
engine_min_msgs = 8 # dylib: minimum conversation turns before archiving engages
tool_threshold_token = 256 # token proxy threshold (bytes) - live-reloadable
tool_threshold_cache = 2048 # cache proxy threshold (bytes) - live-reloadable
terminal_threshold = 256 # dylib terminal output threshold (bytes)
inline_threshold = 1024 # inline-vs-durable CCR storage cutoff - live-reloadable
code_multiplier = 1.0 # multiply threshold for code_* content types - live-reloadable
auto_expand = true # proxy+dylib: resolve markers inline as the session fills (compiled-in default: false)
auto_expand_limit = 102400 # proxy+dylib: cap on auto-expanded bytes
live_container = false # dylib: instant CCR 'live'-type markers with chunked retrieval (env APHRODITE_LIVE_CONTAINER)
recursive_depth = 5 # proxy+dylib: nested marker expansion cap (env APHRODITE_RECURSIVE_DEPTH)
# max_request_body_size # proxy: optional request-body cap (env APHRODITE_MAX_REQUEST_BODY_SIZE)
context_engine = true # dylib session status flag (default-on)
poll_worker = true # dylib: auto-background slow tool calls
auto_reload = true # dylib: watch aphrodite.toml, re-apply config fields
chain_split = false # dylib: opt-in fine-grained command splitting
chain_split_min_segments = 2 # dylib: adaptive split floor (min 2)
chain_split_max_segments = 6 # dylib: adaptive split cap
[flow]
budget_chars = 2600 # dylib: hard cap on per-turn injected context
[directives]
active = ["lazy", "lazy-eval", "foresight"] # empty list seeds focus + foresight + lazyWired [compression]/[defaults] fields are overridable via APHRODITE_*
env vars (see
docs/config/env-vars.md).
Reserved keys - parsed but no consumer, setting them is a silent no-op
(kept, marked DOCUMENTED BUT UNWIRED): classifier_poll, catalog_mode,
previews.code_structure_map, previews.rust_preview_lines. The
[templates.*] sections are live and TOML-configurable - see
Templates (TOML) below.
Preview and marker format strings are TOML-configurable via [templates.*].
When a section is absent, the compiled-in builders and marker grammar stay
the default. Per preview the resolution order is: family[ctype] →
reverse[ctype] (a key in the same family) → family[_default] → the
hardcoded builder. [previews] model_family selects the active family
(default code_first when unset); it only matters when templates are
configured. Unknown families and unknown variables degrade gracefully - the
hardcoded builder / empty string, never a panic.
aphrodite.toml (template example)
[templates.preview.code_first]
diff = "[diff:{files}f +{plus}/-{minus} {ln}L{fx}{fn}]"
code = "[{type}:{fns}fns|{structs}structs {sigs} {ln}L]"
_default = "[{type}:{ln}L | {first}]"
[templates.marker]
format = "{preview}\n[{type}: {meta}{center_seg}]\n<<<CCR:{hash}|{type}|{size}>>>"
hint = "...(use aphrodite_retrieve)"
[templates.prompts]
session_inject = "CCR markers (<<<CCR:hash|type|size>>>) are compressed content..."
[templates.reverse]
build_output = "build" # remap a content type to a key in the active familyPreview template variables - each substituted as a brace-wrapped name in the format string; unknown variables degrade to empty string, never panic:
type, ln, size, first, err, warn, msg, exit, cmd, files,
fn, plus, minus, keys, items, commit, hash, subject, pid,
uptime, fns, structs, impls, classes, sigs, code, loc,
errors, total, sig1, fx, cmx
Marker template variables - preview, type, meta, center,
center_seg, hash, size, hint. The {hint} variable renders only
when the [prompts] ccr_marker_hint knob is enabled.
Prompt templates - session_inject (user-facing, injected each session),
engine_offload (rendered when the context engine archives middle turns;
variables hash and tail), and auto_expand_guidance (internal).
Tip
Directives are covered under Session Lifecycle above - seven
built-ins, swapped mid-conversation via aphrodite_directive.
Standard corpus: up to 610× on large low-entropy prose, 132× overall (106 KB → 800 B). Cache and token modes measure identical ratios; 20/20 compressed, 20/20 retrieve round-trips OK.
| Content type | Without | With | Savings |
|---|---|---|---|
| Git diff (42L) | ~350 tok | ~15 tok | 23× |
| Build output (142L) | ~1,400 tok | ~10 tok | 140× |
| Terminal output | ~200 tok | ~10 tok | 20× |
| JSON blob (30 keys) | ~400 tok | ~10 tok | 40× |
| Browser snapshot (342 el) | ~5,000 tok | ~12 tok | 416× |
Median: 23× fewer tokens on tool output. End-to-end latency is 8-40 ms (includes the HTTP round-trip); classification alone is 40-123 ns.
Benchmarks are reproducible:
cargo run --release -p aphrodite --example bench_01_corpus
(bench_02_threshold, bench_03_retrieve, bench_04_ema).
Retroactive analysis of 200 real Hermes sessions (6,843 API calls, Sep 18-20) - multi-agent atomization fan-outs, merge/PR work, plugin integration - by reconstructing every call's payload from the session transcript: tokens as stored (CCR markers included) vs. the same payload with every marker expanded to its original content (stock Hermes).
| Metric | Value |
|---|---|
| Context tokens with markers (what the model saw) | 424,959,588 |
| Context tokens expanded (stock Hermes, no CCR) | 581,302,405 |
| Context tokens saved | 156,342,817 (26.9%) |
| Average saved per API call | 22,921 tok |
| Sessions that saved anything | 183 / 200 |
| Median session saved ratio | 22.9% |
| Retrieval re-entry (tax) | 2,275 calls / 2,011,583 tok |
Real-world per-output compression (orig tokens -> ~33-tok marker):
| Content | Compression |
|---|---|
terminal |
74× |
table |
61× |
source_code |
45× |
ls |
37× |
diff |
23× |
build |
23× |
search |
20× |
Savings scale with tool-output volume and session length - chat-only sessions gain ~0%, a light developer session ~5%, long tool-heavy sessions 20-25%, and pure-tool workloads (simulated diff+ls+build+search loop) 76-82%.
Note
Confidence. The causal result - CCR removes context pressure for large repeated tool outputs, and tool-heavy usage benefits far more than chat - is high. The exact percentage is a band: the marker's byte size is the only trace of the original content (the inline store is session-scoped), so savings were estimated with a calibrated chars/tok ratio; sensitivity across 3.0-4.5 chars/tok spans ~24-33%, centered ~27%. A paired pre/post request capture in the proxy would convert this estimate into an exact measurement.
Aphrodite embeds Headroom - a custom fork tracked
as a git submodule at vendor/headroom/.
Headroom provides the content transforms (classifier, smart crusher, tokenizer);
Aphrodite adds the preview pipeline, CCR storage, Hermes integration, and
dual-proxy architecture.
→ See docs/architecture/10-component.md for how the fork integrates.
| Want to... | Start here |
|---|---|
| Report a bug | Open an issue |
| Suggest a feature | Start a discussion |
| Submit a PR | Fork & open a PR |
| Ask a question | Discussions Q&A |
No contribution is too small. First-time contributors are especially welcome.
Released under CC0-1.0 - public domain.
Built with ❤️ by PlayForm.