---
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

```bash
# Rebuild the index (uses default config path)
python <plugin>/skills/crux-skill-memory-index/scripts/memory-index.py

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

# Post-dream rebuild (checks enableMemories flag, then rebuilds)
python <plugin>/skills/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 `<plugin>/hooks/hooks.json`.

## Configuration

Reads `.crux/crux-memories.json` — uses `cruxMemories.storage.memoriesDir` / `agentMemoriesDir` / `indexFile`, `cruxMemories.referenceTracking.trackingDir`, and `cruxMemories.typePriority`.

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

## 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

```yaml
# 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
```

## 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

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