agentleFS
zotoiozotoio/CRUX-Compress/.cursor/skills/crux-skill-memory-crud/SKILL.md

crux-skill-memory-crud

Skill8 starsChanged 2 months agoMITView on GitHub

Create, read, update, delete, and validate memory files with proper frontmatter management. Use when creating new memories, modifying existing ones, removing memories, or validating memory file structure.

The file

Show its rules and text

We split this skill into the rules it gives an agent

31 rules. About 0 are common, 17 are distinctive, and 14 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈17

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 14

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill whenever you need to:

    line 12
  2. Distinctive:

    Create a new memory file from an extracted insight

    line 13
  3. Distinctive:

    Read and parse an existing memory's frontmatter and body

    line 14
  4. Distinctive:

    Update a memory's metadata or content (e.g.

    line 15
  5. Distinctive:

    Delete a memory and its reference tracker

    line 16
  6. Distinctive:

    Every memory file must have YAML frontmatter with these fields:

    line 23
  7. Distinctive:

    Create a new memory file.

    line 88
  8. Very specific:

    Check file size against maxMemorySize (default 1000 lines).

    line 104
  9. Very specific:

    If agent-id provided: memories/agents/{agent-id}/{type}/

    line 106
  10. Distinctive:

    Create parent directories if needed

    line 108
  11. Very specific:

    Write {slug}.memory.md to the target directory

    line 109
  12. Very specific:

    If given a slug, resolve to a file path by searching memories/ recursively for {slug}.memory.md or {slug}.memory.crux.md

    line 120
  13. Distinctive:

    Read the existing memory (use the Read operation)

    line 134
  14. Very specific:

    If type has changed: a. Set promoted_from to the old type value b.

    line 141
  15. Distinctive:

    If body content is provided, replace the body

    line 146
  16. Very specific:

    Check file size against maxMemorySize.

    line 148
  17. Distinctive:

    Remove a memory file and its reference tracker.

    line 153
  18. Distinctive:

    Delete the memory file

    line 161
  19. Very specific:

    Check for a corresponding reference tracker at {trackingDir}/{slug}.refs.yml (where trackingDir comes from config, default …

    line 162
  20. Distinctive:

    If the tracker file exists, delete it

    line 163
  21. Distinctive:

    Check a memory file against the required schema.

    line 168
  22. Distinctive:

    Read the memory file (use the Read operation)

    line 174
  23. Distinctive:

    Check all required frontmatter fields are present:

    line 175
  24. Very specific:

    Check file size against maxMemorySize

    line 184
  25. Very specific:

    Check that the file is in the correct type subdirectory for its type field

    line 185
  26. Very specific:

    Do not modify id or created on updates — both are immutable after creation

    line 190
  27. Very specific:

    Do not set strength to anything other than 1 on new memories

    line 191
  28. Very specific:

    Do not write memory files outside the memories/ directory tree

    line 192
  29. Distinctive:

    Do not delete reference trackers without also deleting the memory

    line 193
  30. Very specific:

    Do not silently exceed maxMemorySize — always warn the user

    line 194
  31. Very specific:

    Do not create memories when the feature flag enableMemories is false in config without notifying the user

    line 195

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

CRUX Memory CRUD

Provides create, read, update, delete, and validate operations for CRUX memory files stored under memories/.

When to Use

Use this skill whenever you need to:

  • Create a new memory file from an extracted insight
  • Read and parse an existing memory's frontmatter and body
  • Update a memory's metadata or content (e.g. type promotion, strength change)
  • Delete a memory and its reference tracker
  • Validate a memory file against the required schema

Config keys and defaults: see .cursor/skills/_memory-shared.md#config-reference and .crux/crux-memories.json (authoritative).

Memory Frontmatter Schema

Every memory file must have YAML frontmatter with these fields:

Required Fields

FieldTypeRules
idstring7-character hex hash, generated once at creation from sha256(title)[:7]. Immutable — never changes even if the title is edited. Used as the stable short identifier for display and selection.
titlestringDescriptive title conveying the key insight
descriptionstringSelf-contained summary — enough to act on without reading the body
typeenumOne of: core, redflag, goal, learning, idea, archived
strengthintegerStarts at 1 for new memories; incremented on reinforcement
createddateISO date (YYYY-MM-DD); set once at creation, never modified
modifieddateISO date (YYYY-MM-DD); updated on every write
sourcestringSlug of the originating spec or session (e.g. 20260403-component-library)
tagslistArray of lowercase tag strings for categorization

Optional Fields

FieldTypeRules
promoted_fromstringPrevious type before a type transition; set automatically on promotion/demotion
consolidated_fromlistList of original memory id values when this memory was created by merging multiple memories during REM sleep consolidation. Set once, never modified.
consolidation_topicstringShared slug identifying the topic across multi-volume consolidated memories (e.g. plugin-architecture). All volumes for the same topic share this value. Set during consolidation when splitting is needed.
consolidation_partintegerVolume number within a multi-volume consolidated topic (1-indexed). Only present when consolidation_topic is set and the topic spans multiple files.

Example Frontmatter

---
id: "a1b2c3d"
title: "Always validate CRUX checksums before overwriting"
description: "Source files can drift from their CRUX output. Always recompute and compare sourceChecksum before regenerating to avoid silent data loss."
type: "learning"
strength: 1
created: 2026-04-03
modified: 2026-04-03
source: "20260403-crux-memories"
tags: [crux, validation, checksums]
---

File Naming and Placement

File Names

  • Uncompressed: {slug}.memory.md
  • Compressed: {slug}.memory.crux.md

Slugs are lowercase, hyphen-separated, descriptive (e.g. validate-checksums-before-overwrite).

Directory Placement

ScopePath
Base memorymemories/{type}/{slug}.memory.md
Agent-scoped memorymemories/agents/{agent-id}/{type}/{slug}.memory.md

Examples:

  • memories/learning/validate-checksums-before-overwrite.memory.md
  • memories/agents/crux-cursor-rule-manager/core/compression-ratio-thresholds.memory.md

Operations

Create

Create a new memory file.

Inputs: title, description, type, source, tags, body content, and optionally agent-id for scoping.

Procedure:

  1. Load config from .crux/crux-memories.json
  2. Validate type is one of the allowed types in typePriority
  3. Generate slug from title (lowercase, replace spaces/special chars with hyphens, truncate to reasonable length)
  4. Generate id by computing sha256(title) and taking the first 7 hex characters. If a collision exists with another memory, extend to 8 characters.
  5. Build frontmatter with all required fields:
    • id: the generated hash
    • strength: 1
    • created: today's date
    • modified: today's date
  6. Compose the full file: frontmatter + body content
  7. Check file size against maxMemorySize (default 1000 lines). If exceeded, warn the user and suggest trimming the body or compressing
  8. Determine target directory:
    • If agent-id provided: memories/agents/{agent-id}/{type}/
    • Otherwise: memories/{type}/
  9. Create parent directories if needed
  10. Write {slug}.memory.md to the target directory
  11. Return the file path and id

Read

Load and parse an existing memory file.

Inputs: file path or slug (with optional type/scope hints for slug resolution).

Procedure:

  1. If given a slug, resolve to a file path by searching memories/ recursively for {slug}.memory.md or {slug}.memory.crux.md
  2. Read the file
  3. Split on the frontmatter delimiters (---)
  4. Parse the YAML frontmatter into structured fields
  5. Return frontmatter fields and body content separately

Update

Modify a memory's frontmatter or body.

Inputs: file path or slug, fields to update, and optionally new body content.

Procedure:

  1. Read the existing memory (use the Read operation)
  2. Apply field updates to the frontmatter. Enforce these rules:
    • id — never modify this field; it is immutable after creation
    • created — never modify this field; reject any attempt to change it
    • modified — always set to today's date
    • type — if changed, handle type transition (see below)
    • strength — accept new value; no automatic changes here
  3. If type has changed: a. Set promoted_from to the old type value b. Determine new target directory based on scope and new type c. Create new target directory if needed d. Move the file from old location to new location
  4. If body content is provided, replace the body
  5. Recompose and write the updated file
  6. Check file size against maxMemorySize; warn if exceeded
  7. Return the (possibly new) file path

Delete

Remove a memory file and its reference tracker.

Inputs: file path or slug.

Procedure:

  1. Resolve the file path (if given a slug, use the Read resolution logic)
  2. Extract the slug from the filename (strip .memory.md or .memory.crux.md)
  3. Delete the memory file
  4. Check for a corresponding reference tracker at {trackingDir}/{slug}.refs.yml (where trackingDir comes from config, default .crux/reference-tracking/)
  5. If the tracker file exists, delete it
  6. Return confirmation of what was deleted

Validate

Check a memory file against the required schema.

Inputs: file path or slug.

Procedure:

  1. Read the memory file (use the Read operation)
  2. Check all required frontmatter fields are present:
    • id, title, description, type, strength, created, modified, source, tags
  3. Check field types:
    • id must be a 7-character (or 8 on collision) lowercase hex string
    • type must be one of: core, redflag, goal, learning, idea, archived
    • strength must be a positive integer
    • created and modified must be valid ISO dates
    • tags must be a list
    • title and description must be non-empty strings
  4. Check file size against maxMemorySize
  5. Check that the file is in the correct type subdirectory for its type field
  6. Report all errors and warnings found. Return a pass/fail result with details

What NOT to Do

  • Do not modify id or created on updates — both are immutable after creation
  • Do not set strength to anything other than 1 on new memories
  • Do not write memory files outside the memories/ directory tree
  • Do not delete reference trackers without also deleting the memory
  • Do not silently exceed maxMemorySize — always warn the user
  • Do not create memories when the feature flag enableMemories is false in config without notifying the user

Out-of-scope and cross-skill delegation: see .cursor/skills/_memory-shared.md#cross-skill-boundaries and the agent table in AGENTS.md.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.