CRUX-Compress: Skill for Cursor

CRUX Memory Compress

Applies CRUX compression to memory file bodies, enforces size caps, archives originals, and handles migration of pre-existing uncompressed memories.

Prerequisites

Before any operation:

1. Read config: Load .crux/crux-memories.json and extract:
   • flags.enableMemoryCompression — must be "true" or abort with message
   • cruxMemories.compressionTarget — target percentage (default 33)
   • cruxMemories.sizeUnit — unit for size thresholds: "lines" or "bytes" (default "lines")
   • cruxMemories.compressionMinLines — minimum file size in lines before compression is considered (default 500)
   • cruxMemories.maxMemorySize — hard cap in configured sizeUnit (default 1000 lines)
   • cruxMemories.storage.compressionSourceArchive — archive path (default .ai-ignored/memories/sources)
   • cruxMemories.storage.memoriesDir — where memories live (default memories)
2. Load CRUX spec: Read CRUX.md from project root for encoding symbols and compression rules
3. Guard check: If flags.enableMemoryCompression is not "true", refuse all operations and inform the caller that memory compression is disabled

Operations

1. Compress

Compress a single memory file's body using CRUX notation.

Input: Path to a .memory.md file

Steps:

1. Read the memory file and separate frontmatter from body
2. Check compressionMinLines — count the total lines in the file. If below compressionMinLines (default 500), skip compression and return the file unchanged. Files below this threshold are too small to benefit from CRUX compression.
3. Frontmatter is NEVER compressed — preserve it exactly as-is (title, description, type, tags, strength, scope, etc.)
4. Estimate body token count using crux-utils skill (--token-count) if available, otherwise LLM estimation (prose: 4 chars/token, code: 3.5 chars/token, CRUX symbols: 1 token each)
5. Apply CRUX compression to the body only, targeting compressionTarget% of original body size
6. Measure compressed body size in the configured sizeUnit (default: lines)
7. Adaptive sizing — determine the applicable size cap: use maxConsolidatedSize if the file has consolidation_topic in its frontmatter, otherwise maxMemorySize. If compressed output exceeds the cap (measured in sizeUnit):
   • Increase compression aggressiveness (reduce target by 10 percentage points)
   • Re-compress and re-measure
   • Repeat until under the cap or target reaches 5%
   • If still over the cap at maximum compression, flag for manual review and do NOT write the file
8. Archive the original (see Source Archival)
9. Write compressed output as {slug}.memory.crux.md in the same directory
10. Delete the original .memory.md from the working directory (it has been archived in step 7)
11. Add compression metadata to frontmatter of the output file:

compressed: true
compressionTarget: 33
beforeTokens: <original body tokens>
afterTokens: <compressed body tokens>
reducedBy: <percentage>
compressedDate: <YYYY-MM-DD>
sourceArchive: <path to archived original>