debug-memory

name	debug-memory
description	Diagnose ClaudeMemory installation and configuration issues. Use when memory tools fail or setup seems broken.
user_invocable	true

Debug Memory Setup

When invoked with /debug-memory, this skill runs comprehensive diagnostics on your ClaudeMemory installation.

What This Checks

This skill will verify:

• ✅ Database existence (global and project)
• ✅ Schema version compatibility
• ✅ Hook configuration
• ✅ CLAUDE.md setup
• ✅ Published snapshot status
• ✅ MCP server connectivity
• ✅ Recent ingest activity

Step 1: Run Setup Check

First, check the memory system status using the MCP tool:

memory.check_setup

This returns:

• initialized: true/false
• version: ClaudeMemory version
• issues: List of problems found
• recommendation: Actionable next steps

Step 2: Analyze Results

Based on the check results:

If initialized = true

✅ System is healthy! Show the user:

• Version information
• Database stats
• Last successful operations

If initialized = false

⚠️ System needs setup. Check for:

• Missing database: Run claude-memory init
• Missing CLAUDE.md: Not importing memory snapshot
• Missing hooks: Hooks not configured in settings.json
• Version mismatch: Need to upgrade with gem update claude-memory

Step 3: Provide Recommendations

Give the user clear next steps:

For missing setup:

# Initialize ClaudeMemory
claude-memory init

# Or use the setup skill
/setup-memory

For configuration issues:

# Check system health
claude-memory doctor

# View current status
claude-memory status

For version issues:

# Upgrade to latest version
gem update claude-memory
claude-memory init  # Re-run init after upgrade

Step 4: Verify Fix

After user follows recommendations, run memory.check_setup again to confirm the issue is resolved.

Common Issues

"Database not found"

• Cause: ClaudeMemory not initialized
• Fix: Run claude-memory init or /setup-memory

"Hooks not configured"

• Cause: .claude/settings.json missing hook definitions
• Fix: Run claude-memory init to add hooks

"CLAUDE.md not importing snapshot"

• Cause: Missing @.claude/rules/claude_memory.generated.md import
• Fix: Add import to .claude/CLAUDE.md

"Version mismatch"

• Cause: Old ClaudeMemory version installed
• Fix: Run gem update claude-memory

"No recent ingest activity"

• Cause: Hooks not triggering or failing silently
• Fix: Check hook configuration with claude-memory doctor

Example Output

Running ClaudeMemory diagnostics...

✅ Global database: healthy
   - Location: ~/.claude/memory.sqlite3
   - Schema: v7
   - Facts: 42

✅ Project database: healthy
   - Location: .claude/memory.sqlite3
   - Schema: v7
   - Facts: 127
   - Last ingest: 2026-01-29T21:47:41Z

✅ Hooks: configured
✅ Snapshot: published
✅ CLAUDE.md: importing snapshot

All systems operational! Memory is working correctly.

When to Use This Skill

Use /debug-memory when:

• Memory tools are failing with errors
• Unsure if ClaudeMemory is properly installed
• Hooks don't seem to be running
• Facts aren't being captured
• After upgrading ClaudeMemory
• Setting up a new project

Related Commands

• /setup-memory - Install or upgrade ClaudeMemory
• claude-memory doctor - CLI health check
• claude-memory status - View system status
• memory.check_setup - The underlying MCP tool