​

How Claude-Mem Uses Hooks: A Lifecycle-Driven Architecture

​

Core Principle

​

The Big Picture

┌─────────────────────────────────────────────────────────┐
│              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   │
└─────────────────────────────────────────────────────────┘

​

Why Hooks?

​

The Non-Invasive Requirement

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

​

The Hook System Advantage

​

The Hook Scripts

​

Setup Hook: Version Check

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.

{
  "hooks": {
    "Setup": [{
      "hooks": [{
        "type": "command",
        "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/version-check.js",
        "timeout": 300
      }]
    }]
  }
}

• ✅ Fast when the install is complete: a declared-dependency check, no install
• ✅ Self-heals marketplace installs: installs missing dependencies and writes the marker, so a working install never sees a “run the installer” message
• ✅ Names the missing modules when an install cannot be completed
• ✅ Always exit 0 — never blocks a session

​

Hook 1: SessionStart - Context Injection

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)

• ✅ 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

# [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*

​

Hook 2: UserPromptSubmit (New Session Hook)

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)

{
  "hooks": {
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/new-hook.js"
      }]
    }]
  }
}

• ✅ 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)

INSERT INTO sdk_sessions (claude_session_id, project, user_prompt, ...)
VALUES (?, ?, ?, ...)

INSERT INTO user_prompts (session_id, prompt, prompt_number, ...)
VALUES (?, ?, ?, ...)

​

Hook 3: PostToolUse (Save Observation Hook)

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)

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/save-hook.js"
      }]
    }]
  }
}

• ✅ Matcher: * (captures all tools)
• ✅ Non-blocking (just enqueues, doesn’t process)
• ✅ Worker processes observations asynchronously
• ✅ Parallel execution safe (each hook gets own stdin)

INSERT INTO observation_queue (session_id, tool_name, tool_input, tool_output, ...)
VALUES (?, ?, ?, ?, ...)

{
  "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
}

​

Hook 4: Stop Hook (Summary Generation)

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

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/summary-hook.js"
      }]
    }]
  }
}

• ✅ 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>
  <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>

​

Hook 5: SessionEnd (Cleanup Hook)

1. Marks session as completed in database
2. Allows worker to finish processing
3. Performs graceful cleanup

{
  "hooks": {
    "SessionEnd": [{
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/cleanup-hook.js"
      }]
    }]
  }
}

• ✅ Graceful completion (v4.1.0+)
• ✅ No longer sends DELETE to workers
• ✅ Skips cleanup on /clear commands
• ✅ Preserves ongoing sessions

// ❌ Aggressive cleanup
SessionEnd → DELETE /worker/session → Worker stops immediately

• Interrupted summary generation
• Lost pending observations
• Race conditions

// ✅ Graceful completion
SessionEnd → UPDATE sessions SET completed_at = NOW()
Worker sees completion → Finishes processing → Exits naturally

• Worker finishes important operations
• Summaries complete successfully
• Clean state transitions

​

Hook Execution Flow

​

Session Lifecycle

​

Hook Timing

​

The Worker Service Architecture

​

Why a Background Worker?

┌─────────────────────────────────────────────────────────┐
│                   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

• 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

# 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

• 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

// ❌ 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

Hook (capture) → Queue (buffer) → Worker (process)

• Parallel hook execution safe
• Worker failure doesn’t affect hooks
• Retry logic centralized
• Backpressure handling

​

Pattern 3: Graceful Degradation

try {
  await captureObservation();
} catch (error) {
  // Log error, but don't throw
  console.error('Memory capture failed:', error);
  return { continue: true, suppressOutput: true };
}

• 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

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

claude --debug

[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_PLUGIN_ROOT}/scripts/save-hook.js with timeout 60000ms
[DEBUG] Hook command completed with status 0: {"continue":true,"suppressOutput":true}

​

Common Issues

​

Testing Hooks Manually

# Test context hook
echo '{
  "session_id": "test123",
  "cwd": "/Users/alex/projects/my-app",
  "hook_event_name": "SessionStart",
  "source": "startup"
}' | node plugin/scripts/context-hook.js

# Test save hook
echo '{
  "session_id": "test123",
  "tool_name": "Edit",
  "tool_input": {"file_path": "test.ts"},
  "tool_output": {"success": true}
}' | node plugin/scripts/save-hook.js

# Test with actual Claude Code
claude --debug
/hooks  # View registered hooks
# Submit prompt and watch debug output

​

Performance Considerations

​

Hook Execution Time

• 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 runs once per Claude Code launch, so this never lands on 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

• Indexes on project, created_at_epoch, claude_session_id
• FTS5 virtual tables for full-text search
• WAL mode for concurrent reads/writes

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

• Process observations sequentially (simpler, more predictable)
• Skip low-value observations (TodoWrite, ListMcpResourcesTool)
• Batch summaries (generate every N observations, not every observation)

• Parallel processing (multiple workers)
• Smart batching (combine related observations)
• Lazy summarization (summarize only when needed)

​

Security Considerations

​

Hook Command Safety

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

• User prompts (raw text) - v4.2.0+
• Tool inputs and outputs
• File paths read/modified
• Session summaries

• 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

​

API Key Protection

• 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 - Official documentation
• Progressive Disclosure - Context priming philosophy
• Architecture Evolution - v3 to v4 journey
• Worker Service Design - Background processing details