claude-mem — User Guide

1. Quick Start

claude-mem is a persistent memory system for AI coding assistants. It intercepts your coding sessions, extracts structured observations (bugs fixed, features built, decisions made), and compresses them into a timeline that gets injected into future sessions — so your AI assistant remembers what happened last time.

Key features:

• Automatic memory capture from every coding session via lifecycle hooks
• Compressed timeline injection at session start — your AI picks up where you left off
• File-specific context injection — when your AI reads a file, it sees past observations about that file
• Session summaries generated at session end
• MCP server with 12+ search tools for querying your memory database
• 13 IDE integrations: Claude Code, Cursor, Gemini CLI, OpenCode, Windsurf, Codex CLI, Copilot CLI, Antigravity, Goose, Crush, Roo Code, Warp, and OpenClaw
• SQLite primary storage with optional Chroma vector DB for semantic search
• Privacy tags (<private>...</private>) to prevent storing sensitive information
• 30+ localized modes for observations in your language
• Knowledge corpus system for building queryable knowledge bases
• Worktree adoption for merged branch provenance tracking

Prerequisites:

• Node.js ≥ 20.0.0
• Bun ≥ 1.0.0
• At least one supported AI coding IDE installed

Install and start in one command:

npx claude-mem install

? Select IDEs to install for:
  ◉ Claude Code
  ◯ Cursor
  ◯ Gemini CLI
  ...

Installing claude-mem for Claude Code...
  ✓ Plugin registered
  ✓ Hooks installed
  ✓ Worker started on port 37777

Installation complete!

What to try next:

• Start a coding session in your IDE — memory capture begins automatically
• Search your memory: use the mcp__plugin_claude-mem_mcp-search__search MCP tool
• View the timeline in your browser at http://localhost:37777
• See the Configuration section for customization options

Tip

If you already have Bun installed, npx claude-mem install will use it automatically. If not, the installer will offer to install Bun for you — it's required for the worker daemon.

2. Installation

System Requirements

Supported IDEs

Interactive Installation

The recommended way to install claude-mem:

npx claude-mem install

The installer will:

1. Detect which supported IDEs are installed on your system
2. Present a multi-select prompt to choose which IDEs to configure
3. Register the plugin in the IDE's marketplace/plugin directory
4. Install hooks for lifecycle event capture
5. Cache the plugin locally at ~/.claude/plugins/marketplaces/thedotmack/
6. Start the worker daemon

Important

On Windows, hooks require "shell": "bash" in the hooks configuration. The installer handles this automatically, but if you're seeing hook failures on Windows, verify that Git Bash is available and the shell is set correctly. See GitHub issue #2131.

Manual Installation (Advanced)

If you prefer manual setup:

# Clone or install the package
npm install -g claude-mem

# Start the worker
npx claude-mem start

# Verify
npx claude-mem status

claude-mem worker is running on port 37777
Database: ~/.claude-mem/claude-mem.db
Sessions: 0 active

Docker Installation

For containerized deployments:

# Build the image
cd docker/claude-mem
./build.sh

# Run with OAuth credentials (macOS)
./run.sh

The Docker entrypoint seeds OAuth credentials from either a mounted credentials file or the ANTHROPIC_API_KEY environment variable.

Warning

The Docker container needs access to your AI provider credentials. On macOS, run.sh extracts OAuth tokens from the Keychain automatically. On Linux, mount ~/.claude/.credentials.json into the container or set ANTHROPIC_API_KEY.

Cursor-Specific Installation

npx claude-mem install
# Select "Cursor" from the IDE list

Or use the dedicated Cursor commands:

# Install Cursor hooks + MCP server
npm run cursor:install

# Check status
npm run cursor:status

# Uninstall
npm run cursor:uninstall

The Cursor integration installs:

• Hooks for file edit observation capture
• MCP server configuration in Cursor's MCP settings
• Project registry for auto-context updates to .cursor/rules

Post-Install Verification

After installation, verify everything is working:

npx claude-mem status

claude-mem worker is running on port 37777
Database: ~/.claude-mem/claude-mem.db
PID: 12345
Uptime: 2m 15s

Open your IDE and start a coding session. After using a few tools (reading files, editing code), check that observations are being captured:

curl http://localhost:37777/api/stats

Updating

npx claude-mem update

This updates the plugin to the latest version, preserving your database and settings.

Uninstalling

npx claude-mem uninstall

The uninstaller removes:

• Marketplace directory and cached plugin files
• IDE-specific hook registrations
• Plugin registrations

Note

Uninstalling does not delete your memory database at ~/.claude-mem/. Your observations and session history are preserved. Delete ~/.claude-mem/ manually if you want a clean slate.

Install Troubleshooting

Bun not found: Install Bun first: curl -fsSL https://bun.sh/install | bash (macOS/Linux) or powershell -c "irm bun.sh/install.ps1 | iex" (Windows).

Permission denied on ~/.claude/plugins/: Ensure your user owns the .claude directory: sudo chown -R $(whoami) ~/.claude.

Worker fails to start on Windows with spaces in username: This is a known issue (#2123). The worker path resolution fails when the Windows username contains spaces. Workaround: set CLAUDE_MEM_DATA_DIR to a path without spaces.

PowerShell WQL query fails during cleanup on Windows: Known issue (#2114). The orphaned process cleanup uses a WQL LIKE query that can fail on certain PowerShell configurations.

Multiple install/uninstall errors: If you encounter cascading errors during install or uninstall (#2106), try a clean install: remove ~/.claude/plugins/marketplaces/thedotmack/ manually, then run npx claude-mem install again.

Port already in use: The worker defaults to port 37777. If another process holds it, set a different port: CLAUDE_MEM_WORKER_PORT=37778 npx claude-mem start. Known issue: on Windows, a stale socket can hold the port after a crash (#2111).

Hooks fail silently on Windows + Git Bash: SessionStart context injection may fail due to POSIX path and port detection bugs (#2109). Ensure Git Bash is in your PATH and GIT_BASH_PATH is set if needed.

TypeError: n._zod.def in OpenCode hooks: Zod version conflict when bundled scripts run inside OpenCode (#2113). The hook execution fails due to incompatible Zod versions. Wait for an upstream fix or pin Zod version.

3. Configuration

claude-mem uses a layered configuration system. Settings are resolved in priority order: environment variables → settings.json → built-in defaults.

Settings File

The primary configuration file is ~/.claude-mem/settings.json:

{
  "CLAUDE_MEM_WORKER_PORT": "37777",
  "CLAUDE_MEM_MODE": "code",
  "CLAUDE_MEM_LOG_LEVEL": "info"
}

Key User Settings

Environment Variables

Set these in your shell profile or ~/.claude-mem/.env:

Credential Management

claude-mem stores AI provider credentials separately in ~/.claude-mem/.env, isolated from your project environment. The credential manager uses a blocklist approach, stripping ANTHROPIC_API_KEY and CLAUDECODE variables from subprocess environments to prevent credential leakage.

# Claude (default) — uses OAuth from Claude Code installation
# No additional setup needed if Claude Code is already configured

# Gemini — set your API key
CLAUDE_MEM_GEMINI_API_KEY=your-gemini-key

# OpenRouter — set your API key
CLAUDE_MEM_OPENROUTER_API_KEY=your-openrouter-key

Important

When using the Gemini or OpenRouter provider, you must configure the corresponding API key. The worker will fail with a clear error message if the key is missing. Claude (default) uses your existing Claude Code OAuth credentials automatically.

Modes

Modes customize what types of observations claude-mem records and how they're formatted. The default mode is code.

Built-in modes:

Available localized modes: ar, bn, cs, da, de, el, es, fi, fr, he, hi, hu, id, it, ja, ko, nl, no, pl, pt-br, ro, ru, sv, th, tr, uk, vi, zh, zh-tw

To change mode:

{
  "CLAUDE_MEM_MODE": "code--chill"
}

The chill mode is ideal for experienced users who want less noise — it skips routine operations and only records significant architectural decisions, completed features, and non-obvious gotchas.

Tip

Try code--chill mode if your timeline feels cluttered. It dramatically reduces observation volume by filtering out routine file reads, dependency updates, and incremental changes that are obvious from git history.

Telegram Notifications

claude-mem can send notifications to Telegram for security events and specific concepts:

For full configuration reference including all 60+ settings, see the Admin Guide.

4. Core Usage

How Memory Capture Works

claude-mem operates transparently through IDE lifecycle hooks. You don't need to do anything special — just use your AI coding assistant normally.

The hook lifecycle:

1. SessionStart — Worker starts (if needed), compressed memory timeline is injected as context so your AI knows what happened in previous sessions
2. UserPromptSubmit — A session is created or resumed, the SDK agent is spawned to observe tool usage
3. PostToolUse — Each tool use (file read, edit, bash command) is sent to the worker for observation extraction
4. PreToolUse:Read — When your AI reads a file, past observations about that file are injected as context
5. Stop — A session summary is generated capturing what was investigated, learned, and completed
6. SessionEnd — Session is removed from the active session map

What gets recorded:

Each observation includes:

• Title: Short description of the action or topic
• Subtitle: One-sentence explanation (max 24 words)
• Narrative: Full context — what was done, how it works, why it matters
• Facts: Concise, self-contained statements
• Type: bugfix, feature, refactor, change, discovery, decision
• Concepts: Knowledge categories for filtering
• Files: Which files were read or modified

Privacy Tags

Wrap sensitive content in <private> tags to prevent it from being stored:

<private>
The API key is sk-abc123...
The database password is hunter2
</private>

Content inside <private> tags is stripped before observation extraction. Use this for credentials, personal information, or anything you don't want in your memory database.

Searching Your Memory

claude-mem provides multiple search methods through its MCP server.

MCP Tools (available in your IDE):

Recommended search workflow:

1. Search with keywords to see titles, dates, and IDs
2. Timeline to get chronological context around interesting results
3. get_observations to batch fetch full details for specific IDs

# In your IDE, use the MCP tool:
mcp__plugin_claude-mem_mcp-search__search query="authentication" obs_type="bugfix"

# Filter by date range:
mcp__plugin_claude-mem_mcp-search__search query="database" dateStart="2026-01-01"

# Sort options:
mcp__plugin_claude-mem_mcp-search__search query="refactor" orderBy="date_desc"

Note

The MCP server auto-starts the worker via ensureWorkerConnection if it's not running. You don't need to manually start the worker before searching.

HTTP API (direct access):

The worker exposes a REST API on its configured port:

The Memory Viewer

claude-mem includes a web-based viewer accessible at http://localhost:37777 (or your configured port). The viewer shows:

• Real-time session activity via Server-Sent Events (SSE)
• Observation timeline with type icons and token economics
• Session summaries and progress reports
• File-specific observation history
• Search interface

Worker Management

# Start the worker daemon
npx claude-mem start

# Stop the worker
npx claude-mem stop

# Restart the worker
npx claude-mem restart

# Check worker status
npx claude-mem status

Tip

The worker auto-starts on SessionStart via the ensureWorkerRunning mechanism. You rarely need to start it manually. If the worker is unreachable, hooks use a fail-loud counter with a configurable threshold before giving up.

Session Summaries

At session end (or when you stop your AI assistant), claude-mem generates a progress summary capturing:

• Request: What the user asked for
• Investigated: What was explored and examined
• Learned: Key insights about how things work
• Completed: What work was finished
• Next steps: What's planned for the next session
• Notes: Additional observations

These summaries are injected into the next session's context, giving your AI assistant a running start.

5. Common Tasks

Task: Search for All Observations About a Specific File

Goal: Find every observation that touched a particular file.

Steps:

1. Use the MCP search-by-file tool:

   mcp__plugin_claude-mem_mcp-search__search query="src/auth/login.ts"
   

2. Or use the HTTP API:

   curl "http://localhost:37777/api/observations/by-file?file=src/auth/login.ts"
   

3. Review the results — each observation shows the title, type, and when it was created.

Task: Review What Happened in Your Last Session

Goal: See a summary of your most recent coding session.

Steps:

1. Use the timeline MCP tool:

   mcp__plugin_claude-mem_mcp-search__timeline
   

2. The timeline shows observations in chronological order with session boundaries.
3. Session summaries appear at the end of each session block.

Task: Switch to a Quieter Observation Mode

Goal: Reduce observation noise for experienced users.

Steps:

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

   { "CLAUDE_MEM_MODE": "code--chill" }
   

2. Restart the worker:

   npx claude-mem restart
   

3. Future sessions will only record significant observations.

Verify: Start a new session and check that routine file reads no longer generate observations.

Task: Use Observations in a Different Language

Goal: Have observations written in your native language.

Steps:

1. Set the mode to your language code:

   { "CLAUDE_MEM_MODE": "code--ja" }
   

2. Restart the worker.
3. New observations will be written in Japanese (or your chosen language).

Available language codes: ar, bn, cs, da, de, el, es, fi, fr, he, hi, hu, id, it, ja, ko, nl, no, pl, pt-br, ro, ru, sv, th, tr, uk, vi, zh, zh-tw.

Task: Switch AI Provider from Claude to Gemini

Goal: Use Google's Gemini API instead of Claude for observation extraction.

Prerequisites: A Gemini API key.

Steps:

1. Set the provider and API key in ~/.claude-mem/settings.json:

   {
     "CLAUDE_MEM_PROVIDER": "gemini",
     "CLAUDE_MEM_GEMINI_API_KEY": "your-api-key"
   }
   

2. Restart the worker:

   npx claude-mem restart
   

3. Observations will now be extracted using the Gemini API.

Note

Gemini has free-tier RPM (requests per minute) limits that vary by model. The GeminiAgent handles rate limiting automatically. Available Gemini models include gemini-2.5-flash-lite, gemini-2.5-flash, gemini-2.5-pro, gemini-3-flash, and others.

Task: Switch AI Provider to OpenRouter

Goal: Use OpenRouter to access 100+ models from different providers.

Prerequisites: An OpenRouter API key.

Steps:

1. Configure in ~/.claude-mem/settings.json:

   {
     "CLAUDE_MEM_PROVIDER": "openrouter",
     "CLAUDE_MEM_OPENROUTER_API_KEY": "your-api-key"
   }
   

2. Restart the worker.

Task: Enable Semantic Search with Chroma

Goal: Add vector-based semantic search to complement SQLite keyword search.

Steps:

1. Ensure Chroma is enabled (it is by default):

   { "CLAUDE_MEM_CHROMA_ENABLED": "true" }
   

2. Restart the worker. ChromaSync will automatically sync observations to the vector database.
3. Use smart_search MCP tool for semantic queries.

If it fails: If the Chroma subprocess fails to start, claude-mem falls back to SQLite-only search. Check logs: npm run worker:logs.

Warning

If Chroma is enabled but failing, the MCP retry logic may spawn new subprocesses per timeout without killing previous ones — a known memory leak issue (#2102). Disable Chroma with CLAUDE_MEM_CHROMA_ENABLED=false if you experience high memory usage.

Task: Build a Knowledge Corpus

Goal: Create a queryable knowledge base from filtered observations.

Steps:

1. Build a corpus using the MCP tool:

   mcp__plugin_claude-mem_mcp-search__build_corpus name="auth-system" query="authentication"
   

2. Prime the corpus with AI analysis:

   mcp__plugin_claude-mem_mcp-search__prime_corpus name="auth-system"
   

3. Query the corpus:

   mcp__plugin_claude-mem_mcp-search__query_corpus name="auth-system" query="how does token refresh work?"
   

Manage corpora:

mcp__plugin_claude-mem_mcp-search__list_corpora
mcp__plugin_claude-mem_mcp-search__rebuild_corpus name="auth-system"
mcp__plugin_claude-mem_mcp-search__reprime_corpus name="auth-system"

Task: Adopt Observations from a Merged Worktree

Goal: When you merge a git worktree, stamp its observations with provenance so they appear in the main project's timeline.

Steps:

1. After merging the worktree branch:

   npx claude-mem adopt
   

2. This stamps merged worktree observations with provenance metadata, making them visible in the main project's context.

Task: Set Up Transcript Watching for Codex CLI

Goal: Capture memory from Codex CLI sessions via transcript watching (no hooks needed).

Steps:

1. Install the Codex CLI integration:

   npx claude-mem install
   # Select "Codex CLI" from the IDE list
   

2. This merges a Codex watch configuration into ~/.claude-mem/transcript-watch.json.
3. The watcher monitors ~/.codex/sessions/**/*.jsonl for new activity.
4. Context is injected via workspace-local AGENTS.md files.

Task: View Worker Logs

Goal: Diagnose issues by reading worker logs.

Steps:

# View recent logs
npm run worker:logs

# Tail logs in real-time
npm run worker:tail

# Via HTTP API
curl http://localhost:37777/api/logs

Task: Import Existing Data

Goal: Bulk import observations from another source.

Steps:

curl -X POST http://localhost:37777/api/import \
  -H "Content-Type: application/json" \
  -d @observations.json

The import endpoint supports bulk data import with duplicate checking.

Task: Save a Manual Memory

Goal: Explicitly save a memory observation outside of the automatic hook flow.

Steps:

curl -X POST http://localhost:37777/api/memory/save \
  -H "Content-Type: application/json" \
  -d '{"title": "Important decision", "narrative": "We decided to use PostgreSQL instead of MySQL because..."}'

Warning

The POST /api/memory/save endpoint in v12.3.9 silently drops custom metadata.* fields and forces the project column to the plugin's own project (#2116). Verify your saved memories include the metadata you expect.

Task: Switch Between Stable and Beta Branches

Goal: Toggle between the stable and beta versions of claude-mem.

Steps:

1. Open the viewer at http://localhost:37777
2. Use the branch switcher in the settings panel
3. Or via API:

   curl -X POST http://localhost:37777/api/branch/switch \
     -H "Content-Type: application/json" \
     -d '{"branch": "beta"}'
   

The BranchManager validates branch names to prevent command injection and handles npm install after switching.

Task: Use the __IMPORTANT Workflow Guide

Goal: Get a workflow overview when starting with claude-mem's MCP tools.

Steps: Use the __IMPORTANT MCP tool at the start of a session:

mcp__plugin_claude-mem_mcp-search____IMPORTANT topic="workflow"

Available topics: workflow, search_params, examples, all.

Task: Check System Health

Goal: Verify all claude-mem components are functioning.

Steps:

# Quick health check
curl http://localhost:37777/health

# Detailed readiness check
curl http://localhost:37777/api/readiness

# Full diagnostic
curl http://localhost:37777/api/admin/doctor

Task: Clear Failed Queue Messages

Goal: Clean up stuck messages in the processing queue.

Steps:

npm run queue:clear

Or check the queue status first:

npm run queue

Task: Regenerate CLAUDE.md Files

Goal: Update auto-generated CLAUDE.md context files for all folders with observations.

Steps:

npm run claude-md:regenerate

# Preview changes without writing
npm run claude-md:dry-run

This scans your project for folders with observations and generates per-folder CLAUDE.md files containing relevant memory context.

Task: Configure Tier-Based Model Routing

Goal: Route simple observations to a cheaper/faster model and complex ones to a more capable model.

Configure tier routing in settings to automatically select models based on observation complexity — simple tool reads go to a fast model (like Haiku), while complex multi-file changes use the default model.

Task: Run SWE-bench Evaluations

Goal: Benchmark claude-mem's effectiveness using the SWE-bench evaluation suite.

Steps:

# Run a batch of evaluation instances
python evals/swebench/run-batch.py --run-id my-eval --max-concurrent 4

# Summarize results
python evals/swebench/summarize.py --run-id my-eval

6. Troubleshooting

Diagnostic Decision Tree

Issue?
├── Worker won't start
│   ├── Port in use? → Change CLAUDE_MEM_WORKER_PORT or kill stale process
│   ├── Bun not found? → Install Bun (bun.sh)
│   └── Permission denied? → Check ~/.claude-mem/ ownership
├── No observations being captured
│   ├── Worker running? → npx claude-mem status
│   ├── Hooks installed? → Check IDE plugin registration
│   └── Hook errors? → Check worker logs (npm run worker:logs)
├── Context not injected at session start
│   ├── Worker reachable? → curl http://localhost:37777/health
│   ├── Database empty? → Check /api/stats
│   └── Windows + Git Bash? → See #2109
├── Search returns no results
│   ├── Observations exist? → GET /api/stats
│   ├── Chroma errors? → Try SQLite-only (CLAUDE_MEM_CHROMA_ENABLED=false)
│   └── Wrong project? → Check /api/projects
└── High memory/CPU usage
    ├── Chroma subprocess leak? → Disable Chroma, restart worker
    ├── Observer restart loop? → Check #2108
    └── Too many SDK processes? → Hard cap is 10 (process-registry.ts)

Error: UserPromptSubmit hook exits with code 1

Cause: The worker is unreachable when the UserPromptSubmit hook fires. The hook returns exit code 1, causing Claude Code to show "Failed with non-blocking status code" on every prompt (#2095).

Solution:

1. Start the worker: npx claude-mem start
2. Verify it's reachable: curl http://localhost:37777/health
3. If the port is held by a stale process, kill it or change ports.

Prevention: The worker auto-starts on SessionStart. If it consistently fails, check logs for the root cause.

Error: observer-sessions restart/compaction churn

Cause: The observer agent's restart/compaction cycle re-enters the same flow and consumes ~97% of prompt volume (#2108).

Solution:

1. Restart the worker: npx claude-mem restart
2. If the issue persists, check for a RestartGuard trip in the logs — the guard blocks restarts after 10 within 60 seconds or 5 consecutive failures with no successful processing.

Prevention: Upgrade to the latest version, which includes RestartGuard with sliding window and consecutive failure detection.

Error: Worker API error (${status})

Cause: The MCP server or a hook received an error response from the worker HTTP API.

Solution:

1. Check worker status: npx claude-mem status
2. Check logs: npm run worker:logs
3. Restart if needed: npx claude-mem restart

Error: Database not initialized. Call initialize() first.

Cause: Code attempted to access the SQLite database before the DatabaseManager completed initialization.

Solution:

1. Restart the worker — initialization runs on startup.
2. If the error persists, the database file may be corrupted. Back up ~/.claude-mem/claude-mem.db and restart (a new database will be created).

Error: Hard cap exceeded: N processes in registry

Cause: The ProcessRegistry has hit its hard cap of 10 simultaneous SDK subprocesses. This typically means sessions aren't being cleaned up properly.

Solution:

1. Restart the worker to clear the process registry.
2. Check for orphaned processes — the health checker runs every 30 seconds to prune dead processes.

Error: null is not an object on POST /api/memory/save

Cause: Missing optional chaining in MemoryRoutes.ts when Chroma is disabled (#2105).

Solution: Upgrade to a version with the fix, or disable Chroma as a workaround.

Error: Corrupt JSON file, refusing to overwrite

Cause: A JSON configuration file (settings, hooks, registry) contains invalid JSON. claude-mem refuses to overwrite it to prevent data loss.

Solution:

1. Back up the corrupt file.
2. Delete it and let claude-mem regenerate defaults on next start.

Error: PreToolUse:Read hook truncates reads to 1 line

Cause: The file-context handler truncates file reads to 1 line for files with existing observations, injecting observation history instead (#2094). This can cause Edit operations to deadlock if the hook reduces the read to a single line.

Solution: Upgrade to a version where the truncation and deduplication logic has been refined.

Error: Worker fails to spawn on Windows when username contains a space

Cause: Path resolution breaks when the Windows username has spaces, causing 3 cascading bugs (#2097, #2123).

Solution: Set CLAUDE_MEM_DATA_DIR to a path without spaces:

{ "CLAUDE_MEM_DATA_DIR": "C:\\claude-mem-data" }

Error: OpenRouter provider selected but no API key configured

Cause: CLAUDE_MEM_PROVIDER is set to openrouter but no API key is configured.

Solution:

{
  "CLAUDE_MEM_OPENROUTER_API_KEY": "your-key-here"
}

Or set the OPENROUTER_API_KEY environment variable.

Error: Gemini provider selected but no API key configured

Cause: CLAUDE_MEM_PROVIDER is set to gemini but no API key is configured.

Solution:

{
  "CLAUDE_MEM_GEMINI_API_KEY": "your-key-here"
}

Or set the GEMINI_API_KEY environment variable.

Error: Worker self-triggers duplicate-worker detection

Cause: worker-cli.js start/restart can self-trigger duplicate-worker detection and leave claude-mem in a broken reconnect state (#2107).

Solution:

1. Stop all worker processes manually.
2. Wait a few seconds for port release.
3. Start fresh: npx claude-mem start

Error: Supervisor is shutting down, refusing to spawn

Cause: A new SDK subprocess was requested while the supervisor is in its shutdown sequence.

Solution: This is expected during graceful shutdown. Wait for the shutdown to complete, then restart.

Error: SSE stream returned HTTP ${status} (OpenClaw)

Cause: The OpenClaw extension received an error from the SSE stream endpoint.

Solution: Verify the worker is running and the endpoint is accessible.

Error: Viewer UI not found at any expected location

Cause: The bundled viewer HTML/JS files are missing from the expected paths.

Solution: Reinstall: npx claude-mem install

Error: Transcript watch config not found

Cause: The transcript watcher was configured to watch a path that doesn't have a valid configuration file.

Solution: Check ~/.claude-mem/transcript-watch.json exists and has valid JSON.

Error: Telegram API responded ${status}

Cause: The Telegram notification failed, likely due to an invalid bot token or chat ID.

Solution: Verify CLAUDE_MEM_TELEGRAM_BOT_TOKEN and CLAUDE_MEM_TELEGRAM_CHAT_ID in your settings.

Error: Observer agent system prompts leak into database

Cause: The observer agent's own system prompt and tool event XML are persisted as rows in the user_prompts table (#2104).

Solution: Upgrade to a version with the observer session filtering fix. The SSEBroadcaster now filters observer-sessions events (#2118).

Error: Concurrent multi-account setups cannot isolate memory

Cause: Running multiple accounts (e.g., work + personal) on the same machine shares the memory database, daemon, and billing (#2101).

Solution: Use separate CLAUDE_MEM_DATA_DIR values for each account.

Error: PreToolUse:Read timeout (2000s) blocks Claude Code

Cause: The PreToolUse:Read hook has a 2000-second (33-minute) timeout that blocks Claude Code when the worker is unresponsive (#2100).

Solution:

1. Ensure the worker is running and responsive.
2. Set CLAUDE_MEM_HEALTH_TIMEOUT_MS to a lower value (default: 3000ms).
3. Restart the worker if it's hung.

Error: Worker inherits global proxy env and stalls requests

Cause: Worker Claude subprocesses inherit proxy environment variables (HTTP_PROXY, etc.) and stall on requests (#2115).

Solution: The env-sanitizer strips CLAUDECODE_* and CLAUDE_CODE_* variables but may not catch all proxy vars. Unset proxy variables before starting the worker.

Error: timeline-report skill: hardcoded port 37777

Cause: The timeline-report skill has a hardcoded port and broken worktree detection for monorepo subdirectories (#2103).

Solution: Set CLAUDE_MEM_WORKER_PORT consistently and ensure the skill can detect your project root.

Aggressive startup cleanup kills hook-shell ancestors (Linux)

Cause: On cold start, aggressive cleanup SIGKILLs its own hook-shell ancestor processes (#2117, regression of #1785).

Solution: Upgrade to a version with the fix. Workaround: start the worker manually before opening your IDE.

Error: Antigravity context file written to wrong path

Cause: The Antigravity integration writes the context file to .agent/rules instead of .agents/rules (#2132).

Solution: Upgrade to a version with the path fix.

Error: Unknown Gemini CLI event

Cause: The Gemini CLI hooks installer encountered an unrecognized event type from the Gemini CLI.

Solution: This is a non-fatal warning. Check that your Gemini CLI version is compatible with the current claude-mem version.

Error: Corrupt hooks.json at Windsurf path

Cause: The Windsurf hooks JSON file contains invalid JSON. claude-mem refuses to overwrite to prevent data loss.

Solution: Back up the corrupt file, delete it, and reinstall the Windsurf integration.

7. FAQ

Q: Does claude-mem work without an internet connection?

Yes, if you're using the Claude provider with local OAuth credentials. The worker and database are entirely local. Gemini and OpenRouter providers require internet access for API calls.

Q: How much disk space does the database use?

It depends on your usage. A typical developer working 8 hours/day generates roughly 50-200 observations per day. The SQLite database grows at approximately 1-5 MB per week of active use. Session summaries and observation narratives are the largest contributors.

Q: Can I use claude-mem with multiple projects simultaneously?

Yes. Each project is tracked by its project name (derived from the working directory). Observations, sessions, and context are all project-scoped. The worker handles multiple concurrent sessions via the SessionManager.

Q: What happens if the worker crashes mid-session?

The PendingMessageStore uses a claim-confirm pattern with crash recovery. Messages that were being processed when the worker crashed are automatically reclaimed on restart — their worker_pid is checked against live PIDs, and orphaned messages are re-queued. No observations are lost.

Q: Can I export my memory database?

Yes, the database is a standard SQLite file at ~/.claude-mem/claude-mem.db. You can copy it, query it with any SQLite client, or use the GET /api/observations endpoint with pagination to export programmatically.

Q: How does the file-context injection work?

When your AI reads a file (PreToolUse:Read), the file-context handler queries the database for observations that mention that file. It then injects a formatted observation history as additional context, with deduplication by session and specificity scoring to keep the injection concise.

Q: What's the difference between search and smart_search?

search uses SQLite full-text search (keyword matching with filters). smart_search uses Chroma's vector embeddings for semantic similarity — it finds conceptually related observations even when the exact keywords don't match. smart_search requires Chroma to be enabled.

Q: Can I delete specific observations?

You can delete observations through the SQLite database directly. There's no built-in UI for selective deletion, but you can use any SQLite client to DELETE FROM observations WHERE id = ?.

Q: How does the observer agent work?

The observer is a Claude Agent SDK subprocess that receives tool usage events and extracts structured observations using XML-based prompts. It runs alongside your main coding session as a separate process managed by the Supervisor's ProcessRegistry. The observer never interferes with your session — it's read-only.

Q: What's the maximum number of concurrent sessions?

The ProcessRegistry enforces a hard cap of 10 simultaneous SDK subprocesses. If the cap is reached, new sessions wait for a slot via backpressure (pool slot waiting). The HealthChecker prunes dead processes every 30 seconds to free slots.

Q: Can I use claude-mem with multiple AI providers at the same time?

No, the provider setting (CLAUDE_MEM_PROVIDER) is global. You can switch between claude, gemini, and openrouter, but only one is active at a time. Each provider has its own agent implementation (SDKAgent, GeminiAgent, OpenRouterAgent) with the same XML observation format.

Q: How does the token economics display work?

claude-mem tracks two token metrics: discovery tokens (the full size of tool usage that was observed) and read tokens (the compressed observation size). The savings percentage shows how much context compression reduces your token usage when observations are injected back into sessions.

Q: What is worktree adoption?

When you use git worktrees for parallel development, each worktree gets its own project scope. After merging a worktree branch back to main, npx claude-mem adopt stamps those observations with provenance metadata so they appear in the main project's timeline with full context about where they originated.

Q: How do I completely reset claude-mem?

1. Stop the worker: npx claude-mem stop
2. Uninstall: npx claude-mem uninstall
3. Delete data: rm -rf ~/.claude-mem
4. Reinstall: npx claude-mem install

Q: Is my data sent to any cloud service?

Only when observations are being extracted by the AI provider (Claude, Gemini, or OpenRouter). The tool usage content is sent to the provider's API for observation extraction. The resulting observations are stored locally in your SQLite database. No data is sent to claude-mem's servers — there are no claude-mem servers.

Q: Can I run multiple claude-mem workers on different ports?

Not officially supported. The architecture assumes a single worker per machine. For multi-account isolation, use separate CLAUDE_MEM_DATA_DIR directories (#2101).

Q: What does the RestartGuard do?

The RestartGuard prevents tight-loop restart cycles. It has two trip conditions: (1) more than 10 restarts within 60 seconds (sliding window), or (2) more than 5 consecutive failures with no successful processing between them. Once tripped, the guard blocks further restarts until the session is manually cleared or 5 minutes of uninterrupted success resets the counters.

Q: How does claude-mem handle Git Bash on Windows?

claude-mem detects Git Bash via the GIT_BASH_PATH environment variable and shell detection. However, there are known issues with POSIX path normalization and port detection on Windows + Git Bash (#2109). If hooks fail silently, ensure Git Bash is in your PATH.

Q: What observation types are available?

The default code mode supports: bugfix, feature, refactor, change, discovery, decision, session, and prompt. Custom modes can define additional types.

Q: How does the CLAUDE.md generation work?

npm run claude-md:regenerate scans your project for folders that have associated observations, then writes per-folder CLAUDE.md files containing a formatted timeline of relevant observations. This gives your AI assistant folder-specific context when working in different parts of the codebase. It uses git ls-files to respect .gitignore.

Q: What's the __IMPORTANT MCP tool?

It's a workflow guide tool that provides onboarding information about how to use claude-mem's search tools effectively. Call it with topic="workflow" for the recommended search strategy, topic="search_params" for available filter parameters, or topic="all" for everything.

Q: Can I use claude-mem for non-coding tasks?

The observation extraction is optimized for coding sessions (file reads, edits, bash commands), but the system works with any tool usage that flows through the hook lifecycle. The code--chill mode is particularly useful for non-coding work as it only records significant events.

Q: How does session management handle IDE restarts?

Each session has a unique ID tied to the IDE session. If you restart your IDE, a new session is created. The previous session's summary (generated at Stop/SessionEnd) is included in the next session's context injection. The SessionManager tracks active sessions and cleans up orphans.

Q: What is the SWE-bench evaluation system?

claude-mem includes an evaluation harness in evals/swebench/ for running SWE-bench benchmarks with claude-mem augmentation. It supports batch processing with configurable concurrency, timeout, and auth modes (OAuth or API key). This is for development and research purposes.

Q: What's the difference between the PendingMessageStore and direct database writes?

The PendingMessageStore is a persistent work queue that ensures observations are never lost. Messages are persisted before processing using a claim-confirm pattern: enqueue (status=pending) → claim (status=processing, stamped with worker PID) → confirm (deleted after successful DB write). If the worker crashes between claim and confirm, the message is automatically reclaimed by the next worker that starts — it checks worker_pid liveness, not a timer.

Q: How do I check which version of claude-mem is installed?

npx claude-mem version

Or query the worker API:

curl http://localhost:37777/api/version

Q: What's the code--chill mode exactly?

The chill mode records only work that would be painful to rediscover: shipped features, fixed bugs, architecture decisions, significant refactors, and non-obvious gotchas. It skips incremental steps, routine implementations, straightforward pattern-following, and changes obvious from code or git history. The rule is: when in doubt, skip it.

Q: Does claude-mem support multi-language codebases?

Yes. The tree-sitter grammar plugin (plugin/package.json) includes parsers for 20+ languages: C, C++, Go, Java, JavaScript, TypeScript, Python, Ruby, Rust, Kotlin, Swift, PHP, Elixir, Lua, Scala, Bash, Haskell, Zig, CSS, SCSS, TOML, YAML, SQL, and Markdown. These are used for smart code analysis in hooks and context injection.