claude-mem

Captures tool usage observations at five discrete lifecycle points (SessionStart, UserPromptSubmit, PostToolUse, Summary, SessionEnd) via CLAUDE.md plugin hooks registered with Claude Code. Each hook fires at specific moments in the agent's execution flow, collecting raw tool invocations, outputs, and user interactions without requiring manual instrumentation. The system queues observations asynchronously and routes them to a worker service for processing.

Extracts and compresses raw tool observations into structured, semantically meaningful summaries using Claude 3.5 Sonnet, Haiku, or other models via Claude Agent SDK, Gemini, or OpenRouter. The system implements agent selection with fallback logic—if the primary provider fails, it automatically retries with a secondary provider. Compression happens asynchronously in a worker service queue, preventing blocking of the IDE during AI processing.

Implements a hierarchical configuration system where settings are resolved in priority order: environment variables (highest), .claude-mem/config.json, .claude-mem/.env, and hardcoded defaults (lowest). This allows users to configure the system via environment variables (for CI/CD), config files (for projects), or defaults (for simplicity). The system supports configuration for AI providers, database paths, privacy controls, and token budgets. Configuration is validated on startup and errors are reported clearly.

Provides a web-based UI (accessible via localhost) for viewing observations, searching memory, and managing settings. The UI uses Server-Sent Events (SSE) for real-time updates, allowing the browser to receive notifications when new observations are captured or processed. The UI includes a settings modal for configuring privacy controls, AI providers, and token budgets. Component architecture separates concerns (search, timeline, settings) into reusable React components.

Implements a batch processing system (Ragtime) that compresses multiple observations in parallel, optimizing for throughput over latency. The batch processor groups observations by session, submits them to the AI API in batches, and persists results to SQLite/ChromaDB. This is useful for backfilling observations from previous sessions or processing high-volume observation streams. Batch processing is configurable (batch size, parallelism) and can be triggered manually or scheduled.

Persists compressed observations in two complementary stores: SQLite (~/.claude-mem/claude-mem.db) for structured relational data with schema migrations, and ChromaDB (~/.claude-mem/vector-db) for semantic vector embeddings. The system maintains schema consistency through migrations, syncs embeddings via ChromaSync operations, and enables both SQL queries (for exact matches, filtering) and vector similarity search (for semantic retrieval). Data flows from observation compression → SQLite insert → ChromaDB embedding sync.

Implements a three-layer search workflow that progressively discloses context to optimize token usage: Layer 1 (fast metadata filtering) uses SQLite queries to narrow candidates by timestamp, file path, or tags; Layer 2 (semantic search) queries ChromaDB for vector similarity to the user's query; Layer 3 (context assembly) constructs the final MEMORY.md with ranked results. The system uses progressive disclosure—it starts with minimal context and expands only if the agent requests more, reducing token overhead for simple queries.

Generates a structured MEMORY.md file containing compressed observations, ranked by relevance, and injects it into Claude Code's context at session start via the SessionStart hook. The MEMORY.md format includes observation summaries, metadata (timestamps, file paths, tool names), and optional tags. The system uses a Context Builder Pipeline to assemble MEMORY.md from search results, ensuring consistent formatting and token budgeting.

A central Express-based HTTP API server (port 37777) managed by Bun that handles asynchronous observation processing, session management, and queue orchestration. The worker service exposes endpoints for session creation, observation submission, search queries, and context generation. It implements a queue architecture where observations are enqueued, processed by AI agents, and persisted to SQLite/ChromaDB. The service manages process supervision, crash recovery, and lifecycle state transitions.

Exposes claude-mem functionality as Model Context Protocol (MCP) tools that can be called by Claude Desktop or other MCP-compatible clients. The system registers tools for session search, context generation, and observation retrieval via an MCP server. Tools use a schema-based function registry that maps tool names to handler functions, enabling Claude to call memory operations directly without IDE integration. The MCP server runs alongside the worker service and communicates via stdio or HTTP.

Manages two types of session identifiers: IDE session IDs (ephemeral, tied to IDE instance lifetime) and logical session IDs (persistent, tied to project or time period). The Timeline Service uses temporal metadata (start time, end time, duration) to enable filtering observations by time ranges, enabling queries like 'show me work from last Tuesday' or 'observations from the past 3 hours'. Session duality allows observations from multiple IDE sessions to be grouped into a single logical session for context assembly.

Implements process supervision and crash recovery mechanisms to ensure observations are not lost if the worker service or IDE plugin crashes. The system uses a combination of in-memory queues with periodic SQLite checkpoints, process supervision (Bun manages worker service restarts), and graceful shutdown handlers. If a crash occurs, the system recovers by replaying queued observations from SQLite on restart. Lifecycle hooks are re-registered on IDE restart, ensuring no observations are missed.

Stores all observations locally in ~/.claude-mem (SQLite + ChromaDB) by default, ensuring no data leaves the user's machine without explicit consent. The system provides optional cloud sync via OpenClaw Gateway or other integrations, but this is disabled by default. Users can configure privacy controls (e.g., exclude certain file paths, redact sensitive data) via configuration files. The architecture is designed for air-gapped environments where cloud connectivity is not available or desired.