ΣCRUX Compress

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

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:

You write rules in natural language markdown — readable, maintainable, version-controllable
CRUX compresses them — extracting the "crux" (the decisive, most important points) into a compact symbolic notation
Compressed rules load into context — achieving 5-10x token reduction (target ≤20% of original)
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          │
│                                                           │
└───────────────────────────────────────────────────────────┘

BEFORE — Original Rule (625 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 Not allowed in production code

Magic numbers Extract to named constants instead

Examples

Good Practice

When handling errors, use try/catch with proper logging and handling:
try {
  await riskyOperation();
} catch (error) {
  logger.error('Operation failed', error);
  handleError(error);
}
Bad Practice

Never silently swallow errors:
try {
  await riskyOperation();
} catch (e) {
  /* ignore */
}
Core Principles

Quality takes priority over speed — Don't sacrifice code quality to ship faster

Readable code takes priority over clever code — Write code that others can understand

AFTER — CRUX Compressed (112 tokens)

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}⟧

Formatted CRUX (for readability)

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-cursor-rule-manager.md`	Compression subagent
`.cursor/commands/crux-compress.md`	Compression command
`.cursor/rules/_CRUX-RULE.mdc`	Always-applied rule
`.cursor/skills/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 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/"]
        MANAGER["crux-cursor-rule-manager.md<br/>(Subagent - ΣCRUX)<br/>.cursor/agents/"]
        COMMAND["crux-compress.md<br/>(Cursor Command)<br/>.cursor/commands/"]
        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/`)

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/`)

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:

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

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:

Triggered by the afterFileEdit Cursor hook
Checks if the edited file is in .cursor/rules/ with .md extension (not .crux.mdc)
Verifies the file has crux: true in its frontmatter
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/`)

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-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 a 3D graph
`/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`	Recursive memory-informed exploration of current context
`/crux-meditate "topic"`	Explore a specific theme with 3-level deep memory search
`/crux-amnesia`	Toggle session-only amnesia mode for ambient memory usage
`/crux-amnesia on\|off\|status`	Disable, restore, or inspect session memory mode without changing repo config

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

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:

Download the MCP server package from the latest release
Install it to ~/.crux-mcp-server/ (or a directory you choose)
Install Python dependencies (fastmcp, pyyaml, watchdog)
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-cursor-rule-manager.md`	Compression subagent
`.cursor/agents/crux-cursor-memory-manager.md`	Memory lifecycle agent
`.cursor/commands/crux-compress.md`	Compression command
`.cursor/commands/crux-dream.md`	Memory extraction command
`.cursor/commands/crux-recall.md`	Memory retrieval command
`.cursor/commands/crux-forget.md`	Memory removal command
`.cursor/commands/crux-remember.md`	Ad-hoc memory creation command
`.cursor/commands/crux-meditate.md`	Recursive exploration command
`.cursor/rules/_CRUX-RULE.mdc`	Always-applied rule
`.cursor/rules/crux-memories-integration.crux.mdc`	Memory integration rule
`.cursor/skills/crux-utils/`	Utility skill (token estimation, checksums)
`.cursor/skills/crux-skill-memory-*/`	Memory skills (CRUD, compress, extract, index, rebalance, reference tracking)

Then:

Ensure .cursor/hooks.json is recognized by Cursor
Add crux: true to any rule files you want to compress
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:

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.
NEVER EDIT CRUX.md - The specification is read-only unless explicitly asked by the user
DO NOT LOAD SOURCE FILES when CRUX exists - Use «CRUX⟨...⟩» content directly
SURGICAL DIFF UPDATES - Keep CRUX files synchronized with source changes
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-RULE.mdc`	Runtime instructions
Subagent	`.cursor/agents/crux-cursor-rule-manager.md`	Compression executor
Compress Command	`.cursor/commands/crux-compress.md`	Compression interface
Test Command	`.cursor/commands/crux-test.md`	LLM feature testing
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-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
Memory Config	`.crux/crux-memories.json`	Memory system configuration
Memory Index	`.crux/memory-index.yml`	Prioritised memory index
Memory Manager	`.cursor/agents/crux-cursor-memory-manager.md`	Memory lifecycle agent
Dream Command	`.cursor/commands/crux-dream.md`	Memory extraction command
Recall Command	`.cursor/commands/crux-recall.md`	Memory query command
Forget Command	`.cursor/commands/crux-forget.md`	Memory removal interface
Remember Command	`.cursor/commands/crux-remember.md`	Ad-hoc memory creation
Meditate Command	`.cursor/commands/crux-meditate.md`	Recursive memory exploration
MCP Server	`crux_mcp_server/`	Semantic memory search server (standalone zip)
Memory Skills	`.cursor/skills/crux-skill-memory-*/`	Memory operation skills
Memory Storage	`memories/`	Memory file storage
Eval Tests	`evals/`	Python-based eval test suite

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:

Rename the file to .md (preserving the source)
Compress to .crux.md (universal output)
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	`test_m_config_validation.py`	Configuration 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.

LLM Feature Testing

Use the /crux-test command in Cursor to run comprehensive LLM-driven tests:

/crux-test              - Run all tests
/crux-test compression  - Test compression only
/crux-test validation   - Test semantic validation only

This generates a CRUX-TEST-REPORT.md with detailed results including:

Compression metrics
Token reduction analysis
Semantic validation scores
Any issues found

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

Push commits to main with conventional commit messages
version-bump.yml reads .crux/dist-manifest.json for release-relevant paths, analyzes commits, and updates .crux/crux.json
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

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

Contributing

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

License

MIT License - see LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 181 Commits
.crux		.crux
.cursor		.cursor
.github/workflows		.github/workflows
analysis		analysis
crux_mcp_server		crux_mcp_server
docs		docs
evals		evals
memories		memories
scripts		scripts
specs		specs
tests/fixtures		tests/fixtures
web		web
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTORS.md		CONTRIBUTORS.md
CRUX-TEST-REPORT.md		CRUX-TEST-REPORT.md
CRUX.md		CRUX.md
LICENSE.md		LICENSE.md
README.md		README.md
crux-cicd-and-hooks.png		crux-cicd-and-hooks.png
crux-overview.png		crux-overview.png
install.crux.md		install.crux.md
install.py		install.py

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

Anti-Pattern	Guidance
`any` type	Strictly forbidden! Always use proper types
`console.log`	Not allowed in production code
Magic numbers	Extract to named constants instead

Folders and files

Latest commit

History

Repository files navigation

ΣCRUX Compress

Table of Contents

The Problem

The Approach

Demonstration

Team Development Standards

Key Definitions

Style Rules

Indentation & Formatting

Naming Conventions

Quality Rules

Size Limits

Documentation & Testing

Complexity

Code Review Process

Patterns to Avoid

Examples

Good Practice

Bad Practice

Core Principles

Etymology

Quick Install

Recommended: Agent-Driven Install

Alternative: One-Line Script Install

Install Options

What Gets Installed

Upgrading

System Architecture

Component Details

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

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

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

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

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

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

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

Memories

Enabling Memories

Memory Commands

Session-Only Memory Override

Memory Skills

Type Transitions and Reference Tracking

MCP Server (Optional)

Installation

Configuration

Python Dependencies

Installation in Another Project

How They Work Together

Compression Flow

Decompression Flow (Runtime)

Synchronization Flow

Foundational Rules (All Components Enforce)

File Locations Summary

Quick Reference

To Compress a Rule File

To Make a File Eligible for Compression

To Check Compression Ratio and Confidence

CRUX Notation Quick Reference

Testing

Running Tests Locally

Running Shellcheck Locally

Test Coverage

Python Eval Tests

LLM Feature Testing

CI/CD

Workflows

Conventional Commits

Release Process

Contributing

License

About

Topics

Resources

License

Uh oh!

Stars

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

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

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

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

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

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

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

Packages