troubleshoot
Diagnose and fix claude-mem installation issues. Checks PM2 worker status, database integrity, service health, dependencies, and provides automated fixes for common problems.
When & Why to Use This Skill
The Claude-Mem Troubleshooting Skill is a specialized diagnostic and repair utility designed to maintain the health of the claude-mem ecosystem. It automates complex technical checks including PM2 worker status, database integrity, and dependency verification, providing users with instant automated fixes for common installation and operational failures to ensure persistent AI memory.
Use Cases
- Automated recovery of the claude-mem-worker service when memory fails to persist after sessions.
- Diagnosing and repairing corrupted or missing database files to restore agent context and history.
- Resolving port conflicts and environment dependency issues during initial plugin setup or updates.
- Fixing 'Viewer UI' loading errors and empty search result bugs through systematic system diagnostics.
| 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
- Full System Diagnostics - Comprehensive step-by-step diagnostic workflow
- Worker Diagnostics - PM2 worker-specific troubleshooting
- Database Diagnostics - Database integrity and data checks
Issue Resolution
- Common Issues - Quick fixes for frequently encountered problems
- Automated Fixes - One-command fix sequences
Reference
- 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:
- Identify the symptom - What's the user reporting?
- Choose operation file - Use the decision guide above
- Follow steps systematically - Don't skip diagnostic steps
- Report findings - Tell user what you found and what was fixed
- 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.