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 Recursive exploration
/crux-meditateExplore facets from current context via file-based agent tree
/crux-meditate "topic"3-level deep, 3-way fan-out exploration to meditations/
/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

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: Recursive Exploration

Run /crux-meditate to launch a 3-level recursive, memory-informed exploration with 3-way fan-out at every level. The agent derives facets from your context and writes them to a shared working directory in meditations/. Parallel agents each explore a distinct subfocus, write their discoveries to markdown files, derive 3 narrower child subfocuses, and recurse deeper. Parent agents poll for child output files and aggregate insights back up into a final consolidation.md.

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 →