Troubleshooting Guide

Quick Diagnostic Tool

Describe any issues you're experiencing to Claude, and the troubleshoot skill will automatically activate to provide diagnosis and fixes.

The troubleshoot skill will:

✅ Check worker status and health
✅ Verify database existence and integrity
✅ Test worker service connectivity
✅ Validate dependencies installation
✅ Check port configuration and availability
✅ Provide automated fixes for common issues

The skill includes comprehensive diagnostics, automated repair sequences, and detailed troubleshooting workflows for all common issues. Simply describe the problem naturally to invoke it.

Common Issues

Viewer UI Not Loading

Symptoms: Cannot reach the viewer URL, page doesn't load, or browser shows a connection error.

Solutions:

Find the worker port. The default is 37700 + (uid % 100). The configured port is the value of CLAUDE_MEM_WORKER_PORT in ~/.claude-mem/settings.json; the running worker also reports it on /api/health:
bash
```
PORT=$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json)
lsof -i :$PORT
npm run worker:status
```
Verify worker is healthy:
bash
```
curl http://127.0.0.1:$PORT/health
```
Check worker logs for errors:
bash
```
npm run worker:logs
```
Restart worker service:
bash
```
npm run worker:restart
```

Pin a fixed port if the auto-assigned one collides:

bash

export CLAUDE_MEM_WORKER_PORT=38000
npm run worker:restart

Theme Toggle Not Persisting

Symptoms: Theme preference (light/dark mode) resets after browser refresh.

Solutions:

Check browser localStorage is enabled:

javascript

// In browser console
localStorage.getItem('claude-mem-settings')

Verify settings endpoint is working:
bash
```
curl http://localhost:37777/api/settings
```

Clear localStorage and try again:

javascript

// In browser console
localStorage.removeItem('claude-mem-settings')

Check for browser privacy mode (blocks localStorage)

SSE Connection Issues

Symptoms: Viewer shows "Disconnected" status, updates not appearing in real-time.

Solutions:

Check SSE endpoint is accessible:
bash
```
curl -N http://localhost:37777/stream
```
Check browser console for errors:
- Open DevTools (F12)
- Look for EventSource errors
- Check Network tab for failed /stream requests
Verify worker is running:
bash
```
npm run worker:status
```
Check for network/proxy issues blocking SSE
- Corporate firewalls may block SSE
- Try disabling VPN temporarily
Restart worker and refresh browser:
bash
```
npm run worker:restart
```

Chroma/Python Dependency Issues (v5.0.0+)

Symptoms: Installation fails with chromadb or Python-related errors.

Solutions:

Verify Python 3.8+ is installed:

bash

python --version
# or
python3 --version

Install chromadb manually:

bash

cd ~/.claude/plugins/marketplaces/thedotmack
npm install chromadb

Check chromadb health:
bash
```
npm run chroma:health
```

Windows-specific: Ensure Python is in PATH:

bash

where python
# Should show Python installation path

If Chroma continues to fail, hybrid search will gracefully degrade to SQLite FTS5 only

Smart Install Caching Issues (v5.0.3+)

Symptoms: Dependencies not updating after plugin update, stale version marker.

Solutions:

Clear install cache:

bash

rm ~/.claude/plugins/marketplaces/thedotmack/.install-version

Force reinstall:

bash

cd ~/.claude/plugins/marketplaces/thedotmack
npm install --force

Check version marker:

bash

cat ~/.claude/plugins/marketplaces/thedotmack/.install-version
cat ~/.claude/plugins/marketplaces/thedotmack/package.json | grep version

Restart Claude Code after manual install

Worker Service Issues

Worker Service Not Starting

Symptoms: Worker doesn't start, or worker status shows it's not running.

Solutions:

Check worker status:
bash
```
npm run worker:status
```
Try starting manually:
bash
```
npm run worker:start
```
Check worker logs for errors:
bash
```
npm run worker:logs
```

Full reset:

bash

npm run worker:stop
npm run worker:start

Verify Bun is installed:
bash
```
which bun
bun --version
```

Port Allocation Failed

Symptoms: Worker fails to start with "port already in use" error.

Solutions:

Check if port 37777 is in use:
bash
```
lsof -i :37777
```
Kill process using the port:
bash
```
kill -9 $(lsof -t -i:37777)
```

Or use a different port:

bash

export CLAUDE_MEM_WORKER_PORT=38000
npm run worker:restart

Verify new port:

bash

curl -s http://127.0.0.1:$CLAUDE_MEM_WORKER_PORT/api/health | jq .port

Worker Keeps Crashing

Symptoms: Worker restarts repeatedly or fails to stay running.

Solutions:

Check error logs:
bash
```
npm run worker:logs
```
Check worker status:
bash
```
npm run worker:status
```

Check database for corruption:

bash

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

Verify Bun installation:
bash
```
bun --version
```

Worker Not Processing Observations

Symptoms: Observations saved but not processed, no summaries generated.

Solutions:

Check worker is running:
bash
```
npm run worker:status
```
Check worker logs:
bash
```
npm run worker:logs
```

Verify database has observations:

bash

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

Restart worker:
bash
```
npm run worker:restart
```

Manual Recovery for Stuck Observations

Symptoms: Observations stuck in processing queue after worker crash or restart, no new summaries appearing despite worker running.

Background: As of v5.x, automatic queue recovery on worker startup is disabled. Users must manually trigger recovery to maintain explicit control over reprocessing and prevent unexpected duplicate observations.

Solutions:

Option 1: Use CLI Recovery Tool (Recommended)

The interactive CLI tool provides the safest and most user-friendly recovery experience:

bash

# Check queue status and prompt for recovery
bun scripts/check-pending-queue.ts

# Auto-process without prompting
bun scripts/check-pending-queue.ts --process

# Process up to 5 sessions
bun scripts/check-pending-queue.ts --process --limit 5

What it does:

✅ Checks worker health before proceeding
✅ Shows detailed queue summary (pending, processing, failed, stuck)
✅ Groups messages by session with age and status breakdown
✅ Prompts user to confirm processing (unless --process flag used)
✅ Shows recently processed messages for feedback

Interactive Example:

Worker is healthy ✓

Queue Summary:
  Pending: 12 messages
  Processing: 2 messages (1 stuck)
  Failed: 0 messages
  Recently Processed: 5 messages in last 30 minutes

Sessions with pending work: 3
  Session 44: 5 pending, 1 processing (age: 2m)
  Session 45: 4 pending, 1 processing (age: 7m - STUCK)
  Session 46: 2 pending

Would you like to process these pending queues? (y/n)

Option 2: Use HTTP API Directly

For automation or scripting scenarios:

Check queue status:
bash
```
curl http://localhost:37777/api/pending-queue
```
Response shows:
- queue.totalPending: Messages waiting to process
- queue.totalProcessing: Messages currently processing
- queue.stuckCount: Processing messages >5 minutes old
- sessionsWithPendingWork: Session IDs needing recovery
Trigger manual recovery:
bash
```
curl -X POST http://localhost:37777/api/pending-queue/process \
  -H "Content-Type: application/json" \
  -d '{"sessionLimit": 10}'
```
Response includes:
- totalPendingSessions: Total sessions with pending messages
- sessionsStarted: Number of sessions we started processing
- sessionsSkipped: Sessions already processing (not restarted)
- startedSessionIds: Database IDs of sessions started

Understanding Queue States

Messages progress through these states:

pending - Queued, waiting to process
processing - Currently being processed by SDK agent
processed - Completed successfully
failed - Failed after 3 retry attempts

Stuck Detection: Messages in processing state for >5 minutes are considered stuck and automatically reset to pending on worker startup (but not automatically reprocessed).

Recovery Strategy

When to use manual recovery:

After worker crashes or unexpected restarts
When observations appear saved but no summaries generated
When queue status shows stuck messages (processing >5 minutes)
After system crashes or forced shutdowns

Best practices:

Always check queue status before triggering recovery
Use the CLI tool for interactive sessions (provides feedback)
Use the HTTP API for automation/scripting
Start with a low session limit (5-10) to avoid overwhelming the worker
Monitor worker logs during recovery: npm run worker:logs
Check recently processed messages to confirm recovery worked

Troubleshooting Recovery Issues

If recovery fails or messages remain stuck:

Verify worker is healthy:

bash

curl http://localhost:37777/health
# Should return: {"status":"ok","uptime":12345,"port":37777}

Check database for corruption:

bash

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

View stuck messages directly:

bash

sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT id, session_db_id, status, retry_count,
         (strftime('%s', 'now') * 1000 - started_processing_at_epoch) / 60000 as age_minutes
  FROM pending_messages
  WHERE status = 'processing'
  ORDER BY started_processing_at_epoch;
"

Force reset stuck messages (nuclear option):

bash

sqlite3 ~/.claude-mem/claude-mem.db "
  UPDATE pending_messages
  SET status = 'pending', started_processing_at_epoch = NULL
  WHERE status = 'processing';
"

Then trigger recovery:

bash

bun scripts/check-pending-queue.ts --process

Check worker logs for SDK errors:
bash
```
npm run worker:logs | grep -i error
```

Understanding the Queue Table

The pending_messages table tracks all messages with these key fields:

sql

CREATE TABLE pending_messages (
  id INTEGER PRIMARY KEY,
  session_db_id INTEGER,          -- Foreign key to sdk_sessions
  claude_session_id TEXT,          -- Claude session ID
  message_type TEXT,               -- 'observation' | 'summarize'
  status TEXT,                     -- 'pending' | 'processing' | 'processed' | 'failed'
  retry_count INTEGER,             -- Current retry attempt (max: 3)
  created_at_epoch INTEGER,        -- When message was queued
  started_processing_at_epoch INTEGER,  -- When marked 'processing'
  completed_at_epoch INTEGER       -- When completed/failed
)

Query examples:

bash

# Count messages by status
sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT status, COUNT(*)
  FROM pending_messages
  GROUP BY status;
"

# Find sessions with pending work
sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT session_db_id, COUNT(*) as pending_count
  FROM pending_messages
  WHERE status IN ('pending', 'processing')
  GROUP BY session_db_id;
"

# View recent failures
sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT id, session_db_id, message_type, retry_count,
         datetime(completed_at_epoch/1000, 'unixepoch') as failed_at
  FROM pending_messages
  WHERE status = 'failed'
  ORDER BY completed_at_epoch DESC
  LIMIT 10;
"

Hook Issues

Hooks Not Firing

Symptoms: No context appears, observations not saved.

Solutions:

Verify hooks are configured:
bash
```
cat plugin/hooks/hooks.json
```

Test hooks manually:

bash

# Test context hook
echo '{"session_id":"test-123","cwd":"'$(pwd)'","source":"startup"}' | node plugin/scripts/context-hook.js

Check hook permissions:
bash
```
ls -la plugin/scripts/*.js
```
Verify hooks.json is valid JSON:
bash
```
cat plugin/hooks/hooks.json | jq .
```

Context Not Appearing

Symptoms: No session context when Claude starts.

Solutions:

Check if summaries exist:

bash

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

View recent sessions:
bash
```
npm run test:context:verbose
```

Check database integrity:

bash

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

Manually test context hook:
bash
```
npm run test:context
```

Hooks Timeout

Symptoms: Hook execution times out, errors in Claude Code.

Solutions:

Increase timeout in plugin/hooks/hooks.json:

json

{
  "timeout": 180  // Increase from 120
}

Check worker is running (prevents timeout waiting for worker):
bash
```
npm run worker:status
```
Check database size (large database = slow queries):
bash
```
ls -lh ~/.claude-mem/claude-mem.db
```

Optimize database:

bash

sqlite3 ~/.claude-mem/claude-mem.db "VACUUM;"

Dependencies Not Installing

Symptoms: SessionStart hook fails with "module not found" errors.

Solutions:

Manually install dependencies:

bash

cd ~/.claude/plugins/marketplaces/thedotmack
npm install

Check npm is available:
bash
```
which npm
npm --version
```

Check package.json exists:

bash

ls -la ~/.claude/plugins/marketplaces/thedotmack/package.json

Database Issues

Database Locked

Symptoms: "database is locked" errors in logs.

Solutions:

Close all connections:
bash
```
npm run worker:stop
```
Check for stale locks:
bash
```
lsof ~/.claude-mem/claude-mem.db
```
Kill processes holding locks:
bash
```
kill -9 <PID>
```
Restart worker:
bash
```
npm run worker:start
```

Database Corruption

Symptoms: Integrity check fails, weird errors.

Solutions:

Check database integrity:

bash

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

Backup database:

bash

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

Try to repair:

bash

sqlite3 ~/.claude-mem/claude-mem.db "VACUUM;"

Nuclear option - recreate database:

bash

rm ~/.claude-mem/claude-mem.db
npm run worker:start  # Will recreate schema

FTS5 Search Not Working

Symptoms: Search returns no results, FTS5 errors.

Solutions:

Check FTS5 tables exist:

bash

sqlite3 ~/.claude-mem/claude-mem.db "SELECT name FROM sqlite_master WHERE type='table' AND name LIKE '%_fts';"

Rebuild FTS5 tables:

bash

sqlite3 ~/.claude-mem/claude-mem.db "
  INSERT INTO observations_fts(observations_fts) VALUES('rebuild');
  INSERT INTO session_summaries_fts(session_summaries_fts) VALUES('rebuild');
  INSERT INTO user_prompts_fts(user_prompts_fts) VALUES('rebuild');
"

Check triggers exist:

bash

sqlite3 ~/.claude-mem/claude-mem.db "SELECT name FROM sqlite_master WHERE type='trigger';"

Database Too Large

Symptoms: Slow performance, large database file.

Solutions:

Check database size:
bash
```
ls -lh ~/.claude-mem/claude-mem.db
```

Vacuum database:

bash

sqlite3 ~/.claude-mem/claude-mem.db "VACUUM;"

Delete old sessions:

bash

sqlite3 ~/.claude-mem/claude-mem.db "
  DELETE FROM observations WHERE created_at_epoch < $(date -v-30d +%s);
  DELETE FROM session_summaries WHERE created_at_epoch < $(date -v-30d +%s);
  DELETE FROM sdk_sessions WHERE created_at_epoch < $(date -v-30d +%s);
"

Rebuild FTS5 after deletion:

bash

sqlite3 ~/.claude-mem/claude-mem.db "
  INSERT INTO observations_fts(observations_fts) VALUES('rebuild');
  INSERT INTO session_summaries_fts(session_summaries_fts) VALUES('rebuild');
"

MCP Search Issues

Search Tools Not Available

Symptoms: MCP search tools not visible in Claude Code.

Solutions:

Check MCP configuration:
bash
```
cat plugin/.mcp.json
```
Verify search server is built:
bash
```
ls -l plugin/scripts/mcp-server.cjs
```
Rebuild if needed:
bash
```
npm run build
```
Restart Claude Code

Search Returns No Results

Symptoms: Valid queries return empty results.

Solutions:

Check database has data:

bash

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

Verify FTS5 tables populated:

bash

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

Test simple query:

bash

# Test MCP search tool
search(query="test", limit=5)

Check query syntax:

bash

# Bad: Special characters may cause issues
search(query="[test]")

# Good: Simple words
search(query="test")

Token Limit Errors

Symptoms: "exceeded token limit" errors from MCP.

Solutions:

Follow 3-layer workflow (don't skip to get_observations):

bash

# Start with search to get index
search(query="...", limit=10)

# Review IDs, then fetch only relevant ones
get_observations(ids=[<2-3 relevant IDs>])

Reduce limit in search:
bash
```
search(query="...", limit=3)
```

Use filters to narrow results:

bash

search(query="...", type="decision", limit=5)

Paginate results:

bash

# First page
search(query="...", limit=5, offset=0)

# Second page
search(query="...", limit=5, offset=5)

Batch IDs in get_observations:

bash

# Always batch multiple IDs in one call
get_observations(ids=[123, 456, 789])

# Don't make separate calls per ID

Performance Issues

Slow Context Injection

Symptoms: SessionStart hook takes too long.

Solutions:

Reduce context sessions:

typescript

// In src/hooks/context.ts
const CONTEXT_SESSIONS = 5;  // Reduce from 10

Optimize database:

bash

sqlite3 ~/.claude-mem/claude-mem.db "
  ANALYZE;
  VACUUM;
"

Add indexes (if missing):

bash

sqlite3 ~/.claude-mem/claude-mem.db "
  CREATE INDEX IF NOT EXISTS idx_sessions_project_created ON sdk_sessions(project, created_at_epoch DESC);
"

Slow Search Queries

Symptoms: MCP search tools take too long.

Solutions:

Use more specific queries
Add date range filters
Add type/concept filters
Reduce result limit
Use index format instead of full format

High Memory Usage

Symptoms: Worker uses too much memory.

Solutions:

Check current usage:
bash
```
npm run worker:status
```
Restart worker:
bash
```
npm run worker:restart
```
Clean up old data (see "Database Too Large" above)

Installation Issues

Plugin Not Found

Symptoms: /plugin install claude-mem fails.

Solutions:

Add marketplace first:

bash

/plugin marketplace add thedotmack/claude-mem

Then install:
bash
```
/plugin install claude-mem
```

Verify installation:

bash

ls -la ~/.claude/plugins/marketplaces/thedotmack/

Build Failures

Symptoms: npm run build fails.

Solutions:

Clean and reinstall:

bash

rm -rf node_modules package-lock.json
npm install

Check Node.js version:
bash
```
node --version  # Should be >= 18.0.0
```
Check for TypeScript errors:
bash
```
npx tsc --noEmit
```

Missing Dependencies

Symptoms: "Cannot find module" errors.

Solutions:

Install dependencies:
bash
```
npm install
```
Check package.json:
bash
```
cat package.json
```
Verify node_modules exists:
bash
```
ls -la node_modules/
```

Debugging

Enable Verbose Logging

bash

export DEBUG=claude-mem:*
npm run worker:restart
npm run worker:logs

Check Correlation IDs

Trace observations through the pipeline:

bash

sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT correlation_id, tool_name, created_at
  FROM observations
  WHERE session_id = 'YOUR_SESSION_ID'
  ORDER BY created_at;
"

Inspect Worker State

bash

# Check if worker is running
npm run worker:status

# View logs
npm run worker:logs

# Check configured port (per-user default = 37700 + uid % 100)
jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json

# Test worker health (substitute PORT for the value above)
curl "http://127.0.0.1:$PORT/health"

Database Inspection

bash

sqlite3 ~/.claude-mem/claude-mem.db

# View schema
.schema

# Check table counts
SELECT 'sessions', COUNT(*) FROM sdk_sessions
UNION ALL
SELECT 'observations', COUNT(*) FROM observations
UNION ALL
SELECT 'summaries', COUNT(*) FROM session_summaries
UNION ALL
SELECT 'prompts', COUNT(*) FROM user_prompts;

# View recent activity
SELECT created_at, tool_name FROM observations ORDER BY created_at DESC LIMIT 10;

Common Error Messages

"Worker service not responding"

Cause: Worker not running or port mismatch.

Solution: Restart worker with npm run worker:restart.

"Database is locked"

Cause: Multiple processes accessing database.

Solution: Stop worker, kill stale processes, restart.

"FTS5: syntax error"

Cause: Invalid search query syntax.

Solution: Use simpler query, avoid special characters.

"SQLITE_CANTOPEN"

Cause: Database file permissions or missing directory.

Solution: Check ~/.claude-mem/ exists and is writable.

"Module not found"

Cause: Missing dependencies.

Solution: Run npm install.

Getting Help

If none of these solutions work:

Check logs:
bash
```
npm run worker:logs
```
Create issue: GitHub Issues
- Include error messages
- Include relevant logs
- Include steps to reproduce
Check existing issues: Someone may have already solved your problem

Next Steps

Configuration - Customize Claude-Mem
Development - Build from source
Architecture - Understand the system