ΣCRUX Compress

Website: compress.md Repository: github.com/zotoio/CRUX-Compress

Table of Contents

• The Problem
• The Approach
• Demonstration
• Etymology
• Quick Install
  • Install Options
  • What Gets Installed
  • Upgrading
• How They Work Together
  • Compression Flow
• Installation in Another Project
• CRUX Components
  • 1. CRUX.md - The Specification
  • 2. AGENTS.md - Agent Awareness
  • 3. _CRUX-RULE.mdc - Always-Applied Rule
  • 4. crux-cursor-rule-manager.md - The Subagent
  • 5. crux-compress.md - The Command
  • 6. crux-detect-changes.py - The Hook
  • 7. crux-utils - The Skill
• Memories
  • Enabling Memories
  • Memory Commands
  • Memory Skills
  • Type Transitions and Reference Tracking
  • MCP Server (Optional)
  • Python Dependencies

Recent update: The memory agent has been split into five mode-scoped thin agents (crux-memory-dream, crux-memory-rem, crux-memory-recall, crux-memory-remember, crux-memory-forget), reducing per-spawn context load by 52–80% depending on the operation. Primitives loaded unconditionally are now lazy-loaded, cutting context overhead by ~57% across common workflows. See analysis/context-token-reduction-report.md for the full analysis.

The Problem

AI coding assistants like Cursor rely on context windows to understand your project. When you add natural language markdown rules to guide agent behavior, those rules consume valuable context tokens—often thousands of tokens per rule file. As your rule library grows, context window usage balloons, leaving less room for actual code and conversation.

Users want to manage their rules in readable, natural language markdown. But LLMs don't need the verbose prose—they just need the actionable information.

The Approach

CRUX extracts the essential meaning from natural language markdown rules and compresses it into a logic-based Domain Specific Language (DSL) that all LLMs understand without additional instructions.

CRUX compression works for more than just rules, but this is the current focus.

How it works:

1. You write rules in natural language markdown — readable, maintainable, version-controllable
2. CRUX compresses them — extracting the "crux" (the decisive, most important points) into a compact symbolic notation
3. Compressed rules load into context — achieving 5-10x token reduction (target ≤20% of original)
4. LLMs interpret the notation natively — no decompression needed, semantic meaning preserved, although the spec is added for completeness and reinforcement

CRUX can compress markdown rules, source code, images, and even public webpages. URL sources are automatically saved to .crux/out/ for easy access.

The result: your context window stays lean while your rules remain powerful.

Demonstration

┌───────────────────────────────────────────────────────────┐
│                                                           │
│   ████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  82% SAVED     │
│                                                           │
│       BEFORE: ~625 tokens  →  AFTER: ~112 tokens          │
│                                                           │
└───────────────────────────────────────────────────────────┘

Team Development Standards

Key Definitions

Abbreviation	Meaning
fn	function
cls	class
cmp	component
pr	pull request

Style Rules

Indentation & Formatting

• Use 2 spaces for indentation
• Never use tabs! This is strictly enforced
• Lines must not exceed 100 characters

Naming Conventions

Element	Convention	Examples
Functions	camelCase	getUserData, processOrder
Classes	PascalCase	UserService, OrderProcessor
Constants	UPPER_SNAKE_CASE	MAX_RETRIES, API_BASE_URL

Quality Rules

Size Limits

• Functions must be 50 lines or fewer
• Classes must be 300 lines or fewer

Documentation & Testing

• All exported members must have test coverage of at least 80%
• All functions must include JSDoc comments documenting:
  • Parameters
  • Return value

Complexity

• Cyclomatic complexity must not exceed 10

Code Review Process

• All pull requests require:
  • At least 1 approval from a reviewer
  • CI pipeline must pass
• If a change is 500 lines or more, you must split it into smaller PRs!

Patterns to Avoid

Anti-Pattern	Guidance
any type	Strictly forbidden! Always use proper types
console.log

---

Try this Copy and paste into Claude, ChatGPT, Gemini, or any LLM:

Explain this: ⟦CRUX:coding-standards.md;Ρ{team dev standards};Κ{fn=function;cls=class;cmp=component;pr=pull request};R.style{indent=2sp;¬tabs!;line≤100ch;naming{fn=camelCase;cls=PascalCase;const=UPPER_SNAKE}};R.quality{fn.len≤50;cls.len≤300;∀export→test.cov≥80%;∀fn→jsdoc[params+return];cyclomatic≤10};Λ.review{pr→≥1approval+CI.pass;Δ≥500lines→split!};P.avoid{¬any!;¬console.log[prod];¬magic.num→use.const};E{⊤:err→try/catch→log+handle;⊥:catch(e){/*ignore*/}};Ω{quality≻speed;readable≻clever}⟧

Explain this: 

⟦CRUX:coding-standards.md
Ρ{team dev standards}
Κ{fn=function; cls=class; cmp=component; pr=pull request}
R.style{
  indent=2sp; ¬tabs!; line≤100ch
  naming{fn=camelCase; cls=PascalCase; const=UPPER_SNAKE}
}
R.quality{
  fn.len≤50; cls.len≤300; ∀export→test.cov≥80%
  ∀fn→jsdoc[params+return]; cyclomatic≤10
}
Λ.review{pr→≥1approval+CI.pass; Δ≥500lines→split!}
P.avoid{¬any!; ¬console.log[prod]; ¬magic.num→use.const}
E{⊤:err→try/catch→log+handle; ⊥:catch(e){/*ignore*/}}
Ω{quality≻speed; readable≻clever}
⟧

---

Note: Larger source documents typically achieve higher compression percentages. A 500-word markdown file might compress to 15% of its original tokens, while a 100-word file might only reach 40%. CRUX helps most dealing with verbose rules.

Etymology

CRUX = Context Reduction Using X-encoding

The "X" is intentionally flexible:

• eXpressive symbols (→ ⊳ ⊲ ∋ ∀)
• eXtensible notation (custom blocks)
• eXchange format (compress ↔ expand)

The name also serves as a backronym for "crux" — the decisive or most important point — which is exactly what the compression preserves while stripping everything else.

Quick Install

Recommended: Agent-Driven Install

The easiest way to install CRUX is to let your AI agent do it. In Cursor, paste this into chat:

Fetch https://raw.githubusercontent.com/zotoio/CRUX-Compress/main/install.crux.md, read it, and follow its instructions to install CRUX Compress into this project.

The agent will decompress the CRUX installer spec and execute the installation — no python3 or curl required on your system. The spec includes language fallback logic so the agent can implement the installer in whatever runtime is available.

Tip: If your agent can't fetch URLs, save install.crux.md to your project and reference it, or paste its contents directly into chat.

Alternative: One-Line Script Install

If you prefer a traditional install, run:

curl -fsSL https://raw.githubusercontent.com/zotoio/CRUX-Compress/main/install.py | python3 -

If GitHub is blocked in your environment, use the jsDelivr CDN mirror:

curl -fsSL https://cdn.jsdelivr.net/gh/zotoio/CRUX-Compress@main/install.py | python3 -

The installer automatically falls back to jsDelivr for version checks and file downloads when GitHub is unreachable.

Tip: You can also copy install.py locally and run it directly with python3 install.py -- it works the same way.

Prerequisites (script install only): curl and python3.

Install Options

# With backup of existing files
curl -fsSL .../install.py | python3 - --backup

# Verbose output
curl -fsSL .../install.py | python3 - --verbose

# Scaffold optional memory system components
curl -fsSL .../install.py | python3 - --with-memories

# Install standalone MCP memory server (user-level, all projects)
curl -fsSL .../install.py | python3 - --with-mcp-server

# Show help
curl -fsSL .../install.py | python3 - --help

What Gets Installed

The installer creates/updates these files in your project:

File	Purpose
CRUX.md	Specification (READONLY)
AGENTS.md	Agent awareness notice
install.crux.md	Installer spec (update reference)
.crux/crux.json	Installed CRUX version
.crux/crux-release-files.json	Release manifest
.cursor/hooks.json	Hook configuration
.cursor/hooks/crux-detect-changes.py	File change detection
.cursor/hooks/crux-session-start.py	Session start hook
.cursor/agents/crux/crux-cursor-rule-manager.md	Compression subagent
.cursor/commands/crux/crux-compress.md	Compression command
.cursor/rules/crux/_CRUX-RULE.mdc	Always-applied rule
.cursor/skills/crux/crux-utils/	Utility skill

Upgrading

Ask your agent to read install.crux.md in your project root and follow the Γ.bootstrap_upgrade instructions. It will detect the installed version, download the latest release, clean up deprecated files from older versions, and update everything.

Alternatively, use the script directly:

# If update.py exists (installed by previous CRUX versions)
python3 .crux/update.py --backup

# Or re-run the installer from source
curl -fsSL https://raw.githubusercontent.com/zotoio/CRUX-Compress/main/install.py | python3 - --backup

The upgrade process automatically migrates existing CRUX primitives into .cursor/<type>/crux/, removes stale files from older versions (e.g., renamed hooks and skills), and cleans deprecated commands from hooks.json.

System Architecture

The CRUX system consists of 6 interconnected components:

flowchart TB
    subgraph "CRUX System Architecture"
        CRUX["CRUX.md<br/>(Specification)<br/>READONLY"]
        AGENTS["AGENTS.md<br/><CRUX> block<br/>(High-visibility notice)"]
        RULE["_CRUX-RULE.mdc<br/>(Always-Applied Rule)<br/>.cursor/rules/crux/"]
        MANAGER["crux-cursor-rule-manager.md<br/>(Subagent - ΣCRUX)<br/>.cursor/agents/crux/"]
        COMMAND["crux-compress.md<br/>(Cursor Command)<br/>.cursor/commands/crux/"]
        HOOK["crux-detect-changes.py<br/>(File Edit Hook)<br/>.cursor/hooks/"]
        
        AGENTS -->|"References"| CRUX
        RULE -->|"Points to spec"| CRUX
        MANAGER -->|"Loads spec"| CRUX
        COMMAND -->|"Spawns"| MANAGER
        RULE -->|"Delegates compression"| MANAGER
        HOOK -->|"Queues files for"| COMMAND
    end
    
    subgraph "I/O"
        INPUT["*.md / *.sh / *.ts / *.png files"]
        OUTPUT["*.crux.md files (universal)"]
        CURSOR["*.crux.mdc (Cursor adapter)"]
        INPUT -->|"Compression"| OUTPUT
        OUTPUT -->|"If .cursor/rules/"| CURSOR
    end

Component Details

1. CRUX.md - The Specification (Project Root)

Purpose: The authoritative specification defining CRUX notation syntax, encoding symbols, and compression rules.

Key Contents:

• Encoding symbols (structure, relations, logic, change, qualifiers)
• Standard blocks (Ρ, E, Λ, Π, Κ, R, P, Γ, M, Φ, Ω)
• Compression rules (eliminate prose, deduplicate, collapse, merge)
• Image compression (semantic visual descriptions using vision capabilities)
• Code compression (semantic structure extraction from source code)
• Quality gates (target ≤20% of original token count)
• Example transformations (markdown, code, and image)

Critical Rules:

• READONLY - Agents must NEVER edit this file unless explicitly asked by the user
• All other CRUX components reference this as their source of truth

2. <CRUX> Block in AGENTS.md (Project Root)

Purpose: High-visibility notice ensuring ALL agents are aware of CRUX notation before they begin work.

Location: Near the top of AGENTS.md, the first file agents read.

Key Contents:

<CRUX agents="always">
## CRITICAL: CRUX Notation
...
### Foundational CRUX Rules (MUST FOLLOW)
1. NEVER EDIT `CRUX.md`
2. DO NOT LOAD SOURCE FILES when CRUX exists
3. SURGICAL DIFF UPDATES on source changes
4. ABORT IF NO SIGNIFICANT REDUCTION
5. IGNORE EXAMPLE RULES - `.cursor/rules/example/*` are demos only
</CRUX>

Why It Matters: This ensures agents know to:

• Load CRUX.md to understand compression symbols
• Use CRUX content instead of loading original source files
• Keep CRUX files synchronized when sources change

3. _CRUX-RULE.mdc - Always-Applied Rule (.cursor/rules/crux/)

Purpose: A Cursor rule that is always loaded into context, providing agents with instructions for handling CRUX notation.

Key Functions:

• Specification Loading: Instructs agents to load CRUX.md and AGENTS.md from the project root
• Decompression: Tells agents to interpret and follow CRUX-compressed rules
• Compression: Directs agents to delegate compression tasks to crux-cursor-rule-manager subagent

Key Instructions:

• When encountering CRUX notation, use the specification in CRUX.md to understand and adhere to the rules
• Always interpret, understand and adhere to the meaning compressed in CRUX notation
• When asked to compress a markdown rule file, delegate to the crux-cursor-rule-manager subagent

4. crux-cursor-rule-manager.md - The Subagent (.cursor/agents/crux/)

Purpose: A specialized AI subagent (ΣCRUX) that performs compression and decompression tasks.

Capabilities:

• Compression: Convert verbose markdown or code → compact CRUX notation
• Code Compression: Extract semantic structure from source code into CRUX notation
• Image Compression: Extract semantic visual descriptions from images
• Decompression: Explain CRUX notation in natural language
• Validation: Verify CRUX output follows specification
• Semantic Validation: Compare CRUX to source, produce confidence score
• Surgical Diff Updates: Update CRUX files when sources change

Workflow:

1. Load CRUX.md specification (required first step)
2. Get source file's checksum via crux-utils skill
3. Check if existing CRUX sourceChecksum matches → skip if unchanged
4. Estimate token reduction using crux-utils skill → abort if <50% reduction
5. Apply compression rules from specification
6. Generate output with frontmatter (generated, sourceChecksum/sourceUrl, beforeTokens, afterTokens, reducedBy)
7. Verify quality gates (target ≤20% of original)
8. Semantic validation: Fresh agent instance compares CRUX to source, produces confidence score
9. Update frontmatter with confidence: XX%

Output Format:

---
generated: YYYY-MM-DD HH:MM
sourceChecksum: "1234567890"
beforeTokens: 2500
afterTokens: 400
reducedBy: 84%
confidence: 92%
alwaysApply: true
---

> [!IMPORTANT]
> Generated file - do not edit!

5. crux-compress.md - The Command (.cursor/commands/crux/)

Purpose: A Cursor command that orchestrates CRUX compression tasks.

Usage:

/crux-compress ALL                    - Compress all eligible rules
/crux-compress @path/to/file.md       - Compress a specific file
/crux-compress @file1.md @file2.md    - Compress multiple files
/crux-compress @script.sh             - Compress a code file
/crux-compress @image.png             - Compress an image
/crux-compress https://example.com/   - Compress a public webpage (outputs to .crux/out/)
/crux-compress ALL --force            - Force recompression (delete existing CRUX files first)
/crux-compress @file.md --minified    - Compress with single-line output (note that LLMs take more effort to parse and understand this format)
/crux-compress @file.md --plugin=frontmatter-tagger - Run a plugin while compressing

Flags:

Flag	Description
--minified	Single-line output, no spaces, max compression
--force	Delete existing CRUX output files before compression (bypasses checksum skip)
--plugin <name> / --plugin=<name>	Enable a named plugin from .crux/plugins/registry.json
--no-plugin <name>	Disable a specific default-enabled plugin

Key Features:

• Parallelism: Spawns up to 4 crux-cursor-rule-manager subagents in parallel
• Batching: Processes files in batches of 4 when >4 files
• Source Checksum Tracking: Skips files whose sourceChecksum hasn't changed (use --force to bypass)
• URL Compression: Compress public webpages using sourceUrl instead of sourceChecksum (outputs to .crux/out/)
• Default Output Location: URL sources and unspecified locations output to .crux/out/
• Two-tier output: Universal .crux.md + Cursor adapter .crux.mdc (when source is in .cursor/rules/)
• Eligibility: Markdown needs crux: true frontmatter; code/images need explicit file reference
• Plugin Hooks: Optional lifecycle plugins (beforeFetch, beforeCompress, afterCompress, afterValidate) can be enabled via command param
• Default Plugins: Plugins with enabledByDefault: true load automatically when no --plugin flags are specified. Use --no-plugin <name> to opt out of a default plugin.

Plugin Registry:

Plugins are declared in .crux/plugins/registry.json:

{
  "plugins": {
    "compression-level": {
      "description": "Enforce compression ratio targets and generate token metrics.",
      "hooks": ["beforeCompress", "afterCompress"],
      "failClosed": false,
      "enabledByDefault": true
    },
    "frontmatter-tagger": {
      "description": "Add standardized metadata after compression.",
      "hooks": ["afterCompress"],
      "failClosed": false,
      "enabledByDefault": false
    },
    "quality-gate": {
      "description": "Apply additional policy checks after validation.",
      "hooks": ["afterValidate"],
      "failClosed": false,
      "enabledByDefault": false
    },
    "release-notes": {
      "description": "Collect per-file reduction metrics for release summaries.",
      "hooks": ["afterCompress", "afterValidate"],
      "failClosed": false,
      "enabledByDefault": false
    }
  }
}

Plugin Loading Modes:

• No --plugin flags: Default-enabled plugins (e.g. compression-level) load automatically. Use --no-plugin compression-level to opt out.
• Explicit --plugin flags: Only the named plugins load. Defaults are not implicitly added. To get defaults plus extras: --plugin compression-level --plugin frontmatter-tagger

The compression-level plugin is the reference default plugin. It enforces compression ratio targets and injects token metrics (beforeTokens, afterTokens, reducedBy) into output frontmatter. See .crux/plugins/compression-level.md for full specification.

File Convention:

Type	Extension	Example
Source (human-readable)	.md	core-tenets.md
Compressed (universal, IDE-agnostic)	.crux.md	core-tenets.crux.md
Cursor adapter (derived)	.crux.mdc	core-tenets.crux.mdc
Compressed code	.crux.md	install.crux.md
Compressed image	.crux.md	diagram.crux.md
Compressed webpage (URL)	.crux.md	.crux/out/page.crux.md

6. crux-detect-changes.py - The Hook (.cursor/hooks/)

Purpose: A Cursor hook that automatically detects when source files with crux: true are modified and queues them for compression.

How It Works:

1. Triggered by the afterFileEdit Cursor hook
2. Checks if the edited file is in .cursor/rules/ with .md extension (not .crux.mdc)
3. Verifies the file has crux: true in its frontmatter
4. Queues the file in .crux/pending-compression.json for later compression

Hook Configuration (.cursor/hooks.json):

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "command": "python3 .cursor/hooks/crux-session-start.py",
        "description": "Display pending CRUX compressions at session start"
      }
    ],
    "afterFileEdit": [
      {
        "command": "python3 .cursor/hooks/crux-detect-changes.py",
        "description": "Queue modified source files for CRUX compression"
      }
    ]
  }
}

Benefits:

• Automatically tracks which source files need recompression
• Displays pending compressions at session start
• Avoids manual tracking of modified files
• Works with the /crux-compress command workflow

7. crux-utils - The Skill (.cursor/skills/crux/)

Purpose: Multi-purpose utility for CRUX compression workflows.

Modes:

Mode	Purpose
--token-count <file>	Estimate tokens for a file
--token-count --ratio <src> <crux>	Compare source vs CRUX, calculate compression ratio
--token-count --ratio <src> <crux> --target <n>	Compare with custom target percentage (default 25)
--cksum <file>	Get checksum formatted for sourceChecksum frontmatter

Token Estimation Method:

Content Type	Chars/Token	Notes
Prose	4.0	Markdown text, headers, lists
Code blocks	3.5	More symbols, shorter identifiers
Special chars	1.0	CRUX Unicode symbols (→, ⊳, «, etc.)

Benefits:

• Deterministic (same input = same output)
• Content-aware (different ratios for prose vs code)
• CRUX-aware (counts special Unicode symbols)
• Used by crux-cursor-rule-manager for frontmatter metrics

See .cursor/skills/crux/crux-utils/SKILL.md for detailed usage.

Memories

CRUX Memories is an optional learning system that lets agents extract, store, and recall knowledge across sessions. Memories persist as structured markdown files and are automatically surfaced to agents based on relevance.

The memory lifecycle has four phases:

• Dream — After completing a spec, extract learnings, red flags, goals, and ideas into memory files
• REM Sleep — Periodically rebalance the memory corpus: promote high-value memories, demote stale ones, consolidate duplicates, archive unused entries
• Recall — Query and display memories in human-readable form (read-only)
• Forget — Remove incorrect or unwanted memories from the corpus

Enabling Memories

Memories are disabled by default. To scaffold the memory system during install:

curl -fsSL .../install.py | python3 - --with-memories

Or enable manually by editing .crux/crux-memories.json and setting enableMemories to "true":

{
  "flags": [
    { "enableMemories": "true" }
  ]
}

Memories are stored in the memories/ directory, organized by type:

Type	Directory	Purpose
Core	memories/core/	Proven, high-value knowledge
Red Flag	memories/redflag/	Pitfalls, anti-patterns, things to avoid
Goal	memories/goal/	Aspirational targets and objectives
Learning	memories/learning/	Patterns and insights from completed work
Idea	memories/idea/	Speculative thoughts for future consideration

Agent-scoped memories live under memories/agents/{agent-id}/ and are isolated per agent.

Memory Commands

Command	Purpose
/crux-dream <spec-name>	Extract memories from a completed spec
/crux-dream --rem	Run REM sleep (rebalance all memories)
/crux-dream --rem --yolo	REM sleep with auto-apply for non-conflict changes
/crux-recall	Show contextually relevant memories
/crux-recall "query"	Search memories by keyword
/crux-recall <spec-name>	Show memories from a specific spec
/crux-recall --total	Visualize the entire memory system as an interactive canvas
/crux-forget <memory-id>	Forget a specific memory by ID
/crux-forget "query"	Search and select memories to forget
/crux-remember	Interactively create a new ad-hoc memory
/crux-remember "insight"	Create a memory from provided text
/crux-remember "insight" --type learning	Create with a specific type
/crux-meditate	Deep research exploration of current context — Research mode (default) with citations, peer review, adversarial review, and a paired HTML + PDF report. A merged invocation gate offers richness levels compact / default / detailed / exhaustive (default preselected). A post-consolidation finalisation-enhancement gate (K10, multi-select 0–5) refines the report before adversarial review.
/crux-meditate "topic"	Same for a specific theme — e.g. /crux-meditate "should we adopt event sourcing for the auth service"
/crux-meditate --quick "topic"	Faster parallel fan-out (no peer review); citations still required but enforced warn-only
/crux-meditate --random-model "topic"	Single tree, model randomly picked from cruxMemories.meditate.modelPool; same agent count as default
/crux-meditate --model-per-branch "topic"	Single tree, each top-level facet branch assigned a distinct model from the pool (descendants inherit); same agent count as default; per-branch model attribution recorded in the report

Meditate: Recursion mode and Model strategy

/crux-meditate is the heaviest command in the suite — it spawns a recursive research tree of subagents that mine memories, files, and chat history, then delivers a paired HTML + PDF report under meditations/{yyyymmdd}-{topic-slug}/ with infographics, Chart.js / D3 visualisations, an in-page table of contents, a citations index, and a mandatory adversarial review pass over every output file. Reach for it on high-stakes problems you'd otherwise spend a day researching by hand: architecture trade-offs, technology selection, strategic investments.

A meditation is controlled by two orthogonal axes: recursion mode (Research vs Quick) and model strategy (how cruxMemories.meditate.modelPool is used, if at all).

Recursion mode

Mode	Flag	Best for
Research (default)	none	Depth-first serial recursion with globally unique facets, mandatory inline citations, and branch peer review. Pick this when the output will be cited, persisted, or drive downstream work.
Quick	--quick	Fast parallel fan-out (legacy shape). Same report contract and visualisation requirements, no peer review, warn-only citation enforcement. Use for breadth-first early scoping.

Model strategy (combinable with either recursion mode)

Strategy	Flag	Trees	Agent count	Best for
Single (default)	none	1, on the caller's model	baseline	Standard runs.
Random model	--random-model	1, on a randomly-picked pool entry	same as baseline	Cheap diversity sampling across multiple invocations.
Model per branch	--model-per-branch	1, each top-level facet branch assigned a distinct pool model (descendants inherit; sampling without replacement when poolSize ≥ branchCount, otherwise round-robin)	same as baseline	Comparing how different models explore different facets without paying the full Ensemble Max cost. Peer reviewer and adversarial reviewer run on the caller's model for a unified cross-branch evaluation.
Ensemble (max)	--ensemble	N parallel trees + cross-model aggregator	~N × baseline + 1	Maximum-confidence analysis where convergence / divergence between every pool model is the deliverable. Combinable with --quick.

--random-model, --model-per-branch, and --ensemble are mutually exclusive. The cost-and-richness gate also lets you swap between strategies in place (only the swaps satisfied by the configured modelPool size are offered).

Before the tree spawns, four mandatory pre-spawn gates protect you from runaway cost (depth-3 Research is ~45 agents):

1. Depth Selection (Q-Depth-Selection) — 1 / 2 / 3, default 3.
2. Cost & Scope Acknowledgment (Q-Cost-Acknowledgment) — surfaces the agent count for the selected mode and lets you swap to Quick or Ensemble, or cancel.
3. Theme Preflight (Q1–Q5) — anti-homogenisation styling questions so every report feels deliberately different from the default AI look.
4. Facet Confirmation (Q-Confirm-1 and Q-Confirm-2) — you approve the three top-level facets before any branches spawn, and opt in to deep-facet confirmation if desired.

If the adversarial review can't reach PASS in ≤3 iterations, the report is not generated and you receive the review iterations plus a structured summary of unresolved findings instead.

Session-Only Memory Override

Use /crux-amnesia when you want a clean chat session without ambient memory recall, annotations, or reference tracking. This override only affects the current chat session and spawned subagents for ordinary work; it never edits .crux/crux-memories.json and does not block explicit memory-management commands like /crux-dream, /crux-recall, /crux-forget, /crux-remember, or /crux-meditate.

Memory Skills

Six specialized skills power the memory system:

Skill	Purpose
crux-skill-memory-crud	Create, read, update, delete memory files with frontmatter management
crux-skill-memory-extract	Analyse completed work and propose ranked candidate facts
crux-skill-memory-rebalance	Consolidate, promote, demote, and archive memories during REM sleep
crux-skill-memory-compress	CRUX-compress memory file bodies with adaptive sizing
crux-skill-memory-index	Build a prioritised memory index from all memory files
crux-skill-memory-reference-tracker	Track memory references in agent output and sync strength counters

Meditation Skills

Six dedicated skills power the crux-cursor-meditation-guide agent:

Skill	Purpose
crux-skill-memory-meditation-research	Research-mode Phases A–G depth-first recursion protocol
crux-skill-memory-meditation-quick	Quick-mode 6-step parallel fan-out protocol
crux-skill-memory-meditation-ensemble	Ensemble Aggregation cross-model synthesis
crux-skill-memory-meditation-review	13-dimension adversarial review-and-fix cycle
crux-skill-memory-meditation-report	Mandatory paired HTML+PDF report generation
crux-skill-memory-meditation-coordination	File-based coordination primitives and artefact filename grammar

Type Transitions and Reference Tracking

Memories gain strength through reference tracking — each time an agent uses a memory, its reference count increments. When a memory reaches a promotion threshold, it transitions to a higher type:

• idea → learning (at 5 references)
• learning → core (at 15 references)
• redflag → core (at 10 references)

Memories unreferenced for 90 days are demoted; after 180 days they are archived. Memories with very high reference counts (30+) may be promoted to permanent Cursor rules.

Memory bodies can be CRUX-compressed to save storage and context tokens, with the original source archived for rollback.

MCP Server (Optional)

The CRUX MCP server provides semantic search over the memory corpus via the Model Context Protocol. Agents with MCP access can search memories more effectively than linear index scanning.

Installation

The MCP server is distributed as a standalone zip and installed independently of any project. It runs at the user level so all your Cursor projects can use it:

# Install via the CRUX installer
curl -fsSL https://raw.githubusercontent.com/zotoio/CRUX-Compress/main/install.py | python3 - --with-mcp-server

# Or add it to an existing CRUX installation
python3 .crux/update.py --with-mcp-server

This will:

1. Download the MCP server package from the latest release
2. Install it to ~/.crux-mcp-server/ (or a directory you choose)
3. Install Python dependencies (fastmcp, pyyaml, watchdog)
4. Configure the user-level ~/.cursor/mcp.json so the server is available across all projects

Configuration

The installer configures ~/.cursor/mcp.json automatically:

{
  "mcpServers": {
    "crux-memories": {
      "command": "python3",
      "args": ["-m", "crux_mcp_server", "-t", "stdio"],
      "cwd": "~/.crux-mcp-server"
    }
  }
}

Each project still needs its own .crux/crux-memories.json (created by --with-memories) with memory paths pointing to that project's memory directory.

The server can also run in HTTP mode for external integrations:

cd ~/.crux-mcp-server
python3 -m crux_mcp_server -t http --port 8742

See crux_mcp_server/README.md for full options and tool documentation.

Python Dependencies

The memory system and MCP server require Python >= 3.10. Dependencies are installed automatically by the installer. For manual or dev setup:

# MCP server (installed automatically by --with-mcp-server)
pip install -r crux_mcp_server/requirements.txt

# Eval tests
pip install -r evals/requirements.txt

Installation in Another Project

To use CRUX in your project, see Quick Install.

File	Purpose
CRUX.md	Specification (READONLY)
AGENTS.md	Agent awareness notice (or add the <CRUX> block to your existing AGENTS.md)
install.crux.md	Installer spec (update reference)
.crux/crux.json	Installed CRUX version
.crux/crux-release-files.json	Release manifest with per-version checksums
.cursor/hooks.json	Hook configuration
.cursor/hooks/crux-detect-changes.py	File change detection hook
.cursor/hooks/crux-detect-memory-changes.py	Memory change detection hook
.cursor/hooks/crux-session-start.py	Session start hook
.cursor/agents/crux/crux-cursor-rule-manager.md	Compression subagent
.cursor/agents/crux/crux-cursor-memory-manager.md	Memory lifecycle dispatcher (deprecated — see thin agents below)
.cursor/agents/crux/crux-memory-dream.md	Dream mode agent (memory extraction)
.cursor/agents/crux/crux-memory-rem.md	REM Sleep mode agent (rebalance)
.cursor/agents/crux/crux-memory-recall.md	Recall mode agent (query memories)
.cursor/agents/crux/crux-memory-remember.md	Remember mode agent (ad-hoc creation)
.cursor/agents/crux/crux-memory-forget.md	Forget mode agent (memory removal)
.cursor/agents/crux/templates/recall-canvas.tsx.md	Canvas structural template (used by Recall --total)
.cursor/agents/crux/crux-cursor-meditation-guide.md	Recursive meditation research guide (spawned by /crux-meditate)
.cursor/commands/crux/crux-compress.md	Compression command
.cursor/commands/crux/crux-dream.md	Memory extraction command

Then:

1. Ensure .cursor/hooks.json is recognized by Cursor
2. Add crux: true to any rule files you want to compress
3. Use /crux-compress ALL to compress eligible files

How They Work Together

Compression Flow

flowchart TD
    USER["User: /crux-compress @.cursor/rules/my-rule.md"]
    
    subgraph COMMAND["crux-compress.md (Command)"]
        C1["Parse arguments"]
        C2["Resolve plugins (--plugin)"]
        C3["Spawn subagent(s)"]
        C1 --> C2 --> C3
    end
    
    subgraph MANAGER["crux-cursor-rule-manager (Subagent)"]
        M1["1. Read CRUX.md specification"]
        M2["2. Get checksum (crux-utils skill)"]
        M3{"3. sourceChecksum matches?"}
        M4["4. Read source file"]
        M5["5. Estimate tokens (crux-utils skill)"]
        M6{"6. Reduction ≥50%?"}
        M7["7. Apply compression rules"]
        M8["8. Write .crux.md (universal)"]
        M9{"9. Source in .cursor/rules/?"}
        M10["10. Copy to .crux.mdc + alwaysApply"]
        
        M1 --> M2 --> M3
        M3 -->|"Yes"| SKIP["Skip - source unchanged"]
        M3 -->|"No"| M4 --> M5 --> M6
        M6 -->|"No"| ABORT["Abort - not beneficial"]
        M6 -->|"Yes"| M7 --> M8 --> M9
        M9 -->|"Yes"| M10
        M9 -->|"No"| DONE["Done"]
    end
    
    USER --> COMMAND
    COMMAND --> MANAGER

Decompression Flow (Runtime)

flowchart TD
    START["Agent loads context"]
    
    subgraph RULE["_CRUX-RULE.mdc (Always Applied)"]
        R1["Instructs: interpret CRUX notation"]
        R2["Points to CRUX.md for symbols"]
    end
    
    subgraph INTERPRET["Agent encounters «CRUX⟨source.md⟩»"]
        I1["Uses compressed content directly"]
        I2["Does NOT load source.md"]
        I3["Interprets symbols per CRUX.md"]
    end
    
    START --> RULE
    RULE --> INTERPRET

Synchronization Flow

flowchart TD
    START["User modifies source.md"]
    
    subgraph RULE["_CRUX-RULE.mdc detects change"]
        R1["Triggers: SURGICAL DIFF UPDATES"]
        R2["Invokes crux-cursor-rule-manager"]
        R1 --> R2
    end
    
    subgraph MANAGER["crux-cursor-rule-manager"]
        M1["Read existing .crux.md"]
        M2["Identify what changed in source"]
        M3["Apply minimal targeted edits"]
        M4["Update generated timestamp"]
        M5["Update sourceChecksum"]
        M6["Regenerate .crux.mdc adapter (if applicable)"]
        
        M1 --> M2 --> M3 --> M4 --> M5 --> M6
    end
    
    START --> RULE
    RULE --> MANAGER

Foundational Rules (All Components Enforce)

These rules are defined in CRUX.md (numbered 0-4) and enforced by all CRUX components:

0. ALWAYS INTERPRET AND UNDERSTAND ALL CRUX RULES FIRST - At session start, interpret all CRUX notation in rules. When new rules are added to context, interpret them immediately. Build a mental model of all rules that can be visualized on request.
1. NEVER EDIT CRUX.md - The specification is read-only unless explicitly asked by the user
2. DO NOT LOAD SOURCE FILES when CRUX exists - Use «CRUX⟨...⟩» content directly
3. SURGICAL DIFF UPDATES - Keep CRUX files synchronized with source changes
4. ABORT IF NO SIGNIFICANT REDUCTION - Target ≤20% of original; skip if not achieved

File Locations Summary

Component	Path	Purpose
Specification	CRUX.md	Defines notation syntax
Agent Notice	AGENTS.md (CRUX block)	High-visibility awareness
Version Metadata	.crux/crux.json	Installed CRUX version
Release Manifest	.crux/crux-release-files.json	File checksums for backup
Always-Applied Rule	.cursor/rules/crux/_CRUX-RULE.mdc	Runtime instructions
Subagent	.cursor/agents/crux/crux-cursor-rule-manager.md	Compression executor
Compress Command	.cursor/commands/crux/crux-compress.md	Compression interface
Test Command	.cursor/commands/crux-test.md	Pytest command-suite shim
Hook	.cursor/hooks/crux-detect-changes.py	Auto-detect file changes
Session Hook	.cursor/hooks/crux-session-start.py	Show pending compressions
Hook Config	.cursor/hooks.json	Hook configuration
Utility Skill	.cursor/skills/crux/crux-utils/	Token estimation, checksums
Install Script	install.py	Curl-pipe installer (Python)
Zip Builder	scripts/create-crux-zip.py	Build distribution zip
Tests	evals/*.py	Pytest test suite
CI Workflows	.github/workflows/	Automated testing and releases
Dev Rules	.cursor/rules/*.mdc	Development workflow rules
Plugin Registry	.crux/plugins/registry.json	Plugin declarations and hook bindings
Plugin Spec	.crux/plugins/compression-level.md	Default compression-level plugin spec

Quick Reference

To Compress a Rule File

/crux-compress @.cursor/rules/my-rule.md

To Make a File Eligible for Compression

Add to frontmatter:

---
crux: true
---

Note: Both .md and .mdc files with crux: true are eligible. For .mdc files, the compression workflow will:

1. Rename the file to .md (preserving the source)
2. Compress to .crux.md (universal output)
3. If in .cursor/rules/, also produce .crux.mdc (Cursor adapter with alwaysApply)

To Check Compression Ratio and Confidence

Compressed files include metrics in frontmatter:

beforeTokens: 2500  # Original
afterTokens: 400    # Compressed (16% of original)
reducedBy: 84%      # Compression percentage
confidence: 92%     # Semantic validation score

Confidence Score indicates how well CRUX preserves semantic meaning:

• ≥90%: Excellent (accept as-is)
• 80-89%: Good (accept)
• 70-79%: Marginal (review)
• <70%: Poor (revise)

CRUX Notation Quick Reference

STRUCTURE:  «»⟨⟩{}[]().sub
COMPARE:    > < ≥ ≤
PRIORITY:   ≻ ≺
DATA FLOW:  → ←
RELATIONS:  ⊳ ⊲ @ : = ∋
LOGIC:      | & ⊤ ⊥ ∀ ∃ ¬
CHANGE:     Δ + -
QUALIFY:    * ? ! #
IMPORTANCE: ⊛ ◊
BLOCKS:     Ρ E Λ Π Κ R P Γ M Φ Ω

See CRUX.md for complete specification.

Testing

CRUX Compress includes comprehensive test coverage for all scripts.

Running Tests Locally

Tests use pytest:

# Install test dependencies
pip install -r evals/requirements.txt

# Run all tests
pytest evals/ -v

# Run specific test file
pytest evals/test_crux_utils.py -v

# Run with short output
pytest evals/ --tb=short

Running Shellcheck Locally

All shell scripts are validated with shellcheck. Run locally before committing:

# Install shellcheck (if not already installed)
# macOS
brew install shellcheck

# Ubuntu/Debian
sudo apt install shellcheck

# Run all tests
python3 scripts/test.py

Test Coverage

Script	Test File	Coverage
crux-utils.py	test_crux_utils.py	Token counting, checksums, ratios, --target flag, error handling
scripts/create-crux-zip.py	test_create_zip.py	Zip contents, version embedding, structure
crux-detect-changes.py	test_detect_hook.py	Frontmatter detection, queue management
install.py	test_install.py	CLI flags, version comparison, hooks merge, --with-memories, --with-mcp-server, upsert
registry.json	test_n_plugin_registry.py	Registry schema, enabledByDefault semantics, plugin validation
Memory CRUD	test_a_memory_crud.py	Memory create, read, update, delete
Dream extraction	test_b_dream_workflow.py	Post-spec memory extraction workflow
REM sleep	test_c_rem_sleep.py	Promotion, demotion, archival
Reference tracking	test_d_reference_tracking.py	Usage tracking and strength sync
Memory index	test_e_memory_index.py	Index building and prioritisation
Type transitions	test_f_type_transitions.py	Type transition logic
Memory compression	test_g_compression.py	Memory CRUX compression
Agent scoping	test_h_agent_scoping.py	Agent memory isolation
Scope ranking	test_i_scope_ranking.py	Scope ranking logic
Session hook	test_k_session_hook.py	Memory nudge on session start
MCP server	test_l_mcp_server.py	MCP server tools
Config validation

Python Eval Tests

The evals/ directory contains pytest-based integration tests for the memory system:

# Install dependencies
pip install -r evals/requirements.txt

# Run eval tests
pytest evals/ -v

The scripts/test.py wrapper runs available automated test suites in sequence and prints a warning instead of a false success when required tools such as pytest are not installed.

Command Suite Testing (/crux-test)

/crux-test is a thin pytest shim. Cases live in evals/test_r_crux_command_suite.py; LLM-driven scenarios are marked llm_driven and skipped by default in CI.

# All deterministic command-suite tests
python3 scripts/run_crux_command_suite.py

# Fast CI smoke subset
python3 scripts/run_crux_command_suite.py --smoke

# Smoke via pytest directly
python3 -m pytest evals/test_r_crux_command_suite.py -m crux_command_smoke -v

In Cursor, invoke /crux-test to run the same suite. Historical scenario names (compression, validation, etc.) map to pytest classes documented in the /crux-test command.

CI/CD

CRUX Compress uses GitHub Actions for automated testing and releases.

Workflows

Workflow	Trigger	Purpose
test.yml	PR, Push	Runs pytest, validates zip, checks scripts
version-bump.yml	Push to main	Auto-bumps version based on conventional commits
release.yml	Version change	Creates GitHub Release with zip artifact

Conventional Commits

Version bumping follows conventional commits:

Commit Type	Version Bump	Example
feat:	Minor (1.X.0)	feat: add new compression mode
fix:	Patch (1.0.X)	fix: handle empty files
BREAKING CHANGE:	Major (X.0.0)	Body contains "BREAKING CHANGE:"
Other	Patch (1.0.X)	docs: update readme

Release Process

1. Push commits to main with conventional commit messages
2. version-bump.yml reads .crux/dist-manifest.json for release-relevant paths, analyzes commits, and updates .crux/crux.json
3. release.yml detects version change and runs scripts/create-crux-zip.py, which:

• Builds the versioned zip (CRUX-Compress-vX.Y.Z.zip)
• Updates .crux/dist-manifest.json (canonical file list)
• Generates checksums and updates .crux/crux-release-files.json

4. The workflow then creates a GitHub Release with tag vX.X.Z, attaches the zip, and generates release notes

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make changes and add tests
4. Run tests: pytest evals/ -v
5. Commit with conventional message: git commit -m "feat: add my feature"
6. Push and create PR

License

MIT License - see LICENSE file for details.