crux-skill-memory-compress
Skill8 starsChanged 2 months agoMITView on GitHub
CRUX-compress memory files with adaptive sizing and source archival. Handles compress, decompress, migration of existing memories, and maxMemorySize enforcement (in lines). Use when compressing or decompressing memory files, or migrating uncompressed memories after enabling compression.
In this repository35 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .cursor/rules/crux-memories-integration.crux.mdcCursor rule
- .cursor/rules/crux-memories-integration.mdCursor rule
- .cursor/rules/_CRUX-RULE.mdcCursor rule
- .cursor/rules/docs-sync.crux.mdCursor rule
- .cursor/rules/docs-sync.crux.mdcCursor rule
- .cursor/rules/docs-sync.mdCursor rule
- .cursor/rules/example/coding-standards-demo.crux.mdcCursor rule
- .cursor/rules/example/coding-standards-demo.mdCursor rule
- .cursor/rules/ignore-example-rules.crux.mdCursor rule
- .cursor/rules/ignore-example-rules.crux.mdcCursor rule
- .cursor/rules/ignore-example-rules.mdCursor rule
- .cursor/rules/skill-and-agent-references.mdcCursor rule
- .cursor/rules/spec-agent-allocation.crux.mdCursor rule
- .cursor/rules/spec-agent-allocation.crux.mdcCursor rule
- .cursor/rules/spec-agent-allocation.mdCursor rule
- .cursor/rules/spec-implementation-hygiene.mdcCursor rule
- .cursor/rules/version-bump.crux.mdCursor rule
- .cursor/rules/version-bump.crux.mdcCursor rule
- .cursor/rules/version-bump.mdCursor rule
- .cursor/rules/zip-contents-protection.crux.mdCursor rule
- .cursor/rules/zip-contents-protection.crux.mdcCursor rule
- .cursor/rules/zip-contents-protection.mdCursor rule
- crux-skill-memory-crudSkill
- crux-skill-memory-extractSkill
- crux-skill-memory-indexSkill
- crux-skill-memory-meditation-coordinationSkill
- crux-skill-memory-meditation-ensembleSkill
- crux-skill-memory-meditation-quickSkill
- crux-skill-memory-meditation-reportSkill
- crux-skill-memory-meditation-researchSkill
- crux-skill-memory-meditation-reviewSkill
- crux-skill-memory-rebalanceSkill
- crux-skill-memory-reference-trackerSkill
- crux-utilsSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
18 rules. About 0 are common, 7 are distinctive, and 11 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
11
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 15
Load CRUX spec: Read CRUX.md from project root for encoding symbols and compression rules.
- Very specific: line 16
Guard check: If flags.enableMemoryCompression is not "true", refuse all operations and inform the caller that memory compression is …
- Distinctive: line 28
Read the memory file and separate frontmatter from body
- Distinctive: line 38
If still over the cap at maximum compression, flag for manual review and do NOT write the file
- Very specific: line 40
Write compressed output as {slug}.memory.crux.md in the same directory
- Very specific: line 41
Delete the original .memory.md from the working directory (it has been archived in step 7)
- Very specific: line 42
Add compression metadata to the output frontmatter: compressed: true, compressionTarget, beforeTokens, afterTokens, reducedBy, …
- Distinctive: line 73
Read the compressed file and separate frontmatter from CRUX body
- Very specific: line 75
Remove compression metadata fields from frontmatter (compressed, compressionTarget, beforeTokens, afterTokens, reducedBy, compressedDate, …
- Very specific: line 76
Write the result as {slug}.memory.md (rename from .memory.crux.md to .memory.md)
- Very specific: line 77
Delete the .memory.crux.md file
- Very specific: line 83
Before replacing a .memory.md with its compressed .memory.crux.md, archive the original.
- Distinctive: line 91
Create the dated archive directory if it doesn't exist
- Distinctive: line 94
Only after successful archival, proceed with writing the compressed file
- Distinctive: line 100
When compression is enabled on a repo with existing uncompressed memories, detect and offer to compress them.
- Distinctive: line 124
When compressing memory bodies, follow these patterns adapted from the CRUX spec:
- Very specific: line 126
Use standard CRUX blocks where applicable (Ρ{} for purpose, Κ{} for key definitions, R{} for rules, Λ{} for triggers, P{} for prohibitions)
- Very specific: line 127
Use CRUX encoding symbols (→, ¬, ⊤, ⊥, ∀, ≻, etc.) per CRUX.md
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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:
- Read config: Load
.crux/crux-memories.json. This skill needsflags.enableMemoryCompression,cruxMemories.compressionTarget,sizeUnit,compressionMinLines,maxMemorySize,maxConsolidatedSize, andstorage.compressionSourceArchive/memoriesDir. Defaults and full key descriptions live in.cursor/skills/_memory-shared.md#config-referenceand.crux/crux-memories.json(authoritative). - Load CRUX spec: Read
CRUX.mdfrom project root for encoding symbols and compression rules. - Guard check: If
flags.enableMemoryCompressionis 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:
- Read the memory file and separate frontmatter from body
- Check
compressionMinLines— count the total lines in the file. If belowcompressionMinLines(default500), skip compression and return the file unchanged. Files below this threshold are too small to benefit from CRUX compression. - Frontmatter is NEVER compressed — preserve it exactly as-is (title, description, type, tags, strength, scope, etc.)
- Estimate body token count using
crux-utilsskill (--token-count) if available, otherwise LLM estimation (prose: 4 chars/token, code: 3.5 chars/token, CRUX symbols: 1 token each) - Apply CRUX compression to the body only, targeting
compressionTarget% of original body size - Measure compressed body size in the configured
sizeUnit(default: lines) - Adaptive sizing — determine the applicable size cap: use
maxConsolidatedSizeif the file hasconsolidation_topicin its frontmatter, otherwisemaxMemorySize. If compressed output exceeds the cap (measured insizeUnit):- 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
- Archive the original (see Source Archival)
- Write compressed output as
{slug}.memory.crux.mdin the same directory - Delete the original
.memory.mdfrom the working directory (it has been archived in step 7) - Add compression metadata to the output frontmatter:
compressed: true,compressionTarget,beforeTokens,afterTokens,reducedBy,compressedDate,sourceArchive(see Output format below for a filled example).
Output format ({slug}.memory.crux.md):
---
<original frontmatter fields preserved>
compressed: true
compressionTarget: 33
beforeTokens: 450
afterTokens: 140
reducedBy: 69%
compressedDate: 2026-04-04
sourceArchive: .ai-ignored/memories/sources/20260404/react-memo-list-rendering.memory.md
---
⟦CRUX:memory
<compressed body content>
⟧Unlike rule compression (percentage-only), memory compression also enforces maxMemorySize in sizeUnit — the loop in step 6 may push past compressionTarget when the absolute cap requires it.
2. Decompress
Restore a compressed memory for editing.
Input: Path to a .memory.crux.md file
Steps:
- Read the compressed file and separate frontmatter from CRUX body
- Decompress the CRUX body back to natural language (terse, not verbose — preserve meaning without expanding to full prose)
- Remove compression metadata fields from frontmatter (
compressed,compressionTarget,beforeTokens,afterTokens,reducedBy,compressedDate,sourceArchive) - Write the result as
{slug}.memory.md(rename from.memory.crux.mdto.memory.md) - Delete the
.memory.crux.mdfile
Expand CRUX to terse natural language (matches Recall display) — preserve meaning, don't reinflate to the original verbosity. If sourceArchive in frontmatter points at a surviving original, offer to restore that exact file instead of decompressing.
3. Source Archival
Before replacing a .memory.md with its compressed .memory.crux.md, archive the original.
Archive path: {compressionSourceArchive}/{yyyymmdd}/{original-filename}
Example: .ai-ignored/memories/sources/20260404/react-memo-list-rendering.memory.md
Steps:
- Create the dated archive directory if it doesn't exist
- Copy (not move) the original
.memory.mdto the archive path - Record the archive path in the compressed file's
sourceArchivefrontmatter field - Only after successful archival, proceed with writing the compressed file
The archive directory (.ai-ignored/) is excluded from AI context loading, keeping originals available for recovery without polluting agent context.
4. Migration
When compression is enabled on a repo with existing uncompressed memories, detect and offer to compress them.
Trigger: Called when enableMemoryCompression is "true" and uncompressed .memory.md files exist
Steps:
- Scan
memoriesDirrecursively for*.memory.mdfiles (exclude any already-compressed*.memory.crux.md) - For each uncompressed file, estimate current size and projected compressed size
- Return a migration plan in your response. Do NOT call
AskQuestion— the calling agent handles user interaction:
The calling agent will present this to the user and collect their decision (all/select/skip) viaFound N uncompressed memory files: | File | Current Size | Est. Compressed | Fits maxMemorySize | |------|-------------|-----------------|-------------------| | core/react-memo.memory.md | 85 lines | ~28 lines | Yes | | learning/stale-closure.memory.md | 45 lines | ~15 lines | Yes | | idea/visual-regression.memory.md | 120 lines | ~40 lines | Yes |AskQuestion, then pass the confirmed list back to you. - On confirmation, compress each file using the Compress operation (files below
compressionMinLinesare automatically skipped) - Report results: how many compressed, how many skipped (below minimum), any that exceeded
maxMemorySizeand were flagged
CRUX Compression Patterns for Memories
When compressing memory bodies, follow these patterns adapted from the CRUX spec:
- Use standard CRUX blocks where applicable (
Ρ{}for purpose,Κ{}for key definitions,R{}for rules,Λ{}for triggers,P{}for prohibitions) - Use CRUX encoding symbols (
→,¬,⊤,⊥,∀,≻, etc.) perCRUX.md - For factual memories (learnings, core), compress to key-value assertions
- For procedural memories (goals, ideas), compress to action sequences
- For warning memories (redflags), compress to condition → consequence patterns
- Reference the
crux-cursor-rule-manageragent definition for full compression methodology
Out-of-scope and cross-skill delegation: see
.cursor/skills/_memory-shared.md#cross-skill-boundariesand the agent table inAGENTS.md.
Error Handling
| Condition | Action |
enableMemoryCompression is not "true" | Abort, inform caller compression is disabled |
File is not a .memory.md or .memory.crux.md | Reject with descriptive error |
Compressed output exceeds maxMemorySize (in configured sizeUnit) at max compression | Flag for manual review, do not write output |
| Source archive directory cannot be created | Abort compression, report filesystem error |
Decompressed file would overwrite existing .memory.md | Return needs_user_input for the calling agent to confirm with the user |
| Config file missing or malformed | Report error with path and expected structure |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

