claude-mem — Administrator & Developer Guide

1. Architecture Overview

claude-mem is a persistent memory compression framework for AI coding assistants. It intercepts IDE lifecycle events (session start, tool usage, file reads, session end), processes them through an AI observation extraction agent, stores structured observations in a local SQLite database, and re-injects compressed context into future sessions. The system operates as a local daemon with no cloud dependencies beyond the AI provider API.

The architecture follows a hook-driven event pipeline: IDE hooks capture events → Express HTTP worker processes them → SDK agent extracts observations → SQLite stores them → context builder compresses and injects them back. All state is local to the user's machine.

Architecture Diagram

┌─────────────────────────────────────────────────────────────────────┐
│  IDE (Claude Code / Cursor / Gemini CLI / 10+ others)              │
│                                                                     │
│  Hooks:                                                             │
│    SessionStart ──→ context-hook ──→ inject timeline context        │
│    UserPromptSubmit ──→ session-init ──→ create/resume session      │
│    PostToolUse(*) ──→ observation ──→ queue for SDK extraction      │
│    PreToolUse:Read ──→ file-context ──→ inject file observations    │
│    Stop ──→ summarize ──→ generate session summary                  │
│    SessionEnd ──→ session-complete ──→ cleanup                      │
└───────────────────────────┬─────────────────────────────────────────┘
                            │ HTTP (port 37777)
                            ▼
┌─────────────────────────────────────────────────────────────────────┐
│  Worker Daemon (Express + Bun runtime)                              │
│                                                                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │ SessionMgr   │  │ SearchMgr    │  │ ContextBuilder│             │
│  │ (sessions,   │  │ (SQLite FTS, │  │ (timeline,    │             │
│  │  queue)      │  │  Chroma,     │  │  token econ)  │             │
│  └──────┬───────┘  │  hybrid)     │  └───────────────┘             │
│         │          └──────────────┘                                  │
│         ▼                                                            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │ SDKAgent     │  │ GeminiAgent  │  │ OpenRouter   │              │
│  │ (Claude SDK) │  │ (REST API)   │  │  Agent       │              │
│  └──────┬───────┘  └──────────────┘  └──────────────┘              │
│         │                                                            │
│  ┌──────▼───────┐  ┌──────────────┐  ┌──────────────┐              │
│  │ Supervisor   │  │ PendingMsg   │  │ SSE          │              │
│  │ (ProcessReg, │  │  Store       │  │  Broadcaster  │             │
│  │  health chk) │  │ (queue)      │  │ (live UI)    │              │
│  └──────────────┘  └──────────────┘  └──────────────┘              │
│                                                                     │
│  ┌──────────────────────────────────────────────────────────┐       │
│  │ SQLite (WAL mode)     │  Chroma (optional)               │      │
│  │ observations, sessions│  Vector embeddings for            │      │
│  │ summaries, prompts,   │  semantic search                  │      │
│  │ pending_messages,     │                                   │      │
│  │ schema_versions       │                                   │      │
│  └───────────────────────┴───────────────────────────────────┘      │
└─────────────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────────┐
│  MCP Server (stdio transport)                                       │
│  12+ tools: search, timeline, get_observations, smart_search,       │
│  smart_unfold, smart_outline, build_corpus, list_corpora,           │
│  prime_corpus, query_corpus, rebuild_corpus, reprime_corpus,        │
│  __IMPORTANT                                                        │
│  Parent heartbeat for orphan detection                              │
└─────────────────────────────────────────────────────────────────────┘

Component Inventory

Technology Stack

Data Flow: Observation Extraction

1. User invokes tool in IDE (e.g., Edit file)
2. PostToolUse hook fires → observation handler
3. Handler sends tool_name + tool_input + tool_response + cwd to worker
4. Worker's SessionManager enqueues a PendingMessage (status=pending)
5. Worker claims message (status=processing, stamps worker_pid)
6. SDKAgent (or Gemini/OpenRouter agent) receives observation prompt
7. Agent returns XML: <observation> with title, subtitle, narrative, facts, type, concepts, files
8. Parser validates XML → discriminated union: observation[] | summary | invalid
9. Observations stored in SQLite + synced to Chroma (if enabled)
10. PendingMessage confirmed (deleted from queue)
11. SSEBroadcaster notifies connected viewer clients

Data Flow: Context Injection

1. SessionStart hook fires → context-hook handler
2. ContextBuilder queries SQLite for recent observations + summaries
3. ObservationCompiler applies type/concept filtering per mode config
4. TokenCalculator computes read vs. discovery token economics
5. Compressed timeline returned as hookSpecificOutput → additionalContext
6. IDE injects timeline into the AI's system context
7. AI now knows what happened in previous sessions

2. System Requirements

Hardware

Software

Supported Platforms

Note

Windows support has several known issues around path handling (spaces in usernames), shell detection (Git Bash requirement), and port management (stale sockets). macOS and Linux provide the most reliable experience.

3. Configuration Reference

Configuration Precedence

Settings are resolved in this order (first match wins):

1. Environment variables (e.g., CLAUDE_MEM_WORKER_PORT=37778)
2. Settings file (~/.claude-mem/settings.json)
3. Built-in defaults (in SettingsDefaultsManager)

File Locations

All Settings

Important

The CLAUDE_MEM_DATA_DIR setting changes the root for all data files (database, logs, vector DB, observer sessions). Set this before first run if you need a non-default location — migrating later requires moving the database file manually.

Hook Timeouts

Defined in src/shared/hook-constants.ts:

Hooks Configuration

The plugin's hooks.json defines the complete hook lifecycle:

{
  "hooks": {
    "Setup": ["smart-install"],
    "SessionStart": {
      "triggers": ["startup", "clear", "compact"],
      "commands": ["smart-install", "worker start", "context hook"]
    },
    "UserPromptSubmit": ["session-init hook"],
    "PostToolUse": {
      "triggers": ["*"],
      "commands": ["observation hook"]
    },
    "PreToolUse": {
      "triggers": ["Read"],
      "commands": ["file-context hook"]
    },
    "Stop": ["summarize hook"],
    "SessionEnd": ["session-complete hook"]
  }
}

SQLite Configuration

Applied on database initialization (in ClaudeMemDatabase and DatabaseManager):

4. Deployment & Scaling

Local Deployment (Standard)

The standard deployment is a single-user local installation:

npx claude-mem install   # Interactive IDE setup
npx claude-mem start     # Start worker daemon

All data lives in ~/.claude-mem/. The worker binds to localhost:37777. No external network access required except AI provider API calls.

Docker Deployment

Build:

cd docker/claude-mem
./build.sh    # Runs npm build + docker build

Run (macOS with Keychain):

./run.sh

The run.sh script:

1. Extracts OAuth credentials from the macOS Keychain
2. Mounts ~/.claude-mem as a persistent volume
3. Runs the container interactively

Run (Linux / manual credentials):

docker run -it \
  -v ~/.claude-mem:/home/user/.claude-mem \
  -v ~/.claude/.credentials.json:/tmp/claude-creds.json:ro \
  -e CLAUDE_CREDENTIALS_FILE=/tmp/claude-creds.json \
  claude-mem/claude-mem:latest

Or use an API key directly:

docker run -it \
  -v ~/.claude-mem:/home/user/.claude-mem \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  claude-mem/claude-mem:latest

The entrypoint.sh seeds credentials from the mounted file or environment variable into the container's credential store.

Warning

The Docker image expects the ~/.claude-mem volume for persistent storage. Without it, all observations are lost when the container stops.

Multi-Account Isolation

Running multiple accounts (work + personal) on the same machine requires separate data directories (#2101):

# Account 1
CLAUDE_MEM_DATA_DIR=~/.claude-mem-work CLAUDE_MEM_WORKER_PORT=37777 npx claude-mem start

# Account 2
CLAUDE_MEM_DATA_DIR=~/.claude-mem-personal CLAUDE_MEM_WORKER_PORT=37778 npx claude-mem start

Each instance gets its own database, logs, and observer sessions. Configure IDE hooks to point to the correct port.

Scaling Considerations

claude-mem is designed for single-user, single-machine operation. Scaling limits:

5. Operations

Worker Lifecycle

The worker daemon is the central component. All operations flow through it.

Start/Stop/Restart:

npx claude-mem start     # Start in background
npx claude-mem stop      # Graceful shutdown (SIGTERM → 5s → SIGKILL)
npx claude-mem restart   # Stop then start
npx claude-mem status    # Check if running

Auto-start: The SessionStart hook calls ensureWorkerRunning() which lazy-spawns the worker if it's not already running. The mechanism uses a health check (/health endpoint) with a configurable timeout.

Fail-loud counter: If the worker is unreachable, executeWithWorkerFallback increments a fail counter. After a threshold, hooks stop attempting to contact the worker and fail immediately (reducing hook latency when the worker is down).

Tip

Monitor worker health by polling GET /health or GET /api/readiness. The readiness endpoint includes database connectivity status.

Process Management

Supervisor: The Supervisor singleton validates the worker PID file and manages SDK subprocess lifecycle. It uses start-token verification to detect PID reuse (stale PID files pointing to a different process).

ProcessRegistry: Manages all SDK subprocesses with:

• PID tracking and POSIX process groups (pgid)
• Session reaping for cleanup
• SDK spawn factory with pre-spawn cleanup
• Pool slot waiting (backpressure when at capacity)
• Hard cap of 10 processes
• Health checker: 30-second interval pruning dead processes

Shutdown cascade:

1. SIGTERM sent to all registered processes
2. Wait 5 seconds for graceful termination
3. SIGKILL for any remaining processes
4. On Windows: uses tree-kill (optional dependency) for process tree termination

Note

On Linux, the Supervisor uses POSIX process groups (pgid) for reliable child cleanup. On Windows, it falls back to tree-kill which traverses the process tree via the Win32 API.

Log Management

Logs are written to ~/.claude-mem/logs/worker-{YYYY-MM-DD}.log with daily rotation.

# View recent logs
npm run worker:logs      # Last 50 lines

# Tail in real-time
npm run worker:tail

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

# Clear logs
curl -X POST http://localhost:37777/api/logs/clear

The Logger class (src/utils/logger.ts) supports levels: debug, info, warn, error. Set via CLAUDE_MEM_LOG_LEVEL.

Queue Management

The PendingMessageStore is the persistent work queue:

# Check queue status
npm run queue

# Process pending messages
npm run queue:process

# Clear all failed messages
npm run queue:clear

Self-healing: The claimNextMessage() query automatically reclaims messages from crashed workers by checking worker_pid against the live-pids set. No timer-based reaper — liveness is the truth.

Failed message cleanup: On worker startup, clearFailedOlderThan() deletes stale failed messages to keep the queue bounded and claim queries fast.

Tip

If you see the queue growing with failed messages, check the worker logs for SDK agent errors (model rate limits, credential issues, or XML parse failures).

Database Operations

Backup:

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

SQLite WAL mode means you should also copy the -wal and -shm files if they exist, or use .backup command via SQLite CLI for a consistent snapshot.

Migrations: The MigrationRunner runs all pending schema migrations on startup. Migrations are versioned and tracked in the schema_versions table. You don't need to run migrations manually — they're applied automatically.

Direct query access:

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

Health Monitoring

Admin Endpoints

6. Performance

Token Economics

claude-mem tracks two metrics for every observation:

• Discovery tokens: The estimated size of the raw tool usage (input + response) that was observed
• Read tokens: The compressed observation size (title + subtitle + narrative + facts)

The TokenCalculator (src/services/context/) computes savings percentages and formats the economics display. Estimation uses 4 characters per token.

Context Injection Optimization

The ContextBuilder compresses observations for injection:

• ObservationCompiler applies SQL filters by type, concept, and mode configuration
• Multi-project support for worktrees — queries both the main project and worktree-adopted observations
• Token budgeting — the context builder tracks cumulative injection size
• Deduplication — the file-context handler deduplicates observations by session ID and applies specificity scoring

Search Performance

The SearchManager delegates to modular strategies:

Pagination: The PaginationHelper uses the LIMIT+1 trick to detect hasMore without a COUNT(*) query.

Database Performance Tuning

The SQLite database is configured for maximum read performance:

• WAL mode: Allows concurrent readers during writes
• Memory-mapped I/O: 256 MB mmap reduces syscall overhead
• Page cache: 10,000 pages in memory
• In-memory temp store: Temporary tables don't hit disk

For large installations (10K+ observations), consider periodic VACUUM:

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

Worker Resource Usage

Warning

With Chroma enabled and multiple active sessions, peak memory can reach 2+ GB. On memory-constrained systems, disable Chroma (CLAUDE_MEM_CHROMA_ENABLED=false) and limit concurrent sessions.

7. Security

Credential Isolation

The EnvManager (src/shared/EnvManager.ts) provides credential isolation:

• Credentials stored separately in ~/.claude-mem/.env
• Blocklist approach: ANTHROPIC_API_KEY and CLAUDECODE* variables are stripped from subprocess environments
• buildIsolatedEnv() constructs a clean environment for SDK subprocesses
• getCredential() provides read access to stored credentials

Subprocess Environment Sanitization

The env-sanitizer (src/supervisor/env-sanitizer.ts) strips additional sensitive variables:

• CLAUDECODE_* variables (all)
• CLAUDE_CODE_* variables (all)
• Preserved: OAUTH_TOKEN and GIT_BASH_PATH (needed for operation)

Caution

Proxy environment variables (HTTP_PROXY, HTTPS_PROXY, ALL_PROXY) are NOT stripped by the sanitizer. Worker subprocesses inherit them, which can cause stalls when the proxy is unreachable (#2115). Unset these before starting the worker if your network uses a proxy.

Input Validation

• Branch names: BranchManager.isValidBranchName() validates against ^[a-zA-Z0-9][a-zA-Z0-9._/-]*$ and rejects .. sequences (prevents command injection via git operations)
• File paths: Adapter layers validate cwd input — AdapterRejectedInput error for invalid working directories
• Hook responses: Standard { continue: true, suppressOutput: true } JSON response prevents hook output from leaking into IDE output
• JSON integrity: json-utils.ts refuses to overwrite corrupt JSON files — detection before write prevents silent data loss

Privacy

• <private>...</private> tags: Content wrapped in privacy tags is stripped before observation extraction
• Observer session isolation: Observer agent sessions are tracked separately (OBSERVER_SESSIONS_DIR) and filtered from user-facing queries
• Project exclusion: Configurable project exclusion prevents observations from specific directories

Network Exposure

The worker binds to localhost only — it is not accessible from other machines on the network. External access requires explicit port forwarding or reverse proxy configuration.

The only external network calls are:

1. AI provider API calls (Claude/Gemini/OpenRouter) for observation extraction
2. Telegram API calls (if configured)
3. GitHub API calls (viewer version check)

Warning

The worker's HTTP API has no authentication. Anyone with local access to the machine can query and modify observations. This is by design for single-user operation, but be aware in shared-machine scenarios.

8. Developer Internals

Repository Structure

claude-mem/
├── src/
│   ├── cli/
│   │   ├── adapters/          # IDE input normalization (claude-code, cursor, gemini-cli, raw, windsurf)
│   │   ├── handlers/          # 8 hook event handlers (context, session-init, observation, file-context, summarize, session-complete, user-message, file-edit)
│   │   └── claude-md-commands.ts  # CLAUDE.md generation/cleanup
│   ├── hooks/
│   │   └── hook-response.ts   # Standard hook response constant
│   ├── integrations/
│   │   └── opencode-plugin/   # OpenCode plugin entry point
│   ├── npx-cli/
│   │   ├── commands/          # install, runtime, uninstall, ide-detection
│   │   ├── utils/             # bun-resolver
│   │   └── index.ts           # CLI entry point
│   ├── sdk/
│   │   ├── parser.ts          # XML response parser (observation[], summary, invalid)
│   │   └── prompts.ts         # XML prompt builders (init, observation, summary, continuation)
│   ├── servers/
│   │   └── mcp-server.ts      # MCP server with 12+ tools
│   ├── services/
│   │   ├── context/           # ContextBuilder, ContextConfigLoader, ObservationCompiler, TokenCalculator
│   │   ├── domain/            # ModeManager
│   │   ├── infrastructure/    # WorktreeAdoption
│   │   ├── integrations/      # 7 IDE installers + TelegramNotifier + McpIntegrations
│   │   ├── server/            # Express Server base, ErrorHandler
│   │   ├── sqlite/            # Database, SessionStore, SessionSearch, PendingMessageStore, migrations
│   │   ├── sync/              # ChromaSync
│   │   ├── transcripts/       # TranscriptWatcher, TranscriptEventProcessor
│   │   ├── worker/            # Core worker: SDKAgent, GeminiAgent, OpenRouterAgent, SessionManager, SearchManager, etc.
│   │   └── worker-service.ts  # Worker lifecycle management (1365+ lines)
│   ├── shared/                # EnvManager, SettingsDefaultsManager, paths, worker-utils, hook-constants
│   ├── supervisor/            # ProcessRegistry, health-checker, env-sanitizer, shutdown
│   ├── types/                 # Shared type definitions
│   ├── ui/
│   │   └── viewer/            # React SPA (App.tsx, components, hooks, utils)
│   └── utils/                 # Logger, json-utils, cursor-utils, claude-md-utils
├── plugin/
│   ├── hooks/                 # hooks.json
│   ├── modes/                 # 35 JSON mode files
│   ├── scripts/               # worker-service.cjs, mcp-server.cjs, smart-install
│   ├── skills/                # 8 skills: pathfinder, timeline-report, version-bump, smart-explore, knowledge-agent, mem-search, make-plan, do
│   ├── ui/                    # Bundled viewer assets
│   └── .mcp.json              # MCP server declaration
├── openclaw/                  # @openclaw/claude-mem extension package
├── ragtime/                   # Ragtime transcript processor
├── cursor-hooks/              # Cursor-specific hook scripts
├── docker/claude-mem/         # Docker build/run scripts
├── evals/swebench/            # SWE-bench evaluation harness
├── scripts/                   # Build scripts, translation, bug-report tool
├── tests/                     # Comprehensive test suite
│   ├── cli/                   # Handler tests, adapter tests
│   ├── context/               # Context builder tests
│   ├── infrastructure/        # Plugin-disabled check
│   ├── integration/           # Integration tests
│   ├── sdk/                   # Parser tests
│   ├── server/                # Server tests
│   ├── services/              # SQLite, queue, sync tests
│   ├── shared/                # Settings, utils tests
│   ├── sqlite/                # Database tests
│   ├── supervisor/            # Supervisor tests
│   ├── utils/                 # Utility tests
│   └── worker/                # Worker tests (agents, routes, middleware, search)
├── docs/
│   ├── public/                # MDX documentation site
│   ├── i18n/                  # 31 language README translations
│   ├── reports/               # Bug investigation reports
│   └── context/               # Context documentation
├── install/                   # Installation page/assets
└── PATHFINDER-*/              # Architecture exploration documents

Module Deep-Dive: SDK Agent Pipeline

The SDK agent pipeline is the core observation extraction mechanism:

1. Prompt Construction (src/sdk/prompts.ts):

• buildInitPrompt(mode) — Initial system prompt establishing the observer role, XML output format, mode-specific type/concept definitions
• buildObservationPrompt(toolName, toolInput, toolResponse, mode) — Observation extraction prompt for a specific tool use
• buildSummaryPrompt(lastAssistantMessage, mode) — Session summary prompt
• buildContinuationPrompt(mode) — Continuation prompt when the agent needs to generate more observations

All prompts are mode-aware — the ModeManager loads the active mode's JSON file and injects customized placeholders, footer text, and language requirements.

2. Agent Execution:

Three agent implementations share the same XML observation format:

• SDKAgent — Uses @anthropic-ai/claude-agent-sdk's query() function to spawn a Claude subprocess. Event-driven (no polling). Managed by the ProcessRegistry.
• GeminiAgent — Direct REST calls to https://generativelanguage.googleapis.com/v1/models. Handles free-tier RPM limits per model.
• OpenRouterAgent — REST calls to https://openrouter.ai/api/v1/chat/completions. OpenAI-compatible message format. Default context limit: 20 messages / 100K estimated tokens.

3. Response Parsing (src/sdk/parser.ts):

parseAgentXml() returns a discriminated union:

• { kind: 'observation', observations: Observation[] } — One or more extracted observations
• { kind: 'summary', summary: SessionSummary } — Session progress summary
• { kind: 'invalid', reason: string } — Parse failure
• Handles <skip_summary/> as a first-class case (agent decided no summary needed)

4. Storage and Sync:

Parsed observations are:

1. Stored in SQLite via SessionStore.storeObservation()
2. Synced to Chroma via ChromaSync (if enabled)
3. SSE-broadcast to connected viewer clients

Module Deep-Dive: PendingMessageStore

The PendingMessageStore (src/services/sqlite/PendingMessageStore.ts) is the persistence layer for the observation queue:

Lifecycle:

1. enqueue() — INSERT OR IGNORE (tool_use_id UNIQUE constraint prevents duplicates)
2. claimNextMessage() — Atomic UPDATE ... WHERE id = (subselect) with worker PID stamping
3. confirmProcessed() — DELETE after successful storage
4. Self-healing: claimNextMessage reclaims rows where worker_pid NOT IN (live_pids)

Key design decisions:

• No timer-based reaping — liveness is checked at claim time, not by a background process
• PID-based crash detection — LiveWorkerPidsProvider returns the set of alive worker PIDs
• Idempotent enqueue — INSERT OR IGNORE on the (content_session_id, tool_use_id) UNIQUE index
• Max retries: 3 per message (configurable)
• Terminal states: failed (narrow: only processing rows), abandoned (wide: pending + processing)

Module Deep-Dive: Context Builder

The context system (src/services/context/) compresses observation history for injection:

• ContextBuilder — Orchestrator that queries SQLite and formats the timeline
• ContextConfigLoader — Loads settings with mode-based filtering (type/concept exclusions)
• ObservationCompiler — SQL query builder with:
  • Type filtering per mode config
  • Concept filtering
  • Multi-project support (main project + adopted worktree observations)
  • Date range filtering
• TokenCalculator — Computes read tokens vs. discovery tokens, savings percentage

Module Deep-Dive: Search Infrastructure

The search system uses a strategy pattern:

SearchManager (facade)
  └── SearchOrchestrator (strategy selection)
       ├── SQLiteSearchStrategy  — Filter-only queries
       ├── ChromaSearchStrategy  — Vector semantic search
       └── HybridSearchStrategy  — Filters + semantic ranking

Additional components:

• ResultFormatter — Consistent output formatting
• TimelineBuilder — Chronological timeline construction
• FormattingService — Table format matching context-generator style

Module Deep-Dive: IDE Integration Installers

Each supported IDE has a dedicated installer in src/services/integrations/:

Cursor specifics:

• Project registry at ~/.claude-mem/cursor-projects.json
• Auto-updates .cursor/rules after summary generation via updateCursorContextForProject()
• MCP server script at plugin/scripts/mcp-server.cjs
• Detects Bun executable across macOS, Linux, and Windows paths

Codex CLI specifics:

• Transcript-only approach — no hooks, watches ~/.codex/sessions/**/*.jsonl
• Merges watch config into ~/.claude-mem/transcript-watch.json (preserves other watches)
• Context via workspace-local AGENTS.md files
• Legacy global ~/.codex/AGENTS.md context is cleaned up on install

Code Patterns and Conventions

Module organization:

• Named re-export facades (e.g., Search.ts re-exports ./search/index.js)
• Route classes extend BaseRouteHandler
• Singleton patterns: Supervisor, DatabaseManager (legacy), Logger
• New code uses ClaudeMemDatabase class (deprecating singleton DatabaseManager)

Error handling:

• AppError extends Error with HTTP status codes
• asyncHandler wraps Express route handlers for promise rejection
• AdapterRejectedInput for invalid IDE input
• DryRunRollback for worktree adoption dry runs

TypeScript patterns:

• ESM modules ("type": "module")
• bun:sqlite for database access (Bun-specific)
• Zod 4 for runtime validation
• Discriminated unions for parse results
• Strict null checks

Build system:

• scripts/build-hooks.js — esbuild bundles for hooks
• scripts/sync-plugin-manifests.js — Syncs version across package.json files
• scripts/sync-marketplace.cjs — Copies plugin to marketplace directory
• esbuild for all bundling

Testing Strategy

Tests use Bun's built-in test runner (bun test):

bun test                    # All tests
bun test tests/sqlite/      # SQLite layer tests
bun test tests/worker/      # Worker tests
bun test tests/context/     # Context builder tests
bun test tests/server/      # Server tests
bun test tests/sdk/         # Parser tests

Test organization mirrors source structure:

• tests/cli/handlers/ — Hook handler tests
• tests/cli/adapters/ — IDE adapter tests
• tests/worker/agents/ — Agent tests
• tests/worker/search/ — Search strategy tests
• tests/worker/http/routes/ — HTTP route tests
• tests/worker/middleware/ — Middleware tests
• tests/sqlite/ — Database layer tests
• tests/services/sqlite/observations/ — Observation storage tests
• tests/services/queue/ — Queue tests
• tests/services/sync/ — Chroma sync tests
• tests/context/formatters/ — Context formatter tests
• tests/shared/ — Shared utility tests
• tests/infrastructure/ — Plugin state tests
• tests/supervisor/ — Supervisor tests

Type checking:

npm run typecheck          # Root + Viewer
npm run typecheck:root     # Root tsconfig only
npm run typecheck:viewer   # Viewer tsconfig only

Potential Improvements

Based on open GitHub issues and code patterns:

1. Windows reliability — Multiple open issues (#2109, #2111, #2114, #2123, #2131) around path handling, port management, and shell detection. A comprehensive Windows test suite would catch regressions.

2. Session timeout configurability — Currently hardcoded MAX_SESSION_WALL_CLOCK_MS at 4 hours (#2098, #2127). Should be exposed as a setting.

3. Chroma subprocess lifecycle — The MCP retry logic can spawn multiple Chroma subprocesses without killing previous ones (#2102). Needs proper subprocess lifecycle management.

4. Observer session isolation — Observer prompts leaking into user_prompts (#2104) and SSE events (#2118) indicate incomplete session boundary enforcement.

5. PreToolUse:Read hook timeout — The 2000-second timeout (#2100) should be reduced to prevent blocking the IDE when the worker hangs.

6. Environment variable filtering — Configurable whitelist requested (#2099) instead of the current blocklist approach, which can miss proxy variables (#2115).

7. Multi-account support — No built-in isolation for work/personal accounts (#2101). The current workaround (separate DATA_DIR) is manual.

9. Integration Points

MCP Server

The MCP server (src/servers/mcp-server.ts) exposes claude-mem's capabilities to any MCP-compatible client via stdio transport.

Server declaration (plugin/.mcp.json):

{
  "mcpServers": {
    "mcp-search": {
      "type": "stdio",
      "command": "bun",
      "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/mcp-server.cjs"]
    }
  }
}

Available tools:

Orphan detection: The MCP server uses a parent heartbeat mechanism to detect when the IDE process has died, allowing clean self-termination.

Worker HTTP API Reference

Complete API surface extracted from route definitions:

Health & Admin:

Data & Observations:

Search:

Context:

Sessions:

Settings & Configuration:

Memory:

Corpus:

Chroma:

Logs:

Viewer & SSE:

Transcript Watcher Integration

For IDEs without hook support, claude-mem offers transcript watching:

Configuration (~/.claude-mem/transcript-watch.json):

{
  "version": 1,
  "schemas": {
    "codex": { "version": 1, "format": "jsonl" }
  },
  "watches": [
    {
      "name": "codex",
      "glob": "~/.codex/sessions/**/*.jsonl",
      "schema": "codex"
    }
  ],
  "stateFile": "~/.claude-mem/transcript-watch-state.json"
}

Components:

• TranscriptWatcher — FileTailer that monitors glob patterns for new JSONL/JSON content
• TranscriptEventProcessor — Processes transcript events and maps them to observation ingestion
• Supports Codex CLI JSONL and Gemini CLI JSON formats

OpenClaw Extension

The openclaw/ directory contains a standalone extension package (@openclaw/claude-mem) that integrates with the OpenClaw platform:

• Communicates via SSE stream to the worker
• Runs as a private npm package
• Built and tested independently (tsc + node --test)

Plugin Skills

The plugin includes 8 skills in plugin/skills/:

Ragtime

The ragtime/ directory contains a transcript processor that:

• Reads from RAGTIME_CORPUS_PATH
• Connects to worker on CLAUDE_MEM_WORKER_PORT
• Processes transcripts with configurable max age, file limits, and session delays
• Supports mode-aware observation extraction

Troubleshooting (Admin)

Worker Won't Start

1. Check port availability:

   lsof -i :37777   # macOS/Linux
   netstat -an | grep 37777   # Windows
   

2. Check Bun installation: bun --version
3. Check logs: cat ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
4. Check PID file: cat ~/.claude-mem/worker.pid

Database Corruption

Symptoms: SQLITE_CORRUPT, SQLITE_NOTADB, unexpected query errors.

1. Stop the worker
2. Back up the database: cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.corrupt
3. Attempt recovery:

   sqlite3 ~/.claude-mem/claude-mem.db ".recover" | sqlite3 ~/.claude-mem/claude-mem-recovered.db
   

4. Replace the database and restart

SDK Agent Not Extracting Observations

1. Check provider credentials:
   • Claude: OAuth token valid? (~/.claude/.credentials.json)
   • Gemini: API key set? (CLAUDE_MEM_GEMINI_API_KEY)
   • OpenRouter: API key set? (CLAUDE_MEM_OPENROUTER_API_KEY)
2. Check process count: GET /api/processing-status
3. Check for hard cap: logs show "Hard cap exceeded" if at 10 processes
4. Check PendingMessage queue: npm run queue

Caution

If the SDK agent fails repeatedly, messages accumulate in the pending queue. The clearFailedOlderThan() method cleans up on restart, but a persistent failure (e.g., expired credentials) will keep generating failed messages. Fix the root cause before restarting.

High Memory Usage

1. Check Chroma: GET /api/chroma/status — disable if leaking (#2102)
2. Count SDK processes: check logs for ProcessRegistry spawn count
3. Check for restart loops: RestartGuard logs will show trip conditions
4. Consider reducing MAX_CONCURRENT (default context limit: 20 messages per agent)

Migration Failures

If a migration fails on startup:

1. Check the schema_versions table for the last successful version
2. Examine the migration runner logs
3. The migration runner is idempotent — restarting will retry failed migrations
4. In extreme cases, back up and recreate the database

Quick Reference

npm Scripts

npx CLI Commands

Key File Paths

Key Constants