# Antigravity CLI Setup
Source: https://docs.claude-mem.ai/antigravity-cli/setup

Add persistent memory to Antigravity CLI with claude-mem

# Antigravity CLI Setup

> **Give Antigravity CLI persistent memory across sessions.**

Antigravity CLI (`agy`) is Google's standalone successor to Gemini CLI — it reuses Gemini CLI's `~/.gemini/` config tree and, per Google, "keeps the most critical features of Gemini CLI: Agent Skills, Hooks, Subagents, and Extensions." Claude-mem changes what happens across sessions by capturing observations, decisions, and patterns — then injecting relevant context into each new session.

<Info>
  **How it works:** Claude-mem installs lifecycle hooks into Antigravity CLI's `~/.gemini/config/hooks.json` that capture tool usage, agent responses, and session events. A local worker service extracts semantic observations and injects relevant history at session start — via `GEMINI.md`, an MCP server, and a rules file.
</Info>

<Note>
  Antigravity CLI is a different product from the Antigravity **desktop IDE** (`antigravity` binary) — both share the same `~/.gemini/antigravity` namespace, but the CLI's own binary is `agy`. Detection checks for `agy` in your `PATH` (or an existing `~/.gemini/antigravity` directory).
</Note>

## Prerequisites

* [Antigravity CLI](https://github.com/google-antigravity/antigravity-cli) (`agy`) installed — `curl -fsSL https://antigravity.google/cli/install.sh | bash`
* [Node.js](https://nodejs.org/) 18+
* The `~/.gemini` directory must exist (created by Antigravity CLI / Gemini CLI on first run)

## Installation

### Step 1: Install claude-mem

```bash theme={null}
npx claude-mem install --ide antigravity
```

The installer will:

1. Auto-detect Antigravity CLI (checks for `agy` in `PATH`, or an existing `~/.gemini/antigravity` directory)
2. Install the Antigravity CLI lifecycle hooks into `~/.gemini/config/hooks.json`
3. Inject context configuration into `~/.gemini/GEMINI.md`
4. Register claude-mem's MCP server in `~/.gemini/antigravity/mcp_config.json` **and** `~/.gemini/config/mcp_config.json`
5. Write a rules/context placeholder to `~/.agents/rules/claude-mem-context.md`
6. Start the worker service

### Step 2: Configure an AI provider

Claude-mem needs an AI provider to extract observations from your sessions. Choose one:

<Tabs>
  <Tab title="Gemini API">
    The simplest option — use Gemini's own API for observation extraction:

    1. Create an API key in [Google AI Studio](https://aistudio.google.com/apikey)
    2. Add it to your settings:

    ```bash theme={null}
    mkdir -p ~/.claude-mem
    cat > ~/.claude-mem/settings.json << 'EOF'
    {
      "CLAUDE_MEM_PROVIDER": "gemini",
      "CLAUDE_MEM_GEMINI_API_KEY": "YOUR_API_KEY"
    }
    EOF
    ```

    <Tip>
      **No billing required:** You can create a Gemini API key without enabling billing. Enable billing for higher rate limits only after reviewing Google's current quota and billing terms.
    </Tip>
  </Tab>

  <Tab title="Claude SDK">
    If you have a Claude API key:

    ```bash theme={null}
    mkdir -p ~/.claude-mem
    cat > ~/.claude-mem/settings.json << 'EOF'
    {
      "CLAUDE_MEM_PROVIDER": "claude"
    }
    EOF
    ```

    Set your API key via environment variable:

    ```bash theme={null}
    export ANTHROPIC_API_KEY="your-key"
    ```
  </Tab>

  <Tab title="OpenRouter">
    For access to 100+ models:

    ```bash theme={null}
    mkdir -p ~/.claude-mem
    cat > ~/.claude-mem/settings.json << 'EOF'
    {
      "CLAUDE_MEM_PROVIDER": "openrouter",
      "CLAUDE_MEM_OPENROUTER_API_KEY": "YOUR_KEY"
    }
    EOF
    ```
  </Tab>
</Tabs>

### Step 3: Verify installation

```bash theme={null}
# Check worker is running
npx claude-mem status

# Check hooks are installed — look for claude-mem entries
cat ~/.gemini/config/hooks.json | grep claude-mem

# Check MCP registration in either candidate config path
cat ~/.gemini/antigravity/mcp_config.json | grep claude-mem
cat ~/.gemini/config/mcp_config.json | grep claude-mem
```

Open the worker URL printed on startup to see the memory viewer.

### Step 4: Start using Antigravity CLI

Launch Antigravity CLI normally. Claude-mem works in the background:

```bash theme={null}
agy
```

On session start, you'll see claude-mem context injected with your recent observations and project history.

## What gets captured

Claude-mem registers the five lifecycle hooks Antigravity CLI (`agy` 1.2.1) actually fires:

| Hook | Internal event | Purpose |
| - | - | - |
| **PreInvocation** | `context` | Injects memory context (via `injectSteps`) before the agent runs |
| **PreToolUse** | `observation` | Records tool intent, returns `{"decision":"allow"}` so the call proceeds |
| **PostToolUse** | `observation` | Captures tool results after execution |
| **PostInvocation** | `observation` | Records the agent's response (from the transcript's `PLANNER_RESPONSE` node) |
| **Stop** | `summarize` | Captures the session summary at turn/session end |

<Note>
  These are the real `agy` 1.2.1 event names. Earlier releases mistakenly registered Gemini CLI names (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeTool`, `AfterTool`) into `~/.gemini/settings.json` — none of which exist in the `agy` binary, so hooks never fired and no observations were recorded (issue [#4057](https://github.com/thedotmack/claude-mem/issues/4057)).
</Note>

## MCP registration

Antigravity CLI has native MCP support, but which config path it reads was genuinely ambiguous at the time of writing — two real candidate paths exist on disk with no definitive documentation resolving which one `agy` loads. Claude-mem writes to **both**, safely and idempotently:

* `~/.gemini/antigravity/mcp_config.json`
* `~/.gemini/config/mcp_config.json`

This gives claude-mem's search tools (`search`, `smart_search`, `timeline`, etc.) a chance to register correctly regardless of which path Antigravity CLI actually reads.

## Future enhancement (not implemented in this release)

Antigravity CLI ships a first-class plugin-marketplace subcommand system: `agy plugin {list,import,install,uninstall,enable,disable,validate,link}`. Notably, `agy plugin import gemini|claude` suggests native cross-tool plugin migration — structurally similar to Codex CLI's `.codex-plugin/plugin.json` marketplace mechanism. This could eventually be a cleaner, more idiomatic way to bundle claude-mem's hooks + MCP + skills registration than hand-editing `hooks.json`. It isn't implemented here because its manifest schema isn't discoverable without running `agy plugin import`/`install` against a real manifest, which would mutate a user's live local plugin state. Tracked as a candidate follow-up.

## Troubleshooting

### Hooks not firing

1. Verify hooks exist in the hooks config:
   ```bash theme={null}
   cat ~/.gemini/config/hooks.json
   ```
   Each top-level key is a **hook name**. claude-mem writes a single
   `"claude-mem"` key wrapping the event keys, with `PreToolUse`/`PostToolUse`
   using the grouped `{ "matcher", "hooks" }` shape and
   `PreInvocation`/`PostInvocation`/`Stop` using a flat array of handlers:
   ```json theme={null}
   {
     "claude-mem": {
       "PreInvocation": [ { "type": "command", "command": "...", "timeout": 30 } ],
       "PreToolUse": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "...", "timeout": 30 } ] } ],
       "PostToolUse": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "...", "timeout": 30 } ] } ],
       "PostInvocation": [ { "type": "command", "command": "...", "timeout": 30 } ],
       "Stop": [ { "type": "command", "command": "...", "timeout": 30 } ]
     }
   }
   ```
   `timeout` is in **seconds** (agy's default is 30). If you see event names at
   the top level, handlers tagged with `"name": "claude-mem"`, or
   `"timeout": 10000`, you are on a pre-fix install — re-run the installer
   below, which migrates the old layout automatically.

2. Restart Antigravity CLI after installation.

3. Re-run the installer:
   ```bash theme={null}
   npx claude-mem install --ide antigravity
   ```

### Worker not running

```bash theme={null}
# Check status
npx claude-mem status

# View logs
npx claude-mem logs

# Restart worker
npx claude-mem restart
```

### No context appearing at session start

1. Ensure the worker is running (`npm run worker:status`)
2. You need at least one previous session with observations for context to appear
3. Check your AI provider is configured in `~/.claude-mem/settings.json`

### Raw escape codes in output

If you see characters like `[31m` or `[0m` in the session context, your claude-mem version may need updating — the Antigravity CLI adapter strips ANSI color codes automatically:

```bash theme={null}
npx claude-mem install --ide antigravity
```

## Uninstalling

```bash theme={null}
npx claude-mem uninstall
```

This removes claude-mem's hooks from `~/.gemini/config/hooks.json` (and any legacy entries from `~/.gemini/settings.json`), cleans up the context section in `~/.gemini/GEMINI.md`, removes claude-mem's entry from both MCP config files, and removes the rules context section — while preserving everything else in those files.

## Next Steps

* [Gemini Provider](/usage/gemini-provider) — Configure the Gemini AI provider for observation extraction
* [Configuration](/configuration) — All settings options
* [Search Tools](/usage/search-tools) — Search your memory from within sessions
* [Troubleshooting](/troubleshooting) — Common issues and solutions


# Architecture Evolution
Source: https://docs.claude-mem.ai/architecture-evolution

How claude-mem evolved from v3 to v5+

# Architecture Evolution

## The Problem We Solved

**Goal:** Create a memory system that makes Claude smarter across sessions without the user noticing it exists.

**Challenge:** How do you observe AI agent behavior, compress it intelligently, and serve it back at the right time - all without slowing down or interfering with the main workflow?

This is the story of how claude-mem evolved from a simple idea to a production-ready system, and the key architectural decisions that made it work.

***

## v5.x: Maturity and User Experience

After establishing the solid v4 architecture, v5.x focused on user experience, visualization, and polish.

### v5.1.2: Theme Toggle (November 2025)

**What Changed**: Added light/dark mode theme toggle to viewer UI

**New Features**:

* User-selectable theme preference (light, dark, system)
* Persistent theme settings in localStorage
* Smooth theme transitions
* System preference detection

**Implementation**:

```typescript theme={null}
// Theme context with persistence
const ThemeProvider = ({ children }) => {
  const [theme, setTheme] = useState<'light' | 'dark' | 'system'>(() => {
    return localStorage.getItem('claude-mem-theme') || 'system';
  });

  useEffect(() => {
    localStorage.setItem('claude-mem-theme', theme);
  }, [theme]);

  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  );
};
```

**Why It Matters**: Users working in different lighting conditions can now customize the viewer for comfort.

### v5.1.1: Worker Startup Fix (November 2025) - Now Deprecated

**Note**: This section describes a historical PM2-based approach that has been replaced with Bun in later versions.

**The Problem**: Worker startup failed on Windows with ENOENT error when using PM2

**Historical Solution**: Used full path to PM2 binary instead of relying on PATH

**Current Approach**: The project now uses Bun for process management, which provides better cross-platform compatibility and eliminates these PATH-related issues.

**Impact**: Cross-platform compatibility restored, Windows users can now use claude-mem without issues.

### v5.1.0: Web-Based Viewer UI (October 2025)

**The Breakthrough**: Real-time visualization of memory stream

**What We Built**:

* React-based web UI at [http://localhost:37777](http://localhost:37777)
* Server-Sent Events (SSE) for real-time updates
* Infinite scroll pagination
* Project filtering
* Settings persistence (sidebar state, selected project)
* Auto-reconnection with exponential backoff
* GPU-accelerated animations

**New Worker Endpoints** (8 additions):

```
GET /                    # Serves viewer HTML
GET /stream              # SSE real-time updates
GET /api/prompts         # Paginated user prompts
GET /api/observations    # Paginated observations
GET /api/summaries       # Paginated session summaries
GET /api/stats           # Database statistics
GET /api/settings        # User settings
POST /api/settings       # Save settings
```

**Database Enhancements**: SessionStore gained paginated queries for recent prompts, observations, and summaries (filterable by project), plus database stats and project listing to back the viewer endpoints. (These viewer-specific methods were later replaced by the unified search layer.)

**React Architecture**:

```
src/ui/viewer/
├── components/
│   ├── Header.tsx          # Navigation + stats
│   ├── Sidebar.tsx         # Project filter
│   ├── Feed.tsx            # Infinite scroll
│   └── cards/
│       ├── ObservationCard.tsx
│       ├── PromptCard.tsx
│       ├── SummaryCard.tsx
│       └── SkeletonCard.tsx
├── hooks/
│   ├── useSSE.ts           # Real-time events
│   ├── usePagination.ts    # Infinite scroll
│   ├── useSettings.ts      # Persistence
│   └── useStats.ts         # Statistics
└── utils/
    ├── merge.ts            # Data deduplication
    └── format.ts           # Display formatting
```

**Build Process**:

```typescript theme={null}
// esbuild bundles everything into single HTML file
esbuild.build({
  entryPoints: ['src/ui/viewer/index.tsx'],
  bundle: true,
  outfile: 'plugin/ui/viewer.html',
  loader: { '.tsx': 'tsx', '.woff2': 'dataurl' },
  define: { 'process.env.NODE_ENV': '"production"' },
});
```

**Why It Matters**: Users can now see exactly what's being captured in real-time, making the memory system transparent and debuggable.

### v5.0.3: Smart Install Caching (October 2025)

**The Problem**: `npm install` ran on every SessionStart (2-5 seconds)

**The Insight**: Dependencies rarely change between sessions

**The Solution**: Version-based caching

```typescript theme={null}
// Check version marker before installing
const currentVersion = getPackageVersion();
const installedVersion = readFileSync('.install-version', 'utf-8');

if (currentVersion !== installedVersion) {
  // Only install if version changed
  await runNpmInstall();
  writeFileSync('.install-version', currentVersion);
}
```

**Cached Check Logic**:

1. Does `node_modules` exist?
2. Does `.install-version` match `package.json` version?
3. Is `better-sqlite3` present? (Legacy: now uses bun:sqlite which requires no installation)

**Impact**:

* SessionStart hook: 2-5 seconds → 10ms (99.5% faster)
* Only installs on: first run, version change, missing deps
* Better Windows error messages with build tool help

### v5.0.2: Worker Health Checks (October 2025)

**What Changed**: More robust worker startup and monitoring

**New Features**:

```typescript theme={null}
// Health check endpoint
app.get('/health', (req, res) => {
  res.json({
    status: 'ok',
    uptime: process.uptime(),
    port: WORKER_PORT,
    memory: process.memoryUsage(),
  });
});

// Smart worker startup
async function ensureWorkerHealthy() {
  const healthy = await isWorkerHealthy(1000);
  if (!healthy) {
    await startWorker();
    await waitForWorkerHealth(10000);
  }
}
```

**Benefits**:

* Graceful degradation when worker is down
* Auto-recovery from crashes
* Better error messages for debugging

### v5.0.1: Stability Improvements (October 2025)

**What Changed**: Various bug fixes and stability enhancements

**Key Fixes**:

* Fixed race conditions in observation queue processing
* Improved error handling in SDK worker
* Better cleanup of stale worker processes
* Enhanced logging for debugging

### v5.0.0: Hybrid Search Architecture (October 2025)

**The Evolution**: SQLite FTS5 + Chroma vector search

**What We Added**:

```
┌─────────────────────────────────────────────────────────┐
│                    HYBRID SEARCH                         │
│                                                          │
│  Text Query → SQLite FTS5 (keyword matching)            │
│                      ↓                                   │
│            Chroma Vector Search (semantic)               │
│                      ↓                                   │
│              Merge + Re-rank Results                     │
└─────────────────────────────────────────────────────────┘
```

**New Dependencies**:

* `chromadb` - Vector database for semantic search
* Python 3.8+ - Required by chromadb

**MCP Tools Enhancement**:

```typescript theme={null}
// Chroma-backed semantic search
search_observations({
  query: "authentication bug",
  useSemanticSearch: true  // Uses Chroma
});

// Falls back to FTS5 if Chroma unavailable
```

**Why Hybrid**:

* FTS5: Fast keyword matching, no dependencies
* Chroma: Semantic understanding, finds related concepts
* Graceful degradation: Works without Chroma (FTS5 only)

**Trade-offs**:

* Added Python dependency (optional)
* Increased installation complexity
* Better search relevance

***

## MCP Architecture Simplification (December 2025)

### The Problem: Complex MCP Implementation

**Before:**

```
9+ MCP tools registered at session start:
- search_observations
- find_by_type
- find_by_file
- find_by_concept
- get_recent_context
- get_observation
- get_session
- get_prompt
- help

Problems:
- Overlapping operations (search_observations vs find_by_type)
- Complex parameter schemas (~2,500 tokens in tool definitions)
- No built-in workflow guidance
- High cognitive load for Claude (which tool to use?)
- Code size: ~2,718 lines in mcp-server.ts
```

**The Insight:** Progressive disclosure should be built into tool design itself, not something Claude has to remember.

### The Solution: 3-Layer Workflow

**After:**

```
4 MCP tools following 3-layer workflow:

1. important_workflow - Workflow documentation (always visible)
   "3-LAYER WORKFLOW (ALWAYS FOLLOW):
    1. search(query) → Get index with IDs
    2. timeline(anchor=ID) → Get context
    3. get_observations([IDs]) → Fetch details
    NEVER fetch full details without filtering first."

2. search - Layer 1: Get index with IDs (~50-100 tokens/result)
3. timeline - Layer 2: Get chronological context
4. get_observations - Layer 3: Fetch full details (~500-1,000 tokens/result)

Benefits:
- Progressive disclosure enforced by tool structure
- No overlapping operations
- Simple schemas (additionalProperties: true)
- Clear workflow pattern
- Code size: ~312 lines in mcp-server.ts (88% reduction)
- ~10x token savings
```

### Migration: Skill-Based Search Removed

**Previously:** Used skill-based search

* mem-search skill invoked via natural language
* HTTP API called directly via curl
* Progressive disclosure through skill loading
* 17 skill documentation files

**Now:** Removed skill-based approach

* MCP-only architecture
* Native MCP protocol (better Claude integration)
* Works with both Claude Desktop and Claude Code
* Simpler to maintain (no skill files)
* All 19 mem-search skill files removed (\~2,744 lines)

### Key Architectural Changes

**MCP Server Refactor:**

Before:

```typescript theme={null}
// Complex parameter schemas
{
  name: "search_observations",
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string", description: "..." },
      type: { type: "array", items: { enum: [...] } },
      format: { enum: ["index", "full"] },
      limit: { type: "number", minimum: 1, maximum: 100 },
      // ... many more parameters
    }
  }
}
```

After:

```typescript theme={null}
// Simple schemas with workflow guidance
{
  name: "search",
  description: "Step 1: Search memory. Returns index with IDs.",
  inputSchema: {
    type: "object",
    properties: {},
    additionalProperties: true  // Accept any parameters
  }
}
```

**Workflow Enforcement:**

Before: Claude had to remember progressive disclosure pattern

After: Tool structure makes it impossible to skip steps

* Can't get details without IDs from search
* Can't search without seeing important\_workflow reminder
* Timeline provides middle ground (context without full details)

### Impact

**Token Efficiency:**

```
Traditional: Fetch 20 observations upfront
→ 10,000-20,000 tokens
→ Only 2 observations relevant (90% waste)

3-Layer Workflow:
→ search (20 results): ~1,000-2,000 tokens
→ Review index, identify 3 relevant IDs
→ get_observations (3 IDs): ~1,500-3,000 tokens
→ Total: 2,500-5,000 tokens (50-75% savings)
```

**Code Simplicity:**

* MCP server: 2,718 lines → 312 lines (88% reduction)
* Removed: 19 skill files (\~2,744 lines)
* Net reduction: \~5,150 lines of code removed

**User Experience:**

* Same natural language interaction
* Better token efficiency
* Clearer architecture
* Works identically on Claude Desktop and Claude Code

### Design Philosophy

**Progressive Disclosure Through Structure:**

The 3-layer workflow embodies progressive disclosure at the architectural level:

1. **Layer 1 (Index)** - "What exists?" - Cheap survey of options
2. **Layer 2 (Timeline)** - "What was happening?" - Context around specific points
3. **Layer 3 (Details)** - "Tell me everything" - Full details only when justified

Each layer provides a decision point where Claude can:

* Stop if irrelevant
* Get more context if uncertain
* Dive deep if confident

This makes it structurally difficult to waste tokens.

***

## v1-v2: The Naive Approach

### The First Attempt: Dump Everything

**Architecture:**

```
PostToolUse Hook → Save raw tool outputs → Retrieve everything on startup
```

**What we learned:**

* ❌ Context pollution (thousands of tokens of irrelevant data)
* ❌ No compression (raw tool outputs are verbose)
* ❌ No search (had to scan everything linearly)
* ✅ Proved the concept: Memory across sessions is valuable

**Example of what went wrong:**

```
SessionStart loaded:
- 150 file read operations
- 80 grep searches
- 45 bash commands
- Total: ~35,000 tokens
- Relevant to current task: ~500 tokens (1.4%)
```

***

## v3: Smart Compression, Wrong Architecture

### The Breakthrough: AI-Powered Compression

**New idea:** Use Claude itself to compress observations

**Architecture:**

```
PostToolUse Hook → Queue observation → SDK Worker → AI compression → Store insights
```

**What we added:**

1. **Claude Agent SDK integration** - Use AI to compress observations
2. **Background worker** - Don't block main session
3. **Structured observations** - Extract facts, decisions, insights
4. **Session summaries** - Generate comprehensive summaries

**What worked:**

* ✅ Compression ratio: 10:1 to 100:1
* ✅ Semantic understanding (not just keyword matching)
* ✅ Background processing (hooks stayed fast)
* ✅ Search became useful

**What didn't work:**

* ❌ Still loaded everything upfront
* ❌ Session ID management was broken
* ❌ Aggressive cleanup interrupted summaries
* ❌ Multiple SDK sessions per Claude Code session

***

## The Key Realizations

### Realization 1: Progressive Disclosure

**Problem:** Even compressed observations can pollute context if you load them all.

**Insight:** Humans don't read everything before starting work. Why should AI?

**Solution:** Show an index first, fetch details on-demand.

```
❌ Old: Load 50 observations (8,500 tokens)
✅ New: Show index of 50 observations (800 tokens)
        Agent fetches 2-3 relevant ones (300 tokens)
        Total: 1,100 tokens vs 8,500 tokens
```

**Impact:**

* 87% reduction in context usage
* 100% relevance (only fetch what's needed)
* Agent autonomy (decides what's relevant)

### Realization 2: Session ID Chaos

**Problem:** SDK session IDs change on every turn.

**What we thought:**

```typescript theme={null}
// ❌ Wrong assumption
UserPromptSubmit → Capture session ID once → Use forever
```

**Reality:**

```typescript theme={null}
// ✅ Actual behavior
Turn 1: session_abc123
Turn 2: session_def456
Turn 3: session_ghi789
```

**Why this matters:**

* Can't resume sessions without tracking ID updates
* Session state gets lost between turns
* Observations get orphaned

**Solution:**

```typescript theme={null}
// Capture from system init message
for await (const msg of response) {
  if (msg.type === 'system' && msg.subtype === 'init') {
    sdkSessionId = msg.session_id;
    await updateSessionId(sessionId, sdkSessionId);
  }
}
```

### Realization 3: Graceful vs Aggressive Cleanup

**v3 approach:**

```typescript theme={null}
// ❌ Aggressive: Kill worker immediately
SessionEnd → DELETE /worker/session → Worker stops
```

**Problems:**

* Summary generation interrupted mid-process
* Pending observations lost
* Race conditions everywhere

**v4 approach:**

```typescript theme={null}
// ✅ Graceful: Let worker finish
SessionEnd → Mark session complete → Worker finishes → Exit naturally
```

**Benefits:**

* Summaries complete successfully
* No lost observations
* Clean state transitions

**Code:**

```typescript theme={null}
// v3: Aggressive
async function sessionEnd(sessionId: string) {
  await fetch(`http://localhost:37777/sessions/${sessionId}`, {
    method: 'DELETE'
  });
}

// v4: Graceful
async function sessionEnd(sessionId: string) {
  await db.run(
    'UPDATE sdk_sessions SET completed_at = ? WHERE id = ?',
    [Date.now(), sessionId]
  );
}
```

### Realization 4: One Session, Not Many

**Problem:** We were creating multiple SDK sessions per Claude Code session.

**What we thought:**

```
Claude Code session → Create SDK session per observation → 100+ SDK sessions
```

**Reality should be:**

```
Claude Code session → ONE long-running SDK session → Streaming input
```

**Why this matters:**

* SDK maintains conversation state
* Context accumulates naturally
* Much more efficient

**Implementation:**

```typescript theme={null}
// ✅ Streaming Input Mode
async function* messageGenerator(): AsyncIterable<UserMessage> {
  // Initial prompt
  yield {
    role: "user",
    content: "You are a memory assistant..."
  };

  // Then continuously yield observations
  while (session.status === 'active') {
    const observations = await pollQueue();
    for (const obs of observations) {
      yield {
        role: "user",
        content: formatObservation(obs)
      };
    }
    await sleep(1000);
  }
}

const response = query({
  prompt: messageGenerator(),
  options: { maxTurns: 1000 }
});
```

***

## v4: The Architecture That Works

### The Core Design

```
┌─────────────────────────────────────────────────────────┐
│              CLAUDE CODE SESSION                         │
│  User → Claude → Tools (Read, Edit, Write, Bash)        │
│                    ↓                                     │
│              PostToolUse Hook                            │
│              (queues observation)                        │
└─────────────────────────────────────────────────────────┘
                     ↓ SQLite queue
┌─────────────────────────────────────────────────────────┐
│              SDK WORKER PROCESS                          │
│  ONE streaming session per Claude Code session          │
│                                                          │
│  AsyncIterable<UserMessage>                             │
│    → Yields observations from queue                     │
│    → SDK compresses via AI                              │
│    → Parses XML responses                               │
│    → Stores in database                                 │
└─────────────────────────────────────────────────────────┘
                     ↓ SQLite storage
┌─────────────────────────────────────────────────────────┐
│              NEXT SESSION                                │
│  SessionStart Hook                                       │
│    → Queries database                                    │
│    → Returns progressive disclosure index               │
│    → Agent fetches details via MCP                      │
└─────────────────────────────────────────────────────────┘
```

### The Five Hook Architecture

<Tabs>
  <Tab title="SessionStart">
    **Purpose:** Inject context from previous sessions

    **Timing:** When Claude Code starts

    **What it does:**

    * Queries last 10 session summaries
    * Formats as progressive disclosure index
    * Injects into context via stdout

    **Key change from v3:**

    * ✅ Index format (not full details)
    * ✅ Token counts visible
    * ✅ MCP search instructions included
  </Tab>

  <Tab title="UserPromptSubmit">
    **Purpose:** Initialize session tracking

    **Timing:** Before Claude processes prompt

    **What it does:**

    * Creates session record
    * Saves raw user prompt (v4.2.0+)
    * Starts worker if needed

    **Key change from v3:**

    * ✅ Stores raw prompts for search
    * ✅ Auto-starts worker service
  </Tab>

  <Tab title="PostToolUse">
    **Purpose:** Capture tool observations

    **Timing:** After every tool execution

    **What it does:**

    * Enqueues observation in database
    * Returns immediately

    **Key change from v3:**

    * ✅ Just enqueues (doesn't process)
    * ✅ Worker handles all AI calls
  </Tab>

  <Tab title="Summary">
    **Purpose:** Generate session summaries

    **Timing:** Worker-triggered (mid-session)

    **What it does:**

    * Gathers observations
    * Sends to Claude for summarization
    * Stores structured summary

    **Key change from v3:**

    * ✅ Multiple summaries per session
    * ✅ Summaries are checkpoints, not endings
  </Tab>

  <Tab title="SessionEnd">
    **Purpose:** Graceful cleanup

    **Timing:** When session ends

    **What it does:**

    * Marks session complete
    * Lets worker finish processing

    **Key change from v3:**

    * ✅ Graceful (not aggressive)
    * ✅ No DELETE requests
    * ✅ Worker finishes naturally
  </Tab>
</Tabs>

### Database Schema Evolution

**v3 schema:**

```sql theme={null}
-- Simple, flat structure
CREATE TABLE observations (
  id INTEGER PRIMARY KEY,
  session_id TEXT,
  text TEXT,
  created_at INTEGER
);
```

**v4 schema:**

```sql theme={null}
-- Rich, structured schema
CREATE TABLE observations (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  session_id TEXT NOT NULL,
  project TEXT NOT NULL,

  -- Progressive disclosure metadata
  title TEXT NOT NULL,
  subtitle TEXT,
  type TEXT NOT NULL,  -- decision, bugfix, feature, etc.

  -- Content
  narrative TEXT NOT NULL,
  facts TEXT,  -- JSON array

  -- Searchability
  concepts TEXT,  -- JSON array of tags
  files_read TEXT,  -- JSON array
  files_modified TEXT,  -- JSON array

  -- Timestamps
  created_at TEXT NOT NULL,
  created_at_epoch INTEGER NOT NULL,

  FOREIGN KEY(session_id) REFERENCES sdk_sessions(id)
);

-- FTS5 for full-text search
CREATE VIRTUAL TABLE observations_fts USING fts5(
  title, subtitle, narrative, facts, concepts,
  content=observations
);

-- Auto-sync triggers
CREATE TRIGGER observations_ai AFTER INSERT ON observations BEGIN
  INSERT INTO observations_fts(rowid, title, subtitle, narrative, facts, concepts)
  VALUES (new.id, new.title, new.subtitle, new.narrative, new.facts, new.concepts);
END;
```

**What changed:**

* ✅ Structured fields (title, subtitle, type)
* ✅ FTS5 full-text search
* ✅ Project-scoped queries
* ✅ Rich metadata for progressive disclosure

### Worker Service Redesign

**v3 worker:**

```typescript theme={null}
// Multiple short SDK sessions
app.post('/process', async (req, res) => {
  const response = await query({
    prompt: buildPrompt(req.body),
    options: { maxTurns: 1 }
  });

  for await (const msg of response) {
    // Process single observation
  }

  res.json({ success: true });
});
```

**v4 worker:**

```typescript theme={null}
// ONE long-running SDK session
async function runWorker(sessionId: string) {
  const response = query({
    prompt: messageGenerator(),  // AsyncIterable
    options: { maxTurns: 1000 }
  });

  for await (const msg of response) {
    if (msg.type === 'text') {
      parseObservations(msg.content);
      parseSummaries(msg.content);
    }
  }
}
```

**Benefits:**

* Maintains conversation state
* SDK handles context automatically
* More efficient (fewer API calls)
* Natural multi-turn flow

***

## Critical Fixes Along the Way

### Fix 1: Context Injection Pollution (v4.3.1)

**Problem:** SessionStart hook output polluted with npm install logs

```bash theme={null}
# Hook output contained:
npm WARN deprecated ...
npm WARN deprecated ...
{"hookSpecificOutput": {"additionalContext": "..."}}
```

**Why it broke:**

* Claude Code expects clean JSON or plain text
* stderr/stdout from npm install mixed with hook output
* Context didn't inject properly

**Solution:**

```json theme={null}
{
  "command": "npm install --loglevel=silent && node context-hook.js"
}
```

**Result:** Clean JSON output, context injection works

### Fix 2: Double Shebang Issue (v4.3.1)

**Problem:** Hook executables had duplicate shebangs

```javascript theme={null}
#!/usr/bin/env node
#!/usr/bin/env node  // ← Duplicate!

// Rest of code...
```

**Why it happened:**

* Source files had shebang
* esbuild added another shebang during build

**Solution:**

```typescript theme={null}
// Remove shebangs from source files
// Let esbuild add them during build
```

**Result:** Clean executables, no parsing errors

### Fix 3: FTS5 Injection Vulnerability (v4.2.3)

**Problem:** User input passed directly to FTS5 query

```typescript theme={null}
// ❌ Vulnerable
const results = db.query(
  `SELECT * FROM observations_fts WHERE observations_fts MATCH '${userQuery}'`
);
```

**Attack:**

```typescript theme={null}
userQuery = "'; DROP TABLE observations; --"
```

**Solution:**

```typescript theme={null}
// ✅ Safe: Use parameterized queries
const results = db.query(
  'SELECT * FROM observations_fts WHERE observations_fts MATCH ?',
  [userQuery]
);
```

### Fix 4: NOT NULL Constraint Violation (v4.2.8)

**Problem:** Session creation failed when prompt was empty

```sql theme={null}
INSERT INTO sdk_sessions (claude_session_id, user_prompt, ...)
VALUES ('abc123', NULL, ...)  -- ❌ user_prompt is NOT NULL
```

**Solution:**

```typescript theme={null}
// Allow NULL user_prompts
user_prompt: input.prompt ?? null
```

**Schema change:**

```sql theme={null}
-- Before
user_prompt TEXT NOT NULL

-- After
user_prompt TEXT  -- Nullable
```

***

## Performance Improvements

### Optimization 1: Prepared Statements

**Before:**

```typescript theme={null}
for (const obs of observations) {
  db.run(`INSERT INTO observations (...) VALUES (?, ?, ...)`, [obs.id, obs.text, ...]);
}
```

**After:**

```typescript theme={null}
const stmt = db.prepare(`INSERT INTO observations (...) VALUES (?, ?, ...)`);
for (const obs of observations) {
  stmt.run([obs.id, obs.text, ...]);
}
stmt.finalize();
```

**Impact:** 5x faster bulk inserts

### Optimization 2: FTS5 Indexing

**Before:**

```typescript theme={null}
// Manual full-text search
const results = db.query(
  `SELECT * FROM observations WHERE text LIKE '%${query}%'`
);
```

**After:**

```typescript theme={null}
// FTS5 virtual table
const results = db.query(
  `SELECT * FROM observations_fts WHERE observations_fts MATCH ?`,
  [query]
);
```

**Impact:** 100x faster searches on large datasets

### Optimization 3: Index Format Default

**Before:**

```typescript theme={null}
// Always return full observations
search_observations({ query: "hooks" });
// Returns: 5,000 tokens
```

**After:**

```typescript theme={null}
// Default to index format
search_observations({ query: "hooks", format: "index" });
// Returns: 200 tokens

// Fetch full only when needed
search_observations({ query: "hooks", format: "full", limit: 1 });
// Returns: 150 tokens
```

**Impact:** 25x reduction in average search result size

***

## What We Learned

### Lesson 1: Context is Precious

**Principle:** Every token you put in context window costs attention.

**Application:**

* Progressive disclosure reduces waste by 87%
* Index-first approach gives agent control
* Token counts make costs visible

### Lesson 2: Session State is Complicated

**Principle:** Distributed state is hard. SDK handles it better than we can.

**Application:**

* Use SDK's built-in session resumption
* Don't try to manually reconstruct state
* Track session IDs from init messages

### Lesson 3: Graceful Beats Aggressive

**Principle:** Let processes finish their work before terminating.

**Application:**

* Graceful cleanup prevents data loss
* Workers finish important operations
* Clean state transitions reduce bugs

### Lesson 4: AI is the Compressor

**Principle:** Don't compress manually. Let AI do semantic compression.

**Application:**

* 10:1 to 100:1 compression ratios
* Semantic understanding, not keyword extraction
* Structured outputs (XML parsing)

### Lesson 5: Progressive Everything

**Principle:** Show metadata first, fetch details on-demand.

**Application:**

* Progressive disclosure in context injection
* Index format in search results
* Layer 1 (titles) → Layer 2 (summaries) → Layer 3 (full details)

***

## The Road Ahead

### Planned: Adaptive Index Size

```typescript theme={null}
SessionStart({ source: "startup" }):
  → Show last 10 sessions (normal)

SessionStart({ source: "resume" }):
  → Show only current session (minimal)

SessionStart({ source: "compact" }):
  → Show last 20 sessions (comprehensive)
```

### Planned: Relevance Scoring

```typescript theme={null}
// Use embeddings to pre-sort index by semantic relevance
search_observations({
  query: "authentication bug",
  sort: "relevance"  // Based on embeddings
});
```

### Planned: Multi-Project Context

```typescript theme={null}
// Cross-project pattern recognition
search_observations({
  query: "API rate limiting",
  projects: ["api-gateway", "user-service", "billing-service"]
});
```

### Planned: Collaborative Memory

```typescript theme={null}
// Team-shared observations (optional)
createObservation({
  title: "Rate limit: 100 req/min",
  scope: "team"  // vs "user"
});
```

***

## Migration Guide: v3 → v5

### Step 1: Backup Database

```bash theme={null}
cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem-v3-backup.db
```

### Step 2: Update Plugin

```bash theme={null}
cd ~/.claude/plugins/marketplaces/thedotmack
git pull
```

### Step 3: Update Plugin

```bash theme={null}
/plugin update claude-mem
```

**What happens automatically:**

* Dependencies update (including new ones like chromadb for v5.0.0+)
* Database schema migrations run automatically
* Worker service restarts with new code
* Smart install caching activates (v5.0.3+)

### Step 4: Test

```bash theme={null}
# Start Claude Code
claude

# Check that context is injected
# (Should see progressive disclosure index with v5 viewer link)

# Open viewer UI (v5.1.0+)
open http://localhost:37777

# Submit a prompt and watch real-time updates in viewer
```

### Step 5: Explore New Features

```bash theme={null}
# View memory stream in browser (v5.1.0+)
open http://localhost:37777

# Toggle theme (v5.1.2+)
# Click theme button in viewer header

# Check worker health
npm run worker:status
curl http://localhost:37777/health
```

***

## Key Metrics

### v3 Performance

| Metric | Value |
| - | - |
| Context usage per session | \~25,000 tokens |
| Relevant context | \~2,000 tokens (8%) |
| Hook execution time | \~200ms |
| Search latency | \~500ms (LIKE queries) |

### v4 Performance

| Metric | Value |
| - | - |
| Context usage per session | \~1,100 tokens |
| Relevant context | \~1,100 tokens (100%) |
| Hook execution time | \~45ms |
| Search latency | \~15ms (FTS5) |

### v5 Performance

| Metric | Value |
| - | - |
| Context usage per session | \~1,100 tokens |
| Relevant context | \~1,100 tokens (100%) |
| Hook execution time | \~10ms (cached install) |
| Search latency | \~12ms (FTS5) or \~25ms (hybrid) |
| Viewer UI load time | \~50ms (bundled HTML) |
| SSE update latency | \~5ms (real-time) |

**v3 → v4 Improvements:**

* 96% reduction in context waste
* 12x increase in relevance
* 4x faster hooks
* 33x faster search

**v4 → v5 Improvements:**

* 78% faster hooks (smart caching)
* Real-time visualization (viewer UI)
* Better search relevance (hybrid)
* Enhanced UX (theme toggle, persistence)

***

## Conclusion

The journey from v3 to v5 was about understanding these fundamental truths:

1. **Context is finite** - Progressive disclosure respects attention budget
2. **AI is the compressor** - Semantic understanding beats keyword extraction
3. **Agents are smart** - Let them decide what to fetch
4. **State is hard** - Use SDK's built-in mechanisms
5. **Graceful wins** - Let processes finish cleanly

The result is a memory system that's both powerful and invisible. Users never notice it working - Claude just gets smarter over time.

**v5 adds visibility**: Now users CAN see the memory system working if they want (via viewer UI), but it's still non-intrusive.

***

## Further Reading

* [Progressive Disclosure](progressive-disclosure) - The philosophy behind v4
* [Hooks Architecture](hooks-architecture) - How hooks power the system
* [Context Engineering](context-engineering) - Foundational principles
* [Worker Service](/architecture/worker-service) - Real-time visualization (v5.1.0+)

***

*This architecture evolution reflects hundreds of hours of experimentation, dozens of dead ends, and the invaluable experience of real-world usage. v5 is the architecture that emerged from understanding what actually works - and making it visible to users.*


# Database Architecture
Source: https://docs.claude-mem.ai/architecture/database

SQLite schema, FTS5 search, and data storage

# Database Architecture

Claude-Mem uses SQLite 3 with the bun:sqlite native module for persistent storage and FTS5 for full-text search.

## Database Location

**Path**: `~/.claude-mem/claude-mem.db`

The database uses SQLite's WAL (Write-Ahead Logging) mode for concurrent reads/writes.

## Database Implementation

**Primary Implementation**: bun:sqlite (native SQLite module)

* Used by: SessionStore and SessionSearch
* Format: Synchronous API with better performance
* **Note**: Database.ts (using bun:sqlite) is legacy code

## Core Tables

### 1. sdk\_sessions

Tracks active and completed sessions.

```sql theme={null}
CREATE TABLE sdk_sessions (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  sdk_session_id TEXT UNIQUE NOT NULL,
  claude_session_id TEXT,
  project TEXT NOT NULL,
  prompt_counter INTEGER DEFAULT 0,
  status TEXT NOT NULL DEFAULT 'active',
  created_at TEXT NOT NULL,
  created_at_epoch INTEGER NOT NULL,
  completed_at TEXT,
  completed_at_epoch INTEGER,
  last_activity_at TEXT,
  last_activity_epoch INTEGER
);
```

**Indexes**:

* `idx_sdk_sessions_claude_session` on `claude_session_id`
* `idx_sdk_sessions_project` on `project`
* `idx_sdk_sessions_status` on `status`
* `idx_sdk_sessions_created_at` on `created_at_epoch DESC`

### 2. observations

Individual tool executions with hierarchical structure.

```sql theme={null}
CREATE TABLE observations (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  session_id TEXT NOT NULL,
  sdk_session_id TEXT NOT NULL,
  claude_session_id TEXT,
  project TEXT NOT NULL,
  prompt_number INTEGER,
  tool_name TEXT NOT NULL,
  correlation_id TEXT,

  -- Hierarchical fields
  title TEXT,
  subtitle TEXT,
  narrative TEXT,
  text TEXT,
  facts TEXT,
  concepts TEXT,
  type TEXT,
  files_read TEXT,
  files_modified TEXT,

  created_at TEXT NOT NULL,
  created_at_epoch INTEGER NOT NULL,

  FOREIGN KEY (sdk_session_id) REFERENCES sdk_sessions(sdk_session_id)
);
```

**Observation Types**:

* `decision` - Architectural or design decisions
* `bugfix` - Bug fixes and corrections
* `feature` - New features or capabilities
* `refactor` - Code refactoring and cleanup
* `discovery` - Learnings about the codebase
* `change` - General changes and modifications

**Indexes**:

* `idx_observations_session` on `session_id`
* `idx_observations_sdk_session` on `sdk_session_id`
* `idx_observations_project` on `project`
* `idx_observations_tool_name` on `tool_name`
* `idx_observations_created_at` on `created_at_epoch DESC`
* `idx_observations_type` on `type`

### 3. session\_summaries

AI-generated session summaries (multiple per session).

```sql theme={null}
CREATE TABLE session_summaries (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  sdk_session_id TEXT NOT NULL,
  claude_session_id TEXT,
  project TEXT NOT NULL,
  prompt_number INTEGER,

  -- Summary fields
  request TEXT,
  investigated TEXT,
  learned TEXT,
  completed TEXT,
  next_steps TEXT,
  notes TEXT,

  created_at TEXT NOT NULL,
  created_at_epoch INTEGER NOT NULL,

  FOREIGN KEY (sdk_session_id) REFERENCES sdk_sessions(sdk_session_id)
);
```

**Indexes**:

* `idx_session_summaries_sdk_session` on `sdk_session_id`
* `idx_session_summaries_project` on `project`
* `idx_session_summaries_created_at` on `created_at_epoch DESC`

### 4. user\_prompts

Raw user prompts with FTS5 search (as of v4.2.0).

```sql theme={null}
CREATE TABLE user_prompts (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  sdk_session_id TEXT NOT NULL,
  claude_session_id TEXT,
  project TEXT NOT NULL,
  prompt_number INTEGER,
  prompt_text TEXT NOT NULL,
  created_at TEXT NOT NULL,
  created_at_epoch INTEGER NOT NULL,

  FOREIGN KEY (sdk_session_id) REFERENCES sdk_sessions(sdk_session_id)
);
```

**Indexes**:

* `idx_user_prompts_sdk_session` on `sdk_session_id`
* `idx_user_prompts_project` on `project`
* `idx_user_prompts_created_at` on `created_at_epoch DESC`

### 5. tool\_uses

Durable backup index for raw tool I/O (schema v51). Written from the same ingest
choke point that feeds the observation generator, so it captures the same calls
without adding a second capture path.

```sql theme={null}
CREATE TABLE tool_uses (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  tool_use_id TEXT NOT NULL,
  content_session_id TEXT NOT NULL,
  memory_session_id TEXT,
  session_db_id INTEGER,
  project TEXT NOT NULL,
  platform_source TEXT NOT NULL DEFAULT 'claude',
  tool_name TEXT NOT NULL,
  tool_input TEXT,
  tool_response TEXT,
  cwd TEXT,
  prompt_number INTEGER,
  agent_type TEXT,
  agent_id TEXT,
  observation_id INTEGER,
  or_generation_id TEXT,
  or_session_id TEXT,
  content_hash TEXT,
  created_at TEXT NOT NULL,
  created_at_epoch INTEGER NOT NULL,

  UNIQUE(content_session_id, tool_use_id)
);
```

**Why it exists**: `pending_messages` is the generation *queue* — rows are
claimed, summarized, and deleted, so raw tool payloads were unrecoverable once
an observation existed. `tool_uses` is the durable side index that survives the
queue, and it is what the `get_tool_uses` MCP tool (progressive-disclosure layer
4\) reads.

**Not a transcript store**: the JSONL transcripts on disk and the transcript
watcher remain the spine for session history. This table is a by-reference index
for tool bodies, nothing more.

**Idempotency**: `UNIQUE(content_session_id, tool_use_id)` means a replayed
PostToolUse (hook retry, transcript re-scan) updates the row instead of
duplicating it. `observation_id` is linked *after* generation and is never
overwritten once set.

**Payload cap**: `tool_input` / `tool_response` are truncated at 64 KB with a
`…[truncated: N bytes]` marker. `content_hash` is computed over the original,
pre-truncation payload.

**Cost columns**: none, deliberately. `or_generation_id` and `or_session_id` are
nullable join keys back to an OpenRouter spend line; dollars live on that line,
never here.

**Indexes**: `project`, `memory_session_id`, `content_session_id`,
`session_db_id`, `tool_name`, `created_at_epoch`, `observation_id`,
`or_generation_id`

### Legacy Tables

* **sessions**: Legacy session tracking (v3.x)
* **memories**: Legacy compressed memory chunks (v3.x)
* **overviews**: Legacy session summaries (v3.x)

## FTS5 Full-Text Search

SQLite FTS5 (Full-Text Search) virtual tables enable fast full-text search across observations and session summaries. User prompts are searched by substring (`LIKE`) and have no FTS index.

### FTS5 Virtual Tables

#### observations\_fts

```sql theme={null}
CREATE VIRTUAL TABLE observations_fts USING fts5(
  title,
  subtitle,
  narrative,
  text,
  facts,
  concepts,
  content='observations',
  content_rowid='id'
);
```

#### session\_summaries\_fts

```sql theme={null}
CREATE VIRTUAL TABLE session_summaries_fts USING fts5(
  request,
  investigated,
  learned,
  completed,
  next_steps,
  notes,
  content='session_summaries',
  content_rowid='id'
);
```

### Automatic Synchronization

FTS5 tables stay in sync via triggers. The update triggers fire only when an indexed column is written, so bookkeeping updates (sync revision, project merges, content hashes) never touch the index. Each index update appends a delete marker plus a re-insert of the row's text, so an unscoped update trigger would grow the index on every such write:

```sql theme={null}
-- Insert trigger example
CREATE TRIGGER observations_ai AFTER INSERT ON observations BEGIN
  INSERT INTO observations_fts(rowid, title, subtitle, narrative, text, facts, concepts)
  VALUES (new.id, new.title, new.subtitle, new.narrative, new.text, new.facts, new.concepts);
END;

-- Update trigger example (fires only when an indexed column is written)
CREATE TRIGGER observations_au
AFTER UPDATE OF title, subtitle, narrative, text, facts, concepts ON observations BEGIN
  INSERT INTO observations_fts(observations_fts, rowid, title, subtitle, narrative, text, facts, concepts)
  VALUES('delete', old.id, old.title, old.subtitle, old.narrative, old.text, old.facts, old.concepts);
  INSERT INTO observations_fts(rowid, title, subtitle, narrative, text, facts, concepts)
  VALUES (new.id, new.title, new.subtitle, new.narrative, new.text, new.facts, new.concepts);
END;

-- Delete trigger example
CREATE TRIGGER observations_ad AFTER DELETE ON observations BEGIN
  INSERT INTO observations_fts(observations_fts, rowid, title, subtitle, narrative, text, facts, concepts)
  VALUES('delete', old.id, old.title, old.subtitle, old.narrative, old.text, old.facts, old.concepts);
END;
```

### FTS5 Query Syntax

FTS5 supports rich query syntax:

* **Simple**: `"error handling"`
* **AND**: `"error" AND "handling"`
* **OR**: `"bug" OR "fix"`
* **NOT**: `"bug" NOT "feature"`
* **Phrase**: `"'exact phrase'"`
* **Column**: `title:"authentication"`

### Security

As of v4.2.3, all FTS5 queries are properly escaped to prevent SQL injection:

* Double quotes are escaped: `query.replace(/"/g, '""')`
* Comprehensive test suite with 332 injection attack tests

## Database Classes

### SessionStore

CRUD operations for sessions, observations, summaries, and user prompts.

**Location**: `src/services/sqlite/SessionStore.ts`

**Methods**:

* `createSession()`
* `getSession()`
* `updateSession()`
* `createObservation()`
* `getObservations()`
* `createSummary()`
* `getSummaries()`
* `createUserPrompt()`

### SessionSearch

FTS5 full-text search with 8 specialized search methods.

**Location**: `src/services/sqlite/SessionSearch.ts`

**Methods**:

* `searchObservations()` - Full-text search across observations
* `searchSessions()` - Full-text search across summaries
* `searchUserPrompts()` - Full-text search across user prompts
* `findByConcept()` - Find by concept tags
* `findByFile()` - Find by file references
* `findByType()` - Find by observation type
* `getRecentContext()` - Get recent session context
* `advancedSearch()` - Combined filters

## Migrations

Database schema is managed via migrations in `src/services/sqlite/migrations.ts`.

**Migration History**:

* Migration 001: Initial schema (sessions, memories, overviews, diagnostics, transcript\_events)
* Migration 002: Hierarchical memory fields (title, subtitle, facts, concepts, files\_touched)
* Migration 003: SDK sessions and observations
* Migration 004: Session summaries
* Migration 005: Multi-prompt sessions (prompt\_counter, prompt\_number)
* Migration 006: FTS5 virtual tables and triggers
* Migration 007-010: Various improvements and user prompts table
* Migration 051: `tool_uses` durable raw tool I/O index

## Performance Considerations

* **Indexes**: All foreign keys and frequently queried columns are indexed
* **FTS5**: Full-text search is significantly faster than LIKE queries
* **Triggers**: Automatic synchronization has minimal overhead
* **Connection Pooling**: bun:sqlite reuses connections efficiently
* **Synchronous API**: bun:sqlite uses synchronous API for better performance

## Troubleshooting

See [Troubleshooting - Database Issues](../troubleshooting.md#database-issues) for common problems and solutions.


# Hook Lifecycle
Source: https://docs.claude-mem.ai/architecture/hooks

Complete guide to the 5-stage memory agent lifecycle for platform implementers

# Hook Lifecycle

Claude-Mem implements a **5-stage hook system** that captures development work across Claude Code sessions. This document provides a complete technical reference for developers implementing this pattern on other platforms.

## Architecture Overview

### System Architecture

This two-process architecture works in both Claude Code and VS Code:

```mermaid theme={null}
graph TB
    subgraph EXT["Extension Process (runs in IDE)"]
        direction TB
        ACT[Extension Activation]
        HOOKS[Hook Event Handlers]
        ACT --> HOOKS

        subgraph HOOK_HANDLERS["5 Lifecycle Hooks"]
            H1[SessionStart<br/>activate function]
            H2[UserPromptSubmit<br/>command handler]
            H3[PostToolUse<br/>middleware]
            H4[Stop<br/>idle timeout]
            H5[SessionEnd<br/>deactivate function]
        end

        HOOKS --> HOOK_HANDLERS
    end

    HOOK_HANDLERS -->|"HTTP<br/>(fire-and-forget<br/>2s timeout)"| HTTP[Worker HTTP API<br/>Configured port]

    subgraph WORKER["Worker Process (separate Node.js)"]
        direction TB
        HTTP --> API[Express Server]
        API --> SESS[Session Manager]
        API --> AGENT[SDK Agent]
        API --> DB[Database Manager]

        AGENT -->|Event-Driven| CLAUDE[Claude Agent SDK]
        CLAUDE --> SQLITE[(SQLite + FTS5)]
        CLAUDE --> CHROMA[(Chroma Vectors)]
    end

    style EXT fill:#e1f5ff
    style WORKER fill:#fff4e1
    style HOOK_HANDLERS fill:#f0f0f0
```

**Key Principles:**

* Extension process never blocks (fire-and-forget HTTP)
* Worker processes observations asynchronously
* Session state persists across IDE restarts

### VS Code Extension API Integration Points

For developers porting to VS Code, here's where to hook into the VS Code Extension API:

```mermaid theme={null}
graph LR
    subgraph VSCODE["VS Code Extension API"]
        direction TB
        A["activate(context)"]
        B["commands.registerCommand()"]
        C["chat.createChatParticipant()"]
        D["workspace.onDidSaveTextDocument()"]
        E["window.onDidChangeActiveTextEditor()"]
        F["deactivate()"]
    end

    subgraph HOOKS["Hook Equivalents"]
        direction TB
        G[SessionStart]
        H[UserPromptSubmit]
        I[PostToolUse]
        J[Stop/Summary]
        K[SessionEnd]
    end

    subgraph WORKER_API["Worker HTTP Endpoints"]
        direction TB
        L[GET /api/context/inject]
        M[POST /sessions/init]
        N[POST /sessions/observations]
        O[POST /sessions/summarize]
        P[POST /sessions/complete]
    end

    A --> G
    B --> H
    C --> H
    D --> I
    E --> I
    F --> K

    G --> L
    H --> M
    I --> N
    J --> O
    K --> P

    style VSCODE fill:#007acc,color:#fff
    style HOOKS fill:#f0f0f0
    style WORKER_API fill:#4caf50,color:#fff
```

**Implementation Examples:**

```typescript theme={null}
const workerPort = process.env.CLAUDE_MEM_WORKER_PORT ?? "<worker-port>"
const workerBaseUrl = `http://127.0.0.1:${workerPort}`

// VS Code Extension - SessionStart Hook
export async function activate(context: vscode.ExtensionContext) {
  const sessionId = generateSessionId()
  const project = workspace.name || 'default'

  // Fetch context from worker
  const response = await fetch(`${workerBaseUrl}/api/context/inject?project=${project}`)
  const context = await response.text()

  // Inject into chat or UI panel
  injectContextToChat(context)
}

// VS Code Extension - UserPromptSubmit Hook
const command = vscode.commands.registerCommand('extension.command', async (prompt) => {
  await fetch(`${workerBaseUrl}/sessions/init`, {
    method: 'POST',
    body: JSON.stringify({ sessionId, project, userPrompt: prompt })
  })
})

// VS Code Extension - PostToolUse Hook (middleware pattern)
workspace.onDidSaveTextDocument(async (document) => {
  await fetch(`${workerBaseUrl}/api/sessions/observations`, {
    method: 'POST',
    body: JSON.stringify({
      claudeSessionId: sessionId,
      tool_name: 'FileSave',
      tool_input: { path: document.uri.path },
      tool_response: 'File saved successfully'
    })
  })
})
```

### Async Processing Pipeline

How observations flow from extension to database without blocking the IDE:

```mermaid theme={null}
graph TB
    A["Extension: Tool Use Event"] --> B{"Skip List?<br/>(TodoWrite, AskUserQuestion, etc.)"}
    B -->|"Skip"| X["Discard"]
    B -->|"Keep"| C["Strip Privacy Tags<br/>&lt;private&gt;...&lt;/private&gt;"]
    C --> D["HTTP POST to Worker<br/>Configured port"]
    D --> E["2s timeout<br/>fire-and-forget"]
    E --> F["Extension continues<br/>(non-blocking)"]

    D -.Async Path.-> G["Worker: Queue Observation"]
    G --> H["SDK Agent picks up<br/>(event-driven)"]
    H --> I["Call Claude API<br/>(compress observation)"]
    I --> J["Parse XML response"]
    J --> K["Save to SQLite<br/>(sdk_sessions table)"]
    K --> L["Sync to Chroma<br/>(vector embeddings)"]

    style F fill:#90EE90,stroke:#2d6b2d,stroke-width:3px
    style L fill:#87CEEB,stroke:#2d5f8d,stroke-width:3px
    style E fill:#ffeb3b,stroke:#c6a700,stroke-width:2px
```

**Critical Pattern:** The extension's HTTP call has a 2-second timeout and doesn't wait for AI processing. The worker handles compression asynchronously using an event-driven queue.

## The 5 Lifecycle Stages

| Stage | Hook | Trigger | Purpose |
| - | - | - | - |
| **1. SessionStart** | `claude-mem hook claude-code context` | User opens Claude Code | Inject prior context silently |
| **2. UserPromptSubmit** | `claude-mem hook claude-code session-init` | User submits a prompt | Create/get session, save prompt, init worker |
| **3. PostToolUse** | `claude-mem hook claude-code observation` | Claude uses any tool | Queue observation for AI compression |
| **4. Stop** | `claude-mem hook claude-code summarize` | User stops asking questions | Generate session summary |
| **5. SessionEnd** | `claude-mem hook claude-code session-end` | Session closes | Mark session completed |

PreToolUse (matcher `Read` plus the search tools) also runs `claude-mem hook claude-code file-context` synchronously, to add a file's history before Claude reads it and let the [File Read Gate](/file-read-gate) block a whole-file Read. PostToolUseFailure runs the same `observation` hook as PostToolUse for a tool call that failed.

## Hook Configuration

Hooks are configured in `plugin/hooks/hooks.json` (generated by `scripts/build-hooks.js`). Every runtime hook is exec form: `command` + `args`, no `shell`. Claude Code resolves `claude-mem` on PATH and spawns it directly, with no bash in between:

```json theme={null}
{
  "hooks": {
    "Setup": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "shell": "bash",
        "command": "… resolve the plugin root …; node \"$_P/scripts/version-check.js\"",
        "timeout": 300
      }]
    }],
    "SessionStart": [{
      "matcher": "startup|resume|clear|compact",
      "hooks": [
        { "type": "command", "command": "claude-mem", "args": ["start"], "timeout": 60, "async": true }
      ]
    }, {
      "matcher": "startup|clear|compact",
      "hooks": [
        { "type": "command", "command": "claude-mem", "args": ["hook", "claude-code", "context"], "timeout": 60 }
      ]
    }, {
      "matcher": "startup",
      "hooks": [
        { "type": "command", "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/ensure-launcher.cjs"], "timeout": 180 }
      ]
    }],
    "UserPromptSubmit": [{
      "hooks": [{ "type": "command", "command": "claude-mem", "args": ["hook", "claude-code", "session-init"], "timeout": 15 }]
    }],
    "PreToolUse": [{
      "matcher": "Read|^Bash$|^Grep$|^Glob$|^memory_search$|^memory$|^mcp__.+__memory_search$",
      "hooks": [{ "type": "command", "command": "claude-mem", "args": ["hook", "claude-code", "file-context"], "timeout": 15 }]
    }],
    "PostToolUse": [{
      "matcher": "*",
      "hooks": [{ "type": "command", "command": "claude-mem", "args": ["hook", "claude-code", "observation"], "timeout": 120, "async": true }]
    }],
    "PostToolUseFailure": [{
      "matcher": "*",
      "hooks": [{ "type": "command", "command": "claude-mem", "args": ["hook", "claude-code", "observation"], "timeout": 120, "async": true }]
    }],
    "Stop": [{
      "hooks": [{ "type": "command", "command": "claude-mem", "args": ["hook", "claude-code", "summarize"], "timeout": 120, "async": true }]
    }],
    "SessionEnd": [{
      "hooks": [{ "type": "command", "command": "claude-mem", "args": ["hook", "claude-code", "session-end"], "async": true }]
    }]
  }
}
```

* **`claude-mem`** is a small, version-stable compiled launcher, not the npm CLI. `npx claude-mem install` / `update` place it at `~/.local/bin` (POSIX) or `%LOCALAPPDATA%\claude-mem\bin` (Windows) and add that directory to PATH. It finds the plugin root, runs `worker-service.cjs` with the same arguments under Bun, and exits 0 on any failure.
* **`ensure-launcher.cjs`** (startup only) is the self-heal for marketplace-only installs: it places or refreshes the launcher when it is missing or out of date.
* **Setup** is the only entry that still uses bash. Claude Code fires it only for `claude --init`, `--init-only` and `-p --maintenance`, never on plugin install, update or a normal session start.

See [Hooks Architecture](/hooks-architecture#how-every-hook-is-launched) for the launcher's behavior and the error you see when it is missing.

***

## Stage 1: SessionStart

**Timing**: When user opens Claude Code or resumes session

**Hooks Triggered** (in order):

1. `claude-mem start` - Starts the worker service (async)
2. `claude-mem hook claude-code context` - Fetches and silently injects prior session context
3. `node ${CLAUDE_PLUGIN_ROOT}/scripts/ensure-launcher.cjs` - Startup only, synchronous: keeps the `claude-mem` launcher on PATH, and shows a `systemMessage` when the memory hooks are not active

(Runtime setup is handled by `npx claude-mem install` / `npx claude-mem repair`. The Setup hook runs `version-check.js` only for `claude --init` / `--maintenance`: it installs the plugin's dependencies when they are missing, records the `.install-version` marker once they are complete, and asks you to run `npx claude-mem@latest install` only if they are still missing.)

<Note>
  As of Claude Code 2.1.0 (ultrathink update), SessionStart hooks no longer display user-visible messages. Context is silently injected via `hookSpecificOutput.additionalContext`.
</Note>

### Sequence Diagram

```mermaid theme={null}
sequenceDiagram
    participant User
    participant IDE as IDE/Extension
    participant ContextHook as context-hook.js
    participant Worker as Worker Service
    participant DB as SQLite Database

    User->>IDE: Opens workspace / resumes session
    IDE->>ContextHook: Trigger SessionStart hook
    ContextHook->>ContextHook: Generate/reuse session_id
    ContextHook->>Worker: Health check (max 10s retry)

    alt Worker Ready
        ContextHook->>Worker: GET /api/context/inject?project=X
        Worker->>DB: SELECT * FROM observations<br/>WHERE project=X<br/>ORDER BY created_at DESC<br/>LIMIT 50
        DB-->>Worker: Last 50 observations
        Worker-->>ContextHook: Context markdown
        ContextHook-->>IDE: hookSpecificOutput.additionalContext
        IDE->>IDE: Inject context to Claude's prompt
        IDE-->>User: Session ready with context
    else Worker Not Ready
        ContextHook-->>IDE: Empty context (graceful degradation)
        IDE-->>User: Session ready without context
    end

    Note over User,DB: Total time: <300ms (with health check)
```

### Context Hook (`claude-mem hook claude-code context`)

**Purpose**: Inject context from previous sessions into Claude's initial context.

**Input** (via stdin):

```json theme={null}
{
  "session_id": "claude-session-123",
  "cwd": "/path/to/project",
  "source": "startup"
}
```

**Processing**:

1. Wait for worker to be available (health check, max 10 seconds)
2. Call: `GET http://127.0.0.1:<worker-port>/api/context/inject?project={project}`
3. Return formatted context as `additionalContext` in `hookSpecificOutput`

**Output** (via stdout):

```json theme={null}
{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "<<formatted context markdown>>"
  }
}
```

**Implementation**: `src/cli/handlers/context.ts`

***

## Stage 2: UserPromptSubmit

**Timing**: When user submits any prompt in a session

**Hook**: `claude-mem hook claude-code session-init`

### Sequence Diagram

```mermaid theme={null}
sequenceDiagram
    participant User
    participant IDE as IDE/Extension
    participant NewHook as new-hook.js
    participant DB as Direct SQLite Access
    participant Worker as Worker Service

    User->>IDE: Submits prompt: "Add login feature"
    IDE->>NewHook: Trigger UserPromptSubmit<br/>{ session_id, cwd, prompt }

    NewHook->>NewHook: Extract project = basename(cwd)
    NewHook->>NewHook: Strip privacy tags<br/>&lt;private&gt;...&lt;/private&gt;

    alt Prompt fully private (empty after stripping)
        NewHook-->>IDE: Skip (don't save)
    else Prompt has content
        NewHook->>DB: INSERT OR IGNORE INTO sdk_sessions<br/>(claude_session_id, project, first_user_prompt)
        DB-->>NewHook: sessionDbId (new or existing)

        NewHook->>DB: UPDATE sdk_sessions<br/>SET prompt_counter = prompt_counter + 1<br/>WHERE id = sessionDbId
        DB-->>NewHook: promptNumber (e.g., 1 for first, 2 for continuation)

        NewHook->>DB: INSERT INTO user_prompts<br/>(session_id, prompt_number, prompt)

        NewHook->>Worker: POST /sessions/{sessionDbId}/init<br/>{ project, userPrompt, promptNumber }<br/>(fire-and-forget, 2s timeout)
        Worker-->>NewHook: 200 OK (or timeout)

        NewHook-->>IDE: { continue: true, suppressOutput: true }
        IDE-->>User: Prompt accepted
    end

    Note over NewHook,DB: Idempotent: Same session_id → same sessionDbId
```

**Key Pattern:** The `INSERT OR IGNORE` ensures the same `session_id` always maps to the same `sessionDbId`, enabling conversation continuations.

**Input** (via stdin):

```json theme={null}
{
  "session_id": "claude-session-123",
  "cwd": "/path/to/project",
  "prompt": "User's actual prompt text"
}
```

**Processing Steps**:

```typescript theme={null}
// 1. Extract project name from working directory
project = path.basename(cwd)

// 2. Create or get database session (IDEMPOTENT)
sessionDbId = db.createSDKSession(session_id, project, prompt)
// INSERT OR IGNORE: Creates new row if first prompt, returns existing if continuation

// 3. Increment prompt counter
promptNumber = db.incrementPromptCounter(sessionDbId)
// Returns 1 for first prompt, 2 for continuation, etc.

// 4. Strip privacy tags
cleanedPrompt = stripMemoryTags(prompt)
// Removes <private>...</private> and <claude-mem-context>...</claude-mem-context>

// 5. Skip if fully private
if (!cleanedPrompt || cleanedPrompt.trim() === '') {
  return  // Don't save, don't call worker
}

// 6. Save user prompt to database
db.saveUserPrompt(session_id, promptNumber, cleanedPrompt)

// 7. Initialize session via worker HTTP
POST http://127.0.0.1:<worker-port>/sessions/{sessionDbId}/init
Body: { project, userPrompt, promptNumber }
```

**Output**:

```json theme={null}
{ "continue": true, "suppressOutput": true }
```

**Implementation**: `src/cli/handlers/session-init.ts`

<Note>
  The same `session_id` flows through ALL hooks in a conversation. The `createSDKSession` call is idempotent - it returns the existing session for continuation prompts.
</Note>

***

## Stage 3: PostToolUse

**Timing**: After Claude uses any tool (Read, Bash, Grep, Write, etc.)

**Hook**: `claude-mem hook claude-code observation`

### Sequence Diagram

```mermaid theme={null}
sequenceDiagram
    participant Claude as Claude AI
    participant IDE as IDE/Extension
    participant SaveHook as save-hook.js
    participant Worker as Worker Service
    participant Agent as SDK Agent
    participant DB as SQLite + Chroma

    Claude->>IDE: Uses tool: Read("/src/auth.ts")
    IDE->>SaveHook: PostToolUse hook triggered<br/>{ session_id, tool_name, tool_input, tool_response }

    SaveHook->>SaveHook: Check skip list<br/>(TodoWrite, AskUserQuestion, etc.)

    alt Tool in skip list
        SaveHook-->>IDE: Discard (low-value tool)
    else Tool allowed
        SaveHook->>SaveHook: Strip privacy tags from input/response

        SaveHook->>SaveHook: Ensure worker running<br/>(health check)

        SaveHook->>Worker: POST /api/sessions/observations<br/>{ claudeSessionId, tool_name, tool_input, tool_response, cwd }<br/>(fire-and-forget, 2s timeout)

        SaveHook-->>IDE: { continue: true, suppressOutput: true }
        IDE-->>Claude: Tool execution complete

        Note over Worker,DB: Async path (doesn't block IDE)

        Worker->>Worker: createSDKSession(claudeSessionId)<br/>→ returns sessionDbId
        Worker->>Worker: Check if prompt was private<br/>(skip if fully private)
        Worker->>Agent: Queue observation for processing
        Agent->>Agent: Call Claude SDK to compress<br/>observation into structured format
        Agent->>DB: Save compressed observation<br/>to sdk_sessions table
        Agent->>DB: Sync to Chroma vector DB
    end

    Note over SaveHook,DB: Total sync time: ~2ms<br/>AI processing: 1-3s (async)
```

**Key Pattern:** The hook returns immediately after HTTP POST. AI compression happens asynchronously in the worker without blocking Claude's tool execution.

**Input** (via stdin):

```json theme={null}
{
  "session_id": "claude-session-123",
  "cwd": "/path/to/project",
  "tool_name": "Read",
  "tool_input": { "file_path": "/src/index.ts" },
  "tool_response": "file contents..."
}
```

**Processing Steps**:

```typescript theme={null}
// 1. Check blocklist - skip low-value tools
const SKIP_TOOLS = {
  'ListMcpResourcesTool',  // MCP infrastructure noise
  'SlashCommand',          // Command invocation
  'Skill',                 // Skill invocation
  'TodoWrite',             // Task management meta-tool
  'AskUserQuestion'        // User interaction
}

if (SKIP_TOOLS[tool_name]) return

// 2. Ensure worker is running
await ensureWorkerRunning()

// 3. Send to worker (fire-and-forget HTTP)
POST http://127.0.0.1:<worker-port>/api/sessions/observations
Body: {
  claudeSessionId: session_id,
  tool_name,
  tool_input,
  tool_response,
  cwd
}
Timeout: 2000ms
```

**Worker Processing**:

1. Looks up or creates session: `createSDKSession(claudeSessionId, '', '')`
2. Gets prompt counter
3. Checks privacy (skips if user prompt was entirely private)
4. Strips memory tags from `tool_input` and `tool_response`
5. Queues observation for SDK agent processing
6. SDK agent calls Claude to compress into structured observation
7. Stores observation in database and syncs to Chroma

**Output**:

```json theme={null}
{ "continue": true, "suppressOutput": true }
```

**Implementation**: `src/cli/handlers/observation.ts`

***

## Stage 4: Stop

**Timing**: When user stops or pauses asking questions

**Hook**: `claude-mem hook claude-code summarize`

### Sequence Diagram

```mermaid theme={null}
sequenceDiagram
    participant User
    participant IDE as IDE/Extension
    participant SummaryHook as summary-hook.js
    participant Worker as Worker Service
    participant Agent as SDK Agent
    participant DB as SQLite Database

    User->>IDE: Stops asking questions<br/>(pause, idle, or explicit stop)
    IDE->>SummaryHook: Stop hook triggered<br/>{ session_id, cwd, transcript_path }

    SummaryHook->>SummaryHook: Read transcript JSONL file
    SummaryHook->>SummaryHook: Extract last user message<br/>(type: "user")
    SummaryHook->>SummaryHook: Extract last assistant message<br/>(type: "assistant", filter &lt;system-reminder&gt;)

    SummaryHook->>Worker: POST /api/sessions/summarize<br/>{ claudeSessionId, last_user_message, last_assistant_message }<br/>(fire-and-forget, 2s timeout)

    SummaryHook-->>IDE: { continue: true, suppressOutput: true }
    IDE-->>User: Session paused/stopped

    Note over Worker,DB: Async path

    Worker->>Worker: Lookup sessionDbId from claudeSessionId
    Worker->>Agent: Queue summarization request
    Agent->>Agent: Call Claude SDK with prompt:<br/>"Summarize: request, investigated, learned, completed, next_steps"
    Agent->>Agent: Parse XML response
    Agent->>DB: INSERT INTO session_summaries<br/>{ session_id, request, investigated, learned, completed, next_steps }
    Agent->>DB: Sync to Chroma (for semantic search)

    Note over SummaryHook,DB: Total sync time: ~2ms<br/>AI summarization: 2-5s (async)
```

**Key Pattern:** The summary is generated asynchronously and doesn't block the user from resuming work or closing the session.

**Input** (via stdin):

```json theme={null}
{
  "session_id": "claude-session-123",
  "cwd": "/path/to/project",
  "transcript_path": "/path/to/transcript.jsonl"
}
```

**Processing Steps**:

```typescript theme={null}
// 1. Extract last messages from transcript JSONL
const lines = fs.readFileSync(transcript_path, 'utf-8').split('\n')
// Find last user message (type: "user")
// Find last assistant message (type: "assistant", filter <system-reminder> tags)

// 2. Ensure worker is running
await ensureWorkerRunning()

// 3. Send summarization request (fire-and-forget HTTP)
POST http://127.0.0.1:<worker-port>/api/sessions/summarize
Body: {
  claudeSessionId: session_id,
  last_user_message: string,
  last_assistant_message: string
}
Timeout: 2000ms
```

<Note>
  The summary hook does not call `POST /api/processing`, and that route is not a spinner toggle. It is a localhost-only operator retry. `{ "isProcessing": false }` restarts the observer for every active session that holds buffered work and has no generator running. That includes pauses the automatic resume sweep leaves alone, such as a refused credential or a transport failure. The response's `scheduledSessions` reports how many sessions were retried. `{ "isProcessing": true }` is accepted and does nothing.
</Note>

**Worker Processing**:

1. Queues summarization for SDK agent
2. Agent calls Claude to generate structured summary
3. Summary stored in database with fields: `request`, `investigated`, `learned`, `completed`, `next_steps`

**Output**:

```json theme={null}
{ "continue": true, "suppressOutput": true }
```

**Implementation**: `src/cli/handlers/summarize.ts`

***

## Stage 5: SessionEnd

**Timing**: When Claude Code session closes (exit, clear, logout, etc.)

**Hook**: `claude-mem hook claude-code session-end`

### Sequence Diagram

```mermaid theme={null}
sequenceDiagram
    participant User
    participant IDE as IDE/Extension
    participant CleanupHook as cleanup-hook.js
    participant Worker as Worker Service
    participant DB as SQLite Database
    participant SSE as SSE Clients (Viewer UI)

    User->>IDE: Closes session<br/>(exit, clear, logout)
    IDE->>CleanupHook: SessionEnd hook triggered<br/>{ session_id, cwd, transcript_path, reason }

    CleanupHook->>Worker: POST /api/sessions/complete<br/>{ claudeSessionId, reason }<br/>(fire-and-forget, 2s timeout)

    CleanupHook-->>IDE: { continue: true, suppressOutput: true }
    IDE-->>User: Session closed

    Note over Worker,SSE: Async path

    Worker->>Worker: Lookup sessionDbId from claudeSessionId
    Worker->>DB: UPDATE sdk_sessions<br/>SET status = 'completed', completed_at = NOW()<br/>WHERE claude_session_id = claudeSessionId
    Worker->>SSE: Broadcast session completion event<br/>(for live viewer UI updates)

    SSE-->>SSE: Update UI to show session as completed

    Note over CleanupHook,SSE: Total sync time: ~2ms
```

**Key Pattern:** Session completion is tracked for analytics and UI updates, but doesn't prevent the user from closing the IDE.

**Input** (via stdin):

```json theme={null}
{
  "session_id": "claude-session-123",
  "cwd": "/path/to/project",
  "transcript_path": "/path/to/transcript.jsonl",
  "reason": "exit"
}
```

**Processing Steps**:

```typescript theme={null}
// Send session complete (fire-and-forget HTTP)
POST http://127.0.0.1:<worker-port>/api/sessions/complete
Body: {
  claudeSessionId: session_id,
  reason: string  // 'exit' | 'clear' | 'logout' | 'prompt_input_exit' | 'other'
}
Timeout: 2000ms
```

**Worker Processing**:

1. Finds session by `claudeSessionId`
2. Marks session as 'completed' in database
3. Broadcasts session completion event to SSE clients

**Output**:

```json theme={null}
{ "continue": true, "suppressOutput": true }
```

**Implementation**: `src/cli/handlers/session-end.ts`

***

## Session State Machine

Understanding session lifecycle and state transitions:

```mermaid theme={null}
stateDiagram-v2
    [*] --> Initialized: SessionStart hook<br/>(generate session_id)

    Initialized --> Active: UserPromptSubmit<br/>(first prompt)

    Active --> Active: UserPromptSubmit<br/>(continuation prompts)<br/>promptNumber++

    Active --> ObservationQueued: PostToolUse hook<br/>(tool execution captured)

    ObservationQueued --> Active: Observation processed<br/>(async, non-blocking)

    Active --> Summarizing: Stop hook<br/>(user pauses/stops)

    Summarizing --> Active: User resumes<br/>(new prompt submitted)

    Summarizing --> Completed: SessionEnd hook<br/>(session closes)

    Active --> Completed: SessionEnd hook<br/>(session closes)

    Completed --> [*]

    note right of Active
        session_id: constant (e.g., "claude-session-abc123")
        sessionDbId: constant (e.g., 42)
        promptNumber: increments (1, 2, 3, ...)
        All operations use same sessionDbId
    end note

    note right of ObservationQueued
        Fire-and-forget HTTP
        AI compression happens async
        IDE never blocks
    end note
```

**Key Insights:**

* `session_id` never changes during a conversation
* `sessionDbId` is the database primary key for the session
* `promptNumber` increments with each user prompt
* State transitions are non-blocking (fire-and-forget pattern)

***

## Database Schema

The session-centric data model that enables cross-session memory:

```mermaid theme={null}
erDiagram
    SDK_SESSIONS ||--o{ USER_PROMPTS : "has many"
    SDK_SESSIONS ||--o{ OBSERVATIONS : "has many"
    SDK_SESSIONS ||--o{ SESSION_SUMMARIES : "has many"

    SDK_SESSIONS {
        integer id PK "Auto-increment primary key"
        text claude_session_id UK "From IDE (e.g., 'claude-session-123')"
        text project "Project name from cwd basename"
        text first_user_prompt "Initial prompt that started session"
        integer prompt_counter "Increments with each UserPromptSubmit"
        text status "initialized | active | completed"
        datetime created_at
        datetime completed_at
    }

    USER_PROMPTS {
        integer id PK
        integer session_id FK "References SDK_SESSIONS.id"
        integer prompt_number "1, 2, 3, ... matches prompt_counter"
        text prompt "User's actual prompt (tags stripped)"
        datetime created_at
    }

    OBSERVATIONS {
        integer id PK
        integer session_id FK "References SDK_SESSIONS.id"
        integer prompt_number "Which prompt this observation belongs to"
        text tool_name "Read, Bash, Grep, Write, etc."
        text tool_input_json "Stripped of privacy tags"
        text tool_response_text "Stripped of privacy tags"
        text compressed_observation "AI-generated structured observation"
        datetime created_at
    }

    SESSION_SUMMARIES {
        integer id PK
        integer session_id FK "References SDK_SESSIONS.id"
        text request "What user requested"
        text investigated "What was explored"
        text learned "What was discovered"
        text completed "What was accomplished"
        text next_steps "What remains to be done"
        datetime created_at
    }
```

**Idempotency Pattern:**

```sql theme={null}
-- This ensures same session_id always maps to same sessionDbId
INSERT OR IGNORE INTO sdk_sessions (claude_session_id, project, first_user_prompt)
VALUES (?, ?, ?)
RETURNING id;

-- If already exists, returns existing row
-- If new, creates and returns new row
```

**Foreign Key Cascade:**

All child tables (user\_prompts, observations, session\_summaries) use `session_id` foreign key referencing `SDK_SESSIONS.id`. This ensures:

* All data for a session is queryable by sessionDbId
* Session deletions cascade to child tables
* Efficient joins for context injection

<Warning>
  Never generate your own session IDs. Always use the `session_id` provided by the IDE - this is the source of truth for linking all data together.
</Warning>

***

## Privacy & Tag Stripping

### Dual-Tag System

```typescript theme={null}
// User-Level Privacy Control (manual)
<private>sensitive data</private>

// System-Level Recursion Prevention (auto-injected)
<claude-mem-context>...</claude-mem-context>
```

### Processing Pipeline

**Location**: `src/utils/tag-stripping.ts`

```typescript theme={null}
// Called by: new-hook.js (user prompts) and save-hook.js (tool_input, tool_response)
stripMemoryTags(content: string): string
```

**Execution Order** (Edge Processing):

1. `new-hook.js` strips tags from user prompt before saving
2. `save-hook.js` strips tags from tool data before sending to worker
3. Worker strips tags again (defense in depth) before storing

***

## SDK Agent Processing

### Query Loop (Event-Driven)

**Location**: `src/services/worker/SDKAgent.ts`

```typescript theme={null}
async startSession(session: ActiveSession, worker?: any) {
  // 1. Create event-driven message generator
  const messageGenerator = this.createMessageGenerator(session)

  // 2. Run Agent SDK query loop
  const queryResult = query({
    prompt: messageGenerator,
    options: {
      model: 'claude-sonnet-5',
      disallowedTools: ['Bash', 'Read', 'Write', ...],  // Observer-only
      abortController: session.abortController
    }
  })

  // 3. Process responses
  for await (const message of queryResult) {
    if (message.type === 'assistant') {
      await this.processSDKResponse(session, text, worker)
    }
  }
}
```

### Message Types

The message generator yields three types of prompts:

1. **Initial Prompt** (prompt #1): Full instructions for starting observation
2. **Continuation Prompt** (prompt #2+): Context-only for continuing work
3. **Observation Prompts**: Tool use data to compress into observations
4. **Summary Prompts**: Session data to summarize

***

## Implementation Checklist

For developers implementing this pattern on other platforms:

### Hook Registration

* [ ] Define hook entry points in platform config
* [ ] 5 hook types: SessionStart (2 hooks), UserPromptSubmit, PostToolUse, Stop, SessionEnd
* [ ] Prefer exec-form hook entries (`command` + `args`, no shell) when the host supports them
* [ ] Pass `session_id`, `cwd`, and context-specific data

### Database Schema

* [ ] SQLite with WAL mode
* [ ] 4 main tables: `sdk_sessions`, `user_prompts`, `observations`, `session_summaries`
* [ ] Indices for common queries

### Worker Service

* [ ] HTTP server on configured worker port
* [ ] Bun runtime for process management
* [ ] 3 core services: SessionManager, SDKAgent, DatabaseManager

### Hook Implementation

* [ ] context-hook: `GET /api/context/inject` (with health check)
* [ ] new-hook: createSDKSession, saveUserPrompt, `POST /sessions/{id}/init`
* [ ] save-hook: Skip low-value tools, `POST /api/sessions/observations`
* [ ] summary-hook: Parse transcript, `POST /api/sessions/summarize`
* [ ] cleanup-hook: `POST /api/sessions/complete`

### Privacy & Tags

* [ ] Implement `stripMemoryTags()`
* [ ] Process tags at hook layer (edge processing)
* [ ] Max tag count = 100 (ReDoS protection)

### SDK Integration

* [ ] Call Claude Agent SDK to process observations/summaries
* [ ] Parse XML responses for structured data
* [ ] Store to database + sync to vector DB

***

## Key Design Principles

1. **Session ID is Source of Truth**: Never generate your own session IDs
2. **Idempotent Database Operations**: Use `INSERT OR IGNORE` for session creation
3. **Edge Processing for Privacy**: Strip tags at hook layer before data reaches worker
4. **Fire-and-Forget for Non-Blocking**: HTTP timeouts prevent IDE blocking
5. **Event-Driven, Not Polling**: Zero-latency queue notification to SDK agent
6. **Everything Saves Always**: No "orphaned" sessions

***

## Common Pitfalls

| Problem | Root Cause | Solution |
| - | - | - |
| Session ID mismatch | Different `session_id` used in different hooks | Always use ID from hook input |
| Duplicate sessions | Creating new session instead of using existing | Use `INSERT OR IGNORE` with `session_id` as key |
| Blocking IDE | Waiting for full response | Use fire-and-forget with short timeouts |
| Memory tags in DB | Stripping tags in wrong layer | Strip at hook layer, before HTTP send |
| Worker not found | Health check too fast | Add retry loop with exponential backoff |

***

## Related Documentation

* [Worker Service](/architecture/worker-service) - HTTP API and async processing
* [Database Schema](/architecture/database) - SQLite tables and FTS5 search
* [Privacy Tags](/usage/private-tags) - Using `<private>` tags
* [Troubleshooting](/troubleshooting) - Common hook issues


# Architecture Overview
Source: https://docs.claude-mem.ai/architecture/overview

System components and data flow in Claude-Mem

# Architecture Overview

## System Components

Claude-Mem operates as a Claude Code plugin with the following core components:

1. **Plugin Hooks** - Lifecycle events (lifecycle hooks for SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, Stop and SessionEnd, plus a Setup version-check), each run as a shell-free `claude-mem hook claude-code <event>` command
2. **Worker Service** - Express HTTP API on a per-user port; processes observations via the Claude Agent SDK (or Gemini / OpenRouter)
3. **Database Layer** - SQLite + FTS5 (and optional Chroma for semantic search)
4. **Search Tools** - HTTP API + the `mem-search` skill / MCP server for progressive disclosure search
5. **Viewer UI** - React-based real-time memory stream served by the worker

## Technology Stack

| Layer | Technology |
| - | - |
| **Language** | TypeScript (ES2022, ESNext modules) |
| **Runtime** | Node.js 20+ and Bun ≥ 1.0 |
| **Database** | SQLite 3 with bun:sqlite driver |
| **Vector Store** | Chroma (optional, for semantic search) |
| **HTTP Server** | Express.js 5 |
| **Real-time** | Server-Sent Events (SSE) |
| **UI Framework** | React + TypeScript |
| **AI SDK** | @anthropic-ai/claude-agent-sdk (or Gemini / OpenRouter) |
| **Build Tool** | esbuild (bundles TypeScript) |
| **Process Manager** | Bun |
| **Testing** | `bun test` |

## Data Flow

### Memory Pipeline

```
Hook (stdin) → Database → Worker Service → SDK Processor → Database → Next Session Hook
```

1. **Input**: Claude Code sends tool execution data via stdin to hooks
2. **Storage**: Hooks write observations to SQLite database
3. **Processing**: Worker service reads observations, processes via SDK
4. **Output**: Processed summaries written back to database
5. **Retrieval**: Next session's context hook reads summaries from database

### Search Pipeline

```
User Query → MCP Tools Invoked → HTTP API → SessionSearch Service → FTS5 Database → Search Results → Claude
```

1. **User Query**: User asks naturally: "What bugs did we fix?"
2. **MCP Tools Invoked**: Claude recognizes intent and invokes MCP search tools
3. **HTTP API**: MCP tools call HTTP endpoint (e.g., `/api/search/observations`)
4. **SessionSearch**: Worker service queries FTS5 virtual tables
5. **Format**: Results formatted and returned via MCP
6. **Return**: Claude presents formatted results to user

Uses 3-layer progressive disclosure: search → timeline → get\_observations

## Session Lifecycle

```
┌─────────────────────────────────────────────────────────────────┐
│ 0. Install puts the claude-mem launcher on PATH                 │
│    npx claude-mem install/update, or the startup SessionStart   │
│    self-heal (ensure-launcher.cjs) for marketplace-only installs│
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 1. Session Starts → Worker-start, then Context Hook             │
│    Starts Bun worker if needed, injects context from previous   │
│    sessions (configurable observation count)                    │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 2. User Types Prompt → UserPromptSubmit Hook Fires              │
│    Creates session in database, saves raw user prompt for FTS5  │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 3. Claude Uses Tools → PostToolUse Hook Fires (100+ times)      │
│    Captures tool executions, sends to worker for AI compression │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 4. Worker Processes → Claude Agent SDK Analyzes                 │
│    Extracts structured learnings via iterative AI processing    │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 5. Claude Stops → Summary Hook Fires                            │
│    Generates final summary with request, completions, learnings │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 6. Session Ends → Cleanup Hook Fires                            │
│    Marks session complete (graceful, not DELETE), ready for     │
│    next session context. Skips on /clear to preserve ongoing    │
└─────────────────────────────────────────────────────────────────┘
```

## Directory Structure

```
claude-mem/
├── src/
│   ├── hooks/                  # TypeScript hook implementations (built via esbuild)
│   ├── sdk/                    # Claude Agent SDK integration
│   ├── services/
│   │   ├── worker-service.ts   # Express HTTP + SSE service (worker entry point)
│   │   ├── sync/ChromaSync.ts  # Optional Chroma vector index
│   │   └── sqlite/             # SQLite + FTS5 storage layer
│   ├── ui/viewer/              # React + TypeScript web viewer
│   ├── shared/                 # Shared utilities (paths, settings defaults)
│   └── utils/                  # Logging, platform, tag-stripping helpers
│
├── scripts/                    # Build + utility scripts
│
├── plugin/                     # Plugin distribution (synced to marketplace)
│   ├── .claude-plugin/plugin.json
│   ├── hooks/hooks.json        # Hook registration (exec-form `claude-mem` hooks + Setup)
│   ├── scripts/                # Built executables
│   │   ├── claude-mem-launcher.cjs # Source of the on-PATH `claude-mem` hook launcher (compiled at install)
│   │   ├── ensure-launcher.cjs # Startup SessionStart self-heal: places/refreshes the launcher
│   │   ├── version-check.js    # Setup hook (--init / --maintenance): dependency check + install marker
│   │   ├── bun-runner.js       # Resolves Bun and runs worker-service.cjs (Codex hooks)
│   │   ├── worker-service.cjs  # Worker daemon + lifecycle hook dispatcher
│   │   ├── worker-cli.js       # CLI shim
│   │   ├── worker-wrapper.cjs  # Process wrapper
│   │   ├── mcp-server.cjs      # MCP search server
│   │   ├── statusline-counts.js
│   │   └── context-generator.cjs
│   ├── skills/                 # Agent skills (mem-search, make-plan, do, etc.)
│   └── ui/viewer.html          # Self-contained React bundle
│
├── tests/                      # Test suite (`bun test`)
├── docs/                       # Mintlify documentation
└── openclaw/                   # OpenClaw integration plugin
```

## Component Details

### 1. Plugin Hooks

The plugin registers lifecycle hooks plus a Setup-phase `version-check.js`. Each lifecycle hook is one exec-form command, `claude-mem hook claude-code <event>`, with no shell. `claude-mem` is a small compiled launcher on PATH: it finds the plugin root and runs `worker-service.cjs hook claude-code <event>` under Bun; the worker process is the single dispatcher for all hook logic. Events:

* **Setup** → `version-check.js` (installs missing plugin dependencies, then records the install marker). Still a bash entry, and Claude Code fires it only for `claude --init` / `--maintenance`.
* **SessionStart** → `claude-mem start` (worker, async), then `hook claude-code context` (context injection); at startup also `node ${CLAUDE_PLUGIN_ROOT}/scripts/ensure-launcher.cjs` (launcher self-heal)
* **UserPromptSubmit** → `hook claude-code session-init`
* **PreToolUse** (matcher `Read`) → `hook claude-code file-context`
* **PostToolUse** (matcher `*`) → `hook claude-code observation`
* **Stop** → `hook claude-code summarize` (summary generation)
* **SessionEnd** → `hook claude-code session-end`

The runtime install (Bun, uv, `bun install`, and compiling the launcher into `~/.local/bin` or `%LOCALAPPDATA%\claude-mem\bin`) is performed by `npx claude-mem install` / `npx claude-mem update` with a visible installer spinner. For plugin-marketplace installs, the startup self-heal places the launcher, and the Setup hook (on `claude --init` / `--maintenance`) runs `bun install` when the plugin's dependencies are missing.

See [Plugin Hooks](/architecture/hooks) for detailed hook documentation.

### 2. Worker Service

Express.js HTTP server on a per-user port (default `37700 + (uid % 100)`, override via `CLAUDE_MEM_WORKER_PORT`) with:

* Search HTTP API endpoints
* Viewer UI HTTP/SSE endpoints
* Async observation processing via the Claude Agent SDK (or Gemini / OpenRouter)
* Real-time updates via Server-Sent Events
* Auto-managed by Bun

See [Worker Service](/architecture/worker-service) for HTTP API and endpoints.

### 3. Database Layer

SQLite3 with bun:sqlite driver featuring:

* FTS5 virtual tables for full-text search
* SessionStore for CRUD operations
* SessionSearch for FTS5 queries
* Location: `~/.claude-mem/claude-mem.db`

See [Database Architecture](/architecture/database) for schema and FTS5 search.

### 4. mem-search Skill (v5.4.0+)

Skill-based search with progressive disclosure providing 10 search operations:

* Search observations, sessions, prompts (full-text FTS5)
* Filter by type, concept, file
* Get recent context, timeline, timeline by query
* API help documentation

**Token Savings**: \~2,250 tokens per session vs MCP approach

* Skill frontmatter: \~250 tokens (loaded at session start)
* Full instructions: \~2,500 tokens (loaded on-demand when invoked)
* HTTP API endpoints instead of MCP tools

**Skill Enhancement (v5.5.0)**: Renamed from "search" to "mem-search" for better scope differentiation. Effectiveness increased from 67% to 100% with enhanced triggers and comprehensive documentation.

See [Search Architecture](/architecture/search-architecture) for technical details and examples.

### 5. Viewer UI

React + TypeScript web interface served by the worker on its configured `CLAUDE_MEM_WORKER_PORT` featuring:

* Real-time memory stream via Server-Sent Events
* Infinite scroll pagination with automatic deduplication
* Project filtering and settings persistence
* GPU-accelerated animations
* Self-contained HTML bundle (viewer.html)

Built with esbuild into a single file deployment.


# PM2 to Bun Migration
Source: https://docs.claude-mem.ai/architecture/pm2-to-bun-migration

Complete technical documentation for the process management and database driver migration in v7.1.0

<Note>
  **Historical Migration Documentation**

  This document describes the PM2 to Bun migration that occurred in v7.1.0 (December 2025). If you're installing claude-mem for the first time, this migration has already been completed and you can use the current Bun-based system documented in the main guides.

  This documentation is preserved for users upgrading from versions older than v7.1.0.
</Note>

# PM2 to Bun Migration: Complete Technical Documentation

**Version**: 7.1.0
**Date**: December 2025
**Migration Type**: Process Management (PM2 → Bun) + Database Driver (better-sqlite3 → bun:sqlite)

## Executive Summary

Claude-mem version 7.1.0 introduces two major architectural migrations:

1. **Process Management**: PM2 → Custom Bun-based ProcessManager
2. **Database Driver**: better-sqlite3 npm package → bun:sqlite runtime module

Both migrations are **automatic** and **transparent** to end users. The first time a hook fires after updating to 7.1.0+, the system performs a one-time cleanup of legacy PM2 processes and transitions to the new architecture.

### Key Benefits

* **Simplified Dependencies**: Removes PM2 and better-sqlite3 npm packages
* **Improved Cross-Platform Support**: Better Windows compatibility
* **Faster Installation**: No native module compilation required
* **Built-in Runtime**: Leverages Bun's built-in process management and SQLite
* **Reduced Complexity**: Custom ProcessManager is simpler than PM2 integration

### Migration Impact

* **Data Preservation**: User data, settings, and database remain unchanged
* **Automatic Cleanup**: Old PM2 processes automatically terminated (all platforms)
* **No User Action Required**: Migration happens automatically on first hook trigger
* **Backward Compatible**: SQLite database format unchanged (only driver changed)

## Architecture Comparison

### Old System (PM2-based)

<AccordionGroup>
  <Accordion title="Process Management (PM2)">
    **Component**: PM2 (Process Manager 2)

    * **Package**: `pm2` npm dependency
    * **Process Name**: `claude-mem-worker`
    * **Management**: External PM2 daemon manages lifecycle
    * **Discovery**: `pm2 list`, `pm2 describe` commands
    * **Auto-restart**: PM2 automatically restarts on crash
    * **Logs**: `~/.pm2/logs/claude-mem-worker-*.log`
    * **PID File**: `~/.pm2/pids/claude-mem-worker.pid`

    **Lifecycle Commands**:

    ```bash theme={null}
    pm2 start <script>           # Start worker
    pm2 stop claude-mem-worker   # Stop worker
    pm2 restart claude-mem-worker # Restart worker
    pm2 delete claude-mem-worker  # Remove from PM2
    pm2 logs claude-mem-worker    # View logs
    ```

    **Pain Points**:

    * Additional npm dependency required
    * PM2 daemon must be running
    * Potential conflicts with other PM2 processes
    * Windows compatibility issues
    * Complex configuration for simple use case
  </Accordion>

  <Accordion title="Database Driver (better-sqlite3)">
    **Component**: better-sqlite3

    * **Package**: `better-sqlite3` npm package (native module)
    * **Installation**: Requires native compilation (node-gyp)
    * **Windows**: Requires Visual Studio build tools + Python
    * **Import**: `import Database from 'better-sqlite3'`

    **Installation Requirements**:

    * Node.js development headers
    * C++ compiler (gcc/clang on Mac/Linux, MSVC on Windows)
    * Python (for node-gyp)
    * Windows: Visual Studio Build Tools
  </Accordion>
</AccordionGroup>

### New System (Bun-based)

<AccordionGroup>
  <Accordion title="Process Management (Custom ProcessManager)">
    **Component**: Custom ProcessManager (`src/services/process/ProcessManager.ts`)

    * **Package**: Built-in Bun APIs (no external dependency)
    * **Process Spawn**: `Bun.spawn()` with detached mode
    * **Management**: Direct process control via PID file
    * **Discovery**: PID file + process existence check + HTTP health check
    * **Auto-restart**: Hook-triggered restart on failure detection
    * **Logs**: `~/.claude-mem/logs/worker-YYYY-MM-DD.log`
    * **PID File**: `~/.claude-mem/.worker.pid`
    * **Port File**: `~/.claude-mem/.worker.port` (new)

    **Lifecycle Commands**:

    ```bash theme={null}
    npm run worker:start    # Start worker
    npm run worker:stop     # Stop worker
    npm run worker:restart  # Restart worker
    npm run worker:status   # Check status
    npm run worker:logs     # View logs
    ```

    **Core Mechanisms**:

    1. **PID File Management**:
       * File: `~/.claude-mem/.worker.pid`
       * Content: Process ID (e.g., "35557")
       * Validation: Process existence via `kill(pid, 0)` signal

    2. **Port File Management**:
       * File: `~/.claude-mem/.worker.port`
       * Content: Two lines (port number, PID)
       * Purpose: Track port binding and validate PID match

    3. **Health Checking**:
       * Layer 1: PID file exists?
       * Layer 2: Process alive? (`kill(pid, 0)`)
       * Layer 3: HTTP health check (`GET /health`)
       * All three must pass for "healthy" status

    **Advantages**:

    * No external dependencies
    * Simpler codebase (direct control)
    * Better error handling and validation
    * Platform-agnostic (Bun handles platform differences)
  </Accordion>

  <Accordion title="Database Driver (bun:sqlite)">
    **Component**: bun:sqlite

    * **Package**: Built into Bun runtime (no npm package)
    * **Installation**: None required (comes with Bun ≥1.0)
    * **Platform**: Works anywhere Bun works
    * **Import**: `import { Database } from 'bun:sqlite'`
    * **API**: Similar to better-sqlite3 (synchronous)

    **Installation Requirements**:

    * Bun ≥1.0 (automatically installed if missing)
    * No native compilation required
    * No platform-specific build tools needed

    **Compatibility**:

    * SQLite database format: **Unchanged**
    * Database file: `~/.claude-mem/claude-mem.db` (same location)
    * Query syntax: **Identical** (both use SQLite SQL)
  </Accordion>
</AccordionGroup>

## Migration Mechanics

### One-Time PM2 Cleanup

The migration system uses a marker-based approach to perform PM2 cleanup exactly once.

**Implementation**: `src/shared/worker-utils.ts:73-86`

```typescript theme={null}
// Clean up legacy PM2 (one-time migration)
const pm2MigratedMarker = join(DATA_DIR, '.pm2-migrated');

if (!existsSync(pm2MigratedMarker)) {
  try {
    spawnSync('pm2', ['delete', 'claude-mem-worker'], { stdio: 'ignore' });
    // Mark migration as complete
    writeFileSync(pm2MigratedMarker, new Date().toISOString(), 'utf-8');
    logger.debug('SYSTEM', 'PM2 cleanup completed and marked');
  } catch {
    // PM2 not installed or process doesn't exist - still mark as migrated
    writeFileSync(pm2MigratedMarker, new Date().toISOString(), 'utf-8');
  }
}
```

### Migration Trigger Points

<Steps>
  <Step title="Hook Execution">
    SessionStart, UserPromptSubmit, or PostToolUse hooks execute using new 7.1.0 code
  </Step>

  <Step title="Worker Status Check">
    `ensureWorkerRunning()` checks if `~/.claude-mem/.worker.pid` exists (it doesn't for first run after update)
  </Step>

  <Step title="Start Worker Decision">
    Worker not running → Call `startWorker()`
  </Step>

  <Step title="Migration Check">
    Check if `~/.claude-mem/.pm2-migrated` exists
  </Step>

  <Step title="PM2 Cleanup">
    Execute `pm2 delete claude-mem-worker` (errors ignored), create marker file
  </Step>

  <Step title="New Worker Start">
    Spawn new Bun-managed worker process with PID and port files
  </Step>
</Steps>

### Marker File

**Location**: `~/.claude-mem/.pm2-migrated`

**Content**: ISO 8601 timestamp

```
2025-12-13T00:18:39.673Z
```

**Purpose**:

* One-time migration flag
* Prevents repeated PM2 cleanup on every start
* Persists across restarts and reboots

**Lifecycle**:

* Created: First hook trigger after update to 7.1.0+ (all platforms)
* Updated: Never
* Deleted: Never (user could manually delete to force re-migration)

## User Experience Timeline

### First Session After Update

<Note>
  This is the critical migration moment. The process takes approximately 2-5 seconds.
</Note>

**Step-by-Step Execution**:

1. **Hook fires** (SessionStart most common)
2. **Worker status check**: No PID file → worker not running
3. **Migration check**: No marker file → run PM2 cleanup
4. **PM2 cleanup**: `pm2 delete claude-mem-worker` (old worker terminated)
5. **Marker creation**: `~/.claude-mem/.pm2-migrated` with timestamp
6. **New worker start**: Bun process spawned, PID/port files created
7. **Verification**: Process check + HTTP health check
8. **Hook completes**: Claude Code session starts normally

**User Observable Behavior**:

* Slight delay on first startup (PM2 cleanup + new worker spawn)
* No error messages (cleanup failures silently handled)
* Worker appears running via `npm run worker:status`
* Old PM2 worker no longer in `pm2 list`

### Subsequent Sessions

After migration completes, every hook trigger follows the fast path:

1. PID file exists? **YES**
2. Process alive? **YES**
3. HTTP health check? **SUCCESS**
4. Result: Worker already running, done (\~50ms)

No migration logic runs on subsequent sessions.

## Platform-Specific Behavior

### Platform Comparison

| Feature | macOS | Linux | Windows |
| - | - | - | - |
| PM2 Cleanup | Attempted | Attempted | Attempted |
| Marker File | Created | Created | Created |
| Process Signals | POSIX (native) | POSIX (native) | Bun abstraction |
| Bun Support | Full | Full | Full |
| PID File | Yes | Yes | Yes |
| Port File | Yes | Yes | Yes |
| Health Check | HTTP | HTTP | HTTP |
| Migration Delay | \~2-5s first time | \~2-5s first time | \~2-5s first time |

### Platform Notes

<Tabs>
  <Tab title="macOS">
    * POSIX signal handling works natively
    * Bun fully supported
    * No platform-specific workarounds needed
  </Tab>

  <Tab title="Linux">
    * Identical behavior to macOS
    * POSIX signal handling
    * Works on Ubuntu, Debian, RHEL, CentOS, Arch
    * Alpine may require glibc (not musl)
  </Tab>

  <Tab title="Windows">
    * PM2 cleanup now runs (safe due to try/catch)
    * Bun abstracts signal handling differences
    * Path module handles Windows separators
    * File locking handled by SQLite
  </Tab>
</Tabs>

## Observable Changes

### Command Changes

| Old (PM2) | New (Bun) | Notes |
| - | - | - |
| `pm2 list` | `npm run worker:status` | Shows worker status |
| `pm2 start <script>` | `npm run worker:start` | Start worker |
| `pm2 stop claude-mem-worker` | `npm run worker:stop` | Stop worker |
| `pm2 restart claude-mem-worker` | `npm run worker:restart` | Restart worker |
| `pm2 delete claude-mem-worker` | `npm run worker:stop` | Remove worker |
| `pm2 logs claude-mem-worker` | `npm run worker:logs` | View logs |
| `pm2 describe claude-mem-worker` | `npm run worker:status` | Detailed status |
| `pm2 monit` | No equivalent | PM2-specific monitoring |

### File Location Changes

**Logs**:

```
Old: ~/.pm2/logs/claude-mem-worker-out.log
     ~/.pm2/logs/claude-mem-worker-error.log

New: ~/.claude-mem/logs/worker-YYYY-MM-DD.log
```

**PID Files**:

```
Old: ~/.pm2/pids/claude-mem-worker.pid

New: ~/.claude-mem/.worker.pid
```

**Process State**:

```
Old: PM2 daemon memory (pm2 save)

New: ~/.claude-mem/.worker.pid
     ~/.claude-mem/.worker.port
     ~/.claude-mem/.pm2-migrated (all platforms)
```

**Database** (unchanged):

```
Same: ~/.claude-mem/claude-mem.db
```

### User-Visible Changes

**Before Update**:

```bash theme={null}
$ pm2 list
┌────┬────────────────────┬─────────┬─────────┬──────────┐
│ id │ name               │ status  │ restart │ uptime   │
├────┼────────────────────┼─────────┼─────────┼──────────┤
│ 0  │ claude-mem-worker  │ online  │ 0       │ 2d 5h    │
└────┴────────────────────┴─────────┴─────────┴──────────┘
```

**After Update**:

```bash theme={null}
$ pm2 list
# Empty - worker no longer managed by PM2

$ npm run worker:status
Worker is running
PID: 35557
Port: 37777
Uptime: 2h 15m
```

### Orphaned Files

After migration, these PM2 files may remain (safe to delete):

```
~/.pm2/                    # Entire PM2 directory
~/.pm2/logs/               # Old logs
~/.pm2/pids/               # Old PID files
~/.pm2/pm2.log             # PM2 daemon log
~/.pm2/dump.pm2            # PM2 process dump
```

**Cleanup (optional)**:

```bash theme={null}
# Remove PM2 entirely (if not used for other processes)
pm2 kill
rm -rf ~/.pm2

# Or just remove claude-mem logs
rm -f ~/.pm2/logs/claude-mem-worker-*.log
rm -f ~/.pm2/pids/claude-mem-worker.pid
```

## File System State

### State Directory Structure

**Before Migration** (PM2 system):

```
~/.claude-mem/
├── claude-mem.db          # Database (unchanged)
├── chroma/                # Vector embeddings (unchanged)
├── logs/                  # Application logs (unchanged)
└── settings.json          # User settings (unchanged)

~/.pm2/
├── logs/
│   ├── claude-mem-worker-out.log
│   └── claude-mem-worker-error.log
├── pids/
│   └── claude-mem-worker.pid
└── pm2.log
```

**After Migration** (Bun system):

```
~/.claude-mem/
├── claude-mem.db          # Database (same file)
├── chroma/                # Vector embeddings (unchanged)
├── logs/
│   └── worker-2025-12-13.log  # New log format
├── settings.json          # User settings (unchanged)
├── .worker.pid            # NEW: Process ID
├── .worker.port           # NEW: Port + PID
└── .pm2-migrated          # NEW: Migration marker (all platforms)

~/.pm2/                    # Orphaned (safe to delete)
├── logs/                  # Old logs (no longer written)
├── pids/                  # Old PID (no longer updated)
└── pm2.log                # PM2 daemon log (not used)
```

## Edge Cases and Troubleshooting

### Scenario 1: Migration Fails (PM2 Still Running)

<Warning>
  This is rare but can happen if PM2 has watch mode enabled or the process is manually restarted.
</Warning>

**Symptoms**:

* `pm2 list` still shows `claude-mem-worker`
* Port conflict errors in logs
* Worker fails to start

**Resolution**:

```bash theme={null}
# Manual cleanup
pm2 delete claude-mem-worker
pm2 save  # Persist the deletion

# Force re-migration (optional)
rm ~/.claude-mem/.pm2-migrated

# Restart worker
npm run worker:restart
```

### Scenario 2: Stale PID File (Process Dead)

**Symptoms**:

* `npm run worker:status` shows "not running"
* `.worker.pid` file exists
* Process ID doesn't exist

**Automatic Recovery**: Next hook trigger detects dead process and starts a fresh worker.

**Manual Resolution**:

```bash theme={null}
rm ~/.claude-mem/.worker.pid
rm ~/.claude-mem/.worker.port
npm run worker:start
```

### Scenario 3: Port Already in Use

**Error**: `EADDRINUSE: address already in use`

**Resolution**:

```bash theme={null}
# Check what's using the port
lsof -i :37777

# Kill the process
kill -9 <PID>

# Restart worker
npm run worker:restart
```

### Common Error Messages

| Error | Cause | Resolution |
| - | - | - |
| `EADDRINUSE` | Port already in use | `lsof -i :37777` then kill conflicting process |
| `No such process` | Stale PID file | Automatic cleanup on next hook trigger |
| `pm2: command not found` | PM2 not installed | None needed (error is caught and ignored) |
| `Invalid port X` | Port validation failed | Update `CLAUDE_MEM_WORKER_PORT` in settings |

## Developer Notes

### Testing the Migration

```bash theme={null}
# 1. Install old version (with PM2)
git checkout <pre-7.1.0-tag>
npm install && npm run build && npm run sync-marketplace

# 2. Start PM2 worker
pm2 start plugin/scripts/worker-cli.js --name claude-mem-worker

# 3. Update to new version
git checkout main
npm install && npm run build && npm run sync-marketplace

# 4. Trigger hook
node plugin/scripts/session-start-hook.js

# 5. Verify migration
pm2 list  # Should NOT show claude-mem-worker
cat ~/.claude-mem/.pm2-migrated  # Should exist
npm run worker:status  # Should show Bun worker running
```

### Architecture Decisions

**Why Custom ProcessManager Instead of PM2?**

1. **Simplicity**: Direct control, no external daemon
2. **Dependencies**: Remove npm dependency
3. **Cross-platform**: Bun handles platform differences
4. **Bundle Size**: Reduce plugin package size
5. **Control**: Fine-grained error handling and validation

**Why One-Time Marker Instead of Always Running PM2 Delete?**

1. **Performance**: Avoid unnecessary process spawning
2. **Idempotency**: Migration runs exactly once
3. **Debugging**: Timestamp shows when migration occurred
4. **Simplicity**: Clear migration state

**Why Run PM2 Cleanup on All Platforms?**

1. **Quality Migration**: Clean up orphaned processes
2. **Consistency**: Same behavior across all platforms
3. **Safety**: Error handling already in place (try/catch)
4. **No Downside**: If PM2 not installed, error is caught and ignored

## Summary

The migration from PM2 to Bun-based ProcessManager is a **one-time, automatic, transparent** transition that:

1. **Removes external dependencies** (PM2, better-sqlite3)
2. **Simplifies architecture** (direct process control)
3. **Improves cross-platform support** (especially Windows)
4. **Preserves user data** (database, settings, logs unchanged)
5. **Requires no user action** (automatic on first hook trigger)

**Key Migration Moment**: First hook trigger after update to 7.1.0+
**Duration**: \~2-5 seconds (one-time delay)
**Impact**: Seamless transition, user-invisible
**Rollback**: Not needed (migration is forward-only, safe)

For most users, the migration will be completely transparent - they'll see no errors, no data loss, and experience improved reliability and simpler troubleshooting going forward.


# Search Architecture
Source: https://docs.claude-mem.ai/architecture/search-architecture

MCP tools with 3-layer workflow for token-efficient memory retrieval

# Search Architecture

Claude-mem uses an **MCP-based search architecture** that provides intelligent memory retrieval through 4 streamlined tools following a 3-layer workflow pattern.

## Overview

**Architecture**: MCP Tools → MCP Protocol → HTTP API → Worker Service

**Key Components**:

1. **MCP Tools** (4 tools) - `search`, `timeline`, `get_observations`, `important_workflow`
2. **MCP Server** (`plugin/scripts/mcp-server.cjs`) - Thin wrapper over HTTP API
3. **HTTP API Endpoints** - Fast search operations on the configured Worker Service port
4. **Worker Service** - Express.js server with FTS5 full-text search
5. **SQLite Database** - Persistent storage with FTS5 virtual tables
6. **Chroma Vector DB** - Semantic search with hybrid retrieval

SQLite holds the current memory content; Chroma holds its search projection.
Live indexing and startup backfill share a writer per collection, record type,
and SQLite ID. That writer covers obsolete-fragment cleanup, every document
batch, and the sync checkpoint. Backfill and cloud-sync forwards re-read the
SQLite row after obtaining their turn, so a cached older snapshot cannot
overwrite a completed revision or restore a previous project after a remap.
Other live callers may supply their immutable new-row content directly.
Different records can still index concurrently. This ordering is within one
worker process; it does not provide a transaction across SQLite and Chroma.
SQL mutations that happen after that read still need their own reindexing path.

**Token Efficiency**: \~10x savings through 3-layer workflow pattern

## How It Works

### 1. User Query

Claude has access to 4 MCP tools. When searching memory, Claude follows the 3-layer workflow:

```
Step 1: search(query="authentication bug", type="bugfix", limit=10)
Step 2: timeline(anchor=<observation_id>, depth_before=3, depth_after=3)
Step 3: get_observations(ids=[123, 456, 789])
```

### 2. MCP Protocol

MCP server receives tool call via JSON-RPC over stdio:

```json theme={null}
{
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "authentication bug",
      "type": "bugfix",
      "limit": 10
    }
  }
}
```

### 3. HTTP API Call

MCP server translates to HTTP request:

```typescript theme={null}
const workerPort = process.env.CLAUDE_MEM_WORKER_PORT ?? "<worker-port>";
const workerBaseUrl = `http://127.0.0.1:${workerPort}`;
const url = `${workerBaseUrl}/api/search?query=authentication%20bug&type=bugfix&limit=10`;
const response = await fetch(url);
```

### 4. Worker Processing

Worker service executes FTS5 query:

```sql theme={null}
SELECT * FROM observations_fts
WHERE observations_fts MATCH ?
AND type = 'bugfix'
ORDER BY rank
LIMIT 10
```

### 5. Results Returned

Worker returns structured data → MCP server → Claude:

```json theme={null}
{
  "content": [{
    "type": "text",
    "text": "| ID | Time | Title | Type |\n|---|---|---|---|\n| #123 | 2:15 PM | Fixed auth token expiry | bugfix |"
  }]
}
```

### 6. Claude Processes Results

Claude reviews the index, decides which observations are relevant, and can:

* Use `timeline` to get context
* Use `get_observations` to fetch full details for selected IDs

## The 4 MCP Tools

### `important_workflow` - Workflow Documentation

Always visible to Claude. Explains the 3-layer workflow pattern.

**Description:**

```
3-LAYER WORKFLOW (ALWAYS FOLLOW):
1. search(query) → Get index with IDs (~50-100 tokens/result)
2. timeline(anchor=ID) → Get context around interesting results
3. get_observations([IDs]) → Fetch full details ONLY for filtered IDs
NEVER fetch full details without filtering first. 10x token savings.
```

**Purpose:** Ensures Claude follows token-efficient pattern

### `search` - Search Memory Index

**Tool Definition:**

```typescript theme={null}
{
  name: 'search',
  description: 'Step 1: Search memory. Returns index with IDs. Params: query, limit, project, type, obs_type, dateStart, dateEnd, offset, orderBy',
  inputSchema: {
    type: 'object',
    properties: {},
    additionalProperties: true  // Accepts any parameters
  }
}
```

**HTTP Endpoint:** `GET /api/search`

**Parameters:**

* `query` - Full-text search query
* `limit` - Maximum results (default: 20)
* `type` - Filter by observation type
* `project` - Filter by project name
* `dateStart`, `dateEnd` - Date range filters
* `offset` - Pagination offset
* `orderBy` - Sort order

**Returns:** Compact index with IDs, titles, dates, types (\~50-100 tokens per result), grouped under day headers (`### <date>`) so every served result carries its age. Day groups follow relevance order, not chronological order, so the highest-ranked match stays first even if a lower-ranked match is more recent.

### `timeline` - Get Chronological Context

**Tool Definition:**

```typescript theme={null}
{
  name: 'timeline',
  description: 'Step 2: Get context around results. Params: anchor (observation ID) OR query (finds anchor automatically), depth_before, depth_after, project',
  inputSchema: {
    type: 'object',
    properties: {},
    additionalProperties: true
  }
}
```

**HTTP Endpoint:** `GET /api/timeline`

**Parameters:**

* `anchor` - Observation ID to center timeline around (optional if query provided)
* `query` - Search query to find anchor automatically (optional if anchor provided)
* `depth_before` - Number of observations before anchor (default: 3)
* `depth_after` - Number of observations after anchor (default: 3)
* `project` - Filter by project name

**Returns:** Chronological view showing what happened before/during/after

### `get_observations` - Fetch Full Details

**Tool Definition:**

```typescript theme={null}
{
  name: 'get_observations',
  description: 'Step 3: Fetch full details for filtered IDs. Params: ids (array of observation IDs, required), orderBy, limit, project',
  inputSchema: {
    type: 'object',
    properties: {
      ids: {
        type: 'array',
        items: { type: 'number' },
        description: 'Array of observation IDs to fetch (required)'
      }
    },
    required: ['ids'],
    additionalProperties: true
  }
}
```

**HTTP Endpoint:** `POST /api/observations/batch`

**Body:**

```json theme={null}
{
  "ids": [123, 456, 789],
  "orderBy": "date_desc",
  "project": "my-app"
}
```

**Returns:** Complete observation details (\~500-1,000 tokens per observation)

## MCP Server Implementation

**Location:** `/Users/YOUR_USERNAME/.claude/plugins/marketplaces/thedotmack/plugin/scripts/mcp-server.cjs`

**Role:** Thin wrapper that translates MCP protocol to HTTP API calls

**Key Characteristics:**

* \~312 lines of code (reduced from \~2,718 lines in old implementation)
* No business logic - just protocol translation
* Single source of truth: Worker HTTP API
* Simple schemas with `additionalProperties: true`

**Handler Example:**

```typescript theme={null}
{
  name: 'search',
  handler: async (args: any) => {
    const endpoint = '/api/search';
    const searchParams = new URLSearchParams();

    for (const [key, value] of Object.entries(args)) {
      searchParams.append(key, String(value));
    }

    const workerPort = process.env.CLAUDE_MEM_WORKER_PORT ?? "<worker-port>";
    const workerBaseUrl = `http://127.0.0.1:${workerPort}`;
    const url = `${workerBaseUrl}${endpoint}?${searchParams}`;
    const response = await fetch(url);
    return await response.json();
  }
}
```

## Worker HTTP API

**Location:** `src/services/worker-service.ts`

**Port:** Configured worker port. The default is per-user (`37700 + (uid % 100)`) and can be overridden with `CLAUDE_MEM_WORKER_PORT`.

**Search Endpoints:**

```typescript theme={null}
GET  /api/search           # Main search (used by MCP search tool)
GET  /api/timeline         # Timeline context (used by MCP timeline tool)
POST /api/observations/batch  # Fetch by IDs (used by MCP get_observations tool)
GET  /api/health           # Health check
```

**Database Access:**

* Uses `SessionSearch` service for FTS5 queries
* Uses `SessionStore` for structured queries
* Hybrid search with ChromaDB for semantic similarity

**FTS5 Full-Text Search:**

```typescript theme={null}
// search tool → HTTP GET → FTS5 query
SELECT * FROM observations_fts
WHERE observations_fts MATCH ?
AND type = ?
AND date >= ? AND date <= ?
ORDER BY rank
LIMIT ? OFFSET ?
```

## The 3-Layer Workflow Pattern

### Design Philosophy

The 3-layer workflow embodies **progressive disclosure** - a core principle of claude-mem's architecture.

**Layer 1: Index (Search)**

* **What:** Compact table with IDs, titles, dates, types
* **Cost:** \~50-100 tokens per result
* **Purpose:** Survey what exists before committing tokens
* **Decision Point:** "Which observations are relevant?"

**Layer 2: Context (Timeline)**

* **What:** Chronological view of observations around a point
* **Cost:** Variable based on depth
* **Purpose:** Understand narrative arc, see what led to/from a point
* **Decision Point:** "Do I need full details?"

**Layer 3: Details (Get Observations)**

* **What:** Complete observation data (narrative, facts, files, concepts)
* **Cost:** \~500-1,000 tokens per observation
* **Purpose:** Deep dive on validated, relevant observations
* **Decision Point:** "Apply knowledge to current task"

### Token Efficiency

**Traditional RAG Approach:**

```
Fetch 20 observations upfront: 10,000-20,000 tokens
Relevance: ~10% (only 2 observations actually useful)
Waste: 18,000 tokens on irrelevant context
```

**3-Layer Workflow:**

```
Step 1: search (20 results)        ~1,000-2,000 tokens
Step 2: Review index, filter to 3 relevant IDs
Step 3: get_observations (3 IDs)   ~1,500-3,000 tokens
Total: 2,500-5,000 tokens (50-75% savings)
```

**10x Savings:** By filtering at index level before fetching full details

## Architecture Evolution

### Before: Complex MCP Implementation

**Approach:** 9 MCP tools with detailed parameter schemas

**Token Cost:** \~2,500 tokens in tool definitions per session

* `search_observations` - Full-text search
* `find_by_type` - Filter by type
* `find_by_file` - Filter by file
* `find_by_concept` - Filter by concept
* `get_recent_context` - Recent sessions
* `get_observation` - Fetch single observation
* `get_session` - Fetch session
* `get_prompt` - Fetch prompt
* `help` - API documentation

**Problems:**

* Overlapping operations (search\_observations vs find\_by\_type)
* Complex parameter schemas
* No built-in workflow guidance
* High token cost at session start

**Code Size:** \~2,718 lines in mcp-server.ts

### After: Streamlined MCP Implementation

**Approach:** 4 MCP tools following 3-layer workflow

**Token Cost:** \~312 lines of code, simplified tool definitions

**Tools:**

1. `important_workflow` - Workflow guidance (always visible)
2. `search` - Step 1 (index)
3. `timeline` - Step 2 (context)
4. `get_observations` - Step 3 (details)

**Benefits:**

* Progressive disclosure built into tool design
* No overlapping operations
* Simple schemas (`additionalProperties: true`)
* Clear workflow pattern
* \~10x token savings

**Code Size:** \~312 lines in mcp-server.ts (88% reduction)

### Key Insight

**Before:** Progressive disclosure was something Claude had to remember

**After:** Progressive disclosure is enforced by tool design itself

The 3-layer workflow pattern makes it structurally difficult to waste tokens:

* Can't fetch details without first getting IDs from search
* Can't search without seeing workflow reminder (`important_workflow`)
* Timeline provides middle ground between index and full details

## Configuration

### Claude Desktop

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "mcp-search": {
      "command": "node",
      "args": [
        "/Users/YOUR_USERNAME/.claude/plugins/marketplaces/thedotmack/plugin/scripts/mcp-server.cjs"
      ]
    }
  }
}
```

### Claude Code

MCP server is automatically configured via plugin installation. No manual setup required.

**Both clients use the same MCP tools** - the architecture works identically for Claude Desktop and Claude Code.

## Security

### FTS5 Injection Prevention

All search queries are escaped before FTS5 processing:

```typescript theme={null}
function escapeFTS5Query(query: string): string {
  return query.replace(/"/g, '""');
}
```

**Testing:** 332 injection attack tests covering special characters, SQL keywords, quote escaping, and boolean operators.

### MCP Protocol Security

* Stdio transport (no network exposure)
* Local-only HTTP API on the configured worker port
* No authentication needed (local development only)

## Performance

**FTS5 Full-Text Search:** Sub-10ms for typical queries

**MCP Overhead:** Minimal - simple protocol translation

**Caching:** HTTP layer allows response caching (future enhancement)

**Pagination:** Efficient with offset/limit

**Batching:** `get_observations` accepts multiple IDs in single call

## Benefits Over Alternative Approaches

### vs. Traditional RAG

**Traditional RAG:**

* Fetches everything upfront
* High token cost
* Low relevance ratio

**3-Layer MCP:**

* Fetches only what's needed
* \~10x token savings
* 100% relevance (Claude chooses what to fetch)

### vs. Previous MCP Implementation (v5.x)

**Previous (9 tools):**

* Complex schemas
* Overlapping operations
* No workflow guidance
* \~2,500 tokens in definitions

**Current (4 tools):**

* Simple schemas
* Clear workflow
* Built-in guidance
* \~312 lines of code

### vs. Skill-Based Approach (Previously)

**Skill approach:**

* Required separate skill files
* HTTP API called directly via curl
* Progressive disclosure through skill loading

**MCP approach:**

* Native MCP protocol (better Claude integration)
* Cleaner architecture (protocol translation layer)
* Works with both Claude Desktop and Claude Code
* Simpler to maintain (no skill files)

**Migration:** Skill-based search was removed in favor of streamlined MCP architecture.

## Troubleshooting

For direct API checks, set the worker port first:

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

### MCP Server Not Connected

**Symptoms:** Tools not appearing in Claude

**Solution:**

1. Check MCP server path in configuration
2. Verify worker service is running: `curl http://127.0.0.1:$WORKER_PORT/api/health`
3. Restart Claude Desktop/Code

### Worker Service Not Running

**Symptoms:** MCP tools fail with connection errors

**Solution:**

```bash theme={null}
npm run worker:status       # Check status
npm run worker:restart      # Restart worker
npm run worker:logs         # View logs
```

### Empty Search Results

**Symptoms:** search() returns no results

**Troubleshooting:**

1. Test API directly: `curl "http://127.0.0.1:$WORKER_PORT/api/search?query=test"`
2. Check database: `ls ~/.claude-mem/claude-mem.db`
3. Verify observations exist: `curl "http://127.0.0.1:$WORKER_PORT/api/health"`

## Next Steps

* [Memory Search Usage](/usage/search-tools) - User guide with examples
* [Progressive Disclosure](/progressive-disclosure) - Philosophy behind 3-layer workflow
* [Worker Service Architecture](/architecture/worker-service) - HTTP API details
* [Database Schema](/architecture/database) - FTS5 tables and indexes


# Worker Service
Source: https://docs.claude-mem.ai/architecture/worker-service

HTTP API and Bun process management

# Worker Service

The worker service is a long-running HTTP API built with Express.js and managed natively by Bun. It processes observations through the Claude Agent SDK separately from hook execution to prevent timeout issues.

## Overview

* **Technology**: Express.js HTTP server
* **Runtime**: Bun (auto-installed if missing)
* **Process Manager**: Native Bun process management via ProcessManager
* **Port**: Per-user default `37700 + (uid % 100)` (override with `CLAUDE_MEM_WORKER_PORT`). The active port is stored in `~/.claude-mem/settings.json` and reported by `GET /api/health`.
* **Location**: `src/services/worker-service.ts`
* **Built Output**: `plugin/scripts/worker-service.cjs`
* **Model**: Configurable via `CLAUDE_MEM_MODEL` (default: `claude-haiku-4-5-20251001`)

## Session Buffer Teardown

Deleting or immediately removing a session logs a `WARN` with `pendingCount`
before discarding a nonempty in-memory buffer. Claimed but unconfirmed messages
still count; confirmed messages are no longer buffered.

Worker shutdown also logs `pendingCountAtShutdownStart`, the total for active
sessions before cleanup begins. This is a startup snapshot, not the number
ultimately discarded. Empty buffers do not emit disposal warnings.

## REST API Endpoints

The worker service exposes 22 HTTP endpoints organized into six categories:

### Viewer & Health Endpoints

#### 1. Viewer UI

```
GET /
```

**Purpose**: Serves the web-based viewer UI (v5.1.0+)

**Response**: HTML page with embedded React application

**Features**:

* Real-time memory stream visualization
* Infinite scroll pagination
* Project filtering
* SSE-based live updates
* Theme toggle (light/dark mode) as of v5.1.2

#### 2. Health Check

```
GET /health
```

**Purpose**: Worker health status check

**Response**:

```json theme={null}
{
  "status": "ok",
  "uptime": 12345,
  "port": 37742
}
```

The `port` value is the actual worker port for the current user — per-user default `37700 + (uid % 100)`, or whatever `CLAUDE_MEM_WORKER_PORT` is set to. The example above is illustrative; your value will differ.

#### 3. Server-Sent Events Stream

```
GET /stream
```

**Purpose**: Real-time updates for viewer UI

**Response**: SSE stream with events:

* `observation-created`: New observation added
* `session-summary-created`: New summary generated
* `user-prompt-created`: New prompt recorded

**Event Format**:

```
event: observation-created
data: {"id": 123, "title": "...", ...}
```

### Data Retrieval Endpoints

#### 4. Get Prompts

```
GET /api/prompts?project=my-project&limit=20&offset=0
```

**Purpose**: Retrieve paginated user prompts

**Query Parameters**:

* `project` (optional): Filter by project name
* `limit` (default: 20): Number of results
* `offset` (default: 0): Pagination offset

**Response**:

```json theme={null}
{
  "prompts": [{
    "id": 1,
    "session_id": "abc123",
    "prompt": "User's prompt text",
    "prompt_number": 1,
    "created_at": "2025-11-06T10:30:00Z"
  }],
  "total": 150,
  "hasMore": true
}
```

#### 5. Get Observations

```
GET /api/observations?project=my-project&limit=20&offset=0
```

**Purpose**: Retrieve paginated observations

**Query Parameters**:

* `project` (optional): Filter by project name
* `limit` (default: 20): Number of results
* `offset` (default: 0): Pagination offset

**Response**:

```json theme={null}
{
  "observations": [{
    "id": 123,
    "title": "Fix authentication bug",
    "type": "bugfix",
    "narrative": "...",
    "created_at": "2025-11-06T10:30:00Z"
  }],
  "total": 500,
  "hasMore": true
}
```

#### 6. Get Summaries

```
GET /api/summaries?project=my-project&limit=20&offset=0
```

**Purpose**: Retrieve paginated session summaries

**Query Parameters**:

* `project` (optional): Filter by project name
* `limit` (default: 20): Number of results
* `offset` (default: 0): Pagination offset

**Response**:

```json theme={null}
{
  "summaries": [{
    "id": 456,
    "session_id": "abc123",
    "request": "User's original request",
    "completed": "Work finished",
    "created_at": "2025-11-06T10:30:00Z"
  }],
  "total": 100,
  "hasMore": true
}
```

#### 7. Get Observation by ID

```
GET /api/observation/:id
```

**Purpose**: Retrieve a single observation by its ID

**Path Parameters**:

* `id` (required): Observation ID

**Response**:

```json theme={null}
{
  "id": 123,
  "sdk_session_id": "abc123",
  "project": "my-project",
  "type": "bugfix",
  "title": "Fix authentication bug",
  "narrative": "...",
  "created_at": "2025-11-06T10:30:00Z",
  "created_at_epoch": 1730886600000
}
```

**Error Response** (404):

```json theme={null}
{
  "error": "Observation #123 not found"
}
```

#### 8. Get Observations by IDs (Batch)

```
POST /api/observations/batch
```

**Purpose**: Retrieve multiple observations by their IDs in a single request

**Request Body**:

```json theme={null}
{
  "ids": [123, 456, 789],
  "orderBy": "date_desc",
  "limit": 10,
  "project": "my-project"
}
```

**Body Parameters**:

* `ids` (required): Array of observation IDs
* `orderBy` (optional): Sort order - `date_desc` or `date_asc` (default: `date_desc`)
* `limit` (optional): Maximum number of results to return
* `project` (optional): Filter by project name

**Response**:

```json theme={null}
[
  {
    "id": 789,
    "sdk_session_id": "abc123",
    "project": "my-project",
    "type": "feature",
    "title": "Add new feature",
    "narrative": "...",
    "created_at": "2025-11-06T12:00:00Z",
    "created_at_epoch": 1730891400000
  },
  {
    "id": 456,
    "sdk_session_id": "abc124",
    "project": "my-project",
    "type": "bugfix",
    "title": "Fix authentication bug",
    "narrative": "...",
    "created_at": "2025-11-06T10:30:00Z",
    "created_at_epoch": 1730886600000
  }
]
```

**Error Responses**:

* `400 Bad Request`: `{"error": "ids must be an array of numbers"}`
* `400 Bad Request`: `{"error": "All ids must be integers"}`

**Use Case**: This endpoint is used by the `get_observations` MCP tool to efficiently retrieve multiple observations in a single request, avoiding the overhead of multiple individual requests.

#### 9. Get Session by ID

```
GET /api/session/:id
```

**Purpose**: Retrieve a single session by its ID

**Path Parameters**:

* `id` (required): Session ID

**Response**:

```json theme={null}
{
  "id": 456,
  "sdk_session_id": "abc123",
  "project": "my-project",
  "request": "User's original request",
  "completed": "Work finished",
  "created_at": "2025-11-06T10:30:00Z"
}
```

**Error Response** (404):

```json theme={null}
{
  "error": "Session #456 not found"
}
```

#### 10. Get Prompt by ID

```
GET /api/prompt/:id
```

**Purpose**: Retrieve a single user prompt by its ID

**Path Parameters**:

* `id` (required): Prompt ID

**Response**:

```json theme={null}
{
  "id": 1,
  "session_id": "abc123",
  "prompt": "User's prompt text",
  "prompt_number": 1,
  "created_at": "2025-11-06T10:30:00Z"
}
```

**Error Response** (404):

```json theme={null}
{
  "error": "Prompt #1 not found"
}
```

#### 12. Get Stats

```
GET /api/stats
```

**Purpose**: Get database statistics by project

**Response**:

```json theme={null}
{
  "byProject": {
    "my-project": {
      "observations": 245,
      "summaries": 12,
      "prompts": 48
    },
    "other-project": {
      "observations": 156,
      "summaries": 8,
      "prompts": 32
    }
  },
  "total": {
    "observations": 401,
    "summaries": 20,
    "prompts": 80,
    "sessions": 20
  }
}
```

#### 13. Get Projects

```
GET /api/projects
```

**Purpose**: Get list of distinct projects from observations

**Response**:

```json theme={null}
{
  "projects": ["my-project", "other-project", "test-project"]
}
```

### Settings Endpoints

#### 14. Get Settings

```
GET /api/settings
```

**Purpose**: Retrieve user settings

**Response**:

```json theme={null}
{
  "sidebarOpen": true,
  "selectedProject": "my-project",
  "theme": "dark"
}
```

#### 15. Save Settings

```
POST /api/settings
```

**Purpose**: Persist user settings

**Request Body**:

```json theme={null}
{
  "sidebarOpen": false,
  "selectedProject": "other-project",
  "theme": "light"
}
```

**Response**:

```json theme={null}
{
  "success": true
}
```

### Queue Management Endpoints

#### 16. Get Pending Queue Status

```
GET /api/pending-queue
```

**Purpose**: View current processing queue status and identify stuck messages

**Response**:

```json theme={null}
{
  "queue": {
    "messages": [
      {
        "id": 123,
        "session_db_id": 45,
        "claude_session_id": "abc123",
        "message_type": "observation",
        "status": "pending",
        "retry_count": 0,
        "created_at_epoch": 1730886600000,
        "started_processing_at_epoch": null,
        "completed_at_epoch": null
      }
    ],
    "totalPending": 5,
    "totalProcessing": 2,
    "totalFailed": 0,
    "stuckCount": 1
  },
  "recentlyProcessed": [
    {
      "id": 122,
      "session_db_id": 44,
      "status": "processed",
      "completed_at_epoch": 1730886500000
    }
  ],
  "sessionsWithPendingWork": [44, 45, 46]
}
```

**Status Definitions**:

* `pending`: Message queued, not yet processed
* `processing`: Message currently being processed by SDK agent
* `processed`: Message completed successfully
* `failed`: Message failed after max retry attempts (3 by default)

**Stuck Detection**: Messages in `processing` status for >5 minutes are considered stuck and included in `stuckCount`

**Use Case**: Check queue health after worker crashes or restarts to identify unprocessed observations

#### 17. Trigger Manual Recovery

```
POST /api/pending-queue/process
```

**Purpose**: Manually trigger processing of pending queues (replaces automatic recovery in v5.x+)

**Request Body**:

```json theme={null}
{
  "sessionLimit": 10
}
```

**Body Parameters**:

* `sessionLimit` (optional): Maximum number of sessions to process (default: 10, max: 100)

**Response**:

```json theme={null}
{
  "success": true,
  "totalPendingSessions": 15,
  "sessionsStarted": 10,
  "sessionsSkipped": 2,
  "startedSessionIds": [44, 45, 46, 47, 48, 49, 50, 51, 52, 53]
}
```

**Response Fields**:

* `totalPendingSessions`: Total sessions with pending messages in database
* `sessionsStarted`: Number of sessions we started processing this request
* `sessionsSkipped`: Sessions already actively processing (not restarted)
* `startedSessionIds`: Database IDs of sessions started

**Behavior**:

* Processes up to `sessionLimit` sessions with pending work
* Skips sessions already actively processing (prevents duplicate agents)
* Starts non-blocking SDK agents for each session
* Returns immediately with status (processing continues in background)

**Use Case**: Manually recover stuck observations after worker crashes, or when automatic recovery was disabled

**Recovery Strategy Note**: As of v5.x, automatic recovery on worker startup is disabled by default. Users must manually trigger recovery using this endpoint or the CLI tool (`bun scripts/check-pending-queue.ts`) to maintain explicit control over reprocessing.

### Session Management Endpoints

#### 19. Initialize Session

```
POST /sessions/:sessionDbId/init
```

**Request Body**:

```json theme={null}
{
  "sdk_session_id": "abc-123",
  "project": "my-project"
}
```

**Response**:

```json theme={null}
{
  "success": true,
  "session_id": "abc-123"
}
```

#### 20. Add Observation

```
POST /sessions/:sessionDbId/observations
```

**Request Body**:

```json theme={null}
{
  "tool_name": "Read",
  "tool_input": {...},
  "tool_result": "...",
  "correlation_id": "xyz-789"
}
```

**Response**:

```json theme={null}
{
  "success": true,
  "observation_id": 123
}
```

#### 21. Generate Summary

```
POST /sessions/:sessionDbId/summarize
```

**Request Body**:

```json theme={null}
{
  "trigger": "stop"
}
```

**Response**:

```json theme={null}
{
  "success": true,
  "summary_id": 456
}
```

#### 22. Session Status

```
GET /sessions/:sessionDbId/status
```

**Response**:

```json theme={null}
{
  "session_id": "abc-123",
  "status": "active",
  "observation_count": 42,
  "summary_count": 1
}
```

#### 23. Delete Session

```
DELETE /sessions/:sessionDbId
```

**Response**:

```json theme={null}
{
  "success": true
}
```

**Note**: As of v4.1.0, the cleanup hook no longer calls this endpoint. Sessions are marked complete instead of deleted to allow graceful worker shutdown.

## Bun Process Management

### Overview

The worker is managed by the native `ProcessManager` class which handles:

* Process spawning with Bun runtime
* PID file tracking at `~/.claude-mem/worker.pid`
* Health checks with automatic retry
* Graceful shutdown with SIGTERM/SIGKILL fallback

### Commands

```bash theme={null}
# Start worker (auto-starts on first session)
npm run worker:start

# Stop worker
npm run worker:stop

# Restart worker
npm run worker:restart

# View logs
npm run worker:logs

# Check status
npm run worker:status
```

### Auto-Start Behavior

The worker service auto-starts when the SessionStart hook fires. Manual start is optional.

### Bun Requirement

Bun is required to run the worker service. If Bun is not installed, `npx claude-mem install` (and `npx claude-mem repair`) installs it globally during setup, with a visible clack spinner:

* **Windows**: `powershell -c "irm bun.sh/install.ps1 | iex"`
* **macOS/Linux**: `curl -fsSL https://bun.sh/install | bash`

You can also install manually via:

* `winget install Oven-sh.Bun` (Windows)
* `brew install oven-sh/bun/bun` (macOS)

## Claude Agent SDK Integration

The worker service routes observations to the Claude Agent SDK for AI-powered processing:

### Processing Flow

1. **Observation Queue**: Observations accumulate in memory
2. **SDK Processing**: Observations sent to Claude via Agent SDK
3. **XML Parsing**: Responses parsed for structured data
4. **Database Storage**: Processed observations stored in SQLite

### SDK Components

* **Prompts** (`src/sdk/prompts.ts`): Builds XML-structured prompts
* **Parser** (`src/sdk/parser.ts`): Parses Claude's XML responses
* **Worker** (`src/sdk/worker.ts`): Main SDK agent loop

### Model Configuration

Set the Claude model used for compression via environment variable or `~/.claude-mem/settings.json`:

```bash theme={null}
export CLAUDE_MEM_MODEL=claude-haiku-4-5-20251001
```

Allowed values:

* `claude-haiku-4-5-20251001` - default, fastest (best for compression)
* `claude-sonnet-5` - balanced quality and speed
* `claude-opus-4-8` - highest quality (slowest)

## Port Allocation

The worker uses a per-user default port so different OS users on the same machine never collide:

* **Default**: `37700 + (uid % 100)` (set in `src/shared/SettingsDefaultsManager.ts`)
* **Override**: Set `CLAUDE_MEM_WORKER_PORT` (env or `~/.claude-mem/settings.json`)
* **Discovery**: `GET /api/health` returns the active port; `~/.claude-mem/settings.json` stores the configured value

If the chosen port is occupied, the worker fails to start — pin a different port via `CLAUDE_MEM_WORKER_PORT` and restart.

## Data Storage

The worker service stores data in the user data directory:

```
~/.claude-mem/
├── claude-mem.db           # SQLite database (bun:sqlite)
├── worker.pid              # PID file for process tracking
├── settings.json           # User settings
└── logs/
    └── worker-YYYY-MM-DD.log  # Daily rotating logs
```

## Error Handling

The worker implements graceful degradation:

* **Database Errors**: Logged but don't crash the service
* **SDK Errors**: Retried with exponential backoff
* **Network Errors**: Logged and skipped
* **Invalid Input**: Validated and rejected with error response

## Performance

* **Async Processing**: Observations processed asynchronously
* **In-Memory Queue**: Fast observation accumulation
* **Batch Processing**: Multiple observations processed together
* **Connection Pooling**: SQLite connections reused

## Troubleshooting

See [Troubleshooting - Worker Issues](../troubleshooting.md#worker-service-issues) for common problems and solutions.


# Cloud Sync (cmem.ai Pro)
Source: https://docs.claude-mem.ai/cloud-sync

Two-lane multi-device sync of your memory database — durable HTTP push/pull through a per-user sync hub, with optional Realtime live updates as a speed layer.

# Cloud Sync (cmem.ai Pro)

Cloud sync replicates your local memory database across your devices through a
**per-user sync hub** — an ordered log of everything your devices write. It is
built into the worker: **there is no daemon — the worker syncs on write**. The
same process that records every observation also uploads it, and pulls the
other devices' writes back down.

<Note>
  **Two lanes, one source of truth.** Everything durable travels over plain
  HTTP: pushes append to the hub's ordered log, pulls page through it with a
  cursor. An optional Realtime channel rides alongside as a pure *speed layer* —
  it only makes the next pull happen sooner. The channel can be dropped, disabled,
  or wrong with **zero data loss**; the HTTP cursor is always the truth.
</Note>

## What syncs

Three kinds of rows are replicated between your devices:

* **Observations** — the compressed memories claude-mem generates from your sessions.
* **Session summaries** — the per-session overview records.
* **User prompts** — the prompts you typed. A prompt over 200 KB uploads as its first 200 KB plus a truncation note; the full prompt stays on the device that captured it.

Alongside the rows, three kinds of **mutations** travel through the same log
so later edits converge everywhere: session **title** changes, **prompt→session
repairs** (a prompt captured before its session registered is re-linked on
every device), and **project remaps** (worktree adoption and cwd-based moves
retarget the affected rows on every device).

<Warning>
  **Privacy:** cloud sync uploads your observation narratives and your full
  prompt text to the sync hub under your cmem.ai account. Don't enable it if
  that content must stay on your machine.
</Warning>

## How the push lane works

**The database is the queue.** Every synced table carries a `synced_at` column
(`NULL` = not in the log yet). After each write, the worker nudges a debounced
flusher that drains `WHERE synced_at IS NULL` and stamps rows on success. That
one mechanism handles live sync, offline catch-up, and retry. Rows written
after the SyncHub launch boundary start as `NULL`; anything that fails to
upload stays `NULL` until a later flush picks it up. Pre-launch local rows are
not treated as a cloud migration corpus.

* **Debounced:** write bursts coalesce; the flusher runs \~1.5 s after the
  last write (250 ms while the speed layer is connected), and only one
  flush runs at a time.
* **Batched:** ops drain in requests of up to 500 ops / 4,000,000 encoded
  bytes. Each individual canonical body is capped at 256,000 encoded bytes.
* **Timeboxed:** every request has a 30 s timeout — a dead network can
  never hang the worker.
* **Retrying:** a failed upload leaves rows `NULL` and retries on the next
  write plus a capped exponential backoff (30 s → 10 min). The write
  path is never blocked — sync failures cost nothing but delay.
* **Idempotent:** the hub dedupes on origin identity, so a retried push can
  never create duplicates.

## How the pull lane works

Each device keeps a **cursor** into the hub's log and pulls everything after
it — in pages, so a device that was offline for a week (or is brand new and
starts from zero) catches up the same way an active one stays current:

* **Session start:** the worker pulls immediately before injecting context
  (bounded to 1.5 s, so a dead network can't stall your session), which
  means memory written on another machine is there the moment you start
  working.
* **Steady state:** a short poll every 30 s while a session is active,
  every 5 min when idle, suspended entirely after an hour of no activity.
  Every push response also reports the log head, so an active device learns
  about remote writes without waiting out the timer.
* **Applied like native writes:** pulled rows keep their original timestamps,
  carry their origin device, index into full-text and vector search through
  the same paths native writes use, and are stamped so they can never be
  echoed back up.

## Live updates (optional)

When enabled (the default), the worker also subscribes to a private Realtime
channel for your account. When another device pushes, the server broadcasts a
tiny "the log moved forward" signal and this device pulls right away —
multi-device convergence in about a second instead of a poll interval. The
channel is strictly **advisory**: it never carries your data, and any anomaly
(a dropped connection, a missed heartbeat, a malformed signal) simply closes it
and falls back to an HTTP pull, which is always correct. Set
`CLAUDE_MEM_CLOUD_SYNC_WS` to `false` to turn live updates off — sync stays
fully correct at poll latency. If the sync server does not offer live updates,
the worker stays on polling and checks again hourly.

## Requirements and setup

Cloud sync is active when **all three** of the token, the user id, and the hub
URL are non-empty — there is no separate enable flag; blank any one of them to
turn sync off.

1. A **cmem.ai Pro sync token and user id** (from **cmem.ai → Connect**).
2. A **sync hub URL** in `CLAUDE_MEM_CLOUD_SYNC_HUB_URL`: `https://sync.cmem.ai`,
   which the installer writes for you (source in `services/sync-api/`). A hub
   URL pinned to the older Cloudflare Workers hub is moved to it automatically.

To connect, run `npx claude-mem install` in your terminal and choose **CMEM
Pro**. The installer signs you in through the browser, writes all three values
into `~/.claude-mem/settings.json` (mode `0600`), and restarts the worker. The
`/cloud-sync` skill in Claude Code checks status, points you to the installer
for setup, and verifies the installed client can reach SyncHub. It never asks
you to paste the token into the chat, because anything pasted there lands in the
session transcript. For CI or a remote box, see
[headless setup](/cmem-pro-headless).

## Settings

| Key | Default | Meaning |
| - | - | - |
| `CLAUDE_MEM_CLOUD_SYNC_TOKEN` | `''` | Your cmem.ai sync token (from **cmem.ai → Connect**). Sent as `Authorization: Bearer`. |
| `CLAUDE_MEM_CLOUD_SYNC_USER_ID` | `''` | Your cmem.ai user id (from **cmem.ai → Connect**). All your devices share it — it names your hub log. |
| `CLAUDE_MEM_CLOUD_SYNC_HUB_URL` | `''` | Sync hub base URL. **Empty = sync off.** |
| `CLAUDE_MEM_CLOUD_SYNC_WS` | `'true'` | Live updates over Realtime. `'false'` disables live updates (HTTP polling only); sync stays fully correct at poll latency. |
| `CLAUDE_MEM_CLOUD_SYNC_DEVICE_ID` | `''` | Stable identity of this machine. A fresh UUID is minted and persisted on first start. Don't edit it: every row is attributed to its origin device. |
| `CLAUDE_MEM_CLOUD_SYNC_DEVICE_NAME` | machine hostname | Human-readable label for this device. |
| `CLAUDE_MEM_CLOUD_SYNC_CONTENT_BATCH_SIZE` | `'40'` | Ops per content flush page. 200-op pages timed out at 30s under hub `projection_busy`. Max 500. |
| `CLAUDE_MEM_CLOUD_SYNC_REQUEST_TIMEOUT_MS` | `'90000'` | Content-push `AbortSignal` timeout. Must exceed the hub's 45s projection fetch; default matches the 90s projection lease. |

A Hub accepts at most 64 distinct device ids per account. Existing devices
continue to sync normally at the limit; a new device receives
`409 device_limit_exceeded`. Status/metadata reads and renaming an unknown
device do not create phantom devices.

## Status endpoint

The worker exposes `GET /api/sync/status` (on the same port as the rest of the
worker HTTP API). It is registered unconditionally, so an unconfigured install
answers `200` rather than a `404` — callers can tell "not set up" apart from
"worker down".

```bash theme={null}
curl -s "http://127.0.0.1:${CLAUDE_MEM_WORKER_PORT}/api/sync/status"
```

Configured:

```json theme={null}
{
  "configured": true,
  "deviceId": "2f6b1c9e-7d41-4c1a-9b0e-3d5f8a2c6e10",
  "pending": { "observations": 0, "summaries": 0, "prompts": 2, "mutations": 0, "tombstones": 0 },
  "quarantine": { "count": 0, "latestReason": null },
  "lastFlushAt": 1783981042731,
  "lastError": null,
  "hub": {
    "checkedAt": 1783981042800,
    "reachable": true,
    "epoch": "1783981042000",
    "headSeq": "42",
    "projectedSeq": "42",
    "error": null
  }
}
```

Every configured status request makes an authenticated, read-only
`GET /v1/sync/status` directly to SyncHub, including when all pending counts
are zero. The probe does not append an operation or advance a pull cursor.
`hub.reachable: false` and `hub.error` therefore expose a bad token, wrong Hub
URL, malformed response, timeout, or network failure
that an empty queue would otherwise hide.

* `pending` — rows (and queued mutation ops) still waiting to upload. Counts
  near 0 mean the hub's log has everything this device wrote.
* `lastFlushAt` — epoch ms of the last successful flush, `null` before the first.
* `lastError` — message from the most recent failed flush, `null` when healthy.
  It never contains the token.
* `hub` — the most recent authenticated SyncHub probe. Treat
  `hub.reachable: true` as the connectivity check; `lastError: null` alone is
  not enough. Sequence and epoch fields remain decimal strings.

Not configured:

```json theme={null}
{ "configured": false }
```


# CMEM Pro (manual / headless)
Source: https://docs.claude-mem.ai/cmem-pro-headless

What npx claude-mem install writes for CMEM Pro — OAuth pairing, settings.json keys, and how to verify without the interactive installer

# CMEM Pro (manual / headless)

Use this when you already have a [cmem.ai](https://cmem.ai) account and need to wire CMEM Pro without the interactive installer (CI, a second machine, or a box you SSH into). The usual path is still [`npx claude-mem install`](/installation).

<Warning>
  Never paste real `cm_pro_…` keys, setup tokens, or OpenRouter `sk-or-` keys into chat, tickets, or docs. The examples below are placeholders only. Keep `~/.claude-mem/settings.json` mode `0600`.
</Warning>

## What the installer does

Three stages:

1. **Runtime** — Bun/uv if needed, IDE plugin files, worker deps.
2. **Sign in** — skipped for `--provider claude`, and for non-interactive runs without `--provider` (fresh install defaults to claude; an existing config keeps its provider). A non-interactive install that skipped sign-in prints an optional sign-in link as its last line; agents should show that link to the user rather than open it. Local installs contact cmem.ai once, at signup, to create the sign-in link, with a numbers-only usage summary (observation counts and token totals, no prompts, paths, or project names); nothing else is sent to cmem.ai. Otherwise the CLI does **not** ask for an email:
   * `POST https://cmem.ai/api/installer/oauth/start` with `{ source: "npx-installer", device_name: <hostname>, install_state: "fresh" | "update", usage_summary?: { window_days: 28, active_days, observations, memory_tokens, days: [{ d: "YYYY-MM-DD", obs, tokens }] } }` (`usage_summary` is omitted when no local data can be read)
   * prints a device code `XXXX-XXXX` and opens `authorization_url`
   * polls `https://cmem.ai/api/pro/trial/poll` until authenticated
3. **Provider** — **CMEM Pro is pre-selected.** Choosing it opens `checkout_url` (trial/claim), polls until `status: "ready"`, then writes settings and restarts the worker.

`--provider openrouter` with a **personal** key is a different path: empty `CLAUDE_MEM_OPENROUTER_BASE_URL` (or `https://openrouter.ai/api/v1`). Never send a personal `sk-or-` key to `https://cmem.ai/api/inference`.

## Settings the installer writes

Credentials are **staged**, then **activated**. File: `~/.claude-mem/settings.json`.

### Staged (sync + trial metadata)

| Key | From the ready poll |
| - | - |
| `CLAUDE_MEM_CLOUD_SYNC_TOKEN` | `setup_token` |
| `CLAUDE_MEM_CLOUD_SYNC_USER_ID` | `user_id` |
| `CLAUDE_MEM_CLOUD_SYNC_HUB_URL` | `hub_url` |
| `CLAUDE_MEM_CLOUD_SYNC_DEVICE_ID` | `""` (worker mints on first start) |
| `CLAUDE_MEM_CLOUD_SYNC_DEVICE_NAME` | hostname |
| `CLAUDE_MEM_PRO_TRIAL_STATE` | `active` |
| `CLAUDE_MEM_PRO_TRIAL_ENDS_AT` | `trial.ends_at` or `""` |
| `CLAUDE_MEM_PRO_PLAN` | `trial` / `pro` / `none` |
| `CLAUDE_MEM_PRO_MEMORY_KEY` | `memory_key`, or `setup_token` if omitted |
| `CLAUDE_MEM_PRO_MEMORY_BASE_URL` | `memory_base_url`, or `https://cmem.ai/api/inference/v1` |
| `CLAUDE_MEM_PRO_MEMORY_MODEL` | `memory_model`, or `cmem-observer` |
| `CLAUDE_MEM_PRO_FALLBACK_AT` | `""` |
| `CLAUDE_MEM_PRO_FALLBACK_MESSAGE` | `""` (the worker stores the gateway's message here when a fallback starts) |
| `CLAUDE_MEM_PRO_FALLBACK_ACTION` | `""` (the gateway's "what to do" for that fallback) |
| `CLAUDE_MEM_PRO_FALLBACK_URL` | `""` (the gateway's link for that fallback; the notice shows only an `https://cmem.ai` link) |

Cloud sync is on only when the token, user id, **and** hub URL are all non-empty. See [Cloud Sync](/cloud-sync).

### Activated (this is what makes observations run)

The worker talks to cmem.ai through the generic OpenRouter client. There is no separate CMEM provider implementation.

```json theme={null}
{
  "CLAUDE_MEM_PROVIDER": "openrouter",
  "CLAUDE_MEM_OPENROUTER_BASE_URL": "https://cmem.ai/api/inference/v1",
  "CLAUDE_MEM_OPENROUTER_MODEL": "cmem-observer",
  "CLAUDE_MEM_OPENROUTER_API_KEY": "cm_pro_YOUR_MEMORY_KEY",
  "CLAUDE_MEM_PRO_MEMORY_KEY": "",
  "CLAUDE_MEM_PRO_MEMORY_BASE_URL": "",
  "CLAUDE_MEM_PRO_MEMORY_MODEL": ""
}
```

Keep the cloud-sync trio from staging. `memory_key` and `setup_token` are often the same (`cm_pro_…`). If the poll returns a distinct `memory_key`, use that for `CLAUDE_MEM_OPENROUTER_API_KEY` and keep `setup_token` only on `CLAUDE_MEM_CLOUD_SYNC_TOKEN`.

## Manual recipe (you already have tokens)

1. From **cmem.ai → Connect** (or an installer pairing), copy `setup_token`, `user_id`, `hub_url`, and `memory_key` (if missing, use `setup_token`).
2. Merge staged + activated keys into `~/.claude-mem/settings.json`. Placeholders only:

```json theme={null}
{
  "CLAUDE_MEM_CLOUD_SYNC_TOKEN": "cm_pro_YOUR_SETUP_TOKEN",
  "CLAUDE_MEM_CLOUD_SYNC_USER_ID": "YOUR_USER_ID",
  "CLAUDE_MEM_CLOUD_SYNC_HUB_URL": "https://YOUR_HUB_URL",
  "CLAUDE_MEM_CLOUD_SYNC_DEVICE_ID": "",
  "CLAUDE_MEM_CLOUD_SYNC_DEVICE_NAME": "my-machine",
  "CLAUDE_MEM_PRO_TRIAL_STATE": "active",
  "CLAUDE_MEM_PRO_TRIAL_ENDS_AT": "",
  "CLAUDE_MEM_PRO_PLAN": "trial",
  "CLAUDE_MEM_PRO_FALLBACK_AT": "",
  "CLAUDE_MEM_PROVIDER": "openrouter",
  "CLAUDE_MEM_OPENROUTER_BASE_URL": "https://cmem.ai/api/inference/v1",
  "CLAUDE_MEM_OPENROUTER_MODEL": "cmem-observer",
  "CLAUDE_MEM_OPENROUTER_API_KEY": "cm_pro_YOUR_MEMORY_KEY"
}
```

3. `chmod 600 ~/.claude-mem/settings.json`
4. Restart the worker so it is not holding old in-memory provider/sync state:

```bash theme={null}
npx claude-mem restart
```

The interactive installer stops the worker after it persists the provider for the same reason.

5. Verify (port is `CLAUDE_MEM_WORKER_PORT` or `~/.claude-mem/.worker.port`):

```bash theme={null}
curl -s "http://127.0.0.1:${CLAUDE_MEM_WORKER_PORT}/api/health"
curl -s "http://127.0.0.1:${CLAUDE_MEM_WORKER_PORT}/api/sync/status"
```

Expect health with provider `openrouter`, and sync `configured: true` plus `hub.reachable: true`.

6. First real observation should store via model `cmem-observer`. Gateway success **clears** `CLAUDE_MEM_PRO_FALLBACK_AT`. A terminal gateway rejection (a spent allowance, an inactive subscription, or a refused key) **sets** that timestamp, memory falls back to the Anthropic plan, and the next session start relays the gateway's own message and link.

<Info>
  Fallback is **event-driven**, not a calendar date. Do not treat `CLAUDE_MEM_PRO_TRIAL_ENDS_AT` as the switch. The switch is `CLAUDE_MEM_PRO_FALLBACK_AT`.
</Info>

## What not to mix

| Path | OpenRouter base URL | Key |
| - | - | - |
| CMEM Pro (this page) | `https://cmem.ai/api/inference/v1` | `cm_pro_…` memory key |
| Personal OpenRouter | empty, or `https://openrouter.ai/api/v1` | your `sk-or-…` |
| Anthropic plan | n/a | `--provider claude` — local Max; cloud sync and CMEM keys cleared |

Never send a personal OpenRouter key to the cmem gateway.

## Next steps

* [Installation](/installation) — interactive three-stage installer
* [Cloud Sync](/cloud-sync) — what the sync trio replicates
* [OpenRouter provider](/usage/openrouter-provider) — personal OpenRouter keys (not cmem.ai)


# Configuration
Source: https://docs.claude-mem.ai/configuration

Environment variables and settings for Claude-Mem

# Configuration

## Settings File

Settings are managed in `~/.claude-mem/settings.json`. The file is auto-created with defaults on first run.

### Core Settings

| Setting | Default | Description |
| - | - | - |
| `CLAUDE_MEM_MODEL` | `claude-haiku-4-5-20251001` | Claude model used to compress observations (when using the Claude provider) |
| `CLAUDE_MEM_PROVIDER` | `claude` | AI provider: `claude`, `codex`, `gemini`, `openrouter`, or `openai-compatible` |
| `CLAUDE_MEM_CLAUDE_AUTH_METHOD` | `subscription` | Claude provider auth mode: `subscription`, `api-key`, or `gateway` |
| `CLAUDE_MEM_CLAUDE_OBSERVATION_BATCH_SIZE` | `1` | Queued observations the Claude provider may send in one observer prompt (1–32). Only events with the same prompt number, agent and working directory are combined, in queue order, and queued events are added only while the prompt stays within two capped fields. Raise it when one session queues events faster than its observer answers. Trade-offs, as with Codex batching: every observation from a batched reply lists the files of all events in the batch, and a reply that fails twice drops the whole batch. An environment variable of the same name overrides `settings.json`. |
| `CLAUDE_MEM_LLM_TIMEOUT_MS` | `180000` | Per-request deadline (ms, 500–300000) for non-streamed observer requests: Gemini, Codex, and the cmem.ai gateway (plus any OpenAI-compatible endpoint that refuses streaming). It exists to catch a hung request; a slow backend just needs a higher value. OpenRouter and OpenAI-compatible requests are streamed and are not bounded by this setting: they end after the idle window (`CLAUDE_MEM_LLM_STREAM_IDLE_TIMEOUT_MS`) with no token or keep-alive, with a 300-second cap on the whole request. A `settings.json` still holding the old `30000` default is moved to the new default once; a `30000` you set after that is kept. An environment variable of the same name overrides `settings.json`. |
| `CLAUDE_MEM_FIELD_OPTIMIZE_TIMEOUT_MS` | `180000` | Deadline (ms, 500–300000) for condensing one oversized tool field before its observation is sent; on expiry the field is truncated instead. It is a request to the same backend as the observer request, so it has the same default. A `settings.json` still holding the old `30000` default is moved to the new default once; a `30000` you set after that is kept. An environment variable of the same name overrides `settings.json`. |
| `CLAUDE_MEM_LLM_STREAM_IDLE_TIMEOUT_MS` | `90000` | Silence (ms, 500–300000) that ends a streamed OpenRouter or OpenAI-compatible request: no token and no keep-alive for this long, and the request is abandoned (a 300-second cap bounds the whole request). Raise it when a self-hosted backend queues requests behind a load balancer — the queue wait is silent, so it reads as idle and the shipped 90 seconds can fire before the backend even starts generating. It is an independent knob, so it does not move `CLAUDE_MEM_LLM_TIMEOUT_MS` (which streamed requests ignore). An environment variable of the same name overrides `settings.json`. |
| `CLAUDE_MEM_WORKER_HEARTBEAT_STALE_MS` | `120000` | A silent worker (both health re-probes failed) is spared from the wedged-worker reclaim while its liveness heartbeat is younger than this (ms, 10000–3600000), unless it has finished no HTTP response for 10 minutes. The worker refreshes `worker-heartbeat.json` every 5 seconds from a timer, so a fresh heartbeat means its event loop is still turning — slow, for example under on-access antivirus, but not dead. A worker with no heartbeat, or one written by a different process, is judged as before. An environment variable of the same name overrides `settings.json`. |
| `CLAUDE_MEM_MODE` | `code` | Active mode profile (e.g., `code--es`, `email-investigation`) |
| `CLAUDE_MEM_CONTEXT_OBSERVATIONS` | `50` | Number of observations to inject |
| `CLAUDE_MEM_SESSION_START_INCLUDE_ALL_SOURCES` | `false` | Include observations from every harness in SessionStart context |
| `CLAUDE_MEM_CONTEXT_MAIN_AGENT_ONLY` | `true` | Leave subagent observations out of SessionStart context so their step-logs don't crowd durable main-session memory out of the window. A subagent row carries both an agent id and an agent type; transcript-watch rows (e.g. Grok Bot seats) stay in. Applies in the server runtime too, where a row counts as a subagent row when the hook event it was generated from carried both. Search and the viewer still show everything. |
| `CLAUDE_MEM_REINFORCE_ALPHA` | `0` | Opt-in ACT-R ranking for SessionStart context. `0` (default) keeps the N most recent observations, unchanged. Above `0` (try `0.5`), observations the write path saw re-confirmed on later days can climb into the window: each observation's creation and re-confirmation days are scored with power-law decay, `ln(1 + age^-0.5 + ALPHA · Σ age_k^-0.5)`. The newest quarter of the window is always kept by recency. |
| `CLAUDE_MEM_WORK_STATE_ENABLED` | `true` | `false` turns work state off for hosts that track work their own way: SessionStart context leaves out the work-state section (the rule that `work_state_write` is your canonical to-do list, and the open lists), and the MCP server neither lists nor runs `work_state_write` and `work_state_read`. Lists already written stay in the database and come back when it is turned on again. An environment variable of the same name overrides `settings.json`. Restart the worker after changing it, and start a new session so the MCP server reads it. |
| `CLAUDE_MEM_SEMANTIC_INJECT` | `false` | Add the observations that best match each prompt to that prompt's context (`UserPromptSubmit`), on top of SessionStart context. |
| `CLAUDE_MEM_SEMANTIC_INJECT_LIMIT` | `5` | Number of observations added per prompt (1–20). |
| `CLAUDE_MEM_SEMANTIC_INJECT_FORMAT` | `narrative` | `narrative` adds each match's title and full narrative. `index` adds one line per match with its id, title and subtitle and points Claude to `get_observations` for the details. `narrative` is the default because it works without Claude making a tool call: in `index` mode a match it does not expand only contributes its title and subtitle. An `index` line costs a fraction of a narrative, so `index` can carry more matches for the same tokens; pair it with a higher limit. |
| `CLAUDE_MEM_SEARCH_RECENCY_DAYS` | `90` | Date-less semantic search (`search`, `search_observations`, the timeline) only ranks matches created in the last N days; older matches are left out of the answer. `0` turns the window off so every indexed match stays eligible; a larger N widens it. A request that passes `dateStart`/`dateEnd` always uses that range instead of the window. Restart the worker after changing it. |
| `CLAUDE_MEM_FILE_READ_GATE_ENABLED` | `true` | Block whole-file Reads of code files of 32 KB and up that have observation history and send Claude to `smart_outline` / `smart_unfold` / `get_observations` instead (Claude Code only). Targeted Reads with `offset`/`limit` still work. `false` lets every Read through and still adds the file's timeline as context. See [File Read Gate](/file-read-gate). |
| `CLAUDE_MEM_WORKER_PORT` | `37700 + (uid % 100)` | Worker service port (per-user default; override for fixed port) |
| `CLAUDE_MEM_WORKER_HOST` | `127.0.0.1` | Worker service host address |
| `CLAUDE_MEM_WORKER_AUTOSTART` | `true` | Set `false` when you run the worker yourself (a process manager, a container, `worker-service.cjs --daemon`). Hooks, the MCP server and `start` then use a worker that is already running but never launch, kill or recycle one: no lazy spawn, no version-mismatch recycle, no wedged-worker recycle or reclaim. While your worker is down, hooks skip their work quietly instead of counting it as a failure. |
| `CLAUDE_MEM_WORKER_INGEST_TOKEN` | empty | Shared token for remote hook-spool delivery. Configure the same value in the worker and each client through settings or the environment. The remote spool endpoint is disabled until the worker has this token. It is masked in settings replies. |
| `CLAUDE_MEM_HOOK_SPOOL_TRANSPORT` | `auto` | `auto` uses HTTP for a non-loopback worker host and the filesystem for a local worker. Set `http` for a loopback port forward to a remote worker, or `filesystem` only when hooks and worker share the same spool directory. |
| `CLAUDE_MEM_ALLOWED_ORIGINS` | *(empty)* | Comma-separated browser origins (e.g. `https://app.example.com`) allowed to call the worker API cross-origin, besides `http://localhost:*` and `http://127.0.0.1:*`. A page loaded from the worker's own address (the viewer at `http://<lan-ip>:<port>`) is always allowed. Other `http://localhost:*` pages can read the API but not delete: deletes sync to every device, so a `DELETE` is accepted only from the viewer's own page, an origin listed here, or a client that sends no `Origin` header (hooks, the CLI, curl). To block DNS rebinding, the worker also refuses a request whose `Host` is a DNS name it does not trust. IP addresses, `localhost`, `host.docker.internal`, `CLAUDE_MEM_WORKER_HOST`, the host of `CLAUDE_MEM_PUBLIC_URL`, and the hosts listed here are trusted. To open the viewer by a machine name, such as `http://mybox.local:37777`, list that origin here. Restart the worker after changing it. |
| `CLAUDE_MEM_PUBLIC_URL` | *(empty)* | Browser-reachable base URL printed for the viewer (live view, welcome hint, restart link) when the worker runs in a remote sandbox behind a port-forward, e.g. `https://37700.host.example`. Empty = `http://localhost:<port>`. The env var wins over the setting. (The [hosted server runtime](hosted-server) reads the same variable as its own public base URL.) |
| `CLAUDE_MEM_TV_TOKEN` | — | Shared secret for Observation TV remote access. Empty = off. With a non-loopback `CLAUDE_MEM_WORKER_HOST`, only `/tv`, `/tv.html`, `/stream` and `GET /api/observations` are reachable, and only with this token. |
| `CLAUDE_MEM_DATA_DIR` | `~/.claude-mem` | Data root — every other path (database, chroma, logs, settings.json, worker.pid) derives from this |
| `CLAUDE_MEM_SKIP_TOOLS` | `ListMcpResourcesTool,SlashCommand,Skill,TodoWrite,AskUserQuestion` | Comma-separated tools to exclude from observations |
| `CLAUDE_MEM_SKIP_BASH_PATTERNS` | — | Regular expression matched against each shell command (Claude Code `Bash` and `PowerShell`, Codex `exec_command`); on a match the observation is skipped. Empty captures every command. Use alternation for several patterns, e.g. `^(ls\|cat\|pwd\|git status)\b`. An invalid regex is ignored, so capture is never dropped |
| `CLAUDE_MEM_SKIP_SUBAGENT_OBSERVATIONS` | `false` | When `true`, skip **every** subagent observation (a tool call that carries both an agent id and an agent type). See [Subagent & Dynamic Workflow filtering](#subagent--dynamic-workflow-filtering). |
| `CLAUDE_MEM_CODEX_SUBAGENT_INGESTION` | `false` | When `true`, capture the subagent threads Codex CLI spawns, which its native hooks never report, from their rollout files under `~/.codex/sessions`. Off by default: a busy Codex session spawns dozens of subagents a day, and every tool call they make is one more request to your observer provider. `CLAUDE_MEM_SKIP_SUBAGENT_OBSERVATIONS=true` keeps it off. Restart the worker after changing it. |
| `CLAUDE_MEM_SKIP_AGENT_TYPES` | *(empty)* | Comma-separated subagent `agent_type` values to skip, e.g. `workflow-subagent,Explore,Plan`. Main-session observations are unaffected. |
| `CLAUDE_MEM_CAPTURE_ADVISOR_CALLS` | `false` | When `true`, the Stop hook records each Claude Code `advisor` tool call (the advice text, the advisor model, and the turn's prompt) in the local database, readable at `GET /api/advisor-calls`. The advisor never fires PostToolUse, so the hook reads the end of the transcript for it. `<private>` content is removed before storage. Worker runtime only; nothing is generated, so it costs no tokens. |
| `CLAUDE_MEM_REDACT_ENABLED` | `false` | Opt-in auto-redaction: recognized secret patterns are replaced with `<redacted type='…'/>` markers before storage in tool input and output, prompts, summaries and server-runtime event bodies (not in server-runtime session metadata). See [Auto-Redaction](/usage/auto-redaction) for the built-in pattern list |
| `CLAUDE_MEM_REDACT_GENERIC_ENABLED` | `false` | With redaction on, also redact credentials that have no vendor prefix: `password=`, `*_PWD=`, `*_TOKEN=`, `*_SECRET=`, `*_API_KEY=` values and `Authorization: Bearer …`. Lower confidence than the 11 vendor patterns, so it is a separate opt-in |
| `CLAUDE_MEM_REDACT_DISABLED_BUILTINS` | *(empty)* | CSV of built-in pattern names to leave unredacted while the rest stay active, e.g. `jwt,slack_token` |
| `CLAUDE_MEM_REDACT_CUSTOM_PATTERNS` | `[]` | JSON array of extra `{ "name", "regex" }` patterns, evaluated before the built-ins so they can override a token family |
| `CLAUDE_MEM_REDACT_LOG_MATCHES` | `false` | Log a `pattern,count` line per redaction scan (the matched bytes are never logged) |

### Subagent & Dynamic Workflow filtering

Claude Code [Dynamic Workflows](https://code.claude.com/docs/en/workflows) fan a single
prompt out to tens-to-hundreds of parallel subagents (`agent_type: workflow-subagent`).
Every tool call by every subagent fires a `PostToolUse` hook, so claude-mem creates one
provider-analyzed observation per call — a single run can emit **hundreds-to-thousands**
of low-signal observations. That can exhaust the configured provider's free-tier quota
(HTTP 429) and drop the rest of the run, including valuable main-session work.

Two settings let you filter these out **before** any worker round-trip or provider call.
Both default to off, so existing behavior is preserved.

* **Drop all subagent noise (recommended for heavy workflow users):**

  ```json theme={null}
  { "CLAUDE_MEM_SKIP_SUBAGENT_OBSERVATIONS": "true" }
  ```

  This is the robust lever — it catches every subagent tool call (one that carries both
  an agent id and an agent type) regardless of type. Main-session observations are kept,
  including `claude --agent <type>` main threads and transcript-watch hosts such as
  Grok Bot seats, which carry only one of the two.

* **Surgically drop specific agent types** (keep some subagents, drop others):

  ```json theme={null}
  { "CLAUDE_MEM_SKIP_AGENT_TYPES": "workflow-subagent" }
  ```

  Add a comma-separated list of `agent_type` values. The two settings combine as a
  union: a subagent observation is skipped if the global toggle is on **or** its
  `agent_type` is in the list.

> Subagent **summaries** are already skipped automatically; these settings add the same
> control for **observations**. Durable cross-session knowledge generally comes from the
> main session, so dropping ephemeral subagent steps usually improves signal-to-noise.
> SessionStart already leaves subagent rows out of injected context by default
> (`CLAUDE_MEM_CONTEXT_MAIN_AGENT_ONLY`); these settings go further and skip capturing
> them at all, which also saves the observer's provider tokens.

### Gemini Provider Settings

| Setting | Default | Description |
| - | - | - |
| `CLAUDE_MEM_GEMINI_API_KEY` | — | Gemini API key ([get free key](https://aistudio.google.com/app/apikey)) |
| `CLAUDE_MEM_GEMINI_API_KEYS` | — | Optional: more keys (newline-, comma- or space-separated) to rotate through when one is rate-limited, spent or refused ([Multi-Key Rotation](usage/multi-key-rotation)) |
| `CLAUDE_MEM_GEMINI_MODEL` | `gemini-flash-latest` | Gemini model: `gemini-flash-latest`, `gemini-flash-lite-latest`, `gemini-3.5-flash`, `gemini-3.1-flash-lite`, `gemini-3-flash-preview` |

See [Gemini Provider](usage/gemini-provider) for detailed configuration and rate-limit information.

### Codex Subscription Provider Settings

Run `codex login` as the user running the worker, then install with `npx claude-mem install --provider codex`. Add `--model gpt-6-luna` to choose that model, or select Codex and enter a model in the viewer settings. Codex uses the local CLI subscription login; it does not require an OpenAI API key.

Reinstalling without `--model` keeps the saved Codex model. On a first install the setting is empty and Codex chooses its default. Clear the Codex Model field in the viewer to return to the default later.

| Setting | Default | Description |
| - | - | - |
| `CLAUDE_MEM_CODEX_MODEL` | empty | Codex chooses its default model when empty; otherwise use a model available to your subscription. |
| `CLAUDE_MEM_CODEX_REASONING_EFFORT` | `low` | Reasoning effort: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` or `ultra`, subject to model support; empty uses Codex's default. Advanced override in `settings.json` or the environment. An effort or model Codex refuses stops Codex memory until it is changed, and SessionStart says so. |
| `CLAUDE_MEM_CODEX_PATH` | `codex` | CLI executable or path. File or environment only; the viewer settings API cannot change it. |
| `CLAUDE_MEM_CODEX_MAX_CONCURRENT_AGENTS` | `2` | App-server clients that serve requests in parallel (1–8). File only; restart the worker after changing it. |
| `CLAUDE_MEM_CODEX_OBSERVATION_BATCH_SIZE` | `8` | Queued observations Codex may combine into one request (1–32). |
| `CLAUDE_MEM_CODEX_OBSERVATION_BATCH_MAX_CHARS` | `32000` | Character budget for one combined observation request (4000–128000). |

The worker uses an isolated `codex app-server` session for observations and summaries. Codex CLI authentication must be a file-backed ChatGPT login; API-key login is not accepted. Each request uses the shared `CLAUDE_MEM_LLM_TIMEOUT_MS` deadline. See `docs/codex-provider.md` in the repository for how failures pause and recover.

### OpenRouter Provider Settings

| Setting | Default | Description |
| - | - | - |
| `CLAUDE_MEM_OPENROUTER_API_KEY` | — | OpenRouter API key ([get key](https://openrouter.ai/keys)) |
| `CLAUDE_MEM_OPENROUTER_API_KEYS` | — | Optional: more keys to rotate through when one is rate-limited, spent or refused ([Multi-Key Rotation](usage/multi-key-rotation)). Never used on the cmem.ai gateway |
| `CLAUDE_MEM_OPENROUTER_MODEL` | `cohere/north-mini-code:free` | Model identifier (supports 100+ models) |
| `CLAUDE_MEM_OPENROUTER_BASE_URL` | — | Optional: custom OpenAI-compatible base URL (DeepSeek, LM Studio, [IO Intelligence](https://io.net)) |
| `CLAUDE_MEM_OPENROUTER_SITE_URL` | — | Optional: URL for analytics |
| `CLAUDE_MEM_OPENROUTER_REASONING_EFFORT` | — | Optional: `none`, `minimal`, `low`, `medium` or `high`, openrouter.ai only ([details](usage/openrouter-provider#settings)) |
| `CLAUDE_MEM_OPENROUTER_APP_NAME` | `claude-mem` | Optional: App name for analytics |
| `CLAUDE_MEM_OPENROUTER_EXTRA_BODY` | — | Optional: JSON object of extra request fields, e.g. `{"reasoning":{"enabled":false}}` ([details](usage/openrouter-provider#extra-request-fields)) |

See [OpenRouter Provider](usage/openrouter-provider) for detailed configuration, free model list, and usage guide.

### OpenAI-Compatible Provider Settings

For `CLAUDE_MEM_PROVIDER=openai-compatible`: any endpoint that speaks `/chat/completions`, hosted or local.

| Setting | Default | Description |
| - | - | - |
| `CLAUDE_MEM_OPENAI_COMPAT_PRESET` | — | Named endpoint preset ([list](usage/openai-compatible-provider)). Empty = `custom`: set the base URL yourself |
| `CLAUDE_MEM_OPENAI_COMPAT_BASE_URL` | — | OpenAI-compatible base URL. Overrides the preset's |
| `CLAUDE_MEM_OPENAI_COMPAT_MODEL` | — | Model id, sent as-is. Empty = the preset's default model |
| `CLAUDE_MEM_OPENAI_COMPAT_API_KEY` | — | The key this endpoint issued. Settings file or environment, or `OPENAI_COMPAT_API_KEY` in `~/.claude-mem/.env`; the viewer cannot set it. A local server needs none |
| `CLAUDE_MEM_OPENAI_COMPAT_API_KEYS` | — | Optional: more keys to rotate through ([Multi-Key Rotation](usage/multi-key-rotation)). Settings file or environment, or `OPENAI_COMPAT_API_KEYS` in `~/.claude-mem/.env` |

See [OpenAI-Compatible Provider](usage/openai-compatible-provider) for presets and setup.

### Quota Fallback Settings

| Setting | Default | Description |
| - | - | - |
| `CLAUDE_MEM_QUOTA_FALLBACK_PROVIDER` | `claude` | Where observer work goes while the selected provider can't serve (a spent allowance, rate limits or over-capacity refusals past their retries, an outage, repeated unusable replies), until it recovers: `claude` (your Anthropic plan, used only when a Claude login or key exists), `gemini`, `openrouter`, `openai-compatible`, or `off` to wait instead. Empty (from older settings files) = `claude`. See [Quota Fallback](/usage/quota-fallback) |
| `CLAUDE_MEM_QUOTA_FALLBACK_MODEL` | — | Claude model for a Claude fallback run. Empty = `CLAUDE_MEM_MODEL` and tier routing. Ignored for other fallbacks |

See [Quota Fallback](usage/quota-fallback) for how the fallback starts and ends.

### Quota Guard Settings

With subscription auth, the observer stops once a usage window reaches its threshold. A window the provider has already rejected always stops it, whatever the threshold. The five-hour window also stops it at 85% or more within 15 minutes of its reset, even below its threshold. API-key auth never stops.

Thresholds are fractions from 0 to 1 (`0.93` = 93%). A value outside that range, such as `93`, falls back to the default, with a warning in the worker log. A blank value uses the default.

| Setting | Default | Description |
| - | - | - |
| `CLAUDE_MEM_QUOTA_THRESHOLD_FIVE_HOUR` | `0.95` | Five-hour window |
| `CLAUDE_MEM_QUOTA_THRESHOLD_SEVEN_DAY` | `0.93` | Weekly window |
| `CLAUDE_MEM_QUOTA_THRESHOLD_SEVEN_DAY_OPUS` | `0.93` | Weekly Opus window |
| `CLAUDE_MEM_QUOTA_THRESHOLD_SEVEN_DAY_SONNET` | `0.92` | Weekly Sonnet window |
| `CLAUDE_MEM_QUOTA_THRESHOLD_OVERAGE` | `0.95` | Overage, while it is in use |

### Observer Budget Settings

These apply to every observer provider. The observer's conversation runs in generations. When one fills its budget, claude-mem retires it and starts a fresh one, briefed with the session's own observations. The budget is the smaller of `CLAUDE_MEM_OBSERVER_MAX_CONVERSATION_CHARS` and half the observer model's context window (about 4 characters per token). Each tool call's parameters and outcome are capped at a tenth of the window, 16,000 characters at most.

| Setting | Default | Description |
| - | - | - |
| `CLAUDE_MEM_OBSERVER_MAX_CONVERSATION_CHARS` | `400000` | Characters one observer generation may hold before it is retired |
| `CLAUDE_MEM_OBSERVER_CONTEXT_WINDOW` | — | Observer model context window in tokens. Empty = resolve it: Claude models `200000` (`1000000` for a `[1m]` model id), Gemini models from a built-in map, OpenRouter models from the OpenRouter models catalogue. Any other OpenAI-compatible endpoint (a local server, a custom gateway) falls back to `131072`, so set this for a model with a smaller window, e.g. `16384`. Values below `8192` are clamped up to `8192` |
| `CLAUDE_MEM_OBSERVER_MAX_OUTPUT_TOKENS` | `4096` | Output-token cap on every OpenRouter, custom-endpoint and Gemini observer request (`max_tokens`, or `max_completion_tokens` for endpoints that require it; Gemini `maxOutputTokens`). Raise it for a reasoning model that spends the cap before it answers. `256`–`1000000` |
| `CLAUDE_MEM_OBSERVE_BARE_PROMPTS` | `false` | `false`: a user prompt is not sent to the observer on its own; it goes out with the next tool call or summary, in that request. `true`: one observer request per prompt, as before |

If the provider still rejects a request as too long for the model's window, the observer retires the generation and retries the same work in a fresh one, the same way it handles Claude's "Prompt is too long".

For these HTTP providers, the observer's instructions and output format are sent as the system message, and the user's request as the first user message. A reply cut off at the output-token cap is logged as a warning that names the cap.

### Claude Gateway Settings

Gateway credentials live in `~/.claude-mem/.env`, not `settings.json`.

| Env var | Default | Description |
| - | - | - |
| `ANTHROPIC_BASE_URL` | none | LiteLLM or Anthropic-compatible gateway URL for the Claude Agent SDK path |
| `ANTHROPIC_AUTH_TOKEN` | none | Optional LiteLLM master key or virtual key |
| `ANTHROPIC_API_KEY` | none | Direct Anthropic API key; normally omit this in LiteLLM gateway mode |

Use [LiteLLM Gateway](configuration/litellm-gateway) when you want `CLAUDE_MEM_PROVIDER=claude` to route through LiteLLM while preserving the Claude Agent SDK worker path.

| Setting | Default | Description |
| - | - | - |
| `CLAUDE_MEM_OBSERVER_THINKING` | `disabled` | The `thinking` parameter the Claude observer sends. `disabled` saves tokens on Anthropic-native endpoints. `omit` sends no `thinking` field, for a gateway whose upstream model always thinks and rejects `disabled` (for example GLM's error 1210). `enabled` or `enabled:<budget>` (default budget `1024`) turns thinking on and spends thinking tokens on every observer request |

If an Anthropic-compatible gateway rejects the `thinking` parameter with a 400, the observer drops the parameter for the rest of that session and retries the same batch, so nothing is lost while you change the setting.

### System Configuration

| Setting | Default | Description |
| - | - | - |
| `CLAUDE_MEM_DATA_DIR` | `~/.claude-mem` | Data directory location |
| `CLAUDE_MEM_LOG_LEVEL` | `INFO` | Log verbosity (DEBUG, INFO, WARN, ERROR, SILENT) |
| `CLAUDE_MEM_FETCH_VERBOSE` | *(unset / off)* | Opt-in worker-IPC `fetch()` diagnostics (`1`/`true`/`on`/`yes`). Passes Node/undici `{ verbose: true }` and writes the error cause chain on socket-level hook failures. Default stays off. |
| `CLAUDE_MEM_SESSION_INIT_TIMEOUT_MS` | `10000` (`7000` on Windows) | Total time the UserPromptSubmit hook may spend reaching the worker for each prompt (startup check, session init, semantic context). When it runs out, the prompt goes through without memory for that turn. Accepts 500–14000; it has to stay under Claude Code's 15 s timeout for that hook. The clock starts after the hook process has loaded, which takes 4–5 s on Windows, so on Windows the default is 7000 and any higher value is cut to 7000. Codex keeps its own bounded worker-startup wait, and its requests stay within this budget. Also read from the environment. |
| `CLAUDE_MEM_IDLE_EXIT_SEC` | `0` (off) | Opt-in worker idle exit, in seconds. `0` (the default) never exits, and values from 1 to 59 are raised to 60. Once this long passes with no session activity or running observer, no queued work, no open or recent request (a viewer tab, a memory search, a corpus build) and no AI interaction, the worker stops through the same graceful shutdown as `claude-mem stop` (telemetry `shutdown_reason: idle`). The next hook that reads memory, such as session start or your next prompt, starts it again. That first prompt pays a cold start and goes without memory if the boot outlasts the hook's time budget, and observations captured in between wait in the hook spool until the worker is back. Turn it on only where claude-mem's hooks run, such as Claude Code and Codex. Leave it off for OpenCode plugin capture and OpenClaw, which never start the worker, and for MCP-only hosts, where the first memory call after each idle exit waits for a worker boot. It stays off with `CLAUDE_MEM_WORKER_AUTOSTART=false` or while transcript watches are active, since nothing would start the worker again. Cloud sync and transcript capture run only while the worker is up. Also read from the environment. |
| `CLAUDE_MEM_TOOL_USES_RETENTION_DAYS` | `0` (keep forever) | Opt-in retention for the raw tool input/response index behind `get_tool_uses`. With a positive number of days, the worker deletes `tool_uses` rows older than that **and** linked to an observation that still exists, once at start. Rows with no observation, or whose observation was deleted, are the only copy of that tool I/O and are never deleted. A purged id returns the usual not-found result from `get_tool_uses`. Freed pages are reused by SQLite; shrinking the file on disk needs a `VACUUM`. `30` and `"30"` both work. Anything that is not a whole number of days (empty, negative, `abc`) keeps everything. |
| `CLAUDE_MEM_PYTHON_VERSION` | `3.13` | Python version for chroma-mcp |
| `CLAUDE_MEM_CHROMA_UVX_PATH` | *(empty — search uv's install folders, then PATH)* | The `uvx` that launches chroma-mcp, as the full path to the binary (on Windows, e.g. `C:\Users\you\AppData\Local\Programs\Python\Python313\Scripts\uvx.exe`) or its folder. Set it when `pip install uv` put `uvx` outside uv's usual folders, or when another tool's `uvx` comes first on PATH. An environment variable of the same name overrides `settings.json`. File/env only — not writable via the viewer HTTP API. Restart the worker after changing it. |
| `CLAUDE_CODE_PATH` | *(auto-detect)* | Path to Claude Code CLI (for Windows). File/env only — not writable via the viewer HTTP API. |
| `CLAUDE_MEM_PROJECT_NAME_SOURCE` | `path` | How a git repository's project name is derived: `path` (the repository folder's name) or `git-remote` (a stable `org/repo` slug from the `origin` remote, which survives renaming the folder and tells same-named repositories apart; every worktree of the repository shares it). Opt-in. Memory stored under the folder name before you switch stays readable. See [Project Names](#project-names). |
| `CLAUDE_MEM_PROJECT_ENVIRONMENTS` | `[]` | Named environments: a JSON array of `{"name", "patterns"}`. Folders matching an environment's glob patterns (the same rules as `CLAUDE_MEM_EXCLUDED_PROJECTS`) share one project named after it. See [Project Names](#project-names). |
| `CLAUDE_MEM_CLAUDE_CONFIG_DIR` | *(unset — falls through to `CLAUDE_CONFIG_DIR`/`~/.claude`)* | Override which `CLAUDE_CONFIG_DIR` profile's OAuth keychain entry to read, and which `CLAUDE_CONFIG_DIR` the spawned SDK subprocess sees. For running multiple named Claude Code profiles (e.g. `~/.claude-profiles/<name>`, each logged in separately) side by side on one machine. macOS only for the keychain lookup; Windows/Linux credential stores are not profile-aware yet. |
| `CLAUDE_MEM_OBSERVER_CLAUDE_CONFIG_DIR` | *(unset — transcripts follow the credential profile dir)* | Transcript-only `CLAUDE_CONFIG_DIR` for claude-mem's internal SDK sessions (observer, knowledge corpus). By default they persist under `~/.claude/projects/`, where importers like Codex pick them up as user chats; set this to a dedicated directory (e.g. `~/.claude-mem/observer-claude`) to keep them out. Credentials are unaffected — the worker keeps reading your default login and injects a fresh OAuth token at each spawn, so the directory itself never needs to be logged in. Only honored while `CLAUDE_MEM_CLAUDE_CONFIG_DIR` is unset (an explicit profile keeps its transcripts beside its credentials by design). Two things to know: a token-injected subprocess cannot refresh the token itself — capture pauses with the usual re-login notice if your Claude Code login expires — and sessions recorded before you set this cannot be resumed — a corpus primed before enabling this misses its resume once, and its next query recovers automatically through the existing reprime path into a fresh session here. To carry the old session over instead of starting fresh, move the store first: `mkdir -p <dir>/projects && mv ~/.claude/projects/-<munged-home>-claude-mem-observer-sessions <dir>/projects/`. |

### Grok Bot Brainbeat Webhook

Optional. Set `CLAUDE_MEM_GROK_BOT_WEBHOOK_URL` and claude-mem POSTs every observation that matches the Grok Bot awareness triggers (`CLAUDE_MEM_GROK_BOT_AWARENESS_TRIGGER_TYPES` / `CLAUDE_MEM_GROK_BOT_AWARENESS_TRIGGER_CONCEPTS`, default types `decision,bugfix,security_alert,sensitive`) to that URL. It is independent of every Telegram setting.

| Setting | Default | Description |
| - | - | - |
| `CLAUDE_MEM_GROK_BOT_WEBHOOK_URL` | — | Receiver for brainbeat POSTs; empty = off. File/env only, masked by `GET /api/settings` |
| `CLAUDE_MEM_GROK_BOT_WEBHOOK_SECRET` | — | Optional shared secret sent as `x-claude-mem-shared-secret`. File/env only, masked by `GET /api/settings` |

Each matching observation is sent as one JSON POST:

```json theme={null}
{
  "event": "claude_mem.brainbeat",
  "observation_id": 1234,
  "type": "security_alert",
  "title": "PII exposure in logs",
  "subtitle": "Raw token printed in retry path",
  "project": "payments-service",
  "concepts": ["auth", "logging"],
  "why_fired": {
    "matched_type": true,
    "matched_concepts": ["auth"]
  },
  "timestamp": "2026-09-02T02:56:46.087Z"
}
```

POSTs are sent concurrently and each times out after 5 seconds. Redirects are refused, so the shared secret and the observation only ever go to the configured URL; put the receiver's final address in the setting. A failure is logged with the receiver's origin and a short reason only (never the full URL) and never blocks observation storage or other notifications.

### Near-Duplicate Deduplication

Opt-in (off by default) dedup of observations whose titles describe the same recurring
work but are worded slightly differently, so `content_hash` (byte-identical only) misses them.
Two deterministic tiers:

* **Tier 0 — exact-normalized-title** → safe silent auto-merge: a new observation whose
  title matches an existing one after lowercasing / whitespace-collapse / punctuation-strip
  is collapsed onto the existing row and its `occurrence_count` is bumped (cross-session,
  within the same project, the same host platform and the same agent scope: main session
  work never merges into a subagent row, which SessionStart leaves out). Rows stored before
  an upgrade are re-keyed by `POST /api/dedup/scan`.
* **Tier 1 — IDF-weighted similarity** → *review-only* near-duplicate **candidates** are
  recorded in `observation_dedup_candidates` (never auto-merged), so distinct work that
  differs only in one rare token (`rdlp-api` vs `rdlp-plugin`) is never silently destroyed.

| Setting | Default | Description |
| - | - | - |
| `CLAUDE_MEM_DEDUP_ENABLED` | `false` | Master switch. Off = byte-identical legacy behavior |
| `CLAUDE_MEM_DEDUP_COSINE_THRESHOLD` | `0.80` | Min IDF-weighted cosine for a Tier-1 candidate |
| `CLAUDE_MEM_DEDUP_IDF_VETO_DF` | `10` | A title token in ≤ N project rows is "discriminating" and vetoes a merge |
| `CLAUDE_MEM_DEDUP_MIN_SHARED_TOKENS` | `2` | Require ≥ N shared tokens before scoring (kills sparse-vector noise) |
| `CLAUDE_MEM_DEDUP_MIN_PROJECT_DOCS` | `10` | Cold-start gate: skip Tier-1 below N docs/project (IDF unreliable) |
| `CLAUDE_MEM_DEDUP_MAX_SCAN` | `2000` | Per-insert Tier-1 candidate-scan cap |
| `CLAUDE_MEM_DEDUP_MAX_BACKFILL_ROWS` | `50000` | `dedup-scan` skips a project larger than this (memory safety) |

After enabling on an existing database, run a one-time scan to backfill the IDF model and
surface accumulated near-duplicates: `POST /api/dedup/scan` (worker, localhost-only).
Review candidates via `GET /api/dedup/candidates?project=<name>` (add `&status=pending` to see only
unreviewed ones), and record a verdict with `POST /api/dedup/candidates/<id>/resolve` and a body of
`{"status": "distinct"}` or `{"status": "dismissed"}`. A later scan keeps the verdict.

## Model Configuration

Configure which Claude model compresses your observations (only applies when `CLAUDE_MEM_PROVIDER=claude`).

### Available Models

| Value | Notes |
| - | - |
| `claude-haiku-4-5-20251001` | Default — fastest, ideal for compression |
| `claude-sonnet-5` | Balanced quality and speed |
| `claude-opus-4-8` | Highest quality (slowest) |

### Picking via the Installer

`npx claude-mem install` prompts for the Claude model (when the Claude provider is selected) and persists the choice to `~/.claude-mem/settings.json`.

### Manual Configuration

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

```json theme={null}
{
  "CLAUDE_MEM_MODEL": "claude-haiku-4-5-20251001"
}
```

## Mode Configuration

Configure the active workflow mode and language.

### Settings

| Setting | Default | Description |
| - | - | - |
| `CLAUDE_MEM_MODE` | `code` | Defines behavior and language. See [Modes & Languages](modes). |

### Examples

**Spanish Code Mode:**

```json theme={null}
{
  "CLAUDE_MEM_MODE": "code--es"
}
```

**Email Investigation Mode:**

```json theme={null}
{
  "CLAUDE_MEM_MODE": "email-investigation"
}
```

## Project Names

claude-mem files every observation under a project name, and SessionStart injects the memory stored for the current project.

* **Inside a git repository** the name is the repository root's folder name, so every subfolder shares it. A git worktree is stored as `<repo>/<worktree>` (a worktree whose folder has the repository's own name, like Codex's `~/.codex/worktrees/<id>/<repo>`, is stored as `<repo>`) and a git submodule as `<superproject>/<path>`; both also read their parent repository's memory. Memory a submodule stored under its own folder name before it was grouped this way stays readable from it. When a worktree or submodule checkout is deleted, the worker folds its memory into the parent repository at its next start (merged or not), so nothing is stranded.
* **With `CLAUDE_MEM_PROJECT_NAME_SOURCE=git-remote`** a repository that has an `origin` remote is named by its `org/repo` slug instead (e.g. `thedotmack/claude-mem`), so renaming or re-cloning the folder keeps its memory, two repositories with the same folder name stay apart, and every worktree of the repository shares the slug (a submodule, being a repository of its own, is named by its own `origin`). Memory stored under the folder-based names stays readable, and a deleted worktree's memory from before the switch is still folded into the repository. Repositories without a usable `origin` (or with a local one) keep the folder-based name.
* **Outside git** the name is the current folder's name. To give a non-git project one name across all of its subfolders, put an empty `.claude-mem-project` file (or a `.claude-mem.json`) in its root folder: every folder below it then uses the root folder's name. Memory stored under a subfolder's own name before you added the file stays readable from that subfolder. Marker files in your home directory, the system temp directory or Claude's config directory are ignored, so they can never fold unrelated folders together.
* **Named environments** (`CLAUDE_MEM_PROJECT_ENVIRONMENTS`) group several folders, git or not, into one project and win over every rule above. For example, `[{"name": "acme", "patterns": ["~/work/acme/**"]}]` files everything under `~/work/acme` as `acme`, and SessionStart labels it as an environment. Memory those folders stored under their own names stays readable from them; to fold it into the environment for good, run `npx claude-mem project merge <old-name> acme` (it runs inside claude-mem's worker whenever the worker is running). The merge rewrites nothing (rows are marked as merged, the way a worktree folds into its repository) and brings along memory already folded into the old name, such as a merged worktree's. It reaches your other devices through cloud sync and updates semantic search; if that last step fails, the command says so, and running it again retries it.

## Files and Directories

### Data Directory Structure

The data directory location depends on the environment:

* **Production (installed plugin)**: `~/.claude-mem/` (always, regardless of CLAUDE\_PLUGIN\_ROOT)
* **Development**: Can be overridden with `CLAUDE_MEM_DATA_DIR`

```
~/.claude-mem/
├── claude-mem.db           # SQLite database
├── .install-version        # Version marker written by `npx claude-mem install`/`repair`
├── settings.json           # Worker port + provider/model settings
└── logs/
    ├── worker-out.log      # Worker stdout logs
    └── worker-error.log    # Worker stderr logs
```

### Plugin Directory Structure

```
${CLAUDE_PLUGIN_ROOT}/
├── .claude-plugin/
│   └── plugin.json         # Plugin metadata
├── .mcp.json               # MCP server configuration
├── hooks/
│   └── hooks.json          # Hook configuration
├── scripts/                # Built executables
│   ├── claude-mem-launcher.cjs # Compiled at install into the on-PATH `claude-mem` hook launcher
│   ├── ensure-launcher.cjs # Startup SessionStart self-heal for the launcher
│   ├── version-check.js    # Setup hook (--init / --maintenance): completes missing dependencies, records the install marker
│   ├── worker-service.cjs  # Worker service + hook dispatcher (CJS)
│   └── mcp-server.cjs      # MCP search server (CJS)
└── ui/
    └── viewer.html         # Web viewer UI bundle
```

## Plugin Configuration

### Hooks Configuration

Hooks are registered in `plugin/hooks/hooks.json`. Each runtime hook is one exec-form entry with no shell, `{"command": "claude-mem", "args": ["hook", "claude-code", "<event>"]}`. Claude Code finds `claude-mem` on PATH: a small compiled launcher that `npx claude-mem install` / `update` place at `~/.local/bin` (POSIX) or `%LOCALAPPDATA%\claude-mem\bin` (Windows). The launcher runs the single dispatcher, `worker-service.cjs hook claude-code <event>`, under Bun. The events wired up are:

* `Setup` → `version-check.js` (installs missing plugin dependencies, records `.install-version`). The only bash entry; Claude Code fires it only for `claude --init` / `--maintenance`.
* `SessionStart` → `claude-mem start` (worker, async), then `hook claude-code context` (context injection); at startup also `node ${CLAUDE_PLUGIN_ROOT}/scripts/ensure-launcher.cjs`, which places or refreshes the launcher for marketplace-only installs
* `UserPromptSubmit` → `hook claude-code session-init`
* `PreToolUse` (matcher `Read`) → `hook claude-code file-context` (synchronous: adds the file's observation timeline as context and can block whole-file Reads; see [File Read Gate](/file-read-gate))
* `PostToolUse` (matcher `*`) → `hook claude-code observation`
* `Stop` → `hook claude-code summarize`
* `SessionEnd` → `hook claude-code session-end`

The exact `hooks.json` entries are generated by `scripts/build-hooks.js` and shipped with the plugin; do not hand-edit them in the marketplace copy unless you know what you're doing. `npx claude-mem doctor` shows a **Hook launcher** row for the `claude-mem` the hooks will run.

#### Turning off the tool hooks

These switches are read from the hook's environment only, not from `~/.claude-mem/settings.json`. Set them under the `env` block in `~/.claude/settings.json` (Claude Code passes that block to every hook) or export them in your shell:

| Variable | Effect when set to `1` |
| - | - |
| `CLAUDE_MEM_DISABLE_TOOL_HOOKS` | PreToolUse (`file-context`) and PostToolUse (`observation`) return a no-op right away. SessionStart, UserPromptSubmit and Stop keep working. |
| `CLAUDE_MEM_DISABLE_OBSERVATION` | Only PostToolUse `observation` returns a no-op (tool calls are no longer captured). |
| `CLAUDE_MEM_DISABLE_FILE_CONTEXT` | Only PreToolUse `file-context` returns a no-op: no file history is injected before `Read`, and the [File Read Gate](/file-read-gate) never blocks a Read. |

Claude Code still launches each hook. The `claude-mem` hook launcher checks these switches before resolving the plugin or starting Bun, so a disabled tool hook does not load the worker bundle. The Codex shell hooks check them before starting Node; the Codex Windows launcher still starts Node, then checks the switch before resolving scripts or starting Bun. These switches do not change the feature settings in `settings.json`.

#### Turning off the end-of-session summary

| Variable | Effect when set to `1` |
| - | - |
| `CLAUDE_MEM_DISABLE_SUMMARY` | The Stop hook (`summarize`) skips the end-of-session summary and advisor-call capture: no observer-model call and no `session_summaries` row. SessionStart and UserPromptSubmit keep working, and Kimi's context refresh after a compaction still happens. |

Orchestrators that launch short headless runs (a `codex exec` review of a staged diff, say) usually set `CLAUDE_MEM_DISABLE_OBSERVATION=1` so nothing the run observes is captured. The summary switch completes the picture for those runs: they keep **reading** claude-mem context at session start, but their Stop no longer writes a summary of an intermediate diff into the project's recent summaries. Unlike the tool-hook switches, this check runs inside the summarize handler, so the hook process still starts and reads its input before the summary is skipped.

### Search Configuration

Claude-Mem provides MCP search tools for querying your project history.

**No configuration required** - MCP tools are automatically available in Claude Code sessions.

Search operations are provided via:

* **MCP Server**: 3 tools (search, timeline, get\_observations) with progressive disclosure
* **HTTP API**: 10 endpoints on the worker service port (per-user, default `37700 + (uid % 100)`; see `~/.claude-mem/settings.json`)
* **Auto-Invocation**: Claude recognizes natural language queries about past work

## Worker Service Management

Worker service is managed by Bun as a background process. The worker auto-starts on first session and runs continuously in the background.

### Observation TV Remote Access

The worker binds to `127.0.0.1` by default and has **no request authentication** — the loopback bind is its only defence. `CLAUDE_MEM_TV_TOKEN` adds a read-only broadcast surface so a second device on your LAN (a phone, an iPad, a spare monitor) can watch Observation TV and do nothing else.

Mint a token:

```bash theme={null}
node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"
```

The host setting and the token work as a pair:

| `CLAUDE_MEM_WORKER_HOST` | `CLAUDE_MEM_TV_TOKEN` | Result |
| - | - | - |
| `127.0.0.1` (default) | empty | Today. Nothing reachable off-box. **Recommended for everyone not using the TV remotely.** |
| `127.0.0.1` | set | Token is inert — nothing can reach the port anyway. Harmless. |
| `0.0.0.0` | **empty** | **Dangerous, and unchanged from today**: the full API — settings incl. provider API keys, deletes, import, better-auth — is on the LAN. This is what the Docker setup already tells people to do, so the worker warns rather than refuses to bind. |
| `0.0.0.0` | set | The point of the feature. LAN devices reach `/tv`, `/tv.html`, `/stream`, `GET /api/observations` with the secret, and get 404/403/401 for everything else. |

Booting with a non-loopback host and no token logs a `SECURITY` warning; the worker still binds.

**A local port-forward reopens the whole API.** The guard exempts loopback by socket peer, so anything that arrives *as* loopback bypasses it entirely — including `ssh -L <port>:127.0.0.1:<port> <box>` from another device, or any local forwarding proxy. To the worker that traffic is indistinguishable from the operator's own browser, so it gets the full API, `GET /api/settings` and its provider API keys included. This is the one concrete way "the device can do nothing else" stops being true: only forward the port to devices you would hand the machine to.

**Docker and bridge networking.** With `CLAUDE_MEM_WORKER_HOST=0.0.0.0` inside a bridge-network container, requests from the host's own browser arrive from the bridge gateway address, not `127.0.0.1`. Once a token is set, that browser is treated as remote like any other device and must supply `?token=` to open the TV — and the React viewer at `/` is denied outright, exactly as it is for any other remote device.

Open the TV on the second device at `http://<lan-ip>:<port>/tv.html?token=<secret>`.

**The React viewer at `/` stops working remotely when a token is set.** That is intended — the viewer needs the write and settings routes the guard denies. Loopback is never gated, so the viewer keeps working normally on the machine running the worker.

**Treat the URL as the secret.** The token rides in the query string for `/stream` because the browser's `EventSource` API cannot set request headers. It is *not* written to the worker log (the request logger records `req.path`, which excludes the query string), but it **will** be in the browser's history on the device you open it on. `Authorization: Bearer <token>` and `X-Api-Key: <token>` also work for anything that can set headers.

**This is plain HTTP.** The token stops an unauthenticated device from reading the stream; it does not encrypt it. Anyone who can sniff your LAN sees observation titles. For a home network that is the accepted tradeoff; for anything else, terminate TLS in front of the worker (out of scope here) — and still never a tunnel to the unmodified worker, which would publish `GET /api/settings` and its provider API keys to the open internet.

**Use the exact paths.** The allowlist is exact-match and case-sensitive: `/tv.html`, `/tv`, `/stream`, `/api/observations` and nothing else. A trailing slash or a different case — `/tv/`, `/API/observations`, `/api/observations/by-file` — returns 404 even with a valid token. That is deliberate fail-closed behavior, not a bug.

The TV's `?project=` and `?source=` filters are **client-side only**. They are display filters, not access control — a token holder still receives every project's observations.

Accepted risks, stated plainly:

1. **`GET /api/observations` returns full observation bodies** — `narrative`, `facts`, `text`, `files_read`, `files_modified` — for **every project on the box**, not just the four fields the TV renders. A token holder can page through the entire memory database with `offset`.
2. **`/stream` is unfiltered.** It carries every observation for every project on the box, plus the project catalog and processing status. There is no per-client filtering.
3. **No rate limiting.** A token holder can hammer `GET /api/observations` freely.
4. **The token is readable on loopback** via `GET /api/settings`, exactly like your provider API keys are today. It is deliberately *not* writable through `POST /api/settings` (that route is unauthenticated), so it can only be set by someone with filesystem or environment access.
5. **`/stream` is not side-effect-free.** Every new connection triggers an `initial_load` broadcast to *all* connected clients, and the client list is unbounded. A token holder reconnecting in a loop can therefore disturb the operator's own local viewer. This is pre-existing worker behavior; the token is what newly makes it reachable from the LAN.

### Manual Configuration

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

```json theme={null}
{
  "CLAUDE_MEM_WORKER_HOST": "0.0.0.0",
  "CLAUDE_MEM_TV_TOKEN": "your-minted-token"
}
```

Then restart the worker:

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

### Watching Off-LAN (cmem.ai Pro)

Everything above is the LAN path. Watching from *outside* your network — on cellular, at a coffee shop, from another house — is a **cmem.ai Pro** feature: open `https://cmem.ai/tv` in any browser while signed in to your account. It requires [Cloud Sync](/cloud-sync) to be enabled, because the hosted page reads titles your worker has already pushed to your sync hub.

**No token, no open port, no inbound connection.** This path needs neither `CLAUDE_MEM_TV_TOKEN` nor a non-loopback `CLAUDE_MEM_WORKER_HOST` — both belong to the LAN path and have no effect on it, so leave them at their defaults. The box never accepts an inbound connection for the hosted TV; the worker only ever dials out. No tunnel (cloudflared, ngrok, or anything like them) is needed, and none is recommended.

**The hosted TV surface shows observation titles and nothing else.** It never renders narratives, facts, file lists, snippets or prompt text.

**That is not the same as "only titles leave your machine."** The hosted TV is a feature *of* cloud sync, and cloud sync uploads your observation narratives and your full prompt text to the sync hub under your cmem.ai account. The hosted page is titles-only; the upload standing behind it is not. Don't enable cloud sync if that content must stay on your machine.

**One rendering difference.** An observation with no title still appears on the LAN TV, which falls back to the subtitle. It does not appear on the hosted phone TV — that surface receives titles only, so it has no subtitle to fall back to.

## Folder Context Files

Claude-mem can automatically generate `CLAUDE.md` files in your project folders with activity timelines. This feature is disabled by default.

| Setting | Default | Description |
| - | - | - |
| `CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED` | `false` | Enable auto-generation of folder CLAUDE.md files |

## Grok Bot live INDEX

The worker writes a growing observation INDEX into each Grok Bot seat’s Memory mid-attach file (`agents/<uuid>/memory/log/zz-claude-mem-inject.md`). See [Grok Bot Integration](/grok-bot).

| Setting | Default | Description |
| - | - | - |
| `CLAUDE_MEM_GROK_BOT_INJECT_ENABLED` | `true` | Live-write the INDEX. `false` disables it. No-op when no Grok Bot seats exist. |
| `CLAUDE_MEM_GROK_BOT_INJECT_AGENT_IDS` | `*` | `*` / `all` / empty = every live seat; or a comma-separated UUID list. |
| `CLAUDE_MEM_GROK_BOT_INJECT_FALLBACK` | `house` | `house` fills thin seat diaries from newest worker observations. `off` = seat project only. |
| `CLAUDE_MEM_GROK_BOT_INJECT_TIER` | `episode` | Memory rank prefix (`episode`, `plain`, `note`). |
| `CLAUDE_MEM_GROK_BOT_INJECT_WINDOW` | `80` | Newest INDEX rows to keep (max 100). |
| `CLAUDE_MEM_GROK_BOT_INJECT_PLATFORM_SOURCE` | — | Optional host filter. Leave empty unless you want grok-only rows. |
| `CLAUDE_MEM_GROK_BOT_INJECT_PROJECTS_BY_AGENT` | — | Optional `uuid=projA,projB;uuid2=projC` override of transcript-watch projects. |

See [Folder Context Files](usage/folder-context) for full documentation on how this feature works, configuration options, and git integration recommendations.

## Context Injection Configuration

Claude-Mem injects past observations into each new session, giving Claude awareness of recent work. You can configure exactly what gets injected using the **Context Settings Modal**.

### Context Settings Modal

Access the settings modal from the web viewer. The worker prints its URL on startup; the port comes from `CLAUDE_MEM_WORKER_PORT`.

1. Click the **gear icon** in the header
2. Adjust settings in the right panel
3. See changes reflected live in the **Terminal Preview** on the left
4. Click **Save** to keep your changes

The Terminal Preview shows the selected project and source. Select **All sources** to preview a combined SessionStart context.

### Loading Settings

Control how many observations are injected:

| Setting | Default | Range | Description |
| - | - | - | - |
| **Observations** | 50 | 1-200 | Total number of recent observations to include |
| **Include all sources at session start** | Off | On/Off | Include observations from Claude, Codex, and other harnesses in startup context |
| **Sessions** | 10 | 1-50 | Number of recent sessions to pull observations from |

**Considerations**:

* **Higher values** = More context but slower SessionStart and more tokens used
* **Lower values** = Faster SessionStart but less historical awareness
* Default of 50 observations from 10 sessions balances context richness with performance

### Filter Settings

Control which observation types and concepts are included:

**Types** (select any combination):

* `bugfix` - Bug fixes and error resolutions
* `feature` - New functionality additions
* `refactor` - Code restructuring
* `discovery` - Learnings about how code works
* `decision` - Architectural or design decisions
* `change` - General code changes

**Concepts** (select any combination):

* `how-it-works` - System behavior explanations
* `why-it-exists` - Rationale for code/design
* `what-changed` - Change summaries
* `problem-solution` - Problem/solution pairs
* `gotcha` - Edge cases and pitfalls
* `pattern` - Recurring patterns
* `trade-off` - Design trade-offs

Use "All" or "None" buttons to quickly select/deselect all options.

### Display Settings

Control how observations appear in the context:

**Full Observations**:

| Setting | Default | Options | Description |
| - | - | - | - |
| **Count** | 5 | 0-20 | How many observations show expanded details |
| **Field** | narrative | narrative, facts | Which field to expand |

The most recent N observations (set by Count) show their full narrative or facts. Remaining observations show only title, type, and token counts in a compact table format.

**Token Economics** (toggles):

| Setting | Default | Description |
| - | - | - |
| **Read cost** | true | Show tokens to read each observation |
| **Work investment** | true | Show tokens spent creating the observation |
| **Savings** | true | Show total tokens saved by reusing context |

Token economics help you understand the value of cached observations vs. re-reading files.

### Advanced Settings

| Setting | Default | Description |
| - | - | - |
| **Model** | sonnet | AI model for generating observations |
| **Worker Port** | `37700 + (uid % 100)` | Port for background worker service (override with `CLAUDE_MEM_WORKER_PORT`) |
| **MCP search server** | true | Enable Model Context Protocol search tools |
| **Include last summary** | false | Add previous session's summary to context |
| **Include last message** | false | Add previous session's final message |
| **Block full-file reads** | true | Block whole-file Reads of code files of 32 KB and up that have observation history ([File Read Gate](/file-read-gate)) |

### Manual Configuration

Settings are stored in `~/.claude-mem/settings.json`:

```json theme={null}
{
  "CLAUDE_MEM_CONTEXT_OBSERVATIONS": "100",
  "CLAUDE_MEM_SESSION_START_INCLUDE_ALL_SOURCES": "true",
  "CLAUDE_MEM_CONTEXT_SESSION_COUNT": "20",
  "CLAUDE_MEM_CONTEXT_OBSERVATION_TYPES": "bugfix,decision,discovery",
  "CLAUDE_MEM_CONTEXT_OBSERVATION_CONCEPTS": "how-it-works,gotcha",
  "CLAUDE_MEM_CONTEXT_FULL_COUNT": "10",
  "CLAUDE_MEM_CONTEXT_FULL_FIELD": "narrative",
  "CLAUDE_MEM_CONTEXT_SHOW_READ_TOKENS": "true",
  "CLAUDE_MEM_CONTEXT_SHOW_WORK_TOKENS": "true",
  "CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_AMOUNT": "true",
  "CLAUDE_MEM_CONTEXT_SHOW_LAST_SUMMARY": "false",
  "CLAUDE_MEM_CONTEXT_SHOW_LAST_MESSAGE": "false"
}
```

**Note**: The Context Settings Modal (in the web viewer) is the recommended way to configure these settings, as it provides live preview of changes.

## Customization

Settings can be customized in `~/.claude-mem/settings.json`.

### Custom Data Directory

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

```json theme={null}
{
  "CLAUDE_MEM_DATA_DIR": "/custom/path"
}
```

### Custom Worker Port

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

```json theme={null}
{
  "CLAUDE_MEM_WORKER_PORT": "38000"
}
```

Then restart the worker:

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

### Custom Model

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

```json theme={null}
{
  "CLAUDE_MEM_MODEL": "opus"
}
```

Then restart the worker:

```bash theme={null}
export CLAUDE_MEM_MODEL=opus
npm run worker:restart
```

### Custom Skip Tools

Control which tools are excluded from observations. Edit `~/.claude-mem/settings.json`:

```json theme={null}
{
  "CLAUDE_MEM_SKIP_TOOLS": "ListMcpResourcesTool,SlashCommand,Skill"
}
```

**Default excluded tools:**

* `ListMcpResourcesTool`
* `SlashCommand`
* `Skill`
* `TodoWrite`
* `AskUserQuestion`

**Common customizations:**

* Include TodoWrite: Remove from skip list to track task planning
* Include AskUserQuestion: Remove to capture decision-making conversations
* Skip additional tools: Add tool names to reduce observation noise

Changes take effect on the next tool execution (no worker restart needed).

## Advanced Configuration

### Hook Timeouts

Hook timeouts are set in `plugin/hooks/hooks.json`. The current defaults match the shape of the workload at each lifecycle stage:

* Setup (`version-check.js`, `claude --init` / `--maintenance` only): 300s ceiling; fast when the plugin's dependencies are complete, up to 120s when it has to run `bun install`
* SessionStart (worker-start + context): 60s
* SessionStart (ensure-launcher, startup only, synchronous): 180s, enough to compile the launcher
* UserPromptSubmit: 15s
* PreToolUse (file-context, Read matcher): 15s, synchronous so the [File Read Gate](/file-read-gate) can block a Read; its worker lookup gives up after 3s
* PostToolUse (observation): 120s
* Stop (summary): 120s

`npx claude-mem install` / `npx claude-mem repair` install the runtime (Bun, uv, `bun install`) outside the session lifecycle. The Setup hook only runs `bun install` when the loaded plugin's dependencies are missing — typically a plugin-marketplace install or `claude plugin update` — and writes the `.install-version` marker once they are complete. Claude Code does not fire Setup on plugin install or update, so run `claude --init-only` or `npx claude-mem install` to trigger that repair.

### Worker Memory Limit

The worker service is managed by Bun and will automatically restart if it encounters issues. Memory usage is typically low (\~100-200MB).

### Logging Verbosity

Enable debug logging:

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

## Configuration Best Practices

1. **Use defaults**: Default configuration works for most use cases
2. **Override selectively**: Only change what you need
3. **Document changes**: Keep track of custom configurations
4. **Test after changes**: Verify worker restarts successfully
5. **Monitor logs**: Check worker logs after configuration changes

## Troubleshooting Configuration

### Configuration Not Applied

1. Restart worker after changes:
   ```bash theme={null}
   npm run worker:restart
   ```

2. Verify environment variables:
   ```bash theme={null}
   echo $CLAUDE_MEM_MODEL
   echo $CLAUDE_MEM_WORKER_PORT
   ```

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

### Invalid Model Name

If you specify an invalid Claude model name, the worker logs a warning and uses the default. Valid Claude models for `CLAUDE_MEM_MODEL`:

* `claude-haiku-4-5-20251001` (default)
* `claude-sonnet-5`
* `claude-opus-4-8`

### Port Already in Use

The default worker port is `37700 + (uid % 100)`, so different OS users on the same machine get different ports automatically. If you still hit a collision (e.g. running multiple profiles as the same UID), set a fixed port:

1. Set custom port:
   ```bash theme={null}
   export CLAUDE_MEM_WORKER_PORT=38000
   ```

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

3. Verify new port:
   ```bash theme={null}
   curl -s http://127.0.0.1:$CLAUDE_MEM_WORKER_PORT/api/health | jq .port
   ```

## Next Steps

* [Architecture Overview](architecture/overview) - Understand the system
* [Troubleshooting](troubleshooting) - Common issues
* [Development](development) - Building from source


# Custom Anthropic-Compatible Backends
Source: https://docs.claude-mem.ai/configuration/custom-anthropic-backends

Point claude-mem at bridged or self-hosted Anthropic-compatible API endpoints with ANTHROPIC_BASE_URL

# Custom Anthropic-Compatible Backends

When you use the `claude` provider, claude-mem talks to the Anthropic API through the Claude Agent SDK. By default, the SDK targets the official Anthropic endpoint, but it honors the standard `ANTHROPIC_BASE_URL` environment variable. That means you can route claude-mem at any Anthropic-protocol-compatible backend — for example a corporate gateway, a regional bridge, or a third-party provider that exposes an Anthropic-shaped API — without changing any claude-mem source code.

<Note>
  This page documents how to **persist a custom base URL** so claude-mem's worker uses it consistently. For OpenAI-compatible upstream providers, use a gateway such as LiteLLM and follow the [LiteLLM Gateway](litellm-gateway) guide.
</Note>

## When to Use This

Use `ANTHROPIC_BASE_URL` if you need claude-mem's observation worker to talk to:

* A **corporate Anthropic gateway** (proxy in front of `api.anthropic.com`)
* A **regional Anthropic deployment** (e.g. AWS Bedrock or GCP Vertex via an Anthropic-compatible shim)
* A **third-party provider** that bridges its API to the Anthropic protocol

If your provider only speaks the OpenAI chat-completions protocol, put a gateway such as LiteLLM in front of it and point claude-mem's Claude Agent SDK path at that gateway. See [LiteLLM Gateway](litellm-gateway) for the full routing model.

## How the Plumbing Works

The flow is intentionally simple:

1. **You write the credential** to `~/.claude-mem/.env`.
2. **`EnvManager.loadClaudeMemEnv()`** reads that file (`src/shared/EnvManager.ts:67`).
3. **`buildIsolatedEnv()`** copies `ANTHROPIC_BASE_URL` into the worker's spawn environment alongside explicit gateway or API credentials (`src/shared/EnvManager.ts:164`).
4. **`ClaudeProvider.startSession()`** spawns the Claude Agent SDK with that isolated env (`src/services/worker/ClaudeProvider.ts:115`). The SDK reads `ANTHROPIC_BASE_URL` natively — claude-mem does not parse or rewrite it.

Because the variable is isolated to the worker process, your interactive Claude Code sessions are unaffected; only the background memory agent uses the override.

## Configuration

### Step 1: Edit `~/.claude-mem/.env`

The credentials file is a plain `KEY=VALUE` env file at `~/.claude-mem/.env` (mode `0600`). Add or update the `ANTHROPIC_BASE_URL` line:

```bash theme={null}
# ~/.claude-mem/.env
ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_BASE_URL=https://your-gateway.example.com/v1
```

If the file does not yet exist, create it. The directory permissions are enforced to `0700` and the file to `0600` automatically on the next worker write.

### Step 2: Pick a Compatible Model

`CLAUDE_MEM_MODEL` (in `~/.claude-mem/settings.json`) is passed straight through to the SDK. The model name **must be one your bridge accepts** — claude-mem does not translate names.

```json theme={null}
{
  "CLAUDE_MEM_MODEL": "claude-haiku-4-5-20251001"
}
```

If your bridge expects a non-Anthropic model name (for example, a Bedrock inference profile), set that string here instead.

### Step 3: Restart the Worker

Credentials are loaded when the worker spawns the SDK, so a restart is required after you edit `.env`:

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

## Worked Example: Corporate Gateway

Suppose your team runs `https://anthropic-proxy.internal.example.com` in front of `api.anthropic.com` for audit and rate-limit purposes. The proxy accepts the same protocol and the same model names.

`~/.claude-mem/.env`:

```bash theme={null}
ANTHROPIC_API_KEY=sk-corp-...
ANTHROPIC_BASE_URL=https://anthropic-proxy.internal.example.com
```

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

```json theme={null}
{
  "CLAUDE_MEM_PROVIDER": "claude",
  "CLAUDE_MEM_MODEL": "claude-haiku-4-5-20251001"
}
```

Restart, and the next observation will be routed through your gateway.

## Verifying

After restarting, watch the worker logs for the next observation flush:

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

A successful request through your gateway shows the standard `SDK Starting SDK query` line followed by `Response received`. If the gateway rejects the request, the SDK error surfaces verbatim in `worker-error.log` — there is no silent fallback to the public Anthropic endpoint.

## Limitations and Gotchas

* **No model-name translation.** If your bridge expects `glm-4.7` and `CLAUDE_MEM_MODEL` is `claude-haiku-4-5-20251001`, the request will fail. Pin `CLAUDE_MEM_MODEL` to a name your bridge recognizes.
* **Gateway auth usually uses `ANTHROPIC_AUTH_TOKEN`.** For LiteLLM gateway mode, store the gateway key or virtual key as `ANTHROPIC_AUTH_TOKEN`. Use `ANTHROPIC_API_KEY` for direct Anthropic API-key mode or gateways that explicitly expect it.
* **`ANTHROPIC_BASE_URL` from your shell is not inherited.** `ANTHROPIC_API_KEY` is in the BLOCKED\_ENV\_VARS list (`src/shared/EnvManager.ts:10`) to prevent accidental billing on a shell-leaked key — `ANTHROPIC_BASE_URL` is not blocked, but it must still be set in `~/.claude-mem/.env` for the worker to pick it up reliably across restarts. Do not rely on shell exports.
* **No auto-detection.** If you have already configured `ANTHROPIC_BASE_URL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`, etc. for Claude Code itself, claude-mem will **not** read those today. Mirror the relevant values into `~/.claude-mem/.env` and `~/.claude-mem/settings.json`.

## Related

* [Configuration](../configuration) — All claude-mem settings
* [LiteLLM Gateway](litellm-gateway): Route the Claude Agent SDK path through LiteLLM
* [OpenRouter Provider](../usage/openrouter-provider) — OpenAI-compatible bridge for non-Anthropic protocols
* [Gemini Provider](../usage/gemini-provider) — Native Gemini API alternative


# LiteLLM Gateway
Source: https://docs.claude-mem.ai/configuration/litellm-gateway

Route claude-mem's Claude Agent SDK worker through LiteLLM while keeping one agentic execution path

# LiteLLM Gateway

claude-mem can route its background memory agent through a LiteLLM proxy. This lets teams keep claude-mem's Claude Agent SDK workflow while using LiteLLM for model routing, centralized credentials, usage tracking, budgets, audit logs, and provider failover.

The important detail: claude-mem does **not** call LiteLLM with the OpenAI client directly. claude-mem still uses the Claude Agent SDK, and the SDK sends Anthropic-format requests to LiteLLM. LiteLLM then translates those requests to the upstream model provider you configured.

```text theme={null}
Claude Code session
  -> claude-mem hooks
  -> claude-mem worker
  -> Claude Agent SDK subprocess
  -> ANTHROPIC_BASE_URL=http://localhost:4000
  -> LiteLLM proxy
  -> OpenAI / Azure / Vertex / Bedrock / OpenRouter / local model
```

This keeps the memory agent on one implementation path. The Claude provider, knowledge agents, session resume behavior, XML observation prompts, and queue retry logic all continue to use the same SDK code path whether the upstream model is Anthropic or routed through LiteLLM.

## When to Use This

Use LiteLLM gateway mode when you want:

* A single organization-level LLM gateway for claude-mem traffic
* Provider routing without changing claude-mem source code
* Centralized API keys instead of storing provider keys in each developer's claude-mem settings
* LiteLLM budgets, rate limits, logging, fallback routing, or virtual keys
* A non-Anthropic upstream model while preserving the Claude Agent SDK execution path used by claude-mem

Use the native [OpenRouter Provider](../usage/openrouter-provider) or [Gemini Provider](../usage/gemini-provider) instead if you want claude-mem's REST providers directly and do not need the Claude Agent SDK path.

## Architecture

### One Agent Path

The LiteLLM integration is intentionally small. There is no custom LiteLLM provider, no Python handler, and no OpenAI-compatible server embedded in claude-mem.

At runtime:

1. The installer or user writes gateway settings to `~/.claude-mem/.env`.
2. `~/.claude-mem/settings.json` keeps `CLAUDE_MEM_PROVIDER` set to `claude`.
3. The worker starts the Claude Agent SDK with an isolated environment.
4. The SDK reads `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN`.
5. LiteLLM receives the SDK's Anthropic-format request.
6. LiteLLM maps the request to the upstream provider and model configured in LiteLLM.
7. The SDK response is parsed by the normal claude-mem observation pipeline.

The code paths involved are:

| Layer | Responsibility |
| - | - |
| `src/npx-cli/commands/install.ts` | Prompts for "LiteLLM or custom gateway", stores the gateway URL/token, and allows custom gateway model names |
| `src/shared/EnvManager.ts` | Stores credentials in `~/.claude-mem/.env`, blocks shell-leaked auth vars, and injects only explicit claude-mem credentials |
| `src/services/worker/ClaudeProvider.ts` | Starts the Claude Agent SDK for observation extraction with the isolated environment |
| `src/services/worker/knowledge/KnowledgeAgent.ts` | Uses the same isolated SDK path for knowledge corpus Q\&A |

### Why `CLAUDE_MEM_PROVIDER` Stays `claude`

LiteLLM is a gateway for the Claude Agent SDK path, not a fourth claude-mem provider.

```json theme={null}
{
  "CLAUDE_MEM_PROVIDER": "claude",
  "CLAUDE_MEM_CLAUDE_AUTH_METHOD": "gateway",
  "CLAUDE_MEM_MODEL": "claude-haiku-4-5-20251001"
}
```

Keeping the provider as `claude` matters because the worker should continue to use `ClaudeProvider`, not the native Gemini or OpenRouter REST providers. The gateway URL changes where the SDK sends model traffic; it does not change how claude-mem manages memory sessions.

## Configure LiteLLM

LiteLLM must expose an Anthropic-compatible endpoint for Claude Code / Claude Agent SDK traffic. Anthropic's gateway guidance recommends the unified LiteLLM endpoint as the normal setup:

```bash theme={null}
export ANTHROPIC_BASE_URL=http://localhost:4000
```

For claude-mem, that value goes in `~/.claude-mem/.env`, not your shell, so the background worker uses it consistently across restarts.

### Minimal LiteLLM Example

Create a LiteLLM config that defines the model name claude-mem will request:

```yaml theme={null}
# litellm-config.yaml
model_list:
  - model_name: claude-haiku-4-5-20251001
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY

litellm_settings:
  master_key: sk-litellm-local
```

Start LiteLLM:

```bash theme={null}
OPENAI_API_KEY=sk-your-openai-key \
litellm --config litellm-config.yaml --host 127.0.0.1 --port 4000
```

In this example, claude-mem asks the SDK for `claude-haiku-4-5-20251001`, LiteLLM accepts that model alias, and LiteLLM forwards the request to `openai/gpt-4o-mini`.

<Note>
  The alias in `model_name` must match `CLAUDE_MEM_MODEL`, or `CLAUDE_MEM_MODEL` must be changed to match your LiteLLM alias. claude-mem does not translate model names.
</Note>

## Configure claude-mem

### Option 1: Installer

Run the installer:

```bash theme={null}
npx claude-mem install
```

Choose:

1. `Claude Agent SDK`
2. `API key or gateway`
3. `LiteLLM or custom gateway`
4. Your LiteLLM URL, for example `http://127.0.0.1:4000`
5. Your LiteLLM key/token if the proxy requires one
6. The model alias LiteLLM should receive

The installer stores provider settings in `~/.claude-mem/settings.json` and gateway credentials in `~/.claude-mem/.env`.

### Option 2: Manual Files

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

```json theme={null}
{
  "CLAUDE_MEM_PROVIDER": "claude",
  "CLAUDE_MEM_CLAUDE_AUTH_METHOD": "gateway",
  "CLAUDE_MEM_MODEL": "claude-haiku-4-5-20251001"
}
```

Edit `~/.claude-mem/.env`:

```bash theme={null}
# ~/.claude-mem/.env
ANTHROPIC_BASE_URL=http://127.0.0.1:4000
ANTHROPIC_AUTH_TOKEN=sk-litellm-local
```

If your LiteLLM proxy does not require authentication, omit `ANTHROPIC_AUTH_TOKEN`.

Restart the worker after manual edits:

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

## Environment Isolation

claude-mem deliberately does not trust whatever Anthropic credentials happen to be exported in your shell or project `.env` file.

The worker blocks inherited `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, and stale `CLAUDE_CODE_OAUTH_TOKEN` values. It then re-injects only the credentials stored in `~/.claude-mem/.env`.

This avoids two common failure modes:

* A project-level `ANTHROPIC_API_KEY` silently bypasses LiteLLM and bills the public Anthropic API.
* An expired Claude Code OAuth token overrides a configured gateway token and causes confusing auth failures.

If `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, or `ANTHROPIC_API_KEY` is present in `~/.claude-mem/.env`, the worker treats that as explicit gateway/API configuration and skips Claude OAuth lookup. This prevents a configured gateway from falling back to `api.anthropic.com`.

## Model Names

`CLAUDE_MEM_MODEL` is passed through to the Claude Agent SDK. In gateway mode, claude-mem allows any non-empty model string because the valid model list is owned by LiteLLM.

Recommended pattern:

```yaml theme={null}
model_list:
  - model_name: claude-haiku-4-5-20251001
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY
```

Then keep:

```json theme={null}
{
  "CLAUDE_MEM_MODEL": "claude-haiku-4-5-20251001"
}
```

Alternatively, use a descriptive custom alias:

```yaml theme={null}
model_list:
  - model_name: memory-compressor
    litellm_params:
      model: azure/gpt-4o-mini-memory
      api_base: os.environ/AZURE_API_BASE
      api_key: os.environ/AZURE_API_KEY
      api_version: "2024-10-21"
```

```json theme={null}
{
  "CLAUDE_MEM_MODEL": "memory-compressor"
}
```

## Request Flow

When a Claude Code session produces transcript events, claude-mem's worker queues them for observation extraction. In gateway mode the extraction flow is:

1. The worker loads pending messages for a memory session.
2. `ClaudeProvider` builds the observation prompt and selected model.
3. `buildIsolatedEnvWithFreshOAuth()` loads `~/.claude-mem/.env`.
4. The SDK subprocess starts with `ANTHROPIC_BASE_URL` pointing at LiteLLM.
5. LiteLLM receives the Anthropic-format request.
6. LiteLLM routes to the configured upstream model.
7. The SDK streams the assistant response back to the worker.
8. claude-mem parses observations, stores them in SQLite, and syncs searchable embeddings.

The knowledge-agent APIs use the same gateway environment, so corpus priming and corpus Q\&A route through LiteLLM too.

## What LiteLLM Does and Does Not Replace

LiteLLM replaces:

* Upstream model selection
* Provider credentials
* Gateway-level budgets and rate limits
* Gateway-level logging and auditing
* Optional routing/fallback policies inside LiteLLM

LiteLLM does not replace:

* claude-mem's worker process
* The Claude Agent SDK subprocess
* claude-mem's observation XML format
* SQLite storage
* Chroma/vector sync
* Hook installation
* Session resume handling inside claude-mem

## Verification

Check claude-mem's worker logs:

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

You should see SDK startup logs that report gateway auth, followed by normal observation processing.

Check LiteLLM's logs for a corresponding request to the configured model alias. If LiteLLM never receives traffic, confirm:

* `CLAUDE_MEM_PROVIDER` is `claude`
* `CLAUDE_MEM_CLAUDE_AUTH_METHOD` is `gateway`
* `ANTHROPIC_BASE_URL` is in `~/.claude-mem/.env`
* The worker was restarted after manual edits
* The LiteLLM URL does not include an extra `/v1` suffix for the unified Anthropic endpoint

## Troubleshooting

### LiteLLM returns "model not found"

The model name sent by claude-mem does not match a LiteLLM `model_name`. Make `CLAUDE_MEM_MODEL` and the LiteLLM alias match exactly.

### claude-mem still uses Anthropic directly

Check `~/.claude-mem/.env`. Gateway settings must be stored there. Shell exports are not the reliable configuration source for the worker.

Also make sure `ANTHROPIC_BASE_URL` is present. A token alone authenticates a gateway, but the base URL is what redirects traffic away from the default Anthropic endpoint.

### Authentication fails

If LiteLLM uses a master key or virtual key, store it as `ANTHROPIC_AUTH_TOKEN` in `~/.claude-mem/.env`. The Claude Agent SDK sends this value as gateway authorization.

If you previously configured a direct Anthropic API key, remove `ANTHROPIC_API_KEY` from `~/.claude-mem/.env` for gateway mode unless your gateway explicitly expects that variable.

### Requests fail after changing files

Restart the worker:

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

The SDK environment is built when SDK subprocesses are spawned. Restarting guarantees the next memory agent process sees the new gateway values.

### Tool use behaves differently than full Claude Code

claude-mem's memory worker disables file and shell tools for observation extraction. The LiteLLM gateway is only handling the model call used to compress and summarize memory; it is not a replacement for your interactive Claude Code tool loop.

## Related

* [Custom Anthropic-Compatible Backends](custom-anthropic-backends)
* [Configuration](../configuration)
* [Worker Service Architecture](../architecture/worker-service)
* [Anthropic LLM gateway configuration](https://docs.anthropic.com/en/docs/claude-code/llm-gateway)
* [LiteLLM documentation](https://docs.litellm.ai/)


# Context Engineering
Source: https://docs.claude-mem.ai/context-engineering

Best practices for curating optimal token sets for AI agents

# Context Engineering for AI Agents

## Core Principle

**Find the smallest possible set of high-signal tokens that maximize the likelihood of your desired outcome.**

***

## Context Engineering vs Prompt Engineering

**Prompt Engineering**: Writing and organizing LLM instructions for optimal outcomes (one-time task)

**Context Engineering**: Curating and maintaining the optimal set of tokens during inference across multiple turns (iterative process)

Context engineering manages:

* System instructions
* Tools
* Model Context Protocol (MCP)
* External data
* Message history
* Runtime data retrieval

***

## The Problem: Context Rot

**Key Insight**: LLMs have an "attention budget" that gets depleted as context grows

* Every token attends to every other token (n² relationships)
* As context length increases, model accuracy decreases
* Models have less training experience with longer sequences
* Context must be treated as a finite resource with diminishing marginal returns

***

## System Prompts: Find the "Right Altitude"

### The Goldilocks Zone

**Too Prescriptive** ❌

* Hardcoded if-else logic
* Brittle and fragile
* High maintenance complexity

**Too Vague** ❌

* High-level guidance without concrete signals
* Falsely assumes shared context
* Lacks actionable direction

**Just Right** ✅

* Specific enough to guide behavior effectively
* Flexible enough to provide strong heuristics
* Minimal set of information that fully outlines expected behavior

### Best Practices

* Use simple, direct language
* Organize into distinct sections (`<background_information>`, `<instructions>`, `## Tool guidance`, etc.)
* Use XML tags or Markdown headers for structure
* Start with minimal prompt, add based on failure modes
* Note: Minimal ≠ short (provide sufficient information upfront)

***

## Tools: Minimal and Clear

### Design Principles

* **Self-contained**: Each tool has a single, clear purpose
* **Robust to error**: Handle edge cases gracefully
* **Extremely clear**: Intended use is unambiguous
* **Token-efficient**: Returns relevant information without bloat
* **Descriptive parameters**: Unambiguous input names (e.g., `user_id` not `user`)

### Critical Rule

**If a human engineer can't definitively say which tool to use in a given situation, an AI agent can't be expected to do better.**

### Common Failure Modes to Avoid

* Bloated tool sets covering too much functionality
* Tools with overlapping purposes
* Ambiguous decision points about which tool to use

***

## Examples: Diverse, Not Exhaustive

**Do** ✅

* Curate a set of diverse, canonical examples
* Show expected behavior effectively
* Think "pictures worth a thousand words"

**Don't** ❌

* Stuff in a laundry list of edge cases
* Try to articulate every possible rule
* Overwhelm with exhaustive scenarios

***

## Context Retrieval Strategies

### Just-In-Time Context (Recommended for Agents)

**Approach**: Maintain lightweight identifiers (file paths, queries, links) and dynamically load data at runtime

**Benefits**:

* Avoids context pollution
* Enables progressive disclosure
* Mirrors human cognition (we don't memorize everything)
* Leverages metadata (file names, folder structure, timestamps)
* Agents discover context incrementally

**Trade-offs**:

* Slower than pre-computed retrieval
* Requires proper tool guidance to avoid dead-ends

### Pre-Inference Retrieval (Traditional RAG)

**Approach**: Use embedding-based retrieval to surface context before inference

**When to Use**: Static content that won't change during interaction

### Hybrid Strategy (Best of Both)

**Approach**: Retrieve some data upfront, enable autonomous exploration as needed

**Example**: Claude Code loads CLAUDE.md files upfront, uses glob/grep for just-in-time retrieval

**Rule of Thumb**: "Do the simplest thing that works"

***

## Long-Horizon Tasks: Three Techniques

### 1. Compaction

**What**: Summarize conversation nearing context limit, reinitiate with summary

**Implementation**:

* Pass message history to model for compression
* Preserve critical details (architectural decisions, bugs, implementation)
* Discard redundant outputs
* Continue with compressed context + recently accessed files

**Tuning Process**:

1. **First**: Maximize recall (capture all relevant information)
2. **Then**: Improve precision (eliminate superfluous content)

**Low-Hanging Fruit**: Clear old tool calls and results

**Best For**: Tasks requiring extensive back-and-forth

### 2. Structured Note-Taking (Agentic Memory)

**What**: Agent writes notes persisted outside context window, retrieved later

**Examples**:

* To-do lists
* NOTES.md files
* Game state tracking (Pokémon example: tracking 1,234 steps of training)
* Project progress logs

**Benefits**:

* Persistent memory with minimal overhead
* Maintains critical context across tool calls
* Enables multi-hour coherent strategies

**Best For**: Iterative development with clear milestones

### 3. Sub-Agent Architectures

**What**: Specialized sub-agents handle focused tasks with clean context windows

**How It Works**:

* Main agent coordinates high-level plan
* Sub-agents perform deep technical work
* Sub-agents explore extensively (tens of thousands of tokens)
* Return condensed summaries (1,000-2,000 tokens)

**Benefits**:

* Clear separation of concerns
* Parallel exploration
* Detailed context remains isolated

**Best For**: Complex research and analysis tasks

***

## Quick Decision Framework

| Scenario | Recommended Approach |
| - | - |
| Static content | Pre-inference retrieval or hybrid |
| Dynamic exploration needed | Just-in-time context |
| Extended back-and-forth | Compaction |
| Iterative development | Structured note-taking |
| Complex research | Sub-agent architectures |
| Rapid model improvement | "Do the simplest thing that works" |

***

## Key Takeaways

1. **Context is finite**: Treat it as a precious resource with an attention budget
2. **Think holistically**: Consider the entire state available to the LLM
3. **Stay minimal**: More context isn't always better
4. **Be iterative**: Context curation happens each time you pass to the model
5. **Design for autonomy**: As models improve, let them act intelligently
6. **Start simple**: Test with minimal setup, add based on failure modes

***

## Anti-Patterns to Avoid

* ❌ Cramming everything into prompts
* ❌ Creating brittle if-else logic
* ❌ Building bloated tool sets
* ❌ Stuffing exhaustive edge cases as examples
* ❌ Assuming larger context windows solve everything
* ❌ Ignoring context pollution over long interactions

***

## Remember

> "Even as models continue to improve, the challenge of maintaining coherence across extended interactions will remain central to building more effective agents."

Context engineering will evolve, but the core principle stays the same: **optimize signal-to-noise ratio in your token budget**.

***

*Based on Anthropic's "Effective context engineering for AI agents" (September 2025)*


# Cursor + Gemini Setup
Source: https://docs.claude-mem.ai/cursor/gemini-setup

Use Claude-Mem in Cursor with your Gemini API key

# Cursor + Gemini Setup

Use your Google Gemini key so memory notes run off-plan (they do not spend your Claude subscription). You do **not** clone the repo.

## Install

1. Get a key at [Google AI Studio](https://aistudio.google.com/apikey).
2. Run:

```bash theme={null}
npx claude-mem install
```

Pick **Cursor**, then pick **Gemini** as the memory provider and paste the key.

<Warning>
  `npm install -g claude-mem` is the library only. Always install with `npx claude-mem install`.
</Warning>

### Settings by hand (optional)

```bash theme={null}
mkdir -p ~/.claude-mem
cat > ~/.claude-mem/settings.json << 'EOF'
{
  "CLAUDE_MEM_PROVIDER": "gemini",
  "CLAUDE_MEM_GEMINI_API_KEY": "YOUR_GEMINI_API_KEY"
}
EOF
```

Then re-run `npx claude-mem install` so Cursor hooks and the worker are in place. Do not restart a healthy worker.

## Restart Cursor

Close and reopen Cursor so hooks load.

## Verify

Health: `curl -s "http://127.0.0.1:${CLAUDE_MEM_WORKER_PORT}/api/health"` (port also in `~/.claude-mem/.worker.port`). Open the worker URL from install to see notes.

## Models

| Model | Notes |
| - | - |
| `gemini-flash-latest` | **Default.** Current GA Flash |
| `gemini-flash-lite-latest` | Current GA Flash-Lite |
| `gemini-3.5-flash` | Pinned GA Flash |
| `gemini-3.1-flash-lite` | Pinned GA Flash-Lite |

To pin a model:

```json theme={null}
{
  "CLAUDE_MEM_PROVIDER": "gemini",
  "CLAUDE_MEM_GEMINI_API_KEY": "your-key",
  "CLAUDE_MEM_GEMINI_MODEL": "gemini-3.5-flash"
}
```

Rate limits depend on the model and whether billing is on in Google Cloud. Claude-mem spaces requests when billing is off. To turn off that extra throttle after you enable Google billing:

```json theme={null}
{
  "CLAUDE_MEM_GEMINI_BILLING_ENABLED": true
}
```

## Troubleshooting

**Key not configured** — `cat ~/.claude-mem/settings.json` should show `CLAUDE_MEM_PROVIDER` `gemini` and your key.

**HTTP 429** — wait, enable Google billing, or use [OpenRouter](/cursor/openrouter-setup).

**Worker idle** — read `~/.claude-mem/logs/worker-YYYY-MM-DD.log`. Do not restart a healthy worker (the note queue is in memory).

## Next steps

* [Cursor Integration](/cursor) — default CMEM Pro install
* [OpenRouter](/cursor/openrouter-setup)
* [Configuration](/configuration)


# Cursor Integration
Source: https://docs.claude-mem.ai/cursor/index

Persistent memory for Cursor — install with npx, no git clone

# Cursor Integration

Give Cursor a memory that lasts across chats. The installer wires Cursor hooks (small scripts Cursor runs when a session starts, a file is read, or a tool runs), starts the local worker (the program that stores notes), and uses **CMEM Pro** (the hosted memory service) unless you pick another provider.

<CardGroup>
  <Card title="One command" icon="terminal">
    `npx claude-mem install` — do not clone the repo to install.
  </Card>

  <Card title="CMEM Pro default" icon="cloud">
    Memory notes are written off-plan through the hosted service unless you pick Gemini, OpenRouter, or your Anthropic plan.
  </Card>

  <Card title="Cursor hooks" icon="bolt">
    Cursor has hooks. Grok Bot does not — that host is a [different guide](/grok-bot).
  </Card>

  <Card title="Memory viewer" icon="eye">
    Open the worker URL printed at install to browse saved notes.
  </Card>
</CardGroup>

## Install

```bash theme={null}
npx claude-mem install
```

When the installer lists your apps, pick **Cursor**. The three stages are: install runtime, sign in (device code, no email in the CLI), then pick a memory provider. **CMEM Pro is pre-selected.**

Other provider choices: your Gemini key, your OpenRouter key, or your Anthropic plan (`--provider claude`, which skips the sign-in step; local installs contact cmem.ai once, at signup, to create the sign-in link, with a numbers-only usage summary (observation counts and token totals, no prompts, paths, or project names), and nothing else is sent to cmem.ai). Details: [Installation](/installation).

<Warning>
  `npm install -g claude-mem` installs the library only. It does **not** register Cursor hooks or start the worker. Always use `npx claude-mem install`.
</Warning>

Do not clone this repository to install. Clone is for people changing the code.

## How it works

1. **Hooks** record what the agent does in Cursor.
2. **Worker** stores those notes on your machine (default `127.0.0.1`, port in `~/.claude-mem/.worker.port`).
3. **Next chat** gets relevant past notes.
4. **Viewer** at the worker URL shows the knowledge base.

Never restart a healthy worker. The note queue sits in memory; a restart drops it.

## Gemini or OpenRouter instead of CMEM Pro

* [Gemini](/cursor/gemini-setup) — your Google key, memory off-plan
* [OpenRouter](/cursor/openrouter-setup) — your OpenRouter key. **Never** send a personal `sk-or-` key to `https://cmem.ai/api/inference`

## Verify it worked

1. Restart Cursor after install so hooks load.
2. Health: `curl -s "http://127.0.0.1:${CLAUDE_MEM_WORKER_PORT}/api/health"` (or the port in `~/.claude-mem/.worker.port`).
3. Do a small unit of work, then open the worker URL. New notes should appear.

## Troubleshooting

### Nothing is being stored

* Confirm the worker is up. Do **not** restart it if it is already healthy.
* Confirm you used `npx claude-mem install`, not a global `npm install`.
* Restart Cursor once after install.
* Logs: `~/.claude-mem/logs/worker-YYYY-MM-DD.log`

### Hooks not firing

Restart Cursor. Hooks live under `.cursor/` in the project or your user Cursor config after install.

## Next steps

* [Installation](/installation) — installer stages and CMEM Pro
* [CMEM Pro (manual / headless)](/cmem-pro-headless) — settings the installer writes
* [Gemini](/cursor/gemini-setup) / [OpenRouter](/cursor/openrouter-setup)
* [Search Tools](/usage/search-tools) — query project history


# Cursor + OpenRouter Setup
Source: https://docs.claude-mem.ai/cursor/openrouter-setup

Use Claude-Mem in Cursor with your OpenRouter key

# Cursor + OpenRouter Setup

Use your OpenRouter key so memory notes run off-plan on your OpenRouter credit. You do **not** clone the repo.

<Warning>
  **Never** send a personal `sk-or-` key to `https://cmem.ai/api/inference`. For your own OpenRouter account, leave the base URL empty (or `https://openrouter.ai/api/v1`). CMEM Pro uses the cmem.ai inference URL with a **CMEM Pro** key, not your OpenRouter key.
</Warning>

## Install

1. Create a key at [OpenRouter API Keys](https://openrouter.ai/keys).
2. Run:

```bash theme={null}
npx claude-mem install
```

Pick **Cursor**, then pick **your OpenRouter key** as the memory provider.

<Warning>
  `npm install -g claude-mem` is the library only. Always install with `npx claude-mem install`.
</Warning>

### Settings by hand (optional)

```bash theme={null}
mkdir -p ~/.claude-mem
cat > ~/.claude-mem/settings.json << 'EOF'
{
  "CLAUDE_MEM_PROVIDER": "openrouter",
  "CLAUDE_MEM_OPENROUTER_API_KEY": "YOUR_OPENROUTER_API_KEY"
}
EOF
```

Leave `CLAUDE_MEM_OPENROUTER_BASE_URL` unset for OpenRouter itself. Then re-run `npx claude-mem install` so Cursor hooks and the worker are in place. Do not restart a healthy worker.

## Restart Cursor

Close and reopen Cursor so hooks load.

## Verify

Health: `curl -s "http://127.0.0.1:${CLAUDE_MEM_WORKER_PORT}/api/health"`. Open the worker URL from install to see notes.

## Models

Set `CLAUDE_MEM_OPENROUTER_MODEL` if you do not want the default. Free model ids on OpenRouter often end in `:free` — check the [model list](https://openrouter.ai/models?show_free=true).

```json theme={null}
{
  "CLAUDE_MEM_PROVIDER": "openrouter",
  "CLAUDE_MEM_OPENROUTER_API_KEY": "your-key",
  "CLAUDE_MEM_OPENROUTER_MODEL": "poolside/laguna-xs-2.1:free"
}
```

## Other OpenAI-shaped servers

The OpenRouter provider is a generic OpenAI-compatible client. Set `CLAUDE_MEM_OPENROUTER_BASE_URL` to DeepSeek, LM Studio, or any gateway that speaks `/chat/completions`. The model id is sent as-is.

<Info>
  **Base URL resolution:** When `CLAUDE_MEM_OPENROUTER_BASE_URL` is empty (default), requests go to OpenRouter unchanged. When set, claude-mem POSTs to `<base_url>/chat/completions` — you can supply either a base like `https://api.deepseek.com/v1` (the `/chat/completions` path is appended automatically) or a full `.../chat/completions` URL (kept as-is). Trailing slashes are normalized, and the base URL must be an `http`/`https` URL (the settings UI rejects anything else; a hand-edited value that is not one makes requests fail until it is fixed). A query string or fragment on the base URL is preserved while the `/chat/completions` suffix stays in the request path, so `https://my-gateway.example.com/v1?key=abc` resolves to `https://my-gateway.example.com/v1/chat/completions?key=abc`. The environment variable `OPENROUTER_BASE_URL` is honored as a fallback. With the claude-mem observer the base URL is managed by `npx claude-mem install`, and the settings UI shows it read-only.
</Info>

### DeepSeek

```json theme={null}
{
  "CLAUDE_MEM_PROVIDER": "openrouter",
  "CLAUDE_MEM_OPENROUTER_BASE_URL": "https://api.deepseek.com",
  "CLAUDE_MEM_OPENROUTER_MODEL": "deepseek-chat",
  "CLAUDE_MEM_OPENROUTER_API_KEY": "YOUR_DEEPSEEK_API_KEY"
}
```

### LM Studio (local)

```json theme={null}
{
  "CLAUDE_MEM_PROVIDER": "openrouter",
  "CLAUDE_MEM_OPENROUTER_BASE_URL": "http://localhost:1234/v1",
  "CLAUDE_MEM_OPENROUTER_MODEL": "your-local-model-id"
}
```

### IO Intelligence (io.net)

```json theme={null}
{
  "CLAUDE_MEM_PROVIDER": "openrouter",
  "CLAUDE_MEM_OPENROUTER_BASE_URL": "https://api.intelligence.io.solutions/api/v1",
  "CLAUDE_MEM_OPENROUTER_MODEL": "meta-llama/Llama-3.3-70B-Instruct",
  "CLAUDE_MEM_OPENROUTER_API_KEY": "YOUR_IO_INTELLIGENCE_API_KEY"
}
```

Model ids are org/name pairs from the [IO Intelligence model list](https://api.intelligence.io.solutions/api/v1/models), for example `deepseek-ai/DeepSeek-R1-0528` or `zai-org/GLM-4.6`.

## Troubleshooting

**Key not configured** — `cat ~/.claude-mem/settings.json` should show provider `openrouter` and your key.

**Model not found** — check the id at [OpenRouter Models](https://openrouter.ai/models).

**Worker idle** — read `~/.claude-mem/logs/worker-YYYY-MM-DD.log`. Do not restart a healthy worker.

## Next steps

* [Cursor Integration](/cursor) — default CMEM Pro install
* [Gemini](/cursor/gemini-setup)
* [Configuration](/configuration)


# Development
Source: https://docs.claude-mem.ai/development

Build from source, run tests, and contribute to Claude-Mem

# Development Guide

## Building from Source

### Prerequisites

* Node.js 20.0.0 or higher
* npm (comes with Node.js)
* Git

### Clone and Build

```bash theme={null}
# Clone repository
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem

# Install dependencies
npm install

# Build all components
npm run build
```

### Build Process

The build process uses esbuild to compile TypeScript:

1. Compiles TypeScript to JavaScript
2. Creates standalone executables for each hook in `plugin/scripts/`
3. Bundles MCP search server to `plugin/scripts/mcp-server.cjs`
4. Bundles worker service to `plugin/scripts/worker-service.cjs`
5. Bundles web viewer UI to `plugin/ui/viewer.html`

**Build Output**:

* Hook executables: `*-hook.js` (ESM format)
* Setup version-check: `version-check.js` (ESM format, hand-written; installs missing plugin dependencies and records the install marker)
* Worker service: `worker-service.cjs` (CJS format)
* MCP server: `mcp-server.cjs` (CJS format)
* Viewer UI: `viewer.html` (self-contained HTML bundle)

### Committed release bundles

Marketplace installs run the committed files in `plugin/scripts/`. When changing
release versions or worker lifecycle code, regenerate and commit the affected
runtime bundles with `npm run build`. A newer manifest paired with an older
worker bundle can trigger repeated version-mismatch restarts.

CI checks committed bundle versions **before** rebuilding:

```bash theme={null}
bun test tests/infrastructure/version-consistency.test.ts
```

If a replacement worker still reports a stale version, hooks remember the failed
recycle in the data directory and skip further recycles of that unchanged bundle.
Rebuild or reinstall the bundle to correct the version; a changed bundle allows
another recycle attempt.

### Build Scripts

```bash theme={null}
# Build everything
npm run build

# Build only hooks
npm run build:hooks

# The build script is defined in scripts/build-hooks.js
```

## Development Workflow

### 1. Make Changes

Edit TypeScript source files in `src/`:

```
src/
├── hooks/           # Hook implementations (entry points + logic)
├── services/        # Worker service and database
├── servers/         # MCP search server
├── sdk/             # Claude Agent SDK integration
├── shared/          # Shared utilities
├── ui/
│   └── viewer/      # React web viewer UI components
└── utils/           # General utilities
```

### 2. Build

```bash theme={null}
npm run build
```

### 3. Test

```bash theme={null}
# Run all tests
npm test

# Test specific file
node --test tests/session-lifecycle.test.ts

# Test context injection
npm run test:context

# Verbose context test
npm run test:context:verbose
```

### 4. Manual Testing

```bash theme={null}
# Start worker manually
npm run worker:start

# Check worker status
npm run worker:status

# View logs
npm run worker:logs

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

### 5. Iterate

Repeat steps 1-4 until your changes work as expected.

## Viewer UI Development

### Working with the React Viewer

The web viewer UI is a React application built into a self-contained HTML bundle.

**Location**: `src/ui/viewer/`

**Structure**:

```
src/ui/viewer/
├── index.tsx              # Entry point
├── App.tsx                # Main application component
├── components/            # React components
│   ├── Header.tsx         # Header with logo and actions
│   ├── Sidebar.tsx        # Project filter sidebar
│   ├── Feed.tsx           # Main feed with infinite scroll
│   ├── cards/             # Card components
│   │   ├── ObservationCard.tsx
│   │   ├── PromptCard.tsx
│   │   ├── SummaryCard.tsx
│   │   └── SkeletonCard.tsx
├── hooks/                 # Custom React hooks
│   ├── useSSE.ts          # Server-Sent Events connection
│   ├── usePagination.ts   # Infinite scroll pagination
│   ├── useSettings.ts     # Settings persistence
│   └── useStats.ts        # Database statistics
├── utils/                 # Utilities
│   ├── constants.ts       # Constants (API URLs, etc.)
│   ├── formatters.ts      # Date/time formatting
│   └── merge.ts           # Data merging and deduplication
└── assets/                # Static assets (fonts, logos)
```

### Building Viewer UI

```bash theme={null}
# Build everything including viewer
npm run build

# The viewer is built to plugin/ui/viewer.html
# It's a self-contained HTML file with inlined JS and CSS
```

### Testing Viewer Changes

1. Make changes to React components in `src/ui/viewer/`
2. Build: `npm run build`
3. Sync to installed plugin: `npm run sync-marketplace`
4. Restart worker: `npm run worker:restart`
5. Refresh the worker URL printed by `npm run worker:status`

**Hot Reload**: Not currently supported. Full rebuild + restart required for changes.

### Adding New Viewer Features

**Example: Adding a new card type**

1. Create component in `src/ui/viewer/components/cards/YourCard.tsx`:

```tsx theme={null}
import React from 'react';

export interface YourCardProps {
  // Your data structure
}

export const YourCard: React.FC<YourCardProps> = ({ ... }) => {
  return (
    <div className="card">
      {/* Your UI */}
    </div>
  );
};
```

2. Import and use in `Feed.tsx`:

```tsx theme={null}
import { YourCard } from './cards/YourCard';

// In render logic:
{item.type === 'your_type' && <YourCard {...item} />}
```

3. Update types if needed in `src/ui/viewer/types.ts`

4. Rebuild and test

### Viewer UI Architecture

**Data Flow**:

1. Worker service exposes HTTP + SSE endpoints
2. React app fetches initial data via HTTP (paginated)
3. SSE connection provides real-time updates
4. Custom hooks handle state management and data merging
5. Components render cards based on item type

**Key Patterns**:

* **Infinite Scroll**: `usePagination` hook with Intersection Observer
* **Real-Time Updates**: `useSSE` hook with auto-reconnection
* **Deduplication**: `merge.ts` utilities prevent duplicate items
* **Settings Persistence**: `useSettings` hook with localStorage
* **Theme Support**: CSS variables with light/dark/system themes

## Adding New Features

### Adding a New Hook

1. Create hook implementation in `src/hooks/your-hook.ts`:

```typescript theme={null}
#!/usr/bin/env node
import { readStdin } from '../shared/stdin';

async function main() {
  const input = await readStdin();

  // Hook implementation
  const result = {
    hookSpecificOutput: 'Optional output'
  };

  console.log(JSON.stringify(result));
}

main().catch(console.error);
```

**Note**: As of v4.3.1, hooks are self-contained files. The shebang will be added automatically by esbuild during the build process.

2. Add to `plugin/hooks/hooks.json`:

```json theme={null}
{
  "YourHook": [{
    "hooks": [{
      "type": "command",
      "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/your-hook.js",
      "timeout": 120
    }]
  }]
}
```

3. Rebuild:

```bash theme={null}
npm run build
```

### Modifying Database Schema

1. Add migration to `src/services/sqlite/migrations.ts`:

```typescript theme={null}
export const migration011: Migration = {
  version: 11,
  up: (db: Database) => {
    db.run(`
      ALTER TABLE observations ADD COLUMN new_field TEXT;
    `);
  },
  down: (db: Database) => {
    // Optional: define rollback
  }
};
```

2. Update types in `src/services/sqlite/types.ts`:

```typescript theme={null}
export interface Observation {
  // ... existing fields
  new_field?: string;
}
```

3. Update database methods in `src/services/sqlite/SessionStore.ts`:

```typescript theme={null}
createObservation(obs: Observation) {
  // Include new_field in INSERT
}
```

4. Test migration:

```bash theme={null}
# Backup database first!
cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.backup

# Run tests
npm test
```

### Extending SDK Prompts

1. Modify prompts in `src/sdk/prompts.ts`:

```typescript theme={null}
export function buildObservationPrompt(observation: Observation): string {
  return `
    <observation>

    </observation>
  `;
}
```

2. Update parser in `src/sdk/parser.ts`:

```typescript theme={null}
export function parseObservation(xml: string): ParsedObservation {
  // Parse new XML fields
}
```

3. Test:

```bash theme={null}
npm test
```

### Adding MCP Search Tools

1. Add tool definition in `src/servers/mcp-server.ts`:

```typescript theme={null}
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === 'your_new_tool') {
    // Implement tool logic
    const results = await search.yourNewSearch(params);
    return formatResults(results);
  }
});
```

2. Add search method in `src/services/sqlite/SessionSearch.ts`:

```typescript theme={null}
yourNewSearch(params: YourParams): SearchResult[] {
  // Implement FTS5 search
}
```

3. Rebuild and test:

```bash theme={null}
npm run build
npm test
```

## Testing

### Testing Philosophy

Claude-mem relies on **real-world usage and manual testing** rather than traditional unit tests. The project philosophy prioritizes:

1. **Manual verification** - Testing features in actual Claude Code sessions
2. **Integration testing** - Running the full system end-to-end
3. **Database inspection** - Verifying data correctness via SQLite queries
4. **CLI tools** - Interactive tools for checking system state
5. **Observability** - Comprehensive logging and worker health checks

This approach was chosen because:

* Hook behavior depends heavily on Claude Code's runtime environment
* SDK interactions require real API calls and responses
* SQLite and Bun runtime provide stability guarantees
* Manual testing catches integration issues that unit tests miss

### Manual Testing Workflow

When developing new features:

1. **Build and sync**:
   ```bash theme={null}
   npm run build
   npm run sync-marketplace
   npm run worker:restart
   ```

2. **Test in real session**:
   * Start Claude Code
   * Trigger the feature you're testing
   * Verify expected behavior

3. **Check database state**:
   ```bash theme={null}
   sqlite3 ~/.claude-mem/claude-mem.db "SELECT * FROM your_table;"
   ```

4. **Monitor worker logs**:
   ```bash theme={null}
   npm run worker:logs
   ```

5. **Verify queue health** (for recovery features):
   ```bash theme={null}
   bun scripts/check-pending-queue.ts
   ```

### Testing Tools

**Health Checks**:

```bash theme={null}
# Worker status
npm run worker:status

# Queue inspection
WORKER_PORT=$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json)
curl http://127.0.0.1:$WORKER_PORT/api/pending-queue

# Database integrity
sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"
```

**Hook Testing**:

```bash theme={null}
# Test context hook manually
echo '{"session_id":"test-123","cwd":"'$(pwd)'","source":"startup"}' | node plugin/scripts/context-hook.js

# Test new hook
echo '{"session_id":"test-123","cwd":"'$(pwd)'","prompt":"test"}' | node plugin/scripts/new-hook.js
```

**Data Verification**:

```bash theme={null}
# Check recent observations
sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT id, tool_name, created_at
  FROM observations
  ORDER BY created_at_epoch DESC
  LIMIT 10;
"

# Check summaries
sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT id, request, completed
  FROM session_summaries
  ORDER BY created_at_epoch DESC
  LIMIT 5;
"
```

### Recovery Feature Testing

For manual recovery features specifically:

1. **Simulate stuck messages**:
   ```bash theme={null}
   # Manually create stuck message (for testing only)
   sqlite3 ~/.claude-mem/claude-mem.db "
     UPDATE pending_messages
     SET status = 'processing',
         started_processing_at_epoch = strftime('%s', 'now', '-10 minutes') * 1000
     WHERE id = 123;
   "
   ```

2. **Test recovery**:
   ```bash theme={null}
   bun scripts/check-pending-queue.ts
   ```

3. **Verify results**:
   ```bash theme={null}
   WORKER_PORT=$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json)
   curl http://127.0.0.1:$WORKER_PORT/api/pending-queue | jq '.queue'
   ```

### Regression Testing

Before releasing:

1. **Test all hook triggers**:
   * SessionStart: Start new Claude Code session
   * UserPromptSubmit: Submit a prompt
   * PostToolUse: Use a tool like Read
   * Summary: Let session complete
   * SessionEnd: Close Claude Code

2. **Test core features**:
   * Context injection (recent sessions appear)
   * Observation processing (summaries generated)
   * MCP search tools (search returns results)
   * Viewer UI (loads at the worker URL)
   * Manual recovery (stuck messages recovered)

3. **Test edge cases**:
   * Worker crash recovery
   * Database locks
   * Port conflicts
   * Large databases

4. **Cross-platform** (if applicable):
   * macOS
   * Linux
   * Windows

## Code Style

### TypeScript Guidelines

* Use TypeScript strict mode
* Define interfaces for all data structures
* Use async/await for asynchronous code
* Handle errors explicitly
* Add JSDoc comments for public APIs

### Formatting

* Follow existing code formatting
* Use 2-space indentation
* Use single quotes for strings
* Add trailing commas in objects/arrays

### Example

```typescript theme={null}
/**
 * Create a new observation in the database
 */
export async function createObservation(
  obs: Observation
): Promise<number> {
  try {
    const result = await db.insert('observations', {
      session_id: obs.session_id,
      tool_name: obs.tool_name,
      // ...
    });
    return result.id;
  } catch (error) {
    logger.error('Failed to create observation', error);
    throw error;
  }
}
```

## Debugging

### Enable Debug Logging

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

### Inspect Database

```bash theme={null}
sqlite3 ~/.claude-mem/claude-mem.db

# View schema
.schema observations

# Query data
SELECT * FROM observations LIMIT 10;
```

### Trace Observations

Use correlation IDs to 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;
```

### Debug Hooks

Run hooks manually with test input:

```bash theme={null}
# Test context hook
echo '{"session_id":"test-123","cwd":"'$(pwd)'","source":"startup"}' | node plugin/scripts/context-hook.js

# Test new hook
echo '{"session_id":"test-123","cwd":"'$(pwd)'","prompt":"test"}' | node plugin/scripts/new-hook.js
```

## Publishing

Releases ship from `main` only, and pull requests target `main`.

### Version Bump

Update every manifest that carries the package version:

* `package.json`
* `plugin/package.json`
* `.claude-plugin/marketplace.json`
* `.claude-plugin/plugin.json`
* `plugin/.claude-plugin/plugin.json`
* `.codex-plugin/plugin.json`
* `plugin/.codex-plugin/plugin.json`
* `openclaw/openclaw.plugin.json`

Verify the old version is gone and the new version appears everywhere expected:

```bash theme={null}
git grep -n '"version": "NEW_VERSION"'
git grep -n '"version": "OLD_VERSION"'
```

### Build, Tag, and Publish

```bash theme={null}
npm run build-and-sync
git add -A
git commit -m "chore: bump version to NEW_VERSION"
git tag -a vNEW_VERSION -m "Version NEW_VERSION"
git push origin main
git push origin vNEW_VERSION
```

Publishing to npm requires the maintainer's npm credentials and 2FA:

```bash theme={null}
npm publish
npm view claude-mem@NEW_VERSION version
```

Only after npm resolves the version, create the GitHub release and regenerate the
changelog:

```bash theme={null}
gh release create vNEW_VERSION --title "vNEW_VERSION" --notes "..."
npm run changelog:generate
git add CHANGELOG.md
git commit -m "docs: regenerate changelog for vNEW_VERSION"
git push origin main
```

Do not hand-edit `CHANGELOG.md`; it is generated from GitHub releases.

## Contributing

### Contribution Workflow

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Write tests
5. Update documentation
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request

### Pull Request Guidelines

* **Clear title**: Describe what the PR does
* **Description**: Explain why the change is needed
* **Tests**: Include tests for new features
* **Documentation**: Update docs as needed
* **Changelog**: Do not hand-edit `CHANGELOG.md`; it is generated during release
* **Commits**: Use clear, descriptive commit messages

### Code Review Process

1. Automated tests must pass
2. Code review by maintainer
3. Address feedback
4. Final approval
5. Merge to main

## Development Tools

### Recommended VSCode Extensions

* TypeScript
* ESLint
* Prettier
* SQLite Viewer

### Useful Commands

```bash theme={null}
# Check TypeScript types
npx tsc --noEmit

# Lint code (if configured)
npm run lint

# Format code (if configured)
npm run format

# Clean build artifacts
rm -rf plugin/scripts/*.js plugin/scripts/*.cjs
```

## Troubleshooting Development

### Build Fails

1. Clean node\_modules:
   ```bash theme={null}
   rm -rf node_modules
   npm install
   ```

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

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

### Tests Fail

1. Check database:
   ```bash theme={null}
   rm ~/.claude-mem/claude-mem.db
   npm test
   ```

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

3. View logs:
   ```bash theme={null}
   npm run worker:logs
   ```

### Worker Won't Start

1. Kill existing process:
   ```bash theme={null}
   npm run worker:stop
   ```

2. Check port:
   ```bash theme={null}
   WORKER_PORT=$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json)
   lsof -i :$WORKER_PORT
   ```

3. Try custom port:
   ```bash theme={null}
   export CLAUDE_MEM_WORKER_PORT=38000
   npm run worker:start
   ```

## Next Steps

* [Architecture Overview](architecture/overview) - Understand the system
* [Configuration](configuration) - Customize Claude-Mem
* [Troubleshooting](troubleshooting) - Common issues


# File Read Gate
Source: https://docs.claude-mem.ai/file-read-gate

How claude-mem intercepts file reads to save tokens using observation history

# File Read Gate

## What It Is

The File Read Gate stops Claude Code from reading a whole code file that claude-mem already has observations about. Claude gets the file's observation timeline instead, with directions to cheaper sources: `smart_outline` for the file's structure, `smart_unfold` for one symbol, `get_observations` for past work, and a Read with `offset` and `limit` for exact lines.

The gate is **on by default**. See [How to Turn It Off](#how-to-turn-it-off).

This is [progressive disclosure](/progressive-disclosure) applied to file reads: show what exists first, then let Claude fetch only what it needs.

### When It Blocks a Read

All of these must hold:

* **The session is Claude Code** (not Qwen Code), and the Read comes from the main session, not a subagent.
* **The file is code that `smart_outline` can parse** (see the table below).
* **The file is inside the project**, meaning under the session's working directory once symlinks are resolved. `smart_outline` and `smart_unfold` apply the same check, so a symlink in the project that points outside it is never blocked: those tools would refuse it.
* **The file is at least 32 KB.** Smaller files with history get the timeline as context and are never blocked. See [Size Thresholds](#size-thresholds).
* **The file has observation history**, and it **has not been modified since the newest of those observations**.
* **The Read would return the whole file.** Reads of part of a file always go through. See [Whole-File vs Targeted Reads](#whole-file-vs-targeted-reads).
* **The tree-sitter CLI that powers `smart_outline` and `smart_unfold` is installed.** Without it, the Read goes through with the timeline as context, so Claude is never sent to a tool that can't parse the file. Claude Code's plugin install leaves this executable out, so the claude-mem worker downloads it from the tree-sitter GitHub releases in the background each time it starts without one. It only runs or installs a download whose SHA-256 matches the digest claude-mem pins for that tree-sitter version and platform. On a new install the gate turns on a few seconds into the first session. If the download can't reach GitHub, the worker log says so; run `npx claude-mem repair` once the network allows it.

Code files the gate covers:

| Language | Extensions |
| - | - |
| JavaScript | `.js` `.mjs` `.cjs` `.jsx` |
| TypeScript | `.ts` `.mts` `.cts` `.tsx` |
| Python | `.py` `.pyw` |
| Go | `.go` |
| Rust | `.rs` |
| Ruby | `.rb` |
| Java | `.java` |
| Kotlin | `.kt` `.kts` |
| Scala | `.scala` `.sc` |
| Swift | `.swift` |
| C and C++ | `.c` `.h` `.cpp` `.cc` `.cxx` `.hpp` `.hh` |
| PHP | `.php` |
| Lua | `.lua` |
| Haskell | `.hs` |
| Zig | `.zig` |
| Shell | `.sh` `.bash` `.zsh` |
| CSS and SCSS | `.css` `.scss` |
| SQL | `.sql` |

Markdown, YAML, TOML, JSON and every other file type are never blocked. Read is the right tool for them.

Qwen Code runs the Claude Code hooks, and Codex CLI and Kimi run the same hook, but none of them blocks: the hook adds the file's timeline as context and lets the call through. Other hosts don't run this hook.

***

## How It Works

```
Claude calls Read(file_path="/Users/you/code/acme-api/src/billing/invoice-service.ts")
         ↓
   PreToolUse hook runs (synchronous: the Read waits for it)
         ↓
   Subagent? ────────────────────────────────→ Read proceeds, nothing added
         ↓ No
   Project excluded? ────────────────────────→ Read proceeds, nothing added
         ↓ No
   File under 1,500 bytes? ──────────────────→ Read proceeds, nothing added
         ↓ No
   Query worker: GET /api/observations/by-file (3 s budget)
         ↓
   Worker slow or down? ─────────────────────→ Read proceeds, nothing added
         ↓ No
   No observations? ─────────────────────────→ Read proceeds, nothing added
         ↓ Has observations
   File modified since the newest one? ──────→ Read proceeds, nothing added
         ↓ No
   Keep 1 per session, rank by specificity, keep up to 15
         ↓
   Claude Code (not Qwen)? ────── No ──┐
   Gate setting on? ───────────── No ──┤
   Code file? ─────────────────── No ──┤
   At least 32 KB? ────────────── No ──┤
   Inside the project? ────────── No ──┼──→ Read proceeds, timeline added as context
   Whole-file Read? ───────────── No ──┤    (once per session per file)
   Tree-sitter CLI installed? ─── No ──┘
         ↓ Yes to all seven
   DENY the Read: Claude gets the timeline and where to look instead
```

When a Read isn't blocked but the file has current history, the timeline is added to the Read as context: once per session for each file, and again only after a newer observation of the file lands. Reads that stop earlier in the chart get nothing added.

Every whole-file Read of a gated file is blocked, not only the first one.

***

## What Claude Sees

When the gate blocks a Read, Claude Code cancels it and gives Claude this message in its place. In the transcript it appears as a `PreToolUse:Read hook error`; that is the gate at work, not a failure.

```
Current: 2026-10-05 3:25pm PDT
Full-file Read blocked by claude-mem: /Users/you/code/acme-api/src/billing/invoice-service.ts has prior observations (listed below). Get what you need without reading the whole file:
- Current code: call smart_outline(file_path="/Users/you/code/acme-api/src/billing/invoice-service.ts") for its symbols and line numbers, then smart_unfold(file_path="/Users/you/code/acme-api/src/billing/invoice-service.ts", symbol_name="<name>") for the ones you need (MCP tools mcp__plugin_claude-mem_mcp-search__smart_outline / __smart_unfold; load them with ToolSearch if they are deferred).
- Past work: call get_observations(ids=[41890, 42298, 42301]) for the observations below that matter (~300 tokens each).
- Exact lines, e.g. before an Edit: call Read on this file again with offset and limit around the lines smart_outline reported. Partial reads are allowed and satisfy Edit's read requirement.
The titles below are history from earlier sessions, not the file's current contents.
### Sep 28, 2026
41890 4:30p 🟣 Added proration for mid-cycle plan changes
### Oct 3, 2026
42298 1:50p 🔄 Split invoice totals into calculateSubtotal and applyTaxes
42301 2:15p 🔴 Fixed rounding error in multi-currency invoice totals
```

Each timeline line is `<id> <time> <type> <title>`, grouped by day, oldest first. Type icons: 🔴 bugfix, 🟣 feature, 🔄 refactor, 🔵 discovery, ⚖️ decision, ✅ change.

<Note>
  The block goes to Claude, not to you. There is no approval prompt to click through. To let whole-file Reads through, [turn the gate off](#how-to-turn-it-off).
</Note>

***

## Whole-File vs Targeted Reads

| Read call | Result |
| - | - |
| `Read(file_path)` with no `offset` or `limit` | Blocked |
| `offset` of 0 or 1 (or none) and a `limit` of at least the file's line count | Blocked: it returns the whole file |
| `limit` smaller than the file's line count | Allowed |
| `offset` greater than 1 | Allowed |

Targeted Reads are how Claude gets exact lines for an Edit. Claude Code's Edit tool refuses to change a file that hasn't been Read in the session, and a Read of part of the file satisfies that rule. A typical edit:

1. `Read(file_path)`: blocked. Claude gets the timeline and the directions above.
2. `smart_outline(file_path)`: every symbol with its line range.
3. `Read(file_path, offset=120, limit=40)`: allowed. Just the function to change.
4. `Edit(...)`: works, because step 3 was a Read of the file.

A targeted Read right after a block doesn't repeat the timeline, since the block already showed it.

***

## The Decision Tree

After a block, Claude's options, cheapest first:

| Option | Token Cost | When to Use |
| - | - | - |
| **Timeline only** (semantic priming) | 0 extra | The titles tell Claude enough to proceed |
| **get\_observations(ids=\[...])** | \~300 each | Need the details of past work |
| **smart\_outline** | \~1-2k | Need the file's current structure and line numbers |
| **smart\_unfold** | \~400-2k per symbol | Need one function or class in full |
| **Read with offset and limit** | Only the lines read | Need exact lines, for example before an Edit |
| **Whole-file Read** | The whole file | Blocked while the gate is on: read the part you need with `offset` and `limit` |

The smart tool costs come from the [Smart Explore benchmark](/smart-explore-benchmark).

***

## Current Date/Time for Temporal Reasoning

The message starts with the current date and time:

```
Current: 2026-10-05 3:25pm PDT
```

This lets Claude tell how old each observation is. The format matches the SessionStart context header (`YYYY-MM-DD time timezone`), so Claude sees the same temporal markers throughout its session.

The gate already steps aside when the file was modified after its newest observation, so a blocked file hasn't changed since that observation. Older titles can still describe earlier versions of the code, which is why the message labels them as history, not the file's current contents.

***

## Token Economics

Reading a large source file in full costs thousands to tens of thousands of tokens. The deny message that replaces it costs:

| Component | Tokens |
| - | - |
| Header and directions | \~250 (the path appears three times, so long paths add a little) |
| Each observation line | \~20 |
| **Whole message at the 15-observation cap** | **\~550-600** |

If Claude needs more detail, each observation costs \~300 tokens through `get_observations`.

### Real-World Example

Changing `WorkerService.shutdown()` in this repository's `src/services/worker-service.ts` (1,932 lines).

Without the gate:

```
Read (whole file)                           ~22,000 tokens
```

With the gate:

```
Blocked Read: deny message (5 observations)    ~360 tokens
smart_outline                                ~1,340 tokens
Read offset=1006 limit=67 (shutdown only)      ~890 tokens
Total                                        ~2,600 tokens (about 88% less)
```

Token counts on this page are estimates at 4 characters per token.

***

## Specificity Ranking

The worker returns up to 40 observations of the file, newest first. The gate keeps one per session (the newest), scores each by how specifically it concerns this file, and keeps the 15 highest. Ties go to the newer observation.

| Signal | Score Bonus |
| - | - |
| File was **modified** (not just read) | +2 |
| Observation covers **3 or fewer** total files | +2 |
| Observation covers **4-8** total files | +1 |
| Observation covers **9+** files (survey-like) | +0 |

The score decides which observations make the cut. The ones kept are listed oldest first, grouped by day. An observation where this file was the main thing changed beats one where it was read alongside 20 others.

***

## Hook Timing

The `PreToolUse` hook on `Read` is **synchronous**. It has to be, because only a synchronous hook can block a tool call. Every Read waits for it.

* The hook gives the worker at most **3 seconds** for its health check and the observation lookup together. If the worker is slow or not running, the hook stops waiting and the Read goes ahead with nothing added. The gate fails open.
* Claude Code's timeout for this hook is **15 seconds**, a backstop well above that budget.
* If the hook fails for any other reason, it returns a no-op. An error never blocks a Read.

***

## Configuration

### Size Thresholds

* Files under **1,500 bytes** get nothing: no timeline and no block. At that size, reading the file costs about as much as the timeline would.
* Files from 1,500 bytes up to **32 KB** get the timeline as context, but are never blocked.
* Code files of **32 KB and up** can be blocked.

A block isn't free. The denied Read is a turn, and so is every `smart_outline`, `smart_unfold` or targeted Read after it, and each turn re-reads the whole conversation. A block saves the file it keeps out of context. That saving outgrows those turns only on larger files. The read-gate eval (`evals/read-gate` in the repository) asked the same walkthrough question with the gate on and off:

| File | `claude-sonnet-5-5` | `claude-opus-5-5` |
| - | - | - |
| 513 lines, 19 KB | -6% | +20% |
| 941 lines, 49 KB | -35% | -32% |

Both thresholds are fixed in `src/cli/handlers/file-context.ts`.

### Project Exclusions

Projects matching patterns in `CLAUDE_MEM_EXCLUDED_PROJECTS` skip the hook entirely: no block, no timeline. Configure this in `~/.claude-mem/settings.json`:

```json theme={null}
{
  "CLAUDE_MEM_EXCLUDED_PROJECTS": "/tmp/*,/scratch/*"
}
```

### How to Turn It Off

Any of these turns the gate off:

* **Settings file.** In `~/.claude-mem/settings.json`:

  ```json theme={null}
  {
    "CLAUDE_MEM_FILE_READ_GATE_ENABLED": "false"
  }
  ```

* **Viewer.** Open the settings (gear icon), expand **Advanced**, switch off **Block full-file reads**, and click **Save**.

* **Environment.** Set `CLAUDE_MEM_FILE_READ_GATE_ENABLED=false` where the hook can see it: export it in your shell before starting Claude Code, or add it under `env` in `~/.claude/settings.json`. It overrides the settings file.

A change made in the settings file or the viewer applies from the next Read, with no restart. Only the value `false` turns the gate off; any other value leaves it on. In `settings.json`, write it as the string `"false"`, as above.

With the gate off, every Read goes through and the file's timeline is still added as context, once per session for each file.

To turn off the whole hook, timeline included, set `CLAUDE_MEM_DISABLE_FILE_CONTEXT=1` in the hook's environment (see [Turning off the tool hooks](/configuration#turning-off-the-tool-hooks)). Claude Code still starts the `claude-mem` hook launcher for each Read, but it exits before starting Bun or the worker bundle.

<Note>
  With the gate off, Claude reads whole files whenever it chooses. That costs more tokens on large files but saves the extra tool calls, which can be the better trade for small projects or when observations are sparse.
</Note>

***

## How It Fits Together

The File Read Gate is one piece of claude-mem's layered context strategy:

1. **Session Start**: inject a timeline of recent observations (layer 1: metadata)
2. **File Read Gate**: answer a whole-file Read of a code file with that file's timeline (layer 1: metadata)
3. **get\_observations**: fetch specific observation details on demand (layer 2: details)
4. **smart\_outline / smart\_unfold**: read the current code's structure, or one symbol (layer 3: source)
5. **Read with offset and limit**: exact lines, for example before an Edit (layer 3: source)

Each layer costs more than the one before. The gate makes Claude start at the cheapest layer and escalate only when needed. A whole-file Read still happens wherever the gate steps aside: small and non-code files, files changed since their last observation, subagents, other hosts, installs without the tree-sitter CLI, or with the gate turned off.


# Grok Bot Integration
Source: https://docs.claude-mem.ai/grok-bot/index

Persistent memory for Grok Bot — no host hooks, no Claude CLI, no xAI API key

# Grok Bot Integration

> **Your Grok Bot remembers.** Claude-mem captures what the agent does, compresses it, and injects it into later sessions.

<CardGroup>
  <Card title="No host hooks" icon="ban">
    Ingest is a transcript watcher on agent JSONL, not Cursor-style hooks.
  </Card>

  <Card title="CMEM Pro default" icon="cloud">
    `npx claude-mem install --ide grok-bot` pre-selects CMEM Pro. `--provider host` is opt-in.
  </Card>

  <Card title="Independent of Cursor" icon="puzzle-piece">
    Install Grok Bot only, Cursor only, or both. Neither host requires the other.
  </Card>

  <Card title="MCP search" icon="magnifying-glass">
    Search past sessions with the 3-layer memory tools.
  </Card>
</CardGroup>

<Info>
  This install path ships in **claude-mem 13.24** ([PR #3842](https://github.com/thedotmack/claude-mem/pull/3842)). npm 13.23.x does not yet accept `--ide grok-bot`. Grok Bot is **not** Grok Build CLI. Plugin id: **`claude-mem-grok-bot`**.
</Info>

## How it works

Grok Bot has no session-start, file-read, or tool-use hooks. Claude-mem wires up these pieces instead:

1. **Transcript watcher** tails `agent-transcripts/*/*.jsonl` and stamps `platformSource=grok-bot`.
2. **Local worker** stores sessions and serves search (default port `37700 + uid % 100` on `127.0.0.1`).
3. **Observer (CMEM Pro by default)** — observation extraction runs off-plan through `https://cmem.ai/api/inference/v1` with model `cmem-observer`. Opt in to a **host observer** with `--provider host` (this Grok login over a local OpenAI-compatible loopback, no API key).
4. **MCP** exposes search to the bot (`search` → `timeline` → `get_observations`).
5. **Live timeline INDEX** — as observations land, the worker rewrites `agents/<agent_id>/memory/log/zz-claude-mem-inject.md`. The host already mid-attaches that file as Memory facts. The file keeps growing (newest IDs slide on; oldest slide off). Thin per-seat diaries are filled from the newest house observations so a seat with only a handful of its own rows still gets a useful INDEX.
6. **Awareness push (pilot)** — after an observation is stored, needle types are appended as one dated fact line into that bot's Grok memory log (`YYYY-MM.md`). That is not the INDEX.

Do not install Claude CLI for this host. Do not pass an xAI API key. There is no `--provider grok` flag.

Grok Bot does **not** use Claude Code hook stdin, so the `#2188` empty-stdin / `CAPTURE_BROKEN` path does not apply. Capture is the transcript watcher. Each watch now carries `agentId` into ingest so observations stay labeled with the bot they came from.

## Install

### CLI (Grok Bot only)

```bash theme={null}
npx claude-mem install --ide grok-bot
```

That starts a **local worker** with **CMEM Pro** as the observer (pre-selected). Local host-login observer is opt-in:

```bash theme={null}
npx claude-mem install --ide grok-bot --provider host
```

`--ide` takes a **single** host. To also wire Cursor, run a second install (do not pass `--ide` twice on one command — only the last value is kept):

```bash theme={null}
npx claude-mem install --ide cursor
```

Other options:

```bash theme={null}
# Remote worker
npx claude-mem install --ide grok-bot --runtime server --server-url https://YOUR_HOST

# Remote observer (cmem.ai or any OpenAI-compatible URL)
npx claude-mem install --ide grok-bot --provider openrouter
```

`--provider` also still accepts `claude` and `gemini`. Passing an explicit `--provider` skips the sign-in step.

<Warning>
  `npm install -g claude-mem` installs the SDK only. It does not start the worker, watcher, or observer. Always use `npx claude-mem install`.
</Warning>

### Plugin store

Grok Bot's plugin store **is** the Cursor catalog. Install **`claude-mem-grok-bot`** from there when the listing is live (submitted at [cursor.com/marketplace/publish](https://cursor.com/marketplace/publish) after 13.24 lands). The listing does not install Cursor.

After the plugin is installed, still run the CLI above for a local worker, or set `CLAUDE_MEM_MCP_TOKEN` for remote MCP.

## Observer and worker

| Piece | Default | Opt-in / remote |
| - | - | - |
| Worker | `npx claude-mem install --ide grok-bot` | `--runtime server --server-url` |
| Observer | CMEM Pro (`cmem-observer` at `https://cmem.ai/api/inference/v1`) | `--provider host` (loopback, logged-in Grok Bot, no API key) or `--provider openrouter` |
| MCP | `npx -y claude-mem mcp` | `https://cmem.ai/api/mcp` with `Authorization: Bearer ${CLAUDE_MEM_MCP_TOKEN}` |

`--provider host` is an OpenRouter-shaped loopback: `CLAUDE_MEM_OPENROUTER_BASE_URL=http://127.0.0.1:<shim>/v1` plus a dummy non-empty API key. You do not configure that by hand.

**Port rule:** the observer shim must **not** bind the worker port. The worker is often `37700 + (uid % 100)`. On macOS it is often **37777** — if that port is taken, the shim uses **37778** (or `CLAUDE_MEM_HOST_OBSERVER_PORT`).

Never restart a healthy worker. The observation queue is in RAM and a restart drops it.

Host-observer idle replies must be `skip_summary` XML; a finished unit is one `observation`. Prose like "still observing" **drops the batch** ([issue #2485](https://github.com/thedotmack/claude-mem/issues/2485)).

## XML contract (host observer)

When using `--provider host`, the worker parser only accepts three roots.

**Idle / init / no tool results yet:**

```xml theme={null}
<skip_summary reason="noise" />
```

**Finished searchable unit:** one `<observation>` covering the whole pile — real title, 4–10 facts with paths, a short narrative. Never title with a tool name. Do not mix `skip_summary` and `<observation>`. Timeouts must return `skip_summary` XML, not an HTTP 504.

## Live timeline INDEX (Memory mid-attach)

Grok Bot has no SessionStart hook. The worker writes the same compact ID INDEX Claude Code gets at session start into a file the host already re-reads:

```
agents/<uuid>/memory/log/zz-claude-mem-inject.md
```

What writes it: the worker, after it stores observations (debounced) and once at worker start. The file is overwritten in place when the newest rows change. It is not a one-shot dump.

How it grows: newest observation IDs at the top, oldest slide off at `CLAUDE_MEM_GROK_BOT_INJECT_WINDOW` (default 80). Each fact line keeps the observation ID so `get_observations([IDs])` still works.

Thin seat diaries: `/api/context/inject?projects=<cmem_work_seat>` stays project-scoped (Claude Code / Cursor hooks are unchanged). The Grok Bot writer additionally fills remaining slots from the newest observations on this worker (house feed) so a seat with five of its own rows still gets a useful INDEX.

Enable / disable (settings.json or env; env wins):

| Setting | Default | Effect |
| - | - | - |
| `CLAUDE_MEM_GROK_BOT_INJECT_ENABLED` | `true` | Worker live-writes the INDEX. `false` turns it off. No-op when no Grok Bot seats exist. |
| `CLAUDE_MEM_GROK_BOT_INJECT_AGENT_IDS` | `*` | All live seats with `agents/<uuid>/profile.json`, or a UUID list. |
| `CLAUDE_MEM_GROK_BOT_INJECT_FALLBACK` | `house` | `house` fills thin diaries from newest worker observations. `off` = seat project only. |
| `CLAUDE_MEM_GROK_BOT_INJECT_TIER` | `episode` | Host Memory rank prefix. Keep `episode` or plain-tier lines can lose the 4000-char recall budget. |
| `CLAUDE_MEM_GROK_BOT_INJECT_WINDOW` | `80` | Slide-off size (clamped to 100). |
| `CLAUDE_MEM_GROK_BOT_INJECT_PLATFORM_SOURCE` | empty | Unset = do not drop Cursor / other-host rows. Set only for a grok-only feed. |

Do not write `profile.md`. The host owns `YYYY-MM.md`. CCS `TIMELINE.md` buckets are not the source of truth.

Prove it on a Grok Bot box:

```bash theme={null}
# After the worker is healthy and a new observation has landed:
seat=YOUR-SEAT-UUID
root="${GROK_BOT_AGENT_DATA:-$HOME/.grok-bot}"
# If the seat lives under /home/box or Application Support, use that root.
wc -l "$root/agents/$seat/memory/log/zz-claude-mem-inject.md"
grep -n '\[claude-mem\]' "$root/agents/$seat/memory/log/zz-claude-mem-inject.md" | head
# Do more work, wait ~2s, confirm a newer ID appeared at the top.
```

The optional `scripts/grok-bot-session-inject.mjs` daemon is not required. The worker is the live writer.

## Using memory

At the start of a real task, call MCP `session_start_context` for the project with `platformSource` `grok-bot`.

Then the 3-layer search:

1. `search` — compact index with IDs
2. `timeline` — context around a hit
3. `get_observations` — full details **only** for the IDs you will use

Writes from this host stamp `platformSource=grok-bot`. When reading, do not drop Cursor (or other host) memories unless you asked for grok-only. See [Search Tools](/usage/search-tools).

## Verify it worked

1. Worker health: open `http://127.0.0.1:<worker-port>/api/health` (port is in `~/.claude-mem/.worker.port` or settings).
2. Memory viewer: open the worker URL printed at install.
3. Do a small unit of work in Grok Bot, then search. New observations should show `platformSource=grok-bot`.
4. Default observer: first real observation stores via model `cmem-observer`. Host observer: if the queue sits idle, the reply is probably prose instead of `skip_summary`.
5. Live INDEX: after an observation is stored (any project on this worker), `agents/<this-seat-uuid>/memory/log/zz-claude-mem-inject.md` should gain a new newest row (`- (YYYY-MM-DD) [episode] [claude-mem] <id> …`) without anyone hand-writing the file. A thin seat project still fills from the newest house rows. Turn off with `CLAUDE_MEM_GROK_BOT_INJECT_ENABLED=false`.
6. Awareness push pilot (LFG + Orifice): a needle observation (`decision`, `bugfix`, `security_alert`, `sensitive`) should append `- YYYY-MM-DD [awareness] …` to `agents/<agent_id>/memory/log/YYYY-MM.md`. Nothing is written to `profile.md`. Turn off with `CLAUDE_MEM_GROK_BOT_AWARENESS_ENABLED=false`.

## Troubleshooting

### Nothing is being stored

* Confirm the worker is up and you did **not** restart a healthy one.
* CMEM Pro: check `/api/health` (provider openrouter) and `/api/sync/status`. See [CMEM Pro (manual / headless)](/cmem-pro-headless).
* Host observer: confirm the reply is XML (`skip_summary` or `observation`), and the shim is not on the worker port (macOS: worker 37777 → shim 37778).

### `npx claude-mem install --ide grok-bot` is rejected

You are on npm **13.23.x or earlier**. This host lands in **13.24** with [PR #3842](https://github.com/thedotmack/claude-mem/pull/3842).

### I also use Cursor

`--ide` is a single string. Run a second install for Cursor; do not stack `--ide` flags on one command:

```bash theme={null}
npx claude-mem install --ide grok-bot
npx claude-mem install --ide cursor
```

Cursor uses hooks (`npx claude-mem hook cursor …`) and `platformSource=cursor`. Grok Bot still has no hooks. See [Cursor Integration](/cursor).

### This is not Grok Build

The Grok **Build** CLI marketplace (`xai-org/plugin-marketplace`) is a different catalog. This page is Grok Bot only.

## Next steps

* [CMEM Pro (manual / headless)](/cmem-pro-headless) — default observer settings
* [Search Tools](/usage/search-tools) — query project history
* [Configuration](/configuration) — settings and environment variables
* [Cursor Integration](/cursor) — if you also run Cursor


# Hooks architecture
Source: https://docs.claude-mem.ai/hooks-architecture



# How Claude-Mem Uses Hooks: A Lifecycle-Driven Architecture

## Core Principle

**Observe the main Claude Code session from the outside, process observations in the background, inject context at the right time.**

***

## The Big Picture

Claude-Mem is fundamentally a **hook-driven system**. Every piece of functionality happens in response to lifecycle events:

```
┌─────────────────────────────────────────────────────────┐
│              CLAUDE CODE SESSION                         │
│  (Main session - user interacting with Claude)          │
│                                                          │
│  SessionStart → UserPromptSubmit → Tool Use → Stop      │
│     ↓ ↓ ↓            ↓               ↓          ↓        │
│  [3 Hooks]        [Hook]          [Hook]     [Hook]     │
└─────────────────────────────────────────────────────────┘
    ↓ ↓ ↓             ↓               ↓          ↓
┌─────────────────────────────────────────────────────────┐
│                  CLAUDE-MEM SYSTEM                       │
│                                                          │
│  Smart      Worker      Context    New        Obs       │
│  Install    Start       Inject     Session    Capture   │
└─────────────────────────────────────────────────────────┘
```

<Note>
  As of Claude Code 2.1.0 (ultrathink update), SessionStart hooks no longer display user-visible messages. Context is silently injected via `hookSpecificOutput.additionalContext`.
</Note>

**Key insight:** Claude-Mem doesn't interrupt or modify Claude Code's behavior. It observes from the outside and provides value through lifecycle hooks.

***

## Why Hooks?

### The Non-Invasive Requirement

Claude-Mem had several architectural constraints:

1. **Can't modify Claude Code**: It's a closed-source binary
2. **Must be fast**: Can't slow down the main session
3. **Must be reliable**: Can't break Claude Code if it fails
4. **Must be portable**: Works on any project without configuration

**Solution:** External command hooks configured via settings.json

### The Hook System Advantage

Claude Code's hook system provides exactly what we need:

<CardGroup>
  <Card title="Lifecycle Events" icon="clock">
    SessionStart, UserPromptSubmit, PreToolUse (Read), PostToolUse, PostToolUseFailure, Stop, SessionEnd
  </Card>

  <Card title="Non-Blocking" icon="forward">
    Hooks run in parallel, don't wait for completion
  </Card>

  <Card title="Context Injection" icon="upload">
    SessionStart and UserPromptSubmit can add context
  </Card>

  <Card title="Tool Observation" icon="eye">
    PostToolUse sees all tool inputs and outputs
  </Card>
</CardGroup>

***

## The Hook Scripts

Claude-Mem registers hooks for 7 lifecycle events (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, Stop, SessionEnd) plus a Setup hook. `npx claude-mem install` (and `npx claude-mem repair`) set up the runtime; the Setup hook runs `version-check.js`, which completes a plugin-marketplace install whose dependencies are missing and records the install marker. SessionStart runs worker-service start asynchronously on startup, resume, clear, and compact. The synchronous context hook runs on startup, clear, and compact and starts the worker itself when needed. Continue and resume restore the existing conversation without printing or injecting a new timeline, preserving its prompt cache. A third, startup-only SessionStart entry keeps the hook launcher on PATH.

### How Every Hook Is Launched

Each runtime hook is one short **exec-form** command: `command` + `args`, with no `shell` key. Claude Code resolves `claude-mem` on PATH and spawns it directly, with no bash, no shell string and no per-call shell startup. On Windows that also means no Git Bash requirement and no console window from a bash → node chain.

```json theme={null}
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear|compact",
        "hooks": [
          { "type": "command", "command": "claude-mem", "args": ["start"], "timeout": 60, "async": true }
        ]
      },
      {
        "matcher": "startup|clear|compact",
        "hooks": [
          { "type": "command", "command": "claude-mem", "args": ["hook", "claude-code", "context"], "timeout": 60 }
        ]
      },
      {
        "matcher": "startup",
        "hooks": [
          { "type": "command", "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/ensure-launcher.cjs"], "timeout": 180 }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "claude-mem", "args": ["hook", "claude-code", "observation"], "timeout": 120, "async": true }
        ]
      }
    ]
  }
}
```

The other events follow the same shape (`session-init`, `file-context`, `observation` for PostToolUseFailure, `summarize`, `session-end`). See `plugin/hooks/hooks.json` for the full file; it is generated by `scripts/build-hooks.js`, and the build rejects any runtime entry that has a `shell` key or a `command` other than `claude-mem`.

**The `claude-mem` launcher:**

* A small compiled binary (`bun build --compile` of `plugin/scripts/claude-mem-launcher.cjs`), placed by `npx claude-mem install` / `update` at `~/.local/bin/claude-mem` on macOS and Linux, or `%LOCALAPPDATA%\claude-mem\bin\claude-mem.exe` on Windows, and added to PATH (shell rc file on POSIX, user Path on Windows).
* Its only job: find the installed plugin root (`CLAUDE_PLUGIN_ROOT`, then the newest plugin cache version, then the marketplace copy), run `worker-service.cjs` with the same arguments under Bun, pass the hook's stdin through, and exit 0 on any failure with one `claude-mem: <reason>, continuing without memory` line on stderr. It never exits 2, so it never blocks a prompt or a tool.
* It is **version-stable**: it carries no claude-mem logic, so marketplace auto-updates keep working with the binary already on PATH. `claude-mem --version` prints its protocol number.
* It is not the npm package's `claude-mem` CLI. A global npm `claude-mem` earlier on PATH shadows it; `npx claude-mem doctor` reports that.

**Self-heal for marketplace-only installs.** A marketplace install or update runs no installer code, and Claude Code puts a plugin's `bin/` only on the Bash tool's PATH, not on the hook PATH. The startup-only SessionStart entry, `node ${CLAUDE_PLUGIN_ROOT}/scripts/ensure-launcher.cjs`, compiles and places the launcher when it is missing or older than the plugin needs. It is synchronous and always exits 0. When the launcher is current it prints nothing; when the memory hooks cannot work it prints one `{"systemMessage": "..."}` line to stdout, which Claude Code shows to the user (see below). It runs alongside the other SessionStart hooks, so if the launcher was missing, the other hooks in that first session fail with `Executable not found in $PATH: "claude-mem"`, and that session can miss memory context.

**When the launcher is missing.** Claude Code reports a missing hook executable as a non-blocking error on every hook call (`Executable not found in $PATH: "claude-mem"`) and the session carries on without memory. When the launcher cannot be made active, session start shows:

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

See [claude-mem: command not found in hooks](/troubleshooting#claude-mem-command-not-found-in-hooks).

### Setup Hook: Version Check

**Purpose:** Make sure the loaded plugin can start its worker: install the runtime dependencies the plugin marketplace left out, and record the `.install-version` marker.

**Note:** `npx claude-mem install` and `npx claude-mem repair` install Bun, uv and the plugin dependencies up front. The plugin marketplace (including `claude plugin update`) only extracts files.

**When:** Only when Claude Code is started with `claude --init`, `claude --init-only` or `claude -p --maintenance`. Claude Code does **not** fire Setup on plugin install, plugin update or a normal session start, so for marketplace installs it is a manual repair path, not an automatic one.

**What it does:**

1. Checks that every dependency declared in the plugin's `package.json` (plus the `zod` subpaths the worker loads) is present in its `node_modules`, not just that the folder exists.
2. If any are missing, runs `bun install --production` in the plugin root (up to 120s), then checks again. A partial tree is kept, never deleted.
3. If dependencies are still missing, prints `claude-mem: plugin dependencies missing (…) - run: npx claude-mem@latest install`, naming the modules (stderr; Codex receives it as SessionStart context).
4. If the closure is complete and `.install-version` is missing, unreadable or from another version, writes the marker itself (`{version, installedAt, bun}`) instead of sending a working install to the installer.
5. Always exits 0 — never blocks a session.

**Configuration** (simplified; the shipped entry is the one hook that still uses `"shell": "bash"`, which first resolves the plugin root and Node):

```json theme={null}
{
  "hooks": {
    "Setup": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "shell": "bash",
        "command": "node \"$_P/scripts/version-check.js\"",
        "timeout": 300
      }]
    }]
  }
}
```

**Key Features:**

* ✅ Fast when the install is complete: a declared-dependency check, no install
* ✅ Repairs marketplace installs on `--init` / `--maintenance`: installs missing dependencies and writes the marker
* ✅ Names the missing modules when an install cannot be completed
* ✅ Always exit 0 — never blocks a session

**Source:** `plugin/scripts/version-check.js`. `npx claude-mem install` / `npx claude-mem repair` do the same work ahead of time — they install Bun + uv globally, run `bun install` in the plugin cache, and write the `.install-version` marker — behind a visible clack spinner.

***

### Hook 1: SessionStart - Context Injection

**Purpose:** Inject relevant context from previous sessions

**When:** A new Claude Code session starts, or after clear or compact (runs alongside the async worker-start SessionStart entry). Skipped on continue and resume.

**What it does:**

1. Extracts project name from current working directory
2. Queries SQLite for recent session summaries (last 10)
3. Queries SQLite for recent observations (configurable, default 50)
4. Formats as progressive disclosure index
5. Outputs to stdout (automatically injected into context)

**Key decisions:**

* ✅ Runs on startup, clear, and compact
* ✅ 300-second timeout (allows for npm install if needed)
* ✅ Progressive disclosure format (index, not full details)
* ✅ Configurable observation count via `CLAUDE_MEM_CONTEXT_OBSERVATIONS`

**Codex compaction:** A Codex compaction replaces the thread's history, timeline included. The root thread gets the timeline back from `SessionStart` (source `compact`). Codex never sends `SessionStart` to a subagent thread, and `PostCompact` output cannot carry context, so the `PostCompact` hook marks the thread (`~/.claude-mem/state/codex-compaction-pending/`) and the thread's next `PostToolUse` returns the timeline as `additionalContext`, once. A thread whose `SessionStart` already re-injected the timeline does not get it again.

**Output format:**

```markdown theme={null}
# [claude-mem] recent context

**Legend:** 🎯 session-request | 🔴 gotcha | 🟡 problem-solution ...

### Oct 26, 2025

**General**
| ID | Time | T | Title | Tokens |
|----|------|---|-------|--------|
| #2586 | 12:58 AM | 🔵 | Context hook file empty | ~51 |

*Use MCP search tools to access full details*
```

**Source:** `src/cli/handlers/context.ts`, run as `claude-mem hook claude-code context`

***

### Hook 2: UserPromptSubmit (New Session Hook)

**Purpose:** Initialize session tracking when user submits a prompt

**When:** Before Claude processes the user's message

**What it does:**

1. Reads user prompt and session ID from stdin
2. Creates new session record in SQLite
3. Saves raw user prompt for full-text search (v4.2.0+)
4. Starts Bun worker service if not running
5. Returns immediately (non-blocking)

**Configuration:**

```json theme={null}
{
  "hooks": {
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "claude-mem",
        "args": ["hook", "claude-code", "session-init"],
        "timeout": 15
      }]
    }]
  }
}
```

**Key decisions:**

* ✅ No matcher (runs for all prompts)
* ✅ Creates session record immediately
* ✅ Stores raw prompts for search (privacy note: local SQLite only)
* ✅ Auto-starts worker service
* ✅ Suppresses output (`suppressOutput: true`)

**Database operations:**

```sql theme={null}
INSERT INTO sdk_sessions (claude_session_id, project, user_prompt, ...)
VALUES (?, ?, ?, ...)

INSERT INTO user_prompts (session_id, prompt, prompt_number, ...)
VALUES (?, ?, ?, ...)
```

**Source:** `src/cli/handlers/session-init.ts`, run as `claude-mem hook claude-code session-init`

***

### Hook 3: PostToolUse (Save Observation Hook)

**Purpose:** Capture tool execution observations for later processing

**When:** Immediately after any tool completes successfully. A failed call (e.g. Bash exiting non-zero) arrives on `PostToolUseFailure` instead, which runs the same handler and records `{ error, is_interrupt }` as the tool output, so memory also sees attempts that failed.

**What it does:**

1. Receives tool name, input, output from stdin
2. Finds active session for current project
3. Enqueues observation in observation\_queue table
4. Returns immediately (processing happens in worker)

**Configuration:**

```json theme={null}
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "claude-mem",
        "args": ["hook", "claude-code", "observation"],
        "timeout": 120,
        "async": true
      }]
    }]
  }
}
```

**Key decisions:**

* ✅ Matcher: `*` (captures all tools)
* ✅ Non-blocking (just enqueues, doesn't process)
* ✅ Worker processes observations asynchronously
* ✅ Parallel execution safe (each hook gets own stdin)

**Database operations:**

```sql theme={null}
INSERT INTO observation_queue (session_id, tool_name, tool_input, tool_output, ...)
VALUES (?, ?, ?, ?, ...)
```

**What gets queued:**

```json theme={null}
{
  "session_id": "abc123",
  "tool_name": "Edit",
  "tool_input": {
    "file_path": "/path/to/file.ts",
    "old_string": "...",
    "new_string": "..."
  },
  "tool_output": {
    "success": true,
    "linesChanged": 5
  },
  "created_at_epoch": 1698765432
}
```

**Source:** `src/cli/handlers/observation.ts`, run as `claude-mem hook claude-code observation`

***

### Hook 4: Stop Hook (Summary Generation)

**Purpose:** Generate AI-powered session summaries during the session

**When:** When Claude stops (triggered by Stop lifecycle event)

**What it does:**

1. Gathers session observations from database
2. Sends to Claude Agent SDK for summarization
3. Processes response and extracts structured summary
4. Stores in session\_summaries table

**Configuration:**

```json theme={null}
{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "claude-mem",
        "args": ["hook", "claude-code", "summarize"],
        "timeout": 120,
        "async": true
      }]
    }]
  }
}
```

**Key decisions:**

* ✅ Triggered by Stop lifecycle event
* ✅ Multiple summaries per session (v4.2.0+)
* ✅ Summaries are checkpoints, not endings
* ✅ Uses Claude Agent SDK for AI compression

**Summary structure:**

```xml theme={null}
<summary>
  <request>User's original request</request>
  <investigated>What was examined</investigated>
  <learned>Key discoveries</learned>
  <completed>Work finished</completed>
  <next_steps>Remaining tasks</next_steps>
  <files_read>
    <file>path/to/file1.ts</file>
    <file>path/to/file2.ts</file>
  </files_read>
  <files_modified>
    <file>path/to/file3.ts</file>
  </files_modified>
  <notes>Additional context</notes>
</summary>
```

**Source:** `src/cli/handlers/summarize.ts`, run as `claude-mem hook claude-code summarize`

***

### Hook 5: SessionEnd (Cleanup Hook)

**Purpose:** Mark sessions as completed when they end

**When:** Claude Code session ends (not on `/clear`)

**What it does:**

1. Marks session as completed in database
2. Allows worker to finish processing
3. Performs graceful cleanup

**Configuration:**

```json theme={null}
{
  "hooks": {
    "SessionEnd": [{
      "hooks": [{
        "type": "command",
        "command": "claude-mem",
        "args": ["hook", "claude-code", "session-end"],
        "async": true
      }]
    }]
  }
}
```

**Key decisions:**

* ✅ Graceful completion (v4.1.0+)
* ✅ No longer sends DELETE to workers
* ✅ Skips cleanup on `/clear` commands
* ✅ Preserves ongoing sessions

**Why graceful cleanup?**

**Old approach (v3):**

```typescript theme={null}
// ❌ Aggressive cleanup
SessionEnd → DELETE /worker/session → Worker stops immediately
```

**Problems:**

* Interrupted summary generation
* Lost pending observations
* Race conditions

**New approach (v4.1.0+):**

```typescript theme={null}
// ✅ Graceful completion
SessionEnd → UPDATE sessions SET completed_at = NOW()
Worker sees completion → Finishes processing → Exits naturally
```

**Benefits:**

* Worker finishes important operations
* Summaries complete successfully
* Clean state transitions

**Source:** `src/cli/handlers/session-end.ts`, run as `claude-mem hook claude-code session-end`

***

## Hook Execution Flow

### Session Lifecycle

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Claude
    participant Hooks
    participant Worker
    participant DB

    User->>Claude: Start Claude Code
    Claude->>Hooks: SessionStart hook
    Hooks->>DB: Query recent context
    DB-->>Hooks: Session summaries + observations
    Hooks-->>Claude: Inject context
    Note over Claude: Context available for session

    User->>Claude: Submit prompt
    Claude->>Hooks: UserPromptSubmit hook
    Hooks->>DB: Create session record
    Hooks->>Worker: Start worker (if not running)
    Worker-->>DB: Ready to process

    Claude->>Claude: Execute tools
    Claude->>Hooks: PostToolUse (multiple times)
    Hooks->>DB: Queue observations
    Note over Worker: Polls queue, processes observations

    Worker->>Worker: AI compression
    Worker->>DB: Store compressed observations
    Worker->>Hooks: Trigger summary hook
    Hooks->>DB: Store session summary

    User->>Claude: Finish
    Claude->>Hooks: SessionEnd hook
    Hooks->>DB: Mark session complete
    Worker->>DB: Check completion
    Worker->>Worker: Finish processing
    Worker->>Worker: Exit gracefully
```

### Hook Timing

| Event | Timing | Blocking | Timeout | Output Handling |
| - | - | - | - | - |
| **Setup (version-check)** | `claude --init` / `--maintenance` only | No | 300s | Installs missing plugin dependencies; stderr hint only if they are still missing (always exit 0) |
| **SessionStart (worker-start)** | Session start (async) | No | 60s | stderr (log only) |
| **SessionStart (context)** | Before session | No | 60s | JSON → additionalContext (silent) |
| **SessionStart (ensure-launcher)** | Startup only (synchronous) | No | 180s | Nothing on success; one `systemMessage` JSON line (shown to the user) when the hooks are not active; stderr (debug log only) |
| **UserPromptSubmit** | Before processing | No | 15s (10s internal budget; 7s on Windows) | stdout → context |
| **PostToolUse** | After tool | No | 120s | Transcript only |
| **PostToolUseFailure** | After a failed tool | No | 120s | Transcript only |
| **Summary** | Worker triggered | No | 120s | Database |
| **SessionEnd** | On exit | No | 120s | Log only |

<Note>
  As of Claude Code 2.1.0 (ultrathink update), SessionStart hooks no longer display user-visible messages. Context is silently injected via `hookSpecificOutput.additionalContext`.
</Note>

***

## The Worker Service Architecture

### Why a Background Worker?

**Problem:** Hooks must be fast (\< 1 second)

**Reality:** AI compression takes 5-30 seconds per observation

**Solution:** Hooks enqueue observations, worker processes async

```
┌─────────────────────────────────────────────────────────┐
│                   HOOK (Fast)                            │
│  1. Read stdin (< 1ms)                                  │
│  2. Insert into queue (< 10ms)                          │
│  3. Return success (< 20ms total)                       │
└─────────────────────────────────────────────────────────┘
                        ↓ (queue)
┌─────────────────────────────────────────────────────────┐
│                 WORKER (Slow)                            │
│  1. Poll queue every 1s                                 │
│  2. Process observation via Claude SDK (5-30s)          │
│  3. Parse and store results                             │
│  4. Mark observation processed                          │
└─────────────────────────────────────────────────────────┘
```

### Bun Process Management

**Technology:** Bun (JavaScript runtime and process manager)

**Why Bun:**

* Auto-restart on failure
* Fast startup and low memory footprint
* Built-in TypeScript support
* Cross-platform (works on macOS, Linux, Windows)
* No separate process manager needed

**Worker lifecycle:**

```bash theme={null}
# Started by hooks automatically (if not running)
npm run worker:start

# Status check
npm run worker:status

# View logs
npm run worker:logs

# Restart
npm run worker:restart

# Stop
npm run worker:stop
```

### Worker HTTP API

**Technology:** Express.js REST API on the worker's per-user port (default `37700 + (uid % 100)`, override via `CLAUDE_MEM_WORKER_PORT`)

**Endpoints:**

| Endpoint | Method | Purpose |
| - | - | - |
| `/health` | GET | Health check |
| `/sessions` | POST | Create session |
| `/sessions/:id` | GET | Get session status |
| `/sessions/:id` | PATCH | Update session |
| `/observations` | POST | Enqueue observation |
| `/observations/:id` | GET | Get observation |

**Why HTTP API?**

* Language-agnostic (hooks can be any language)
* Easy debugging (curl commands)
* Standard error handling
* Proper async handling

***

## Design Patterns

### Pattern 1: Fire-and-Forget Hooks

**Principle:** Hooks should return immediately, not wait for completion

```typescript theme={null}
// ❌ Bad: Hook waits for processing
export async function saveHook(stdin: HookInput) {
  const observation = parseInput(stdin);
  await processObservation(observation);  // BLOCKS!
  return success();
}

// ✅ Good: Hook enqueues and returns
export async function saveHook(stdin: HookInput) {
  const observation = parseInput(stdin);
  await enqueueObservation(observation);  // Fast
  return success();  // Immediate
}
```

### Pattern 2: Queue-Based Processing

**Principle:** Decouple capture from processing

```
Hook (capture) → Queue (buffer) → Worker (process)
```

**Benefits:**

* Parallel hook execution safe
* Worker failure doesn't affect hooks
* Retry logic centralized
* Backpressure handling

### Pattern 3: Graceful Degradation

**Principle:** Memory system failure shouldn't break Claude Code

```typescript theme={null}
try {
  await captureObservation();
} catch (error) {
  // Log error, but don't throw
  console.error('Memory capture failed:', error);
  return { continue: true, suppressOutput: true };
}
```

**Failure modes:**

* Launcher can't find the plugin or Bun → One stderr line, exit 0, session continues without memory
* `claude-mem` not on PATH → Claude Code shows a non-blocking hook error and continues
* Database locked → Skip observation, log error
* Worker crashed → Auto-restart via Bun
* Network issue → Retry with exponential backoff
* Disk full → Warn user, disable memory

### Pattern 4: Progressive Enhancement

**Principle:** Core functionality works without memory, memory enhances it

```
Without memory: Claude Code works normally
With memory:    Claude Code + context from past sessions
Memory broken:  Falls back to working normally
```

***

## Hook Debugging

### Debug Mode

Enable detailed hook execution logs:

```bash theme={null}
claude --debug
```

**Output:**

```
[DEBUG] Executing hooks for PostToolUse:Write
[DEBUG] Getting matching hook commands for PostToolUse with query: Write
[DEBUG] Found 1 hook matchers in settings
[DEBUG] Matched 1 hooks for query "Write"
[DEBUG] Found 1 hook commands to execute
[DEBUG] Executing hook command: claude-mem hook claude-code observation with timeout 120000ms
[DEBUG] Hook command completed with status 0: {"continue":true,"suppressOutput":true}
```

### Common Issues

<AccordionGroup>
  <Accordion title="Hook not executing">
    **Symptoms:** Hook command never runs

    **Debugging:**

    1. Check `/hooks` menu - is hook registered?
    2. Verify matcher pattern (case-sensitive!)
    3. Check the launcher is on PATH: `command -v claude-mem && claude-mem --version` (prints a protocol number), or run `npx claude-mem doctor`
    4. Look for `Executable not found in $PATH: "claude-mem"` in `claude --debug` output; see [Troubleshooting](/troubleshooting#claude-mem-command-not-found-in-hooks)
  </Accordion>

  <Accordion title="Hook times out">
    **Symptoms:** Hook execution exceeds timeout

    **Debugging:**

    1. Check timeout setting (default 60s)
    2. Identify slow operation (database? network?)
    3. Move slow operation to worker
    4. Increase timeout if necessary
  </Accordion>

  <Accordion title="Context not injecting">
    **Symptoms:** SessionStart hook runs but context missing

    **Debugging:**

    1. Check stdout (must be valid JSON or plain text)
    2. Verify no stderr output (pollutes JSON)
    3. Check exit code (must be 0)
    4. Look for npm install output (v4.3.1 fix)
  </Accordion>

  <Accordion title="Observations not captured">
    **Symptoms:** PostToolUse hook runs but observations missing

    **Debugging:**

    1. Check database: `sqlite3 ~/.claude-mem/claude-mem.db "SELECT * FROM observation_queue"`
    2. Verify session exists: `SELECT * FROM sdk_sessions`
    3. Check worker status: `npm run worker:status`
    4. View worker logs: `npm run worker:logs`
  </Accordion>
</AccordionGroup>

### Testing Hooks Manually

```bash theme={null}
# Test context hook
echo '{
  "session_id": "test123",
  "cwd": "/Users/alex/projects/my-app",
  "hook_event_name": "SessionStart",
  "source": "startup"
}' | claude-mem hook claude-code context

# Test save hook
echo '{
  "session_id": "test123",
  "tool_name": "Edit",
  "tool_input": {"file_path": "test.ts"},
  "tool_output": {"success": true}
}' | claude-mem hook claude-code observation

# Test with actual Claude Code
claude --debug
/hooks  # View registered hooks
# Submit prompt and watch debug output
```

***

## Performance Considerations

### Hook Execution Time

**Target:** \< 100ms per hook

**Actual measurements:**

| Hook | Average | p95 | p99 |
| - | - | - | - |
| Setup (version-check, dependencies complete, marker current) | 8ms | 20ms | 40ms |
| SessionStart (context) | 45ms | 120ms | 250ms |
| SessionStart (user-message) | 5ms | 10ms | 15ms |
| UserPromptSubmit | 12ms | 25ms | 50ms |
| PostToolUse | 8ms | 15ms | 30ms |
| SessionEnd | 5ms | 10ms | 20ms |

**Launcher overhead:** the compiled `claude-mem` launcher starts in about 10ms, and runtime hooks spawn no shell.

**When the Setup hook is fast, and when it is not:**

* With a complete dependency tree it only checks that the declared modules resolve, and rewrites the `.install-version` marker if it is missing or from another version — no install.
* Only an incomplete tree — a plugin-marketplace install or `claude plugin update` whose dependencies were never installed — runs `bun install` (up to 120s, inside the Setup hook's 300s timeout). Setup only fires for `claude --init` / `--maintenance`, so this never lands on a normal session or the per-prompt path.
* `npx claude-mem install` / `npx claude-mem repair` do the heavy lifting (Bun + uv, `bun install` inside the plugin cache) up front with a visible clack spinner, so installs made that way never pay it at session start.

### Database Performance

**Schema optimizations:**

* Indexes on `project`, `created_at_epoch`, `claude_session_id`
* FTS5 virtual tables for full-text search
* WAL mode for concurrent reads/writes

**Query patterns:**

```sql theme={null}
-- Fast: Uses index on (project, created_at_epoch)
SELECT * FROM session_summaries
WHERE project = ?
ORDER BY created_at_epoch DESC
LIMIT 10

-- Fast: Uses index on claude_session_id
SELECT * FROM sdk_sessions
WHERE claude_session_id = ?
LIMIT 1

-- Fast: FTS5 full-text search
SELECT * FROM observations_fts
WHERE observations_fts MATCH ?
ORDER BY rank
LIMIT 20
```

### Worker Throughput

**Bottleneck:** Claude API latency (5-30s per observation)

**Mitigation:**

* Process observations sequentially (simpler, more predictable)
* Skip low-value observations (TodoWrite, ListMcpResourcesTool)
* Batch summaries (generate every N observations, not every observation)

**Future optimization:**

* Parallel processing (multiple workers)
* Smart batching (combine related observations)
* Lazy summarization (summarize only when needed)

***

## Security Considerations

### Hook Command Safety

**Risk:** Hooks execute arbitrary commands with user permissions

**Mitigations:**

1. **Frozen at startup:** Hook configuration captured at start, changes require review
2. **User review required:** `/hooks` menu shows changes, requires approval
3. **Plugin isolation:** `${CLAUDE_PLUGIN_ROOT}` prevents path traversal
4. **Input validation:** Hooks validate stdin schema before processing

### Data Privacy

**What gets stored:**

* User prompts (raw text) - v4.2.0+
* Tool inputs and outputs
* File paths read/modified
* Session summaries

**Privacy guarantees:**

* All data stored locally in `~/.claude-mem/claude-mem.db`
* No cloud uploads (API calls only for AI compression). Local installs contact cmem.ai once, at signup, to create the sign-in link, with a numbers-only usage summary (observation counts and token totals, no prompts, paths, or project names); nothing else is sent to cmem.ai.
* SQLite file permissions: user-only read/write
* Product telemetry is opt-out and never carries prompts, code, or paths — see [Telemetry](/telemetry)

### API Key Protection

**Configuration:**

* Anthropic API key in `~/.anthropic/api_key` or `ANTHROPIC_API_KEY` env var
* Worker inherits environment from Claude Code
* Never logged or stored in database

***

## Key Takeaways

1. **Hooks are interfaces**: They define clean boundaries between systems
2. **Non-blocking is critical**: Hooks must return fast, workers do the heavy lifting
3. **Graceful degradation**: Memory system can fail without breaking Claude Code
4. **Queue-based decoupling**: Capture and processing happen independently
5. **Progressive disclosure**: Context injection uses index-first approach
6. **Lifecycle alignment**: Each hook has a clear, single purpose

***

## Further Reading

* [Claude Code Hooks Reference](https://docs.claude.com/claude-code/hooks) - Official documentation
* [Progressive Disclosure](progressive-disclosure) - Context priming philosophy
* [Architecture Evolution](architecture-evolution) - v3 to v4 journey
* [Worker Service Design](architecture/worker-service) - Background processing details

***

*The hook-driven architecture enables Claude-Mem to be both powerful and invisible. Users never notice the memory system working - it just makes Claude smarter over time.*


# Hosted Server (Beta)
Source: https://docs.claude-mem.ai/hosted-server

Remote authenticated MCP recall, usage metering + quotas, and data deletion — how claude-mem's cloud server works today.

# Hosted Server (Beta)

<Warning>
  **This is early and moving fast.** The hosted server's capture, recall, metering,
  and deletion paths described below are real and tested, but the **UX and developer
  experience around them are still being built** — there's no polished dashboard,
  onboarding flow, or self-serve signup yet. Expect the *plumbing* to be solid and
  the *paving* to be unfinished. Routes, env var names, and the first-key bootstrap
  flow may shift as we wire up the dashboard. Pin a version if you're integrating.
</Warning>

The hosted server is the cloud side of claude-mem: a Postgres-backed HTTP service
(`/v1`) plus a separate BullMQ generation worker. Where the local plugin keeps
memory in `~/.claude-mem/claude-mem.db` on your machine, the hosted server keeps
it per **team** and per **project** in Postgres, and exposes it back to any MCP
client over an authenticated link.

Three capabilities landed together and are documented here:

<CardGroup>
  <Card title="Remote MCP recall" icon="plug">
    Paste an authenticated link into Claude Code to recall your cloud memory —
    read-only, team/project-scoped.
  </Card>

  <Card title="Paid-readiness" icon="gauge">
    Opt-in rate limiting, monthly request/token quotas, and usage metering —
    the guards a paid tier needs.
  </Card>

  <Card title="Data deletion" icon="trash">
    Right-to-erasure: forget a single memory, or purge everything captured for a
    project.
  </Card>
</CardGroup>

## The shape of the system

```
 Claude Code (or any MCP client)
        │  Authorization: Bearer cm_...
        ▼
 ┌─────────────────────────────┐        ┌──────────────────────────┐
 │  HTTP server  (/v1)          │  jobs  │  BullMQ generation worker │
 │  - auth (api-key mode)       ├───────▶│  claude-mem server         │
 │  - rate limit / quota / meter │        │    worker start            │
 │  - REST + /v1/mcp recall      │        │  - provider call           │
 │  - data deletion              │        │  - writes observations     │
 └──────────────┬───────────────┘        └────────────┬─────────────┘
                │                                       │
                ▼                                       ▼
        ┌───────────────────────────────────────────────────┐
        │  Postgres  (teams, projects, observations,         │
        │  agent_events, server_sessions, generation jobs,   │
        │  api_keys, usage_events, audit_log)                │
        └───────────────────────────────────────────────────┘
```

Every row is scoped by `(team_id, project_id)`. An API key carries a **team**
(always) and an optional **project** scope; that scoping bounds every read,
write, and delete.

### Authentication

Set `CLAUDE_MEM_AUTH_MODE=api-key` and send `Authorization: Bearer <key>` on every
request. Scopes gate access:

* **Read** endpoints (search, context, recall, usage) require `memories:read`.
* **Write** endpoints (ingest, key issuance, deletion) require `memories:write`.

Keys are stored as SHA-256 hashes in the `api_keys` table; the raw `cm_...` value
is shown exactly once, at mint time.

## Remote authenticated MCP recall

`/v1/mcp` is a streamable-HTTP [MCP](https://modelcontextprotocol.io) server. It's
the secure link a user pastes into Claude Code to recall their cloud memory. It is
**read-only** and authenticated by the same API key as the REST routes
(`memories:read`); the key's team — and project, if the key is project-scoped —
bounds every read.

```bash theme={null}
claude mcp add --transport http claude-mem <server-base>/v1/mcp \
  --header "Authorization: Bearer cm_..."
```

Three tools are exposed, each mirroring an existing REST path:

| Tool | Arguments | Returns |
| - | - | - |
| `search` | `{ projectId, query, limit? }` | Matching observations (full-text search). |
| `context` | `{ projectId, query, limit? }` | Observations **plus** a concatenated `context` string ready for prompt injection. |
| `recent` | `{ projectId, limit? }` | The newest observations for a project. |

<Note>
  The transport is **stateless** — one MCP server + transport per request — so it
  needs no session affinity behind a load balancer. Mutating tools are
  intentionally absent: a pasted recall link can never write or delete. Every read
  is written to `audit_log` as an `observation.read` event, the same as
  `POST /v1/search`.
</Note>

## Connecting a client: key issuance + connect

Two routes turn "I have a server" into "Claude Code is recalling my cloud memory":

* **`POST /v1/keys`** (requires `memories:write`) mints a **read-only** API key for
  the caller's team and returns a paste-ready connect command. The raw key appears
  **once**. Body: `{ "expiresInDays"?: number }`. Minting requires write scope so a
  read-only key can't escalate itself into more keys.

  ```json theme={null}
  {
    "id": "...",
    "apiKey": "cm_...",
    "scopes": ["memories:read"],
    "expiresAt": null,
    "mcpUrl": "https://<host>/v1/mcp",
    "connectCommand": "claude mcp add --transport http claude-mem https://<host>/v1/mcp --header \"Authorization: Bearer cm_...\""
  }
  ```

* **`GET /v1/connect`** (requires `memories:read`) returns the same command with a
  `<YOUR_API_KEY>` placeholder — a GET never mints. The `mcpUrl` is built from
  `CLAUDE_MEM_PUBLIC_URL` (recommended when behind a proxy or load balancer) or,
  failing that, the request host.

<Warning>
  **First-key bootstrap is the rough edge.** Minting a team's *very first* key still
  needs a session-gated path (a web dashboard), because `POST /v1/keys` itself
  requires a write-scoped key. better-auth's `apiKey()` plugin exists but writes to
  a different store than the Postgres `api_keys` these routes authenticate against —
  wiring the better-auth org → team mapping is the remaining piece, and the biggest
  part of the devex work still ahead.
</Warning>

## Paid-readiness: rate limiting, quotas, metering

These guards run **after** auth and are **opt-in via environment variables**. Unset
(the default) means no rate limit, no quota, and no metering — behavior is
identical to a server without them. Every guard **fails open**: a backing-store
error never blocks a legitimate request.

| Env var | Effect | Response when exceeded |
| - | - | - |
| `CLAUDE_MEM_RATE_LIMIT_PER_MIN` | Max requests per **API key** per minute. | `429` with `Retry-After` and `X-RateLimit-*` headers. |
| `CLAUDE_MEM_MONTHLY_REQUEST_CAP` | Max requests per **team** per calendar month (UTC). | `402 quota_exceeded`. |
| `CLAUDE_MEM_MONTHLY_TOKEN_CAP` | Max provider **tokens** per team per month. Gates **writes only** — reads stay open so a team over budget can still recall. | `402` at the cap. |
| `CLAUDE_MEM_USAGE_METERING=1` | Records one `request` usage event per authenticated call (fire-and-forget). | — |

Token and observation metering is written to the same `usage_events` table from
the generation worker, so usage reflects real provider spend, not just HTTP calls.

`GET /v1/usage` returns the caller team's per-kind totals for the current month:

```json theme={null}
{ "since": "2026-06-01T00:00:00.000Z", "usage": { "request": 1280, "observation": 44 } }
```

<Note>
  "Gates writes only" is deliberate: ingestion is what drives generation, which is
  what costs tokens. A team that blows its token budget can still **read** its
  existing memory — you never lock someone out of their own data over billing.
</Note>

## Data deletion (forget)

Right-to-erasure. Both routes require `memories:write` and are scoped to the
caller's team. Both write an `audit_log` entry.

* **`DELETE /v1/memories/:id`** — delete a single observation; its
  `observation_sources` cascade. Returns `404` if no such observation exists for
  the team. Audited as `observation.deleted`.

* **`DELETE /v1/projects/:projectId/memory`** — purge **all** captured content for
  a project in one transaction: observations, raw agent events, server sessions,
  and generation jobs. The project shell (config/membership) is kept so the team
  can keep using it. Returns per-table `counts`. Returns `404` if the project
  doesn't belong to the team. Audited as `project.memory_purged`.

  ```json theme={null}
  { "purged": true, "projectId": "...", "counts": { "observations": 42, "agentEvents": 17, "sessions": 3, "jobs": 17 } }
  ```

<Note>
  Deletion is team-scoped at the SQL layer, so a key can only ever erase its own
  team's data — a cross-team or nonexistent `projectId` returns `404` rather than a
  misleading success.
</Note>

## Event generation semantics

Ingestion (`POST /v1/events`) accepts two query flags that control observation
generation:

* `generate=false` — write the event but do **not** enqueue a generation job.
* `wait=true` — return the `generationJob` descriptor so callers can poll
  `GET /v1/jobs/:id` for completion.

Without `wait=true`, the response includes the new event row plus a best-effort
`generationJob` field. With `wait=true`, that field is always populated (or `null`
only when generation was explicitly disabled). The actual provider call happens in
the separate BullMQ worker (`claude-mem server worker start`) — the HTTP path
**never blocks** on a provider response.

### Generation concurrency

By default the generation worker processes one job at a time in each of its two
lanes: `event` (per-event observations) and `summary` (session summaries). If
events arrive faster than one job at a time can process them, jobs still complete
but the backlog grows, and observations land hours after the work they describe.
Set `CLAUDE_MEM_SERVER_GENERATION_CONCURRENCY=N` on the generation worker to run up
to N jobs in parallel **per lane**. Both lanes use the value, so one worker process
can have up to 2N provider calls in flight. Size N against your provider's rate
limit. Values above 64 are clamped to 64, and invalid values are ignored with a
warning.

If a worker stops making progress, stale processing locks can be reclaimed for
another attempt. Each attempt may persist observations or report a failure only
while it still owns the Postgres processing lock. A response from a reclaimed
attempt is discarded so it cannot complete or fail the replacement attempt.
This ownership check also applies to session summaries and does not hold a
database lock during the provider call. Recovery may still require another paid
provider call; it does not guarantee exactly-once provider execution.

### Custom generation provider (advanced)

The generation worker ships with `claude`, `gemini` and `openrouter` providers, and
each one reads a single set of credentials from its environment. If your deployment
needs something else, such as a different key per project, set
`CLAUDE_MEM_SERVER_PROVIDER=custom` and point `CLAUDE_MEM_CUSTOM_PROVIDER_MODULE`
at a JavaScript module. The module must export `createProvider(helpers)`, which
returns an object with a `generate(context)` method. `helpers` gives the module this
server's prompt builder, its Anthropic client (`ClaudeObservationProvider`, which
accepts a `baseUrl`), its retryable error class, the resolved `maxOutputTokens`, and
an `apiVersion` (currently `1`) that changes whenever any of those contracts
change.

<Warning>
  The module runs inside the generation worker with everything that process holds:
  the database URL, every provider key and the Redis credentials. Treat it like any
  other code you deploy. The path is read only from the process environment, never
  from `settings.json` or an API route. It must be an absolute path, and the worker
  logs the path and the file's sha256 when it loads the module.
</Warning>

## Endpoint reference

All endpoints are mounted under `/v1`; legacy worker routes remain under `/api`.

```
GET    /healthz
GET    /v1/info
GET    /v1/projects
POST   /v1/projects
GET    /v1/projects/:id
POST   /v1/sessions/start
POST   /v1/sessions/:id/end
GET    /v1/sessions/:id
POST   /v1/events                 # ?generate= ?wait=
POST   /v1/events/batch
GET    /v1/events/:id
POST   /v1/memories
GET    /v1/memories/:id
PATCH  /v1/memories/:id
DELETE /v1/memories/:id           # forget one observation
POST   /v1/search
POST   /v1/context
ALL    /v1/mcp                    # remote authenticated MCP recall
POST   /v1/keys                   # mint a read-only key (write scope)
GET    /v1/connect                # connect command with key placeholder
GET    /v1/usage                  # current-month usage totals
DELETE /v1/projects/:projectId/memory   # purge a whole project
GET    /v1/audit?projectId=<id>
```

## What's solid vs. what's coming

<Note>
  **Solid today:** Postgres-backed multi-tenant storage, api-key auth with
  read/write scopes, the `/v1/mcp` recall link, opt-in rate limiting + quotas +
  metering, and audited data deletion. All covered by the Postgres-gated e2e suite.

  **Still being built (UX / devex):** a web dashboard for the first-key bootstrap and
  key management, self-serve onboarding, a billing/plan UI on top of the metering
  primitives, and a smoother "connect Claude Code to my cloud memory" flow than
  pasting a CLI command. These are the next focus — the primitives above are the
  foundation they'll sit on.
</Note>


# Installation
Source: https://docs.claude-mem.ai/installation

Install Claude-Mem plugin for persistent memory across sessions

# Installation Guide

**[Grok mem](https://grok-mem.ai)** — Grok Mem is how Grok Bots remember. Sits next to Grok's own memory. Does not replace it. The package name is still [`claude-mem`](https://www.npmjs.com/package/claude-mem).

## Quick Start

### Option 1: Grok Bot

Grok Bot has no host hooks. Install it independently of Cursor or Claude Code. Default is CMEM Pro, the hosted memory:

```bash theme={null}
npx claude-mem install --ide grok-bot
```

Local host-login observer is opt-in: `--provider host`. `--ide` is a single string — a second host is a second install command. Installing this plugin does not install Cursor. See [Grok Bot Integration](/grok-bot).

### Option 2: npx

Install and configure Claude-Mem with a single command:

```bash theme={null}
npx claude-mem install
```

The interactive installer runs in three stages — runtime first, sign in second, then pick your memory provider:

1. **Choose agents and install runtime.** Pre-selects detected agents, including OpenCode, OMP, Cursor, and Codex CLI. Offers to install Claude Code only when you select it and it isn't found. If the host download or installation fails, returns to agent selection so you can retry or choose another agent. Then checks Bun and uv, copies plugin files into the marketplace directory, registers the plugin, installs dependencies, and puts the `claude-mem` hook launcher on your PATH (see [How hooks reach claude-mem](#how-hooks-reach-claude-mem)).
2. **Sign in.** Skipped for `--provider claude` (memory runs on your own Anthropic plan). The CLI does **not** ask for an email. It starts an OAuth pairing (`POST https://cmem.ai/api/installer/oauth/start`), prints a device code `XXXX-XXXX`, opens `authorization_url` in your browser, and polls until you are authenticated. No card required.
3. **Choose your memory provider.** **CMEM Pro is pre-selected.** Picking it opens a checkout/trial URL, polls until the account is `ready`, writes `~/.claude-mem/settings.json`, and restarts the worker. Other choices: personal OpenRouter, Gemini, Anthropic plan, or `--provider host` (local loopback observer).

Headless or already signed in? See [CMEM Pro (manual / headless)](/cmem-pro-headless) for the exact settings the installer writes.

### Memory Provider Options

* **CMEM Pro / claude-mem observer (pre-selected)** — memory runs off-plan through `https://cmem.ai/api/inference/v1` with model `cmem-observer`. **30 Day Free Trial**, then subscribe or fall back. Fallback is **event-driven**: `CLAUDE_MEM_PRO_FALLBACK_AT` is set when the gateway stops serving the account (a spent allowance, an inactive subscription, or a refused key), not on the trial end date, and memory then uses your Anthropic plan. See [CMEM Pro (manual / headless)](/cmem-pro-headless).
* **Your OpenRouter key** — memory runs off-plan on your OpenRouter credit. Empty base URL (or `https://openrouter.ai/api/v1`). **Never** send a personal `sk-or-` key to the cmem.ai inference gateway.
* **Gemini API key** — memory runs off-plan on your Gemini key.
* **Anthropic plan** (`--provider claude`) — memory shares your Claude plan usage. Skips the sign-in step; local installs contact cmem.ai once, at signup, to create the sign-in link, with a numbers-only usage summary (observation counts and token totals, no prompts, paths, or project names), and nothing else is sent to cmem.ai. Prompts for the Claude model used to compress observations (Haiku / Sonnet / Opus).
* **Host observer (opt-in)** — `--provider host` uses the already-logged-in agent over a local loopback. No API key. See [Grok Bot Integration](/grok-bot).

### Skipping the Sign-In

Interactive `--provider claude` skips the sign-in step. Non-interactive runs (no TTY, as when an AI agent runs the installer) without `--provider` default to the Anthropic plan on a fresh install and reuse the configured provider otherwise. Every non-interactive install that skipped sign-in prints an optional sign-in link at the very end; it is best-effort, never blocks or changes the exit status, and is skipped when `CI` is set. Local installs contact cmem.ai once, at signup, to create the sign-in link, with a numbers-only usage summary (observation counts and token totals, no prompts, paths, or project names); nothing else is sent to cmem.ai. You can finish a CMEM Pro pairing anytime by re-running `npx claude-mem install`, or by writing settings by hand ([manual / headless](/cmem-pro-headless)).

### Option 3: Plugin Marketplace

Install Claude-Mem directly from the plugin marketplace inside Claude Code:

```bash theme={null}
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
```

Both methods will automatically configure hooks and start the worker service. Start a new Claude Code session and you'll see context from previous sessions automatically loaded.

A marketplace-only install has no installer step, so the plugin places the `claude-mem` launcher itself on the first session start (see below). That first session can run without memory context while the launcher compiles; the next one has it. Running `npx claude-mem install` once avoids the gap.

> **Important:** Claude-Mem is published on npm, but running `npm install -g claude-mem` installs the
> **SDK/library only**. It does **not** register plugin hooks or start the worker service.
> Always install via `npx claude-mem install` or the `/plugin` commands above. A global npm `claude-mem` that sits
> earlier on PATH than the hook launcher shadows it; see [Troubleshooting](/troubleshooting#claude-mem-command-not-found-in-hooks).

### How hooks reach claude-mem

Every Claude Code hook is one short command with no shell: `claude-mem hook claude-code <event>` (the worker-start entry is `claude-mem start`). Claude Code looks `claude-mem` up on PATH and runs it directly, so runtime hooks need no bash on any platform, and Windows needs no Git Bash for them. The one exception is the Setup hook, which still runs through bash but only fires for `claude --init` / `--maintenance`.

This exec form (`"command": "claude-mem", "args": [...]`) needs **Claude Code 2.1.139 or later**. An older Claude Code ignores `args` and runs bare `claude-mem`, which only prints usage, so no memory is captured. `npx claude-mem install` and `npx claude-mem doctor` warn when the detected Claude Code is older; update it with `claude update`.

`claude-mem` here is a small compiled launcher, not the npm CLI. It finds the installed plugin, runs the hook under Bun, and exits 0 on any failure so it never blocks a session.

| | Where the launcher goes | PATH |
| - | - | - |
| macOS / Linux | `~/.local/bin/claude-mem` | Appended to your shell rc file if `~/.local/bin` is not already on PATH |
| Windows | `%LOCALAPPDATA%\claude-mem\bin\claude-mem.exe` | Appended to your user Path |

* `npx claude-mem install` and `npx claude-mem update` compile and place it. They skip the compile when the placed launcher is already current.
* Marketplace-only installs are covered by an extra SessionStart entry, `node ${CLAUDE_PLUGIN_ROOT}/scripts/ensure-launcher.cjs`, which runs at startup and places or refreshes the launcher when it is missing or out of date.
* If the launcher cannot be made active, session start shows:
  ```
  claude-mem: memory hooks are not active: <reason>. Fix: run `npx claude-mem install`, then restart Claude Code.
  ```
* After a PATH change, restart your terminal or IDE so Claude Code inherits the new PATH.
* `npx claude-mem doctor` shows a **Hook launcher** row with where `claude-mem` resolves on PATH and whether it is the launcher. See [claude-mem: command not found in hooks](/troubleshooting#claude-mem-command-not-found-in-hooks).
* `npx claude-mem uninstall` removes the launcher binary. It leaves your shell rc file and user Path alone and prints the line to remove.

## System Requirements

* **Node.js**: 20.0.0 or higher
* **Bun** ≥ 1.0 (auto-installed by `npx claude-mem install` if missing)
* **uv** (auto-installed if missing — provides Python for Chroma's embedding service)
* **Claude Code** 2.1.139 or later (the first release with exec-form hook `args`), or another supported host (Cursor, Grok Bot, Windsurf, OpenCode, Codex CLI, Antigravity CLI, OpenClaw)
* **SQLite 3**: bundled via `bun:sqlite`

## Advanced Installation

For development or testing, you can clone and build from source:

### Clone and Build

```bash theme={null}
# Clone the repository
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem

# Install dependencies
npm install

# Build hooks and worker service
npm run build

# Worker service will auto-start on first Claude Code session
# Or manually start with:
npm run worker:start

# Verify worker is running
npm run worker:status
```

### Post-Installation Verification

#### 1. Automatic Dependency Installation

Dependencies are installed automatically by `npx claude-mem install` and `npx claude-mem repair`. Heavy lifting (Bun + uv install, `bun install` inside the plugin cache, compiling the hook launcher) happens behind a visible installer spinner. Works cross-platform on Windows, macOS, and Linux.

The plugin also ships a Setup hook (`version-check.js`) that runs `bun install` in the plugin root when its declared dependencies are missing and records the `.install-version` marker once they are complete. Claude Code fires Setup only for `claude --init`, `claude --init-only` and `claude -p --maintenance`, never on plugin install, update or a normal session start, so for a marketplace install whose dependencies are missing, run `npx claude-mem install` (or `claude --init-only`). The Setup hook always exits 0.

#### 2. Verify Plugin Installation

Check that hooks are configured in Claude Code and that the launcher is on PATH:

```bash theme={null}
cat plugin/hooks/hooks.json
command -v claude-mem && claude-mem --version   # prints the launcher protocol number, e.g. 1
npx claude-mem doctor                            # "Hook launcher" row
```

#### 3. Data Directory Location

Data is stored in `~/.claude-mem/`:

* Database: `~/.claude-mem/claude-mem.db`
* PID file: `~/.claude-mem/.worker.pid`
* Port file: `~/.claude-mem/.worker.port`
* Logs: `~/.claude-mem/logs/worker-YYYY-MM-DD.log`
* Settings: `~/.claude-mem/settings.json`

Override with environment variable:

```bash theme={null}
export CLAUDE_MEM_DATA_DIR=/custom/path
```

#### 4. Check Worker Logs

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

#### 5. Test Context Retrieval

```bash theme={null}
npm run test:context
```

#### 6. CMEM Pro / sync

```bash theme={null}
curl -s "http://127.0.0.1:${CLAUDE_MEM_WORKER_PORT}/api/health"
curl -s "http://127.0.0.1:${CLAUDE_MEM_WORKER_PORT}/api/sync/status"
```

See [CMEM Pro (manual / headless)](/cmem-pro-headless).

## Upgrading

Upgrades are automatic when updating via the plugin marketplace. The on-PATH launcher is version-stable: it carries no claude-mem logic, so a marketplace update does not need a new one. When an update does need a newer launcher, the startup SessionStart self-heal compiles it, and that first session may miss memory context while it does. `npx claude-mem update` refreshes the plugin, its dependencies and the launcher in one step. If an update leaves dependencies missing, run `npx claude-mem@latest install`.

See [CHANGELOG](https://github.com/thedotmack/claude-mem/blob/main/CHANGELOG.md) for complete version history.

## Next Steps

* [Getting Started Guide](usage/getting-started) - Learn how Claude-Mem works automatically
* [CMEM Pro (manual / headless)](/cmem-pro-headless) - Exact settings.json keys and headless setup
* [Grok Bot Integration](/grok-bot) - Persistent memory for Grok Bot (no hooks)
* [MCP Search Tools](usage/search-tools) - Query your project history
* [Configuration](configuration) - Customize Claude-Mem behavior


# Introduction
Source: https://docs.claude-mem.ai/introduction

Persistent memory compression system for Claude Code

# Claude-Mem

**Persistent memory compression system for Claude Code**

Claude-Mem seamlessly preserves context across sessions by automatically capturing tool usage observations, generating semantic summaries, and making them available to future sessions. This enables Claude to maintain continuity of knowledge about projects even after sessions end or reconnect.

## Quick Start

Install with a single command:

```bash theme={null}
npx claude-mem install
```

Or install from the plugin marketplace inside Claude Code:

```bash theme={null}
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
```

Restart Claude Code. Context from previous sessions will automatically appear in new sessions.

## Key Features

* 🧠 **Persistent Memory** - Context survives across sessions
* 📁 **Folder Context Files** - Auto-generated `CLAUDE.md` in project folders with activity timelines
* 🌐 **Multilingual Modes** - Supports 28 languages (Spanish, Chinese, French, Japanese, etc.)
* 🎭 **Mode System** - Switch between workflows (Code, Email Investigation, Chill)
* 🔍 **MCP Search Tools** - Query your project history with natural language
* 🧠 **Knowledge Agents** - Build queryable "brains" from your observation history
* 🌐 **Web Viewer UI** - Real-time memory stream visualization served by the local worker
* 🔒 **Privacy Control** - Use [`<private>` tags](/usage/private-tags) for manual blocks, or enable [auto-redaction](/usage/auto-redaction) for regex-based secret detection.
* ⚙️ **Context Configuration** - Fine-grained control over what context gets injected
* 🤖 **Automatic Operation** - No manual intervention required
* 📊 **FTS5 Search** - Fast full-text search across observations
* 🔗 **Citations** - Reference past observations with IDs

## How It Works

```
┌─────────────────────────────────────────────────────────────┐
│ Session Start → Inject context from last 10 sessions       │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ User Prompts → Create session, save user prompts           │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ Tool Executions → Capture observations (Read, Write, etc.)  │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ Worker Processes → Extract learnings via Claude Agent SDK   │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ Session Ends → Generate summary, ready for next session     │
└─────────────────────────────────────────────────────────────┘
```

**Core Components:**

1. **5 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Summary (Stop), SessionEnd
2. **Worker Service** - Express HTTP API managed by Bun on a per-user port (default `37700 + (uid % 100)`)
3. **SQLite Database** - Stores sessions, observations, summaries with FTS5 search
4. **Chroma Vector Index** - Optional embedding-based semantic search
5. **MCP / Skill Search Tools** - Query historical context with natural language
6. **Web Viewer UI** - Real-time visualization with SSE and infinite scroll

See [Architecture Overview](architecture/overview) for details.

## System Requirements

* **Node.js**: 20.0.0 or higher
* **Bun** ≥ 1.0 (auto-installed by `npx claude-mem install` if missing)
* **uv** (auto-installed if missing — provides Python for Chroma)
* **Claude Code** (or another supported IDE: Cursor, Windsurf, OpenCode, Codex CLI, Antigravity CLI, OpenClaw)
* **SQLite 3** — bundled via `bun:sqlite`

## Next Steps

<CardGroup>
  <Card title="Installation" icon="download" href="/installation">
    Quick start & advanced installation
  </Card>

  <Card title="Getting Started" icon="rocket" href="/usage/getting-started">
    Learn how Claude-Mem works automatically
  </Card>

  <Card title="Folder Context" icon="folder-open" href="/usage/folder-context">
    Auto-generated folder CLAUDE.md files
  </Card>

  <Card title="Search Tools" icon="magnifying-glass" href="/usage/search-tools">
    Query your project history
  </Card>

  <Card title="Knowledge Agents" icon="brain" href="/usage/knowledge-agents">
    Build queryable corpora from your history
  </Card>
</CardGroup>


# Kimi Code Integration
Source: https://docs.claude-mem.ai/kimi-integration

Persistent memory for Kimi Code CLI — hook-based observation recording, prompt-submit context injection, and MCP search tools

## Overview

The Kimi Code harness gives claude-mem persistent memory to agents running in the Kimi Code CLI. It handles three things:

1. **Observation recording** — Captures tool usage from Kimi's hook system and sends it to the claude-mem worker for AI processing
2. **Context injection** — Injects the observation timeline once per session (and once after each compaction) via the `UserPromptSubmit` hook's stdout (chained after `session-init`), keeping `MEMORY.md` free for agent-curated memory
3. **MCP search tools** — Registers the `mcp-search` stdio server so you can query memory manually from inside a Kimi session

<Info>
  Kimi Code uses a Claude-Code-like hook system driven by `~/.kimi-code/config.toml`. The claude-mem installer merges hook rules into that file and registers an MCP server in `~/.kimi-code/mcp.json` without touching your personal `AGENTS.md` or `~/.agents/` files.
</Info>

## How It Works

```plaintext theme={null}
Kimi Code CLI
  │
  ├── SessionStart (startup|resume) ──→ worker start
  ├── UserPromptSubmit ───────────────→ Init session + context injection (first prompt of session only)
  ├── PostToolUse ────────────────────→ Record observation
  ├── PostToolUseFailure ─────────────→ Record observation (failed call)
  ├── PreToolUse (Read) ──────────────→ File-context observation
  ├── Stop ───────────────────────────→ Summarize session
  └── PreCompact (manual|auto) ───────→ Summarize session
                    │
                    ▼
         Claude-Mem Worker (per-user port)
           ├── POST /api/sessions/init
           ├── POST /api/sessions/observations
           ├── POST /api/sessions/summarize
           ├── POST /api/sessions/complete
           └── GET  /api/context/inject ──→ First-prompt context (once per session)
```

### Event Lifecycle

<Steps>
  <Step title="Session starts (SessionStart startup|resume)">
    When Kimi starts or resumes a session, the hook starts the claude-mem worker if it is not already running. This hook only warms up the worker; its stdout is not appended to Kimi's context.
  </Step>

  <Step title="User prompt submitted (UserPromptSubmit)">
    The single composite `session-init-context` hook sends the user prompt to `POST /api/sessions/init` so the worker can create or continue the session. On the first prompt of a session it also appends the injected observation timeline to Kimi's context via stdout; later prompts in the same session skip the timeline fetch (a marker under `~/.claude-mem/state/kimi-context-injected/` tracks this). This is a blockable Kimi event; claude-mem always exits 0 so the prompt is never blocked.
  </Step>

  <Step title="Tool is about to read a file (PreToolUse Read)">
    Before Kimi executes a `Read` tool, the hook queries `GET /api/observations/by-file` for the target path and injects the returned timeline as additional context. This mirrors the Claude Code `PreToolUse` matcher.
  </Step>

  <Step title="Tool use recorded (PostToolUse)">
    After a successful tool use, the hook sends the tool name, input, and response to `POST /api/sessions/observations`. This is fire-and-forget — it does not block the agent from continuing work.
  </Step>

  <Step title="Session stops (Stop)">
    When the session stops, the hook extracts the last assistant message and sends it to `POST /api/sessions/summarize`.
  </Step>

  <Step title="Context compacted (PreCompact manual|auto)">
    Before Kimi compacts context manually or automatically, the hook triggers another summarize call so the session state is preserved before compression, and clears the injection marker so the first prompt after compaction re-injects a fresh timeline.
  </Step>
</Steps>

### Event Mapping

| Kimi hook event | matcher | claude-mem internal event | Notes |
| - | - | - | - |
| `SessionStart` | `startup\|resume` | worker start | warms up the worker only |
| `UserPromptSubmit` | (all) | `session-init-context` | composite hook; blockable event; we always exit 0; timeline stdout is appended to Kimi context on the first prompt of a session only |
| `PostToolUse` | (all) | `observation` | the payload carries `tool_output` |
| `PostToolUseFailure` | (all) | `observation` | a failed tool call; the payload carries `error` |
| `PreToolUse` | `Read` | `file-context` | mirrors Claude's matcher |
| `Stop` | (all) | `summarize` | |
| `PreCompact` | `manual\|auto` | `summarize` | also clears the injection marker so context re-injects after compaction |

Unused in v1 (the Claude integration likewise ignores them): `SessionEnd`, `SessionHeartbeat`, `SubagentStart/Stop`, `TurnStarted`, `Notification`, `PermissionRequest/Result`, `Interrupt`, `PostCompact`, `UserPromptQueued`.

### Context Injection

The `UserPromptSubmit` hook injects cross-session observation context into the first Kimi prompt of a session by writing the worker's formatted context to stdout. The content comes from `GET /api/context/inject?projects=<project>`, which generates a markdown timeline from the SQLite database. The composite `session-init-context` event performs the `session-init` and `context` work in a single process so the hook payload is consumed only once.

Kimi fires `UserPromptSubmit` on every message and only appends stdout to context for that event (SessionStart stdout is dropped), so the timeline could not be delivered at session start directly. To avoid re-injecting the full timeline into every prompt, the handler records a per-session marker (`~/.claude-mem/state/kimi-context-injected/<sessionId>`) after a successful injection and skips the timeline fetch while the marker exists. The `PreCompact` hook clears the marker, so the first prompt after a compaction re-injects a fresh timeline. If the worker is unreachable the marker is not written, so injection is retried on the next prompt. Opt-in per-prompt semantic injection (`CLAUDE_MEM_SEMANTIC_INJECT=true`) is unaffected and still runs on every prompt.

This approach keeps `MEMORY.md` under your control for curated long-term memory (decisions, preferences, durable facts), while the observation timeline is delivered through the prompt-submit context where it belongs.

## Installation

Run the interactive installer and let it auto-detect Kimi Code:

```bash theme={null}
npx claude-mem install
```

The installer detects Kimi via the `~/.kimi-code/` directory or the `kimi` binary on `PATH`. You can also manage the harness directly:

```bash theme={null}
# Install only the Kimi harness
npx claude-mem kimi install

# Check whether hooks and MCP are registered
npx claude-mem kimi status

# Remove the claude-mem managed block and its MCP entry (preserves other config)
npx claude-mem kimi uninstall
```

### What Gets Installed

The installer writes a marker-delimited managed block into `$KIMI_CODE_HOME/config.toml` (default `~/.kimi-code/config.toml`) containing seven `[[hooks]]` rules:

```toml theme={null}
# >>> claude-mem kimi hooks (managed by claude-mem; do not edit) >>>
[[hooks]]
event = "SessionStart"
matcher = "startup|resume"
command = "..."
timeout = 60
# ... remaining rules ...
# <<< claude-mem kimi hooks <<<
```

Only the four fields `event`, `matcher`, `command`, and `timeout` are written. Timeouts range from 60–120 seconds.

The installer also merges the `mcp-search` stdio MCP server into `$KIMI_CODE_HOME/mcp.json` under `mcpServers` if it is absent, preserving any servers already configured.

<Info>
  `KIMI_CODE_HOME` is honored when set; otherwise the default root is `~/.kimi-code`.
</Info>

<Warning>
  The first time the installer modifies `config.toml`, it writes a backup to `config.toml.bak-<YYYYMMDD>` before making any changes.
</Warning>

## Commands

### `npx claude-mem kimi install`

Install or upgrade the Kimi harness. If the managed block already exists, it is replaced in place (upgrade-safe).

### `npx claude-mem kimi status`

Report whether the managed hook block is present in `config.toml`.

### `npx claude-mem kimi uninstall`

Remove exactly the claude-mem managed block from `config.toml`, and the `mcp-search` entry claude-mem wrote to `mcp.json` (an entry of that name pointing anywhere else is left alone). All other Kimi configuration is untouched. `npx claude-mem uninstall` runs the same cleanup.

## Error Handling

All Kimi hooks fail open: if the worker is unreachable, the command crashes, or any internal error occurs, the hook exits 0 so Kimi never blocks a session. This matches Kimi's own hook semantics, where exit 0 means allow and stdout may append to context.

## Requirements

* Kimi Code CLI installed and configured
* Claude-mem worker service running (auto-started by the `SessionStart` hook if needed)
* Network access between the Kimi process and the worker on the per-user port


# Modes & Languages
Source: https://docs.claude-mem.ai/modes

Configure Claude-Mem behavior and language with the Mode System

# Modes & Languages

Claude-Mem uses a flexible **Mode System** to adapt its behavior, observation types, and output language. This allows you to switch between different workflows (like coding vs. email investigation) or languages without reinstalling the plugin.

## What is a Mode?

A "mode" is a configuration profile that defines:

1. **Observer Role**: How Claude should analyze your work (e.g., "Software Engineer" vs. "Forensic Analyst").
2. **Observation Types**: Valid categories for memory (e.g., "Bug Fix", "Feature" vs. "Person", "Organization").
3. **Concepts**: Semantic tags for indexing (e.g., "Pattern", "Trade-off").
4. **Language**: The language used for generating observations and summaries.

## Configuration

Set the active mode using the `CLAUDE_MEM_MODE` setting in `~/.claude-mem/settings.json`:

```json theme={null}
{
  "CLAUDE_MEM_MODE": "code--es"
}
```

Or via environment variable:

```bash theme={null}
export CLAUDE_MEM_MODE="code--fr"
```

The active mode is shown in the startup context injected into each new session, for example:

```text theme={null}
Mode: Code Development (code)
```

## Creating a Custom Mode

Run `/mode-creator` to design a domain-specific note system through an interactive interview. It helps choose observation types and concept tags, writes and validates the mode, installs it under `~/.claude-mem/modes/`, activates it, optionally configures Telegram alerts, restarts the worker, and verifies the active mode in startup context.

Custom modes in the data directory are durable across plugin upgrades. A same-named user file cannot shadow a bundled mode ID: for example, `~/.claude-mem/modes/code.json` is ignored and logged as an error. To customize bundled `code`, use a `code--<name>` override, which inherits the bundled parent:

```text theme={null}
~/.claude-mem/modes/code--architecture-practice.json
```

Custom IDs that do not collide with bundled modes load from the user modes directory. `CLAUDE_MEM_MODES_DIR` remains an explicit override for development and tests and may supply any ID. All loaded modes must have complete prompts and valid observation types and concepts after inheritance is applied.

Invalid mode content is logged and rejected with its file paths and missing or invalid keys. A missing mode file is logged before falling back to validated bundled `code`; an invalid bundled fallback also throws.

Avoid editing files inside the plugin cache because a plugin update can replace them.

## Telegram alerts and session wrap-ups

Telegram has two separate delivery paths. A session wrap-up sends the latest stored session summary once the Claude Code session ends. Per-observation alerts are real-time notifications for matching observation types or concepts; they are now disabled by default, even when Telegram itself is enabled.

Configure the new settings as strings in `~/.claude-mem/settings.json`:

* `CLAUDE_MEM_TELEGRAM_WRAPUPS_ENABLED` defaults to `"true"`, but no wrap-up can be sent until a route is configured.
* `CLAUDE_MEM_TELEGRAM_OBSERVATION_ALERTS_ENABLED` defaults to `"false"`; set it to `"true"` only when you want the existing `CLAUDE_MEM_TELEGRAM_TRIGGER_TYPES` or `CLAUDE_MEM_TELEGRAM_TRIGGER_CONCEPTS` alerts to resume.
* `CLAUDE_MEM_TELEGRAM_WRAPUP_ROUTES` defaults to `"{}"` and contains a JSON object keyed by project name.

For example, use this route object as the value of `CLAUDE_MEM_TELEGRAM_WRAPUP_ROUTES`:

```json theme={null}
{
  "claude-mem": {
    "chat_id": "-1001234567890",
    "bot_token": "optional override",
    "key": "optional route label"
  }
}
```

A route needs a `chat_id`; its `bot_token` can override `CLAUDE_MEM_TELEGRAM_BOT_TOKEN`, and `key` is an optional route label. `CLAUDE_MEM_TELEGRAM_ENABLED` remains the master switch for both paths. Route lookup first matches the project name exactly, then the parent name before the first `/` for worktrees. If neither route exists, claude-mem logs `No wrap-up route for project` and does not send anything—there is never a fallback to `CLAUDE_MEM_TELEGRAM_CHAT_ID` for a wrap-up.

## Available Modes

### Code Mode (Default)

The standard mode for software development. Captures bug fixes, features, refactors, and architectural decisions.

**ID:** `code`

### Code Mode Variants

Behavioral variants that change how the code mode operates:

| Variant | Mode ID | Description |
| - | - | - |
| **Chill** | `code--chill` | Produces fewer observations. Only records things "painful to rediscover" - shipped features, architectural decisions, and non-obvious gotchas. Skips routine work and obvious changes. |

### Multilingual Code Modes

Inherits all behavior from Code Mode but instructs Claude to generate **all** memory artifacts (titles, narratives, facts, summaries) in the target language.

| Language | Mode ID | Native Name |
| - | - | - |
| **Arabic** | `code--ar` | العربية |
| **Bengali** | `code--bn` | বাংলা |
| **Chinese** | `code--zh` | 中文 |
| **Czech** | `code--cs` | Čeština |
| **Danish** | `code--da` | Dansk |
| **Dutch** | `code--nl` | Nederlands |
| **Finnish** | `code--fi` | Suomi |
| **French** | `code--fr` | Français |
| **German** | `code--de` | Deutsch |
| **Greek** | `code--el` | Ελληνικά |
| **Hebrew** | `code--he` | עברית |
| **Hindi** | `code--hi` | हिन्दी |
| **Hungarian** | `code--hu` | Magyar |
| **Indonesian** | `code--id` | Bahasa Indonesia |
| **Urdu** | `code--ur` | اردو |
| **Italian** | `code--it` | Italiano |
| **Japanese** | `code--ja` | 日本語 |
| **Korean** | `code--ko` | 한국어 |
| **Norwegian** | `code--no` | Norsk |
| **Polish** | `code--pl` | Polski |
| **Portuguese (Brazil)** | `code--pt-br` | Português Brasileiro |
| **Romanian** | `code--ro` | Română |
| **Russian** | `code--ru` | Русский |
| **Spanish** | `code--es` | Español |
| **Swedish** | `code--sv` | Svenska |
| **Thai** | `code--th` | ภาษาไทย |
| **Turkish** | `code--tr` | Türkçe |
| **Ukrainian** | `code--uk` | Українська |
| **Vietnamese** | `code--vi` | Tiếng Việt |

### Email Investigation Mode

A specialized mode for analyzing email dumps (e.g., FOIA releases, corporate archives). Focuses on identifying entities, relationships, timeline events, and key topics.

**ID:** `email-investigation`

**Observation Types:**

* `entity`: Person, organization, or email address
* `relationship`: Connection between entities
* `timeline-event`: Time-stamped event in communication sequence
* `evidence`: Supporting documentation or proof
* `anomaly`: Suspicious pattern or irregularity
* `conclusion`: Investigative finding or determination

## Mode Inheritance

The system supports inheritance using the `--` separator. For example, `code--es` means:

1. Load `code` (Parent) configuration.
2. Load `code--es` (Child) configuration.
3. Merge Child into Parent (Child overrides).

This allows for lightweight "remix" modes that only change specific aspects (like the language prompt) while keeping the core definitions intact.


# OpenClaw Integration
Source: https://docs.claude-mem.ai/openclaw-integration

Persistent memory for OpenClaw agents — observation recording, system prompt context injection, and real-time observation feeds

## Overview

The OpenClaw plugin gives claude-mem persistent memory to agents running on the [OpenClaw](https://openclaw.ai) gateway. It handles three things:

1. **Observation recording** — Captures tool usage from OpenClaw's embedded runner and sends it to the claude-mem worker for AI processing
2. **System prompt context injection** — Injects the observation timeline into each agent's system prompt via the `before_prompt_build` hook, keeping `MEMORY.md` free for agent-curated memory
3. **Observation feed** — Streams new observations to messaging channels (Telegram, Discord, Slack, etc.) in real-time via SSE

<Info>
  OpenClaw's embedded runner (`pi-embedded`) calls the Anthropic API directly without spawning a `claude` process, so claude-mem's standard hooks never fire. This plugin bridges that gap by using OpenClaw's event system to capture the same data.
</Info>

## How It Works

```plaintext theme={null}
OpenClaw Gateway
  │
  ├── before_agent_start ───→ Init session
  ├── before_prompt_build ──→ Inject context into system prompt
  ├── after_tool_call ──────→ Record observation
  ├── agent_end ────────────→ Summarize + Complete session
  └── gateway_start ────────→ Reset session tracking + context cache
                    │
                    ▼
         Claude-Mem Worker (localhost:37777)
           ├── POST /api/sessions/init
           ├── POST /api/sessions/observations
           ├── POST /api/sessions/summarize
           ├── POST /api/sessions/complete
           ├── GET  /api/context/inject ──→ System prompt context
           └── GET  /stream ─────────────→ SSE → Messaging channels
```

### Event Lifecycle

<Steps>
  <Step title="Agent starts (before_agent_start)">
    When an OpenClaw agent starts, the plugin initializes a session by sending the user prompt to `POST /api/sessions/init` so the worker can create a new session and start processing.
  </Step>

  <Step title="Context injected (before_prompt_build)">
    Before each LLM call, the plugin fetches the observation timeline from the worker's `/api/context/inject` endpoint and returns it as `appendSystemContext`. This injects cross-session context directly into the agent's system prompt without writing any files.

    The context is cached for 60 seconds to avoid re-fetching on every LLM turn within a session.
  </Step>

  <Step title="Tool use recorded (after_tool_call)">
    Every time the agent uses a tool (Read, Write, Bash, etc.), the plugin sends the observation to `POST /api/sessions/observations` with the tool name, input, and truncated response (max 1000 chars). For a failed call, the response starts with its error text. This is fire-and-forget — it doesn't block the agent from continuing work.

    Tools prefixed with `memory_` are skipped to avoid recursive recording.
  </Step>

  <Step title="Agent finishes (agent_end)">
    When the agent completes, the plugin extracts the last assistant message and sends it to `POST /api/sessions/summarize`, then calls `POST /api/sessions/complete` to close the session. Both are fire-and-forget.
  </Step>

  <Step title="Gateway restarts (gateway_start)">
    Clears all session tracking (session IDs, context cache) so agents get fresh state after a gateway restart.
  </Step>
</Steps>

### System Prompt Context Injection

The plugin injects cross-session observation context into each agent's system prompt via OpenClaw's `before_prompt_build` hook. The content comes from the worker's `GET /api/context/inject?projects=<project>` endpoint, which generates a formatted markdown timeline from the SQLite database.

This approach keeps `MEMORY.md` under the agent's control for curated long-term memory (decisions, preferences, durable facts), while the observation timeline is delivered through the system prompt where it belongs.

<Info>
  Context is cached for 60 seconds per project to avoid re-fetching on every LLM turn. The cache is cleared on gateway restart. Use `syncMemoryFileExclude` to opt specific agents out of context injection entirely.
</Info>

### Observation Feed (SSE → Messaging)

The plugin runs a background service that connects to the worker's SSE stream (`GET /stream`) and forwards `new_observation` events to a configured messaging channel. This lets you monitor what your agents are learning in real-time from Telegram, Discord, Slack, or any supported OpenClaw channel.

The SSE connection uses exponential backoff (1s → 30s) for automatic reconnection.

## Setting Up the Observation Feed

The observation feed sends a formatted message to your OpenClaw channel every time claude-mem creates a new observation. Each message includes the observation title and subtitle so you can follow along as your agents work.

Messages look like this in your channel:

```
🧠 Claude-Mem Observation
**Implemented retry logic for API client**
Added exponential backoff with configurable max retries to handle transient failures
```

### Step 1: Choose your channel

The observation feed works with any channel that your OpenClaw gateway has configured. You need two pieces of information:

* **Channel type** — The name of the channel plugin registered with OpenClaw (e.g., `telegram`, `discord`, `slack`, `signal`, `whatsapp`, `line`)
* **Target ID** — The chat ID, channel ID, or user ID where messages should be sent

<AccordionGroup>
  <Accordion title="Telegram" icon="telegram">
    **Channel type:** `telegram`

    **Target ID:** Your Telegram chat ID (numeric). To find it:

    1. Message [@userinfobot](https://t.me/userinfobot) on Telegram
    2. It will reply with your chat ID (e.g., `123456789`)
    3. For group chats, the ID is negative (e.g., `-1001234567890`)

    ```json theme={null}
    "observationFeed": {
      "enabled": true,
      "channel": "telegram",
      "to": "123456789"
    }
    ```
  </Accordion>

  <Accordion title="Discord" icon="discord">
    **Channel type:** `discord`

    **Target ID:** The Discord channel ID. To find it:

    1. Enable Developer Mode in Discord (Settings → Advanced → Developer Mode)
    2. Right-click the channel → Copy Channel ID

    ```json theme={null}
    "observationFeed": {
      "enabled": true,
      "channel": "discord",
      "to": "1234567890123456789"
    }
    ```
  </Accordion>

  <Accordion title="Slack" icon="slack">
    **Channel type:** `slack`

    **Target ID:** The Slack channel ID (not the channel name). To find it:

    1. Open the channel in Slack
    2. Click the channel name at the top
    3. Scroll to the bottom of the channel details — the ID looks like `C01ABC2DEFG`

    ```json theme={null}
    "observationFeed": {
      "enabled": true,
      "channel": "slack",
      "to": "C01ABC2DEFG"
    }
    ```
  </Accordion>

  <Accordion title="Signal" icon="signal-messenger">
    **Channel type:** `signal`

    **Target ID:** The Signal phone number or group ID configured in your OpenClaw gateway.

    ```json theme={null}
    "observationFeed": {
      "enabled": true,
      "channel": "signal",
      "to": "+1234567890"
    }
    ```
  </Accordion>

  <Accordion title="WhatsApp" icon="whatsapp">
    **Channel type:** `whatsapp`

    **Target ID:** The WhatsApp phone number or group JID configured in your OpenClaw gateway.

    ```json theme={null}
    "observationFeed": {
      "enabled": true,
      "channel": "whatsapp",
      "to": "+1234567890"
    }
    ```
  </Accordion>

  <Accordion title="LINE" icon="line">
    **Channel type:** `line`

    **Target ID:** The LINE user ID or group ID from the LINE Developer Console.

    ```json theme={null}
    "observationFeed": {
      "enabled": true,
      "channel": "line",
      "to": "U1234567890abcdef"
    }
    ```
  </Accordion>
</AccordionGroup>

### Step 2: Add the config to your gateway

Add the `observationFeed` block to your claude-mem plugin config in your OpenClaw gateway configuration:

```json theme={null}
{
  "plugins": {
    "claude-mem": {
      "enabled": true,
      "config": {
        "project": "my-project",
        "observationFeed": {
          "enabled": true,
          "channel": "telegram",
          "to": "123456789"
        }
      }
    }
  }
}
```

<Warning>
  The `channel` value must match a channel plugin that is already configured and running on your OpenClaw gateway. If the channel isn't registered, you'll see `Unknown channel type: <channel>` in the logs.
</Warning>

### Step 3: Verify the connection

After starting the gateway, check that the feed is connected:

1. **Check the logs** — You should see:
   ```
   [claude-mem] Observation feed starting — channel: telegram, target: 123456789
   [claude-mem] Connecting to SSE stream at http://localhost:37777/stream
   [claude-mem] Connected to SSE stream
   ```

2. **Use the status command** — Run `/claude_mem_feed` in any OpenClaw chat to see:
   ```
   Claude-Mem Observation Feed
   Enabled: yes
   Channel: telegram
   Target: 123456789
   Connection: connected
   ```

3. **Trigger a test** — Have an agent do some work. When the worker processes the tool usage into an observation, you'll receive a message in your configured channel.

<Info>
  The feed only sends `new_observation` events — not raw tool usage. Observations are generated asynchronously by the worker's AI agent, so there's a 1-2 second delay between tool use and the observation message appearing in your channel.
</Info>

### Troubleshooting the Feed

| Symptom | Cause | Fix |
| - | - | - |
| `Connection: disconnected` | Worker not running or wrong port | Check `workerPort` config, run `npm run worker:status` |
| `Connection: reconnecting` | Worker was running but connection dropped | The plugin auto-reconnects with backoff — wait up to 30s |
| `Unknown channel type` in logs | Channel plugin not loaded on gateway | Verify your OpenClaw gateway has the channel plugin configured |
| No messages appearing | Feed connected but no observations being created | Check that agents are running and the worker is processing observations |
| `Observation feed disabled` in logs | `enabled` is `false` or missing | Set `observationFeed.enabled` to `true` |
| `Observation feed misconfigured` in logs | Missing `channel` or `to` | Both `channel` and `to` are required |

## Installation

Run this one-liner to install everything automatically:

```bash theme={null}
curl -fsSL https://install.cmem.ai/openclaw.sh | bash
```

The installer handles dependency checks (Bun, uv), plugin installation, memory slot configuration, AI provider setup, worker startup, and optional observation feed configuration.

You can also pre-select options:

```bash theme={null}
# With a specific AI provider
curl -fsSL https://install.cmem.ai/openclaw.sh | bash -s -- --provider=gemini --api-key=YOUR_KEY

# Fully unattended (defaults to Claude Max Plan)
curl -fsSL https://install.cmem.ai/openclaw.sh | bash -s -- --non-interactive

# Upgrade existing installation
curl -fsSL https://install.cmem.ai/openclaw.sh | bash -s -- --upgrade
```

### Manual Configuration

Add `claude-mem` to your OpenClaw gateway's plugin configuration:

```json theme={null}
{
  "plugins": {
    "claude-mem": {
      "enabled": true,
      "config": {
        "project": "my-project",
        "syncMemoryFile": true,
        "workerPort": 37777,
        "observationFeed": {
          "enabled": true,
          "channel": "telegram",
          "to": "your-chat-id"
        }
      }
    }
  }
}
```

<Note>
  The claude-mem worker service must be running on the same machine as the OpenClaw gateway. The plugin communicates with it via HTTP on `localhost:37777`.
</Note>

## Configuration

<ParamField type="string">
  Project name for scoping observations in the memory database. All observations from this gateway will be stored under this project name.
</ParamField>

<ParamField type="boolean">
  Inject observation context into the agent system prompt via `before_prompt_build` hook. When `true`, agents receive cross-session context automatically. Set to `false` to disable context injection entirely (observations are still recorded).
</ParamField>

<ParamField type="string[]">
  Agent IDs excluded from automatic context injection. Useful for agents that curate their own memory and don't need the observation timeline (e.g., `["snarf", "debugger"]`). Observations are still recorded for excluded agents — only the context injection is skipped.
</ParamField>

<ParamField type="number">
  Port for the claude-mem worker service. Override if your worker runs on a non-default port.
</ParamField>

<ParamField type="boolean">
  Enable live observation streaming to messaging channels.
</ParamField>

<ParamField type="string">
  Channel type: `telegram`, `discord`, `signal`, `slack`, `whatsapp`, `line`
</ParamField>

<ParamField type="string">
  Target chat/user/channel ID to send observations to.
</ParamField>

## Commands

### /claude\_mem\_feed

Show or toggle the observation feed status.

```
/claude_mem_feed        # Show current status
/claude_mem_feed on     # Request enable
/claude_mem_feed off    # Request disable
```

### /claude\_mem\_status

Check worker health and session status.

```
/claude_mem_status
```

Returns worker status, port, active session count, and observation feed connection state.

## Architecture

The plugin uses HTTP calls to the already-running claude-mem worker service rather than spawning subprocesses. This means:

* No `bun` dependency required on the gateway
* No process spawn overhead per event
* Uses the same worker API that Claude Code hooks use
* All operations are non-blocking (fire-and-forget where possible)

### Session Tracking

Each OpenClaw agent session gets a unique `contentSessionId` (format: `openclaw-<sessionKey>-<timestamp>`) that maps to a claude-mem session in the worker. The plugin tracks:

* `sessionIds` — Maps OpenClaw session keys to content session IDs
* `contextCache` — TTL cache (60s) for context injection responses, keyed by project

Both are cleared on `gateway_start`.

## Requirements

* Claude-mem worker service running on `localhost:37777` (or configured port)
* OpenClaw gateway with plugin support
* Network access between gateway and worker (localhost only)


# Platform Integration Guide
Source: https://docs.claude-mem.ai/platform-integration

Complete reference for integrating claude-mem worker service into VSCode extensions, IDE plugins, and CLI tools

<Note>
  **Target Audience:** Developers building claude-mem integrations (VSCode extensions, IDE plugins, CLI tools).
</Note>

## Quick Reference

### Worker Service Basics

```typescript theme={null}
// Resolve the worker port at runtime. The default is per-user (37700 + uid % 100),
// or whatever the user set via CLAUDE_MEM_WORKER_PORT / settings.json. Read it from
// process.env.CLAUDE_MEM_WORKER_PORT, then ~/.claude-mem/settings.json
// (CLAUDE_MEM_WORKER_PORT key), then fall back to the deterministic default.
const WORKER_BASE_URL = `http://127.0.0.1:${workerPort}`;
```

### Most Common Operations

```typescript theme={null}
// Health check
GET /api/health

// Create/get session and queue observation
POST /api/sessions/observations
Body: { claudeSessionId, tool_name, tool_input, tool_response, cwd }

// Queue summary
POST /api/sessions/summarize
Body: { claudeSessionId, last_user_message, last_assistant_message }

// Complete session
POST /api/sessions/complete
Body: { claudeSessionId }

// Search observations
GET /api/search?query=authentication&type=observations&format=index&limit=20

// Get recent context for project
GET /api/context/recent?project=my-project&limit=3
```

### Environment Variables

```bash theme={null}
CLAUDE_MEM_MODEL=claude-haiku-4-5-20251001  # Default Claude model for observations/summaries
CLAUDE_MEM_CONTEXT_OBSERVATIONS=50          # Observations injected at SessionStart
CLAUDE_MEM_WORKER_PORT=                     # Optional override; default = 37700 + (uid % 100)
CLAUDE_MEM_DATA_DIR=                        # Optional override for the data directory
CLAUDE_MEM_PYTHON_VERSION=3.13              # Python version for chroma-mcp
```

### Build Commands (Local Development)

```bash theme={null}
npm run build                 # Compile TypeScript (hooks + worker)
npm run sync-marketplace      # Copy to ~/.claude/plugins
npm run worker:restart        # Restart worker
npm run worker:logs           # View worker logs
npm run worker:status         # Check worker status
```

## Supported Harnesses

The worker API is harness-agnostic. claude-mem ships first-party installers and adapters for the following platforms:

| Harness | Platform identifier | Hook / MCP config location | Installer command |
| - | - | - | - |
| Claude Code | `claude` | Native plugin hooks (`~/.claude/...`) | `/plugin marketplace add thedotmack/claude-mem` |
| Codex CLI | `codex` | `~/.codex/config.toml` | `npx claude-mem install --ide codex-cli` |
| Cursor | `cursor` | `~/.cursor/hooks.json`, `~/.cursor/mcp.json` | `npx claude-mem install --ide cursor` |
| Windsurf | `windsurf` | `~/.codeium/windsurf/hooks.json` | `npx claude-mem install --ide windsurf` |
| OpenCode | `opencode` | `~/.config/opencode/plugins/claude-mem.js`, `~/.config/opencode/opencode.json` | `npx claude-mem install --ide opencode` |
| OpenClaw | `openclaw` | OpenClaw gateway plugin config | `curl -fsSL https://install.cmem.ai/openclaw.sh \| bash` |
| Antigravity CLI | `antigravity-cli` | `~/.gemini/settings.json`, `~/.gemini/.../mcp_config.json` | `npx claude-mem install --ide antigravity` |
| Kimi Code | `kimi` | `~/.kimi-code/config.toml`, `~/.kimi-code/mcp.json` | `npx claude-mem kimi install` |

The OpenCode plugin needs OpenCode 1.3.4 or later, and supports both OpenCode 1 and OpenCode 2 from one file. OpenCode 2 loads it from its `plugins` directory, so the installer adds a `plugin` entry to `opencode.json` only for OpenCode 1.

## Worker Architecture

### Request Flow

```plaintext theme={null}
Platform Hook/Extension
  → HTTP Request to Worker (`${WORKER_BASE_URL}` — per-user, default 37700+uid%100)
    → Route Handler (SessionRoutes/DataRoutes/SearchRoutes/etc.)
      → Domain Service (SessionManager/SearchManager/DatabaseManager)
        → Database (SQLite3 + Chroma vector DB)
          → SSE Broadcast (real-time UI updates)
```

### Domain Services

<CardGroup>
  <Card title="DatabaseManager" icon="database">
    SQLite connection management, initialization
  </Card>

  <Card title="SessionManager" icon="timeline">
    Event-driven session lifecycle, message queues
  </Card>

  <Card title="SearchManager" icon="magnifying-glass">
    Search orchestration (FTS5 + Chroma)
  </Card>

  <Card title="SSEBroadcaster" icon="broadcast-tower">
    Server-Sent Events for real-time updates
  </Card>

  <Card title="SDKAgent" icon="robot">
    Claude Agent SDK for generating observations/summaries
  </Card>

  <Card title="PaginationHelper" icon="list">
    Query pagination utilities
  </Card>

  <Card title="SettingsManager" icon="gear">
    User settings CRUD
  </Card>

  <Card title="FormattingService" icon="code">
    Result formatting (index vs full)
  </Card>

  <Card title="TimelineService" icon="clock">
    Unified timeline generation
  </Card>
</CardGroup>

### Route Organization

<AccordionGroup>
  <Accordion title="ViewerRoutes" icon="eye">
    * Health check endpoint
    * Viewer UI (React app)
    * SSE stream for real-time updates
  </Accordion>

  <Accordion title="SessionRoutes" icon="timeline">
    * Session lifecycle (init, observations, summarize, complete)
    * Privacy checks and tag stripping
    * Auto-start SDK agent generators
  </Accordion>

  <Accordion title="DataRoutes" icon="database">
    * Data retrieval (observations, summaries, prompts, stats)
    * Pagination support
    * Processing status
  </Accordion>

  <Accordion title="SearchRoutes" icon="magnifying-glass">
    * All search operations
    * Unified search API
    * Timeline context
    * Semantic shortcuts
  </Accordion>

  <Accordion title="SettingsRoutes" icon="gear">
    * User settings
    * MCP toggle
    * Dependency health
  </Accordion>
</AccordionGroup>

## API Reference

### Session Lifecycle (SessionRoutes)

#### Create/Get Session + Queue Observation (New API)

<CodeGroup>
  ```http POST /api/sessions/observations theme={null}
  POST /api/sessions/observations
  Content-Type: application/json

  {
    "claudeSessionId": "abc123",      // Claude session identifier (string)
    "tool_name": "Bash",
    "tool_input": { "command": "ls" },
    "tool_response": { "stdout": "..." },
    "cwd": "/path/to/project"
  }
  ```

  ```json Response theme={null}
  { "status": "queued" }
  // or
  { "status": "skipped", "reason": "private" }
  ```
</CodeGroup>

<Info>
  **Privacy Check:** Skips if user prompt was entirely wrapped in `<private>` tags.
  **Tag Stripping:** Removes `<private>` and `<claude-mem-context>` tags before storage.
  **Auto-Start:** Ensures SDK agent generator is running to process the queue.
</Info>

#### Queue Summary (New API)

<CodeGroup>
  ```http POST /api/sessions/summarize theme={null}
  POST /api/sessions/summarize
  Content-Type: application/json

  {
    "claudeSessionId": "abc123",
    "last_user_message": "User's message",
    "last_assistant_message": "Assistant's response"
  }
  ```

  ```json Response theme={null}
  { "status": "queued" }
  // or
  { "status": "skipped", "reason": "private" }
  // or, for a session the worker has no row for
  { "status": "skipped", "reason": "unknown_session" }
  // or, when the session's checkout is an excluded project
  { "status": "skipped", "reason": "project_excluded" }
  ```
</CodeGroup>

The checkout checked against `CLAUDE_MEM_EXCLUDED_PROJECTS` is the optional `cwd`, or else the one the session was recorded in. A host that cannot check exclusions itself should send its checkout as `cwd`.

#### Complete Session (New API)

<CodeGroup>
  ```http POST /api/sessions/complete theme={null}
  POST /api/sessions/complete
  Content-Type: application/json

  {
    "claudeSessionId": "abc123"
  }
  ```

  ```json Response theme={null}
  { "success": true }
  // or
  { "success": true, "message": "No active session found" }
  ```
</CodeGroup>

<Warning>
  **Effect:** Stops SDK agent, marks session complete, broadcasts status change.
</Warning>

#### Legacy Endpoints (Still Supported)

<Tabs>
  <Tab title="Initialize Session">
    ```http theme={null}
    POST /sessions/:sessionDbId/init
    Body: { userPrompt, promptNumber }
    ```
  </Tab>

  <Tab title="Queue Observations">
    ```http theme={null}
    POST /sessions/:sessionDbId/observations
    Body: { tool_name, tool_input, tool_response, prompt_number, cwd }
    ```
  </Tab>

  <Tab title="Queue Summary">
    ```http theme={null}
    POST /sessions/:sessionDbId/summarize
    Body: { last_user_message, last_assistant_message }
    ```
  </Tab>

  <Tab title="Complete Session">
    ```http theme={null}
    POST /sessions/:sessionDbId/complete
    ```
  </Tab>
</Tabs>

<Note>
  New integrations should use `/api/sessions/*` endpoints with `claudeSessionId`.
</Note>

### Data Retrieval (DataRoutes)

#### Get Paginated Data

<Tabs>
  <Tab title="Observations">
    ```http theme={null}
    GET /api/observations?offset=0&limit=20&project=my-project
    ```
  </Tab>

  <Tab title="Summaries">
    ```http theme={null}
    GET /api/summaries?offset=0&limit=20&project=my-project
    ```
  </Tab>

  <Tab title="User Prompts">
    ```http theme={null}
    GET /api/prompts?offset=0&limit=20&project=my-project
    ```
  </Tab>
</Tabs>

```json Response Format theme={null}
{
  "items": [...],
  "hasMore": boolean,
  "offset": number,
  "limit": number
}
```

#### Get by ID

<Tabs>
  <Tab title="Observation">
    ```http theme={null}
    GET /api/observation/:id
    ```
  </Tab>

  <Tab title="Session">
    ```http theme={null}
    GET /api/session/:id
    ```
  </Tab>

  <Tab title="Prompt">
    ```http theme={null}
    GET /api/prompt/:id
    ```
  </Tab>
</Tabs>

#### Get Database Stats

```http theme={null}
GET /api/stats
```

```json Response theme={null}
{
  "worker": {
    "version": "7.0.0",
    "uptime": 12345,
    "activeSessions": 2,
    "sseClients": 1,
    "port": 37742
  },
  "database": {
    "path": "~/.claude-mem/claude-mem.db",
    "size": 1048576,
    "observations": 500,
    "sessions": 50,
    "summaries": 25
  }
}
```

#### Get Projects List

```http theme={null}
GET /api/projects
```

```json Response theme={null}
{
  "projects": ["claude-mem", "other-project", ...]
}
```

#### Get Processing Status

```http theme={null}
GET /api/processing-status
```

```json Response theme={null}
{
  "isProcessing": boolean,
  "queueDepth": number,
  "parkedSessions": number
}
```

`parkedSessions` counts sessions currently parked waiting for a free
concurrency slot (e.g. blocked behind `CLAUDE_MEM_MAX_CONCURRENT_AGENTS`).
It is independent of `queueDepth`, which counts buffered messages —
a session can be parked with or without buffered messages.

### Search Operations (SearchRoutes)

#### Unified Search

```http theme={null}
GET /api/search?query=authentication&type=observations&format=index&limit=20
```

<ParamField type="string">
  Search query text (optional, omit for filter-only)
</ParamField>

<ParamField type="string">
  "observations" | "sessions" | "prompts"
</ParamField>

<ParamField type="string">
  "index" | "full"
</ParamField>

<ParamField type="number">
  Number of results
</ParamField>

<ParamField type="string">
  Filter by project name
</ParamField>

<ParamField type="string">
  Filter by observation type (discovery, decision, bugfix, feature, refactor)
</ParamField>

<ParamField type="string">
  Filter by concepts (comma-separated)
</ParamField>

<ParamField type="string">
  Filter by file paths (comma-separated)
</ParamField>

<ParamField type="string">
  ISO timestamp (filter start)
</ParamField>

<ParamField type="string">
  ISO timestamp (filter end)
</ParamField>

```json Response theme={null}
{
  "observations": [...],
  "sessions": [...],
  "prompts": [...]
}
```

<Info>
  **Format Options:**

  * `index`: Minimal fields for list display (id, title, preview)
  * `full`: Complete entity with all fields
</Info>

#### Unified Timeline

```http theme={null}
GET /api/timeline?anchor=123&depth_before=10&depth_after=10&project=my-project
```

<ParamField type="string">
  Anchor point (observation ID, "S123" for session, or ISO timestamp)
</ParamField>

<ParamField type="number">
  Records before anchor
</ParamField>

<ParamField type="number">
  Records after anchor
</ParamField>

<ParamField type="string">
  Filter by project
</ParamField>

```json Response theme={null}
[
  { "type": "observation", "id": 120, "created_at_epoch": ..., ... },
  { "type": "session", "id": 5, "created_at_epoch": ..., ... },
  { "type": "observation", "id": 123, "created_at_epoch": ..., ... }
]
```

#### Search by File Path

```http theme={null}
GET /api/search/by-file?filePath=src/services/worker-service.ts&format=index&limit=10
```

#### Get Recent Context

```http theme={null}
GET /api/context/recent?project=my-project&limit=3
```

```json Response theme={null}
{
  "summaries": [...],
  "observations": [...]
}
```

#### Context Preview (for Settings UI)

```http theme={null}
GET /api/context/preview?project=my-project
```

<Note>
  Returns plain text with ANSI colors for terminal display
</Note>

#### Context Injection (for Hooks)

```http theme={null}
GET /api/context/inject?project=my-project&colors=true
```

<Note>
  Returns pre-formatted context string ready for display
</Note>

### Settings & Configuration (SettingsRoutes)

#### Get/Update User Settings

<CodeGroup>
  ```http GET theme={null}
  GET /api/settings
  ```

  ```json GET Response theme={null}
  {
    "sidebarOpen": boolean,
    "selectedProject": string | null
  }
  ```

  ```http POST theme={null}
  POST /api/settings
  Body: { "sidebarOpen": true, "selectedProject": "my-project" }
  ```

  ```json POST Response theme={null}
  { "success": true }
  ```
</CodeGroup>

#### MCP Server Status/Toggle

<CodeGroup>
  ```http GET Status theme={null}
  GET /api/mcp/status
  ```

  ```json GET Response theme={null}
  { "enabled": boolean }
  ```

  ```http POST Toggle theme={null}
  POST /api/mcp/toggle
  Body: { "enabled": true }
  ```

  ```json POST Response theme={null}
  { "success": true, "enabled": boolean }
  ```
</CodeGroup>

### Viewer & Real-Time Updates (ViewerRoutes)

#### Health Check

```http theme={null}
GET /api/health
```

```json Response theme={null}
{ "status": "ok" }
```

#### Viewer UI

```http theme={null}
GET /
```

<Note>
  Returns HTML for React app
</Note>

#### SSE Stream

```http theme={null}
GET /stream
```

<Info>
  **Server-Sent Events stream**

  Event Types:

  * `processing_status`:&#x20;
  * `session_started`:&#x20;
  * `observation_queued`:&#x20;
  * `summarize_queued`:&#x20;
  * `observation_created`:&#x20;
  * `summary_created`:&#x20;
  * `new_prompt`:&#x20;
</Info>

## Data Models

### Active Session (In-Memory)

```typescript theme={null}
interface ActiveSession {
  sessionDbId: number;                  // Database ID (numeric)
  claudeSessionId: string;              // Claude session identifier (string)
  sdkSessionId: string | null;          // SDK session ID
  project: string;                      // Project name
  userPrompt: string;                   // Current user prompt text
  pendingMessages: PendingMessage[];    // Queue of pending operations
  abortController: AbortController;     // For cancellation
  generatorPromise: Promise<void> | null; // SDK agent promise
  lastPromptNumber: number;             // Last processed prompt number
  startTime: number;                    // Session start timestamp
  cumulativeInputTokens: number;        // Total input tokens
  cumulativeOutputTokens: number;       // Total output tokens
}

interface PendingMessage {
  type: 'observation' | 'summarize';
  tool_name?: string;
  tool_input?: any;
  tool_response?: any;
  prompt_number?: number;
  cwd?: string;
  last_user_message?: string;
  last_assistant_message?: string;
}
```

### Database Entities

<Tabs>
  <Tab title="Observation">
    ```typescript theme={null}
    interface ObservationRow {
      id: number;
      sdk_session_id: string;
      title: string;
      subtitle?: string;
      summary: string;
      facts: string;           // JSON array of fact strings
      concepts: string;        // JSON array of concept strings
      files_touched: string;   // JSON array of file paths
      obs_type: string;        // discovery, decision, bugfix, feature, refactor
      project: string;
      created_at_epoch: number;
      prompt_number: number;
    }
    ```
  </Tab>

  <Tab title="Session Summary">
    ```typescript theme={null}
    interface SessionSummaryRow {
      id: number;
      sdk_session_id: string;
      summary_text: string;
      facts: string;           // JSON array
      concepts: string;        // JSON array
      files_touched: string;   // JSON array
      project: string;
      created_at_epoch: number;
    }
    ```
  </Tab>

  <Tab title="User Prompt">
    ```typescript theme={null}
    interface UserPromptRow {
      id: number;
      claude_session_id: string;
      sdk_session_id: string;
      project: string;
      prompt_number: number;
      prompt_text: string;
      created_at_epoch: number;
    }
    ```
  </Tab>
</Tabs>

### Search Results

```typescript theme={null}
interface ObservationSearchResult {
  id: number;
  title: string;
  subtitle?: string;
  summary: string;
  facts: string[];         // Parsed from JSON
  concepts: string[];      // Parsed from JSON
  files_touched: string[]; // Parsed from JSON
  obs_type: string;
  project: string;
  created_at_epoch: number;
  prompt_number: number;
  rank?: number;           // FTS5 rank score
}

interface SessionSummarySearchResult {
  id: number;
  summary_text: string;
  facts: string[];
  concepts: string[];
  files_touched: string[];
  project: string;
  created_at_epoch: number;
  rank?: number;
}

interface UserPromptSearchResult {
  id: number;
  claude_session_id: string;
  project: string;
  prompt_number: number;
  prompt_text: string;
  created_at_epoch: number;
  rank?: number;
}
```

### Timeline Item

```typescript theme={null}
interface TimelineItem {
  type: 'observation' | 'session' | 'prompt';
  id: number;
  created_at_epoch: number;
  // Entity-specific fields based on type
}
```

## Integration Patterns

### Mapping Claude Code Hooks to Worker API

<Steps>
  <Step title="SessionStart Hook">
    Not needed for new API - sessions are auto-created on first observation
  </Step>

  <Step title="UserPromptSubmit Hook">
    No API call needed - user\_prompt is captured by first observation in the prompt
  </Step>

  <Step title="PostToolUse Hook">
    ```typescript theme={null}
    async function onPostToolUse(context: HookContext) {
      const { session_id, tool_name, tool_input, tool_result, cwd } = context;

      const response = await fetch(`${WORKER_BASE_URL}/api/sessions/observations`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          claudeSessionId: session_id,
          tool_name,
          tool_input,
          tool_response: tool_result,
          cwd
        })
      });

      const result = await response.json();
      // result.status === 'queued' | 'skipped'
    }
    ```
  </Step>

  <Step title="Summary Hook">
    ```typescript theme={null}
    async function onSummary(context: HookContext) {
      const { session_id, last_user_message, last_assistant_message } = context;

      await fetch(`${WORKER_BASE_URL}/api/sessions/summarize`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          claudeSessionId: session_id,
          last_user_message,
          last_assistant_message
        })
      });
    }
    ```
  </Step>

  <Step title="SessionEnd Hook">
    ```typescript theme={null}
    async function onSessionEnd(context: HookContext) {
      const { session_id } = context;

      await fetch(`${WORKER_BASE_URL}/api/sessions/complete`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          claudeSessionId: session_id
        })
      });
    }
    ```
  </Step>
</Steps>

### VSCode Extension Integration

#### Language Model Tool Registration

```typescript theme={null}
import * as vscode from 'vscode';

interface SearchTool extends vscode.LanguageModelChatTool {
  invoke(
    options: vscode.LanguageModelToolInvocationOptions<{ query: string }>,
    token: vscode.CancellationToken
  ): vscode.ProviderResult<vscode.LanguageModelToolResult>;
}

const searchTool: SearchTool = {
  invoke: async (options, token) => {
    const { query } = options.input;

    try {
      const response = await fetch(
        `${WORKER_BASE_URL}/api/search?query=${encodeURIComponent(query)}&format=index&limit=10`
      );

      if (!response.ok) {
        throw new Error(`Search failed: ${response.statusText}`);
      }

      const results = await response.json();

      // Format results for language model
      return new vscode.LanguageModelToolResult([
        new vscode.LanguageModelTextPart(JSON.stringify(results, null, 2))
      ]);
    } catch (error) {
      return new vscode.LanguageModelToolResult([
        new vscode.LanguageModelTextPart(`Error: ${error.message}`)
      ]);
    }
  }
};

// Register tool
vscode.lm.registerTool('claude-mem-search', searchTool);
```

#### Chat Participant Implementation

```typescript theme={null}
const participant = vscode.chat.createChatParticipant('claude-mem', async (request, context, stream, token) => {
  const claudeSessionId = context.session.id;

  // First message in conversation - no initialization needed
  // Session is auto-created on first observation

  // Process user message
  stream.markdown(`Searching memory for: ${request.prompt}\n\n`);

  const response = await fetch(
    `${WORKER_BASE_URL}/api/search?query=${encodeURIComponent(request.prompt)}&format=index&limit=5`
  );

  const results = await response.json();

  if (results.observations?.length > 0) {
    stream.markdown('**Found observations:**\n');
    for (const obs of results.observations) {
      stream.markdown(`- ${obs.title} (${obs.project})\n`);
    }
  }

  return { metadata: { command: 'search' } };
});
```

## Error Handling & Resilience

### Connection Failures

```typescript theme={null}
async function callWorkerWithFallback<T>(
  endpoint: string,
  options?: RequestInit
): Promise<T | null> {
  try {
    const response = await fetch(`${WORKER_BASE_URL}${endpoint}`, {
      ...options,
      signal: AbortSignal.timeout(5000) // 5s timeout
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    return await response.json();
  } catch (error) {
    console.error(`Worker unavailable (${endpoint}):`, error);
    return null; // Graceful degradation
  }
}
```

### Retry Logic with Exponential Backoff

```typescript theme={null}
async function retryWithBackoff<T>(
  fn: () => Promise<T>,
  maxRetries = 3,
  baseDelay = 100
): Promise<T> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;

      const delay = baseDelay * Math.pow(2, attempt);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
  throw new Error('Max retries exceeded');
}
```

### Worker Health Check

```typescript theme={null}
async function isWorkerHealthy(): Promise<boolean> {
  try {
    const response = await fetch(`${WORKER_BASE_URL}/api/health`, {
      signal: AbortSignal.timeout(2000)
    });
    return response.ok;
  } catch {
    return false;
  }
}
```

### Privacy Tag Handling

<Info>
  The worker automatically strips privacy tags before storage:

  * `<private>content</private>` - User-level privacy control
  * `<claude-mem-context>content</claude-mem-context>` - System-level tag (prevents recursive storage)

  **Privacy Check:** Observations/summaries are skipped if the entire user prompt was wrapped in `<private>` tags.
</Info>

### Custom Error Classes

```typescript theme={null}
class WorkerUnavailableError extends Error {
  constructor() {
    super('Claude-mem worker is not running or unreachable');
    this.name = 'WorkerUnavailableError';
  }
}

class WorkerTimeoutError extends Error {
  constructor(endpoint: string) {
    super(`Worker request timed out: ${endpoint}`);
    this.name = 'WorkerTimeoutError';
  }
}
```

### SSE Stream Error Handling

```typescript theme={null}
function connectToSSE(onEvent: (event: any) => void) {
  const eventSource = new EventSource(`${WORKER_BASE_URL}/stream`);

  eventSource.onmessage = (event) => {
    try {
      const data = JSON.parse(event.data);
      onEvent(data);
    } catch (error) {
      console.error('SSE parse error:', error);
    }
  };

  eventSource.onerror = (error) => {
    console.error('SSE connection error:', error);
    eventSource.close();

    // Reconnect after 5 seconds
    setTimeout(() => connectToSSE(onEvent), 5000);
  };

  return eventSource;
}
```

## Development Workflow

### Project Structure (Recommended)

```plaintext theme={null}
vscode-extension/
├── src/
│   ├── extension.ts              # Extension entry point
│   ├── services/
│   │   ├── WorkerClient.ts       # HTTP client for worker
│   │   └── MemoryManager.ts      # High-level memory operations
│   ├── chat/
│   │   └── participant.ts        # Chat participant implementation
│   └── tools/
│       ├── search.ts             # Search language model tool
│       └── context.ts            # Context injection tool
├── package.json
├── tsconfig.json
└── README.md
```

### Build Configuration (esbuild)

```javascript theme={null}
// build.js
const esbuild = require('esbuild');

esbuild.build({
  entryPoints: ['src/extension.ts'],
  bundle: true,
  outfile: 'dist/extension.js',
  external: ['vscode'],
  format: 'cjs',
  platform: 'node',
  target: 'node18',
  sourcemap: true
}).catch(() => process.exit(1));
```

### package.json (VSCode Extension)

```json theme={null}
{
  "name": "claude-mem-vscode",
  "displayName": "Claude-Mem",
  "version": "1.0.0",
  "engines": {
    "vscode": "^1.95.0"
  },
  "activationEvents": [
    "onStartupFinished"
  ],
  "main": "./dist/extension.js",
  "contributes": {
    "chatParticipants": [
      {
        "id": "claude-mem",
        "name": "memory",
        "description": "Search your persistent memory"
      }
    ],
    "languageModelTools": [
      {
        "name": "claude-mem-search",
        "displayName": "Search Memory",
        "description": "Search persistent memory for observations, sessions, and prompts"
      }
    ]
  },
  "scripts": {
    "build": "node build.js",
    "watch": "node build.js --watch",
    "package": "vsce package"
  },
  "devDependencies": {
    "@types/vscode": "^1.95.0",
    "esbuild": "^0.19.0",
    "typescript": "^5.3.0"
  }
}
```

### Local Testing Loop

<Steps>
  <Step title="Terminal 1: Watch build">
    ```bash theme={null}
    npm run watch
    ```
  </Step>

  <Step title="Terminal 2: Check worker status">
    ```bash theme={null}
    npm run worker:status
    npm run worker:logs
    ```
  </Step>

  <Step title="Terminal 3: Test API manually">
    ```bash theme={null}
    curl http://127.0.0.1:$WORKER_PORT/api/health
    curl "http://127.0.0.1:$WORKER_PORT/api/search?query=test&limit=5"
    ```
  </Step>

  <Step title="VSCode: Launch extension host">
    Press F5 to launch extension host
  </Step>
</Steps>

### Debug Configuration (.vscode/launch.json)

```json theme={null}
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Run Extension",
      "type": "extensionHost",
      "request": "launch",
      "args": [
        "--extensionDevelopmentPath=${workspaceFolder}"
      ],
      "outFiles": [
        "${workspaceFolder}/dist/**/*.js"
      ],
      "preLaunchTask": "npm: build"
    }
  ]
}
```

## Testing Strategy

### Unit Tests (Worker Client)

```typescript theme={null}
import { describe, it, expect } from 'vitest';
import { WorkerClient } from '../src/services/WorkerClient';

describe('WorkerClient', () => {
  it('should check worker health', async () => {
    const client = new WorkerClient();
    const healthy = await client.isHealthy();
    expect(healthy).toBe(true);
  });

  it('should queue observation', async () => {
    const client = new WorkerClient();
    const result = await client.queueObservation({
      claudeSessionId: 'test-123',
      tool_name: 'Bash',
      tool_input: { command: 'ls' },
      tool_response: { stdout: 'file1.txt' },
      cwd: '/tmp'
    });
    expect(result.status).toBe('queued');
  });

  it('should search observations', async () => {
    const client = new WorkerClient();
    const results = await client.search({ query: 'test', limit: 5 });
    expect(results).toHaveProperty('observations');
  });
});
```

### Integration Tests (With Worker Spawning)

```typescript theme={null}
import { spawn } from 'child_process';
import { describe, it, expect, beforeAll, afterAll } from 'vitest';

describe('Worker Integration', () => {
  let workerProcess: ReturnType<typeof spawn>;

  beforeAll(async () => {
    // Start worker process
    workerProcess = spawn('node', ['dist/worker-service.js'], {
      env: { ...process.env, CLAUDE_MEM_WORKER_PORT: '37778' }
    });

    // Wait for worker to be ready
    await new Promise(resolve => setTimeout(resolve, 2000));
  });

  afterAll(() => {
    workerProcess.kill();
  });

  it('should respond to health check', async () => {
    const response = await fetch('http://localhost:37778/api/health');
    expect(response.ok).toBe(true);
  });
});
```

### Manual Testing Checklist

<AccordionGroup>
  <Accordion title="Phase 1: Connection & Health">
    * [ ] Worker starts successfully (`npm run worker:status`)
    * [ ] Health endpoint responds (`curl http://127.0.0.1:$WORKER_PORT/api/health`)
    * [ ] SSE stream connects (`curl http://127.0.0.1:$WORKER_PORT/stream`)
  </Accordion>

  <Accordion title="Phase 2: Session Lifecycle">
    * [ ] Queue observation creates session
    * [ ] Observation appears in database
    * [ ] Privacy tags are stripped
    * [ ] Private prompts are skipped
    * [ ] Queue summary creates summary
    * [ ] Complete session stops processing
  </Accordion>

  <Accordion title="Phase 3: Search & Retrieval">
    * [ ] Search observations by query
    * [ ] Search sessions by query
    * [ ] Search prompts by query
    * [ ] Get recent context for project
    * [ ] Get timeline around observation
    * [ ] Semantic shortcuts (decisions, changes, how-it-works)
  </Accordion>

  <Accordion title="Phase 4: Real-Time Updates">
    * [ ] SSE broadcasts processing status
    * [ ] SSE broadcasts new observations
    * [ ] SSE broadcasts new summaries
    * [ ] SSE broadcasts new prompts
  </Accordion>

  <Accordion title="Phase 5: Error Handling">
    * [ ] Graceful degradation when worker unavailable
    * [ ] Timeout handling for slow requests
    * [ ] Retry logic for transient failures
  </Accordion>
</AccordionGroup>

## Code Examples

### Complete WorkerClient Implementation

<CodeGroup>
  ```typescript WorkerClient.ts theme={null}
  export class WorkerClient {
    private baseUrl: string;

    // Resolve the active worker port via env / settings.json, falling back
    // to the deterministic per-user default. See parseWorkerPort() for an
    // example helper; never hardcode a single value.
    constructor(port: number = resolveWorkerPort()) {
      this.baseUrl = `http://127.0.0.1:${port}`;
    }

    async isHealthy(): Promise<boolean> {
      try {
        const response = await fetch(`${this.baseUrl}/api/health`, {
          signal: AbortSignal.timeout(2000)
        });
        return response.ok;
      } catch {
        return false;
      }
    }

    async queueObservation(data: {
      claudeSessionId: string;
      tool_name: string;
      tool_input: any;
      tool_response: any;
      cwd?: string;
    }): Promise<{ status: string; reason?: string }> {
      const response = await fetch(`${this.baseUrl}/api/sessions/observations`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(data),
        signal: AbortSignal.timeout(5000)
      });

      if (!response.ok) {
        throw new Error(`Failed to queue observation: ${response.statusText}`);
      }

      return await response.json();
    }

    async queueSummarize(data: {
      claudeSessionId: string;
      last_user_message?: string;
      last_assistant_message?: string;
    }): Promise<{ status: string; reason?: string }> {
      const response = await fetch(`${this.baseUrl}/api/sessions/summarize`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(data),
        signal: AbortSignal.timeout(5000)
      });

      if (!response.ok) {
        throw new Error(`Failed to queue summary: ${response.statusText}`);
      }

      return await response.json();
    }

    async completeSession(claudeSessionId: string): Promise<void> {
      const response = await fetch(`${this.baseUrl}/api/sessions/complete`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ claudeSessionId }),
        signal: AbortSignal.timeout(5000)
      });

      if (!response.ok) {
        throw new Error(`Failed to complete session: ${response.statusText}`);
      }
    }

    async search(params: {
      query?: string;
      type?: 'observations' | 'sessions' | 'prompts';
      format?: 'index' | 'full';
      limit?: number;
      project?: string;
    }): Promise<any> {
      const queryString = new URLSearchParams(
        Object.entries(params)
          .filter(([_, v]) => v !== undefined)
          .map(([k, v]) => [k, String(v)])
      ).toString();

      const response = await fetch(
        `${this.baseUrl}/api/search?${queryString}`,
        { signal: AbortSignal.timeout(10000) }
      );

      if (!response.ok) {
        throw new Error(`Search failed: ${response.statusText}`);
      }

      return await response.json();
    }

    connectSSE(onEvent: (event: any) => void): EventSource {
      const eventSource = new EventSource(`${this.baseUrl}/stream`);

      eventSource.onmessage = (event) => {
        try {
          const data = JSON.parse(event.data);
          onEvent(data);
        } catch (error) {
          console.error('SSE parse error:', error);
        }
      };

      eventSource.onerror = (error) => {
        console.error('SSE connection error:', error);
      };

      return eventSource;
    }
  }
  ```
</CodeGroup>

### Search Language Model Tool

```typescript theme={null}
import * as vscode from 'vscode';
import { WorkerClient } from './WorkerClient';

export function registerSearchTool(context: vscode.ExtensionContext) {
  const client = new WorkerClient();

  const searchTool = vscode.lm.registerTool('claude-mem-search', {
    description: 'Search persistent memory for observations, sessions, and prompts',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Search query text'
        },
        type: {
          type: 'string',
          enum: ['observations', 'sessions', 'prompts'],
          description: 'Type of results to return'
        },
        limit: {
          type: 'number',
          description: 'Maximum number of results',
          default: 10
        }
      },
      required: ['query']
    },
    invoke: async (options, token) => {
      const { query, type, limit = 10 } = options.input;

      try {
        const results = await client.search({
          query,
          type,
          format: 'index',
          limit
        });

        // Format results for language model
        let formatted = '';

        if (results.observations?.length > 0) {
          formatted += '## Observations\n\n';
          for (const obs of results.observations) {
            formatted += `- **${obs.title}** (${obs.project})\n`;
            formatted += `  ${obs.summary}\n`;
            if (obs.concepts?.length > 0) {
              formatted += `  Concepts: ${obs.concepts.join(', ')}\n`;
            }
            formatted += '\n';
          }
        }

        return new vscode.LanguageModelToolResult([
          new vscode.LanguageModelTextPart(formatted)
        ]);
      } catch (error) {
        return new vscode.LanguageModelToolResult([
          new vscode.LanguageModelTextPart(`Error: ${error.message}`)
        ]);
      }
    }
  });

  context.subscriptions.push(searchTool);
}
```

## Critical Implementation Notes

<Warning>
  ### sessionDbId vs claudeSessionId

  **IMPORTANT:** Use `claudeSessionId` (string) for new API endpoints, not `sessionDbId` (number).

  * `sessionDbId` - Numeric database ID (legacy endpoints only)
  * `claudeSessionId` - String identifier from Claude platform (new endpoints)
</Warning>

<Warning>
  ### JSON String Fields

  Fields like `facts`, `concepts`, and `files_touched` are stored as JSON strings and require parsing:

  ```typescript theme={null}
  const observation = await client.getObservationById(123);
  const facts = JSON.parse(observation.facts); // string[] array
  const concepts = JSON.parse(observation.concepts); // string[] array
  ```
</Warning>

<Warning>
  ### Timestamps

  All `created_at_epoch` fields are in **milliseconds**, not seconds:

  ```typescript theme={null}
  const date = new Date(observation.created_at_epoch); // ✅ Correct
  const date = new Date(observation.created_at_epoch * 1000); // ❌ Wrong (already in ms)
  ```
</Warning>

<Info>
  ### Asynchronous Processing

  Workers process observations/summaries asynchronously. Results appear in the database 1-2 seconds after queuing. Use SSE events for real-time notifications.
</Info>

<Info>
  ### Privacy Tags

  Always wrap sensitive content in `<private>` tags to prevent storage:

  ```typescript theme={null}
  const userMessage = '<private>API key: sk-1234567890</private>';
  // This observation will be skipped (entire prompt is private)
  ```
</Info>

## Additional Resources

<CardGroup>
  <Card title="Documentation" icon="book" href="https://claude-mem.ai">
    Complete claude-mem documentation
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/thedotmack/claude-mem">
    Source code and issue tracker
  </Card>

  <Card title="Worker Service" icon="server" href="/architecture/worker-service">
    Worker architecture details
  </Card>

  <Card title="Database Schema" icon="database" href="/architecture/database">
    Database structure and queries
  </Card>
</CardGroup>


# Progressive disclosure
Source: https://docs.claude-mem.ai/progressive-disclosure



# Progressive Disclosure: Claude-Mem's Context Priming Philosophy

## Core Principle

**Show what exists and its retrieval cost first. Let the agent decide what to fetch based on relevance and need.**

***

## What is Progressive Disclosure?

Progressive disclosure is an information architecture pattern where you reveal complexity gradually rather than all at once. In the context of AI agents, it means:

1. **Layer 1 (Index)**: Show lightweight metadata (titles, dates, types, token counts)
2. **Layer 2 (Details)**: Fetch full content only when needed
3. **Layer 3 (Deep Dive)**: Read original source files if required

This mirrors how humans work: We scan headlines before reading articles, review table of contents before diving into chapters, and check file names before opening files.

***

## The Problem: Context Pollution

Traditional RAG (Retrieval-Augmented Generation) systems fetch everything upfront:

```
❌ Traditional Approach:
┌─────────────────────────────────────┐
│ Session Start                        │
│                                      │
│ [15,000 tokens of past sessions]    │
│ [8,000 tokens of observations]      │
│ [12,000 tokens of file summaries]   │
│                                      │
│ Total: 35,000 tokens                │
│ Relevant: ~2,000 tokens (6%)        │
└─────────────────────────────────────┘
```

**Problems:**

* Wastes 94% of attention budget on irrelevant context
* User prompt gets buried under mountain of history
* Agent must process everything before understanding task
* No way to know what's actually useful until after reading

***

## Claude-Mem's Solution: Progressive Disclosure

```
✅ Progressive Disclosure Approach:
┌─────────────────────────────────────┐
│ Session Start                        │
│                                      │
│ Index of 50 observations: ~800 tokens│
│ ↓                                    │
│ Agent sees: "🔴 Hook timeout issue"  │
│ Agent decides: "Relevant!"           │
│ ↓                                    │
│ Fetch observation #2543: ~120 tokens│
│                                      │
│ Total: 920 tokens                   │
│ Relevant: 920 tokens (100%)         │
└─────────────────────────────────────┘
```

**Benefits:**

* Agent controls its own context consumption
* Directly relevant to current task
* Can fetch more if needed
* Can skip everything if not relevant
* Clear cost/benefit for each retrieval decision

***

## How It Works in Claude-Mem

### The Index Format

Every SessionStart hook provides a compact index:

```markdown theme={null}
### Oct 26, 2025

**General**
| ID | Time | T | Title | Tokens |
|----|------|---|-------|--------|
| #2586 | 12:58 AM | 🔵 | Context hook file exists but is empty | ~51 |
| #2587 | ″ | 🔵 | Context hook script file is empty | ~46 |
| #2589 | ″ | 🟡 | Investigated hook debug output docs | ~105 |

**src/hooks/context-hook.ts**
| ID | Time | T | Title | Tokens |
|----|------|---|-------|--------|
| #2591 | 1:15 AM | ⚖️ | Stderr messaging abandoned | ~155 |
| #2592 | 1:16 AM | ⚖️ | Web UI strategy redesigned | ~193 |
```

**What the agent sees:**

* **What exists**: Observation titles give semantic meaning
* **When it happened**: Timestamps for temporal context
* **What type**: Icons indicate observation category
* **Retrieval cost**: Token counts for informed decisions
* **Where to get it**: MCP search tools referenced at bottom

### The Legend System

```
🎯 session-request  - User's original goal
🔴 gotcha          - Critical edge case or pitfall
🟡 problem-solution - Bug fix or workaround
🔵 how-it-works    - Technical explanation
🟢 what-changed    - Code/architecture change
🟣 discovery       - Learning or insight
🟠 why-it-exists   - Design rationale
🟤 decision        - Architecture decision
⚖️ trade-off       - Deliberate compromise
```

**Purpose:**

* Visual scanning (humans and AI both benefit)
* Semantic categorization
* Priority signaling (🔴 gotchas are more critical)
* Pattern recognition across sessions

### Progressive Disclosure Instructions

The index includes usage guidance:

```markdown theme={null}
💡 **Progressive Disclosure:** This index shows WHAT exists and retrieval COST.
- Use MCP search tools to fetch full observation details on-demand
- Prefer searching observations over re-reading code for past decisions
- Critical types (🔴 gotcha, 🟤 decision, ⚖️ trade-off) often worth fetching immediately
```

**What this does:**

* Teaches the agent the pattern
* Suggests when to fetch (critical types)
* Recommends search over code re-reading (efficiency)
* Makes the system self-documenting

***

## The Philosophy: Context as Currency

### Mental Model: Token Budget as Money

Think of context window as a bank account:

| Approach | Metaphor | Outcome |
| - | - | - |
| **Dump everything** | Spending your entire paycheck on groceries you might need someday | Waste, clutter, can't afford what you actually need |
| **Fetch nothing** | Refusing to spend any money | Starvation, can't accomplish tasks |
| **Progressive disclosure** | Check your pantry, make a shopping list, buy only what you need | Efficiency, room for unexpected needs |

### The Attention Budget

LLMs have finite attention:

* Every token attends to every other token (n² relationships)
* 100,000 token window ≠ 100,000 tokens of useful attention
* Context "rot" happens as window fills
* Later tokens get less attention than earlier ones

**Claude-Mem's approach:**

* Start with \~1,000 tokens of index
* Agent has 99,000 tokens free for task
* Agent fetches \~200 tokens when needed
* Final budget: \~98,000 tokens for actual work

### Design for Autonomy

> "As models improve, let them act intelligently"

Progressive disclosure treats the agent as an **intelligent information forager**, not a passive recipient of pre-selected context.

**Traditional RAG:**

```
System → [Decides relevance] → Agent
        ↑
   Hope this helps!
```

**Progressive Disclosure:**

```
System → [Shows index] → Agent → [Decides relevance] → [Fetches details]
                          ↑
                   You know best!
```

The agent knows:

* The current task context
* What information would help
* How much budget to spend
* When to stop searching

We don't.

***

## Implementation Principles

### 1. Make Costs Visible

Every item in the index shows token count:

```
| #2591 | 1:15 AM | ⚖️ | Stderr messaging abandoned | ~155 |
                                                        ^^^^
                                                    Retrieval cost
```

**Why:**

* Agent can make informed ROI decisions
* Small observations (\~50 tokens) are "cheap" to fetch
* Large observations (\~500 tokens) require stronger justification
* Matches how humans think about effort

### 2. Use Semantic Compression

Titles compress full observations into \~10 words:

**Bad title:**

```
Observation about a thing
```

**Good title:**

```
🔴 Hook timeout issue: 60s default too short for npm install
```

**What makes a good title:**

* Specific: Identifies exact issue
* Actionable: Clear what to do
* Self-contained: Doesn't require reading observation
* Searchable: Contains key terms (hook, timeout, npm)
* Categorized: Icon indicates type

### 3. Group by Context

Observations are grouped by:

* **Date**: Temporal context
* **File path**: Spatial context (work on specific files)
* **Project**: Logical context

```markdown theme={null}
**src/hooks/context-hook.ts**
| ID | Time | T | Title | Tokens |
|----|------|---|-------|--------|
| #2591 | 1:15 AM | ⚖️ | Stderr messaging abandoned | ~155 |
| #2594 | 1:17 AM | 🟠 | Removed stderr section from docs | ~93 |
```

**Benefit:** If agent is working on `src/hooks/context-hook.ts`, related observations are already grouped together.

### 4. Provide Retrieval Tools

The index is useless without retrieval mechanisms:

```markdown theme={null}
*Use claude-mem MCP search to access records with the given ID*
```

**Available MCP tools:**

* `search` - Search memory index (Layer 1: Get IDs)
* `timeline` - Get chronological context (Layer 2: See narrative arc)
* `get_observations` - Fetch full details (Layer 3: Deep dive)
* `get_tool_uses` - Fetch the original `tool_input` / `tool_response` (Layer 4: Raw evidence)

The layered workflow ensures progressive disclosure: index → context → details → raw evidence.

***

## Real-World Example

### Scenario: Agent asked to fix a bug in hooks

**Without progressive disclosure:**

```
SessionStart injects 25,000 tokens of past context
Agent reads everything
Agent finds 1 relevant observation (buried in middle)
Total tokens consumed: 25,000
Relevant tokens: ~200
Efficiency: 0.8%
```

**With progressive disclosure:**

```
SessionStart shows index: ~800 tokens
Agent sees title: "🔴 Hook timeout issue: 60s too short"
Agent thinks: "This looks relevant to my bug!"
Agent fetches observation #2543: ~155 tokens
Total tokens consumed: 955
Relevant tokens: 955
Efficiency: 100%
```

### The Index Entry

```markdown theme={null}
| #2543 | 2:14 PM | 🔴 | Hook timeout: 60s too short for npm install | ~155 |
```

**What the agent learns WITHOUT fetching:**

* There's a known gotcha (🔴) about hook timeouts
* It's related to npm install taking too long
* Full details are \~155 tokens (cheap)
* Happened at 2:14 PM (recent)

**Decision tree:**

```
Is my task related to hooks? → YES
Is my task related to timeouts? → YES
Is my task related to npm? → YES
155 tokens is cheap → FETCH IT
```

***

## The Layered Workflow

Claude-Mem implements progressive disclosure through a layered workflow pattern.
Layers 1-3 are the everyday path; layer 4 exists for the rare case where a
summary is not evidence enough.

### Layer 1: Search (Index)

Start by searching to get a compact index with IDs:

```typescript theme={null}
search({
  query: "hook timeout",
  limit: 10
})
```

**Returns:**

```
Found 3 observations matching "hook timeout":

| ID | Date | Type | Title |
|----|------|------|-------|
| #2543 | Oct 26 | gotcha | Hook timeout: 60s too short |
| #2891 | Oct 25 | how-it-works | Hook timeout configuration |
| #2102 | Oct 20 | problem-solution | Fixed timeout in CI |
```

**Cost:** \~50-100 tokens per result
**Value:** Agent can scan and decide which observations are relevant

### Layer 2: Timeline (Context)

Get chronological context around interesting observations:

```typescript theme={null}
timeline({
  anchor: 2543,  // Observation ID from search
  depth_before: 3,
  depth_after: 3
})
```

**Returns:** Chronological view showing what happened before/during/after observation #2543

**Cost:** Variable based on depth
**Value:** Understand narrative arc and context

### Layer 3: Get Observations (Details)

Fetch full details only for relevant observations:

```typescript theme={null}
get_observations({
  ids: [2543, 2102]  // Selected from search results
})
```

**Returns:**

```
#2543 🔴 Hook timeout: 60s too short for npm install
─────────────────────────────────────────────────
Date: Oct 26, 2025 2:14 PM
Type: gotcha
Project: claude-mem

Narrative:
Discovered that the default 60-second hook timeout is insufficient
for npm install operations, especially with large dependency trees
or slow network conditions. This causes SessionStart hook to fail
silently, preventing context injection.

Facts:
- Default timeout: 60 seconds
- npm install with cold cache: ~90 seconds
- Configured timeout: 120 seconds in plugin/hooks/hooks.json:25

Files Modified:
- plugin/hooks/hooks.json

Concepts: hooks, timeout, npm, configuration
```

**Cost:** \~155 tokens for full details
**Value:** Complete understanding of the issue

### Layer 4: Get Tool Uses (Raw Evidence)

Observations are compressed *summaries* of what tools did. Sometimes the
compression is exactly what you do not want — you need the literal bytes: the
exact diff that was applied, the exact stderr a build printed, the exact JSON an
API returned.

Claude-mem keeps those raw bodies in the `tool_uses` table, and this layer is
the only way to read them back:

```typescript theme={null}
get_tool_uses({
  ids: ["toolu_01ABC..."],   // or numeric tool_uses ids
  project: "claude-mem"
})
```

**Returns:** The stored `tool_input` / `tool_response` for those calls, along
with the tool name, the session ids, and the observation the call was folded
into.

**Cost:** Up to 64 KB per row — by far the most expensive layer
**Value:** The unsummarized truth, when and only when the summary was not enough

<Warning>
  Never start here, and never call `get_tool_uses` without ids you got from
  layers 1-3. Raw tool bodies are exactly the context pollution the rest of this
  page exists to avoid; disclosing a handful on purpose is progressive
  disclosure, disclosing them by default is just a bigger transcript.
</Warning>

Payloads larger than 64 KB are truncated on write and carry a
`…[truncated: N bytes]` marker, so a clipped body is distinguishable from one
that legitimately ends where it does.

***

## Cognitive Load Theory

Progressive disclosure is grounded in **Cognitive Load Theory**:

### Intrinsic Load

The inherent difficulty of the task itself.

**Example:** "Fix authentication bug"

* Must understand auth system
* Must understand the bug
* Must write the fix

This load is unavoidable.

### Extraneous Load

The cognitive burden of poorly presented information.

**Traditional RAG adds extraneous load:**

* Scanning irrelevant observations
* Filtering out noise
* Remembering what to ignore
* Re-contextualizing after each section

**Progressive disclosure minimizes extraneous load:**

* Scan titles (low effort)
* Fetch only relevant (targeted effort)
* Full attention on current task

### Germane Load

The effort of building mental models and schemas.

**Progressive disclosure supports germane load:**

* Consistent structure (legend, grouping)
* Clear categorization (types, icons)
* Semantic compression (good titles)
* Explicit costs (token counts)

***

## Anti-Patterns to Avoid

### ❌ Verbose Titles

**Bad:**

```
| #2543 | 2:14 PM | 🔴 | Investigation into the issue where hooks time out | ~155 |
```

**Good:**

```
| #2543 | 2:14 PM | 🔴 | Hook timeout: 60s too short for npm install | ~155 |
```

### ❌ Hiding Costs

**Bad:**

```
| #2543 | 2:14 PM | 🔴 | Hook timeout issue |
```

**Good:**

```
| #2543 | 2:14 PM | 🔴 | Hook timeout issue | ~155 |
```

### ❌ No Retrieval Path

**Bad:**

```
Here are 10 observations. [No instructions on how to get full details]
```

**Good:**

```
Here are 10 observations.
*Use MCP search tools to fetch full observation details on-demand*
```

### ❌ Skipping the Index Layer

**Bad:**

```typescript theme={null}
// Fetching full details immediately
get_observations({
  ids: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]  // Guessing which are relevant
})
```

**Good:**

```typescript theme={null}
// Follow the 3-layer workflow
// Layer 1: Search for index
search({
  query: "hooks",
  limit: 20
})

// Layer 2: Review index, identify 2-3 relevant IDs

// Layer 3: Fetch only relevant observations
get_observations({
  ids: [2543, 2891]  // Just the most relevant
})
```

***

## Key Design Decisions

### Why Token Counts?

**Decision:** Show approximate token counts (\~155, \~203) rather than exact counts.

**Rationale:**

* Communicates scale (50 vs 500) without false precision
* Maps to human intuition (small/medium/large)
* Allows agent to budget attention
* Encourages cost-conscious retrieval

### Why Icons Instead of Text Labels?

**Decision:** Use emoji icons (🔴, 🟡, 🔵) rather than text (GOTCHA, PROBLEM, HOWTO).

**Rationale:**

* Visual scanning (pattern recognition)
* Token efficient (1 char vs 10 chars)
* Language-agnostic
* Aesthetically distinct
* Works for both humans and AI

### Why Index-First, Not Smart Pre-Fetch?

**Decision:** Always show index first, even if we "know" what's relevant.

**Rationale:**

* We can't know what's relevant better than the agent
* Pre-fetching assumes we understand the task
* Agent knows current context, we don't
* Respects agent autonomy
* Fails gracefully (can always fetch more)

### Why Group by File Path?

**Decision:** Group observations by file path in addition to date.

**Rationale:**

* Spatial locality: Work on file X likely needs context about file X
* Reduces scanning effort
* Matches how developers think
* Clear semantic boundaries

***

## Measuring Success

Progressive disclosure is working when:

### ✅ Low Waste Ratio

```
Relevant Tokens / Total Context Tokens > 80%
```

Most of the context consumed is actually useful.

### ✅ Selective Fetching

```
Index Shown: 50 observations
Details Fetched: 2-3 observations
```

Agent is being selective, not fetching everything.

### ✅ Fast Task Completion

```
Session with index: 30 seconds to find relevant context
Session without: 90 seconds scanning all context
```

Time-to-relevant-information is faster.

### ✅ Appropriate Depth

```
Simple task: Only index needed
Medium task: 1-2 observations fetched
Complex task: 5-10 observations + code reads
```

Depth scales with task complexity.

***

## Future Enhancements

### Adaptive Index Size

```typescript theme={null}
// Vary index size based on session type
SessionStart({ source: "startup" }):
  → Show last 10 sessions (small index)

SessionStart({ source: "resume" }):
  → Show only current session (micro index)

SessionStart({ source: "compact" }):
  → Show last 20 sessions (larger index)
```

### Relevance Scoring

```typescript theme={null}
// Use embeddings to pre-sort index by relevance
search({
  query: "authentication bug",
  orderBy: "relevance"  // Based on semantic similarity (future enhancement)
})
```

### Cost Forecasting

```markdown theme={null}
💡 **Budget Estimate:**
- Fetching all 🔴 gotchas: ~450 tokens
- Fetching all file-related: ~1,200 tokens
- Fetching everything: ~8,500 tokens
```

### Progressive Detail Levels

```
Layer 1: Index (titles only)
Layer 2: Summaries (2-3 sentences)
Layer 3: Full details (complete observation)
Layer 4: Source files (referenced code)
```

***

## Key Takeaways

1. **Show, don't tell**: Index reveals what exists without forcing consumption
2. **Cost-conscious**: Make retrieval costs visible for informed decisions
3. **Agent autonomy**: Let the agent decide what's relevant
4. **Semantic compression**: Good titles make or break the system
5. **Consistent structure**: Patterns reduce cognitive load
6. **Two-tier everything**: Index first, details on-demand
7. **Context as currency**: Spend wisely on high-value information

***

## Remember

> "The best interface is one that disappears when not needed, and appears exactly when it is."

Progressive disclosure respects the agent's intelligence and autonomy. We provide the map; the agent chooses the path.

***

## Further Reading

* [Context Engineering for AI Agents](context-engineering) - Foundational principles
* [Claude-Mem Architecture](architecture/overview) - How it all fits together
* Cognitive Load Theory (Sweller, 1988)
* Information Foraging Theory (Pirolli & Card, 1999)
* Progressive Disclosure (Nielsen Norman Group)

***

*This philosophy emerged from real-world usage of Claude-Mem across hundreds of coding sessions. The pattern works because it aligns with both human cognition and LLM attention mechanics.*


# Qoder Integration
Source: https://docs.claude-mem.ai/qoder-integration

Install claude-mem as a native Qoder plugin for the CLI or the IDE

claude-mem ships a native Qoder plugin. It loads the same memory skills and MCP search server as the Claude Code plugin, and records sessions through Qoder's lifecycle hooks.

## Install in Qoder CLI

```bash theme={null}
qoder plugins marketplace add thedotmack/claude-mem
qoder plugins install claude-mem@thedotmack
```

To check a local checkout, run `qoder plugins validate .`.

## Install in Qoder IDE

From a built checkout, create an archive:

```bash theme={null}
git archive --format=zip --output=claude-mem-qoder.zip HEAD
```

Then import it from **Extensions → Plugins → Add Plugins → Upload Plugin**.

## How it works

* Qoder exposes the same hook payload and output contract as Codex, so the Qoder hooks run through claude-mem's existing Codex structured-hook adapter. Qoder sessions are stored and shown under the Codex source.
* Qoder has no Setup event. On the first Qoder session, the SessionStart launcher runs the plugin's dependency check before memory starts. If dependencies are still missing afterwards, every hook returns a harmless no-op instead of starting the worker.
* Bun must already be installed, as described in the system requirements.

## Context from other tools

By default, SessionStart context only includes the current hook namespace. To include observations from every tool, set `"CLAUDE_MEM_SESSION_START_INCLUDE_ALL_SOURCES": "true"` in `~/.claude-mem/settings.json`, or turn on **Include all sources at session start** in the viewer settings.


# Screenpipe Integration
Source: https://docs.claude-mem.ai/screenpipe-integration

Bring selected screen and meeting context into claude-mem with the bundled Screenpipe skill.

[Screenpipe](https://screenpipe.com) records screen text and audio on your computer.
The bundled `screenpipe` skill lets you recall that context from Claude Code and
save selected facts into claude-mem for future sessions.

## Setup

1. Install [Screenpipe](https://screenpipe.com), grant its recording permissions,
   and leave it running on the same computer as Claude Code.
2. [Install claude-mem](/installation) and restart Claude Code. The skill ships
   inside the plugin; no additional MCP server or package is required.
3. Invoke the skill:

```text theme={null}
/claude-mem:screenpipe Find the release discussion from my meetings this morning.
```

To save useful context, include that in your request:

```text theme={null}
/claude-mem:screenpipe Find yesterday's API design discussion and remember the decisions in this project.
```

The skill searches a bounded time window, summarizes matching screen text or audio
transcripts with source IDs and timestamps, and saves a selected note only when
asked. Saved notes use the existing local worker observation API and can be
retrieved with claude-mem's memory search tools.

```text theme={null}
Before: claude-mem recalls your agent sessions.
After:  Screenpipe screen/audio search -> selected context -> claude-mem observation
```

## Configuration and privacy

The helper requires Node.js 20+ (already required by claude-mem). It defaults to
Screenpipe at `http://127.0.0.1:3030`. Set `SCREENPIPE_URL` in the agent's environment
for another local port, and `SCREENPIPE_API_KEY` if Screenpipe requires bearer
authentication. Keep the API key out of prompts and command arguments.

Searches default to screen text and 20 results per page, with an explicit time
window. Audio is requested for meeting queries. The helper returns text and
source metadata, not screenshots or audio files. Long text is marked as truncated.

The HTTP requests go to local services, but **retrieved text enters the agent's
conversation** and is sent to its configured AI provider. Search results are
wrapped in `<private>` so claude-mem's automatic capture doesn't store them; only
a note you ask to save is stored. Saved notes are stored like any other
claude-mem memory: in the local database, and in your cloud account if cloud
sync is on. Choose a narrow topic, app, and time window.

Saving uses claude-mem's running local worker, found from `CLAUDE_MEM_WORKER_PORT`
or `~/.claude-mem/settings.json`. Hosted server mode and remote Screenpipe
instances are not supported by this basic integration. It does not enable
recording, periodically poll, or bulk-sync history.

## Troubleshooting

* **Connection failure or timeout:** check that Screenpipe or the claude-mem
  worker is running at the configured address. The helper exits with an error;
  it does not report an empty search or successful import.
* **HTTP 401/403:** check Screenpipe's API-key settings and `SCREENPIPE_API_KEY`.
* **No matches:** confirm Screenpipe recorded the requested interval and check
  the time zone, content type, and app filter.
* **Unconfirmed save:** keep the selected note and check memory before retrying,
  since a connection failure can happen after the worker stored it.

For a support report, include the operation and helper error; omit recorded text
and credentials unless you intend to share them.


# Smart Explore Benchmark
Source: https://docs.claude-mem.ai/smart-explore-benchmark

Token efficiency comparison between AST-based and traditional code exploration

# Smart Explore Benchmark

Smart Explore uses tree-sitter AST parsing to provide structural code navigation through three MCP tools: `smart_search`, `smart_outline`, and `smart_unfold`. This report documents a rigorous A/B comparison against the standard Explore agent (which uses Glob, Grep, and Read tools) to quantify the token savings and quality trade-offs.

## Executive Summary

| Metric | Smart Explore | Explore Agent | Advantage |
| - | :-: | :-: | - |
| Discovery (cross-file search) | \~14,200 tokens | \~252,500 tokens | **17.8x cheaper** |
| Targeted reads (specific symbols) | \~5,650 tokens | \~109,400 tokens | **19.4x cheaper** |
| End-to-end (search + read) | \~4,200 tokens | \~45,000 tokens | **10-12x cheaper** |
| Completeness | 5/5 full source returned | 4/5 (truncated longest method) | Smart Explore more reliable |
| Speed | Under 2s per call | 5-66s per call | **10-30x faster** |

## Methodology

### Test Environment

* **Codebase**: claude-mem (`src/` directory, 194 TypeScript files, 1,206 parsed symbols)
* **Model**: Claude Opus 4.6 for both approaches
* **Measurement**: Token counts from tool response metadata (`total_tokens` for Explore agents, self-reported `~N tokens for folded view` for Smart Explore)

### Controls

The Explore agents were explicitly instructed: *"Do NOT use smart\_search, smart\_outline, or smart\_unfold tools. Only use Glob, Grep, and Read tools."* This was verified necessary after an initial round where agents opportunistically used the Smart Explore tools, invalidating the comparison.

### Queries

Five queries were selected to represent common exploration tasks:

1. **"session processing"** -- Cross-cutting feature spanning multiple services
2. **"shutdown"** -- Infrastructure concern touching 6+ files
3. **"hook registration"** -- Architecture question about plugin system
4. **"sqlite database"** -- Technology-specific search across the data layer
5. **"worker-service.ts outline"** -- Single large file (1,225 lines) structural understanding

## Round 1: Discovery

*"What exists and where is it?"* -- Finding relevant files and symbols across the codebase.

### Results

| Query | Smart Explore | Explore Agent | Ratio | Explore Tool Calls |
| - | :-: | :-: | :-: | :-: |
| session processing | \~4,391 t | 51,659 t | **11.8x** | 15 |
| shutdown | \~3,852 t | 51,523 t | **13.4x** | 18 |
| hook registration | \~1,930 t | 51,688 t | **26.8x** | 37 |
| sqlite database | \~2,543 t | 58,633 t | **23.1x** | 16 |
| worker-service outline | \~1,500 t | 38,973 t | **26.0x** | 15 |
| **Total** | **\~14,216 t** | **252,476 t** | **17.8x** | **101** |

### What Each Returned

**Smart Explore** (1 tool call each): 10 ranked symbols with signatures, line numbers, and JSDoc summaries, plus folded structural views of all matching files showing every function/class/interface with bodies collapsed.

**Explore Agent** (15-37 tool calls each): Synthesized narrative reports with architecture diagrams, design pattern analysis, data flow explanations, complete interface dumps, and file structure maps. Significantly more explanatory prose.

### Analysis

The token gap is widest for narrowly-scoped queries ("hook registration" at 26.8x) because the Explore agent reads multiple full files to find relatively few relevant symbols. For broad queries ("session processing" at 11.8x), more of the file content is relevant, narrowing the ratio.

Smart Explore's consistent 1-tool-call pattern means its cost is predictable. The Explore agent's cost varies with how many files it reads and how much it synthesizes -- ranging from 15 to 37 tool calls for comparable scope.

## Round 2: Targeted Reads

*"Show me this specific function."* -- Reading the implementation of a known symbol after discovery.

Based on the Round 1 results, five specific symbols were selected as natural drill-down targets:

| Target Symbol | File | Lines |
| - | - | :-: |
| `SessionManager.initializeSession` | services/worker/SessionManager.ts | 135 |
| `performGracefulShutdown` | services/infrastructure/GracefulShutdown.ts | 48 |
| `hookCommand` | cli/hook-command.ts | 45 |
| `DatabaseManager.initialize` | services/sqlite/Database.ts | 27 |
| `WorkerService.startSessionProcessor` | services/worker-service.ts | 158 |

### Results

| Symbol | Smart Unfold | Explore Agent | Ratio | Completeness |
| - | :-: | :-: | :-: | - |
| initializeSession (135 lines) | \~1,800 t | 27,816 t | **15.5x** | Both returned full source |
| performGracefulShutdown (48 lines) | \~700 t | 19,621 t | **28.0x** | Both returned full source |
| hookCommand (45 lines) | \~650 t | 18,680 t | **28.7x** | Both returned full source |
| DatabaseManager.initialize (27 lines) | \~400 t | 22,334 t | **55.8x** | Both returned full source |
| startSessionProcessor (158 lines) | \~2,100 t | 20,906 t | **10.0x** | Smart Unfold: complete. Explore: **truncated** |
| **Total** | **\~5,650 t** | **109,357 t** | **19.4x** | |

### Analysis

**The ratio scales inversely with symbol size.** The smallest function (`initialize`, 27 lines) shows the biggest gap at 55.8x because the Explore agent still reads the entire 235-line file to extract 27 lines. The largest method (`startSessionProcessor`, 158 lines) narrows to 10x since more of the file is "useful."

**Smart Unfold returned more complete code.** For the longest method (158 lines), the Explore agent truncated the error handling section with "... error handling continues ...", while `smart_unfold` returned the complete implementation. This is because smart\_unfold extracts by AST node boundaries, guaranteeing completeness regardless of symbol size.

**Explore agents add zero unique information for targeted reads.** When you already know the file path and symbol name, the agent's overhead is pure waste -- it reads the file, locates the function, and echoes it back. The only addition is a brief explanatory paragraph.

## Combined Workflow

The realistic workflow is discovery followed by targeted reading. Here is the end-to-end cost comparison for understanding a single function:

### Smart Explore: search + unfold

```
smart_search("shutdown", path="./src")     ~3,852 tokens
smart_unfold("GracefulShutdown.ts", "performGracefulShutdown")  ~700 tokens
────────────────────────────────────────────────────────────────
Total: ~4,552 tokens (2 tool calls, under 3 seconds)
```

### Explore Agent: single query

```
"Find and explain the shutdown logic"      ~51,523 tokens
────────────────────────────────────────────────────────────────
Total: ~51,523 tokens (18 tool calls, ~43 seconds)
```

**End-to-end ratio: 11.3x** -- and the Smart Explore workflow gives you the actual source code, while the Explore agent gives you a prose summary that may paraphrase or truncate.

## Quality Assessment

Neither approach is universally better. They optimize for different outcomes.

### Smart Explore Strengths

* **Predictable cost**: 1 tool call per operation, consistent token ranges
* **Complete source code**: AST-based extraction guarantees full symbol bodies
* **Structural context**: Folded views show every symbol in matching files
* **Speed**: Sub-second responses enable rapid iteration
* **Composability**: Search, outline, and unfold chain naturally

### Explore Agent Strengths

* **Synthesized understanding**: Produces architecture narratives, data flow diagrams, and design pattern analysis
* **Cross-cutting explanation**: Connects concepts across files that individual symbol reads cannot
* **Onboarding quality**: Output reads like documentation, not raw code
* **Error handling insight**: Identifies edge cases and design decisions that require reading multiple related functions
* **No prior knowledge needed**: Can answer open-ended questions without knowing file paths or symbol names

### Quality by Task Type

| Task | Better Tool | Why |
| - | - | - |
| "Where is X defined?" | Smart Explore | One call, exact answer |
| "What functions are in this file?" | Smart Explore | Outline returns complete structural map |
| "Show me this function" | Smart Explore | Unfold returns exact source, never truncates |
| "How does feature X work end-to-end?" | Explore Agent | Reads multiple files and synthesizes narrative |
| "What design patterns are used here?" | Explore Agent | Requires reading and interpreting, not just extracting |
| "Help me understand this codebase" | Explore Agent | Produces onboarding-quality documentation |

## When to Use Which

**Use Smart Explore when:**

* You know what you are looking for (function name, concept, file)
* You need source code, not explanation
* You are iterating quickly (read, modify, read again)
* Token budget matters (large codebases, long sessions)
* You need file structure at a glance

**Use the Explore Agent when:**

* You need synthesized cross-cutting understanding
* The question is open-ended ("how does this system work?")
* You are writing documentation or architecture reviews
* You need to understand *why*, not just *what*
* You are onboarding to an unfamiliar codebase

**Use both when:**

* Start with Smart Explore for discovery and navigation
* Escalate to Explore Agent only for deep analysis that requires multi-file synthesis
* This hybrid approach captures most of the token savings while preserving access to deep understanding when needed

## Token Economics Reference

| Operation | Tokens | Use Case |
| - | :-: | - |
| `smart_search` | 2,000-6,000 | Cross-file symbol discovery |
| `smart_outline` | 1,000-2,000 | Single file structural map |
| `smart_unfold` | 400-2,100 | Single symbol full source |
| `smart_search` + `smart_unfold` | 3,000-8,000 | End-to-end: find and read |
| Explore Agent (targeted) | 18,000-28,000 | Single function with explanation |
| Explore Agent (cross-cutting) | 39,000-59,000 | Architecture-level understanding |
| Read (full file) | 8,000-15,000+ | Complete file contents |

### Savings by Workflow

| Workflow | Smart Explore | Traditional | Savings |
| - | :-: | :-: | :-: |
| Understand one file | outline + unfold (\~3,100 t) | Read full file (\~12,000 t) | **4x** |
| Find a function across codebase | search (\~3,500 t) | Explore agent (\~50,000 t) | **14x** |
| Find and read a specific function | search + unfold (\~4,500 t) | Explore agent (\~50,000 t) | **11x** |
| Navigate a 1,200-line file | outline (\~1,500 t) | Read full file (\~12,000 t) | **8x** |


# T3 Code Integration
Source: https://docs.claude-mem.ai/t3code-integration

Native Claude-Mem hooks and MCP search for T3 Code's Codex and Claude Code providers.

T3 Code runs coding providers on its server's machine. Claude-Mem installs into those providers' native configuration homes, so their existing hooks capture prompts and tool results, generate summaries, and inject project context into future sessions. The same plugin supplies MCP memory search.

## Install

Open T3 Code once and configure a **Codex** or **Claude Code** provider. On the machine running the T3 server, run:

```bash theme={null}
npx claude-mem@latest install --ide t3code
```

`t3` and `t3-code` are aliases for `t3code`. The memory observer provider is a separate choice: use the main installer's provider selector or an explicit `--provider` flag as usual.

Restart T3 Code and start a new thread in your project. If Codex prompts to trust Claude-Mem's hooks, approve them through the provider's normal approval flow. If the T3 client does not expose that prompt, open the same Codex executable with the same `CODEX_HOME` in a terminal, trust the hooks there, then restart T3 Code. Installing the plugin does not bypass hook trust.

## What gets configured

The installer reads `~/.t3/userdata/settings.json`, including both `providerInstances` and legacy `providers`. An explicit instance overrides the legacy entry for its default slot. Disabled providers are skipped.

| T3 provider | Claude-Mem installation |
| - | - |
| Codex | Native Codex plugin marketplace, plugin cache, and `features.hooks` in its shared home's `config.toml` |
| Claude Code (`claudeAgent`) | Native Claude Code plugin registered at user scope in its configured `CLAUDE_CONFIG_DIR` |
| Other T3 providers | Use that provider's existing Claude-Mem integration; this installer currently handles Codex and Claude Code |

Configured binary paths and home paths are honored. T3-managed Codex uses the active installation in `T3CODE_HOME/tools/codex`. Codex shadow homes share configuration and plugins with their source home, so Claude-Mem installs into that source instead of creating conflicting files in the shadow directory.

The connector uses the existing Claude-Mem plugin lifecycle, capture handlers, privacy filtering, and project resolution. It adds no transcript watcher and does not edit T3 settings or its database. Providers using the same native home share the installation with their standalone CLI.

## Custom server or development profile

If T3 Code uses a custom home, export `T3CODE_HOME` before installing. For a specific settings file, including a development profile:

```bash theme={null}
CLAUDE_MEM_T3CODE_SETTINGS_PATH=/path/to/t3/userdata/settings.json \
  npx claude-mem@latest install --ide t3code
```

Run on the remote server machine for a remote T3 environment, and inside WSL for a WSL-backed provider. Installing on the phone or browser's machine will not configure the remote provider.

## Status and removal

```bash theme={null}
npx claude-mem t3code status
npx claude-mem t3code status --settings /path/to/settings.json
npx claude-mem t3code uninstall
```

Status checks provider configuration, plugin enablement, marketplace registration, and runtime assets. It does not claim hook approval or successful capture: verify a new thread produces observations in the Claude-Mem viewer at `http://localhost:37777` on the server machine.

Removal disables only Claude-Mem in the configured native homes, preserving other plugins and provider settings. This also disables Claude-Mem for standalone CLIs that share those homes. Restart T3 Code after removal. The main `npx claude-mem uninstall` command also performs this cleanup; memory data is preserved.

## Troubleshooting

* **No settings file:** open T3 Code and complete provider setup, or point the installer at the actual server's settings file.
* **Managed Codex missing:** finish Codex setup inside T3 Code, then rerun the installer. Other usable providers are still configured, but the installer returns a nonzero exit code for the missing provider. The connector does not download or replace T3's provider runtime.
* **Launch overrides block capture:** remove Codex overrides that disable `features.hooks` or Claude-Mem. Claude's `--setting-sources`, when explicitly set, must include `user`; `--strict-mcp-config` and `--disable-all-hooks` block the plugin's normal operation. The installer reports these conflicts instead of rewriting your T3 launch arguments.
* **Provider install fails:** the installer reports each failed provider and returns a nonzero exit code. Repair that provider's binary or permissions, then rerun the installer; providers already installed remain usable.


# Telemetry
Source: https://docs.claude-mem.ai/telemetry

Anonymous usage analytics — on by default, fully documented, one command to opt out

# Telemetry

Claude-mem includes anonymous usage analytics (via PostHog) to help prioritize fixes and features.

**It is on by default (opt-out).** Events are anonymous, identified only by a random install UUID, and every analytics property passes a strict whitelist — see [What is collected](#what-is-collected) and [What is NEVER collected](#what-is-never-collected) below. Turning it off is one command:

```bash theme={null}
npx claude-mem telemetry disable
```

The standard [`DO_NOT_TRACK`](https://consoledonottrack.com) environment variable is also honored and overrides everything. The installer asks once at the end of `npx claude-mem install` so the default is never silent for new installs — your answer (either way) is remembered and never re-asked, and the prompt is skipped entirely when `DO_NOT_TRACK` is set or in CI/non-interactive installs.

## How instrumentation works

Claude-mem has a single instrumentation path (`instrument()` in `src/services/telemetry/instrument.ts`). Every observable event is described once and fans out to two sinks:

* **The local logger — always, at full fidelity.** Logging keeps working with telemetry off, and the local log never goes through the scrubber. This is where the complete, unredacted detail lives — on your machine.
* **Telemetry — only when consent passes.** The telemetry copy is scrubbed (the [whitelist](#what-is-collected) for structured properties; [allow-then-redact](#error-tracking) for error text) and, for high-volume events, rolled up into per-session/per-window aggregates before anything is sent.

So a single source of truth produces both the rich local log and the minimal, privacy-preserving telemetry — they never drift, and the scrubbing only ever happens on the telemetry branch.

**Note on session replay:** PostHog session replay is **not applicable** to claude-mem. Replay records a browser DOM session; claude-mem is a Node background worker with no browser surface, so there is nothing to replay and it is never enabled.

## What is collected

When enabled, events are anonymous and identified only by a random install UUID (`crypto.randomUUID()`, generated locally on first use).

Low-volume lifecycle events (`install_*`, `uninstall_completed`, `worker_started`) build an analytics profile keyed to that random UUID so aggregate retention and cohort statistics are computable — the profile contains nothing beyond the whitelisted fields below (platform, version, IDE/provider choice). It is not, and cannot be, connected to you: there is no name, email, IP, hardware ID, or any other identifier. All high-volume activity is sent with `$process_person_profile: false` and builds no profile at all.

About the observed IDE session's identity, claude-mem collects only its model id (`observed_model`) and a billing tier (`observed_billing`) — never account ids, emails, or tokens.

**High-volume events are rolled up, not streamed.** Rather than emit one event per compression or context injection, claude-mem aggregates them locally and sends one summary:

* **`observer_turn_rollup`** — a **per-session** accumulator. Every compression in a session folds into one running rollup that is emitted **once, at session end** (instead of one `session_compressed` event per turn). It carries a `rollup_reason` explaining why it flushed (`session_end` | `worker_shutdown` | `safety_flush`) and a `window_seq` partial-flush counter (`0` for a normal one-shot session; `0,1,2,…` only when a long-lived session trips the periodic safety sweep).
* **`context_injected_rollup`** — a **5-minute time-window** accumulator for context injections.

This rollup model is what cut the high-volume event stream by roughly 99.9%. There is no longer any code path that emits raw `session_compressed` or `context_injected` events directly — the only path to PostHog for that activity is the rollup.

Every event property passes through a strict whitelist scrubber — any key not in this table is silently dropped before sending:

| Field | Example | Description |
| - | - | - |
| event name | `observer_turn_rollup` | Which of the events below occurred |
| `distinct_id` | `7f3c…` (random UUID) | Anonymous install ID — not derived from you or your machine |
| `version` | `13.4.2` | claude-mem version |
| `os` | `darwin` | Operating system platform |
| `os_version` | `10.0.22631` | OS kernel release string — distinguishes e.g. Windows 10 from 11 |
| `is_wsl` | `false` | Whether running under Windows Subsystem for Linux |
| `arch` | `arm64` | CPU architecture |
| `runtime` | `bun` | `bun` or `node` |
| `runtime_version` | `1.2.0` | Runtime version string |
| `node_version` | `22.14.0` | Node.js version string |
| `duration_ms` | `1843` | How long an operation took |
| `outcome` | `ok` | Coarse result — a closed enum: ok / error / partial / invalid\_output / aborted |
| `error_category` | `provider_error` | Coarse error bucket — never an error message |
| `locale` | `en-US` | Language tag |
| `is_ci` | `false` | Whether running in CI |
| `endpoint` | `by-file` | Which claude-mem search route — always one of our route names, never a query |
| `ide` | `claude-code` | Installer IDE choice (the installer's own id list) or, on `observer_turn_rollup`, the observed session's platform source (`claude` / `codex` / `cursor` / …) |
| `provider` | `claude` | LLM provider choice: claude / codex / gemini / openrouter / openai-compatible |
| `runtime_mode` | `worker` | worker or server runtime |
| `trigger` | `heartbeat` | Whether `worker_started` was a real start or the daily heartbeat |
| `count` | `7` | Integer volume, e.g. observations stored in one compression |
| `has_summary` | `true` | Whether a compression also produced a session summary |
| `is_update` | `false` | Whether an install ran over an existing installation |
| `interactive` | `true` | Whether the installer ran in an interactive terminal |
| `install_method` | `npm` | Which package manager launched the CLI: npm / bun / pnpm / yarn |
| `bun_version` / `uv_version` | `1.3.9` / `0.7.2` | Toolchain versions detected during install |
| `claude_code_version` | `2.0.14` | Claude Code CLI version, if detectable |
| `trial_days` | `30` | Assigned CMEM Pro installer offer length: 30 days (older events may report 7 or 14) |
| `trial_variant` | `test_30` | Trial assignment identifier: control\_7 / test\_14 / test\_30; all current arms grant 30 days |
| `offer_surface` / `funnel_source` | `installer` / `installer` | Closed source labels on the installer offer exposure event |
| `stage` | `awaiting_checkout` | Installer trial polling stage: awaiting\_login / awaiting\_checkout / awaiting\_approval |
| `phase` | `login` | Installer OAuth pairing phase — a closed enum: login / enrollment / deferred |
| `provider_source` | `default` | How the installer decided the provider — a closed enum: flag (`--provider` given) / default (non-interactive fresh install fell back to claude) / persisted (non-interactive run reused the configured provider) / prompt (interactive choice) |
| `mode` | `code` | Active claude-mem mode id (our mode list) |
| `model` | `claude-haiku-4-5` | Model id used for compression |
| `observed_model` | `claude-fable-5-1` | Model id the observed IDE session itself was running (read from its transcript) — distinct from `model`, which is the compression model. `unknown` when not determinable |
| `observed_billing` | `max` | Billing posture of the observed session — a closed enum: max / pro / team / enterprise / subscription / api\_key / bedrock / vertex / foundry / unknown. Never an account id, email, or token |
| `hook` | `ingest` | What triggered a compression: init / ingest / summarize |
| `observation_type`, `obs_type_*` | `bugfix`, `3` | Observation type buckets (bugfix / discovery / decision / refactor / other) — counts only |
| `compression_ms` | `2140` | Latency of the compression model call |
| `tokens_input` / `tokens_output` | `5800` / `420` | Real token usage reported by the model API for one compression |
| `compression_ratio` | `13.8` | tokens\_input ÷ tokens\_output |
| `cost_usd` | `0.0021` | Provider-reported cost of one compression call in USD (Claude SDK / openrouter.ai) — never an estimate, absent when the provider reports none |
| `endpoint_class` | `openrouter` | Whether the OpenRouter provider targets openrouter.ai or a custom gateway |
| `rollup_reason` | `session_end` | Why a per-session `observer_turn_rollup` was emitted — a closed enum: session\_end / worker\_shutdown / safety\_flush |
| `window_seq` | `0` | Partial-flush sequence number for a rollup — `0` for a normal one-shot session, incrementing only when a long-lived session trips the safety sweep |
| `observation_count`, `session_count` | `50`, `12` | How many observations/sessions fed one context injection |
| `timeline_depth_days` | `90` | Age in days of the oldest injected observation |
| `has_session_summary` | `true` | Whether a session summary was part of the injection |
| `tokens_injected` | `17914` | Estimated tokens of injected context |
| `tokens_saved_vs_naive` | `144379` | Estimated tokens saved vs re-discovering that work |
| `search_strategy` | `timeline` | Which retrieval strategy built the injection (our enum) |
| `db_observation_count`, `db_session_count`, `db_summary_count`, `db_project_count` | `92501`, `5243`, `9698`, `379` | Total rows in the local memory database — counts only, never names or text |
| `db_size_mb` | `364.4` | Memory database file size in MB |
| `install_age_days` | `104` | Days since the install's first recorded session |
| `obs_count_7d` / `obs_count_30d` | `1887` / `10357` | Observations stored in the last 7 / 30 days |
| `days_since_last_obs` | `0` | Days since the most recent observation was stored |
| `result_count` | `12` | How many results a memory search returned — count only, never the results or the query |
| `chroma_available` | `true` | Whether the vector-search backend was reachable for a search — reachability only; zero-result fallbacks report `true` here, so count fallbacks via `fallback_reason` |
| `fallback_reason` | `none` | Why a search fell back from vector search: none / chroma\_connection / chroma\_error / chroma\_not\_initialized / chroma\_zero\_results — a closed enum, never an error message |
| `invalid_output_class` | `idle` | Coarse class of an unusable compression output: xml / idle / prose (`xml` = looked like the expected format but failed to parse) — never the output itself |
| `consecutive_invalid_outputs` | `0` | Legacy unusable-output counter, retained as a scrubbed numeric field |
| `respawn_triggered` | `false` | Legacy recovery flag for old invalid-output restarts |
| `abort_reason` | `idle` | Why a compression session was aborted: idle / shutdown / overflow / restart\_guard / quota / rate\_limit / auth / provider\_switch / deadline\_exceeded (a model request outlived `CLAUDE_MEM_LLM_TIMEOUT_MS`) / output\_retry (a queued batch was answered with neither observation XML nor the skip tag, and is asked for once more) / drift (the observer kept replying in tags outside the observation schema, so a fresh generation was started) / none — a closed enum |
| `outcomes_aborted_deadline_exceeded` | `1` | On `observer_turn_rollup`: how many of the session's `outcomes_aborted` were model requests abandoned at the per-request deadline — a count only |
| `previous_shutdown` | `clean` | How the previous worker run ended, detected at startup: crash / clean / unknown |
| `previous_uptime_seconds` | `86400` | How long the previous worker run was up, in whole seconds |
| `uptime_seconds` | `3600` | How long the worker was up when it stopped, in whole seconds |
| `shutdown_reason` | `restart` | Why the worker stopped: stop / restart / signal / idle |
| `process_rss_mb` | `187` | Worker process resident memory, integer megabytes |
| `heap_used_mb` | `92` | Worker JS heap in use, integer megabytes |
| `hook_type` | `observation` | Which hook kind failed: context / session-init / observation / summarize / session-end / file-context — our handler names |
| `limit_window` | `five_hour` | Which subscription window was exhausted on `usage_limit_hit`: five\_hour / seven\_day / seven\_day\_opus / seven\_day\_sonnet / overage / unknown — a closed enum |
| `overage_status` | `rejected` | Whether extra-usage credits could cover the request: allowed / allowed\_warning / rejected / unknown — a closed enum |
| `is_using_overage` | `false` | Whether the request was already being billed to extra usage |
| `resets_in_minutes` | `112` | Whole minutes until the exhausted window resets, floored at 0 — never the provider's message text |
| `error_mode` | `worker_unavailable` | Coarse hook failure mode: worker\_unavailable / blocking\_error — never an error message |
| `consecutive_failures` | `3` | How many hook failures occurred in a row (the fail-loud counter) |
| `threshold_tripped` | `true` | Whether the consecutive-failure count reached the fail-loud threshold |
| `skill_id` | `mem-search` | Which bundled skill was invoked — a closed enum of `plugin/skills/` directory names, or `other`. Third-party skill names are never sent. |
| `skill_source` | `first_party` | `first_party` (a shipped `plugin/skills/` skill) or `third_party` (collapsed to `skill_id: other`) |
| `skill_trigger` | `tool` | How the skill was invoked: `tool` (host Skill tool) or `prompt` (typed `/skill` at session-init). Never the prompt body. |

One value is derived server-side rather than sent by the client: PostHog resolves the request's sender IP to a **coarse location** (country / region / city) at ingestion, before the IP itself is discarded. The client never attaches an IP to any event, and the raw IP is never stored — see [What is NEVER collected](#what-is-never-collected).

### Events

| Event | When | Extra properties |
| - | - | - |
| `install_completed` | `npx claude-mem install` finishes | `ide`, `provider`, `provider_source`, `runtime_mode`, `is_update`, `outcome`, `duration_ms`, `interactive`, `install_method`, `bun_version`, `uv_version`, `claude_code_version` |
| `installer_oauth_started` | The installer opened the browser sign-in link | `version` — never the link, pairing id, secret, or device code |
| `installer_oauth_completed` | Browser sign-in finished | `version` |
| `installer_oauth_timeout` | Sign-in polling reached the pairing's expiry (the server's `expires_in`, capped at 30 minutes; 4 minutes when the server reports none) | `version`, `phase` (login / enrollment), `duration_ms` |
| `installer_oauth_start_failed` | `POST /api/installer/oauth/start` did not return a usable pairing | `version`, `outcome` (http\_error / network / timeout / bad\_body), `interactive`, `phase` (login / deferred) |
| `installer_oauth_deferred` | A non-interactive install that skipped sign-in printed the optional sign-in link at the end | `version`, `interactive` (always `false`) |
| `install_failed` | The installer aborts | `error_category` (our error-taxonomy id), `interactive`, `install_method`, `claude_code_version` |
| `pro_offer_viewed` | A CMEM Pro offer is displayed in the installer | `trial_days`, `trial_variant`, `offer_surface` (`installer`), `funnel_source` (`installer`) |
| `trial_email_submitted` | The user submits an email to start the installer trial flow | `version` only — never the email |
| `trial_link_sent` | The trial start API accepts the request and sends a sign-in link | `version`, `duration_ms` — never the email, link, pairing secret, or device code |
| `trial_activated` | Trial credentials are received and saved after browser approval | `version`, `duration_ms` |
| `trial_poll_timeout` | Browser completion polling is cancelled, expires, times out, or becomes unreachable | `version`, `stage`, `outcome`, `duration_ms` |
| `uninstall_completed` | `npx claude-mem uninstall` finishes | — |
| `worker_started` | The background worker starts, plus one heartbeat per 24h of uptime | `trigger` (start / heartbeat), `duration_ms`, `ide`, `provider`, `mode`, `runtime_mode`, process memory (`process_rss_mb`, `heap_used_mb`), the install snapshot: `db_observation_count`, `db_session_count`, `db_summary_count`, `db_project_count`, `db_size_mb`, `install_age_days`, `obs_count_7d`, `obs_count_30d`, `days_since_last_obs`; on a real start also crash detection: `previous_shutdown` (crash / clean / unknown) and, after a clean shutdown, `previous_uptime_seconds` |
| `observer_turn_rollup` | Emitted **once per session, at session end** — a per-session rollup that aggregates every compression in that session (stored observations, invalid-output drops, failures, aborts) instead of one event per turn | `rollup_reason` (session\_end / worker\_shutdown / safety\_flush), `window_seq`, aggregated `outcomes_*` counts (including `outcomes_aborted_deadline_exceeded`), `total_tokens_input`, `total_tokens_output`, `total_cost_usd`, `avg_duration_ms`, `avg_compression_ms`, `top_model`, `top_abort_reason` (the most common `abort_reason` among the session's aborted turns; present only when one aborted), `observed_model`, `observed_billing`, `observations_created` (sum of observations generated in the session — pairs with `total_cost_usd` to derive cost per observation), summed `obs_type_*` buckets, `window_start_ts`, plus the per-turn fields it summarizes (`provider`, `ide`) |
| `context_injected_rollup` | A 5-minute time-window rollup of context injections (stored memory injected into new sessions) | aggregated `outcomes_ok` / `outcomes_error` counts, `count`, `total_tokens`, `avg_tokens`, `total_observations_injected` (sum of observations served from cache into prompts), `total_tokens_saved_vs_naive`, `window_start_ts` |
| `work_state_usage_rollup` | A 5-minute rollup of captured work-state activity and instruction returns; also flushed at worker shutdown | `platform`, `agent_role`, `instruction_state`, the counters described below, `window_start_ts` |
| `search_performed` | A memory search runs (never the query text) | `endpoint`, `outcome`, `duration_ms`, `result_count`, `search_strategy`, `chroma_available`, `fallback_reason` |
| `skill_invoked` | A bundled skill is invoked — the host Skill tool loads its instructions, or the user types a first-party `/skill` at session-init. **Not** work completion; no `duration_ms` / outcome. Worker path only. Unknown `/foo` emits nothing. | `skill_id` (closed enum + `other`), `skill_source` (`first_party` / `third_party`), `skill_trigger` (`tool` / `prompt`), `ide` |
| `worker_stopped` | The background worker shuts down gracefully | `uptime_seconds`, `shutdown_reason` (stop / restart / signal / idle) |
| `supervisor_registry_degraded` | The worker could not write its process registry (`supervisor.json`, e.g. an unwritable data directory) and kept it in memory instead. Sent once per degraded episode, not once per failed write | `error_category` (the filesystem error code, e.g. `EACCES` / `EROFS` / `ENOSPC`, or `unknown`) |
| `worker_start_failed` | A worker this launcher started died before it became ready. Sent by the launcher that started it, never by one that only waited for another launcher's worker | `outcome` (`dead`), `error_category` (`boot_crash` when the crash could be reproduced, else `unreachable_after_boot`); never the crash text, which stays in the local log |
| `usage_limit_hit` | The Claude subscription behind the observer reports a window as `rejected` — since the observer shares the observed session's account, this is when the user's own Claude Code session ran out of usage. Emitted once per exhausted window (deduped on the window's reset time; a worker restart while still capped re-emits once). Only fires when the observer runs on Claude with a subscription login — API-key, Gemini, and OpenRouter observers never see it | `limit_window` (five\_hour / seven\_day / seven\_day\_opus / seven\_day\_sonnet / overage / unknown), `overage_status` (allowed / allowed\_warning / rejected / unknown), `is_using_overage`, `resets_in_minutes`, `ide`, `provider`, `observed_model`, `observed_billing` |
| `hook_failed` | A claude-mem hook fails hard — the worker is unreachable past the fail-loud threshold, or a blocking error occurs | `hook_type`, `error_mode`, `consecutive_failures`, `threshold_tripped` |
| `error_occurred` | The worker returns an HTTP 5xx | `error_category` |
| `$exception` | A real error is captured for [error tracking](#error-tracking) — consent-gated and independently kill-switchable | Redacted `error_type` / `error_message` / `error_stack`, `occurrence_count`, plus whitelisted context. See [Error tracking](#error-tracking) for exactly what is kept vs. redacted |

### Work-state usage and diagnostic limits

Work-state rollups contain counts only. They never include task titles, fields,
prompts, project names, paths, raw session or agent IDs, or inferred models.
`platform` is a fixed supported-host name, `other`, or `unknown`; `agent_role`
is `main`, `subagent`, or `unknown` (using the same subagent predicate as capture).

| Counter | What it measures |
| - | - |
| `instruction_returned_count` | Hooks returning the complete work-state instruction block, including cached blocks. This is a handoff to the host, **not proof the host accepted it or the model followed it**. |
| `instruction_disabled_count`, `instruction_excluded_count`, `instruction_missing_count`, `instruction_unknown_count` | Known configuration exclusions, successful returns without the block, or a failed/unknown context read. |
| `captured_prompt_count`, `captured_session_count` | Newly recorded, nonprivate prompts with an original hook timestamp within the 30-day replay window, and their first captured session/agent scope. Untimestamped transcript prompts are omitted. |
| `captured_tool_count`, `unidentified_tool_event_count` | Distinct captured tool calls with stable IDs; calls without a stable ID count only in the second diagnostic counter. Both require an original event timestamp and a preceding known public-turn boundary. Memory/project/privacy/agent exclusions still apply. |
| `native_todo_count` | Captured `TodoWrite`, `SetTodoList`, or `update_plan` calls, including those excluded from memory generation. With `instruction_state=returned`, this is a useful competing-todo diagnostic, **not a verdict of noncompliance**. |
| `captured_read_count`, `captured_write_count` | Distinct work-state tool receipts seen by post-tool capture, attributed to the captured host and agent role. |
| `mcp_read_count`, `mcp_write_count` | Executions in this plugin's MCP server, including failures before the worker can answer. Agent and host attribution are `unknown`. Receipts remain in the local spool until a worker can collect them. |

Both `captured_` and `mcp_` read/write counters also have outcome counters ending
in `_ok_count`, `_error_count`, `_excluded_count`, `_disabled_count`, or
`_unknown_count`. Only an explicit saved receipt establishes a successful write.
The two sources can observe **the same call: never add them as distinct usage**.

`instruction_state` describes the last known hook handoff preceding the event
in that exact local session/agent scope. Delayed activity older than the latest
handoff has `instruction_state=unknown`; later instructions are never applied
retroactively. Captured prompts and tools without original timestamps are omitted.
Before a handoff is observed, it is `unknown`. Direct MCP calls,
server-runtime-only capture, missing hooks, and an unavailable worker can leave
coverage unknown. Live Pi, OpenCode, and OMP prompt callbacks carry their original
timing; Pi uses the persisted user-message timestamp even on replay. Generic DSH
client calls and OpenClaw synthetic init paths lack verified prompt timing and
remain outside captured prompt/tool counts. OMP has its own bounded platform label;
missing stable tool IDs contribute only unidentified-arrival diagnostics. Older adapters that already supplied a default host cannot
be distinguished from hosts that explicitly reported it. Missing counters or
events are not evidence of zero usage or
zero adherence; an ordinary question may correctly require no write. No
compliance percentage or task classification is computed.

Local hashed receipt keys suppress duplicate prompts, tool replay, and repeated
spool delivery across worker restarts for 30 days. Cleanup on activity, at most
once an hour, removes older
receipts; older events are dropped rather than counted again. A local,
content-free public/private turn bit is maintained even while analytics is off,
so opting back in during private work cannot reuse a previous public prompt.
Only a strictly newer, timestamped public submission can reopen public coverage,
including when duplicate text reuses a prompt row; private turns win timestamp ties.
Neither the keys nor this bit are sent to PostHog. The worker uses the existing
30-second consent cache. Telemetry remains best effort: opt-out disables
analytics, and a crash before a rollup flush can lose counts. This feature does
not backfill past releases.

## Error tracking

Claude-mem captures real errors to PostHog Error Tracking as `$exception` events. **This is a deliberate change from the old strictly-whitelist-only posture:** error messages and stack traces are free-form text, so the property whitelist (which only passes known closed-set keys) would drop them entirely. Instead, error text takes a separate **allow-then-redact** path (`src/services/telemetry/error-scrub.ts`): we keep the diagnostic text and aggressively strip anything that could leak PII or secrets.

**What is kept (redacted):**

* The error **type** (constructor name, e.g. `TypeError`), capped to 100 chars.
* The error **message**, redacted and capped to 500 chars.
* The **stack trace** — only the top 10 frames, each redacted, capped to \~2KB total.
* An `occurrence_count` (how many times this error fingerprint fired in the current window).

**What is redacted out of that text** (replaced with `[REDACTED]`, in this order):

* Home directory (`/Users/you` → `~`) — first, so a username embedded in the home path never survives.
* Absolute filesystem paths → collapsed to basename (POSIX, Windows drive, and UNC paths) — keeps "which file" without the directory tree.
* URL / connection-string credentials and query strings — userinfo (`user:pass@`) and `?…`/`#…` are stripped from any `scheme://…` (http, ws, postgres, redis, mongodb+srv, amqp, …), so DB connection-string creds and signed-URL tokens die.
* Emails.
* API tokens and keys: provider-prefixed keys (`sk-`, `phc_`, `ghp_`, `xoxb-`, …), Bearer tokens, **AWS access key IDs** (`AKIA…`), JWTs, UUIDs, long hex blobs (24+ chars), and generic high-entropy tokens.
* **IPv4 addresses** (internal IPs/hostnames that leak in network errors).

The redaction pipeline is **pure and never throws** — hostile input (null, circular, objects with throwing getters, 200KB blobs) always yields a safe, bounded result, because telemetry must never break or block the worker. Raw input is hard-capped at 8KB before any regex runs (ReDoS defense).

**Rate-limiting.** At most **one `$exception` per error fingerprint per 60 seconds**. Errors are fingerprinted by type + a normalized message template + top stack frame, so a storm of the "same" error with varying ids/numbers dedupes to a single send with an occurrence count attached. This applies to both our manual captures and any SDK autocapture. (Autocapture is additionally re-scrubbed before send — raw source-context lines that posthog-node reads off disk are deleted, and filenames are redacted to basenames.)

**Consent-gated, with an independent kill-switch.** Error capture is gated by the normal telemetry consent chain (opting out of telemetry disables errors too) **and** by a separate `CLAUDE_MEM_TELEMETRY_ERRORS` switch — see [How to opt out](#how-to-opt-out-four-ways). No person profile is built for `$exception` events (`$process_person_profile: false`).

<Warning>
  **One-way door.** Unlike the whitelisted analytics events — every field of which is a number, boolean, or value from a closed set — `$exception` events carry real (redacted) message text. Once an error message is ingested into PostHog, it **cannot be selectively deleted** after the fact. This is a deliberate trade-off made to get actionable crash diagnostics, mitigated by aggressive redaction, rate-limiting, consent-gating, and the `CLAUDE_MEM_TELEMETRY_ERRORS=0` kill-switch. If you would rather send nothing free-form, set that variable.
</Warning>

## Historical backfill

Telemetry shipped later than claude-mem itself, so installs that predate it have activity the live events never saw. On the first worker start after upgrading, claude-mem performs a **one-time** backfill of that pre-telemetry history — anonymized counts only, passed through the same whitelist scrubber as everything else:

| Event | When (timestamp) | What it carries |
| - | - | - |
| `historical_activity` | One per day the install was active, stamped on that historical day | Daily activity counts only: observations, sessions, summaries, prompts, distinct-project **count**, observation-type buckets (`obs_type_*`), session outcomes (`session_completed_count` / `session_failed_count`), per-platform session counts (`sessions_claude_count` etc.), `subagent_obs_count`, `discovery_tokens`, plus `backfilled: true`. Profile-less (`$process_person_profile: false`), like all high-volume events |
| `install_inferred` | Once, stamped on the install's first recorded activity day | `first_active_date` (a date string, e.g. `2025-10-19`) and `backfilled: true` |

Like everything else, these are counts and closed-set values only — **never titles, prompts, file contents, or project names**. The same anonymous install UUID identifies them, and every property passes the whitelist scrubber.

A few things worth knowing:

* **It runs once.** A completion marker (`backfill.json` in the claude-mem data directory) is written after a successful send and prevents the backfill from ever running again. Until a run succeeds, no marker is written, so a failed attempt simply retries on the next worker start.
* **It honors the exact same consent gates as live telemetry** — `DO_NOT_TRACK`, `CLAUDE_MEM_TELEMETRY=0`, and `enabled: false` in `telemetry.json` all block it, and [debug mode](#debug-mode) prints the would-be payload without sending.
* **Opting out before the first worker start after upgrading prevents it entirely.** Nothing is sent and no marker is written while you are opted out — though if you opt back in later, the backfill will then run.
* **Location is upload-time, not historical.** The coarse location PostHog derives at ingestion (see above) reflects where the events were uploaded from, not where you were on the historical dates they describe.

## What is NEVER collected

| Never collected | Notes |
| - | - |
| Prompts or conversation content | Not even truncated or hashed |
| File paths or directory names | Redacted out of analytics entirely, and redacted out of error text (home dir → `~`, absolute paths → basename) — see [Error tracking](#error-tracking) |
| Source code | In any form — including the source-context lines posthog-node would otherwise attach to autocaptured exceptions (deleted before send) |
| Project or repository names | Including git remotes and branch names |
| Search queries | Only the fact that a search happened |
| IP addresses | Never attached to events by the client; the sender IP is used transiently at ingest to derive coarse location (country / region / city), then discarded — the analytics project is configured to never store sender IPs |
| Hardware or machine identifiers | Not even hashed MAC addresses or hostnames |
| Environment variable values | Ever |
| Emails, usernames, or any PII | Ever — emails, tokens, keys, and credentials are redacted out of error text too |
| Skill arguments, skill markdown, or prompt bodies | `skill_invoked` sends only a closed `skill_id` / `skill_source` / `skill_trigger`. `tool_input.args` and the rest of a slash prompt never leave the machine |
| Third-party skill names | Collapsed to `skill_id: other` + `skill_source: third_party`. Unknown `/foo` slash tokens emit no event at all |

**One honest exception: error messages.** Since the addition of [error tracking](#error-tracking), redacted error **messages and stack traces** ARE collected (as `$exception` events) — that is a deliberate change from the previous coarse-category-only posture, and it is consent-gated with its own [kill-switch](#how-to-opt-out-four-ways). Raw paths, prompts, project names, source code, and model output are still **never** collected — they are stripped from the error text before it leaves your machine.

Analytics properties are enforced in code: they go through a whitelist (only the fields in the [What is collected](#what-is-collected) table survive), not a blocklist. Every whitelisted field is either a number, a boolean, or a value from a closed set we define — there is no analytics field that could carry free-form user content. Error text is the one free-form path, and it goes through the separate allow-then-redact scrubber instead.

## How to opt out (four ways)

Any one of these keeps telemetry off — they are checked in this order, first match wins:

1. **`DO_NOT_TRACK`** — the [universal opt-out](https://consoledonottrack.com). Set `DO_NOT_TRACK=1` and telemetry is forced off, overriding everything else.
2. **`CLAUDE_MEM_TELEMETRY=0`** (also `false` / `off`) — environment override. (`CLAUDE_MEM_TELEMETRY=1` conversely forces it on.)
3. **Telemetry config file** — `enabled: false` in `telemetry.json` (see below).
4. **CLI command**:
   ```bash theme={null}
   npx claude-mem telemetry disable
   ```

### Error tracking opt-out (independent)

[Error tracking](#error-tracking) (`$exception` events with redacted message/stack) can be disabled **on its own**, without turning off anonymous analytics:

```bash theme={null}
CLAUDE_MEM_TELEMETRY_ERRORS=0   # also accepts 'false' / 'off'
```

This is the one telemetry path that carries free-form (redacted) text and is a [one-way door](#error-tracking) once ingested, so it has its own kill-switch for operators who are fine with anonymous counters but not error text. It defaults on whenever telemetry consent is on; any of the four opt-outs above also disables it implicitly (no consent ⇒ no errors).

Check the current state — and which of the four layers decided it — anytime:

```bash theme={null}
npx claude-mem telemetry status
```

## Debug mode

Want to see exactly what would be sent? Set:

```bash theme={null}
CLAUDE_MEM_TELEMETRY_DEBUG=1
```

With debug mode on (and telemetry enabled), every would-be event payload is printed to stderr and **nothing is sent over the network**.

## Where the config lives

Consent and the anonymous install ID are stored in `telemetry.json` inside the claude-mem data directory:

* Default: `~/.claude-mem/telemetry.json`
* Or `$CLAUDE_MEM_DATA_DIR/telemetry.json` if you've overridden the data dir

```json theme={null}
{
  "enabled": false,
  "installId": "<random UUID>",
  "decidedAt": "2026-06-09T21:00:00.000Z"
}
```

The `enabled` field is only present once you've made an explicit choice (installer prompt, `telemetry enable`, or `telemetry disable`). A file with just an `installId` means no decision was recorded and the default (on) applies. Delete the file to reset completely — a fresh install ID is generated on next use.


# Troubleshooting
Source: https://docs.claude-mem.ai/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](configuration).

**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 IDs, then fetch only relevant ones
   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](configuration) - Customize Claude-Mem
* [Development](development) - Build from source
* [Architecture](architecture/overview) - Understand the system


# Auto-Redaction
Source: https://docs.claude-mem.ai/usage/auto-redaction

Opt-in regex-based detection that replaces common secret patterns with <redacted/> placeholders before storage

# Auto-Redaction

claude-mem can automatically detect and redact common secrets before observations and summaries are stored. Unlike the manual [`<private>` tag](/usage/private-tags), this is a deterministic regex pipeline that catches secrets you never typed yourself — for example, an API key printed by a `curl` response or echoed by a `Bash` command.

## How it works

When enabled, redaction runs at the same single point where `<private>` tags are stripped, so it covers the capture paths at once: tool inputs and outputs, your prompts (including stored prompt history) and the assistant's last message used for summaries. The [server runtime](/hosted-server) also redacts every text value of an event body before it stores the event, and the worker and hook logs redact the tool line they write (for example a `Bash` command). One exception: server-runtime session and event **metadata** (such as the opening `prompt` in session metadata) is tag-stripped only when a string contains a tag, so redaction does not run on it. Content is scanned for a curated set of high-confidence secret patterns, and matches are replaced inline with a self-closing `<redacted type='...'/>` placeholder, preserving the surrounding context so search and observation quality stay intact.

```
Before:  curl -H "Authorization: Bearer sk-abc123def456..." …
After:   curl -H "Authorization: Bearer <redacted type='openai_key'/>" …
```

When a payload contains a marker, the observer prompt tells the model to treat it as a placeholder and not to infer the literal value. Prompts without markers are unchanged, so redaction adds no tokens when it finds nothing.

## Enable it

Add to `~/.claude-mem/settings.json`:

```json theme={null}
{
  "CLAUDE_MEM_REDACT_ENABLED": "true"
}
```

That is all you need for the 11 built-in patterns to kick in. Add `"CLAUDE_MEM_REDACT_GENERIC_ENABLED": "true"` to also turn on the 3 [generic patterns](#generic-patterns).

## Built-in patterns

| Name | Catches |
| - | - |
| `aws_access_key` | `AKIA…` (16 trailing alphanumerics) |
| `aws_secret_key` | 40-char base64 anchored to `AWS_SECRET_ACCESS_KEY=…` (shell / yaml style — see [limitations](#limits)) |
| `github_pat` | `ghp_…`, `ghs_…`, `github_pat_…` |
| `openai_key` | `sk-…` (≥20 chars) |
| `anthropic_key` | `sk-ant-…` (≥20 chars) |
| `slack_token` | `xoxb-…`, `xoxp-…`, `xoxa-…`, `xoxr-…`, `xoxs-…` |
| `jwt` | `eyJ…[.]eyJ…[.]…` three-segment tokens |
| `private_key_pem` | `-----BEGIN [RSA\|DSA\|EC\|OPENSSH\|PGP\|]PRIVATE KEY-----` blocks |
| `stripe_key` | `sk_live_…`, `pk_live_…`, `rk_test_…` |
| `google_api_key` | `AIza…` (35 trailing chars) |
| `claude_mem_key` | claude-mem's own server API keys (`cmem_…`) and cmem.ai Pro memory keys (`cm_pro_…`) |

## Generic patterns

Credentials without a vendor prefix (a database password, an internal token) need a lower-confidence match on the key name. These three patterns are off until you opt in:

```json theme={null}
{
  "CLAUDE_MEM_REDACT_ENABLED": "true",
  "CLAUDE_MEM_REDACT_GENERIC_ENABLED": "true"
}
```

| Name | Catches |
| - | - |
| `generic_password` | values assigned to a `password` / `passwd` key or a `*_PWD` key (`DB_PASSWORD=…`, `MYSQL_PWD=…`), in shell, yaml or JSON style |
| `generic_token` | values assigned to a `*_TOKEN` / `*_SECRET` / `*_API_KEY` key (e.g. `AUTH_TOKEN=…`, `"client_secret": "…"`) |
| `bearer_token` | the value after `Authorization: Bearer …` |

They run **after** every vendor pattern, so a vendor-shaped value (a `sk-…` key, a JWT, …) keeps its specific marker. To keep false positives away they only fire when the value is 8+ characters, contains at least one letter, and consists solely of secret-typical characters — so `max_tokens=4096`, short PINs, purely numeric values and the `PWD` / `OLDPWD` working-directory variables are left alone. In server-runtime event bodies, a string value under a credential-named key (`client_secret`, `db_password`, `token`, …) is redacted whole. Like every built-in, each can be disabled by name.

## Disable a single built-in

```json theme={null}
{
  "CLAUDE_MEM_REDACT_ENABLED": "true",
  "CLAUDE_MEM_REDACT_DISABLED_BUILTINS": "jwt,slack_token"
}
```

CSV format. The other built-ins stay active.

## Add a custom pattern

```json theme={null}
{
  "CLAUDE_MEM_REDACT_ENABLED": "true",
  "CLAUDE_MEM_REDACT_CUSTOM_PATTERNS": "[{\"name\":\"company_internal_token\",\"regex\":\"INTERNAL-[A-Z0-9]{32}\"}]"
}
```

`name` is required and surfaces in the `<redacted type='...'/>` marker. Custom patterns are evaluated **before** built-ins, so you can override the built-in detection for a specific token family.

If your regex fails to compile or your JSON is malformed, claude-mem logs a warning and skips the broken entry — the rest keep working.

## Diagnostic logging

```json theme={null}
{
  "CLAUDE_MEM_REDACT_LOG_MATCHES": "true"
}
```

Writes a `pattern,count` line per invocation to the worker log. The original matched bytes are never logged.

## Limits

* **Fails closed on huge fields**: a single field over about 1M characters (UTF-16 code units) is replaced whole by `<redacted type='oversize'/>` rather than stored unscanned, and a warning is logged. There is no cap on the number of matches: every match is redacted.
* **`aws_secret_key` shape**: the lookbehind only anchors `KEY=val` (shell) and `KEY: val` (yaml) styles. JSON-style `"AWS_SECRET_ACCESS_KEY": "value"` is **not** matched because the lookbehind expects `=` or `:` directly after the key name. If you commonly handle JSON config, write a custom pattern for it. (The generic built-ins do anchor JSON-style keys, but only the `password`/`*_TOKEN`/`*_SECRET`/`*_API_KEY` families.)
* **Coverage gap**: Built-ins do not cover Azure / GCP service-account JSON / IBM Cloud / private IDC tokens — use custom patterns for those.
* **Unreadable settings.json**: if the file stops parsing (for example after a bad hand edit) while redaction is on, claude-mem keeps redacting, with the last configuration that loaded or the built-in patterns, and logs a warning. It does not fall back to the default (off). Repair the file to change the configuration, or set `CLAUDE_MEM_REDACT_ENABLED=false` in the environment to turn redaction off.
* **Server-beta scope**: in multi-tenant `server-beta` deployments, the redaction config is currently read from the worker's local `~/.claude-mem/settings.json` rather than from tenant-scoped settings. For team deployments, configure redaction at the worker level. A future change will source tenant-scoped redaction config.
* **Destructive**: this is destructive replacement, not encryption. Redacted bytes cannot be recovered. If you need reversible protection, use the `<private>` tag and keep the secrets out of the conversation entirely.

## Comparison with `<private>` tags

| | `<private>` (manual) | Auto-redaction |
| - | - | - |
| **Trigger** | User wraps `<private>...</private>` | Regex match anywhere in content |
| **Granularity** | Whole block dropped | Inline placeholder, surroundings kept |
| **Default** | Always on (no setting) | Off until you opt in |
| **Use when** | You know up front the content is sensitive | You want a safety net for accidental token leaks |

Both can be used together — `<private>` blocks are removed first, then auto-redaction scans what remains, so a wrapped `<private>` block has its content removed entirely regardless of what's inside.


# Claude Desktop MCP
Source: https://docs.claude-mem.ai/usage/claude-desktop

Use claude-mem memory search in Claude Desktop with MCP tools

<Note>
  **Availability:** Claude-mem MCP tools work with Claude Desktop on macOS and Windows.
</Note>

## Overview

Claude Desktop can access your claude-mem memory database through **MCP tools**. This allows you to search past sessions, decisions, and observations directly from Claude Desktop conversations.

## Prerequisites

Before configuring MCP tools, ensure:

1. **claude-mem is installed** and the worker service is running
2. **MCP server is configured** in Claude Desktop (uses the `mcp-search` MCP server)

### Verify Worker is Running

```bash theme={null}
WORKER_PORT=$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json)
curl http://127.0.0.1:$WORKER_PORT/api/health
# Should return: {"status":"ok"}
```

## Installation

### Step 1: Configure MCP Server

The skill requires the `mcp-search` MCP server. Add this to your Claude Desktop configuration:

<Tabs>
  <Tab title="macOS">
    Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "mcp-search": {
          "command": "node",
          "args": [
            "/Users/YOUR_USERNAME/.claude/plugins/marketplaces/thedotmack/plugin/scripts/mcp-server.cjs"
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windows">
    Edit `%APPDATA%\Claude\claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "mcp-search": {
          "command": "node",
          "args": [
            "C:\\Users\\YOUR_USERNAME\\.claude\\plugins\\marketplaces\\thedotmack\\plugin\\scripts\\mcp-server.cjs"
          ]
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Warning>
  Replace `YOUR_USERNAME` with your actual username. Restart Claude Desktop after editing the configuration.
</Warning>

### Step 2: Restart Claude Desktop

Close and reopen Claude Desktop for the MCP server configuration to take effect.

## Usage

Once installed, the skill auto-activates when you ask about past work:

```
"What did we do last session?"
"Did we fix this bug before?"
"How did we implement authentication?"
"What decisions did we make about the API?"
"Show me changes to worker-service.ts"
```

## Available MCP Tools

The skill provides three core MCP tools following a 3-layer workflow pattern:

| Tool | Description |
| - | - |
| `search` | Search memory index. Returns compact results with IDs for filtering |
| `timeline` | Get chronological context around a query or observation ID |
| `get_observations` | Fetch full observation details by ID (use after filtering with search/timeline) |

### Token-Efficient Workflow

1. **Search** → Get index with IDs (\~50-100 tokens/result)
2. **Timeline** → Get context around interesting results
3. **Get Observations** → Fetch full details ONLY for filtered IDs

This 3-layer approach provides \~10x token savings compared to fetching full details upfront.

## Troubleshooting

### Skill Not Appearing

1. Verify the zip file was properly installed
2. Check Claude Desktop's skill installation logs
3. Restart Claude Desktop

### MCP Server Connection Failed

1. Verify the worker is running: `curl http://127.0.0.1:$WORKER_PORT/api/health`
2. Check the MCP server path in configuration
3. Look for errors in Claude Desktop logs

<Tabs>
  <Tab title="macOS">
    ```bash theme={null}
    # View Claude Desktop logs
    tail -f ~/Library/Logs/Claude/claude.log
    ```
  </Tab>

  <Tab title="Windows">
    Check `%APPDATA%\Claude\logs\`
  </Tab>
</Tabs>

### Search Returns No Results

1. Ensure claude-mem has recorded sessions (check [http://127.0.0.1:\$WORKER\_PORT](http://127.0.0.1:\$WORKER_PORT))
2. Verify the database exists: `ls ~/.claude-mem/claude-mem.db`
3. Test the API directly: `curl "http://127.0.0.1:$WORKER_PORT/api/search?query=test"`

## Related

<CardGroup>
  <Card title="Search Tools" icon="magnifying-glass" href="/usage/search-tools">
    Complete search API reference
  </Card>

  <Card title="Platform Integration" icon="plug" href="/platform-integration">
    Build custom integrations
  </Card>
</CardGroup>


# Memory Export/Import
Source: https://docs.claude-mem.ai/usage/export-import

Share knowledge across claude-mem installations with duplicate prevention

# Memory Export/Import Scripts

Share your claude-mem knowledge with other users! These scripts allow you to export specific memories (observations, sessions, summaries, and prompts) and import them into another claude-mem installation.

## Use Cases

* **Share Windows compatibility knowledge** with Windows users
* **Share bug fix patterns** with contributors
* **Share project-specific learnings** across teams
* **Backup specific memory sets** for safekeeping

## How It Works

### Export Script

Searches the database using **hybrid search** (combines ChromaDB vector embeddings with FTS5 full-text search) and exports all matching:

* **Observations** - Individual learnings and discoveries
* **Sessions** - Session metadata
* **Summaries** - Session summaries
* **Prompts** - User prompts that led to the work

Output is a portable JSON file that can be shared.

> **Privacy Note:** Export files contain all matching memory data in plain text. Review exports before sharing to ensure no sensitive information (API keys, passwords, private paths) is included.

### Import Script

Imports memories with **duplicate prevention**:

* Checks if each record already exists before inserting
* Skips duplicates automatically
* Maintains data integrity with transactional imports
* Reports what was imported vs. skipped

When a session already exists in the destination installation, its local title,
prompt, and registered memory session ID are retained. New observations and
summaries from the export attach to that existing session. If it has no memory
session ID yet, the import registers the exported ID before adding those memories.
Re-importing the same export still skips the memories already restored.

**Duplicate Detection Strategy:**

* **Sessions**: By `claude_session_id` (unique)
* **Summaries**: By `sdk_session_id` (unique)
* **Observations**: By `sdk_session_id` + `title` + `created_at_epoch` (composite)
* **Prompts**: By `claude_session_id` + `prompt_number` (composite)

## Usage

### Export Memories

```bash theme={null}
# Export all Windows-related memories
npx tsx scripts/export-memories.ts "windows" windows-memories.json

# Export bug fixes
npx tsx scripts/export-memories.ts "bugfix" bugfixes.json

# Export specific feature work
npx tsx scripts/export-memories.ts "progressive disclosure" progressive-disclosure.json
```

**Parameters:**

1. `<query>` - Search query (uses hybrid semantic + full-text search)
2. `<output-file>` - Output JSON file path
3. `--project=name` - Optional: filter results to a specific project

**Example Output:**

```
🔍 Searching for: "windows"
✅ Found 54 observations
✅ Found 12 sessions
✅ Found 12 summaries
✅ Found 7 prompts

📦 Export complete!
📄 Output: windows-memories.json
📊 Stats:
   • 54 observations
   • 12 sessions
   • 12 summaries
   • 7 prompts
```

### Import Memories

```bash theme={null}
# Import from an export file
npx tsx scripts/import-memories.ts windows-memories.json
```

**Parameters:**

1. `<input-file>` - Input JSON file (from export script)

**Example Output:**

```
📦 Import file: windows-memories.json
📅 Exported: 2025-12-10T23:45:00.000Z
🔍 Query: "windows"
📊 Contains:
   • 54 observations
   • 12 sessions
   • 12 summaries
   • 7 prompts

🔄 Importing sessions...
   ✅ Imported: 12, Skipped: 0
🔄 Importing summaries...
   ✅ Imported: 12, Skipped: 0
🔄 Importing observations...
   ✅ Imported: 54, Skipped: 0
🔄 Importing prompts...
   ✅ Imported: 7, Skipped: 0

✅ Import complete!
📊 Summary:
   Sessions:     12 imported, 0 skipped
   Summaries:    12 imported, 0 skipped
   Observations: 54 imported, 0 skipped
   Prompts:      7 imported, 0 skipped
```

### Re-importing (Duplicate Prevention)

If you run the import again on the same file, duplicates are automatically skipped:

```
🔄 Importing sessions...
   ✅ Imported: 0, Skipped: 12  ← All skipped (already exist)
🔄 Importing summaries...
   ✅ Imported: 0, Skipped: 12
🔄 Importing observations...
   ✅ Imported: 0, Skipped: 54
🔄 Importing prompts...
   ✅ Imported: 0, Skipped: 7
```

## Sharing Memories

### For Export Authors

1. **Export your memories:**
   ```bash theme={null}
   npx tsx scripts/export-memories.ts "windows" windows-memories.json
   ```

2. **Share the JSON file** via:
   * GitHub gist
   * Project repository (`shared-memories/`)
   * Direct file transfer
   * Package in releases

3. **Document what's included:**
   * What query was used
   * What knowledge is contained
   * Who might benefit from it

### For Import Users

1. **Download the export file** to your local machine

2. **Review what's in it** (optional):
   ```bash theme={null}
   cat windows-memories.json | jq '.totalObservations, .totalSessions'
   ```

3. **Import into your database:**
   ```bash theme={null}
   npx tsx scripts/import-memories.ts windows-memories.json
   ```

4. **Verify import** by searching:
   ```bash theme={null}
   WORKER_PORT=$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json)
   curl "http://127.0.0.1:$WORKER_PORT/api/search?query=windows&format=index&limit=10"
   ```

## JSON Export Format

```json theme={null}
{
  "exportedAt": "2025-12-10T23:45:00.000Z",
  "exportedAtEpoch": 1733876700000,
  "query": "windows",
  "totalObservations": 54,
  "totalSessions": 12,
  "totalSummaries": 12,
  "totalPrompts": 7,
  "observations": [ /* array of observation objects */ ],
  "sessions": [ /* array of session objects */ ],
  "summaries": [ /* array of summary objects */ ],
  "prompts": [ /* array of prompt objects */ ]
}
```

## Safety Features

✅ **Duplicate Prevention** - Won't re-import existing records
✅ **Transactional** - All-or-nothing imports (database stays consistent)
✅ **Read-only Export** - Export script opens database in read-only mode
✅ **Dependency Ordering** - Sessions imported before observations/summaries
✅ **Validation** - Checks database exists before starting

## Advanced Usage

### Export by Project

```bash theme={null}
# Export only claude-mem project memories
npx tsx scripts/export-memories.ts "bugfix" bugfixes.json --project=claude-mem

# Export all memories for a specific project
npx tsx scripts/export-memories.ts "" all-project.json --project=my-app
```

### Export by Type

```bash theme={null}
# Export only discoveries
npx tsx scripts/export-memories.ts "type:discovery" discoveries.json

# Export only bug fixes
npx tsx scripts/export-memories.ts "type:bugfix" bugfixes.json
```

### Export by Date Range

You can filter the export after exporting:

```bash theme={null}
# Export all memories, then filter manually with jq
npx tsx scripts/export-memories.ts "" all-memories.json
cat all-memories.json | jq '.observations |= map(select(.created_at_epoch > 1700000000000))' > recent-memories.json
```

### Combine Multiple Exports

```bash theme={null}
# Export different topics
npx tsx scripts/export-memories.ts "windows" windows.json
npx tsx scripts/export-memories.ts "linux" linux.json

# Import both
npx tsx scripts/import-memories.ts windows.json
npx tsx scripts/import-memories.ts linux.json
```

## Troubleshooting

### Database Not Found

```
❌ Database not found at: /Users/you/.claude-mem/claude-mem.db
```

**Solution:** Make sure claude-mem is installed and has been run at least once.

### Import File Not Found

```
❌ Input file not found: windows-memories.json
```

**Solution:** Check the file path. Use absolute paths if needed.

### Partial Import

If import fails mid-way, the transaction is rolled back - your database remains unchanged. Fix the issue and try again.

## Contributing Memory Sets

If you've exported valuable knowledge that others might benefit from:

1. Create a PR to the `shared-memories/` directory
2. Include a README describing what's in the export
3. Tag with relevant keywords (windows, linux, bugfix, etc.)
4. Community members can then import your knowledge!

## Examples of Useful Exports

**Windows Compatibility Knowledge:**

```bash theme={null}
npx tsx scripts/export-memories.ts "windows compatibility installation" windows-fixes.json
```

**Progressive Disclosure Architecture:**

```bash theme={null}
npx tsx scripts/export-memories.ts "progressive disclosure architecture token" pd-patterns.json
```

**Bug Fix Patterns:**

```bash theme={null}
npx tsx scripts/export-memories.ts "bugfix error handling" bugfix-patterns.json
```

**Performance Optimization:**

```bash theme={null}
npx tsx scripts/export-memories.ts "performance optimization caching" perf-tips.json
```


# Folder Context Files
Source: https://docs.claude-mem.ai/usage/folder-context

Automatic per-folder CLAUDE.md files that provide directory-level context to Claude

## Overview

Claude-mem automatically generates `CLAUDE.md` files in your project folders to provide Claude with directory-level context. These files contain a summary of recent activity in each folder, helping Claude understand what work has been done and where.

<Info>
  This feature is **disabled by default**. Enable it via settings if you want automatic folder-level context generation.
</Info>

## How It Works

When you work with Claude Code in a project, claude-mem tracks which files are read and modified. After each observation is saved, it automatically:

1. Identifies unique folder paths from touched files
2. Queries recent observations relevant to each folder
3. Generates a formatted timeline of activity
4. Writes it to `CLAUDE.md` in that folder (inside `<claude-mem-context>` tags)

### What Gets Generated

Each folder's `CLAUDE.md` contains a "Recent Activity" section showing:

* Observation IDs for reference
* Timestamps of when work occurred
* Type indicators (bug fixes, features, discoveries, etc.)
* Brief titles describing the work
* Estimated token counts

```markdown theme={null}
<claude-mem-context>
# Recent Activity

### Jan 4, 2026

| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #1234 | 4:30 PM | 🔵 | Implemented user authentication | ~250 |
| #1235 | " | 🔴 | Fixed login redirect bug | ~180 |
</claude-mem-context>
```

### User Content Preservation

The auto-generated content is wrapped in `<claude-mem-context>` tags. **Any content you write outside these tags is preserved** when the file is regenerated. This means you can:

* Add your own documentation above or below the generated section
* Write folder-specific instructions for Claude
* Include architectural notes or conventions

```markdown theme={null}
# Authentication Module

This folder contains all authentication-related code.
Follow the established patterns for new auth providers.

<claude-mem-context>
... auto-generated content ...
</claude-mem-context>

## Manual Notes

- OAuth providers go in /providers/
- Session handling uses Redis
```

### Project Root Exclusion

The **project root** (folders containing a `.git` directory) is **excluded** from auto-generation. This is intentional:

* Root `CLAUDE.md` files typically contain project-wide instructions you've written manually
* Auto-generating at the root could overwrite important project documentation
* Subfolders are where folder-level context is most useful

<Note>
  Git submodules (which have a `.git` *file* instead of directory) are correctly detected and **not** excluded, so they receive auto-generated context.
</Note>

## Configuration

### Enabling the Feature

To enable folder CLAUDE.md generation, edit your settings file:

**1. Open `~/.claude-mem/settings.json`**

**2. Add or update this setting:**

```json theme={null}
{
  "CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED": "true"
}
```

**3. Save the file** - changes take effect immediately (no restart needed)

| Value | Behavior |
| - | - |
| `"false"` (default) | Folder CLAUDE.md generation disabled |
| `"true"` | Auto-generate folder CLAUDE.md files |

<Tip>
  If the settings file doesn't exist, create it with just the settings you want to change. Claude-mem will use defaults for any missing settings.
</Tip>

## Cleanup Mode

The regenerate script includes a `--clean` mode for removing auto-generated content:

```bash theme={null}
# Preview what would be cleaned (dry run)
bun scripts/regenerate-claude-md.ts --clean --dry-run

# Actually clean files
bun scripts/regenerate-claude-md.ts --clean
```

**What cleanup does:**

1. Finds all `CLAUDE.md` files recursively
2. Strips `<claude-mem-context>...</claude-mem-context>` sections
3. **Deletes** files that become empty after stripping
4. **Preserves** files that have user content outside the tags

This is useful for:

* Preparing a branch for PR (removing generated files)
* Resetting folder context to start fresh
* Removing context before sharing code

## Git Integration

### Should You Commit These Files?

This is **your choice** based on your workflow. Here are the trade-offs:

<Tabs>
  <Tab title="Commit Them">
    **Pros:**

    * Team members see folder-level context and recent activity
    * New contributors can understand what happened where
    * Code reviewers get additional context about changes
    * Historical record of work patterns in the repo

    **Cons:**

    * Adds files to your repository
    * Files change frequently during development
    * May create noise in diffs and commit history
    * Different team members may generate different content
  </Tab>

  <Tab title="Gitignore Them">
    **Pros:**

    * Clean repository without generated files
    * No commit noise from auto-generated content
    * Each developer has their own local context
    * Simpler git history

    **Cons:**

    * Team doesn't share folder context
    * Context is lost when switching machines
    * New team members don't benefit from existing context
  </Tab>
</Tabs>

### Gitignore Pattern

To exclude folder CLAUDE.md files from git:

```gitignore theme={null}
# Ignore auto-generated folder context files
**/CLAUDE.md

# But keep the root CLAUDE.md if you want
!CLAUDE.md
```

Or to ignore all CLAUDE.md files everywhere:

```gitignore theme={null}
**/CLAUDE.md
```

### Recommended Workflows

**For Solo Developers:**

* Keep them local (gitignore) for personal context
* Or commit them if you work across multiple machines

**For Teams:**

* Discuss with your team which approach works best
* Consider committing them if onboarding is frequent
* Use `--clean` before PRs if you prefer clean diffs

**Before Merging PRs:**

```bash theme={null}
# Clean up generated files before merge
bun scripts/regenerate-claude-md.ts --clean
git add -A
git commit -m "chore: clean up generated CLAUDE.md files"
```

## Regenerating Context

To manually regenerate all folder CLAUDE.md files from the database:

```bash theme={null}
# Preview what would be regenerated
bun scripts/regenerate-claude-md.ts --dry-run

# Regenerate all folders
bun scripts/regenerate-claude-md.ts

# Regenerate for a specific project only
bun scripts/regenerate-claude-md.ts --project=my-project
```

This is useful after:

* Importing observations from another machine
* Database recovery
* Wanting to refresh all folder context

## Worktree Support

**New in v9.0**: Claude-mem now supports git worktrees with unified context.

When you're working in a git worktree, context is automatically gathered from both:

* The parent repository (where the worktree was created)
* The worktree directory itself

This means observations about shared code are visible regardless of which worktree you're in, giving you a complete picture of recent activity across all related directories.

### How It Works

1. When generating context, claude-mem detects if your project is a worktree
2. It identifies the parent repository automatically
3. Timeline queries include both locations
4. Results are interleaved chronologically

<Note>
  No configuration needed - worktree detection is automatic. If you're not using worktrees, this feature has no effect.
</Note>

## Technical Details

### File Format

Generated content uses a consistent markdown table format:

| Column | Description |
| - | - |
| ID | Observation ID (e.g., `#1234`) or session ID (`#S123`) |
| Time | 12-hour format with AM/PM, ditto marks (`"`) for repeated times |
| T | Type emoji indicator |
| Title | Brief description of the observation |
| Read | Estimated token count (e.g., `~250`) |

### Type Indicators

| Emoji | Type |
| - | - |
| 🔴 | Bug fix |
| 🟣 | Feature |
| 🔄 | Refactor |
| ✅ | Change |
| 🔵 | Discovery |
| ⚖️ | Decision |
| 🎯 | Session |
| 💬 | Prompt |

### Atomic Writes

Files are written atomically using a temp file + rename pattern. This prevents partial writes if the process is interrupted.

### Performance

* Updates happen asynchronously (fire-and-forget)
* Failures are logged but don't block the main workflow
* Only folders with actual file activity are updated
* Deduplication prevents redundant updates for the same folder


# Gemini Provider
Source: https://docs.claude-mem.ai/usage/gemini-provider

Use Google's Gemini API as an alternative to Claude for observation extraction

# Gemini Provider

Claude-mem supports Google's Gemini API as an alternative to the Claude Agent SDK for extracting observations from your sessions. Memory runs off-plan on your Gemini key, so observation extraction never shares your Claude plan usage.

<Warning>
  **Rate limits without billing**: Gemini applies model-specific limits to projects without billing. Enable billing on your Google Cloud project for higher limits, and review Google's current quota and billing terms before doing so.
</Warning>

## Why Use Gemini?

* **Runs off-plan**: Observation extraction happens on your Gemini key, not your Claude plan
* **Same quality**: Gemini extracts observations using the same XML format as Claude
* **Errors throw clearly**: 429s, 5xx, and network failures throw — leaving messages pending so they can be retried
* **Hot-swappable**: Switch providers without restarting the worker

## Getting an API Key

1. Go to the [Google AI Studio API Key page](https://aistudio.google.com/app/apikey)
2. Sign in with your Google account
3. Accept the Terms of Service and privacy policies
4. Click the **Create API key** button
5. Choose a Google Cloud project or create a new one
6. Copy and securely store the generated API key

<Tip>
  **No billing required** to get started. Enabling billing can unlock higher rate limits; review Google's current quota and billing terms first.
</Tip>

## Configuration

### Settings

| Setting | Values | Default | Description |
| - | - | - | - |
| `CLAUDE_MEM_PROVIDER` | `claude`, `codex`, `gemini`, `openrouter`, `openai-compatible` | `claude` | AI provider for observation extraction |
| `CLAUDE_MEM_GEMINI_API_KEY` | string | — | Your Gemini API key |
| `CLAUDE_MEM_GEMINI_API_KEYS` | newline- or comma-separated keys | — | Extra keys to rotate through when one is rate-limited or spent ([Multi-Key Rotation](/usage/multi-key-rotation)) |
| `CLAUDE_MEM_GEMINI_MODEL` | `gemini-flash-latest`, `gemini-flash-lite-latest`, `gemini-3.5-flash`, `gemini-3.1-flash-lite`, `gemini-3-flash-preview` | `gemini-flash-latest` | Gemini model to use |
| `CLAUDE_MEM_GEMINI_RATE_LIMITING_ENABLED` | `true`, `false` | `true` | Pace requests to the model's no-billing RPM. Set `false` once billing is enabled on Google Cloud |

### Using the Settings UI

1. Open the worker URL printed on startup
2. Click the **gear icon** to open Settings
3. Under **AI Provider**, select **Gemini**
4. Enter your Gemini API key
5. Optionally select a different model

Settings are applied immediately—no restart required.

### Manual Configuration

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

```json theme={null}
{
  "CLAUDE_MEM_PROVIDER": "gemini",
  "CLAUDE_MEM_GEMINI_API_KEY": "your-api-key-here",
  "CLAUDE_MEM_GEMINI_MODEL": "gemini-flash-latest",
  "CLAUDE_MEM_GEMINI_RATE_LIMITING_ENABLED": "true"
}
```

Alternatively, set the API key via environment variable:

```bash theme={null}
export GEMINI_API_KEY="your-api-key-here"
```

The settings file takes precedence over the environment variable.

## Available Models

| Model | RPM without billing | Notes |
| - | - | - |
| `gemini-flash-latest` | 10 | **Default.** Google alias that always tracks the current GA Flash model |
| `gemini-flash-lite-latest` | 15 | Google alias that always tracks the current GA Flash-Lite model |
| `gemini-3.5-flash` | 10 | Pinned GA Flash model |
| `gemini-3.1-flash-lite` | 15 | Pinned GA Flash-Lite model |
| `gemini-3-flash-preview` | 5 | Preview model, lower rate limit |

<Note>
  The older `gemini-2.5-*` and `gemini-2.0-*` model IDs were removed: Google returns `404 NOT_FOUND` ("no longer available to new users") for these when called with a freshly created API key. The `-latest` aliases are recommended because they never go stale as Google rotates GA models.
</Note>

## Provider Switching

You can switch between Claude and Gemini at any time:

* **No restart required**: Changes take effect on the next observation
* **Conversation history preserved**: When switching mid-session, the new provider sees the full conversation context
* **Seamless transition**: Both providers use the same observation format

### Switching via UI

1. Open Settings in the viewer
2. Change the **AI Provider** dropdown
3. The next observation will use the new provider

### Switching via Settings File

```json theme={null}
{
  "CLAUDE_MEM_PROVIDER": "gemini"
}
```

## Error Behavior

When Gemini refuses a request, queued observations stay pending; what happens next depends on the refusal:

* **Per-minute throttle** (a 429 whose quota is per minute): claude-mem waits the delay Google names and resumes. If the throttle keeps refusing, Gemini is held for 90 seconds.
* **Spent daily (or weekly, monthly) quota** (a 429 naming a per-day quota): Gemini is held for 30 minutes, then one request checks whether the quota has reset.
* **Region not served** ("User location is not supported"): capture pauses with the work kept, and the next session start says to switch providers. Gemini is re-checked once every 30 minutes. Extra keys are not tried, since every key gets the same answer.
* **Invalid or revoked key**: with extra keys configured, the next key is tried; otherwise the same pause, and the notice says to fix the key.
* **Server errors and network faults**: paused with the work kept, then resumed automatically on a backoff.
* **Other malformed requests** (HTTP 400): that session's pending observations are dropped. A request too long for the model's window retires the conversation instead and keeps them.

To keep capturing while Gemini is held, configure a [quota fallback](/usage/quota-fallback) (opt-in, off by default). Extra keys rotate within Gemini ([Multi-Key Rotation](/usage/multi-key-rotation)). To switch providers for good, change `CLAUDE_MEM_PROVIDER`.

## Troubleshooting

### "Gemini API key not configured"

Either:

* Set `CLAUDE_MEM_GEMINI_API_KEY` in `~/.claude-mem/settings.json`, or
* Set the `GEMINI_API_KEY` environment variable

### Rate Limiting

Google applies different rate limits depending on whether billing is enabled:

**Without billing (API key only):**

| Model | RPM | TPM |
| - | - | - |
| gemini-flash-latest / gemini-3.5-flash | 10 | 250K |
| gemini-flash-lite-latest / gemini-3.1-flash-lite | 15 | 250K |
| gemini-3-flash-preview | 5 | 250K |

Claude-mem enforces these limits automatically with built-in delays between requests. Processing may be slower but stays within limits.

**With billing enabled:**

| Model | RPM | TPM |
| - | - | - |
| gemini-flash-lite-latest / gemini-3.1-flash-lite | 4,000 | 4M |
| gemini-flash-latest / gemini-3.5-flash | 1,000 | 1M |
| gemini-3-flash-preview | 1,000 | 1M |

<Tip>
  **Higher throughput**: Enabling billing can unlock much higher rate limits. Review your Google Cloud quota and billing settings first. Claude-mem can then use the higher configured limits instead of its conservative no-billing throttle.
</Tip>

If you hit rate limits:

* The pending observations stay queued and resume when the limit resets (see [Error Behavior](#error-behavior))
* Or configure a [quota fallback](/usage/quota-fallback), or switch back to Claude as your primary provider

### Observation Quality

If observations seem lower quality with Gemini:

* Note that Claude typically produces slightly higher quality observations
* Consider using Gemini to keep memory off-plan and Claude for important projects

## Next Steps

* [Configuration](/configuration) - Full settings reference
* [Getting Started](/usage/getting-started) - Basic usage guide
* [Troubleshooting](/troubleshooting) - Common issues

## Multiple keys

`CLAUDE_MEM_GEMINI_API_KEYS` accepts additional keys (newline- or comma-separated) alongside
`CLAUDE_MEM_GEMINI_API_KEY`. When a key hits a rate limit, spends its quota, or is rejected as
invalid, Gemini requests rotate to the next key instead of failing for the
rest of the window. See [Multi-Key Rotation](/usage/multi-key-rotation).


# Getting Started
Source: https://docs.claude-mem.ai/usage/getting-started

Learn how Claude-Mem works automatically in the background

# Getting Started with Claude-Mem

## Automatic Operation

Claude-Mem works automatically once installed. No manual intervention required!

### The Full Cycle

1. **Start Claude Code** - Context from last 10 sessions appears automatically
2. **Work normally** - Every tool execution is captured
3. **Claude finishes responding** - Stop hook automatically generates and saves a summary
4. **Next session** - Previous work appears in context

### What Gets Captured

Every time Claude uses a tool, claude-mem captures it:

* **Read** - File reads and content access
* **Write** - New file creation
* **Edit** - File modifications
* **Bash** - Command executions
* **Glob** - File pattern searches
* **Grep** - Content searches
* And all other Claude Code tools

### What Gets Processed

The worker service processes tool observations and extracts:

* **Title** - Brief description of what happened
* **Subtitle** - Additional context
* **Narrative** - Detailed explanation
* **Facts** - Key learnings as bullet points
* **Concepts** - Relevant tags and categories
* **Type** - Classification (decision, bugfix, feature, etc.)
* **Files** - Which files were read or modified

### Session Summaries

When Claude finishes responding (triggering the Stop hook), a summary is automatically generated with:

* **Request** - What you asked for
* **Investigated** - What Claude explored
* **Learned** - Key discoveries and insights
* **Completed** - What was accomplished
* **Next Steps** - What to do next
* **Notes** - Anything else worth keeping

### Context Injection

When you start a new Claude Code session, the SessionStart hook:

1. Queries the database for recent observations in your project (default: 50)
2. Retrieves recent session summaries for context
3. Displays observations in a chronological timeline with session markers
4. Shows full summary details (Investigated, Learned, Completed, Next Steps, Notes) **only if the summary was generated after the last observation**
5. Injects formatted context into Claude's initial context

**Summary Display Logic:**

The most recent summary's full details appear at the end of the context display **only when** the summary was generated after the most recent observation. This ensures you see summary details when they represent the latest state of your project, but not when new observations have been captured since the last summary.

For example:

* ✅ **Shows summary**: Last observation at 2:00 PM, summary generated at 2:05 PM → Summary details appear
* ❌ **Hides summary**: Summary generated at 2:00 PM, new observation at 2:05 PM → Summary details hidden (outdated)

This prevents showing stale summaries when new work has been captured but not yet summarized.

This means Claude "remembers" what happened in previous sessions!

## Manual Commands (Optional)

### Worker Management

The worker auto-starts on the first SessionStart hook, so you usually don't need these commands. They're handy for diagnostics.

```bash theme={null}
# Start worker service (optional - auto-starts automatically)
npm run worker:start

# Stop worker service
npm run worker:stop

# Restart worker service
npm run worker:restart

# View worker logs
npm run worker:logs

# Check worker status
npm run worker:status
```

### Testing

```bash theme={null}
# Run all tests
npm test

# Test context injection
npm run test:context

# Verbose context test
npm run test:context:verbose
```

### Development

```bash theme={null}
# Build hooks and worker
npm run build

# Build only hooks
npm run build:hooks

# Publish to NPM (maintainers only)
npm run publish:npm
```

## Viewing Stored Context

Context is stored in SQLite database at `~/.claude-mem/claude-mem.db`.

Query the database directly:

```bash theme={null}
# Open database
sqlite3 ~/.claude-mem/claude-mem.db

# View recent sessions
SELECT session_id, project, created_at, status
FROM sdk_sessions
ORDER BY created_at DESC
LIMIT 10;

# View session summaries
SELECT session_id, request, completed, learned
FROM session_summaries
ORDER BY created_at DESC
LIMIT 5;

# View observations for a session
SELECT tool_name, created_at
FROM observations
WHERE session_id = 'YOUR_SESSION_ID';
```

## Understanding Progressive Disclosure

Context injection uses progressive disclosure for efficient token usage:

### Layer 1: Index Display (Session Start)

* Shows observation titles with token cost estimates
* Displays session markers in chronological timeline
* Groups observations by file for visual clarity
* Shows full summary details **only if** generated after last observation
* Token cost: \~50-200 tokens for index view

### Layer 2: On-Demand Details (MCP Tools)

* Ask naturally: "What bugs did we fix?" or "How did we implement X?"
* Claude auto-invokes MCP search tools to fetch full details
* Search by concept, file, type, or keyword
* Timeline context around specific observations
* Token cost: \~100-500 tokens per observation fetched
* Uses 3-layer workflow: search → timeline → get\_observations

### Layer 3: Perfect Recall (Code Access)

* Read source files directly when needed
* Access original transcripts and raw data
* Full context available on-demand

This ensures efficient token usage while maintaining access to complete history when needed.

## Multi-Prompt Sessions & `/clear` Behavior

Claude-Mem supports sessions that span multiple user prompts:

* **prompt\_counter**: Tracks total prompts in a session
* **prompt\_number**: Identifies specific prompt within session
* **Session continuity**: Observations and summaries link across prompts

### Important Note About `/clear`

When you use `/clear`, the session doesn't end - it continues with a new prompt number. This means:

* ✅ **Context is re-injected** from recent sessions (SessionStart hook fires with `source: "clear"`)
* ✅ **Observations are still being captured** and added to the current session
* ✅ **A summary will be generated** when Claude finishes responding (Stop hook fires)

The `/clear` command clears the conversation context visible to Claude AND re-injects fresh context from recent sessions, while the underlying session continues tracking observations.

## Searching Your History

Claude-Mem provides MCP tools for querying your project history. Simply ask naturally:

```
"What bugs did we fix last session?"
"How did we implement authentication?"
"What changes were made to worker-service.ts?"
"Show me recent work on this project"
```

Claude automatically recognizes your intent and invokes the MCP search tools, which use a 3-layer workflow (search → timeline → get\_observations) for efficient token usage.

## Next Steps

* [Skill-Based Search](/usage/search-tools) - Learn how to search your project history
* [Architecture Overview](/architecture/overview) - Understand how it works
* [Troubleshooting](/troubleshooting) - Common issues and solutions


# Knowledge Agents
Source: https://docs.claude-mem.ai/usage/knowledge-agents

Build queryable AI brains from your observation history

# Knowledge Agents

Knowledge agents let you compile a slice of your claude-mem observation history into a **queryable "brain"** that answers questions conversationally. Instead of getting raw search results back, you get synthesized, grounded answers drawn from your actual project history -- decisions, discoveries, bugfixes, and features.

## Quick Start

Three ways to use knowledge agents, from simplest to most powerful.

### 1. Create a Knowledge Agent

Use the `/knowledge-agent` skill or the MCP tools directly:

```
build_corpus name="hooks-expertise" query="hooks architecture" project="claude-mem" limit=200
```

This searches your observation history, collects matching records, and saves them as a corpus file. Then prime it — this loads the corpus into a Claude session's context window:

```
prime_corpus name="hooks-expertise"
```

Your knowledge agent is ready. The returned `session_id` **is** the agent — a Claude session with your history baked in.

### 2. Ask a Single Question

Once primed, ask any question and get a grounded answer:

```
query_corpus name="hooks-expertise" question="What are the 5 lifecycle hooks and when does each fire?"
```

The agent answers grounded in its corpus — responses are drawn from your actual project history, reducing hallucination and guessing. Each follow-up question builds on the prior conversation:

```
query_corpus name="hooks-expertise" question="Which hook handles context injection?"
```

### 3. Start a Fresh Conversation

If the conversation drifts, or you want to ask an unrelated question against the same corpus, reprime to start clean:

```
reprime_corpus name="hooks-expertise"
```

This creates a **new session** with the full corpus reloaded — like opening a fresh chat with the same "brain." All prior Q\&A context is cleared, but the corpus knowledge remains. Use this when:

* The conversation went off-track and you want a clean slate
* You're switching topics within the same corpus
* You want to ask a question without prior answers biasing the response

### Keeping It Current

When new observations are added to your project, rebuild the corpus to pull in the latest, then reprime:

```
rebuild_corpus name="hooks-expertise"
reprime_corpus name="hooks-expertise"
```

Rebuild re-runs the original search filters. Reprime loads the refreshed data into a new session.

***

## The Workflow: Build, Prime, Query

```
BUILD  ──>  PRIME  ──>  QUERY
```

### 1. Build a Corpus

A corpus is a filtered collection of observations saved as a JSON file. Use search filters to select exactly the slice of history you want.

```bash theme={null}
WORKER_PORT=$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json)
curl -X POST http://127.0.0.1:$WORKER_PORT/api/corpus \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hooks-expertise",
    "query": "hooks architecture",
    "project": "claude-mem",
    "types": ["decision", "discovery"],
    "limit": 200
  }'
```

Under the hood, `CorpusBuilder` searches your observations, hydrates full records, parses structured fields (facts, concepts, files), calculates stats, and writes everything to `~/.claude-mem/corpora/hooks-expertise.corpus.json`.

### 2. Prime the Knowledge Agent

Priming loads the entire corpus into a Claude session's context window.

```bash theme={null}
curl -X POST http://127.0.0.1:$WORKER_PORT/api/corpus/hooks-expertise/prime
```

The agent renders all observations into full-detail text and feeds them to the Claude Agent SDK. Claude reads the corpus and acknowledges the themes. The returned `session_id` **is** the knowledge agent -- a Claude session with your history baked in.

### 3. Query

Resume the primed session and ask questions.

```bash theme={null}
curl -X POST http://127.0.0.1:$WORKER_PORT/api/corpus/hooks-expertise/query \
  -H "Content-Type: application/json" \
  -d '{ "question": "What are the 5 lifecycle hooks?" }'
```

Each follow-up question adds to the conversation naturally. If the session expires, the agent auto-reprimes from the corpus file and retries.

***

## Filter Options

Use these parameters when building a corpus to control which observations are included:

| Parameter | Type | Description |
| - | - | - |
| `name` | string | Name for the corpus (used in all subsequent API calls) |
| `project` | string | Filter by project name |
| `types` | string\[] | Filter by observation type (bugfix, feature, decision, discovery, refactor, change) |
| `concepts` | string\[] | Filter by tagged concepts |
| `files` | string\[] | Filter by files read or modified |
| `query` | string | Full-text search query |
| `dateStart` | string | Start date filter (YYYY-MM-DD) |
| `dateEnd` | string | End date filter (YYYY-MM-DD) |
| `limit` | number | Maximum observations to include |

***

## Architecture

```
                MCP Tools                    HTTP API
            (mcp-server.ts)            (worker on :$WORKER_PORT)
                  |                          |
   build_corpus ──┤                          |
   list_corpora ──┤                          |
   prime_corpus ──┤──── callWorker() ───────>|
   query_corpus ──┤                          |
rebuild_corpus ──┤                          |
reprime_corpus ──┘                          |
                                             v
                                       CorpusRoutes
                                       (8 endpoints)
                                        /    |    \
                              CorpusBuilder  |  KnowledgeAgent
                                  |          |       |
                        SearchOrchestrator   |   Agent SDK V1
                        SessionStore         |   query() + resume
                                             |
                                        CorpusStore
                                    (~/.claude-mem/corpora/)
```

**Key insight:** The Agent SDK's `resume` option lets you prime a session once (upload the corpus), save the `session_id`, and resume it for every future question. The corpus stays in context permanently -- no re-uploading, no prompt caching tricks. The 1M token context window makes this viable: 2,000 observations at \~300 tokens each fits comfortably.

***

## When to Use `/knowledge-agent` vs `/mem-search`

| | `/mem-search` | `/knowledge-agent` |
| - | - | - |
| **Returns** | Raw observation records | Synthesized conversational answers |
| **Best for** | Finding specific observations, IDs, timelines | Asking questions about patterns, decisions, architecture |
| **Token model** | Pay-per-query (3-layer progressive disclosure) | Pay-once at prime time, then cheap follow-ups |
| **Interaction** | Search, filter, fetch | Ask questions in natural language |
| **Data freshness** | Always current (queries database live) | Snapshot at build time (rebuild to refresh) |
| **Setup** | None -- works immediately | Build + prime required before first query |

**Rule of thumb:** Use `/mem-search` when you need to find something specific. Use `/knowledge-agent` when you want to understand something broadly.

***

## API Reference

| Method | Path | Description |
| - | - | - |
| POST | `/api/corpus` | Build a new corpus from filters |
| GET | `/api/corpus` | List all corpora with stats |
| GET | `/api/corpus/:name` | Get corpus metadata |
| DELETE | `/api/corpus/:name` | Delete a corpus |
| POST | `/api/corpus/:name/rebuild` | Rebuild from stored filters |
| POST | `/api/corpus/:name/prime` | Create AI session with corpus loaded |
| POST | `/api/corpus/:name/query` | Ask the knowledge agent a question |
| POST | `/api/corpus/:name/reprime` | Fresh session (wipe prior Q\&A) |

***

## Edge Cases

* **Session expiry**: If `resume` fails, the agent auto-reprimes from the corpus file and retries
* **SDK process exit**: If the Claude process exits after yielding all messages, the agent treats it as success when the session\_id or answer was already captured
* **Empty corpus**: A corpus with 0 observations is valid (just empty)
* **Model from settings**: Reads `CLAUDE_MEM_MODEL` from user settings -- no hardcoded model IDs

## Next Steps

* [Memory Search](/usage/search-tools) - The 3-layer search workflow for finding specific observations
* [Progressive Disclosure](/progressive-disclosure) - Philosophy behind token-efficient retrieval
* [Architecture Overview](/architecture/overview) - System components


# Manual Recovery
Source: https://docs.claude-mem.ai/usage/manual-recovery

Recover stuck observations after worker crashes or restarts

# Manual Recovery Guide

## Overview

Claude-mem's manual recovery system helps you recover observations that get stuck in the processing queue after worker crashes, system restarts, or unexpected shutdowns.

**Key Change in v5.x**: Automatic recovery on worker startup is now disabled. This gives you explicit control over when reprocessing happens, preventing unexpected duplicate observations.

## When Do You Need Manual Recovery?

You should trigger manual recovery when:

* **Worker crashed or restarted** - Observations were queued but worker stopped before processing
* **No new summaries appearing** - Observations are being saved but not processed into summaries
* **Stuck messages detected** - Messages showing as "processing" for >5 minutes
* **System crashes** - Unexpected shutdowns left messages in incomplete states

## Quick Start

### Using the CLI Tool (Recommended)

The interactive CLI tool is the safest and easiest way to recover stuck observations:

```bash theme={null}
# Check status and prompt for recovery
bun scripts/check-pending-queue.ts
```

This will:

1. Check worker health
2. Show queue summary (pending, processing, failed, stuck counts)
3. Display sessions with pending work
4. Prompt you to confirm recovery
5. Show recently processed messages for feedback

### Auto-Process Without Prompts

For scripting or when you're confident recovery is needed:

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

# Limit to 5 sessions
bun scripts/check-pending-queue.ts --process --limit 5
```

## Understanding Queue States

Messages progress through these lifecycle 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:

* They're automatically reset to `pending` on worker startup
* They're NOT automatically reprocessed (requires manual trigger)
* They appear in the `stuckCount` field when checking queue status

## Recovery Methods

### Method 1: Interactive CLI Tool

**Best for**: Regular users, interactive sessions, when you want visibility into what's happening

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

**Example Output**:

```
Checking worker health...
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)
```

**Features**:

* ✅ Pre-flight health check (verifies worker is running)
* ✅ Detailed queue breakdown by session
* ✅ Age tracking for stuck detection
* ✅ Confirmation prompt (prevents accidental reprocessing)
* ✅ Non-interactive mode with `--process` flag
* ✅ Session limit control with `--limit N`

### Method 2: HTTP API

**Best for**: Automation, scripting, integration with monitoring systems

#### Check Queue Status

```bash theme={null}
WORKER_PORT=$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json)
curl http://127.0.0.1:$WORKER_PORT/api/pending-queue
```

**Response**:

```json theme={null}
{
  "queue": {
    "messages": [
      {
        "id": 123,
        "session_db_id": 45,
        "claude_session_id": "abc123",
        "message_type": "observation",
        "status": "pending",
        "retry_count": 0,
        "created_at_epoch": 1730886600000
      }
    ],
    "totalPending": 12,
    "totalProcessing": 2,
    "totalFailed": 0,
    "stuckCount": 1
  },
  "recentlyProcessed": [...],
  "sessionsWithPendingWork": [44, 45, 46]
}
```

**Key Fields**:

* `totalPending` - Messages waiting to process
* `totalProcessing` - Messages currently processing
* `stuckCount` - Processing messages >5 minutes old
* `sessionsWithPendingWork` - Session IDs needing recovery

#### Trigger Recovery

```bash theme={null}
curl -X POST http://127.0.0.1:$WORKER_PORT/api/pending-queue/process \
  -H "Content-Type: application/json" \
  -d '{"sessionLimit": 10}'
```

**Response**:

```json theme={null}
{
  "success": true,
  "totalPendingSessions": 15,
  "sessionsStarted": 10,
  "sessionsSkipped": 2,
  "startedSessionIds": [44, 45, 46, 47, 48, 49, 50, 51, 52, 53]
}
```

**Response Fields**:

* `totalPendingSessions` - Total sessions with pending messages in database
* `sessionsStarted` - Sessions we started processing this request
* `sessionsSkipped` - Sessions already processing (prevents duplicate agents)
* `startedSessionIds` - Database IDs of sessions we started

## Best Practices

### 1. Always Check Before Recovery

```bash theme={null}
# Check queue status first
curl http://127.0.0.1:$WORKER_PORT/api/pending-queue

# Or use CLI tool which checks automatically
bun scripts/check-pending-queue.ts
```

### 2. Start with Low Session Limits

```bash theme={null}
# Process only 5 sessions at a time
bun scripts/check-pending-queue.ts --process --limit 5
```

This prevents overwhelming the worker with too many concurrent SDK agents.

### 3. Monitor During Recovery

Watch worker logs while recovery runs:

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

Look for:

* SDK agent starts: `Starting SDK agent for session...`
* Processing completions: `Processed observation...`
* Errors: `ERROR` or `Failed to process...`

### 4. Verify Recovery Success

Check recently processed messages:

```bash theme={null}
curl http://127.0.0.1:$WORKER_PORT/api/pending-queue | jq '.recentlyProcessed'
```

Or use the CLI tool which shows this automatically.

### 5. Handle Failed Messages

Messages that fail 3 times are marked `failed` and won't auto-retry:

```bash theme={null}
# View failed messages
sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT id, session_db_id, message_type, retry_count
  FROM pending_messages
  WHERE status = 'failed'
  ORDER BY completed_at_epoch DESC;
"
```

You can manually reset them if needed:

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

## Troubleshooting

### Recovery Not Working

**Symptom**: Triggered recovery but messages still pending

**Solutions**:

1. **Verify worker health**:
   ```bash theme={null}
   curl http://127.0.0.1:$WORKER_PORT/health
   ```

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

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

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

### Messages Stuck Forever

**Symptom**: Messages show as "processing" for hours

**Solution**: Force reset stuck messages

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

# Then trigger recovery
bun scripts/check-pending-queue.ts --process
```

### Worker Crashes During Recovery

**Symptom**: Worker stops while processing recovered messages

**Solutions**:

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

2. **Reduce session limit**:
   ```bash theme={null}
   bun scripts/check-pending-queue.ts --process --limit 3
   ```

3. **Check for SDK errors in logs**:
   ```bash theme={null}
   npm run worker:logs | grep -i "sdk"
   ```

4. **Increase worker memory** (if using custom runner):
   ```bash theme={null}
   export NODE_OPTIONS="--max-old-space-size=4096"
   npm run worker:restart
   ```

## Advanced Usage

### Direct Database Inspection

View all pending messages:

```bash theme={null}
sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT
    id,
    session_db_id,
    message_type,
    status,
    retry_count,
    datetime(created_at_epoch/1000, 'unixepoch') as created_at,
    datetime(started_processing_at_epoch/1000, 'unixepoch') as started_at,
    CAST((strftime('%s', 'now') * 1000 - started_processing_at_epoch) / 60000 AS INTEGER) as age_minutes
  FROM pending_messages
  WHERE status IN ('pending', 'processing')
  ORDER BY created_at_epoch;
"
```

### Count Messages by Status

```bash theme={null}
sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT status, COUNT(*) as count
  FROM pending_messages
  GROUP BY status;
"
```

### Find Sessions with Pending Work

```bash theme={null}
sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT
    session_db_id,
    COUNT(*) as pending_count,
    GROUP_CONCAT(message_type) as message_types
  FROM pending_messages
  WHERE status IN ('pending', 'processing')
  GROUP BY session_db_id;
"
```

### View Recent Failures

```bash theme={null}
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;
"
```

## Integration Examples

### Cron Job for Automatic Recovery

```bash theme={null}
#!/bin/bash
# Run every hour to process stuck queues

WORKER_PORT=$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json)

# Check if worker is healthy
if curl -f http://127.0.0.1:$WORKER_PORT/health > /dev/null 2>&1; then
  # Auto-process up to 5 sessions
  bun scripts/check-pending-queue.ts --process --limit 5
else
  echo "Worker not healthy, skipping recovery"
  exit 1
fi
```

### Monitoring Script

```bash theme={null}
#!/bin/bash
# Alert if stuck count exceeds threshold

WORKER_PORT=$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json)
STUCK_COUNT=$(curl -s http://127.0.0.1:$WORKER_PORT/api/pending-queue | jq '.queue.stuckCount')

if [ "$STUCK_COUNT" -gt 5 ]; then
  echo "WARNING: $STUCK_COUNT stuck messages detected"
  # Send alert (email, Slack, etc.)
fi
```

### Pre-Shutdown Recovery

```bash theme={null}
#!/bin/bash
# Process pending queues before system shutdown

echo "Processing pending queues before shutdown..."
bun scripts/check-pending-queue.ts --process --limit 20

echo "Waiting for processing to complete..."
sleep 10

echo "Stopping worker..."
claude-mem stop
```

## Migration Note

If you're upgrading from v4.x to v5.x:

**v4.x Behavior** (Automatic Recovery):

* Worker automatically recovered stuck messages on startup
* No user control over reprocessing timing

**v5.x Behavior** (Manual Recovery):

* Stuck messages detected but NOT automatically reprocessed
* User must explicitly trigger recovery via CLI or API
* Prevents unexpected duplicate observations
* Provides explicit control over when processing happens

**Migration Steps**:

1. Upgrade to v5.x
2. Check for stuck messages: `bun scripts/check-pending-queue.ts`
3. Process if needed: `bun scripts/check-pending-queue.ts --process`
4. Add recovery to your workflow (cron job, pre-shutdown script, etc.)

## See Also

* [Worker Service Architecture](../architecture/worker-service) - Technical details on queue processing
* [Troubleshooting - Manual Recovery](../troubleshooting#manual-recovery-for-stuck-observations) - Common issues and solutions
* [Database Schema](../architecture/database) - Pending messages table structure


# Memory Ingest
Source: https://docs.claude-mem.ai/usage/memory-ingest

Import Claude Code's auto-memory markdown files directly into claude-mem as observations — no model spend

# Memory Ingest

Claude Code maintains its own **auto-memory** — markdown it distills for itself — under:

```
~/.claude/projects/<encoded-cwd>/memory/MEMORY.md   (a link-only index)
~/.claude/projects/<encoded-cwd>/memory/<topic>.md  (distilled prose, one fact per file)
```

`<encoded-cwd>` is the repo's absolute path with every character other than a
letter or digit replaced by `-` (e.g. `/home/you/code/my_app` →
`-home-you-code-my-app`). Claude Code cuts a name longer than 200 characters to
200 and ends it with a short hash.

`claude-mem memory ingest` imports those topic files **directly** into your
memory database as observations.

## Why it doesn't cost anything

Auto-memory is **already distilled** — each topic file is the same *kind* of
artifact the observation generator produces. So memory-ingest does **not** run
the Haiku generation pipeline. It stores each file's prose directly through
claude-mem's existing observation seam (content-hash dedup + Chroma sync).
Re-running generation on already-distilled prose would be lossy and pay for
negative value.

The `MEMORY.md` index is skipped — it's just links and carries no knowledge of
its own.

## Usage

Always **dry-run first** — it's a zero-spend, DB-free scan + count:

```bash theme={null}
# Scan the current repo's memory dir and report what would be stored
npx claude-mem memory ingest --dry-run

# Sweep every project under ~/.claude/projects/*/memory/
npx claude-mem memory ingest --all --dry-run
```

Then run the real ingest:

```bash theme={null}
# Ingest the current repo's memory (default source = cwd)
npx claude-mem memory ingest

# Ingest from an explicit directory
npx claude-mem memory ingest --source ~/.claude/projects/-home-you-code-app/memory

# Ingest everything
npx claude-mem memory ingest --all
```

### Flags

| Flag | Effect |
| - | - |
| *(none)* | Source = the memory dir of the repo you run the command in. |
| `--source <dir>` | Ingest from an explicit `memory/` directory. It must be inside Claude Code's projects directory (`~/.claude/projects`, or `$CLAUDE_CONFIG_DIR/projects`); anything else, including a symlink that leads outside it, is refused. |
| `--all` | Sweep every `~/.claude/projects/*/memory/` directory. |
| `--dry-run` | Zero-spend parse + count only. No worker, no DB writes. Run this first. |
| `--require-cwd` | Skip orphaned project dirs whose originating `cwd` cannot be resolved (instead of ingesting them under a fallback project). |

## How it runs

* **`--dry-run`** is pure parse + count — it runs entirely in the CLI process,
  touches no worker and no database, and spends nothing.
* The **real ingest** stores into the SQLite observation database, which lives
  in the worker. The CLI starts the worker if needed and drives the import over
  HTTP (`POST /api/memory/ingest`), as summaries reach the worker. Bulk
  imports are not time-limited.
* A file that cannot be read is reported as `failed`; the rest of the import
  carries on. A symlinked note is never followed and a note over 64 KB is not
  read; both are reported as `skipped`, each named with its reason. A note
  swapped for a symlink mid-scan is refused when opened and reported as
  `failed`. A source outside the projects directory, or one that does not
  exist, is a `400` from the worker.
* Only the memory notes are imported. A sibling transcript is read for its
  `cwd`, to key the project like live capture does; its content is never
  ingested.

## Frontmatter

Topic files carry a small YAML frontmatter block, which is preserved as
observation metadata:

```markdown theme={null}
---
name: recent-work
description: "What was done in the most recent session"
metadata:
  node_type: memory
  type: project
  originSessionId: 74e59070-...
---

<the distilled prose — stored as the observation body>
```

`metadata.type` (e.g. `project`, `feedback`, `reference`, `user`) and
`metadata.originSessionId` are carried through; files without frontmatter are
stored using their body as-is.

## Idempotency

Ingest is safe to re-run. Observations are content-hash deduplicated on insert,
so already-imported files are reported as `already-imported` and skipped — only
new or changed files are stored.

Changed prose is stored even when the file keeps the same title and
`CLAUDE_MEM_DEDUP_ENABLED=true`. Native notes use exact content deduplication;
the title-only merge for generated observations does not discard note revisions
or distinct topic files sharing a title. Earlier revisions remain available.

The summary line reports the outcome:

```
MEMORY INGEST: 12 stored, 38 already-imported, 0 skipped, 0 failed, of 50 files across 1 dirs
```

## Related

* [Memory Export/Import](/usage/export-import) — share memory sets between installations.


# Multi-Key Rotation
Source: https://docs.claude-mem.ai/usage/multi-key-rotation

Configure several API keys per provider so a rate-limited or exhausted key rotates to the next one instead of stopping memory

# Multi-Key Rotation

Give a provider more than one API key and claude-mem rotates through them: a key
that hits a rate limit, spends its quota, or turns out to be invalid is set aside
for a cooldown, and the next request uses the next key.

<Tip>
  This is for keys you already hold — a personal key next to a work or team key,
  or keys from separate billing accounts. When one runs into its limit, capture
  keeps going on the next instead of stopping for the rest of the window. Check
  your provider's terms first: some do not allow extra keys or accounts used only
  to get around their rate limits.
</Tip>

## What it fixes

Without a pool, one key's exhaustion stops memory for the rest of the window:

* `rate_limit` is retried twice more against the **same** key, honoring a
  `Retry-After` that defaults to 60 seconds — so each observation stalls a full
  minute and then fails anyway.
* `quota_exhausted` and `auth_invalid` are not retryable at all. The generator
  exits and the provider quota breaker arms the whole provider shut for 30
  minutes.

## Configuration

Add the plural setting alongside the existing single-key one. Keys can be
separated by newlines, commas, or spaces.

```json theme={null}
{
  "CLAUDE_MEM_PROVIDER": "gemini",
  "CLAUDE_MEM_GEMINI_API_KEY": "AIza...primary",
  "CLAUDE_MEM_GEMINI_API_KEYS": "AIza...second\nAIza...third"
}
```

| Provider | Single key | Rotation pool |
| - | - | - |
| Gemini | `CLAUDE_MEM_GEMINI_API_KEY` | `CLAUDE_MEM_GEMINI_API_KEYS` |
| OpenRouter | `CLAUDE_MEM_OPENROUTER_API_KEY` | `CLAUDE_MEM_OPENROUTER_API_KEYS` |
| OpenAI-compatible | `CLAUDE_MEM_OPENAI_COMPAT_API_KEY` | `CLAUDE_MEM_OPENAI_COMPAT_API_KEYS` |

Each plural setting is also readable from `~/.claude-mem/.env` as
`GEMINI_API_KEYS`, `OPENROUTER_API_KEYS`, or `OPENAI_COMPAT_API_KEYS`, which
keeps keys out of `settings.json`.

The single key stays first in the pool. You can also leave it empty and supply
every key through the list — the first listed key is promoted, so availability
checks and error messages keep working.

## How rotation behaves

**Rotates on** `rate_limit`, `quota_exhausted`, `auth_invalid` — the three
classifications that mean *this key* is the problem.

**Does not rotate on** `transient` (network blips, 5xx) or `unrecoverable` (a
malformed request, a bad model id). Retries already own the first, and the second
would fail identically on every key — rotating would just spend the pool.

**Cooldown windows**

| Kind | Window |
| - | - |
| `rate_limit` | the endpoint's `Retry-After`, clamped to 1s–15m; 60s if it sends none |
| `quota_exhausted` | 30 minutes |
| `auth_invalid` | 6 hours |

A success clears that key's cooldown immediately, so recovery never waits out a
window. Correcting a mistyped key also takes effect at once.

**When every key is cooling**, claude-mem still tries the one nearest to expiry
rather than failing without sending anything — a misclassification, or an
endpoint that reset earlier than it announced, should not become a hard stop. If
that attempt also fails, the last classified error propagates unchanged, so the
existing pause and breaker behaviour is exactly what it was.

Cooldowns are written to `~/.claude-mem/api-key-cooldown.json` so they survive a
worker restart. **Keys are never written to that file or to any log line** —
both use a salted fingerprint that is meaningless outside your install.

## What does not change

* **One key behaves exactly as before.** A pool of one is a pass-through: same
  request path, same error, no cooldown bookkeeping.
* **Provider selection is untouched.** Rotation happens *within* the provider you
  selected. When a pool is fully spent, claude-mem does not silently switch to a
  different provider.
* **The cmem.ai gateway never pools, whichever provider points at it.** Its key
  is account-delivered, so a gateway endpoint uses exactly one `cm_pro_` key and
  never rotates through several. Your personal keys are never sent to it.
* **A `cm_pro_` key never goes to any other host.** The same rule covers the
  Gemini, OpenRouter, and OpenAI-compatible pools: a `cm_pro_` key, whether set
  as the single key or placed in a list, is dropped before any request to an
  endpoint other than the cmem.ai gateway. A Gemini setup that holds only
  `cm_pro_` keys counts as having no key.

## Verifying

Rotation events are logged at `warn` in the worker log
(`~/.claude-mem/logs/worker-YYYY-MM-DD.log`) with the pool position and key
fingerprint — never the key:

```
OpenRouter key 1/3 hit quota_exhausted; rotating to the next key
```


# My Work: the local live viewer
Source: https://docs.claude-mem.ai/usage/my-work

Follow recorded work, review completed results, and pick up the next human handoff on your own computer.

Open the worker URL printed by claude-mem, usually `http://localhost:37777`.
**My Work** is the default local viewer. It brings recorded human requests,
progress, next steps, and finished results into one readable place.

The panel runs locally and reads your saved memory database. It does not require
a cloud account, a new model call, or an internet connection to show your work.
The original memory timeline, sessions, settings and console remain under
**Memory & settings**, at `/viewer` on the same worker.

## Working, ready and checked

* **In progress** means the latest saved work state says work is underway. It is
  not a live-presence signal or a promise that an agent is currently running.
* **Needs you** appears when recorded work explicitly asks for human input.
  Open the handoff, inspect the original request and evidence, then continue in
  the agent conversation where the work is happening.
* **Ready to check** means the parent request was explicitly reported complete.
  A finished subtask or a closed agent session does not finish its parent.
* **Checked** means you pressed **Mark checked** for that version of the result.
  It records your review locally; it does not certify correctness or change the
  agent's source status. **Undo** is available on a checked card.
* **No recent update** means no newer activity has been recorded for six hours.

A new substantive source update invalidates an older check. If the request is
still reported complete, it returns to **Ready to check**. If it has reopened,
the recorded work status is shown instead. Review notes live in the private
`work-view-reviews.db` sidecar in the claude-mem data directory and are not
uploaded by cloud sync.

## Live updates without losing your place

The panel receives new local data automatically. While you are reading an open
request, using a control, or scrolled down, incoming changes wait behind
**Show updates**. Applied cards preserve their existing order. Timestamps refresh
without rebuilding the card you are reading.

**Local updates connected** describes the local data connection, separately from
cloud sync. If the connection or source fails, the panel keeps its last received
work visible and shows the interruption. It never animates a saved work status
as proof of agent activity.

## Requests and source evidence

Open a request to see its original human ask, recorded follow-ups, result and
source records. **Copy handoff** copies the goal, recorded state, next step and
recent updates so you can continue in the agent you choose. It never sends or
assigns work; if clipboard access is unavailable, select the displayed text.
A captured conversation normally forms one request; explicit
`request_id` fields can distinguish independent goals. The panel does not guess
that two unrelated conversations describe the same request.

Records without a proven human request remain under **work records need a linked
human request**. The live view loads a bounded recent slice; use **Memory &
settings** for the full saved history. Search and the time filter scope the cards,
state counts and **Your next move** together. When several projects are loaded, use the project selector to narrow that same view. **Other states** includes blocked, queued, quiet and unknown work; each card retains its recorded state label.

## Optional Claude.ai and ChatGPT connections

The **Connect Claude.ai** and **Connect ChatGPT** actions open the existing CMEM
Cloud setup. Clicking does not connect an account or upload memory. Sign in and
review the setup and sharing scope before enabling anything.

[Cloud sync](/cloud-sync) can upload saved prompt text and observation narratives.
Your local viewer continues to work without it.

## Work with your team

Switch from **My Work** to **TeamBrain** to view shared work. Personal requests
and local review notes remain in My Work. TeamBrain reads the shared board for
your selected team using your existing sync connection.

If this install has not joined a team, choose **Set up TeamBrain** to open the
team setup and plan page. To join with an invitation, run
`npx claude-mem teambrain join <invite-link>`, approve the device, and choose
which projects to share. Opening the TeamBrain tab does not enable sharing.

The connected panel shows your actual membership, whether you are broadcasting,
the shared project's open lists and tasks, and linked collision or delegation
findings. These are **shared work lists**, not inferred human requests. Local
Checked notes do not appear on them.

Shared updates wait while you read, and the panel refreshes only while its tab
is open and visible. If access is revoked or a team stops, the shared board is
cleared. A temporary connection failure keeps the last received board with a
visible error. **Team workspace & sharing settings** opens the full cloud page
for membership, invitations, billing and explicit sharing changes.


# OpenAI-Compatible Provider (NVIDIA NIM & others)
Source: https://docs.claude-mem.ai/usage/openai-compatible-provider

Run observation extraction on NVIDIA NIM, DeepSeek, Groq, Together, Ollama, LM Studio, or any OpenAI-compatible endpoint

# OpenAI-Compatible Provider

Claude-mem can run observation extraction against any endpoint that speaks the
OpenAI `/chat/completions` shape. Set `CLAUDE_MEM_PROVIDER` to
`openai-compatible`, pick a preset (or supply a base URL), and memory runs
entirely off your Claude plan.

<Note>
  **claude-mem observer**: choosing the claude-mem observer during
  `npx claude-mem install` runs memory off-plan with nothing to configure. This
  page is for bringing your own endpoint and key.
</Note>

## Why this is separate from the OpenRouter provider

`CLAUDE_MEM_OPENROUTER_BASE_URL` already lets the OpenRouter client talk to any
OpenAI-compatible endpoint, and it keeps working — nothing on that path changed.
But it carries three things that belong to openrouter.ai specifically:

* **Attribution headers.** `HTTP-Referer` and `X-Title` are sent to whatever
  host the base URL names, so pointing it at NVIDIA announces claude-mem's
  OpenRouter identity to NVIDIA.
* **`usage: { include: true }`**, gated on the URL containing `openrouter.ai`.
* **The cmem.ai gateway's credential-pinning rules**, which decide when a
  persisted base URL pins a persisted key. Those rules exist so an
  account-delivered gateway credential is never sent somewhere else — correct,
  and irrelevant to an endpoint you configured yourself, but you still share
  the same three settings keys with them.

This provider has its own settings keys and sends a deliberately plain request
body: `model`, `messages`, `temperature`, `max_tokens`, and nothing else. Strict
servers (vLLM in particular) reject unknown fields. `max_tokens` is
`CLAUDE_MEM_OBSERVER_MAX_OUTPUT_TOKENS` (4096 by default); a model that only
accepts `max_completion_tokens` gets the request again with that field.

A claude-mem observer key (`cm_pro_…`) is never sent to these endpoints. Use the
key the endpoint issued.

## Quick start: NVIDIA NIM

<Steps>
  <Step title="Get a key">
    Sign in at [build.nvidia.com](https://build.nvidia.com) and create an API key.
    It starts with `nvapi-`. NVIDIA's hosted models are free to start, which suits
    observation extraction: it is high-volume and structured, and does not need a
    frontier model.
  </Step>

  <Step title="Point claude-mem at it">
    ```json theme={null}
    {
      "CLAUDE_MEM_PROVIDER": "openai-compatible",
      "CLAUDE_MEM_OPENAI_COMPAT_PRESET": "nvidia-nim",
      "CLAUDE_MEM_OPENAI_COMPAT_API_KEY": "nvapi-..."
    }
    ```

    Or keep the key out of `settings.json` and put it in `~/.claude-mem/.env`:

    ```
    OPENAI_COMPAT_API_KEY=nvapi-...
    ```
  </Step>

  <Step title="Pick a model (optional)">
    The preset defaults to a small, fast NVIDIA-served model. Any model id from
    build.nvidia.com works and is passed verbatim:

    ```json theme={null}
    { "CLAUDE_MEM_OPENAI_COMPAT_MODEL": "nvidia/nemotron-3-super-120b-a12b" }
    ```
  </Step>

  <Step title="Restart the worker">
    ```bash theme={null}
    npx claude-mem restart
    ```
  </Step>
</Steps>

## Presets

A preset only supplies a default base URL and a default model. Anything it sets
is overridden by the matching setting, so switching preset never moves an
endpoint or model you pinned yourself.

| Preset | Base URL | Key required |
| - | - | - |
| `nvidia-nim` | `https://integrate.api.nvidia.com/v1` | yes |
| `orcarouter` | `https://api.orcarouter.ai/v1` | yes |
| `api-route` | `https://global.api-route.com/v1` | yes |
| `opper` | `https://api.opper.ai/v3/compat` | yes |
| `atlascloud` | `https://api.atlascloud.ai/v1` | yes |
| `deepseek` | `https://api.deepseek.com/v1` | yes |
| `opencode-go` | `https://opencode.ai/zen/go/v1` | yes |
| `opencode-zen` | `https://opencode.ai/zen/v1` | yes |
| `groq` | `https://api.groq.com/openai/v1` | yes |
| `together` | `https://api.together.xyz/v1` | yes |
| `minimax` | `https://api.minimax.io/v1` | yes |
| `minimax-cn` | `https://api.minimaxi.com/v1` | yes |
| `iflytek` | `https://maas-api.cn-huabei-1.xf-yun.com/v2` | yes |
| `ollama` | `http://localhost:11434/v1` | no |
| `lmstudio` | `http://localhost:1234/v1` | no |
| `vllm` | `http://localhost:8000/v1` | no |
| `custom` | — set it yourself | no |

<Note>
  Local presets need a model id — claude-mem cannot guess which model you loaded.
  Set `CLAUDE_MEM_OPENAI_COMPAT_MODEL` to whatever `ollama list` (or your server)
  reports, or the provider reports itself unconfigured and dispatch falls through
  to Claude.
</Note>

## OpenCode Go and Zen

An [OpenCode](https://opencode.ai) Go subscription or Zen key works here.
`opencode-go` defaults to `kimi-k3`; `opencode-zen` ships no default, so set the
model too. Pick ids from `https://opencode.ai/zen/go/v1/models` or
`https://opencode.ai/zen/v1/models`. Only models served on `/chat/completions`
work.

```json theme={null}
{
  "CLAUDE_MEM_PROVIDER": "openai-compatible",
  "CLAUDE_MEM_OPENAI_COMPAT_PRESET": "opencode-zen",
  "CLAUDE_MEM_OPENAI_COMPAT_API_KEY": "<your OpenCode key>",
  "CLAUDE_MEM_OPENAI_COMPAT_MODEL": "deepseek-v4-flash"
}
```

## Settings

| Setting | Default | Description |
| - | - | - |
| `CLAUDE_MEM_PROVIDER` | `claude` | Set to `openai-compatible` to select this provider |
| `CLAUDE_MEM_OPENAI_COMPAT_PRESET` | `''` (= `custom`) | Named endpoint preset from the table above |
| `CLAUDE_MEM_OPENAI_COMPAT_BASE_URL` | preset's | OpenAI-compatible base URL. `/chat/completions` is appended if absent |
| `CLAUDE_MEM_OPENAI_COMPAT_MODEL` | preset's | Model id, passed verbatim |
| `CLAUDE_MEM_OPENAI_COMPAT_API_KEY` | `''` | API key. Also read from `OPENAI_COMPAT_API_KEY` in `~/.claude-mem/.env` |
| `CLAUDE_MEM_OPENAI_COMPAT_API_KEYS` | `''` | Extra keys for rotation — see [multi-key rotation](/usage/multi-key-rotation) |

An unknown preset id degrades to `custom` rather than failing, because settings
are read during status polling and a typo should not crash a poll.

The viewer's **Settings → Advanced** panel edits the provider, preset, base URL
and model. The API key is set in `~/.claude-mem/settings.json` or
`~/.claude-mem/.env` only, never through the viewer.

## MiniMax

`minimax` is MiniMax's global endpoint and `minimax-cn` the mainland-China one;
use the preset that matches where your account lives. Both default to
`MiniMax-M3`. Any model id MiniMax serves is passed verbatim:

```json theme={null}
{
  "CLAUDE_MEM_PROVIDER": "openai-compatible",
  "CLAUDE_MEM_OPENAI_COMPAT_PRESET": "minimax",
  "CLAUDE_MEM_OPENAI_COMPAT_API_KEY": "<key from platform.minimax.io>",
  "CLAUDE_MEM_OPENAI_COMPAT_MODEL": "MiniMax-M2.7"
}
```

Reasoning models such as the M2 family can open their reply with a
`<think>…</think>` block. claude-mem removes a leading block like that on every
preset (it also covers DeepSeek R1 or Qwen3 on Ollama and vLLM), so the reasoning
is never stored or re-sent with the next request.

## iFlytek Spark

`iflytek` points at iFlytek's Astron MaaS platform and defaults to `spark-x2.5`.
Keys come from the [MaaS console](https://maas.xfyun.cn). The preset's base URL
is the pay-as-you-go endpoint; a Token Plan key is only accepted on the Token
Plan endpoint, so set the base URL as well:

```json theme={null}
{
  "CLAUDE_MEM_PROVIDER": "openai-compatible",
  "CLAUDE_MEM_OPENAI_COMPAT_PRESET": "iflytek",
  "CLAUDE_MEM_OPENAI_COMPAT_API_KEY": "<your MaaS key>",
  "CLAUDE_MEM_OPENAI_COMPAT_BASE_URL": "https://maas-token-api.cn-huabei-1.xf-yun.com/v2"
}
```

A key used on the other endpoint is rejected with a 403 (`11200`). `spark-x2.5`
returns its reasoning in a separate `reasoning_content` field, which claude-mem
ignores, so only the answer is stored.

## Any other endpoint

```json theme={null}
{
  "CLAUDE_MEM_PROVIDER": "openai-compatible",
  "CLAUDE_MEM_OPENAI_COMPAT_BASE_URL": "https://my-gateway.example.com/v1",
  "CLAUDE_MEM_OPENAI_COMPAT_MODEL": "my-model-id",
  "CLAUDE_MEM_OPENAI_COMPAT_API_KEY": "..."
}
```

### When a key is required

Setting `CLAUDE_MEM_OPENAI_COMPAT_BASE_URL` replaces the preset's endpoint, so
whether a key is needed is decided by the endpoint you pointed at, not by the
preset name you started from:

| Endpoint | Key required |
| - | - |
| `localhost`, `127.0.0.1`, `[::1]`, `*.local` | No |
| A private network address (`10.x`, `192.168.x`, `172.16–31.x`) | No |
| Anything else | Yes |

Without an override, the preset decides — the hosted presets need a key, the
local ones do not.

A remote endpoint that genuinely needs no authentication still works: set
`CLAUDE_MEM_OPENAI_COMPAT_API_KEY` to any non-empty value. The default errs
toward asking for a key because the alternative is a provider that reports
itself ready and then fails every observation with a 401.

## OrcaRouter

[OrcaRouter](https://www.orcarouter.ai) serves provider-scoped model ids, such
as `openai/gpt-4o-mini` (the preset's default) or `anthropic/claude-haiku-4.5`,
behind one `sk-orca-` key. Its model list is public at
`https://api.orcarouter.ai/v1/models`.

```json theme={null}
{
  "CLAUDE_MEM_PROVIDER": "openai-compatible",
  "CLAUDE_MEM_OPENAI_COMPAT_PRESET": "orcarouter",
  "CLAUDE_MEM_OPENAI_COMPAT_API_KEY": "sk-orca-...",
  "CLAUDE_MEM_OPENAI_COMPAT_MODEL": "anthropic/claude-haiku-4.5"
}
```

## API Route

[API Route](https://api-route.com) uses the `api-route` preset with an API Route
key. It has no default model: set `CLAUDE_MEM_OPENAI_COMPAT_MODEL` to an exact
model id available to your account on `https://global.api-route.com/v1/models`.
Choose a model served on `/chat/completions`; the id is passed verbatim.

```json theme={null}
{
  "CLAUDE_MEM_PROVIDER": "openai-compatible",
  "CLAUDE_MEM_OPENAI_COMPAT_PRESET": "api-route",
  "CLAUDE_MEM_OPENAI_COMPAT_API_KEY": "<your API Route key>",
  "CLAUDE_MEM_OPENAI_COMPAT_MODEL": "<your chat-completions model id>"
}
```

Alternatively, store the key as `OPENAI_COMPAT_API_KEY` in
`~/.claude-mem/.env`. Restart the worker after changing the configuration.
Without a model or key, this provider is unconfigured and dispatch falls
through to Claude.

## Opper

[Opper](https://opper.ai) is an EU-hosted gateway with one OpenAI-compatible
API and one key for 700+ models. Model ids are pooled names such as
`gpt-5.4-mini` (the preset's default) or `claude-haiku-4-5`, and Opper picks
the route per request. A `provider/model` id such as `aws/claude-haiku-4-5-eu`
pins one provider and region. The catalogue is public at
`https://api.opper.ai/v3/models`, and keys come from
[platform.opper.ai](https://platform.opper.ai).

```json theme={null}
{
  "CLAUDE_MEM_PROVIDER": "openai-compatible",
  "CLAUDE_MEM_OPENAI_COMPAT_PRESET": "opper",
  "CLAUDE_MEM_OPENAI_COMPAT_API_KEY": "<your Opper key>",
  "CLAUDE_MEM_OPENAI_COMPAT_MODEL": "claude-haiku-4-5"
}
```

## Atlas Cloud

[Atlas Cloud](https://www.atlascloud.ai) serves models from DeepSeek, Z.ai,
Moonshot, Qwen and other vendors behind one OpenAI-compatible API key. Model ids
are vendor-prefixed, such as `deepseek-ai/deepseek-v4-flash` (the preset's
default) or `zai-org/glm-5.3`, and are passed verbatim. The model list is public
at `https://api.atlascloud.ai/v1/models`, and keys come from
[console.atlascloud.ai](https://console.atlascloud.ai/api-keys).

```json theme={null}
{
  "CLAUDE_MEM_PROVIDER": "openai-compatible",
  "CLAUDE_MEM_OPENAI_COMPAT_PRESET": "atlascloud",
  "CLAUDE_MEM_OPENAI_COMPAT_API_KEY": "<your Atlas Cloud key>",
  "CLAUDE_MEM_OPENAI_COMPAT_MODEL": "deepseek-ai/deepseek-v4-flash"
}
```

## Troubleshooting

**Memory silently runs on Claude instead.** Dispatch falls through to Claude
when the provider is selected but not fully configured — a missing base URL, a
missing model, or a missing key on a preset that needs one. That fall-through is
deliberate: a half-configured endpoint should not fail every observation. Check
`npx claude-mem doctor`.

**404 from the endpoint.** Almost always a wrong base URL or a model the
endpoint does not serve; the error names both settings. Note that some gateways
prefix model ids differently from the vendor's own docs.

**Repeated timeouts.** Requests are streamed, so a request is given up only
after 90 seconds with no token and no keep-alive from the endpoint, or after
300 seconds in total. A self-hosted endpoint that queues requests behind a load
balancer spends that queue wait silent, so the wait reads as idle; raise
`CLAUDE_MEM_LLM_STREAM_IDLE_TIMEOUT_MS` past it. `CLAUDE_MEM_LLM_TIMEOUT_MS`
does not apply to streamed requests; it is the deadline only for an endpoint
that refuses streaming (a 400 naming `stream` or `stream_options`), which
claude-mem then calls non-streamed for the rest of the worker's life. If
requests keep timing out, prefer a small, fast model: observation extraction is
a high-volume structured task, not a reasoning benchmark.

**Empty or cut-off observations.** A model that will not hold to the output
schema produces nothing usable. Small instruct-tuned models generally do better
here than reasoning models, whose thinking output tends to crowd out the
structured reply. When the log says a reply was cut off at the output-token
limit, raise `CLAUDE_MEM_OBSERVER_MAX_OUTPUT_TOKENS`.


# OpenRouter Provider
Source: https://docs.claude-mem.ai/usage/openrouter-provider

Access 100+ AI models through OpenRouter's unified API and run observation extraction off-plan

# OpenRouter Provider

Claude-mem supports [OpenRouter](https://openrouter.ai) as an alternative provider for observation extraction. OpenRouter provides a unified API to access 100+ models from different providers including Google, Meta, Mistral, DeepSeek, and many others.

<Tip>
  **Memory runs off-plan**: With OpenRouter (or the claude-mem observer, which runs on this provider), observation extraction happens off your Claude plan — so memory work never shares your plan usage.
</Tip>

<Note>
  **claude-mem observer**: When you sign in during `npx claude-mem install` and choose the claude-mem observer, claude-mem configures this provider for you automatically with a provisioned key — no manual setup needed. The rest of this page covers bringing your own OpenRouter key.
</Note>

## Why Use OpenRouter?

* **Runs off-plan**: Observation extraction never shares your Claude plan usage
* **Access to 100+ models**: Choose from models across multiple providers through one API
* **Free model options**: Several high-quality models are available at no charge
* **Errors throw clearly**: 429s, 5xx, and network failures throw — leaving messages pending so they can be retried
* **Hot-swappable**: Switch providers without restarting the worker
* **Multi-turn conversations**: Full conversation history maintained across API calls

## Free Models on OpenRouter

OpenRouter actively supports democratizing AI access by offering free models. These are production-ready models suitable for observation extraction.

### Featured Free Models

| Model | ID | Parameters | Context | Best For |
| - | - | - | - | - |
| **Cohere North Mini Code** | `cohere/north-mini-code:free` | 30B (3B active, MoE) | 256K | Default; agentic coding |
| **Poolside Laguna XS 2.1** | `poolside/laguna-xs-2.1:free` | 33B (3B active, MoE) | 256K | Coding agents |
| **NVIDIA Nemotron 3 Ultra** | `nvidia/nemotron-3-ultra-550b-a55b:free` | 550B (55B active, MoE) | 1M | Reasoning, orchestration |

<Note>
  **Default Model**: Claude-mem uses `cohere/north-mini-code:free` by default, a sparse mixture-of-experts coding model with a 256K context window.
</Note>

### Free Model Considerations

* **Rate limits**: Free models may have stricter rate limits than paid models
* **Availability**: Free capacity depends on provider partnerships and demand
* **Retirement**: OpenRouter retires free model ids regularly. If the default is retired, claude-mem moves stored settings off it automatically. If a model you picked is retired, the observer reports "OpenRouter model unavailable" (see [Troubleshooting](#model-unavailable))
* **Queue times**: During peak usage, requests may be queued briefly
* **Max tokens**: Most free models support 65,536 completion tokens

All free models support:

* Tool use and function calling
* Temperature and sampling controls
* Stop sequences
* Streaming responses

## Getting an API Key

1. Go to [OpenRouter](https://openrouter.ai)
2. Sign in with Google, GitHub, or email
3. Navigate to [API Keys](https://openrouter.ai/keys)
4. Click **Create Key**
5. Copy and securely store your API key

<Tip>
  **Free to start**: No credit card required to create an account or use free models. Add credits only if you want to use premium models.
</Tip>

## Configuration

### Settings

| Setting | Values | Default | Description |
| - | - | - | - |
| `CLAUDE_MEM_PROVIDER` | `claude`, `codex`, `gemini`, `openrouter`, `openai-compatible` | `claude` | AI provider for observation extraction |
| `CLAUDE_MEM_OPENROUTER_API_KEY` | string | — | Your OpenRouter API key |
| `CLAUDE_MEM_OPENROUTER_MODEL` | string or array | `cohere/north-mini-code:free` | Model identifier, or a list to fall back through (see [Model fallbacks](#model-fallbacks)) |
| `CLAUDE_MEM_OPENROUTER_BASE_URL` | string | — | Optional: custom OpenAI-compatible base URL (see [Custom OpenAI-compatible gateways](#custom-openai-compatible-gateways)) |
| `CLAUDE_MEM_OPENROUTER_SITE_URL` | string | — | Optional: URL for analytics attribution |
| `CLAUDE_MEM_OPENROUTER_REASONING_EFFORT` | `none`, `minimal`, `low`, `medium`, `high` | — | Optional: reasoning effort for openrouter.ai models. `none` turns reasoning off, the fix for a model that spends the output budget thinking and answers with nothing. Unset sends nothing. Never sent to custom base URLs or the claude-mem observer |
| `CLAUDE_MEM_OPENROUTER_APP_NAME` | string | `claude-mem` | Optional: App name for analytics |
| `CLAUDE_MEM_OPENROUTER_TEMPERATURE` | Number, 0–2 | Unset (0.3) | Optional worker sampling temperature, e.g. `0.7` or `"0.7"`. Settings file or environment; environment takes precedence. Overrides extra-body temperature when set. Blank or invalid values preserve existing behavior |
| `CLAUDE_MEM_OPENROUTER_EXTRA_BODY` | JSON object | — | Optional: extra request fields (see [Extra request fields](#extra-request-fields)). Settings file or environment only |

### Using the Settings UI

1. Open the worker URL printed on startup
2. Click the **gear icon** to open Settings
3. Under **AI Provider**, select **OpenRouter**
4. Enter your OpenRouter API key
5. Optionally select a different model

Settings are applied immediately—no restart required.

### Manual Configuration

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

```json theme={null}
{
  "CLAUDE_MEM_PROVIDER": "openrouter",
  "CLAUDE_MEM_OPENROUTER_API_KEY": "sk-or-v1-your-key-here",
  "CLAUDE_MEM_OPENROUTER_MODEL": "cohere/north-mini-code:free"
}
```

### Model fallbacks

`CLAUDE_MEM_OPENROUTER_MODEL` also accepts a **list** of model ids. The first is
the one normally used; the rest are handed to OpenRouter's native `models`
fallback array, which tries them in order when the one before it errors.

```json theme={null}
{
  "CLAUDE_MEM_PROVIDER": "openrouter",
  "CLAUDE_MEM_OPENROUTER_API_KEY": "sk-or-v1-your-key-here",
  "CLAUDE_MEM_OPENROUTER_MODEL": [
    "vendor/fast-model:free",
    "vendor/backup-model:free",
    "vendor/paid-model"
  ]
}
```

A comma- or space-separated string works too, so
`"vendor/a, vendor/b"` means the same thing as the two-entry array.

Fallbacks are sent only to `openrouter.ai`. A custom
`CLAUDE_MEM_OPENROUTER_BASE_URL` gateway speaks plain OpenAI, which has no
`models` field, so it receives the **first** id and ignores the rest.

Alternatively, set the API key via environment variable:

```bash theme={null}
export OPENROUTER_API_KEY="sk-or-v1-your-key-here"
```

The settings file takes precedence over the environment variable.

### Custom OpenAI-compatible gateways

The OpenRouter provider is a generic OpenAI-compatible client. Set `CLAUDE_MEM_OPENROUTER_BASE_URL` to any server that speaks `/chat/completions`, such as DeepSeek (`https://api.deepseek.com`), LM Studio (`http://localhost:1234/v1`) or [IO Intelligence](https://io.net) by io.net. The model id is sent as-is, and the first id of a fallback list is used (plain OpenAI has no `models` field). Use the key that endpoint issued: a claude-mem observer key (`cm_pro_…`) is only ever sent to the claude-mem observer.

<Tip>
  The [OpenAI-compatible provider](/usage/openai-compatible-provider) does the same job on settings of its own, with presets for common endpoints, and sends none of OpenRouter's attribution headers. Prefer it for an endpoint that is not OpenRouter.
</Tip>

For example, IO Intelligence:

```json theme={null}
{
  "CLAUDE_MEM_PROVIDER": "openrouter",
  "CLAUDE_MEM_OPENROUTER_BASE_URL": "https://api.intelligence.io.solutions/api/v1",
  "CLAUDE_MEM_OPENROUTER_MODEL": "meta-llama/Llama-3.3-70B-Instruct",
  "CLAUDE_MEM_OPENROUTER_API_KEY": "YOUR_IO_INTELLIGENCE_API_KEY"
}
```

Model ids are org/name pairs from the [IO Intelligence model list](https://api.intelligence.io.solutions/api/v1/models), for example `deepseek-ai/DeepSeek-R1-0528` or `zai-org/GLM-4.6`. A trailing slash on the base URL is fine; `/chat/completions` is appended automatically.

### Extra request fields

`CLAUDE_MEM_OPENROUTER_EXTRA_BODY` merges a JSON object into every request, for provider-specific fields claude-mem does not set itself. The common case is a reasoning model that spends the whole output budget thinking and answers with nothing. Turn its reasoning off:

```json theme={null}
{
  "CLAUDE_MEM_OPENROUTER_EXTRA_BODY": { "reasoning": { "enabled": false } }
}
```

As an environment variable it is the same object as a string: `CLAUDE_MEM_OPENROUTER_EXTRA_BODY='{"reasoning":{"enabled":false}}'`. A custom gateway may use its vendor's own field instead, for example `{"thinking":{"type":"disabled"}}`.

* The value must be a JSON object. Anything else is ignored with a warning in the worker log.
* It cannot replace `model`, `models`, `messages`, `stream`, `max_tokens` or `max_completion_tokens`. Those fields are dropped with a warning. Set the output cap with `CLAUDE_MEM_OBSERVER_MAX_OUTPUT_TOKENS`.
* It is never sent to the claude-mem observer.
* When `CLAUDE_MEM_OPENROUTER_REASONING_EFFORT` is set, it decides `reasoning` and the extra body's `reasoning` field is ignored.
* Set it in `~/.claude-mem/settings.json` or the environment. The settings UI and API do not write it.

## Model Selection Guide

### Free Models

**Recommended**: `cohere/north-mini-code:free` (the default)

* 256K context window handles large observations
* 64K max completion tokens
* Sparse mixture-of-experts architecture (3B active parameters)

**Alternatives**:

* `poolside/laguna-xs-2.1:free` - Coding-agent model, 256K context
* `nvidia/nemotron-3-ultra-550b-a55b:free` - 1M context, strong reasoning

### Premium Models (Higher Quality/Speed)

| Model | Best For |
| - | - |
| `anthropic/claude-haiku-4.5` | Same model as the Claude provider's default |
| `google/gemini-2.5-flash` | Fast responses |
| `openai/gpt-4o` | GPT-4 quality |

Premium models draw on your OpenRouter credit — still off-plan, so they never touch your Claude plan usage.

## Context Window Management

The full conversation history is sent to the model on each request. claude-mem does
**not** apply any client-side truncation or message-count cap — the provider and model
own their own context window. If you need to bound context for a specific model, choose a
model with an appropriate context length or manage limits at the OpenRouter/provider level.

### Usage Tracking

Logs include detailed usage information:

```
OpenRouter API usage: {
  model: "cohere/north-mini-code:free",
  inputTokens: 2500,
  outputTokens: 1200,
  totalTokens: 3700,
  estimatedCostUSD: "0.00",
  messagesInContext: 8
}
```

## Provider Switching

You can switch between providers at any time:

* **No restart required**: Changes take effect on the next observation
* **Conversation history preserved**: When switching mid-session, the new provider sees the full conversation context
* **Seamless transition**: All providers use the same observation format

### Switching via UI

1. Open Settings in the viewer
2. Change the **AI Provider** dropdown
3. The next observation will use the new provider

### Switching via Settings File

```json theme={null}
{
  "CLAUDE_MEM_PROVIDER": "openrouter"
}
```

## Error Behavior

If OpenRouter errors, claude-mem logs the failure and re-throws so the message stays pending for later retry. There is no Claude SDK fallback — earlier docs claimed automatic Claude fallback, but the wiring was never actually engaged in production (#2087). To switch providers, change `CLAUDE_MEM_PROVIDER` in settings.

**Throwing conditions:**

* Rate limiting (HTTP 429)
* Server errors (HTTP 500, 502, 503)
* Network issues (connection refused, timeout)
* 4xx errors other than 429
* Missing API key

## Multi-Turn Conversation Support

OpenRouter agent maintains full conversation history across API calls:

```
Session Created
  ↓
Load Pending Messages (observations from queue)
  ↓
For each message:
  → Add to conversation history
  → Call OpenRouter API with FULL history
  → Parse XML response
  → Store observations in database
  → Sync to Chroma vector DB
  ↓
Session complete
```

This enables:

* Coherent multi-turn exchanges
* Context preservation across observations
* Seamless provider switching mid-session

## Troubleshooting

### "OpenRouter API key not configured"

Either:

* Set `CLAUDE_MEM_OPENROUTER_API_KEY` in `~/.claude-mem/settings.json`, or
* Set the `OPENROUTER_API_KEY` environment variable

### Rate Limiting

Free models may have rate limits during peak usage. If you hit rate limits:

* The agent throws and leaves the message pending — it will be retried later
* Consider switching to a different free model
* Add credits for premium model access

### Model unavailable

The observer reports `OpenRouter model unavailable` when OpenRouter says the configured model is retired ("This model has been deprecated"), unknown ("is not a valid model ID"), or has no endpoint left ("No endpoints found for …"). Retrying cannot fix that, so it is not retried; the worker log and the session-start warning tell you to change the model:

* Pick a model from [OpenRouter Models](https://openrouter.ai/models) and set it as `CLAUDE_MEM_OPENROUTER_MODEL` in `~/.claude-mem/settings.json` (or in the viewer's Settings). The next observation uses it
* Use the `:free` suffix for free model variants
* Model IDs are case-sensitive

If you were still on the retired `xiaomi/mimo-v2-flash:free` default, claude-mem already moved you to `cohere/north-mini-code:free` the first time it loaded your settings.

### High Token Usage

If a session accumulates a large conversation history, requests can grow. To keep
per-request size down:

* Choose a model suited to your usage volume
* Consider a model with a larger context window if you hit provider-side limits

### Connection Errors

If you see connection errors:

* Check your internet connection
* Verify OpenRouter service status at [status.openrouter.ai](https://status.openrouter.ai)
* The agent throws and leaves the message pending for later retry

## API Details

OpenRouter uses an OpenAI-compatible REST API:

**Endpoint**: `https://openrouter.ai/api/v1/chat/completions`

**Headers**:

```
Authorization: Bearer {apiKey}
HTTP-Referer: https://github.com/thedotmack/claude-mem
X-Title: claude-mem
Content-Type: application/json
```

**Request Format**:

```json theme={null}
{
  "model": "cohere/north-mini-code:free",
  "messages": [
    {"role": "system", "content": "..."},
    {"role": "user", "content": "..."}
  ],
  "temperature": 0.3,
  "max_tokens": 4096
}
```

## Comparing Providers

| Feature | Claude (SDK) | Gemini | OpenRouter |
| - | - | - | - |
| **Plan usage** | Shares your Claude plan | Off-plan (your Gemini key) | Off-plan (your OpenRouter credit or the claude-mem observer) |
| **Models** | Claude only | Gemini only | 100+ models |
| **Quality** | Highest | High | Varies by model |
| **Rate limits** | Based on tier | 5-4000 RPM | Varies by model |
| **On error** | Throws | Throws | Throws |
| **Setup** | Automatic | API key required | API key required |

<Tip>
  **Recommendation**: The claude-mem observer (chosen at install) is the easiest way to run memory off-plan. Bringing your own key? Start with the free `cohere/north-mini-code:free` model. If you need higher quality or encounter rate limits, switch to a premium model or the Claude provider.
</Tip>

## Next Steps

* [Configuration](/configuration) - Full settings reference
* [Gemini Provider](/usage/gemini-provider) - Alternative free provider
* [Getting Started](/usage/getting-started) - Basic usage guide
* [Troubleshooting](/troubleshooting) - Common issues

## Multiple keys

`CLAUDE_MEM_OPENROUTER_API_KEYS` accepts additional keys (newline- or comma-separated) alongside
`CLAUDE_MEM_OPENROUTER_API_KEY`. When a key hits a rate limit, spends its quota, or is rejected as
invalid, OpenRouter requests rotate to the next key instead of failing for the
rest of the window. See [Multi-Key Rotation](/usage/multi-key-rotation).


# Private Tags
Source: https://docs.claude-mem.ai/usage/private-tags

Control what gets stored in memory with privacy tags

# Private Tags

## Overview

Use `<private>` tags to mark content you don't want persisted in claude-mem's observation database. This gives you fine-grained control over what gets remembered across sessions.

## How It Works

Wrap any content in `<private>` tags:

```
<private>
This content will not be stored in memory
</private>
```

Claude can see and use this content during the current session, but it won't be saved as an observation.

## Use Cases

### 1. Sensitive Information

```
Please analyze this error:

<private>
Error: Database connection failed
Host: internal-db-prod.company.com
Port: 5432
User: admin_user
</private>

What might be causing this?
```

Claude sees the full error but only the question gets stored.

### 2. Temporary Context

```
<private>
Here's some background context just for this session:
- Project deadline is tomorrow
- This is a hotfix for production
- Manager asked for this specifically
</private>

Help me fix this bug quickly.
```

### 3. Debugging Information

```
<private>
Debug output from previous run:
[... 500 lines of logs ...]
</private>

Based on these logs, what's the root cause?
```

### 4. Exploratory Prompts

```
<private>
I'm just brainstorming here, not making a final decision
</private>

What are some wild approaches to solving this?
```

## Technical Details

### Tag Behavior

* **Multiline support**: Tags can wrap multiple lines of content
* **Multiple tags**: You can use multiple `<private>` sections in one message
* **Nested tags**: Inner tags are included in outer tag removal
* **Always active**: No configuration needed - works automatically

### What Gets Filtered

The `<private>` tag filters content from storage and memory:

* **User prompt storage** - Tags are stripped before saving to the user\_prompts table
* **Tool inputs** - Parameters passed to tools are filtered before observation creation
* **Tool responses** - Output from tools is filtered before observation creation
* **All searchable content** - Private content never reaches the database or search indices

**Important**: Tags are stripped during storage, not from the live conversation. Claude sees the full content including `<private>` tags during the session, and they only disappear when content is persisted to the database.

### What Doesn't Get Filtered

* Session summaries (generated from non-private observations only)
* Claude's responses (not captured by claude-mem)

## Examples

### Example 1: API Keys

```
<private>
API_KEY=sk-proj-abc123xyz789
</private>

Test this API connection for me
```

The API key won't be stored, but Claude can use it during the session.

### Example 2: Personal Notes

```
<private>
Note to self: This is for the Smith project - the one we discussed
last Tuesday. Don't confuse with the Jones project.
</private>

Review the authentication implementation and suggest improvements.
```

The personal context helps Claude understand your request without polluting your observation history.

## Best Practices

1. **Don't over-tag**: Only use `<private>` for content you genuinely don't want stored
2. **Context matters**: Claude's understanding of your project comes from observations - excessive private tagging reduces future context quality
3. **Secrets belong elsewhere**: While `<private>` prevents storage, sensitive data should still use proper secrets management
4. **Test it works**: Check `~/.claude-mem/silent.log` if you're unsure whether tags are being stripped

## Verification

To verify tags are working:

1. Submit a prompt with `<private>` tags
2. Check the database to ensure private content is not stored:
   ```bash theme={null}
   # Check user prompts
   sqlite3 ~/.claude-mem/claude-mem.db "SELECT prompt_text FROM user_prompts ORDER BY created_at_epoch DESC LIMIT 1;"

   # Check observations
   sqlite3 ~/.claude-mem/claude-mem.db "SELECT narrative FROM observations ORDER BY created_at_epoch DESC LIMIT 1;"
   ```
3. The private content should NOT appear in either user\_prompts or observations
4. The `<private>` tags themselves should also be stripped

## Architecture

The `<private>` tag uses an **edge processing pattern**:

* Content is filtered at the hook layer before any storage
  * **UserPromptSubmit hook**: Strips tags from user prompts before saving to the user\_prompts table (your typed prompts are cleaned before database storage)
  * **PostToolUse hook**: Strips tags from serialized tool\_input and tool\_response JSON before observation creation
* Filtering happens before data reaches the worker service or database
* This keeps the worker simple and follows a one-way data stream
* Tags remain visible in the live conversation but are stripped from all persistent storage

**Tag Stripping Scope**: The implementation strips tags from the *serialized JSON representations* of tool inputs and tool responses, not from the original user prompt text in the conversation UI. The user prompt text you type is stored in a separate table (user\_prompts) where tags are also stripped before storage.

This design ensures that private content never reaches the database, search indices, or memory agent, maintaining a clean separation between ephemeral and persistent data.

## Related Features

* [Search Tools](/usage/search-tools) - How to search past observations
* [Getting Started](/usage/getting-started) - Basic usage guide
* [Configuration](/configuration) - System settings and environment variables

## Troubleshooting

### Tags Not Being Stripped

1. Verify correct syntax: `<private>content</private>`
2. Check `~/.claude-mem/silent.log` for errors
3. Ensure worker is running: `npm run worker:status`
4. Restart worker: `npm run worker:restart`

### Partial Content Stored

If content appears partially in observations:

* Ensure tags are properly closed
* Check for typos in tag names
* Verify content is inside tool executions (not just in your prompt text)

### Silent Log Shows Errors

If you see errors in `~/.claude-mem/silent.log`:

```
[save-hook] stripMemoryTags received non-string: { type: 'object' }
```

This is usually harmless - it indicates defensive type checking is working. However, if you see these frequently, it may indicate a bug. Please report it at [https://github.com/thedotmack/claude-mem/issues](https://github.com/thedotmack/claude-mem/issues)

## See also

* [Auto-Redaction](/usage/auto-redaction) — opt-in regex-based detection for accidental token leaks. Complements `<private>` tags by catching secrets you never typed yourself.


# Quota Fallback
Source: https://docs.claude-mem.ai/usage/quota-fallback

Keep capturing memories on your Anthropic plan (or another provider) while the selected provider can't serve

# Quota Fallback

When the observer's provider can't serve (its allowance is spent, it stays rate limited or over capacity after its retries, it is down, or it keeps answering without usable output), claude-mem holds it for a short cooldown and stops sending it work, so it does not keep buying the same refusal.

**By default, that work moves to your Anthropic plan (Claude)** for as long as the provider is held, provided Claude can run on this machine (a Claude Code login, or an `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` in `~/.claude-mem/.env`). When the cooldown ends, one generator probes the original provider; if it answers, everything moves back on its own. If Claude can't run, or you turn the fallback off, work waits and stays queued until the provider recovers.

This applies when your selected provider is the claude-mem observer (cmem.ai), OpenRouter, Gemini, Codex, or an OpenAI-compatible endpoint. When Claude is your selected provider there is nothing to fall back to.

## Settings

Add these to `~/.claude-mem/settings.json`, or set them in the viewer under **Settings → Advanced**:

| Setting | Values | Meaning |
| - | - | - |
| `CLAUDE_MEM_QUOTA_FALLBACK_PROVIDER` | `claude` (the default; `""` means the same), `gemini`, `openrouter`, `openai-compatible`, `off` | Where observation work goes while the selected provider can't serve. `off` turns the fallback off: work waits for the provider. |
| `CLAUDE_MEM_QUOTA_FALLBACK_MODEL` | `""` or a Claude model id or alias | The model for a **Claude** fallback run. Empty keeps `CLAUDE_MEM_MODEL` and tier routing. Ignored for every other fallback. |

For example, Gemini as the primary with Claude Haiku as the fallback:

```json theme={null}
{
  "CLAUDE_MEM_PROVIDER": "gemini",
  "CLAUDE_MEM_QUOTA_FALLBACK_PROVIDER": "claude",
  "CLAUDE_MEM_QUOTA_FALLBACK_MODEL": "claude-haiku-4-5-20251001"
}
```

To turn the fallback off:

```json theme={null}
{
  "CLAUDE_MEM_QUOTA_FALLBACK_PROVIDER": "off"
}
```

Settings files from earlier versions hold `""` for this setting; that now means the default, so those installs get the Anthropic-plan fallback too. Only `off` opts out.

The fallback needs its own credentials: a Gemini, OpenRouter or OpenAI-compatible API key, or a Claude Code login (or Anthropic key) for Claude. A fallback without them, or any fallback that is itself held (a quota cooldown, or a refused key), is skipped, and work waits as it does without a fallback. For Claude, claude-mem checks that a login or key exists; a login that has expired fails its first fallback run and is then skipped until you log in again. When the cmem.ai gateway turns your account away (a lapsed plan, a spent allowance), it is skipped as a fallback for 15 minutes and then re-tried by a single request; the next session start tells you once, in the gateway's own words. Unattended retries on the gateway are capped the same way whether it is your provider or your fallback.

## What switches, and what does not

* **Switches:** a spent allowance (a 30-minute cooldown); rate limits and "over capacity" refusals that are still refused after the provider's own retries; outages (5xx, network errors, timeouts) that outlast the retries; and a provider that answers the same batch twice without usable output, which hands that batch to the fallback instead of dropping it (each a 90-second cooldown). Work moves back as soon as the cooldown ends and the original provider answers its probe.
* **The claude-mem observer (cmem.ai) refusing your key** (a lapsed trial or plan) moves memory to your Anthropic plan as well, and re-checks the observer every 15 minutes.
* **Does not switch:** authentication errors on other providers — an invalid, expired or revoked key (401/403). Those pause capture exactly as before, because a different provider would not fix the key.
* **A fallback with a bad key is skipped once it is refused.** Only a *missing* key is detected ahead of time; an invalid or revoked fallback key fails its first run, and its auth cooldown then takes it out of rotation. Fix or clear the fallback key.
* **Paused work resumes on its own.** A generator that stops on a quota error keeps its queued observations. The worker's periodic resume (once a minute) restarts them on whichever provider can take the work — the fallback, or the original provider again if it has recovered by then — and the session's next tool call does the same sooner. If neither can, it waits as before.
* **Both exhausted:** if the fallback is also in a quota cooldown, nothing changes: work waits until one of them clears.

## Things to know

* **It spends the fallback's allowance.** With Claude as the fallback, observation runs count against your Claude plan. Setting `CLAUDE_MEM_QUOTA_FALLBACK_MODEL` to a Haiku model keeps that cheap.
* **Claude runs are capped by `CLAUDE_MEM_MAX_CONCURRENT_AGENTS`** (default 2). With three or more busy sessions on a Claude fallback, the extra sessions wait for a slot.
* **Telegram wrap-ups** are not governed by `CLAUDE_MEM_QUOTA_FALLBACK_MODEL`: they use the model the session last ran on, or the summary tier model.
* **Session-start notice.** While another provider is serving, the notice says capture continues there (for Claude: that memory is running on your Anthropic plan) instead of saying memory is paused. It is refreshed whenever a cooldown starts or ends, so right after a settings change it can be one step behind.

In the worker log, the switch shows as `Primary cannot serve right now; memory runs on the Anthropic plan (Claude) until it recovers` (or `Primary in quota cooldown; dispatching to fallback` for another fallback), followed later by `Primary quota cooldown elapsed; probing primary` and `Primary recovered from quota cooldown`. If nothing can take the work, the log says so once: `Primary and fallback both in quota cooldown; …` or `Primary in quota cooldown and the quota fallback cannot serve; …`.


# Memory Search
Source: https://docs.claude-mem.ai/usage/search-tools

Search your project history with MCP tools

# Memory Search with MCP Tools

Claude-mem provides persistent memory across sessions through **4 MCP tools** that follow a token-efficient **3-layer workflow pattern**.

## Overview

Instead of fetching all historical data upfront (expensive), claude-mem uses a progressive disclosure approach:

1. **Search** → Get a compact index with IDs (\~50-100 tokens/result)
2. **Timeline** → Get context around interesting results
3. **Get Observations** → Fetch full details ONLY for filtered IDs

This achieves **\~10x token savings** compared to traditional RAG approaches.

## The 3-Layer Workflow

### Layer 1: Search (Index)

Start by searching to get a lightweight index of results:

```
search(query="authentication bug", type="bugfix", limit=10)
```

**Returns:** Compact table with IDs, titles, dates, types
**Cost:** \~50-100 tokens per result
**Purpose:** Survey what exists before fetching details

### Layer 2: Timeline (Context)

Get chronological context around specific observations:

```
timeline(anchor=<observation_id>, depth_before=3, depth_after=3)
```

Or search and get timeline in one step:

```
timeline(query="authentication", depth_before=2, depth_after=2)
```

**Returns:** Chronological view showing what was happening before/after
**Cost:** Variable, depends on depth
**Purpose:** Understand narrative arc and context

### Layer 3: Get Observations (Details)

Fetch full details only for relevant observations:

```
get_observations(ids=[123, 456, 789])
```

**Returns:** Complete observation details (narrative, facts, files, concepts)
**Cost:** \~500-1000 tokens per observation
**Purpose:** Deep dive on specific, validated items

### Why This Works

**Traditional Approach:**

* Fetch everything upfront: 20,000 tokens
* Relevance: \~10% (2,000 tokens actually useful)
* Waste: 18,000 tokens on irrelevant context

**3-Layer Approach:**

* Search index: 1,000 tokens (10 results)
* Timeline context: 500 tokens (around 2 key results)
* Fetch details: 1,500 tokens (3 observations)
* **Total: 3,000 tokens, 100% relevant**

## Available Tools

### `important_workflow` - Workflow Documentation

Always visible reminder of the 3-layer workflow pattern. Helps Claude understand how to use the search tools efficiently.

**Usage:** Automatically shown, no need to invoke

### `search` - Search Memory Index

Search your memory and get a compact index with IDs.

**Parameters:**

* `query` - What to look for, in plain words: matched by meaning first, then by keywords (see [How the query is matched](#how-the-query-is-matched))
* `limit` - Maximum results (default: 20)
* `offset` - Skip first N results for pagination
* `type` - Record category: `observations`, `sessions` or `prompts` (default: all). Any other value is treated as an observation type, like `obs_type`
* `obs_type` - Filter observations by type (bugfix, feature, decision, discovery, refactor, change); comma-separated for several
* `project` - Filter by project name
* `dateStart` - Filter by start date (YYYY-MM-DD)
* `dateEnd` - Filter by end date (YYYY-MM-DD)
* `orderBy` - Sort order (date\_desc, date\_asc, relevance)

**Returns:** Compact index table with IDs, titles, dates, types

**Example:**

```
search(query="database migration", type="bugfix", limit=5, orderBy="date_desc")
```

### `timeline` - Get Chronological Context

Get a chronological view of observations around a specific point or query.

**Parameters:**

* `anchor` - Observation ID to center timeline around (optional if query provided)
* `query` - Search query to find anchor automatically (optional if anchor provided)
* `depth_before` - Number of observations before anchor (default: 3)
* `depth_after` - Number of observations after anchor (default: 3)
* `project` - Filter by project name

**Returns:** Chronological list showing what happened before/during/after

**Example:**

```
timeline(anchor=12345, depth_before=5, depth_after=5)
```

Or search-based:

```
timeline(query="implemented JWT auth", depth_before=3, depth_after=3)
```

### `get_observations` - Fetch Full Details

Fetch complete observation details by IDs. **Always batch multiple IDs in a single call for efficiency.**

**Parameters:**

* `ids` - Array of observation IDs (required)
* `orderBy` - Sort order (date\_desc, date\_asc)
* `limit` - Maximum observations to return
* `project` - Filter by project name

**Returns:** Complete observation details including narrative, facts, files, concepts

**Example:**

```
get_observations(ids=[123, 456, 789, 1011])
```

**Important:** Always batch IDs instead of making separate calls per observation.

## Common Use Cases

### Debugging Issues

**Scenario:** Find what went wrong with database connections

```
Step 1: search(query="error database connection", type="bugfix", limit=10)
  → Review index, identify observations #245, #312, #489

Step 2: timeline(anchor=312, depth_before=3, depth_after=3)
  → See what was happening around the fix

Step 3: get_observations(ids=[312, 489])
  → Get full details on relevant fixes
```

### Understanding Decisions

**Scenario:** Review architectural choices about authentication

```
Step 1: search(query="authentication", type="decision", limit=5)
  → Find decision observations

Step 2: get_observations(ids=[<relevant_ids>])
  → Get full decision rationale, trade-offs, facts
```

### Code Archaeology

**Scenario:** Find when a specific file was modified

```
Step 1: search(query="worker-service.ts", limit=20)
  → Get all observations mentioning that file

Step 2: timeline(query="worker-service.ts refactor", depth_before=2, depth_after=2)
  → See what led to and followed from the refactor

Step 3: get_observations(ids=[<specific_observation_ids>])
  → Get implementation details
```

### Feature History

**Scenario:** Track how a feature evolved

```
Step 1: search(query="dark mode", type="feature", orderBy="date_asc")
  → Chronological view of feature work

Step 2: timeline(anchor=<first_observation_id>, depth_after=10)
  → See the full development timeline

Step 3: get_observations(ids=[<key_milestones>])
  → Deep dive on critical implementation points
```

### Learning from Past Work

**Scenario:** Review refactoring patterns

```
Step 1: search(type="refactor", limit=10, orderBy="date_desc")
  → Recent refactoring work

Step 2: get_observations(ids=[<interesting_ids>])
  → Study the patterns and approaches used
```

### Context Recovery

**Scenario:** Restore context after time away from project

```
Step 1: search(query="project-name", limit=10, orderBy="date_desc")
  → See recent work

Step 2: timeline(anchor=<most_recent_id>, depth_before=10)
  → Understand what led to current state

Step 3: get_observations(ids=[<critical_observations>])
  → Refresh memory on key decisions
```

## How the query is matched

When the vector index (Chroma) is running, `search` first matches your query **by meaning**, so describe what you are looking for in plain words: `query="why the worker failed to start after the upgrade"`. Keyword matching fills any record category the semantic pass left empty, and answers on its own when the vector index is off or unavailable.

Keyword matching of observations and session summaries reads the query as plain words. It has no operators:

* **Every word must appear** somewhere in the record, in any order and in any field. `query="security deprecated"` finds records that mention both.
* **`AND`, `OR`, `NOT`, quotes, parentheses and `field:` prefixes are ordinary words.** `query="security NOT deprecated"` requires "not" and "deprecated" too, and `query='"database migration"'` is not a phrase search: the two words can appear anywhere. To narrow results, use the `obs_type`, `project`, `dateStart` and `dateEnd` parameters.
* **Case does not matter. Punctuation inside a word splits it into parts that must appear together, in order**, so `query="worker-service.ts"` finds that file name, but not a record that only mentions "worker", "service" and "ts" apart.
* **Words can match inside longer words when nothing matches whole words.** If no record contains every whole word, each word must still appear, but may be part of a longer one, so `query="migrat"` finds "migration". Text in scripts written without spaces between words (Chinese, Japanese, Korean, Thai and others) is always matched this way.

```
query="database migration"       # records mentioning both words, anywhere
query="worker-service.ts"         # a file name
query="security NOT deprecated"  # all three words, "not" included: there are no operators
```

Your own prompts are matched as one piece of text instead: the whole query must appear in the prompt as written, so `query="database migration"` misses a prompt that says "migration of the database". Keep prompt searches short.

The [hosted server runtime](/hosted-server) searches observations with PostgreSQL full-text search, which has its own rules: words match by their English stem, `OR` combines alternatives, quotes require a phrase, a leading `-` excludes a word, and there is no matching inside longer words.

## Token Management

### Token Efficiency Best Practices

1. **Always start with search** - Get index first (\~50-100 tokens/result)
2. **Use small limits** - Start with 3-5 results, increase if needed
3. **Filter before fetching** - Use type, date, project filters
4. **Batch get\_observations** - Always group multiple IDs in one call
5. **Use timeline strategically** - Get context only when narrative matters

### Token Cost Estimates

| Operation | Tokens per Result |
| - | - |
| search (index) | 50-100 |
| timeline (per observation) | 100-200 |
| get\_observations (full details) | 500-1,000 |

**Example Comparison:**

**Inefficient:**

```
# Fetching 20 full observations upfront: 10,000-20,000 tokens
get_observations(ids=[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20])
```

**Efficient:**

```
# Search index: ~1,000 tokens
search(query="bug fix", limit=20)

# Review IDs, identify 3 relevant observations

# Fetch only relevant: ~1,500-3,000 tokens
get_observations(ids=[5, 12, 18])

# Total: 2,500-4,000 tokens (vs 10,000-20,000)
```

## Advanced Filtering

### Date Ranges

```
search(
  query="performance optimization",
  dateStart="2025-10-01",
  dateEnd="2025-10-31"
)
```

### Multiple Types

For observations of multiple types, make multiple searches or use broader query:

```
search(query="database", type="bugfix", limit=10)
search(query="database", type="feature", limit=10)
```

### Project-Specific

```
search(query="API", project="my-app", limit=15)
```

### Pagination

```
# First page
search(query="refactor", limit=10, offset=0)

# Second page
search(query="refactor", limit=10, offset=10)

# Third page
search(query="refactor", limit=10, offset=20)
```

## Result Metadata

All observations include rich metadata:

* **ID** - Unique observation identifier
* **Type** - bugfix, feature, decision, discovery, refactor, change
* **Date** - When the work occurred
* **Title** - Concise description
* **Concepts** - Tagged themes (e.g., security, performance, architecture)
* **Files Read** - Files examined during work
* **Files Modified** - Files changed during work
* **Narrative** - Story of what happened and why
* **Facts** - Key factual points (decisions made, patterns used, metrics)

## Troubleshooting

### No Results Found

1. **Broaden your search:**
   ```
   # Too specific
   search(query="JWT authentication implementation with RS256")

   # Better
   search(query="authentication")
   ```

2. **Check database has data:**
   ```bash theme={null}
   WORKER_PORT=$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json)
   curl "http://127.0.0.1:$WORKER_PORT/api/search?query=test"
   ```

3. **Try without filters:**
   ```
   # Remove type/date filters to see if data exists
   search(query="your-search-term")
   ```

### IDs Not Found in get\_observations

**Error:** "Observation IDs not found: \[123, 456]"

**Causes:**

* IDs from different project (use `project` parameter)
* IDs were deleted
* Typo in ID numbers

**Solution:**

```
# Verify IDs exist
search(query="<related-search>")

# Use correct project filter
get_observations(ids=[123, 456], project="correct-project-name")
```

### Token Limit Errors

**Error:** Response exceeds token limits

**Solution:** Use the 3-layer workflow to reduce upfront costs:

```
# Instead of fetching 50 full observations:
# get_observations(ids=[1,2,3,...,50])  # 25,000-50,000 tokens!

# Do this:
search(query="<your-query>", limit=50)  # ~2,500-5,000 tokens
# Review index, identify 5 relevant observations
get_observations(ids=[<5-most-relevant>])  # ~2,500-5,000 tokens
# Total: 5,000-10,000 tokens (50-80% savings)
```

### Search Performance

If searches seem slow:

1. Be more specific in queries (helps FTS5 index)
2. Use date range filters to narrow scope
3. Specify project filter when possible
4. Use smaller limit values

## Best Practices

1. **Index First, Details Later** - Always start with search to survey options
2. **Filter Before Fetching** - Use search parameters to narrow results
3. **Batch ID Fetches** - Group multiple IDs in one get\_observations call
4. **Use Timeline for Context** - When narrative matters, timeline shows the story
5. **Specific Queries** - More specific = better relevance
6. **Small Limits Initially** - Start with 3-5 results, expand if needed
7. **Review Before Deep Dive** - Check index before fetching full details

## Technical Details

**Architecture:** MCP tools are a thin wrapper over the local Worker HTTP API. The MCP server translates tool calls into HTTP requests to the worker service, which handles all business logic, database queries, and Chroma vector search.

**MCP Server:** Located at `~/.claude/plugins/marketplaces/thedotmack/plugin/scripts/mcp-server.cjs`

**Worker Service:** Express API on the configured worker port, managed by Bun

**Database:** SQLite FTS5 full-text search on `~/.claude-mem/claude-mem.db`

**Vector Search:** Chroma embeddings for semantic search (underlying implementation)

## Next Steps

* [Progressive Disclosure](/progressive-disclosure) - Philosophy behind 3-layer workflow
* [Architecture Overview](/architecture/overview) - System components
* [Database Schema](/architecture/database) - Understanding the data structure
* [Claude Desktop Setup](/usage/claude-desktop) - Installation and configuration


# TeamBrain
Source: https://docs.claude-mem.ai/usage/teambrain

Bring your team's shared work beside your personal local workspace.

TeamBrain adds a shared workspace to Claude-Mem. Open **TeamBrain** beside
**My Work** in the local viewer to see the work your teammates chose to share,
with member and project attribution and linked findings about overlapping work.

My Work remains free and local. Opening the team view does not turn on sharing,
change the memory provider, or merge shared work into your private review queue.

## Set up or join a team

Choose **Set up TeamBrain** to see the current team plan and checkout at
[cmem.ai/teambrain/start](https://cmem.ai/teambrain/start). Team owners can invite
people from the cloud workspace.

With an invitation, run:

```bash theme={null}
npx claude-mem teambrain join '<invite-link>'
```

Sign in, approve the device, and choose which projects to share. The command
keeps your observer and provider settings. It does not switch an install that
already syncs as a different account.

Return to the local viewer, choose **TeamBrain**, and refresh the connection.
The membership summary shows your team and current sharing choice. An empty
project selection means no projects; it is different from sharing all projects.

## Understand the shared board

The team view shows open shared work lists and their tasks. These are labeled
**shared work** because a task or list is not necessarily a captured human
request. It keeps that distinction from My Work's original-request cards.

* See who shared a list and which project it belongs to.
* Open a card for recorded task state, next steps and source-linked findings.
* Filter by project or search the currently loaded shared work.
* Apply incoming updates when ready; reading an open card preserves your place.

The local panel does not assign work, send replies, or mark a teammate's task
checked. Continue in the source conversation or open **Sharing settings** for
the full cloud workspace, invitations and billing.

## Keep control of sharing

Each member controls broadcasting and project scope. My Work's local human
review notes are not part of the shared board. The local UI uses the sync
connection already approved for the install; it does not receive account tokens
in the browser or forward browser cookies to the cloud.

To inspect or change sharing from the terminal:

```bash theme={null}
npx claude-mem teambrain status
npx claude-mem teambrain share
```

If the team connection is interrupted, the panel labels the last received
board. If membership or access is refused, it clears that shared board. Your
personal local workspace remains available either way.