crux-skill-memory-index

name	crux-skill-memory-index
description	Build a prioritised memory index from all memory files and reference trackers. Use when rebuilding the memory index, after memory CRUD operations, or when agents need a sorted discovery list.

CRUX Skill: Memory Index

Builds a prioritised index of all memory files by scanning the configured memory directories, joining with reference tracker data, and writing a sorted index to .crux/memory-index.yml.

When to Use

• After creating, updating, or deleting memories (post-CRUD housekeeping)
• During REM sleep / dream cycles to refresh the index
• When an agent needs to discover available memories sorted by priority
• After bulk operations that may have changed multiple memory files

Quick Start

# Rebuild the index (uses default config path)
python .cursor/skills/crux/crux-skill-memory-index/scripts/memory-index.py

# Rebuild with a custom config path
python .cursor/skills/crux/crux-skill-memory-index/scripts/memory-index.py --config path/to/config.json

# Post-dream rebuild (checks enableMemories flag, then rebuilds)
python .cursor/skills/crux/crux-skill-memory-index/scripts/post-dream.py

Post-Dream Rebuild

The post-dream.py script is a convenience wrapper invoked programmatically by the /crux-dream workflow after memory extraction or REM sleep completes. It:

1. Checks .crux/crux-memories.json — exits early if enableMemories is not "true"
2. Calls memory-index.py to rebuild the index
3. The MCP server's file watcher detects the index timestamp change automatically

This script is not a Cursor event hook and is not registered in .cursor/hooks.json.

Configuration

All settings are read from .crux/crux-memories.json under the cruxMemories key:

Setting	Default	Purpose
storage.memoriesDir	memories	Root directory for base memories
storage.agentMemoriesDir	memories/agents	Root for agent-scoped memories
storage.indexFile	.crux/memory-index.yml	Output index file path
referenceTracking.trackingDir	.crux/reference-tracking	Directory containing .refs.yml files
typePriority	[core, redflag, goal, learning, idea, archived]	Sort order for memory types

Index File Format

The generated .crux/memory-index.yml contains a flat list under the memories key, sorted by:

1. Type priority — types earlier in typePriority rank higher
2. Strength descending — within a type, stronger memories first
3. References descending — ties broken by reference count

Each entry has:

Field	Type	Description
id	string	7-char hex hash from frontmatter (omitted if memory predates the id field)
slug	string	Memory slug derived from filename
title	string	Title from frontmatter
description	string	Description from frontmatter
type	string	Memory type from frontmatter
strength	integer	Strength from frontmatter
references	integer	Total reference count from tracker (0 if no tracker)
tags	list	Tags from frontmatter
file	string	Relative path to the memory file

Example Output

# Generated by crux-skill-memory-index — do not edit manually
# Last rebuilt: 2026-04-03T14:22:00Z

memories:
  - id: "b3f1a2c"
    slug: react-memo-list-rendering
    title: "React.memo on list item components prevents full re-render"
    description: "Wrapping list item components in React.memo..."
    type: "core"
    strength: 3
    references: 12
    tags: [react, performance, rendering]
    file: memories/core/react-memo-list-rendering.memory.crux.md
  - id: "a1b2c3d"
    slug: validate-checksums-before-overwrite
    title: "Always validate CRUX checksums before overwriting"
    description: "Source files can drift from their CRUX output..."
    type: "learning"
    strength: 1
    references: 0
    tags: [crux, validation, checksums]
    file: memories/learning/validate-checksums-before-overwrite.memory.md

How Agents Use the Index

1. Read .crux/memory-index.yml to get a prioritised list of all memories
2. Filter by type, tags, or keyword in title/description to find relevant memories
3. Load the full memory file via the file path when deeper context is needed
4. The index is pre-sorted — top entries are the highest priority memories

Error Handling

• Missing config: exits with code 1 and prints an error to stderr
• Corrupt/missing frontmatter: skips the file with a warning to stderr
• Missing tracker file: sets references to 0 for that memory
• Empty memories directory: produces a valid index with an empty memories list

Prerequisites

• Python >= 3.10
• pyyaml package installed
• .crux/crux-memories.json must exist with valid config

What This Skill Does NOT Do

• Does not create or modify memory files (that is crux-skill-memory-crud)
• Does not update reference trackers (that is crux-skill-memory-reference-tracker)
• Does not promote or demote memories between types
• Does not compress memories (that is crux-skill-memory-compress)