Troubleshooting - Claude Mem

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.

Check current status

npm run worker:status

Try starting manually

npm run worker:start

Check logs for errors

npm run worker:logs

Full stop-start reset

npm run worker:stop
npm run worker:start

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.

Find what's using the port

lsof -i :37777

Kill the conflicting process

kill -9 $(lsof -t -i:37777)
npm run worker:start

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.

Read the error logs

npm run worker:logs

Check database for corruption

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

If integrity check fails, see Database corruption below.

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.

Confirm the worker is running

npm run worker:status

Check the worker logs

npm run worker:logs

Verify the database has observations

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

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.

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.

Test context injection manually

npm run test:context

Verbose context test

npm run test:context:verbose

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.

Verify hooks are configured

cat plugin/hooks/hooks.json

Validate hooks.json is valid JSON

cat plugin/hooks/hooks.json | jq .

Check script permissions

ls -la plugin/scripts/*.js

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.

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

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;"

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.

Check MCP configuration

cat plugin/.mcp.json

Verify MCP server binary exists

ls -l plugin/scripts/mcp-server.cjs

Rebuild if the binary is missing

npm run build

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.

Confirm the database has data

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

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.

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');
"

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:

Start with search to get an index

search(query="your topic", limit=10)

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.

Stop the worker

npm run worker:stop

Find processes holding locks

lsof ~/.claude-mem/claude-mem.db

Kill the locking process

kill -9 <PID>

Restart the worker

npm run worker:start

Database corruption

Symptoms: PRAGMA integrity_check returns errors; unusual query failures.

Run integrity check

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

Back up the database

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

Attempt repair with VACUUM

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

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.

Clean install

rm -rf node_modules package-lock.json
npm install

Check Node.js version

node --version
# Must be >= 18.0.0

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.

Confirm the worker is running on port 37777

lsof -i :37777
npm run worker:status

Test the health endpoint

curl http://localhost:37777/health

Check logs for errors

npm run worker:logs

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.

Test the SSE endpoint

curl -N http://localhost:37777/stream

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.

Check for VPN or proxy interference

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

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.

Get Started

Using Claude Mem

AI Providers

Best Practices

Configuration & Development

Documentation Index

​Quick diagnostics

​Worker service issues

​Worker not starting

​Port conflict

​Worker keeps crashing

​Worker not processing observations

​Stuck observation queue

​Option 1: CLI tool (recommended)

​Option 2: HTTP API

​If recovery fails

​Context not injecting

​No context appears in new sessions

​Hooks not firing

​Hooks timing out

​Search issues

​Search tools not available in Claude Code

​Search returns no results

​Token limit errors from MCP

​Database issues

​Database locked

​Database corruption

​Database too large

​Installation issues

​Plugin not found

​Build failures

​Dependencies not installing (SessionStart errors)

​Smart install cache stale (v5.0.3+)

​Viewer UI issues

​Viewer not loading

​Theme not persisting

​Real-time updates not appearing (SSE disconnected)

​Common error messages

​Getting help

Generate a bug report

File a GitHub issue

Build docs developers (and LLMs) love

Quick diagnostics

Worker service issues

Worker not starting

Port conflict

Worker keeps crashing

Worker not processing observations

Stuck observation queue

Option 1: CLI tool (recommended)

Option 2: HTTP API

If recovery fails

Context not injecting

No context appears in new sessions

Hooks not firing

Hooks timing out

Search issues

Search tools not available in Claude Code

Search returns no results

Token limit errors from MCP

Database issues

Database locked

Database corruption

Database too large

Installation issues

Plugin not found

Build failures

Dependencies not installing (SessionStart errors)

Smart install cache stale (v5.0.3+)

Viewer UI issues

Viewer not loading

Theme not persisting

Real-time updates not appearing (SSE disconnected)

Common error messages

Getting help