Home
CRUX Compress

CRUX Compress

CRUX-Compress, packaged as a plugin for Cursor, Claude Code, and Codex. CRUX (Context Reduction Using X-encoding) compresses markdown rules, code files, images, and web pages into a dense notation that agents read directly — usually to about a quarter of the original tokens. The plugin also carries CRUX memories and meditation.

Plugin version 2.11.8 matches the CRUX-Compress release it packages. The release is carried unchanged except for the path and frontmatter changes listed in scripts/upstream-map.json.

Install

Client	Marketplace file	Install
Cursor	`.cursor-plugin/marketplace.json`	Add `zotoio/zoto-agents` as a marketplace, then install crux-compress.
Claude Code	`.claude-plugin/marketplace.json`	`/plugin marketplace add zotoio/zoto-agents`, then `/plugin install crux-compress@zoto-agents`
Codex	`.agents/plugins/marketplace.json`	`codex plugin marketplace add zotoio/zoto-agents`, then install from `/plugins`

Requirements: Python 3 (python3 on PATH) for the hooks and the crux-utils and memory-index scripts.

Set up a project

Run once in each project, and again after updating the plugin:

/z-crux-init
/z-crux-init with memories

This copies the CRUX specification to CRUX.md, adds or refreshes the <CRUX> block in AGENTS.md, and writes .crux/crux.json. With memories, it also creates .crux/crux-memories.json, memories/, and .crux/reference-tracking/. Memories stay off until you set enableMemories to "true".

If the project already has CRUX from the upstream installer (files under .cursor/agents/crux*, .cursor/commands/crux*, .cursor/skills/crux*, .cursor/hooks/crux-*.py), /z-crux-init lists them and offers to remove them. Leaving them loads every CRUX agent and rule twice and runs each hook twice.

What's included

Commands

Command	What it does
`/crux-compress`	Compress markdown rules, code files, images, and web pages into CRUX notation for token efficiency.
`/crux-dream`	Post-execution memory extraction and REM sleep rebalancing.
`/crux-recall`	Decompress, query, and display CRUX memories in human-readable form.
`/crux-remember`	Store ad-hoc memories outside of spec workflows; they join standard consolidation during REM sleep.
`/crux-forget`	Remove memories from the CRUX memory corpus.
`/crux-amnesia`	Temporarily disable or restore ambient CRUX memory usage for the current chat session.
`/crux-meditate`	Run a recursive, memory-informed meditation on a topic: research, adversarial review, and a final report.
`/z-<skill>`	One wrapper per skill, e.g. `/z-crux-init`, `/z-crux-utils`, `/z-crux-skill-memory-index`.

Agents, skills, rules, hooks

Component	Contents
Agents	`crux-cursor-rule-manager`, `crux-cursor-meditation-guide`, `crux-cursor-memory-manager` (deprecated upstream), and the memory agents `crux-memory-dream`, `crux-memory-rem`, `crux-memory-recall`, `crux-memory-remember`, `crux-memory-forget`.
Skills	`crux-init` (this plugin), `crux-utils` (token estimation and checksums), and the `crux-skill-memory-*` skills (compress, crud, extract, index, rebalance, reference-tracker, and the meditation steps).
Rules	`_CRUX-RULE.mdc`, `crux-memories-integration.crux.mdc`, and `crux-plugin-paths.mdc` (this plugin).
Hooks	Session start (pending compressions, memory nudges), after file edit (queue changed `crux: true` sources, flag the memory index), after agent response (track `[memory:*]` references).

The crux-skill-memory-meditation-* skills are steps of /crux-meditate, loaded by the crux-cursor-meditation-guide agent. Their /z- commands exist to inspect or reuse one step.

Usage

/crux-compress ALL                      # all eligible rules
/crux-compress @path/to/file.md         # a specific file
/crux-compress @f1.md @f2.md            # multiple files
/crux-compress @file.md --minified      # single-line output
/crux-compress ALL --force              # force recompression
/crux-compress @file.md --40            # target 40% of original
/crux-compress @script.sh               # a code file
/crux-compress @image.png               # an image (semantic visual description)
/crux-compress https://example.com      # a URL source

Usage forms taken from commands/crux-compress.md.

Configuration

File	Purpose
`CRUX.md`	The CRUX specification, copied into the project by `/z-crux-init`.
`AGENTS.md`	Gets a `<CRUX>` block, added or refreshed by `/z-crux-init`.
`.crux/crux.json`	Records the installed CRUX version.
`.crux/crux-memories.json`	Memory settings (from `templates/crux-memories.default.json`). Flags `enableMemories` and `enableMemoryCompression` default to `"false"`; storage defaults to `memories/` with the index at `.crux/memory-index.yml`.

Hooks & paths

hooks/hooks.json runs each hook as python3 "${CURSOR_PLUGIN_ROOT:-.}"/hooks/<hook>.py, and the hooks read and write .crux/ in CURSOR_PROJECT_DIR. The hooks file uses Cursor's format, so Claude Code does not run these hooks.

Upstream files refer to their own files as .cursor/...; in the plugin those are written <plugin>/..., and rules/crux-plugin-paths.mdc tells agents that <plugin> is the plugin's install directory. Project paths (CRUX.md, AGENTS.md, .crux/, memories/, your .cursor/rules/) are unchanged.

Update from upstream

Maintainers rebuild the plugin from a CRUX-Compress GitHub release with scripts/sync-upstream.mjs:

node scripts/sync-upstream.mjs --ref v2.11.8
node scripts/sync-upstream.mjs
node scripts/sync-upstream.mjs --check --ref v2.11.8

The script verifies every file against the release's .crux/crux-release-files.json checksums, applies the rewrites in scripts/upstream-map.json (--raw skips content changes), and writes upstream.json. --check writes nothing and exits non-zero if the plugin differs from the release. Plugin-owned files (crux-plugin-paths.mdc, skills/crux-init/, commands/z-*.md, evals/, manifests, assets/, tests/, README) are never touched by a sync.

Troubleshooting & limits

Hooks don't fire: make sure python3 is on PATH. Hooks run in Cursor only, not Claude Code.
Everything loads twice: remove upstream-installer files under .cursor/ — /z-crux-init lists them and offers to remove them.
Memories do nothing: they're off by default; set enableMemories to "true" in .crux/crux-memories.json.
Known upstream issue: AGENTS.crux.md is in the release zip but not its checksum manifest, so the sync can't verify it and warns.