> ## Documentation Index
> Fetch the complete documentation index at: https://docs.claude-mem.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions for Claude-Mem

# 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

For worker API commands below, set `PORT` first:

```bash theme={null}
PORT=${CLAUDE_MEM_WORKER_PORT:-$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json)}
```

### Viewer UI Not Loading

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

**Solutions**:

1. 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 theme={null}
   PORT=$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json)
   lsof -i :$PORT
   npm run worker:status
   ```

2. Verify worker is healthy:
   ```bash theme={null}
   curl http://127.0.0.1:$PORT/health
   ```

3. Check worker logs for errors:
   ```bash theme={null}
   npm run worker:logs
   ```

4. Restart worker service:
   ```bash theme={null}
   npm run worker:restart
   ```

5. Pin a fixed port if the auto-assigned one collides:
   ```bash theme={null}
   export CLAUDE_MEM_WORKER_PORT=38000
   npm run worker:restart
   ```

### Observer Paused After a Provider Timeout

If an observer request times out, Claude-Mem keeps its queued observations and
schedules another attempt after a delay. The delay starts near the configured
`CLAUDE_MEM_LLM_TIMEOUT_MS` and grows when consecutive attempts time out. A
successful queued observation resets that backoff. No new Claude Code hook is
needed, even when the original session has ended.

Check the worker logs for `Transport pause: scheduled buffered-work resume` and
then `Generator auto-starting (transport-resume)`. If the provider remains
unavailable, the worker keeps probing at a slower rate and admits one
unattended transport resume at a time. On the cmem.ai memory gateway, retries
that run with no Claude Code activity behind them — after a timeout, after a
rate limit's wait, or when memory moves to your Anthropic plan — stop after
three in a row that get no answer, so they do not spend your plan; the queued
observations then wait for your next Claude Code activity (the log says
`Unattended resumes stopped on the cmem gateway`). Authentication and quota
pauses still require their existing recovery paths.

The queued observations in this path are held in worker memory. A worker restart
before they are processed can still discard them; see the separate persistence
work tracked in [issue #4068](https://github.com/thedotmack/claude-mem/issues/4068).

### Theme Toggle Not Persisting

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

**Solutions**:

1. Check browser localStorage is enabled:
   ```javascript theme={null}
   // In browser console
   localStorage.getItem('claude-mem-settings')
   ```

2. Verify settings endpoint is working:
   ```bash theme={null}
   curl http://127.0.0.1:$PORT/api/settings
   ```

3. Clear localStorage and try again:
   ```javascript theme={null}
   // In browser console
   localStorage.removeItem('claude-mem-settings')
   ```

4. Check for browser privacy mode (blocks localStorage)

### SSE Connection Issues

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

**Solutions**:

1. Check SSE endpoint is accessible:
   ```bash theme={null}
   curl -N http://127.0.0.1:$PORT/stream
   ```

2. Check browser console for errors:
   * Open DevTools (F12)
   * Look for EventSource errors
   * Check Network tab for failed /stream requests

3. Verify worker is running:
   ```bash theme={null}
   npm run worker:status
   ```

4. Check for network/proxy issues blocking SSE
   * Corporate firewalls may block SSE
   * Try disabling VPN temporarily

5. Restart worker and refresh browser:
   ```bash theme={null}
   npm run worker:restart
   ```

### Chroma/Python Dependency Issues (v5.0.0+)

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

**Solutions**:

1. Verify Python 3.8+ is installed:
   ```bash theme={null}
   python --version
   # or
   python3 --version
   ```

2. Install chromadb manually:
   ```bash theme={null}
   cd ~/.claude/plugins/marketplaces/thedotmack
   npm install chromadb
   ```

3. Check chromadb health:
   ```bash theme={null}
   npm run chroma:health
   ```

4. Windows-specific: Ensure Python is in PATH:
   ```bash theme={null}
   where python
   # Should show Python installation path
   ```

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

### Turning off tool-hook capture (PreToolUse / PostToolUse)

**When to use it**: you want claude-mem to stop capturing tool calls (`PostToolUse` `observation`) or injecting file history before `Read` (`PreToolUse` `file-context`), for example because the per-tool-call hook cost is too high on your machine. Do not rename those keys in `hooks.json` instead: Claude Code rejects unknown hook keys and drops the entire plugin hook set.

**Opt-out** (SessionStart context, UserPromptSubmit and Stop summaries keep working):

```json theme={null}
{
  "env": {
    "CLAUDE_MEM_DISABLE_TOOL_HOOKS": "1"
  }
}
```

Add that to `~/.claude/settings.json` (or export the variable in your shell). To turn off just one of the two hooks, use `CLAUDE_MEM_DISABLE_OBSERVATION=1` or `CLAUDE_MEM_DISABLE_FILE_CONTEXT=1`. See [Configuration](https://docs.claude-mem.ai/configuration.md).

**Windows console windows**: this switch is not needed for the console window that older versions flashed on each tool call. Claude Code now runs each hook as the `claude-mem` launcher directly, with no bash in between ([#3605](https://github.com/thedotmack/claude-mem/issues/3605)). The switch still only makes each tool hook exit right away; Claude Code still starts the `claude-mem` process.

### Smart Install Caching Issues (v5.0.3+)

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

**Solutions**:

1. Clear install cache:
   ```bash theme={null}
   rm ~/.claude/plugins/marketplaces/thedotmack/.install-version
   ```

2. Force reinstall:
   ```bash theme={null}
   cd ~/.claude/plugins/marketplaces/thedotmack
   npm install --force
   ```

3. Check version marker:
   ```bash theme={null}
   cat ~/.claude/plugins/marketplaces/thedotmack/.install-version
   cat ~/.claude/plugins/marketplaces/thedotmack/package.json | grep version
   ```

4. 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**:

1. Check worker status:
   ```bash theme={null}
   npm run worker:status
   ```

2. Try starting manually:
   ```bash theme={null}
   npm run worker:start
   ```

3. Check worker logs for errors:
   ```bash theme={null}
   npm run worker:logs
   ```

4. Full reset:
   ```bash theme={null}
   npm run worker:stop
   npm run worker:start
   ```

5. Verify Bun is installed:
   ```bash theme={null}
   which bun
   bun --version
   ```

### Port Allocation Failed

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

**Solutions**:

1. Check if the configured port is in use:
   ```bash theme={null}
   lsof -i :$PORT
   ```

2. Kill process using the port:
   ```bash theme={null}
   kill -9 $(lsof -t -i:$PORT)
   ```

3. Or use a different port:
   ```bash theme={null}
   export CLAUDE_MEM_WORKER_PORT=38000
   npm run worker:restart
   ```

4. Verify new port:
   ```bash theme={null}
   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**:

1. Check error logs:
   ```bash theme={null}
   npm run worker:logs
   ```

2. Check worker status:
   ```bash theme={null}
   npm run worker:status
   ```

3. Check database for corruption:
   ```bash theme={null}
   sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"
   ```

4. Verify Bun installation:
   ```bash theme={null}
   bun --version
   ```

### Worker Not Processing Observations

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

**Solutions**:

1. Check worker is running:
   ```bash theme={null}
   npm run worker:status
   ```

2. Check worker logs:
   ```bash theme={null}
   npm run worker:logs
   ```

3. Verify database has observations:
   ```bash theme={null}
   sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;"
   ```

4. Restart worker:
   ```bash theme={null}
   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 theme={null}
# 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:

1. **Check queue status**:

   ```bash theme={null}
   curl http://127.0.0.1:$PORT/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

2. **Trigger manual recovery**:

   ```bash theme={null}
   curl -X POST http://127.0.0.1:$PORT/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:

1. **pending** - Queued, waiting to process
2. **processing** - Currently being processed by SDK agent
3. **processed** - Completed successfully
4. **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**:

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

#### Troubleshooting Recovery Issues

If recovery fails or messages remain stuck:

1. **Verify worker is healthy**:
   ```bash theme={null}
   curl http://127.0.0.1:$PORT/health
   # Should return: {"status":"ok","uptime":12345,"port":...}
   ```

2. **Check database for corruption**:
   ```bash theme={null}
   sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"
   ```

3. **View stuck messages directly**:
   ```bash theme={null}
   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;
   "
   ```

4. **Force reset stuck messages** (nuclear option):

   ```bash theme={null}
   sqlite3 ~/.claude-mem/claude-mem.db "
     UPDATE pending_messages
     SET status = 'pending', started_processing_at_epoch = NULL
     WHERE status = 'processing';
   "
   ```

   Then trigger recovery:

   ```bash theme={null}
   bun scripts/check-pending-queue.ts --process
   ```

5. **Check worker logs for SDK errors**:
   ```bash theme={null}
   npm run worker:logs | grep -i error
   ```

#### Understanding the Queue Table

The `pending_messages` table tracks all messages with these key fields:

```sql theme={null}
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 theme={null}
# 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

### claude-mem: command not found in hooks

**Symptoms**: Every hook reports a non-blocking error, and no context or observations appear. In the transcript or in `claude --debug` output:

```
Error occurred while executing hook command: Executable not found in $PATH: "claude-mem"
```

or, for the startup self-heal entry:

```
Error occurred while executing hook command: Executable not found in $PATH: "node"
```

Session start may also show:

```
claude-mem: memory hooks are not active: <reason>. Fix: run `npx claude-mem install`, then restart Claude Code.
```

**Cause**: Claude Code runs each hook as `claude-mem hook claude-code <event>` with no shell, so it needs the `claude-mem` launcher on the PATH it inherited when it started. The launcher lives at `~/.local/bin/claude-mem` (macOS/Linux) or `%LOCALAPPDATA%\claude-mem\bin\claude-mem.exe` (Windows). The `node` error means Node.js is not on that PATH either, so the self-heal entry (`node ${CLAUDE_PLUGIN_ROOT}/scripts/ensure-launcher.cjs`) cannot run to place the launcher.

**Solutions**:

1. Install or refresh the launcher:
   ```bash theme={null}
   npx claude-mem install
   ```
   It compiles the launcher, places it, and adds its directory to PATH (your shell rc file on macOS/Linux, your user Path on Windows). For the `node` error, install Node.js 20+ first.

2. Restart your terminal or IDE, then Claude Code. A running Claude Code, or an IDE that launched it, keeps the PATH it started with and does not see the change.

3. Check the **Hook launcher** row:
   ```bash theme={null}
   npx claude-mem doctor
   ```
   * `ok` — `<path> (protocol N, --version N ms)`: the launcher resolves; restart Claude Code from a fresh terminal.
   * `installed at <path> but its directory is not on PATH` — open a new terminal, or re-run `npx claude-mem install`.
   * `claude-mem not on PATH` — run `npx claude-mem install`.
   * `<path> is not the claude-mem hook launcher` — another `claude-mem` comes first on PATH (see the next step).
   * `speaks protocol N, expected M` (warn) — the launcher is from another release; run `npx claude-mem install`.

4. Look for a shadowing npm-global `claude-mem`. `npm install -g claude-mem` installs the npm CLI as `claude-mem`; if its directory comes before the launcher's on PATH, hooks run the wrong program:
   ```bash theme={null}
   which -a claude-mem      # macOS/Linux
   where.exe claude-mem     # Windows
   ```
   Remove it with `npm uninstall -g claude-mem`, or put `~/.local/bin` (or `%LOCALAPPDATA%\claude-mem\bin`) ahead of it on PATH. The installer never overwrites a `claude-mem` it did not place.

5. Check your Claude Code version with `claude --version`. The exec-form hooks need **Claude Code 2.1.139 or later**; an older Claude Code ignores the hook `args` and runs bare `claude-mem`, which prints usage and captures nothing, with no error shown. `npx claude-mem doctor` warns on the **Claude Code version** row. Update with `claude update`.

6. Expect one gap after an update. On a marketplace-only install, the startup self-heal compiles the launcher during session start when it is missing or out of date. The first session after that update may miss memory context while it compiles; the next session has it. Running `npx claude-mem update` instead avoids the gap.

### Hooks Not Firing

**Symptoms**: No context appears, observations not saved.

**Solutions**:

1. Verify hooks are configured:
   ```bash theme={null}
   cat plugin/hooks/hooks.json
   ```

2. Test hooks manually:
   ```bash theme={null}
   # Test context hook
   echo '{"session_id":"test-123","cwd":"'$(pwd)'","source":"startup"}' | claude-mem hook claude-code context
   ```

3. Check the launcher is on PATH:
   ```bash theme={null}
   command -v claude-mem && claude-mem --version   # prints the launcher protocol number
   ```
   If it is missing, see [claude-mem: command not found in hooks](#claude-mem-command-not-found-in-hooks).

4. Verify hooks.json is valid JSON:
   ```bash theme={null}
   cat plugin/hooks/hooks.json | jq .
   ```

### Context Not Appearing

**Symptoms**: No session context when Claude starts.

**Solutions**:

1. Check if summaries exist:
   ```bash theme={null}
   sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM session_summaries;"
   ```

2. View recent sessions:
   ```bash theme={null}
   npm run test:context:verbose
   ```

3. Check database integrity:
   ```bash theme={null}
   sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"
   ```

4. Manually test context hook:
   ```bash theme={null}
   npm run test:context
   ```

### Hooks Timeout

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

**Solutions**:

1. Increase timeout in `plugin/hooks/hooks.json`:
   ```json theme={null}
   {
     "timeout": 180  // Increase from 120
   }
   ```

2. Check worker is running (prevents timeout waiting for worker):
   ```bash theme={null}
   npm run worker:status
   ```

3. Check database size (large database = slow queries):
   ```bash theme={null}
   ls -lh ~/.claude-mem/claude-mem.db
   ```

4. Optimize database:
   ```bash theme={null}
   sqlite3 ~/.claude-mem/claude-mem.db "VACUUM;"
   ```

### Windows: `"bun" is not recognized` Hook Errors

**Symptoms**: Every hook fails on Windows with:

```
SessionStart:startup hook error
Failed with non-blocking status code: ""bun"" is not recognized as an internal or external command
```

(or the localized equivalent), even though `bun --version` works fine in any terminal and `where bun` resolves correctly.

**Cause**: cmd.exe silently drops environment variables longer than \~8,191 characters. Older bash-based hooks prepended the login-shell PATH to the inherited PATH, which could double it past that limit — inside cmd.exe the PATH was then empty, so a bare `bun` command could not be resolved even though `where.exe` (which uses Win32 APIs and has no such limit) finds it. This only reproduces when the combined PATH exceeds the limit, which is why the same setup works on machines with a shorter PATH.

**Solutions**:

1. Update claude-mem with `npx claude-mem install`. Hooks now run the `claude-mem` launcher directly with no bash or cmd.exe, and it resolves the absolute `bun.exe` path and spawns it directly. Git Bash is no longer needed for runtime hooks.

2. Check your PATH length; if it is near or above \~4,000 characters it will exceed the cmd.exe limit once doubled:
   ```powershell theme={null}
   $env:Path.Length
   ```

3. Trim duplicate or dead PATH entries (Windows merges the machine and user PATH, and many installers add both).

### Dependencies Not Installing

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

**Solutions**:

1. Manually install dependencies:
   ```bash theme={null}
   cd ~/.claude/plugins/marketplaces/thedotmack
   npm install
   ```

2. Check npm is available:
   ```bash theme={null}
   which npm
   npm --version
   ```

3. Check package.json exists:
   ```bash theme={null}
   ls -la ~/.claude/plugins/marketplaces/thedotmack/package.json
   ```

## Database Issues

### Database Locked

**Symptoms**: "database is locked" errors in logs.

**Solutions**:

1. Close all connections:
   ```bash theme={null}
   npm run worker:stop
   ```

2. Check for stale locks:
   ```bash theme={null}
   lsof ~/.claude-mem/claude-mem.db
   ```

3. Kill processes holding locks:
   ```bash theme={null}
   kill -9 <PID>
   ```

4. Restart worker:
   ```bash theme={null}
   npm run worker:start
   ```

### Database Corruption

**Symptoms**: Integrity check fails, weird errors.

**Solutions**:

1. Check database integrity:
   ```bash theme={null}
   sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"
   ```

2. Backup database:
   ```bash theme={null}
   cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.backup
   ```

3. Try to repair:
   ```bash theme={null}
   sqlite3 ~/.claude-mem/claude-mem.db "VACUUM;"
   ```

4. Nuclear option - recreate database:
   ```bash theme={null}
   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**:

1. Check FTS5 tables exist:
   ```bash theme={null}
   sqlite3 ~/.claude-mem/claude-mem.db "SELECT name FROM sqlite_master WHERE type='table' AND name LIKE '%_fts';"
   ```

2. Rebuild FTS5 tables:
   ```bash theme={null}
   sqlite3 ~/.claude-mem/claude-mem.db "
     INSERT INTO observations_fts(observations_fts) VALUES('rebuild');
     INSERT INTO session_summaries_fts(session_summaries_fts) VALUES('rebuild');
   "
   ```

3. Check triggers exist:
   ```bash theme={null}
   sqlite3 ~/.claude-mem/claude-mem.db "SELECT name FROM sqlite_master WHERE type='trigger';"
   ```

### Database Too Large

**Symptoms**: Slow performance, large database file.

**Solutions**:

1. Check database size:
   ```bash theme={null}
   ls -lh ~/.claude-mem/claude-mem.db
   ```

2. Vacuum database:
   ```bash theme={null}
   sqlite3 ~/.claude-mem/claude-mem.db "VACUUM;"
   ```

3. Delete old sessions:
   ```bash theme={null}
   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);
   "
   ```

4. Rebuild FTS5 after deletion:
   ```bash theme={null}
   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**:

1. Check MCP configuration:
   ```bash theme={null}
   cat plugin/.mcp.json
   ```

2. Verify search server is built:
   ```bash theme={null}
   ls -l plugin/scripts/mcp-server.cjs
   ```

3. Rebuild if needed:
   ```bash theme={null}
   npm run build
   ```

4. Restart Claude Code

### Search Returns No Results

**Symptoms**: Valid queries return empty results.

**Solutions**:

1. Check database has data:
   ```bash theme={null}
   sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;"
   ```

2. Verify FTS5 tables populated:
   ```bash theme={null}
   sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations_fts;"
   ```

3. Test simple query:
   ```bash theme={null}
   # Test MCP search tool
   search(query="test", limit=5)
   ```

4. Check query syntax:
   ```bash theme={null}
   # 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**:

1. Follow 3-layer workflow (don't skip to get\_observations):
   ```bash theme={null}
   # Start with search to get index
   search(query="...", limit=10)

   # Review the index and inspect context around a relevant ID
   timeline(anchor=<relevant_id>, depth_before=2, depth_after=2)

   # Review that context, then fetch only the selected records
   get_observations(ids=[<2-3 relevant IDs>])
   ```

2. Reduce limit in search:
   ```bash theme={null}
   search(query="...", limit=3)
   ```

3. Use filters to narrow results:
   ```bash theme={null}
   search(query="...", type="decision", limit=5)
   ```

4. Paginate results:
   ```bash theme={null}
   # First page
   search(query="...", limit=5, offset=0)

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

5. Batch IDs in get\_observations:
   ```bash theme={null}
   # 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**:

1. Reduce context sessions:
   ```typescript theme={null}
   // In src/hooks/context.ts
   const CONTEXT_SESSIONS = 5;  // Reduce from 10
   ```

2. Optimize database:
   ```bash theme={null}
   sqlite3 ~/.claude-mem/claude-mem.db "
     ANALYZE;
     VACUUM;
   "
   ```

3. Add indexes (if missing):
   ```bash theme={null}
   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**:

1. Use more specific queries
2. Add date range filters
3. Add type/concept filters
4. Reduce result limit
5. Use index format instead of full format

### High Memory Usage

**Symptoms**: Worker uses too much memory.

**Solutions**:

1. Check current usage:
   ```bash theme={null}
   npm run worker:status
   ```

2. Restart worker:
   ```bash theme={null}
   npm run worker:restart
   ```

3. Clean up old data (see "Database Too Large" above)

## Installation Issues

### Plugin Not Found

**Symptoms**: `/plugin install claude-mem` fails.

**Solutions**:

1. Add marketplace first:
   ```bash theme={null}
   /plugin marketplace add thedotmack/claude-mem
   ```

2. Then install:
   ```bash theme={null}
   /plugin install claude-mem
   ```

3. Verify installation:
   ```bash theme={null}
   ls -la ~/.claude/plugins/marketplaces/thedotmack/
   ```

### Build Failures

**Symptoms**: `npm run build` fails.

**Solutions**:

1. Clean and reinstall:
   ```bash theme={null}
   rm -rf node_modules package-lock.json
   npm install
   ```

2. Check Node.js version:
   ```bash theme={null}
   node --version  # Should be >= 20.0.0
   ```

3. Check for TypeScript errors:
   ```bash theme={null}
   npx tsc --noEmit
   ```

### Missing Dependencies

**Symptoms**: "Cannot find module" errors.

**Solutions**:

1. Install dependencies:
   ```bash theme={null}
   npm install
   ```

2. Check package.json:
   ```bash theme={null}
   cat package.json
   ```

3. Verify node\_modules exists:
   ```bash theme={null}
   ls -la node_modules/
   ```

## Debugging

### Enable Verbose Logging

```bash theme={null}
export DEBUG=claude-mem:*
npm run worker:restart
npm run worker:logs
```

### Check Correlation IDs

Trace observations through the pipeline:

```bash theme={null}
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 theme={null}
# 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 theme={null}
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:

1. **Check logs**:
   ```bash theme={null}
   npm run worker:logs
   ```

2. **Create issue**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
   * Include error messages
   * Include relevant logs
   * Include steps to reproduce

3. **Check existing issues**: Someone may have already solved your problem

## Next Steps

* [Configuration](https://docs.claude-mem.ai/configuration.md) - Customize Claude-Mem
* [Development](https://docs.claude-mem.ai/development.md) - Build from source
* [Architecture](https://docs.claude-mem.ai/architecture/overview.md) - Understand the system


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.