troubleshoot

name	troubleshoot
description	Diagnose and fix claude-mem installation issues. Checks PM2 worker status, database integrity, service health, dependencies, and provides automated fixes for common problems.

Claude-Mem Troubleshooting Skill

Diagnose and resolve installation and operational issues with the claude-mem plugin.

When to Use This Skill

Invoke this skill when:

• Memory not persisting after /clear
• Viewer UI empty or not loading
• Worker service not running
• Database missing or corrupted
• Port conflicts
• Missing dependencies
• "Nothing is remembered" complaints
• Search results empty when they shouldn't be

Do NOT invoke for feature requests or usage questions (use regular documentation for that).

Quick Decision Guide

Once the skill is loaded, choose the appropriate operation:

What's the problem?

• "Nothing is being remembered" → operations/common-issues.md
• "Viewer is empty" → operations/common-issues.md
• "Worker won't start" → operations/common-issues.md
• "Want to run full diagnostics" → operations/diagnostics.md
• "Need automated fix" → operations/automated-fixes.md

Available Operations

Choose the appropriate operation file for detailed instructions:

Diagnostic Workflows

1. Full System Diagnostics - Comprehensive step-by-step diagnostic workflow
2. Worker Diagnostics - PM2 worker-specific troubleshooting
3. Database Diagnostics - Database integrity and data checks

Issue Resolution

4. Common Issues - Quick fixes for frequently encountered problems
5. Automated Fixes - One-command fix sequences

Reference

6. Quick Commands - Essential commands for troubleshooting

Quick Start

Fast automated fix (try this first):

cd ~/.claude/plugins/marketplaces/thedotmack/ && \
pm2 delete claude-mem-worker 2>/dev/null; \
npm install && \
node_modules/.bin/pm2 start ecosystem.config.cjs && \
sleep 3 && \
curl -s http://127.0.0.1:37777/health

Expected output: {"status":"ok"}

If that doesn't work, proceed to detailed diagnostics.

Response Format

When troubleshooting:

1. Identify the symptom - What's the user reporting?
2. Choose operation file - Use the decision guide above
3. Follow steps systematically - Don't skip diagnostic steps
4. Report findings - Tell user what you found and what was fixed
5. Verify resolution - Confirm the issue is resolved

Technical Notes

• Worker port: Default 37777 (configurable via CLAUDE_MEM_WORKER_PORT)
• Database location: ~/.claude-mem/claude-mem.db
• Plugin location: ~/.claude/plugins/marketplaces/thedotmack/
• PM2 process name: claude-mem-worker

Error Reporting

If troubleshooting doesn't resolve the issue, collect diagnostic data and direct user to: https://github.com/thedotmack/claude-mem/issues

See operations/diagnostics.md for details on what to collect.