CRUX Memories

Agents that learn. CRUX Memories lets your AI agents extract insights from completed work and reuse them in future sessions — like long-term memory for your codebase.

System Architecture

The memory system is fully managed by CRUX. Consumers only provide configuration — all engine logic, storage, tracking, and lifecycle management ships with the CRUX tool.

COMMANDS /crux-dream /crux-recall /crux-forget /crux-remember /crux-meditate MEMORY MANAGER AGENT Orchestrates all memory operations crux-cursor-memory-manager CONFIG .crux/crux-memories.json Flags, paths, thresholds, transitions 6 SKILLS memory-extract Analyse & propose memory-crud Create, read, update memory-rebalance Promote & demote memory-compress CRUX-compress memory-index Build priority index memory-ref-tracker Track usage STORAGE LAYER memories/ core/ redflag/ goal/ learning/ idea/ *.memory.md | *.memory.crux.md memories/agents/ code-reviewer/ test-generator/ Scoped per agent identity .crux/ memory-index.yml Prioritised discovery Rebuilt after every change reference-tracking/ *.refs.yml Per-memory usage data Drives promote/demote HOOKS Session start nudge Post-dream rebuild MCP SERVER (optional) Semantic search via sentence-transformers PLATFORMS Cursor | Claude Code | Generic Same engine, different wiring

The Memory Lifecycle

Memories follow a continuous lifecycle: agents do work, learnings are extracted via dreaming, memories are consolidated during REM sleep, and surfaced on demand via Recall.

WORK Complete a spec or unit of work DREAM Extract learnings /crux-dream Analyse & save facts REM Rebalance /crux-dream --rem Promote, demote, merge RECALL Query on demand extract consolidate surface inform FORGET /crux-forget Remove from any phase forget

Dream Workflow

After a spec (or unit of work) completes, run /crux-dream to extract learnings. The agent walks through a structured analysis flow.

1. VERIFY Check spec completed 2. DIFF Repo changes since spec start 3. ANALYSE Spec + output + existing memories 4. CONFLICTS Detect contra- dictions, resolve 5. PRESENT Top N candidate facts for review 6. SAVE CRUD memories user confirms 7. ARCHIVE Move spec or keep Candidate Fact Example [learning] React.memo on list items reduced re-render time from 480ms to 12ms on 500-item lists strength: 1 | source: component-library tags: [react, performance, rendering] Conflict Detection When a new candidate contradicts an existing memory, the agent presents both sides and asks: 1. Keep existing 2. Replace with new 3. Merge both 4. Keep both + note Archival Options After memories are saved, the agent offers to handle the spec: 1. Move to archive (recommended) 2. Leave in place 3. Delete Summary written to spec directory

REM Sleep Workflow

Periodic rebalancing of the entire memory corpus. Run /crux-dream --rem to scan all memories and trackers, detect issues, and apply corrections.

1. LOAD All memories + trackers 2. VERIFY Consistency check 3. CONFLICTS Detect contradictions 4. RECOMMEND & APPLY User confirms changes Recommendation Categories PROMOTE Strength exceeds promoteAt threshold idea@5 → learning@15 → core DEMOTE Unreferenced for longer than threshold default: 90 days ARCHIVE Unreferenced for longer than archive default: 180 days CONSOLIDATE Merge duplicate or near-duplicate memories PROMOTE TO RULE 30+ references → permanent rule --yolo mode Auto-applies all non-conflict changes. Conflicts always require user input — even in unattended mode. REM summary written to archiveDir as rem-{yyyymmdd}.md covering all memories reviewed.

Memory Types & Promotion

Memories are classified into types representing different categories of knowledge. As memories prove their value through repeated use, they are automatically promoted to higher-priority types.

IDEA Speculative thoughts for future exploration Priority: 5 (lowest) 5 refs LEARNING Patterns & insights from completed work Priority: 4 15 refs CORE Proven, high-value knowledge. Highest priority type. Priority: 1 (highest) 30 refs CURSOR RULE Promoted to permanent .cursor/rules/ file Always loaded by agent RED FLAG Pitfalls & anti-patterns Priority: 2 10 refs GOAL Aspirational targets Priority: 3 | No promotion ARCHIVED Demoted after 90 days unused Archived after 180 days stale

Reference Tracking

Every time an agent's output is influenced by a memory, the reference tracker increments its count. This externalised tracking drives all promotion and demotion decisions.

AGENT OUTPUT Uses a memory insight [memory:{title}] {slug}.refs.yml slug: react-memo-list-rendering references: 12 last_referenced: 2026-04-03 strength: 3 SYNC STRENGTH Update memory frontmatter PROMOTE? Check threshold Why Per-Memory Tracker Files? Zero contention Concurrent sessions write different files Clean separation Memory frontmatter describes what, not usage Lazy creation No overhead for unreferenced memories Easy cleanup Small & diffable Drives REM sleep

Agent Scoping

Memories can be scoped to specific agent identities. Agent-scoped memories are boosted for that agent but never override higher-priority base types. This lets agents develop expertise without polluting shared knowledge.

BASE MEMORIES memories/ — shared across all agents core/ redflag/ goal/ learning/ idea/ Read/write by all agents AGENT: code-reviewer memories/agents/code-reviewer/ redflag/ learning/ idea/ BOOSTED Same type → agent wins AGENT: test-gen memories/agents/test-generator/ learning/ idea/ ISOLATED Cannot read code-reviewer Boost Resolution Rules Agent learning/ vs Base learning/ → Agent wins (same type, agent boosted) Agent learning/ vs Base redflag/ → Base wins (higher-priority type) Agent core/ vs Base learning/ → Agent wins (higher-priority type) Agent memories are only written during dream workflow — never during normal agent work

File Structure & Format

Each memory is self-contained — its YAML frontmatter and body together provide full context. Files are organised by type in subdirectories.

memories/ core/ react-memo.memory.crux.md redflag/ cache-race.memory.md goal/ learning/ usecallback-stale.memory.md idea/ k8s-limits.memory.md archived/ agents/ code-reviewer/ redflag/ learning/ idea/ test-generator/ shared/ → symlink (read-only)

Memory Frontmatter

react-memo.memory.crux.md 
---
title: "React.memo on list item components
  prevents full re-render on data changes"
description: "Wrapping list item components
  in React.memo with a custom comparator
  reduced re-render time from 480ms to 12ms
  on a 500-item list."
type: "core"
strength: 3
created: 2026-04-03
modified: 2026-04-03
source: "20260403-component-library"
tags: [react, performance, rendering]
promoted_from: "learning"
---

(CRUX-compressed memory body)
title Instructive, descriptive — conveys insight at a glance
description Self-contained summary, enough to act on without reading body
type Category matching directory: core, redflag, goal, learning, idea
strength Numeric score, auto-incremented on reference
source Unit of work that originated this memory
promoted_from Previous type if a transition occurred

Recall

Query and surface memories on demand. Compressed memories are decompressed for display without modifying files on disk.

/crux-dream Extract & rebalance
/crux-dream <spec-name>Extract memories from completed work
/crux-dream --remRun REM sleep rebalancing
/crux-dream --rem --yoloAuto-apply non-conflict changes
/crux-recall Query & display
/crux-recallShow contextually relevant memories
/crux-recall "query"Search by keyword
/crux-recall <spec-name>Show memories from a specific spec
/crux-forget Remove memories
/crux-forget <memory-id>Forget a specific memory by ID
/crux-forget "query"Search and select memories to forget
/crux-forgetList all memories for selection
/crux-remember Ad-hoc memory creation
/crux-rememberInteractively create a new memory
/crux-remember "insight"Create from provided text
/crux-remember "insight" --type learningCreate with specific type
/crux-meditate Deep research — paired HTML + PDF report
/crux-meditate "topic"Research mode (default) — depth-first recursion, peer review, mandatory citations
/crux-meditate --quick "topic"Fast parallel fan-out for breadth-first scoping
/crux-meditate --random-model "topic"Single tree, model randomly picked from modelPool (no extra cost)
/crux-meditate --model-per-branch "topic"Single tree, each top-level branch assigned a different model from the pool (no extra cost)
/crux-meditate --ensemble "topic"Ensemble max — run across every model in the pool in parallel, then cross-model synthesis
/crux-meditate @file @folder/Explore referenced code architecture
/crux-amnesia Session memory override
/crux-amnesiaToggle session-scoped amnesia mode
/crux-amnesia onDisable ambient memory usage for this chat
/crux-amnesia offReturn to config-driven memory behavior

Powered by 6 Skills

The memory system is modular — each operation is handled by a dedicated skill, orchestrated by the memory manager agent.

memory-crudCreate, read, update, delete
memory-extractAnalyse work, propose candidates
memory-rebalancePromote, demote, consolidate
memory-compressCRUX-compress memory bodies
memory-indexBuild prioritised index
memory-reference-trackerTrack usage, sync strength

Meditation Agent & 6 Skills

/crux-meditate spawns crux-cursor-meditation-guide as the dedicated recursive research orchestrator. Six additional skills power the meditation tree.

meditation-researchResearch Phases A–G recursion
meditation-quickQuick parallel fan-out
meditation-ensembleEnsemble cross-model synthesis
meditation-reviewAdversarial review cycle
meditation-reportHTML+PDF report generation
meditation-coordinationFile coordination primitives

Key Features

Reference Tracking Every time an agent uses a memory, its reference count increments. High-count memories get promoted automatically.
CRUX Compression Memory bodies are CRUX-compressed to save context tokens, with original sources archived for rollback.
Agent Scoping Memories can be scoped to specific agents under memories/agents/{id}/, keeping context isolated.
Conflict Detection Both dream and REM sleep detect contradictions between memories and present them for manual resolution.

Meditate: Deep Research with Paired HTML + PDF Reports

Run /crux-meditate "your topic" to launch a recursive, memory-informed research tree that writes its outputs to meditations/{yyyymmdd}-{topic-slug}/. The deliverable is not a chat reply — it’s a paired report-{topic-slug}-{ts}.html and report-{topic-slug}-{ts}.pdf with infographics, Chart.js / D3 visualisations, a clickable table of contents, a citations index, and a mandatory adversarial review pass over every output file. Reach for it on the high-stakes questions you’d otherwise spend a day on by hand.

A meditation is configured on two orthogonal axes: a recursion mode (how the tree explores) and a model strategy (how cruxMemories.meditate.modelPool is used, if at all).

Recursion mode

Research (default) Depth-first serial recursion with globally unique facets, mandatory inline citations, and branch peer review at the top. Pick this when the output will be cited or drive downstream work.
Quick --quick Parallel fan-out (the legacy shape illustrated below). Same report contract, no peer review, warn-only citation enforcement. Use for early-stage breadth-first scoping.

Model strategy (combinable with either recursion mode)

Single (default) One tree on the caller’s model. The baseline shape and cost.
Random model --random-model One tree, model randomly picked from modelPool at the start. Same agent count as the baseline — useful for cheap diversity sampling across multiple invocations.
Model per branch --model-per-branch One tree, each top-level facet branch assigned a distinct model from the pool (descendants inherit). Peer reviewer and adversarial reviewer run on the caller’s model for a unified evaluator. Same agent count as the baseline; the report carries per-branch model attribution.
Ensemble max --ensemble Run the entire meditation across every model in the pool in parallel, then aggregate into a cross-model synthesis report highlighting convergence, divergence, and unique insights. ~N× baseline + 1 agents. Combinable with --quick.

--random-model, --model-per-branch, and --ensemble are mutually exclusive. The cost-and-richness gate also offers in-place swaps between strategies whenever the configured modelPool size allows.

Before the tree spawns, a merged pre-spawn gate covers depth selection, cost & scope acknowledgment with mode-swap options, and richness level — choose from compact, default (preselected), detailed, or exhaustive to control report depth and agent count. The depth-0 manager also produces init-time suggestions for report sections, visualisation types, and additional focus areas before branches spawn. An anti-homogenisation theme preflight and facet confirmation complete the gates. After consolidation, a finalisation-enhancement gate (multi-select 0–5 curated upgrades) refines the report before adversarial review; skipping all reproduces previous behaviour. If the adversarial review cycle can’t reach PASS within three iterations, the report is not generated and you receive the iteration files plus unresolved findings instead.

The diagram below shows the Quick-mode parallel fan-out tree (the legacy shape, still in use under --quick). Research mode runs the same three top-level branches but recurses depth-first — each depth’s findings drive the next depth’s facet derivation — and adds a peer-review pass across the three branches before consolidation.

meditations/ facets.md branch-1.md branch-2.md branch-3.md branch-1-depth-2-sub-1.md branch-1-depth-2-sub-2.md branch-1-depth-2-sub-3.md ×3 per branch = 9 files branch-1-depth-3-sub-1.md branch-1-depth-3-sub-2.md branch-1-depth-3-sub-3.md ×9 per branch = 27 files consolidation.md ~39 output files total USER /crux-meditate "topic" LEVEL 0 — ORCHESTRATOR Create dir • Derive 3 facets • Write facets.md depth: 0 facet 1 facet 2 facet 3 DEPTH 1 — BRANCH 1 Query • Expand • 3 subfocuses Spawn 3 children • Write branch-1.md DEPTH 1 — BRANCH 2 Query • Expand • 3 subfocuses Spawn 3 children • Write branch-2.md DEPTH 1 — BRANCH 3 Query • Expand • 3 subfocuses Spawn 3 children • Write branch-3.md depth: 1 memories ×3 children each ×3 children each D2 sub-1 Subfocus A1 3 children • write .md D2 sub-2 Subfocus A2 3 children • write .md D2 sub-3 Subfocus A3 3 children • write .md ×3 branches = 9 agents Each derives 3 subfocuses depth: 2 D3 sub-1 Leaf query write .md D3 sub-2 Leaf query write .md D3 sub-3 Leaf query write .md ×9 per branch = 27 leaf agents No further recursion • Write depth-3 files depth: 3 FILE-BASED CONSOLIDATION Parents poll for child .md files • Read • Aggregate • Write own .md read .md read .md consolidation.md Cross-branch connections • Emergent themes • Actionable insights EXPAND Pick tangent directions New working dir • Repeat SAVE AS SPEC Write draft spec outline to specs/ directory END Complete the session new dir • repeat

Cross-Platform Support

The same memory engine runs identically across platforms. Only the wiring layer differs — rules location, command format, hook mechanism.

Cursor
.cursor/rules/*.mdc
.cursor/commands/crux-dream.md
.cursor/hooks/*.py
.cursor/skills/*/SKILL.md
Claude Code
CLAUDE.md
.claude/commands/crux-dream.md
.claude/hooks/session-start.sh
.mcp.json
Generic
MEMORIES_AGENT_RULE.md
crux-dream (shell script)
Git hooks / manual
MCP stdio server

Get Started

Agent Prompt 
Fetch https://raw.githubusercontent.com/zotoio/CRUX-Compress/main/install.crux.md, read it, and follow its instructions to install CRUX Compress with --with-memories

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

Opt-in Memories are disabled by default. The --with-memories flag scaffolds all memory components. Enable via .crux/crux-memories.json to start capturing agent learnings.
Full Memories Documentation →