Troubleshooting

Solutions to common Claude Mem issues: worker not starting, context not injecting, search returning no results, and more.

Quick diagnostics

Before diving into specific issues, run these checks to get an overview of system health:

# Check if the worker is running
npm run worker:status

# Test worker health endpoint
curl http://localhost:37777/health

# View recent logs
npm run worker:logs

# Check database integrity
sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"

You can also describe your issue to Claude in a session — the built-in troubleshoot skill will automatically activate, run diagnostics, and suggest fixes.

---

Worker service issues

Worker not starting

Symptoms: Worker status shows not running; hooks produce errors; no context is injected.

1. Check current status

   npm run worker:status
   
2. Try starting manually

   npm run worker:start
   
3. Check logs for errors

   npm run worker:logs
   
4. Full stop-start reset

   npm run worker:stop
   npm run worker:start
   
5. Verify Bun is installed

   which bun
   bun --version
   

   Bun is required to run the worker. It should be auto-installed during setup, but if it’s missing, install it from bun.sh.

Port conflict

Symptoms: Worker fails to start with a “port already in use” error; http://localhost:37777 shows a connection error.

1. Find what's using the port

   lsof -i :37777
   
2. Kill the conflicting process

   kill -9 $(lsof -t -i:37777)
   npm run worker:start
   
3. Or switch to a different port

   Edit ~/.claude-mem/settings.json:

   {
     "CLAUDE_MEM_WORKER_PORT": "38000"
   }
   

   Then restart:

   npm run worker:restart
   

   Verify the change took effect:

   cat ~/.claude-mem/worker.port
   

Worker keeps crashing

Symptoms: Worker restarts repeatedly; logs show recurring errors.

1. Read the error logs

   npm run worker:logs
   
2. Check database for corruption

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

   If integrity check fails, see Database corruption below.

3. Verify Bun version

   bun --version
   # Should be >= 1.0.0
   

Worker not processing observations

Symptoms: Observations are saved to the database but no summaries are generated.

1. Confirm the worker is running

   npm run worker:status
   
2. Check the worker logs

   npm run worker:logs
   
3. Verify the database has observations

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

   npm run worker:restart
   

---

Stuck observation queue

Symptoms: Observations are saved but no summaries appear, even after the worker has been running for several minutes.

After a worker crash or forced shutdown, messages may remain stuck in the processing state. Automatic recovery is intentionally disabled — you must trigger it manually.

Option 1: CLI tool (recommended)

# Check queue and prompt to recover
npm run queue

# Auto-process without prompting
npm run queue:process

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

Example output:

Worker is healthy ✓

Queue Summary:
  Pending: 12 messages
  Processing: 2 messages (1 stuck)
  Failed: 0 messages

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: HTTP API

# Check queue status
curl http://localhost:37777/api/pending-queue

# Trigger manual recovery
curl -X POST http://localhost:37777/api/pending-queue/process \
  -H "Content-Type: application/json" \
  -d '{"sessionLimit": 10}'

If recovery fails

Verify worker health

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

View stuck messages directly

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)

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

Then re-run recovery:

npm run queue:process

Check for SDK errors in logs

npm run worker:logs | grep -i error

---

Context not injecting

No context appears in new sessions

Symptoms: Claude starts each session without any memory of past work.

1. Check if summaries exist

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

   If the count is 0, observation processing has not run yet. Start a session, use a few tools, then close it and wait for summaries to generate.

2. Test context injection manually

   npm run test:context
   
3. Verbose context test

   npm run test:context:verbose
   
4. Check database integrity

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

Hooks not firing

Symptoms: No context appears and no observations are being recorded.

1. Verify hooks are configured

   cat plugin/hooks/hooks.json
   
2. Validate hooks.json is valid JSON

   cat plugin/hooks/hooks.json | jq .
   
3. Check script permissions

   ls -la plugin/scripts/*.js
   
4. Test context hook manually

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

Hooks timing out

Symptoms: Hook execution errors in Claude Code; context injection takes too long.

1. Check the worker is running

   If the worker is not running, hooks will wait for it and eventually time out.

   npm run worker:status
   npm run worker:start
   
2. Check database size

   ls -lh ~/.claude-mem/claude-mem.db
   

   A very large database can cause slow queries. Run VACUUM to reclaim space:

   sqlite3 ~/.claude-mem/claude-mem.db "VACUUM;"
   
3. Increase hook timeout

   Edit plugin/hooks/hooks.json and raise the timeout value:

   {
     "timeout": 180
   }
   

---

Search issues

Search tools not available in Claude Code

Symptoms: The search, timeline, and get_observations MCP tools don’t appear.

1. Check MCP configuration

   cat plugin/.mcp.json
   
2. Verify MCP server binary exists

   ls -l plugin/scripts/mcp-server.cjs
   
3. Rebuild if the binary is missing

   npm run build
   
4. Restart Claude Code

   The MCP server is loaded at Claude Code startup — a restart is required after rebuild.

Search returns no results

Symptoms: Valid queries return empty results even though you have prior sessions.

1. Confirm the database has data

   sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;"
   
2. Check FTS5 tables are populated

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

   If observations_fts is empty but observations has rows, rebuild the FTS index.

3. Rebuild FTS5 index

   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');
   "
   
4. Simplify your query

   Special characters can cause FTS5 syntax errors. Use simple words:

   # Avoid
   search(query="[auth] fix")
   
   # Prefer
   search(query="auth fix")
   

Token limit errors from MCP

Symptoms: “exceeded token limit” errors when calling get_observations.

Use the 3-layer progressive disclosure workflow — don’t jump directly to get_observations:

1. Start with search to get an index

   search(query="your topic", limit=10)
   
2. Review IDs and fetch only relevant ones

   get_observations(ids=[<2-3 relevant IDs>])
   

Additional strategies:

• Reduce the limit parameter in search
• Use type and concept filters to narrow results
• Paginate with offset for large result sets
• Always batch multiple IDs in a single get_observations call

---

Database issues

Database locked

Symptoms: “database is locked” errors in worker logs.

1. Stop the worker

   npm run worker:stop
   
2. Find processes holding locks

   lsof ~/.claude-mem/claude-mem.db
   
3. Kill the locking process

   kill -9 <PID>
   
4. Restart the worker

   npm run worker:start
   

Database corruption

Symptoms: PRAGMA integrity_check returns errors; unusual query failures.

1. Run integrity check

   sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"
   
2. Back up the database

   cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.backup
   
3. Attempt repair with VACUUM

   sqlite3 ~/.claude-mem/claude-mem.db "VACUUM;"
   
4. Last resort: recreate the database

   rm ~/.claude-mem/claude-mem.db
   npm run worker:start   # recreates the schema automatically
   

   Deleting the database is irreversible. All stored observations and summaries will be lost. Make a backup first.

Database too large

Symptoms: Slow context injection; slow search; large file size at ~/.claude-mem/claude-mem.db.

# Check size
ls -lh ~/.claude-mem/claude-mem.db

# Reclaim space from deleted rows
sqlite3 ~/.claude-mem/claude-mem.db "VACUUM;"

# Delete sessions older than 30 days
sqlite3 ~/.claude-mem/claude-mem.db "
  DELETE FROM observations WHERE created_at_epoch < (strftime('%s', 'now', '-30 days') * 1000);
  DELETE FROM session_summaries WHERE created_at_epoch < (strftime('%s', 'now', '-30 days') * 1000);
"

# Rebuild FTS index after deletion
sqlite3 ~/.claude-mem/claude-mem.db "
  INSERT INTO observations_fts(observations_fts) VALUES('rebuild');
  INSERT INTO session_summaries_fts(session_summaries_fts) VALUES('rebuild');
"

---

Installation issues

Plugin not found

Symptoms: /plugin install claude-mem fails with “not found”.

# Add the marketplace first
/plugin marketplace add thedotmack/claude-mem

# Then install
/plugin install claude-mem

Build failures

Symptoms: npm run build exits with errors.

1. Clean install

   rm -rf node_modules package-lock.json
   npm install
   
2. Check Node.js version

   node --version
   # Must be >= 18.0.0
   
3. Check for TypeScript errors

   npx tsc --noEmit
   

Dependencies not installing (SessionStart errors)

Symptoms: SessionStart hook fails with “Cannot find module” errors.

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

Smart install cache stale (v5.0.3+)

Symptoms: Dependencies not updating after a plugin update.

# Clear the install cache
rm ~/.claude/plugins/marketplaces/thedotmack/.install-version

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

Restart Claude Code after manual installation.

---

Viewer UI issues

Viewer not loading

Symptoms: http://localhost:37777 shows a connection error or blank page.

1. Confirm the worker is running on port 37777

   lsof -i :37777
   npm run worker:status
   
2. Test the health endpoint

   curl http://localhost:37777/health
   
3. Check logs for errors

   npm run worker:logs
   
4. Restart the worker

   npm run worker:restart
   

Theme not persisting

Symptoms: Light/dark mode preference resets after browser refresh.

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

// Clear and retry if corrupted
localStorage.removeItem('claude-mem-settings')

Also check that your browser is not in private/incognito mode — these block localStorage.

Real-time updates not appearing (SSE disconnected)

Symptoms: Viewer shows “Disconnected” status; new observations don’t appear without a manual refresh.

1. Test the SSE endpoint

   curl -N http://localhost:37777/stream
   
2. Check browser console for errors

   Open DevTools (F12), go to the Network tab, and look for failed /stream requests or EventSource errors in the Console tab.

3. Check for VPN or proxy interference

   Corporate firewalls and some VPNs block Server-Sent Events. Try disabling the VPN temporarily.

4. Restart worker and refresh

   npm run worker:restart
   

---

Common error messages

"Worker service not responding"

Cause: The worker is not running, or the configured port doesn’t match the running worker’s port.

Fix: npm run worker:restart

"Database is locked"

Cause: Multiple processes are accessing the database simultaneously.

Fix: Stop the worker, kill any stale SQLite connections with lsof ~/.claude-mem/claude-mem.db, then restart.

"FTS5: syntax error"

Cause: Invalid characters in a search query (e.g. [, ], * used incorrectly).

Fix: Simplify the query to plain words without special characters.

"SQLITE_CANTOPEN"

Cause: The database file cannot be opened — either missing directory or wrong permissions.

Fix: Verify ~/.claude-mem/ exists and is writable: ls -la ~/.claude-mem/

"Cannot find module"

Cause: Missing npm dependencies.

Fix: npm install in the plugin directory.

"port already in use"

Cause: Another process is occupying port 37777.

Fix: Kill the conflicting process (kill -9 $(lsof -t -i:37777)) or configure a different port in ~/.claude-mem/settings.json.

---

Getting help

If none of the solutions above resolve your issue:

Generate a bug report

Run npm run bug-report to collect diagnostics, then include the output when filing an issue.

File a GitHub issue

Include error messages, relevant log output, and steps to reproduce.