Lifecycle Hooks Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Lifecycle Hooks Architecture in claude-mem provides a systematic way to capture, process, and inject persistent memory across AI development sessions. By intercepting key events in the agentic loop—such as prompt submission, tool execution, and session termination—the system ensures that tool usage observations are compressed and stored for future retrieval.
This architecture acts as a bridge between the AI interface (Claude Code or Cursor) and the Worker Service, facilitating a "fire-and-forget" observation pattern that preserves context without blocking the developer's workflow.
Sources: CLAUDE.md:8-10, cursor-hooks/README.md:16-20
Hook Execution Pipeline
The system utilizes five primary lifecycle stages to manage memory. These stages ensure the environment is ready for the session, capture interactions in real-time, and summarize outcomes upon completion.
Lifecycle Stages
| Hook Stage | Purpose | Implementation Scripts |
|---|---|---|
| SessionStart | Initial session setup and resource check. | context-hook.ts, session-init.sh |
| UserPromptSubmit | Capture user intent and inject relevant past context. | user-message-hook.ts, context-inject.sh |
| PostToolUse | Record MCP tool results, shell commands, and file edits. | save-hook.ts, save-observation.sh |
| Summary | Generate concise session summaries and update context. | summary-hook.ts, session-summary.sh |
| SessionEnd | Finalize data storage and cleanup. | save-file-edit.sh |
Sources: CLAUDE.md:12, cursor-hooks/README.md:58-65, scripts/build-hooks.js:18-24
Hook Flow Diagram
The following diagram illustrates how hooks interact with the AI Interface and the centralized Worker Service.
The lifecycle starts with session initialization and ends with a summary that updates the rule files for the next session.
Sources: cursor-hooks/README.md:67-85, src/services/worker/README.md:27-38
Core Hook Components
1. TypeScript Hooks (src/hooks/*.ts)
The primary hooks used by Claude Code are written in TypeScript and bundled into standalone ESM executables using esbuild. These hooks handle edge-level processing, including privacy tag stripping, before sending data to the Worker.
- context-hook.ts: Manages the injection of previous memory into the current prompt.
- save-hook.ts: Captures tool inputs and outputs.
- summary-hook.ts: Triggers the SDK Agent to compress the session history.
Sources: scripts/build-hooks.js:18-24, CLAUDE.md:14-16
2. Cursor Bash/PowerShell Hooks (cursor-hooks/*.sh)
For Cursor integration, the system uses shell scripts to bridge the IDE's hook system with the Worker API. These scripts follow a modular design where common utilities (like JSON parsing and health checks) are extracted into common.sh.
Cursor hooks are non-blocking; they perform a health check and send observations asynchronously to ensure the IDE remains responsive even if the worker fails.
Sources: cursor-hooks/REVIEW.md:7-13, cursor-hooks/REVIEW.md:120-135
Data Flow and API Integration
Hooks communicate with the Worker Service via standard HTTP REST endpoints. The architecture emphasizes a "Slim Orchestrator" model where the hooks gather data and the Worker Service performs the heavy AI processing.
Key API Endpoints used by Hooks
| Endpoint | Method | Hook Usage |
|---|---|---|
/api/sessions/init | POST | Called by session-init.sh to register a new conversation. |
/api/context/inject | GET | Called by context-inject.sh to fetch relevant past work. |
/api/sessions/:id/observations | POST | Called by save-observation.sh for tool/shell captures. |
/api/sessions/:id/summarize | POST | Called by session-summary.sh to trigger memory compression. |
/api/readiness | GET | Used by all scripts to verify Worker availability before requests. |
Sources: src/services/worker/README.md:27-40, cursor-hooks/REVIEW.md:38-42
Observation Capture Logic
The save-observation.sh and save-file-edit.sh scripts handle diverse input types from Cursor:
- MCP Execution: Captures tool name, input, and response.
- Shell Execution: Records the command string and its output.
- File Edits: Aggregates an array of edits into a summary observation.
Sources: cursor-hooks/REVIEW.md:61-75, cursor-hooks/README.md:78-83
Build and Deployment
The build process for hooks is managed by scripts/build-hooks.js. It targets Node 18 and produces minified versions of the TypeScript hooks.
Build Configuration
// Example build settings for the worker service and hooks
await build({
entryPoints: ['src/services/worker-service.ts'],
bundle: true,
platform: 'node',
target: 'node18',
format: 'cjs',
outfile: 'plugin/scripts/worker-service.cjs',
minify: true,
banner: { js: '#!/usr/bin/env bun' }
});
Sources: scripts/build-hooks.js:84-102
Summary of Significant Files
- src/services/worker-service.ts: Manages the lifecycle of the background process that hooks communicate with. It handles PID file management and port binding. src/services/worker-service.ts:30-45
- cursor-hooks/common.sh: Contains critical utility functions like
ensure_worker_runningandjson_getwhich ensure reliability across all hook scripts. cursor-hooks/REVIEW.md:28-36 - plugin/hooks/hooks.json: Defines the mapping between Cursor IDE events and the specific hook scripts to be executed. cursor-hooks/README.md:120-138
The Lifecycle Hooks Architecture is essential for the "persistent memory" feature of claude-mem, providing the necessary hooks to ensure that no relevant development data is lost between sessions. It maintains high performance through non-blocking operations and ensures reliability with robust health checks and error handling.
Sources: CLAUDE.md:8-10, cursor-hooks/REVIEW.md:118-125