Hooks Architecture

Core principle

Observe the main Claude Code session from the outside, process observations in the background, inject context at the right time. Claude Mem is fundamentally a hook-driven system. Every piece of functionality happens in response to lifecycle events fired by Claude Code. The memory system never interrupts or modifies Claude Code’s behavior — it observes from the outside and provides value through lifecycle hooks.

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

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

Why hooks?

Architectural constraints

Claude Mem had several non-negotiable requirements:

Can’t modify Claude Code — it’s a closed-source binary
Must be fast — hooks can’t slow down the main session
Must be reliable — a failure must not break Claude Code
Must be portable — works on any project without per-project configuration

Claude Code’s hook system provides exactly what’s needed:

Lifecycle events

SessionStart, UserPromptSubmit, PostToolUse, Stop, and SessionEnd cover the full session lifecycle.

Non-blocking

Hooks run independently and don’t block Claude from continuing work.

Context injection

SessionStart hooks can add context to Claude’s initial system prompt via additionalContext.

Tool observation

PostToolUse receives all tool names, inputs, and outputs — the raw material for memory.

How hooks.json is structured

All hook registrations live in a single file at plugin/hooks/hooks.json. Claude Code reads this file at startup and registers the commands to run at each lifecycle event.

{
  "description": "Claude-mem memory system hooks",
  "hooks": {
    "SessionStart": [{
      "matcher": "startup|clear|compact",
      "hooks": [
        { "type": "command", "command": "...", "timeout": 300 },
        { "type": "command", "command": "...", "timeout": 60 },
        { "type": "command", "command": "...", "timeout": 60 }
      ]
    }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "...", "timeout": 60 }] }],
    "PostToolUse":     [{ "matcher": "*", "hooks": [{ "type": "command", "command": "...", "timeout": 120 }] }],
    "Stop":            [{ "hooks": [{ "type": "command", "command": "...", "timeout": 120 }] }],
    "SessionEnd":      [{ "hooks": [{ "type": "command", "command": "...", "timeout": 5 }] }]
  }
}

Key fields:

Field	Purpose
`matcher`	Regex or glob filter on the event subtype. `"startup\|clear\|compact"` means SessionStart fires only for those sources. `"*"` matches any tool name in PostToolUse. Omitting `matcher` means the hook fires unconditionally.
`type`	Always `"command"` for shell commands.
`command`	Shell command to execute. Receives hook data via stdin.
`timeout`	Maximum seconds before Claude Code kills the hook process.

Hook chaining in SessionStart

SessionStart runs three hooks in sequence for the startup|clear|compact source:

smart-install.js — checks and installs dependencies (up to 300s timeout for first-time npm install)
worker-service.cjs start — ensures the Bun worker process is running (60s timeout)
worker-service.cjs hook claude-code context — fetches and injects prior context (60s timeout)

All three run before Claude Code’s session becomes interactive. If any hook times out or exits with a non-blocking error code, Claude Code continues normally.

The 5 lifecycle hooks + smart-install pre-hook

Pre-hook: smart-install (before SessionStart context)

Smart install is not a lifecycle hook — it is a pre-hook script called via command chaining in hooks.json before the context hook runs. When: Claude Code starts with source startup, clear, or compact What it does:

Checks whether dependencies need installation using a .install-version version marker
Only runs npm install when necessary: first-time setup, or when package.json version changed
Provides Windows-specific error messages for missing build tools
Triggers Bun worker service startup

Version caching:

const currentVersion = getPackageVersion();
const installedVersion = readFileSync('.install-version', 'utf-8');

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

Source: scripts/smart-install.js v5.0.3: Version caching reduced SessionStart time from 2–5 seconds (npm install) to ~10ms on cached runs.

Hook 1: SessionStart — context injection

Purpose: Inject relevant context from previous sessions into Claude’s initial prompt When: Claude Code starts (runs after smart-install) What it does:

Extracts the project name from the current working directory
Queries SQLite for recent session summaries (last 10)
Queries SQLite for recent observations (configurable via CLAUDE_MEM_CONTEXT_OBSERVATIONS, default 50)
Formats the results as a progressive disclosure index — titles and metadata, not full content
Outputs to stdout as hookSpecificOutput.additionalContext (silently injected, not shown to user)

Output format:

# [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/hooks/context-hook.ts → plugin/scripts/context-hook.js

Hook 2: UserPromptSubmit — new session

Purpose: Initialize session tracking when the user submits a prompt When: Before Claude processes the user’s message What it does:

Reads the user prompt and session ID from stdin
Creates a new session record in SQLite (idempotent — uses INSERT OR IGNORE)
Saves the raw user prompt for full-text search (v4.2.0+)
Starts the Bun worker service if not already running
Returns immediately — non-blocking

Database operations:

INSERT OR IGNORE INTO sdk_sessions (claude_session_id, project, first_user_prompt, ...)
VALUES (?, ?, ?, ...)

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

Output:

{ "continue": true, "suppressOutput": true }

Source: src/hooks/new-hook.ts → plugin/scripts/new-hook.js

Hook 3: PostToolUse — observation capture

Purpose: Capture tool execution data for asynchronous AI compression When: Immediately after any tool completes (matcher: *) What it does:

Receives tool name, input, and output from stdin
Checks the skip list — discards low-value tools (TodoWrite, AskUserQuestion, ListMcpResourcesTool, SlashCommand, Skill)
Strips privacy tags (<private>...</private>) from input and response
POSTs the observation to the worker via HTTP (fire-and-forget, 2s timeout)
Returns immediately — worker handles AI compression asynchronously

What gets sent to the worker:

{
  "claudeSessionId": "abc123",
  "tool_name": "Edit",
  "tool_input": { "file_path": "/path/to/file.ts", "old_string": "...", "new_string": "..." },
  "tool_response": { "success": true },
  "cwd": "/path/to/project"
}

Output:

{ "continue": true, "suppressOutput": true }

Source: src/hooks/save-hook.ts → plugin/scripts/save-hook.js

Hook 4: Stop — summary generation

Purpose: Generate an AI-powered session summary when Claude stops When: When Claude stops responding (user pauses or stops the session) What it does:

Reads the transcript JSONL file to extract the last user message and last assistant message
Sends a summarization request to the worker via HTTP (fire-and-forget)
Worker queues summarization for the SDK agent asynchronously

Summary structure produced by the worker:

<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>
  </files_read>
  <files_modified>
    <file>path/to/file2.ts</file>
  </files_modified>
  <notes>Additional context</notes>
</summary>

Source: src/hooks/summary-hook.ts → plugin/scripts/summary-hook.js

Hook 5: SessionEnd — cleanup

Purpose: Mark the session as completed when it ends When: Claude Code session closes (not on /clear) What it does:

POSTs a completion request to the worker with the session ID and reason
Worker marks the session as completed in SQLite
Worker broadcasts the session completion event to SSE clients (viewer UI)

Graceful vs. aggressive cleanup (v4.1.0+): Before v4.1.0, SessionEnd sent a DELETE to the worker, immediately killing any in-progress summary generation. Since v4.1.0 the hook simply marks the session complete, allowing the worker to finish processing naturally:

// v3: Aggressive — interrupted summaries
await fetch(`http://localhost:37777/sessions/${sessionId}`, { method: 'DELETE' });

// v4+: Graceful — worker finishes on its own schedule
await db.run(
  'UPDATE sdk_sessions SET completed_at = ? WHERE id = ?',
  [Date.now(), sessionId]
);

Source: src/hooks/cleanup-hook.ts → plugin/scripts/cleanup-hook.js

Exit code strategy

Claude Mem hooks use specific exit codes per Claude Code’s hook contract:

Exit code	Meaning	When Claude Mem uses it
`0`	Success or graceful shutdown	All normal hook completions; worker/hook errors that should not surface to the user
`1`	Non-blocking error	Stderr shown to user, session continues
`2`	Blocking error	Stderr fed to Claude for processing; session pauses

Worker and hook errors exit with code 0 by default to prevent Windows Terminal from accumulating error tab dialogs. The plugin wrapper layer handles restart logic separately.

Stdin / stdout data flow

Every hook receives structured JSON from Claude Code on stdin and writes its response to stdout.

Stdin (hook receives from Claude Code)

{
  "session_id": "claude-session-abc123",
  "cwd": "/path/to/project",
  "hook_event_name": "PostToolUse",
  "tool_name": "Read",
  "tool_input": { "file_path": "/src/index.ts" },
  "tool_response": "file contents..."
}

The exact fields depend on the lifecycle event. session_id and cwd are present for all events.

Stdout (hook sends back to Claude Code)

For most hooks, a simple acknowledgement:

{ "continue": true, "suppressOutput": true }

For SessionStart context injection, a structured output:

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "# [claude-mem] recent context\n\n..."
  }
}

Any output that is not valid JSON is treated as plain text and may be shown in the transcript. Stderr output is logged but does not affect context injection.

Hook timing reference

Event	Timeout	Blocking	Output handling
SessionStart — smart-install	300s	No	stderr (log only)
SessionStart — worker start	60s	No	stderr (log only)
SessionStart — context	60s	No	JSON → `additionalContext` (silent)
UserPromptSubmit	60s	No	stdout → context
PostToolUse	120s	No	Transcript only
Stop	120s	No	Database (async)
SessionEnd	5s	No	Log only

The worker service: why hooks stay fast

Hooks must return in well under a second. AI compression of a single observation takes 5–30 seconds. The solution is a queue-based architecture:

┌─────────────────────────────────────────────────────────┐
│                   HOOK (Fast)                            │
│  1. Read stdin          (< 1ms)                         │
│  2. HTTP POST to worker (< 10ms)                        │
│  3. Return success      (< 20ms total)                  │
└─────────────────────────────────────────────────────────┘
                        ↓ HTTP (fire-and-forget)
┌─────────────────────────────────────────────────────────┐
│                 WORKER (Slow, async)                     │
│  1. Receive observation via HTTP                        │
│  2. Queue for SDK agent processing                      │
│  3. SDK agent calls Claude API (5–30s)                  │
│  4. Parse XML, store compressed observation             │
└─────────────────────────────────────────────────────────┘

The worker is a long-running Express.js server on port 37777, managed by Bun.

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 HTTP POST
  return success();                      // immediate
}

Pattern 2: Queue-based decoupling

Hook (capture) → HTTP POST → Worker queue → SDK agent (process)

Captures and processing are independent. Worker failure doesn’t affect hooks. Retry logic lives in the worker.

Pattern 3: Graceful degradation

try {
  await captureObservation();
} catch (error) {
  console.error('Memory capture failed:', error);
  // Exit 0 — don't break Claude Code
  return { continue: true, suppressOutput: true };
}

Failure modes:

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

Context injection uses an index format, not full observation text:

❌ Old: Load 50 observations upfront    → 8,500 tokens
✅ New: Show index of 50 observations   →   800 tokens
        Agent fetches 2–3 relevant ones →   300 tokens
        Total: 1,100 tokens (87% savings)

Debugging hooks

Debug mode

claude --debug

Example output:

[DEBUG] Executing hooks for PostToolUse:Write
[DEBUG] Found 1 hook commands to execute
[DEBUG] Executing hook command: .../save-hook.js with timeout 60000ms
[DEBUG] Hook command completed with status 0: {"continue":true,"suppressOutput":true}

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_response": {"success": true}
}' | node plugin/scripts/save-hook.js

Common issues

Hook not executing

Symptoms: Hook command never runs.

Open /hooks in Claude Code — is the hook registered?
Check the matcher pattern (case-sensitive regex).
Test the command manually: echo '{}' | node save-hook.js
Verify file permissions (executable bit set?).

Hook times out

Symptoms: Hook execution exceeds timeout, Claude Code kills it.

Check the timeout setting (default 60s, smart-install has 300s).
Identify the slow operation — is it a database call or network request?
Move slow operations to the worker process.
Increase timeout in hooks.json if necessary.

Context not injecting

Symptoms: SessionStart hook runs but prior context is missing.

Check stdout — must be valid JSON, no extra output.
Verify no stderr output is mixed into stdout (npm install logs polluted this in v4.3.0; fixed in v4.3.1).
Check exit code (must be 0).
Confirm hookSpecificOutput.additionalContext is present in the JSON.

Observations not captured

Symptoms: PostToolUse hook runs but no observations appear in the viewer.

Check the observation queue: sqlite3 ~/.claude-mem/claude-mem.db "SELECT * FROM observation_queue"
Verify the session exists: SELECT * FROM sdk_sessions
Check worker status: npm run worker:status
View worker logs: npm run worker:logs

Hook performance measurements

Hook	Average	p95	p99
SessionStart — smart-install (cached)	10ms	20ms	40ms
SessionStart — smart-install (first run)	2,500ms	5,000ms	8,000ms
SessionStart — context	45ms	120ms	250ms
UserPromptSubmit	12ms	25ms	50ms
PostToolUse	8ms	15ms	30ms
SessionEnd	5ms	10ms	20ms

Smart-install is slow only on first run or after a version change. The .install-version marker (v5.0.3) ensures it is skipped on all subsequent startups.

Key takeaways

Hooks are interfaces — they define clean boundaries between Claude Code and the memory system.
Non-blocking is critical — hooks must return fast; the worker does the heavy lifting.
Graceful degradation — the memory system can fail silently without breaking Claude Code.
Queue-based decoupling — capture and processing are independent pipelines.
Progressive disclosure — context injection uses an index-first approach to minimize token cost.
Single responsibility — each hook has one clear purpose.

System Design

Hooks & Lifecycle

Evolution

Hooks Architecture

Hooks Architecture

Core principle

Why hooks?

Architectural constraints

Lifecycle events

Non-blocking

Context injection

Tool observation

How hooks.json is structured

Hook chaining in SessionStart

The 5 lifecycle hooks + smart-install pre-hook

Pre-hook: smart-install (before SessionStart context)

Hook 1: SessionStart — context injection

Hook 2: UserPromptSubmit — new session

Hook 3: PostToolUse — observation capture

Hook 4: Stop — summary generation

Hook 5: SessionEnd — cleanup

Exit code strategy

Stdin / stdout data flow

Stdin (hook receives from Claude Code)

Stdout (hook sends back to Claude Code)

Hook timing reference

The worker service: why hooks stay fast

Design patterns

Pattern 1: Fire-and-forget hooks

Pattern 2: Queue-based decoupling

Pattern 3: Graceful degradation

Pattern 4: Progressive disclosure context

Debugging hooks

Debug mode

Testing hooks manually

Common issues

Hook performance measurements

Key takeaways

Build docs developers (and LLMs) love

System Design

Hooks & Lifecycle

Evolution

​Hooks Architecture

​Core principle

​Why hooks?

​Architectural constraints

Lifecycle events

Non-blocking

Context injection

Tool observation

​How hooks.json is structured

​Hook chaining in SessionStart

​The 5 lifecycle hooks + smart-install pre-hook

​Pre-hook: smart-install (before SessionStart context)

​Hook 1: SessionStart — context injection

​Hook 2: UserPromptSubmit — new session

​Hook 3: PostToolUse — observation capture

​Hook 4: Stop — summary generation

​Hook 5: SessionEnd — cleanup

​Exit code strategy

​Stdin / stdout data flow

​Stdin (hook receives from Claude Code)

​Stdout (hook sends back to Claude Code)

​Hook timing reference

​The worker service: why hooks stay fast

​Design patterns

​Pattern 1: Fire-and-forget hooks

​Pattern 2: Queue-based decoupling

​Pattern 3: Graceful degradation

​Pattern 4: Progressive disclosure context

​Debugging hooks

​Debug mode

​Testing hooks manually

​Common issues

​Hook performance measurements

​Key takeaways

Build docs developers (and LLMs) love

Hooks Architecture

Core principle

Why hooks?

Architectural constraints

How hooks.json is structured

Hook chaining in SessionStart

The 5 lifecycle hooks + smart-install pre-hook

Pre-hook: smart-install (before SessionStart context)

Hook 1: SessionStart — context injection

Hook 2: UserPromptSubmit — new session

Hook 3: PostToolUse — observation capture

Hook 4: Stop — summary generation

Hook 5: SessionEnd — cleanup

Exit code strategy

Stdin / stdout data flow

Stdin (hook receives from Claude Code)

Stdout (hook sends back to Claude Code)

Hook timing reference

The worker service: why hooks stay fast

Design patterns

Pattern 1: Fire-and-forget hooks

Pattern 2: Queue-based decoupling

Pattern 3: Graceful degradation

Pattern 4: Progressive disclosure context

Debugging hooks

Debug mode

Testing hooks manually

Common issues

Hook performance measurements

Key takeaways