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.
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-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-rebalanceSkill
- 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
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
- Distinctive: line 12
Use this skill whenever you need to:
- Distinctive: line 13
Create a new memory file from an extracted insight
- Distinctive: line 14
Read and parse an existing memory's frontmatter and body
- Distinctive: line 15
Update a memory's metadata or content (e.g.
- Distinctive: line 16
Delete a memory and its reference tracker
- Distinctive: line 23
Every memory file must have YAML frontmatter with these fields:
- Distinctive: line 88
Create a new memory file.
- Very specific: line 104
Check file size against maxMemorySize (default 1000 lines).
- Very specific: line 106
If agent-id provided: memories/agents/{agent-id}/{type}/
- Distinctive: line 108
Create parent directories if needed
- Very specific: line 109
Write {slug}.memory.md to the target directory
- Very specific: line 120
If given a slug, resolve to a file path by searching memories/ recursively for {slug}.memory.md or {slug}.memory.crux.md
- Distinctive: line 134
Read the existing memory (use the Read operation)
- Very specific: line 141
If type has changed: a. Set promoted_from to the old type value b.
- Distinctive: line 146
If body content is provided, replace the body
- Very specific: line 148
Check file size against maxMemorySize.
- Distinctive: line 153
Remove a memory file and its reference tracker.
- Distinctive: line 161
Delete the memory file
- Very specific: line 162
Check for a corresponding reference tracker at {trackingDir}/{slug}.refs.yml (where trackingDir comes from config, default …
- Distinctive: line 163
If the tracker file exists, delete it
- Distinctive: line 168
Check a memory file against the required schema.
- Distinctive: line 174
Read the memory file (use the Read operation)
- Distinctive: line 175
Check all required frontmatter fields are present:
- Very specific: line 184
Check file size against maxMemorySize
- Very specific: line 185
Check that the file is in the correct type subdirectory for its type field
- Very specific: line 190
Do not modify id or created on updates — both are immutable after creation
- Very specific: line 191
Do not set strength to anything other than 1 on new memories
- Very specific: line 192
Do not write memory files outside the memories/ directory tree
- Distinctive: line 193
Do not delete reference trackers without also deleting the memory
- Very specific: line 194
Do not silently exceed maxMemorySize — always warn the user
- Very specific: line 195
Do not create memories when the feature flag enableMemories is false in config without notifying the user
≈ “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 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-referenceand.crux/crux-memories.json(authoritative).
Memory Frontmatter Schema
Every memory file must have YAML frontmatter with these fields:
Required Fields
| Field | Type | Rules |
id | string | 7-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. |
title | string | Descriptive title conveying the key insight |
description | string | Self-contained summary — enough to act on without reading the body |
type | enum | One of: core, redflag, goal, learning, idea, archived |
strength | integer | Starts at 1 for new memories; incremented on reinforcement |
created | date | ISO date (YYYY-MM-DD); set once at creation, never modified |
modified | date | ISO date (YYYY-MM-DD); updated on every write |
source | string | Slug of the originating spec or session (e.g. 20260403-component-library) |
tags | list | Array of lowercase tag strings for categorization |
Optional Fields
| Field | Type | Rules |
promoted_from | string | Previous type before a type transition; set automatically on promotion/demotion |
consolidated_from | list | List of original memory id values when this memory was created by merging multiple memories during REM sleep consolidation. Set once, never modified. |
consolidation_topic | string | Shared 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_part | integer | Volume 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
| Scope | Path |
| Base memory | memories/{type}/{slug}.memory.md |
| Agent-scoped memory | memories/agents/{agent-id}/{type}/{slug}.memory.md |
Examples:
memories/learning/validate-checksums-before-overwrite.memory.mdmemories/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:
- Load config from
.crux/crux-memories.json - Validate
typeis one of the allowed types intypePriority - Generate slug from title (lowercase, replace spaces/special chars with hyphens, truncate to reasonable length)
- Generate
idby computingsha256(title)and taking the first 7 hex characters. If a collision exists with another memory, extend to 8 characters. - Build frontmatter with all required fields:
id: the generated hashstrength:1created: today's datemodified: today's date
- Compose the full file: frontmatter + body content
- Check file size against
maxMemorySize(default 1000 lines). If exceeded, warn the user and suggest trimming the body or compressing - Determine target directory:
- If agent-id provided:
memories/agents/{agent-id}/{type}/ - Otherwise:
memories/{type}/
- If agent-id provided:
- Create parent directories if needed
- Write
{slug}.memory.mdto the target directory - 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:
- If given a slug, resolve to a file path by searching
memories/recursively for{slug}.memory.mdor{slug}.memory.crux.md - Read the file
- Split on the frontmatter delimiters (
---) - Parse the YAML frontmatter into structured fields
- 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:
- Read the existing memory (use the Read operation)
- Apply field updates to the frontmatter. Enforce these rules:
id— never modify this field; it is immutable after creationcreated— never modify this field; reject any attempt to change itmodified— always set to today's datetype— if changed, handle type transition (see below)strength— accept new value; no automatic changes here
- If
typehas changed: a. Setpromoted_fromto 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 - If body content is provided, replace the body
- Recompose and write the updated file
- Check file size against
maxMemorySize; warn if exceeded - Return the (possibly new) file path
Delete
Remove a memory file and its reference tracker.
Inputs: file path or slug.
Procedure:
- Resolve the file path (if given a slug, use the Read resolution logic)
- Extract the slug from the filename (strip
.memory.mdor.memory.crux.md) - Delete the memory file
- Check for a corresponding reference tracker at
{trackingDir}/{slug}.refs.yml(wheretrackingDircomes from config, default.crux/reference-tracking/) - If the tracker file exists, delete it
- Return confirmation of what was deleted
Validate
Check a memory file against the required schema.
Inputs: file path or slug.
Procedure:
- Read the memory file (use the Read operation)
- Check all required frontmatter fields are present:
id,title,description,type,strength,created,modified,source,tags
- Check field types:
idmust be a 7-character (or 8 on collision) lowercase hex stringtypemust be one of:core,redflag,goal,learning,idea,archivedstrengthmust be a positive integercreatedandmodifiedmust be valid ISO datestagsmust be a listtitleanddescriptionmust be non-empty strings
- Check file size against
maxMemorySize - Check that the file is in the correct type subdirectory for its
typefield - Report all errors and warnings found. Return a pass/fail result with details
What NOT to Do
- Do not modify
idorcreatedon updates — both are immutable after creation - Do not set
strengthto anything other than1on 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
enableMemoriesisfalsein config without notifying 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.

