crux-skill-memory-rebalance
Skill8 starsChanged 2 months agoMITView on GitHub
Consolidate, promote, demote, and archive memories based on strength, usage patterns, and type transition rules. Use when running REM sleep, rebalancing memory strength, detecting conflicts, or cleaning up orphaned trackers.
In this repository35 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .cursor/rules/crux-memories-integration.crux.mdcCursor rule
- .cursor/rules/crux-memories-integration.mdCursor rule
- .cursor/rules/_CRUX-RULE.mdcCursor rule
- .cursor/rules/docs-sync.crux.mdCursor rule
- .cursor/rules/docs-sync.crux.mdcCursor rule
- .cursor/rules/docs-sync.mdCursor rule
- .cursor/rules/example/coding-standards-demo.crux.mdcCursor rule
- .cursor/rules/example/coding-standards-demo.mdCursor rule
- .cursor/rules/ignore-example-rules.crux.mdCursor rule
- .cursor/rules/ignore-example-rules.crux.mdcCursor rule
- .cursor/rules/ignore-example-rules.mdCursor rule
- .cursor/rules/skill-and-agent-references.mdcCursor rule
- .cursor/rules/spec-agent-allocation.crux.mdCursor rule
- .cursor/rules/spec-agent-allocation.crux.mdcCursor rule
- .cursor/rules/spec-agent-allocation.mdCursor rule
- .cursor/rules/spec-implementation-hygiene.mdcCursor rule
- .cursor/rules/version-bump.crux.mdCursor rule
- .cursor/rules/version-bump.crux.mdcCursor rule
- .cursor/rules/version-bump.mdCursor rule
- .cursor/rules/zip-contents-protection.crux.mdCursor rule
- .cursor/rules/zip-contents-protection.crux.mdcCursor rule
- .cursor/rules/zip-contents-protection.mdCursor rule
- crux-skill-memory-compressSkill
- crux-skill-memory-crudSkill
- crux-skill-memory-extractSkill
- crux-skill-memory-indexSkill
- crux-skill-memory-meditation-coordinationSkill
- crux-skill-memory-meditation-ensembleSkill
- crux-skill-memory-meditation-quickSkill
- crux-skill-memory-meditation-reportSkill
- crux-skill-memory-meditation-researchSkill
- crux-skill-memory-meditation-reviewSkill
- crux-skill-memory-reference-trackerSkill
- crux-utilsSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
43 rules. About 0 are common, 15 are distinctive, and 28 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈15
Distinctive · estimate
This author's own choices. Worth a look.
28
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Use this skill when:
- Very specific: line 23
Guard check: If flags.enableMemories is not "true", abort and inform the caller that memories are disabled.
- Distinctive: line 40
Check for data integrity issues:
- Very specific: line 68
Look up the memory's current type in typeTransitions
- Very specific: line 69
If promoteAt is null, skip (terminal type)
- Very specific: line 70
If strength >= promoteAt, recommend promotion to promoteTo
- Very specific: line 85
If days > demoteAfterDaysUnreferenced (default 90) and the memory is not already archived:
- Very specific: line 86
If memory type is core, recommend demotion to learning
- Very specific: line 89
If memory type is idea, recommend archival instead (skip to Step 6)
- Very specific: line 94
If days > demoteAfterDaysUnreferenced, recommend demotion following the same type rules
- Very specific: line 122
If flags.enableMemoryConsolidation is not "true", skip this step entirely.
- Very specific: line 160
If enableMemoryCompression is "true": estimate whether compressionTarget% of the combined body fits within maxConsolidatedSize
- Very specific: line 161
If compression is disabled: check whether the combined body fits within maxConsolidatedSize uncompressed
- Very specific: line 167
Before creating new consolidation groups, scan for existing multi-volume consolidated memories (files with consolidation_topic in …
- Distinctive: line 170
If new memories match an existing topic:
- Distinctive: line 172
If yes: recommend adding to the existing volume (decompress, merge content, recompress)
- Distinctive: line 173
If no: recommend creating a new volume for the topic and rebalancing content across all volumes (see 7f.
- Very specific: line 178
When a consolidation group's combined content exceeds maxConsolidatedSize:
- Distinctive: line 192
When existing multi-volume topics change (new memories added, members demoted/archived, or volumes become uneven):
- Distinctive: line 200
If rebalancing is needed:
- Very specific: line 203
Update each volume's title and description to reflect its new content
- Distinctive: line 204
If volumes were reduced (e.g.
- Very specific: line 250
When flags.enableMemoryCompression is "true", detect remaining uncompressed .memory.md files that should be compressed individually:
- Very specific: line 266
If flags.enableMemoryCompression is not "true", skip this step entirely — do not recommend compression.
- Distinctive: line 363
Create target directory if needed
- Very specific: line 367
Add promoted_from (for promotions) or demoted_from (for demotions) with the old type value
- Very specific: line 369
If a compressed version exists (.memory.crux.md alongside .memory.md, or vice versa), move that too
- Very specific: line 380
Compress the merged file: If enableMemoryCompression is "true", delegate to crux-skill-memory-compress Compress operation.
- Distinctive: line 382
Delete merged-away memories: Remove all original member memory files from the working directory
- Very specific: line 385
Keep the most recent last_referenced
- Very specific: line 387
Write the merged tracker as {new_slug}.refs.yml
- Distinctive: line 388
Delete merged-away trackers: Remove all original member tracker files
- Very specific: line 405
Compress each volume: If enableMemoryCompression is "true", delegate each to crux-skill-memory-compress (adaptive sizing against …
- Very specific: line 407
Distribute reference trackers: Create a tracker for each volume slug.
- Very specific: line 427
If the compress skill flags a file for manual review (exceeds maxMemorySize even at maximum compression), report it in the REM summary as …
- Very specific: line 431
Read the memory file's frontmatter strength
- Very specific: line 432
Write that value into the tracker file's strength field
- Distinctive: line 436
Delete orphaned tracker files confirmed for removal
- Very specific: line 440
After all changes are applied, write a summary to {archiveDir}/rem-{yyyymmdd}.md:
- Distinctive: line 492
After all changes are applied and the REM summary is written, rebuild the memory index to reflect the current state of the corpus:
- Distinctive: line 506
When a memory transitions between types, follow this exact procedure:
- Distinctive: line 514
Create target directory: if it does not exist
- Very specific: line 520
Handle compressed companion: If a .memory.crux.md exists for a .memory.md being moved (or vice versa), move the companion file to the same …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CRUX Skill: Memory Rebalance
The complete REM sleep workflow for the CRUX memory system. Analyses all memories and their reference trackers to verify consistency, detect conflicts, recommend promotions/demotions/archival/consolidation, and apply confirmed changes.
When to Use
Use this skill when:
- Running REM sleep (
/crux-dream --remor/crux-dream --rem --yolo) - Manually rebalancing memory strength scores
- Investigating potential conflicts between memories
- Cleaning up orphaned tracker files or stale memories
Prerequisites
Before any operation:
- Read config: Load
.crux/crux-memories.json. This skill needscruxMemories.typeTransitions,demoteAfterDaysUnreferenced,archiveAfterDaysUnreferenced,typePriority,sizeUnit,compressionTarget,compressionMinLines,maxMemorySize,maxConsolidatedSize,storage.*,referenceTracking.trackingDir,referenceTracking.promotionToRuleThreshold, plus theflags.enableMemories,flags.enableMemoryCompression, andflags.enableMemoryConsolidationgates. Defaults and full key descriptions live in.cursor/skills/_memory-shared.md#config-referenceand.crux/crux-memories.json(authoritative). - Guard check: If
flags.enableMemoriesis not"true", abort and inform the caller that memories are disabled. typeTransitionsvalues are read verbatim from config — do not hard-code promotion thresholds.
REM Sleep Workflow
The full REM sleep workflow executes these steps in order. Each step produces recommendations that are collected and presented together before any changes are applied.
Step 1: Load Corpus
- Recursively scan
memoriesDirandagentMemoriesDirfor all*.memory.mdand*.memory.crux.mdfiles - Parse frontmatter from each memory file (title, description, type, strength, created, modified, source, tags)
- List all
*.refs.ymlfiles intrackingDir - Parse each tracker file (slug, references, last_referenced, strength)
- Build a joined dataset: each memory paired with its tracker (if one exists)
Step 2: Consistency Verification
Check for data integrity issues:
- Orphaned trackers: For each
.refs.ymlfile, verify a matching memory file exists (by slug). If no memory matches, flag the tracker as orphaned - Stale sources: For each memory, check if its
sourcefield references a unit of work that still exists. Flag if the source directory no longer exists (advisory only — does not trigger deletion) - Broken strength chains: Compare each tracker's
strengthfield against the corresponding memory's frontmatterstrength. If they differ, flag for rebalancing - Missing trackers for strong memories: Memories with
strength > 1but no tracker file may indicate a tracking gap. Flag as advisory
Output: List of consistency issues found, categorized by severity.
Step 3: Conflict Detection
Identify memories that contradict each other:
- Compare memory titles, descriptions, and bodies pairwise for semantic contradictions:
- Opposing advice (e.g. "always use X" vs "never use X")
- Conflicting patterns (e.g. two memories recommending incompatible approaches to the same problem)
- An
ideaorlearningthat directly contradicts acorememory
- For each detected conflict, record:
- The two conflicting memories (paths, titles, types, strengths)
- A brief description of the contradiction
- Resolution options: keep A, keep B, merge, keep both with disambiguation note
Conflicts always require user input — even in --yolo mode, conflicts are never auto-resolved.
Step 4: Promote
For each memory, check if its strength (from frontmatter) meets or exceeds the promoteAt threshold for its current type:
- Look up the memory's current
typeintypeTransitions - If
promoteAtisnull, skip (terminal type) - If
strength >= promoteAt, recommend promotion topromoteTo
Recommendation format:
⬆️ Promote: "{title}"
{current_type} → {promoteTo} (strength {strength} ≥ threshold {promoteAt})
File: {current_path} → {new_path}Step 5: Demote
For each memory that has a tracker file, check temporal staleness:
- Calculate days since
last_referenced(from tracker) - If days >
demoteAfterDaysUnreferenced(default 90) and the memory is not alreadyarchived:- If memory type is
core, recommend demotion tolearning - If memory type is
learning, recommend demotion toidea - If memory type is
redflag, recommend demotion tolearning - If memory type is
idea, recommend archival instead (skip to Step 6) goaltypes are never demoted — flag for manual review instead
- If memory type is
For memories with no tracker file (never referenced):
- Calculate days since
created(from frontmatter) - If days >
demoteAfterDaysUnreferenced, recommend demotion following the same type rules
Recommendation format:
⬇️ Demote: "{title}"
{current_type} → {demoted_type} (unreferenced for {days} days, threshold: {demoteAfterDaysUnreferenced})
File: {current_path} → {new_path}Step 6: Archive
For memories that are stale beyond the archival threshold:
- Calculate days since
last_referenced(from tracker), or days sincecreatedif no tracker exists - If days >
archiveAfterDaysUnreferenced(default 180) and the memory is not alreadyarchived:- Recommend moving to the
archived/type directory
- Recommend moving to the
Recommendation format:
📦 Archive: "{title}"
{current_type} → archived (unreferenced for {days} days, threshold: {archiveAfterDaysUnreferenced})
File: {current_path} → {new_path}Step 7: Consolidate
If flags.enableMemoryConsolidation is not "true", skip this step entirely.
Group related memories by subject matter and merge each group into a single compressed memory. This reduces corpus size while preserving all unique insights.
7a. Identify Consolidation Groups
Cluster memories that cover the same domain or subject area:
- Tag overlap: Memories sharing ≥50% of their tags are candidates for the same group
- Type affinity: Memories of the same type are preferred grouping partners — group same-type memories first, only cross-type when the subject overlap is strong
- Title/description similarity: Memories whose titles or descriptions reference the same concept, pattern, technique, or domain
- Source affinity: Memories originating from the same
source(spec/session) that cover facets of the same subject - Body content: Overlapping or complementary body content (e.g. two memories about plugin architecture with different specific lessons)
A memory may only belong to one consolidation group. Groups must contain at least 2 memories. Memories with no strong affinity to others remain standalone.
7b. Build Consolidated Metadata
For each group, compose shared metadata from the member memories:
| Field | Rule |
id | New 7-character hex hash from sha256(new_title)[:7] |
title | New title that captures the shared subject across all members — concise but covering the group's scope |
description | New self-contained summary synthesising the key insights from all members — not a concatenation, but a coherent combined description |
type | Highest-priority type in the group (per typePriority) |
strength | Sum of all member strengths |
created | Earliest created date from the group |
modified | Today's date |
source | Most frequently occurring source in the group; if tied, earliest |
tags | Union of all member tag sets, deduplicated |
consolidated_from | List of original memory id values (for audit trail) |
7c. Calculate Combined Size and Split Volumes
- Combine the body content from all members into a single merged body, preserving all unique insights and removing redundant content
- Measure the combined body size in the configured
sizeUnit(default: lines) - Determine whether the output fits within
maxConsolidatedSize(default1000lines):- If
enableMemoryCompressionis"true": estimate whethercompressionTarget% of the combined body fits withinmaxConsolidatedSize - If compression is disabled: check whether the combined body fits within
maxConsolidatedSizeuncompressed
- If
- If within limit: the group produces a single consolidated file
- If exceeds limit: split into multiple volumes (see 7e. Volume Splitting)
7d. Detect Existing Consolidated Topics
Before creating new consolidation groups, scan for existing multi-volume consolidated memories (files with consolidation_topic in frontmatter):
- For each existing consolidated topic, check whether any new ungrouped memories belong to it (using the same affinity criteria from 7a)
- If new memories match an existing topic:
- Estimate whether adding them to an existing volume would keep that volume under
maxConsolidatedSize - If yes: recommend adding to the existing volume (decompress, merge content, recompress)
- If no: recommend creating a new volume for the topic and rebalancing content across all volumes (see 7f. Volume Rebalancing)
- Estimate whether adding them to an existing volume would keep that volume under
- Track the
consolidation_topicslug and next availableconsolidation_partnumber
7e. Volume Splitting
When a consolidation group's combined content exceeds maxConsolidatedSize:
- Assign a
consolidation_topicslug derived from the group's shared subject (e.g.plugin-architecture) - Partition the merged body into coherent sub-topics — each sub-topic becomes a volume. Split by semantic boundaries, not arbitrary byte offsets:
- Group related insights, patterns, and examples together
- Each volume should be independently understandable
- Aim for roughly equal volume sizes, each within
maxConsolidatedSize
- Number volumes sequentially:
consolidation_part: 1,consolidation_part: 2, etc. - Each volume gets its own
id(hash from"{topic} part {n}") but shares the sameconsolidation_topic,type,tags, andconsolidated_from(full list of all source IDs across the topic) - Each volume gets its own
titleanddescriptionreflecting its specific sub-topic content - File naming:
{topic}-pt{n}.memory.crux.md(e.g.plugin-architecture-pt1.memory.crux.md)
7f. Volume Rebalancing
When existing multi-volume topics change (new memories added, members demoted/archived, or volumes become uneven):
- Load all volumes for the topic (by
consolidation_topicmatch) - Decompress all volumes to get the full combined content
- Assess whether rebalancing is needed:
- A volume exceeds
maxConsolidatedSize - A volume is less than 25% of
maxConsolidatedSize(under-filled) - Volumes could be reduced (total content now fits in fewer volumes)
- A volume exceeds
- If rebalancing is needed:
- Re-partition all content across the optimal number of volumes, each within
maxConsolidatedSize - Reassign
consolidation_partnumbers sequentially - Update each volume's
titleanddescriptionto reflect its new content - If volumes were reduced (e.g. 3 → 2), delete the surplus volume files and their trackers
- Re-partition all content across the optimal number of volumes, each within
- Present rebalancing as a recommendation alongside new consolidations
Recommendation format for rebalancing:
🔀 Rebalance topic "{consolidation_topic}": {old_count} → {new_count} volumes
Reason: {volume exceeds cap | under-filled volume | reducible}
Volumes: {list of volume paths with current and projected sizes}7g. Present Recommendations
For each consolidation group, present the proposed merge:
Single-volume group:
🔀 Consolidate ({n} memories): "{new_title}"
Members:
- {path_a} "{title_a}" ({type_a}, strength {strength_a})
- {path_b} "{title_b}" ({type_b}, strength {strength_b})
- {path_c} "{title_c}" ({type_c}, strength {strength_c})
Combined strength: {sum}
Combined size: {total_lines} lines → est. {compressed_lines} lines compressed
Tags: {union_of_tags}
Output: {target_dir}/{new_slug}.memory.crux.mdMulti-volume group (exceeds maxConsolidatedSize):
🔀 Consolidate ({n} memories) into {v} volumes: topic "{consolidation_topic}"
Members:
- {path_a} "{title_a}" ({type_a}, strength {strength_a})
- {path_b} "{title_b}" ({type_b}, strength {strength_b})
- ...
Combined strength: {sum}
Tags: {union_of_tags}
Volume 1: "{vol1_title}" — est. {vol1_lines} lines compressed
Volume 2: "{vol2_title}" — est. {vol2_lines} lines compressed
Output: {target_dir}/{topic}-pt1.memory.crux.md, ...Step 8: Compress Uncompressed Memories
When flags.enableMemoryCompression is "true", detect remaining uncompressed .memory.md files that should be compressed individually:
- From the corpus loaded in Step 1, identify all
.memory.mdfiles that do not have a corresponding.memory.crux.mdcompanion - Exclude memories that are part of a consolidation group from Step 7 — those are already compressed as part of the merge
- Skip files below
compressionMinLines(default500lines) — these are too small to benefit from compression - For remaining files, estimate whether they exceed
maxMemorySize(in the configuredsizeUnit) or would benefit from compression to meetcompressionTarget - Recommend compression only for files that meet the minimum size threshold
Recommendation format:
🗜️ Compress: "{title}"
File: {path} ({size} lines)
Target: {compressionTarget}% of body, max {maxMemorySize} linesIf flags.enableMemoryCompression is not "true", skip this step entirely — do not recommend compression.
Apply: Delegate each confirmed compression to crux-skill-memory-compress Compress operation. The compress skill handles archival of the original, adaptive sizing, and writing the .memory.crux.md output.
Step 9: Rebalance Strength
Sync strength scores between memory frontmatter and tracker files:
- For each memory with a tracker, compare frontmatter
strengthwith trackerstrength - The memory frontmatter is authoritative — if they differ, update the tracker
- Report any corrections made
Step 10: Promote to Rule
Flag memories that exceed the promotionToRuleThreshold for potential conversion to a permanent rule:
- For each tracker where
references >= promotionToRuleThreshold(default 30):- Flag the corresponding memory for rule promotion
Recommendation format:
⚡ Promote to rule: "{title}"
Referenced {references} times (threshold: {promotionToRuleThreshold})
Consider creating a permanent rule in .cursor/rules/This is advisory — the user decides whether to create the rule. This skill does not automatically create rules.
Step 11: Cleanup
Identify orphaned tracker files (from Step 2) and recommend deletion:
🧹 Cleanup: {slug}.refs.yml
No matching memory file found — recommend deletionStep 12: Present Recommendations
Collect all recommendations from steps 2–11 and present them to the user in a structured report:
=== REM Sleep Analysis ===
📋 Consistency Issues: {count}
{list of issues from Step 2}
⚠️ Conflicts: {count} (require manual resolution)
{list of conflicts from Step 3}
⬆️ Promotions: {count}
{list from Step 4}
⬇️ Demotions: {count}
{list from Step 5}
📦 Archival: {count}
{list from Step 6}
🔀 Consolidations: {count} groups ({total_merged} memories)
{list from Step 7g}
📚 Volume Rebalances: {count} topics
{list from Step 7f}
🗜️ Compressions: {count}
{list from Step 8}
🔄 Strength Rebalances: {count}
{list from Step 9}
⚡ Rule Promotion Candidates: {count}
{list from Step 10}
🧹 Cleanup: {count}
{list from Step 11}
Apply all recommendations? [all/select/skip]In --yolo mode: Auto-apply everything EXCEPT conflicts (Step 3). Conflicts always require user input.
In interactive mode: Return the full report in your response. Do NOT call AskQuestion — the calling agent (or its parent) will present the report to the user and collect the confirmation decision, then pass it back to you. Expected options for the user:
- all: Apply all non-conflict recommendations; then prompt for each conflict individually
- select: Walk through each recommendation individually for accept/reject
- skip: Abort without changes
Step 13: Apply Changes
Execute confirmed changes. For each approved recommendation:
Moving Files (Promote, Demote, Archive)
- Determine the new target directory based on scope and new type:
- Base memory:
{memoriesDir}/{new_type}/ - Agent-scoped memory:
{agentMemoriesDir}/{agent-id}/{new_type}/
- Base memory:
- Create target directory if needed
- Move the memory file to the new directory
- Update frontmatter:
- Set
typeto the new type - Add
promoted_from(for promotions) ordemoted_from(for demotions) with the old type value - Set
modifiedto today's date
- Set
- If a compressed version exists (
.memory.crux.mdalongside.memory.md, or vice versa), move that too - The reference tracker file stays in
trackingDir— trackers reference by slug, not path, so no tracker update is needed for file moves
Merging (Consolidate) — Single Volume
For each confirmed consolidation group that fits within maxConsolidatedSize:
- Read all member memories in the group (both
.memory.mdand.memory.crux.md— decompress any compressed members first) - Compose merged body: Synthesise a single body from all members. Preserve all unique insights, patterns, and examples. Remove redundant or overlapping content. Organise logically (not as a concatenation)
- Build consolidated frontmatter per Step 7b rules — new
id, sharedtitle, synthesiseddescription, uniontags, summedstrength, earliestcreated,consolidated_fromlisting all originalidvalues - Write the merged file as
{new_slug}.memory.mdusingcrux-skill-memory-crudCreate operation, placed in{memoriesDir}/{type}/(using the highest-priority type from the group) - Compress the merged file: If
enableMemoryCompressionis"true", delegate tocrux-skill-memory-compressCompress operation. The compress skill handles adaptive sizing againstmaxConsolidatedSize, source archival of the merged uncompressed file, and writing the final.memory.crux.mdoutput - Archive source memories: Copy each original member memory file to
{compressionSourceArchive}/{yyyymmdd}/before deletion - Delete merged-away memories: Remove all original member memory files from the working directory
- Merge reference trackers: For all members that have tracker files, merge into a single tracker for the new memory slug:
- Sum
referencesacross all member trackers - Keep the most recent
last_referenced - Combine
recent_referenceslists and re-cap tomaxReferencesStored - Write the merged tracker as
{new_slug}.refs.yml
- Sum
- Delete merged-away trackers: Remove all original member tracker files
Merging (Consolidate) — Multi-Volume
For each confirmed consolidation group that exceeds maxConsolidatedSize:
- Read all member memories in the group (decompress any compressed members)
- Partition content into volumes per Step 7e — split by semantic boundaries, each volume independently understandable, each within
maxConsolidatedSize - For each volume, build frontmatter:
id: hash from"{consolidation_topic} part {n}"titleanddescription: specific to that volume's sub-topic contenttype,tags,strength: shared across volumes (strength divided proportionally by content size, minimum 1 per volume)created: earliestcreatedfrom the full groupconsolidated_from: full list of all sourceidvalues (shared across all volumes)consolidation_topic: shared slug for the topicconsolidation_part: volume number (1-indexed)
- Write each volume as
{topic}-pt{n}.memory.mdin{memoriesDir}/{type}/ - Compress each volume: If
enableMemoryCompressionis"true", delegate each tocrux-skill-memory-compress(adaptive sizing againstmaxConsolidatedSize) - Archive and delete source memories (same as single-volume steps 6–7)
- Distribute reference trackers: Create a tracker for each volume slug. Distribute reference counts proportionally by content size across volumes (minimum 1 reference per volume if source total > 0). Each tracker gets the same
last_referenceddate. - Delete merged-away trackers
Volume Rebalancing
For each confirmed volume rebalance recommendation (from Step 7f):
- Load all volumes for the topic (by
consolidation_topicfrontmatter match) - Decompress all volumes to get full combined content
- If adding new memories: merge new memory content into the combined body
- Re-partition the combined content into the target number of volumes, each within
maxConsolidatedSize, split at semantic boundaries - Update existing volume files in-place where possible; create new volumes or delete surplus volumes as needed
- Recompress each updated volume via
crux-skill-memory-compress - Update trackers: redistribute reference counts proportionally across the new volume set
- Archive and delete any source memories that were merged in, and any surplus volume files
Compression
- Delegate to
crux-skill-memory-compressCompress operation, passing the.memory.mdfile path - The compress skill handles source archival, adaptive sizing against
maxMemorySize(in the configuredsizeUnit), and writing the.memory.crux.mdoutput - If the compress skill flags a file for manual review (exceeds
maxMemorySizeeven at maximum compression), report it in the REM summary as skipped
Strength Rebalance
- Read the memory file's frontmatter
strength - Write that value into the tracker file's
strengthfield
Cleanup
- Delete orphaned tracker files confirmed for removal
Step 14: Write REM Summary
After all changes are applied, write a summary to {archiveDir}/rem-{yyyymmdd}.md:
# REM Sleep Summary — {YYYY-MM-DD}
## Changes Applied
### Promotions ({count})
- "{title}": {old_type} → {new_type}
### Demotions ({count})
- "{title}": {old_type} → {new_type}
### Archived ({count})
- "{title}": {old_type} → archived
### Consolidated ({count} groups, {total_merged} memories merged)
- "{new_title}" ← {n} memories ({combined_size} → {compressed_size} lines)
- {id_a} "{title_a}", {id_b} "{title_b}", ...
### Volume Rebalanced ({count} topics)
- topic "{consolidation_topic}": {old_volumes} → {new_volumes} volumes ({reason})
### Compressed ({count})
- "{title}": {original_size} → {compressed_size} lines ({reduced_by}% reduction)
### Strength Rebalanced ({count})
- "{title}": tracker strength {old} → {new}
### Conflicts Resolved ({count})
- "{title_a}" vs "{title_b}": {resolution}
### Cleaned Up ({count})
- {slug}.refs.yml (orphaned)
### Rule Promotion Candidates ({count})
- "{title}" ({references} references)
## Skipped
- {list of recommendations user declined}
## Corpus Summary
- Total memories: {count} ({standalone_count} standalone, {consolidated_count} consolidated across {topic_count} topics)
- By type: core={n}, redflag={n}, goal={n}, learning={n}, idea={n}, archived={n}
- Compressed: {count} | Uncompressed: {count}
- Multi-volume topics: {count} (total volumes: {count})
- Tracked (with .refs.yml): {count}
- Untracked: {count}Step 15: Rebuild Index
After all changes are applied and the REM summary is written, rebuild the memory index to reflect the current state of the corpus:
python .cursor/skills/crux/crux-skill-memory-index/scripts/memory-index.pyThis is mandatory — skipping this step leaves the index stale, which causes downstream agents (Recall, Dream, session-start hooks) to reference moved, deleted, or renamed files. If the script fails, report the error but do not abort — the REM summary and applied changes are still valid.
Step 16: Report
Present a concise summary of what changed to the user, including confirmation that the memory index was rebuilt (or an error if it failed).
File Move Procedure (Detailed)
When a memory transitions between types, follow this exact procedure:
- Resolve scope: Determine if the memory is base-scoped or agent-scoped by examining its current path
- Path starts with
{agentMemoriesDir}→ agent-scoped; extract{agent-id}from path - Otherwise → base-scoped
- Path starts with
- Build target path:
- Base:
{memoriesDir}/{new_type}/{slug}.memory.md(or.memory.crux.md) - Agent:
{agentMemoriesDir}/{agent-id}/{new_type}/{slug}.memory.md(or.memory.crux.md)
- Base:
- Create target directory if it does not exist
- Move the file to the target path
- Update frontmatter in-place after the move:
type→ new type valuepromoted_fromordemoted_from→ old type valuemodified→ today's date (YYYY-MM-DD)
- Handle compressed companion: If a
.memory.crux.mdexists for a.memory.mdbeing moved (or vice versa), move the companion file to the same target directory and update its frontmatter identically - No tracker update needed: Tracker files in
trackingDirreference memories byslug, not by path. Moving a memory file does not break the tracker association
Error Handling
| Condition | Action |
enableMemories is not "true" | Abort, inform caller memories are disabled |
| Config file missing or malformed | Report error with path and expected structure |
| Memory file cannot be read or parsed | Skip that memory, report in consistency issues |
| Target directory cannot be created | Abort the specific move, report filesystem error |
| Conflict between two memories | Always present to user, never auto-resolve |
Strength exceeds promoteAt but promoteTo is not in typePriority | Skip promotion, report config issue |
| File move would overwrite an existing file | Return needs_user_input for the calling agent to confirm with the user |
Out-of-scope and cross-skill delegation: see
.cursor/skills/_memory-shared.md#cross-skill-boundariesand the agent table inAGENTS.md.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

