cortex-debug-memory skill
✓ VerifiedDebug and maintain memory quality by rating usefulness, protecting critical information, deleting incorrect entries, and restoring from checkpoints.
- GitHub stars
- 76
- Files
- 1
- Last commit
- Nov 12, 2026
- License
- MIT
- Allowed tools
- —
What does the cortex-debug-memory skill do?
cortex-debug-memory is an agent skill. Debug and maintain memory quality by rating usefulness, protecting critical information, deleting incorrect entries, and restoring from checkpoints.
Summary generated from the skill's SKILL.md.
About the cortex-debug-memory skill
Maintaining the accuracy of an agent's long-term recall is what this skill enables for developers managing complex memory systems. It provides a suite of tools to audit, refine, and repair stored information when an agent returns stale or incorrect results. By using this skill, an agent can actively manage its own knowledge base through rating, protection, and deletion.
Users can improve retrieval quality by rating memories as useful or not useful to train the metamemory confidence model. For critical information that must never decay, the anchor tool sets a permanent heat level to ensure the data is injected at session start. The skill also includes a validation tool that checks memories against the local filesystem to identify references to deleted files or moved modules.
When risky operations occur, the checkpoint system allows for saving and restoring states. This includes automatic checkpoints created before context compaction. If an agent needs to remove data, it can perform a soft delete to lower heat or a hard delete for permanent removal, though protected memories require a force flag to be deleted.
What an agent can do with it
- 1Remove incorrect informationDelete a specific memory that is no longer accurate using either a soft or hard delete method.
- 2Improve retrieval rankingProvide feedback on memory usefulness to adjust confidence scores and improve future results.
- 3Prevent data decayEnsure core architectural decisions remain available by anchoring them so they never decay.
- 4Identify stale referencesScan the project directory to find memories that reference files or modules that no longer exist.
- 5Revert memory changesRestore the memory state to a previous point if a cleanup operation causes issues.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the cortex-debug-memory skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the cortex-debug-memory skill in Plugin
/plugin marketplace add cdeust/Cortex /plugin install hypermnesia-mcp@cortex-plugins
Install the cortex-debug-memory skill in Claude Code
~/.claude/skills/cortex-debug-memory/SKILL.md
$ npx degit cdeust/Cortex/skills/cortex-debug-memory ~/.claude/skills/cortex-debug-memoryInstall the cortex-debug-memory skill in Claude Code (project)
.claude/skills/cortex-debug-memory/SKILL.md
$ npx degit cdeust/Cortex/skills/cortex-debug-memory .claude/skills/cortex-debug-memoryInstall the cortex-debug-memory skill in Codex
~/.agents/skills/cortex-debug-memory/SKILL.md
$ npx degit cdeust/Cortex/skills/cortex-debug-memory ~/.agents/skills/cortex-debug-memoryInstall the cortex-debug-memory skill in Gemini CLI
~/.gemini/skills/cortex-debug-memory/SKILL.md
$ npx degit cdeust/Cortex/skills/cortex-debug-memory ~/.gemini/skills/cortex-debug-memoryInstall the cortex-debug-memory skill in Claude.ai
npx degit cdeust/Cortex/skills/cortex-debug-memory cortex-debug-memory && zip -r cortex-debug-memory.zip cortex-debug-memory # claude.ai → Customize → Skills → + → Create skill → Upload a skill → cortex-debug-memory.zip
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablecdeust/cortex/skills/cortex-debug-memory is public and reachablegithub.com/cdeust/cortex/tree/HEAD/skills/cortex-debug-memor ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-12github.com/cdeust/cortex/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/cdeust/cortex/blob/HEAD/skills/cortex-debug-memor ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/cdeust/cortex/blob/HEAD/skills/cortex-debug-memor ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 130 linesgithub.com/cdeust/cortex/blob/HEAD/skills/cortex-debug-memor ↗Pass
SKILL.md
View on GitHubDebug 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:
- Rate the bad results as
useful: false - Rate the good results as
useful: true - Check if there are duplicate/conflicting memories on the same topic
- Run
validate_memoryto find stale content
Too many memories on the same topic:
- Run
cortex:consolidate— CLS will merge similar episodic memories into semantic ones - Manually
forgetduplicates
Memory seems wrong/outdated:
- Forget the old memory
- Remember the corrected version
- The knowledge graph will update automatically
Lost important context after compaction:
- Check
cortex:checkpoint({ "action": "list" })for auto-checkpoints - Restore the most recent pre-compaction checkpoint
- Anchored memories survive compaction automatically
Files in this skill
1cortex-debug-memory skill questions
How do I install the cortex-debug-memory skill in Claude Code?
Run npx degit cdeust/Cortex/skills/cortex-debug-memory ~/.claude/skills/cortex-debug-memory. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the cortex-debug-memory skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How can I prevent a memory from decaying or being lost during compaction?
You can anchor a memory to set its heat to 1.0 permanently, ensuring it is injected at session start. Anchored memories also survive compaction automatically.
What is the difference between a soft delete and a hard delete for memories?
A soft delete sets the memory heat to 0 so it won't surface but still exists, while a hard delete performs a permanent removal.
How do I fix irrelevant results during recall?
You should rate the bad results as not useful, rate the good results as useful, check for duplicate or conflicting memories, and run memory validation to find stale content.