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

User Query → mem-search Skill Invoked → HTTP API → SessionSearch Service → FTS5 Database → Search Results → Claude

┌─────────────────────────────────────────────────────────────────┐
│ 0. Smart Install Pre-Hook Fires                                 │
│    Checks dependencies (cached), only runs on version changes   │
│    Not a lifecycle hook - runs before context-hook starts       │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 1. Session Starts → Context Hook Fires                          │
│    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    │
└─────────────────────────────────────────────────────────────────┘

claude-mem/
├── src/
│   ├── hooks/                  # Hook implementations (6 hooks)
│   │   ├── context-hook.ts     # SessionStart
│   │   ├── user-message-hook.ts # UserMessage (for debugging)
│   │   ├── new-hook.ts         # UserPromptSubmit
│   │   ├── save-hook.ts        # PostToolUse
│   │   ├── summary-hook.ts     # Stop
│   │   ├── cleanup-hook.ts     # SessionEnd
│   │   └── hook-response.ts    # Hook response utilities
│   │
│   ├── sdk/                    # Claude Agent SDK integration
│   │   ├── prompts.ts          # XML prompt builders
│   │   ├── parser.ts           # XML response parser
│   │   └── worker.ts           # Main SDK agent loop
│   │
│   ├── services/
│   │   ├── worker-service.ts   # Express HTTP + SSE service
│   │   └── sqlite/             # Database layer
│   │       ├── SessionStore.ts # CRUD operations
│   │       ├── SessionSearch.ts # FTS5 search service
│   │       ├── migrations.ts
│   │       └── types.ts
│   │
│   ├── ui/                     # Viewer UI
│   │   └── viewer/             # React + TypeScript web interface
│   │       ├── components/     # UI components
│   │       ├── hooks/          # React hooks
│   │       ├── utils/          # Utilities
│   │       └── assets/         # Fonts, logos
│   │
│   ├── shared/                 # Shared utilities
│   │   ├── config.ts
│   │   ├── paths.ts
│   │   └── storage.ts
│   │
│   └── utils/
│       ├── logger.ts
│       ├── platform.ts
│       └── port-allocator.ts
│
├── scripts/                    # Build and utility scripts
│   └── smart-install.js        # Cached dependency checker (pre-hook)
│
├── plugin/                     # Plugin distribution
│   ├── .claude-plugin/
│   │   └── plugin.json
│   ├── hooks/
│   │   └── hooks.json
│   ├── scripts/                # Built executables
│   │   ├── context-hook.js
│   │   ├── user-message-hook.js
│   │   ├── new-hook.js
│   │   ├── save-hook.js
│   │   ├── summary-hook.js
│   │   ├── cleanup-hook.js
│   │   └── worker-service.cjs  # Background worker + HTTP API
│   │
│   ├── skills/                 # Agent skills (v5.4.0+)
│   │   ├── mem-search/         # Search skill with progressive disclosure (v5.5.0)
│   │   │   ├── SKILL.md        # Skill frontmatter (~250 tokens)
│   │   │   ├── operations/     # 12 detailed operation docs
│   │   │   └── principles/     # 2 principle guides
│   │   ├── troubleshoot/       # Troubleshooting skill
│   │   │   ├── SKILL.md
│   │   │   └── operations/     # 6 operation docs
│   │   └── version-bump/       # Version management skill (deprecated)
│   │
│   └── ui/                     # Built viewer UI
│       └── viewer.html         # Self-contained bundle
│
├── tests/                      # Test suite
├── docs/                       # Documentation
└── ecosystem.config.cjs        # Process configuration (deprecated)