DOCSEARCHbyAlgolia
Submit Docs

Claude-Mem

repository·main·Indexed 12 days ago

https://github.com/thedotmack/claude-mem

A persistent memory compression system for Claude Code (version 13.15.0) that captures tool usage observations and generates semantic summaries to preserve context across AI sessions. It features a worker service with a web viewer, SQLite and Chroma vector storage, and integration with Cursor via rules and hooks. It also provides MCP tools for token-efficient memory search and a Docker harness for end-to-end testing.

Tokens
213.4K
Snippets
535
Records
884
Agent score
99%

What's inside Claude-Mem

  1. Understand the Installer Failure Transparency Plan

    main

    The claude-mem installer (npx claude-mem install) is undergoing a transition from silent error suppression to an explicit, severity-based error reporting system. The goal is to prevent the installer from falsely reporting "installed successfully" when critical dependencies (like uv, bun, or tree-sitter peer conflicts) fail to install.

    Key changes to the installation experience:

    • Success Reporting: "Installation Complete" will only be displayed if all ABORT-level dependencies are satisfied.
    • Partial Success: If non-critical failures occur, the installer will display a yellow "Installation Partial" headline accompanied by a remediation block.
    • Strict Dependency Resolution: runNpmInstallInMarketplace() will run in strict mode first. The --legacy-peer-deps flag will only be applied if an ERESOLVE token is explicitly detected, and this fallback will be announced to the user.
    • Improved Error Messaging: Failures like a missing uv (after an auto-install attempt) will trigger an ABORT with platform-specific remediation instructions rather than generic error messages.
    • Regression Guards: A CI guard is being implemented to prevent new transitive dependencies with scripts.postinstall or scripts.install from being added unless they are in an explicit allowlist, preventing hangs caused by network-dependent postinstall scripts.

  2. Use the Pathfinder skill for architectural auditing and unification

    main

    The pathfinder skill is an ORCHESTRATOR designed to map a codebase into feature-grouped flowcharts, identify duplicated concerns, and propose a unified architecture. Use this skill when you need to "find the ideal path," unify duplicated systems, or audit architecture before a refactor.

    Key Capabilities:

    • Maps codebases into feature-grouped Mermaid flowcharts.
    • Identifies duplicated logic (both within and across features).
    • Proposes a simplified, unified architecture.
    • Generates ready-to-use /make-plan prompts for implementation.

    Important Limitation: Pathfinder does not write implementation code. It produces diagrams, reports, and handoff prompts. Implementation is handled by /make-plan and /do after Pathfinder completes.

  3. Overview of the Worker Service

    main

    The Worker Service is a long-running HTTP API built with Express.js and managed by Bun. Its primary role is to process observations through the Claude Agent SDK independently from hook execution, which prevents timeout issues during the main application flow.

    Key Technical Details

    • Runtime: Bun (automatically installed if missing).
    • Process Management: Managed natively via Bun's ProcessManager.
    • Default Port: 37700 + (uid % 100). This can be overridden using the CLAUDE_MEM_WORKER_PORT environment variable.
    • Configuration: The active port is stored in ~/.claude-mem/settings.json and can be verified via the /health endpoint.
    • AI Model: Configurable via CLAUDE_MEM_MODEL (defaults to claude-haiku-4-5-20251001).

  4. What is a Mode in Claude-Mem?

    main

    A Mode is a configuration profile that adapts Claude-Mem's behavior, observation types, and output language. It allows you to switch workflows (e.g., coding vs. investigation) or languages without reinstalling the plugin.

    A mode defines four key elements:

    1. Observer Role: The persona Claude adopts (e.g., "Software Engineer").
    2. Observation Types: The valid categories for memory (e.g., "Bug Fix" vs. "Person").
    3. Concepts: Semantic tags used for indexing (e.g., "Pattern").
    4. Language: The language used for generating all memory artifacts like titles, narratives, and summaries.

  5. Overview of Claude-Mem Core Components

    main

    Claude-Mem functions as a persistent memory compression system for Claude Code. Its architecture relies on several key components:

    • Lifecycle Hooks: Uses 5 primary lifecycle hooks (SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd) to capture context.
    • Worker Service: A local HTTP API managed by Bun that provides a web viewer UI and search endpoints.
    • Storage: Uses a SQLite Database for sessions, observations, and summaries, and a Chroma Vector Database for hybrid semantic and keyword search.
    • mem-search Skill: Enables natural language queries for project history using progressive disclosure (layered retrieval).

  6. Manage uv runtime installation and auto-detection

    main

    The installer attempts to ensure uv is available. If uv is missing, it attempts an auto-install.

    Behavioral Rules:

    • Auto-install is one-shot: If the initial installUv() attempt fails, do not loop or retry the installation. Instead, ABORT the process and surface platform-specific remediation instructions (e.g., winget for Windows or curl for Linux).
    • Path Probing: After installation, explicitly probe UV_COMMON_PATHS in case the shell's PATH has not yet updated.
    • Vector Search Opt-out: If the user has set CLAUDE_MEM_DISABLE_VECTOR_SEARCH to true in their settings, a missing uv binary should result in a WARN_CONTINUE (warning only) rather than an ABORT.
    • Version Probing: If the uv binary is found but --version fails, retry once after a 1-second delay to account for filesystem/process latency. If it still fails, treat it as a WARN_CONTINUE with version unknown.
    // Logic for ensuring uv is present
if (!isUvInstalled()) {
  installUv(); // Throws platform-specific error on failure
}

let uvPath = getUvPath() ?? UV_COMMON_PATHS.find(existsSync) ?? null;

if (!uvPath) {
  if (options.allowVectorSearchOptOut && userHasOptedOutOfVectorSearch()) {
    // Downgrade to warning if user opted out of vector search
    return { uvPath: null, version: null };
  }
  // Otherwise, abort with remediation
  installerError(ErrorSeverity.ABORT, ...);
}

  7. Understand the multi-user identity and tenancy model

    main

    The system uses a multi-dimensional identity model to ensure strict data isolation and auditability across teams and projects. Every row in the database is keyed by these dimensions:

    • team_id × project_id: The primary tenant scope. All read queries are scoped to this pair to prevent cross-tenant data leakage.
    • api_key_id: The transport identity. Represents the specific HTTP key used for authentication. Keys are revocable and can be scoped (e.g., memories:write).
    • actor_id: The semantic identity. A human-readable ID (e.g., human:alice@org or system:ci-runner) representing who the API key is acting on behalf of.
    • request_id: A unique identifier minted at the HTTP boundary used for correlating logs, BullMQ payloads, and audit rows.

    Security Enforcement:

    • API Layer: requirePostgresServerAuth validates the X-API-Key or Authorization: Bearer header, checking for existence, revocation, expiration, and required scopes before populating req.authContext.
    • Worker Layer: Background workers do not trust the payload sent via BullMQ. They re-validate the team_id against the canonical record in Postgres to prevent 'poisoned payload' attacks.

  8. How the Search Pipeline works

    main

    The Search Pipeline enables Claude to retrieve specific memories using natural language queries through a 3-layer progressive disclosure model: search → timeline → get_observations.

    1. User Query: The user asks a natural language question (e.g., "What bugs did we fix?").
    2. MCP Tools Invoked: Claude recognizes the intent and invokes the relevant MCP search tools.
    3. HTTP API: The MCP tools call the HTTP endpoint (e.g., /api/search/observations).
    4. SessionSearch: The Worker service queries the FTS5 virtual tables in the SQLite database.
    5. Format & Return: Results are formatted and returned via the MCP server to Claude, who then presents them to the user.
    User Query → MCP Tools Invoked → HTTP API → SessionSearch Service → FTS5 Database → Search Results → Claude

  9. Understand the difference between Rule A, B, and C hook resolution

    main

    The project uses three distinct strategies (Spawn-Contract Rules) for resolving hook paths:

    • Rule A (Generated/Host-Managed): Paths are generated by build scripts (e.g., scripts/build-hooks.js) or managed by the host. These use the ${CLAUDE_PLUGIN_ROOT} placeholder which is substituted at runtime by the host.
    • Rule B (Installer-Managed): Paths are baked in at install-time by installers (e.g., CursorHooksInstaller.ts). These use absolute paths resolved via install-paths.ts helpers.
    • Rule C (Runtime-Resolved): Paths are resolved at runtime by the script itself (e.g., plugin/scripts/bun-runner.js). These often use RESOLVED_PLUGIN_ROOT and include safety mechanisms like fixBrokenScriptPath to handle cases where the host fails to inject the expected environment variables.

  10. Choose a Context Retrieval Strategy

    main

    Select a retrieval strategy based on the nature of your data and the required agent behavior:

    StrategyApproachBest For
    Just-In-Time ContextMaintain lightweight identifiers (file paths, queries, links) and load data dynamically at runtime.Dynamic exploration and progressive disclosure.
    Pre-Inference Retrieval (RAG)Use embedding-based retrieval to surface context before inference.Static content that won't change during interaction.
    Hybrid StrategyRetrieve some data upfront and enable autonomous exploration (e.g., loading CLAUDE.md files while using glob/grep for JIT retrieval).Balancing speed and autonomy.

  11. Configure SessionGenerationPolicy and queue lanes

    main

    The system uses two distinct queue lanes to manage processing workloads:

    • Event lane: Processes per-event observations via /v1/events. This is throughput-heavy and scaled via worker concurrency.
    • Summary lane: Processes session-end summaries via /v1/sessions/:id/end. This handles lower volume but larger payloads (entire session context).

    Control the behavior of these lanes using SessionGenerationPolicy:

    • per-event (default): Every event triggers an immediate event-lane job.
    • debounce: Collapses events within a window using deterministic job IDs. Use delay: <window> to schedule and replace jobs.
    • end-of-session: Skips per-event jobs and only fires the session-end summary job.

  12. How claude-mem manages context and memory

    main

    claude-mem works by converting every Read, Edit, and Bash action performed by Claude into a compressed observation.

    At the end of a session, these observations are summarized. Relevant observations are then automatically injected into future prompts. This allows subsequent sessions to inherit context from previous work without requiring the user to re-explain the codebase or re-discover previous decisions.