cortex-debug-memory

Debug Memory — Fix, Rate, Protect, and Restore

Keywords

debug, fix, bad memory, wrong, delete, forget, protect, rate, quality, restore, checkpoint, undo, stale, incorrect, mark useful, mark not useful, anchor, unprotect

Overview

Tools for maintaining memory quality — rate memories as useful or not, protect critical ones from decay, forget incorrect ones, validate against the filesystem, and restore from checkpoints when things go wrong.

Use this skill when: Recall returns wrong results, memories are stale, you need to undo changes, or you want to improve retrieval quality through feedback.

Workflow

Fix Bad Memories

Soft delete (sets heat to 0, memory still exists but won't surface):

cortex:forget({
  "memory_id": <id>,
  "hard": false
})

Hard delete (permanent removal):

cortex:forget({
  "memory_id": <id>,
  "hard": true
})

Protected memories require "force": true to delete.

Rate Memory Quality

Provide feedback to train the metamemory confidence model:

cortex:rate_memory({
  "memory_id": <id>,
  "useful": true
})

Or mark as not useful:

cortex:rate_memory({
  "memory_id": <id>,
  "useful": false,
  "reason": "outdated — we no longer use this approach"
})

Ratings adjust the memory's confidence score, which affects future retrieval ranking. Over time, this trains the system to surface better results.

Protect Critical Memories

Anchor a memory (heat=1.0 permanently, injected at session start):

cortex:anchor({
  "memory_id": <id>,
  "reason": "Core architecture decision — never decay"
})

Validate Against Reality

Check if memories reference things that still exist:

cortex:validate_memory({
  "directory": "<project root>"
})

Returns a list of stale memories (referencing deleted files, moved modules, etc.) that should be forgotten or updated.

Checkpoint and Restore

Save a checkpoint before risky operations:

cortex:checkpoint({
  "action": "save",
  "label": "before-cleanup"
})

Restore if something went wrong:

cortex:checkpoint({
  "action": "restore",
  "label": "before-cleanup"
})

List available checkpoints:

cortex:checkpoint({
  "action": "list"
})

Checkpoints are also created automatically before context compaction (via the compaction hook).

Common Issues

Recall returns irrelevant results:

1. Rate the bad results as useful: false
2. Rate the good results as useful: true
3. Check if there are duplicate/conflicting memories on the same topic
4. Run validate_memory to find stale content

Too many memories on the same topic:

1. Run cortex:consolidate — CLS will merge similar episodic memories into semantic ones
2. Manually forget duplicates

Memory seems wrong/outdated:

1. Forget the old memory
2. Remember the corrected version
3. The knowledge graph will update automatically

Lost important context after compaction:

1. Check cortex:checkpoint({ "action": "list" }) for auto-checkpoints
2. Restore the most recent pre-compaction checkpoint
3. Anchored memories survive compaction automatically