claude-mem/plugin/skills/troubleshoot/operations/common-issues.md

Common Issue Resolutions

Quick fixes for frequently encountered claude-mem problems.

Issue: Nothing is Remembered After /clear

Symptoms:

• Data doesn't persist across sessions
• Context is empty after /clear
• Search returns no results for past work

Root cause: Sessions are marked complete but data should persist. This suggests:

• Worker not processing observations
• Database not being written to
• Context hook not reading from database

Fix:

1. Verify worker is running:

   cd ~/.claude/plugins/marketplaces/thedotmack/
   npm run worker:status
   

2. Check database has recent observations:

   sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations WHERE created_at > datetime('now', '-1 day');"
   

3. Restart worker and start new session:

   cd ~/.claude/plugins/marketplaces/thedotmack/
   npm run worker:restart
   

4. Create a test observation: /skill version-bump then cancel

5. Check if observation appears in viewer:

   open http://127.0.0.1:37777
   # Or manually check database:
   sqlite3 ~/.claude-mem/claude-mem.db "SELECT * FROM observations ORDER BY created_at DESC LIMIT 1;"
   

Issue: Viewer Empty After Every Claude Restart

Symptoms:

• Viewer shows no data at http://127.0.0.1:37777
• Stats endpoint returns all zeros
• Database appears empty in UI

Root cause:

• Database being recreated on startup (shouldn't happen)
• Worker reading from wrong database location
• Database permissions issue

Fix:

1. Check database file exists and has data:

   ls -lh ~/.claude-mem/claude-mem.db
   sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;"
   

2. Check file permissions:

   ls -la ~/.claude-mem/claude-mem.db
   # Should be readable/writable by your user
   

3. Verify worker is using correct database path in logs:

   grep "Database" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
   

4. Test viewer connection manually:

   curl -s http://127.0.0.1:37777/api/stats
   # Should show non-zero counts if data exists
   

Issue: Old Memory in Claude

Symptoms:

• Context contains outdated observations
• Irrelevant past work appearing in sessions
• Context feels stale

Root cause: Context hook injecting stale observations

Fix:

1. Check the observation count setting:

   grep CLAUDE_MEM_CONTEXT_OBSERVATIONS ~/.claude-mem/settings.json
   

2. Default is 50 observations - you can adjust this:

   {
     "env": {
       "CLAUDE_MEM_CONTEXT_OBSERVATIONS": "25"
     }
   }
   

3. Check database for actual observation dates:

   sqlite3 ~/.claude-mem/claude-mem.db "SELECT created_at, project, title FROM observations ORDER BY created_at DESC LIMIT 10;"
   

4. Consider filtering by project if working on multiple codebases

Issue: Worker Not Starting

Symptoms:

• Worker status shows not running or error
• Health check fails
• Viewer not accessible

Root cause:

• Port already in use
• Bun not installed
• Missing dependencies

Fix:

1. Try manual worker start to see error:

   cd ~/.claude/plugins/marketplaces/thedotmack/
   bun plugin/scripts/worker-service.js
   # Should start server on port 37777 or show error
   

2. If port in use, change it:

   mkdir -p ~/.claude-mem
   echo '{"CLAUDE_MEM_WORKER_PORT":"37778"}' > ~/.claude-mem/settings.json
   

3. If dependencies missing:

   cd ~/.claude/plugins/marketplaces/thedotmack/
   npm install
   npm run worker:start
   

Issue: Search Results Empty

Symptoms:

• Search skill returns no results
• API endpoints return empty arrays
• Know there's data but can't find it

Root cause:

• FTS5 tables not synchronized
• Wrong project filter
• Database not being queried correctly

Fix:

1. Check if observations exist in database:

   sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;"
   

2. Check FTS5 table sync:

   sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations_fts;"
   # Should match observation count
   

3. Try search via API directly:

   curl "http://127.0.0.1:37777/api/search/observations?q=test&format=index"
   

4. If FTS5 out of sync, restart worker (triggers reindex):

   cd ~/.claude/plugins/marketplaces/thedotmack/
   npm run worker:restart
   

Issue: Port Conflicts

Symptoms:

• Worker won't start
• Error: "EADDRINUSE: address already in use"
• Health check fails

Fix:

1. Check what's using port 37777:

   lsof -i :37777
   

2. Either kill the conflicting process or change claude-mem port:

   mkdir -p ~/.claude-mem
   echo '{"CLAUDE_MEM_WORKER_PORT":"37778"}' > ~/.claude-mem/settings.json
   cd ~/.claude/plugins/marketplaces/thedotmack/
   npm run worker:restart
   

Issue: Database Corrupted

Symptoms:

• SQLite errors in logs
• Worker crashes on startup
• Queries fail

Fix:

1. Backup the database:

   cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.backup
   

2. Try to repair:

   sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"
   

3. If repair fails, recreate (loses data):

   rm ~/.claude-mem/claude-mem.db
   cd ~/.claude/plugins/marketplaces/thedotmack/
   npm run worker:restart
   # Worker will create new database
   

Prevention Tips

Keep claude-mem healthy:

• Regularly check viewer UI to see if observations are being captured
• Monitor database size (shouldn't grow unbounded)
• Update plugin when new versions are released
• Keep Claude Code updated

Performance tuning:

• Adjust CLAUDE_MEM_CONTEXT_OBSERVATIONS if context is too large/small
• Use /clear to mark sessions complete and start fresh
• Use search skill to query specific memories instead of loading everything