Introducing a new way to review your PRs.

Read the announcement

thedotmack / claude-mem

Persistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More

View on GitHub

47 documents · Updated Nov 20, 2026

docs / distribution-integrations

Agent integrations and distribution

Claude-Mem is distributed as an npm package with a command-line installer and host-specific agent assets. It connects one memory service to coding agents and editors through hooks, plugins, MCP tools, or generated context files while keeping installation state separate from stored memory.

Product distribution model

npm package boundary

The package has two roles. The claude-mem command installs, repairs, updates, diagnoses, and removes integrations. The packaged plugin supplies the host-facing hooks, skills, MCP server, runtime services, viewer assets, and native host bundles. A global npm install makes the command available, but it does not register hooks or start the worker.

The published package also carries independent bundles for hosts such as OpenClaw, OMP, Hermes, ODS, Pi, DeepSeek Harness, Qoder, Gemini CLI, Codex CLI, and T3 Code. The build checks that these assets and their launch data form a usable package before publication.

References: package.json• L29-75 scripts/build-hooks.js• L455-572 scripts/check-postinstall-allowlist.js• L1-19

Host metadata

Plugin manifests and marketplace entries tell each host what Claude-Mem provides. Claude Code uses marketplace metadata. Codex uses a local marketplace plus user-level hooks. Other hosts use their own plugin, hook, MCP, provider, gateway, or native-harness contract.

The installer keeps the package identity and version aligned across the root package and copied host assets. It also detects installed hosts so an operator can select one or more integrations instead of enabling every host found on the machine.

See Plugin hooks and agent modes, Cursor integration, Grok Bot integration, Cowork integration, OpenClaw integration, Native harness integrations, Hermes integration, ODS native integration, Eve integration, and Additional agent integrations for host contracts.

References: .claude-plugin/marketplace.json• L9-21 .claude-plugin/plugin.json• L1-24 .codex-plugin/plugin.json• L1-45 src/…/ide-detection.ts• L56-189 src/…/CodexCliInstaller.ts• L605-663

Marketplace synchronization

Local development can mirror the checkout into the Claude marketplace and a versioned plugin cache. This gives local runs the same package shape and dependencies as a published install. The sync protects a local beta branch from an accidental overwrite unless the operator forces the replacement.

References: scripts/sync-marketplace.cjs• L53-69 scripts/sync-marketplace.cjs• L82-127

Installation lifecycle

Installer stages

The npx installer turns a package download into one or more host-ready integrations. It detects hosts, accepts interactive or flag-based choices, prepares a worker or server runtime, installs runtime tools, copies package assets, and dispatches each selected host installer.

The normal sequence is:

  1. Detect supported hosts and select one or more integrations.
  2. Select the worker or server runtime and memory provider.
  3. Copy the plugin into the marketplace and versioned cache.
  4. Prepare Bun and, when needed, uv and parser support.
  5. Write host registration, hooks, MCP settings, or context files.
  6. Start the selected local service unless auto-start is disabled.

The installer records each host result. A failed host does not hide successful hosts in a multi-host install. If every selected host fails, the install reports failure instead of claiming completion.

The diagram shows how one package becomes one or more host integrations.

flowchart TD
    A[npx claude-mem install] --> B[Detect and select hosts]
    B --> C[Select runtime and provider]
    C --> D[Copy package and cache assets]
    D --> E[Prepare runtime tools and dependencies]
    E --> F[Write host registration]
    F --> G{Runtime}
    G -->|Worker| H[Start local worker]
    G -->|Server| I[Use server endpoint]
    H --> J[Host loads memory integration]
    I --> J

References: src/…/index.ts• L26-50 src/…/ide-detection.ts• L56-189 src/…/install.ts• L3318-3497

Runtime and settings state

Worker integrations use a local service. Server integrations use an HTTP service and its MCP endpoint. The installer rejects server mode for worker-only hosts such as Pi and DeepSeek Harness, while non-interactive server setup records the endpoint and prints the command needed to bring up the service stack.

Host registration and Claude-Mem settings are separate. Registration tells a host where to find the integration and which events or tools to expose. Settings hold the provider, model, runtime, server endpoint, worker port, and optional sharing or external-service choices. Secret-bearing files are written with owner-only permissions, and unrelated host settings remain in place.

The local data directory stores memory, logs, settings, telemetry consent, and runtime state. Removing host wiring does not remove stored memory by default.

References: src/…/install.ts• L1116-1144 src/…/install.ts• L1197-1290 src/…/install.ts• L3345-3497 src/…/uninstall.ts• L527-545

Runtime prerequisites

The installer checks the tools needed by the selected runtime. It installs or locates Bun for the local service, can prepare uv for vector search, installs runtime dependencies, provisions the parser used by file reads, and places a stable claude-mem launcher on PATH for later host hooks.

Setup markers record package and tool versions. Repair uses these markers to find an incomplete dependency setup. The doctor command is read-only and reports plugin, dependency, launcher, parser, worker, provider, update, and backup state.

References: src/…/setup-runtime.ts• L16-43 src/…/setup-runtime.ts• L229-562 src/…/npm-install-helper.ts• L109-205 src/…/doctor.ts• L1092-1257

Browser setup handoff

The browser setup flow gives an interactive user a guided choice between local use and hosted setup. The installer starts the worker first, opens a setup URL, and uses worker setup state as the handoff instead of passing secrets through the terminal.

An agent-run install can defer this flow. It prints a command that a person can resume in an interactive terminal. The terminal waits for browser setup and background import work before applying settings that require a worker restart.

References: src/…/browser-setup.ts• L21-57 src/…/browser-setup.ts• L96-289 src/…/install.ts• L3544-3599

Memory import workflows

The CLI can import existing memories from Mem0 or Supermemory without using a model. It reads every source page and validates the complete result before writing local records. Imported records keep source identity and provenance, and an optional platform value places them where the target host can find them.

The workflow supports dry runs, record limits, request timeouts, document import from Supermemory, lifecycle filtering, size checks, and stable fingerprints. A retry recognizes records already saved instead of creating duplicates. Source credentials are used for the vendor read and are not sent to the local worker.

References: src/…/import-memory.ts• L1-13 src/…/import-memory.ts• L171-205 src/…/import-memory.ts• L208-259 src/…/import-memory.ts• L262-343 src/…/import-memory.ts• L347-389

Team sharing configuration

TeamBrain is an optional cloud-sharing layer. A user joins or creates a team through the browser, then chooses all projects, named projects, or no projects to share. Local memory remains on the install while selected observations become available to teammates.

One install stays bound to one sync account. Join and leave refuse to overwrite unreadable settings or silently switch accounts. When the sync connection changes, the command restarts a running worker and waits for the worker to report its new state.

The command surface is teambrain start, join, status, share, and leave. Sharing changes the TeamBrain membership only; it does not change observer or provider settings.

References: src/…/teambrain.ts• L1-17 src/…/teambrain.ts• L203-228 src/…/teambrain.ts• L552-649 src/…/teambrain.ts• L705-813

Anonymous telemetry is enabled by default and uses a random install identifier. Users can inspect, enable, or disable it with telemetry status, telemetry enable, and telemetry disable. CLAUDE_MEM_TELEMETRY=0 and DO_NOT_TRACK=1 opt out.

Events contain coarse versions, platform facts, operation outcomes, counts, and timing. They do not contain prompts, source code, file paths, project names, search queries, IP addresses, or environment values. Status is read-only and does not create a consent file.

References: src/…/telemetry.ts• L1-7 src/…/telemetry.ts• L22-159 src/…/telemetry.ts• L161-237

Host integration models

Lifecycle hook integrations

Lifecycle hook integrations connect host events to the shared memory service. A host adapter maps its event payloads into common session, prompt, tool, and transcript concepts. Shared handlers then load context, record activity, or request summaries while each host keeps its own event names and output rules.

Hook calls are bounded and fail open. Invalid input becomes a harmless no-op, and a worker or server failure does not block the agent action. Write events use a durable handoff so later worker work can recover an event that could not be processed immediately.

For event mapping and hook contracts, see Plugin hooks and agent modes. For editor setup, see Cursor integration. For host variants, see Additional agent integrations. For command-line setup, see Installation and npx CLI.

References: src/…/types.ts• L1-75 src/…/index.ts• L22-172 plugin/…/hooks.json• L1-89 plugin/…/codex-hooks.json• L1-67 src/…/CodexCliInstaller.ts• L542-621

Context and memory flows

Session-start and prompt events request project context. Tool and file events record observations. Stop and compaction events send the last assistant turn for summary and can capture deliverables. The same handlers work with a local worker or a server runtime.

Some hosts use a derived context file because they cannot inject passive hook output into the model. Refreshes are tied to stored summaries and use a per-file publish order, so an older request that finishes late cannot replace newer usable context. A failed refresh leaves the previous file in place.

References: src/…/context.ts• L149-351 src/…/summarize.ts• L104-175 src/…/context-refresh.ts• L3-29 src/…/CursorHooksInstaller.ts• L44-71

Project context files

Claude-Mem can materialize recent activity into project CLAUDE.md files. The generated block is marked and scoped so later runs replace only Claude-Mem content. User-authored content outside that block remains unchanged.

The file is a derived view of stored observations. It complements live hook or MCP access and can be regenerated or cleaned without changing the memory store.

References: scripts/regenerate-claude-md.ts• L56-159 scripts/regenerate-claude-md.ts• L239-348 src/…/claude-md-commands.ts• L138-156 src/…/claude-md-commands.ts• L379-527

File-based agent integrations

File-based integrations serve hosts that read project files but do not provide usable hooks, MCP, or plugin APIs. They provide recalled context at session start and keep generated files outside normal source control.

Aider adds a managed memory file to the project's .aider.conf.yml read: list. aider sync refreshes it from the worker, so Aider receives recall but does not capture transcripts automatically. Grok Build uses a project rules file because passive hook output is not injected into the model; the file refreshes after summaries and is read by the next trusted session. Both integrations preserve user configuration and use project-scoped install, status, refresh, and uninstall behavior.

References: src/…/AiderInstaller.ts• L1-23 src/…/AiderInstaller.ts• L513-657 src/…/GrokBuildRules.ts• L16-36 src/…/GrokBuildRules.ts• L146-185 src/…/GrokBuildRules.ts• L188-243

Plugin integrations

Plugin integrations let a host load a packaged extension that can combine memory tools with lifecycle events. OpenCode receives a plugin bundle and registration. OpenClaw receives a memory extension and optional skills. Hermes receives a memory provider and MCP search entry when full provider setup is selected.

Hermes also supports an MCP-only connection. That mode adds search for one project without selecting Claude-Mem as Hermes's automatic memory provider. A receipt records owned changes so uninstall can restore the earlier provider and remove only the Claude-Mem MCP entry. T3 Code uses its existing Claude and Codex provider homes rather than creating a separate memory store.

The separate Cowork marketplace entry supports Claude app cloud sessions. Grok Bot uses transcript watching and a bounded derived index. Its optional brainbeat path sends matching observations to an external receiver without blocking capture.

References: src/…/OpenCodeInstaller.ts• L127-207 src/…/OpenClawInstaller.ts• L133-252 src/…/HermesInstaller.ts• L21-35 src/…/HermesInstaller.ts• L127-229 src/…/T3CodeInstaller.ts• L243-365 src/…/GrokBotBrainbeat.ts• L73-126

Hermes command workflow

Hermes setup is exposed as a separate CLI workflow. Full install adds the packaged provider and search server. MCP-only install requires an absolute project directory and leaves the active Hermes memory provider unchanged.

Hermes configuration edits preserve comments and unrelated YAML lines. Unsupported or ambiguous config shapes are rejected before the file changes. The uninstall receipt controls what can be restored, so a user-owned provider or MCP entry is not silently removed.

References: src/…/hermes.ts• L5-49 src/…/hermes-config-yaml.ts• L1-12 src/…/hermes-config-yaml.ts• L159-277 src/…/HermesInstaller.ts• L158-228

Native harness integrations

Native harness integrations adapt the memory service to hosts that register tools, skills, and lifecycle callbacks. DeepSeek Harness and Pi keep their own session and turn contracts while using the shared worker address.

DeepSeek Harness offers staged search, timeline and observation tools, saving, and optional capture. Pi loads project context at session start and orders writes around its persisted user-turn identity. These integrations favor safe recall and explicit capture choices rather than changing the host's own turn behavior.

See Native harness integrations for the wider native-host model.

References: scripts/build-hooks.js• L458-460 scripts/build-hooks.js• L1105-1114 src/…/index.ts• L1-103 src/…/index.ts• L81-310

MCP-only integrations

MCP-only integrations expose search tools and an optional starter context file. They do not capture the host transcript or tool activity because the host does not expose a compatible lifecycle interface.

Copilot CLI, Copilot in VS Code, Roo Code, Warp, Goose, and Zed use host-specific configuration formats. Antigravity is a full hooks-plus-MCP integration rather than an MCP-only one. Installers merge only the owned entry and preserve unrelated settings. They use absolute command and server paths so the host can start the packaged server without plugin-root variable expansion.

References: src/…/McpIntegrations.ts• L17-120 src/…/McpIntegrations.ts• L289-343 src/…/McpIntegrations.ts• L345-389 src/…/McpIntegrations.ts• L652-771 src/…/AntigravityCliHooksInstaller.ts• L502-585

Host path adaptation

Each host resolves the MCP server and worker through its own launcher rules. Hosts that do not expand package variables receive absolute paths. Platform-specific command lookup also accounts for Node, Bun, shell shims, and host profiles.

This lets the same service run from a marketplace cache, local checkout, or versioned plugin cache. It prevents a host from accepting a configuration that later fails because its launcher cannot resolve the command.

References: src/…/install-paths.ts• L31-102 src/…/McpIntegrations.ts• L17-20 src/…/CursorHooksInstaller.ts• L139-150 src/…/CodexCliInstaller.ts• L160-193

External notification integrations

External integrations send selected memory outside the local host. Notion exports observations through a bounded asynchronous queue with deduplication and retry. Telegram sends a short session wrap-up after a summary exists and removes sensitive file names before delivery.

These integrations fail independently of capture. Network errors, rate limits, invalid credentials, and full queues produce a log or skipped delivery instead of blocking an agent hook.

See External notification integrations for setup and delivery rules.

References: src/…/NotionExporter.ts• L14-52 src/…/NotionExporter.ts• L315-425 src/…/TelegramWrapupNotifier.ts• L118-175 src/…/telegram-transport.ts• L13-40

Build and validation flows

Distribution build

The distribution build turns source services into host-ready bundles and copies host assets into the package boundary. It builds the worker, server, MCP server, context and transcript services, hook launcher, installer, viewer, and native host extensions.

It checks required files, host events, marketplace source paths, generated hook commands, syntax, and leaked build paths. A missing or corrupt bundle fails release validation instead of reaching users through an incomplete npm package.

References: scripts/build-hooks.js• L455-572 scripts/build-hooks.js• L965-1114 scripts/build-hooks.js• L1126-1228 package.json• L72-75

Server operations

The server runtime separates HTTP reads and writes from queued observation generation. Postgres is the canonical job history. BullMQ is an optional transport and can be inspected as a best-effort comparison.

The operator CLI can show scoped queue state, list failed jobs, retry failed or cancelled jobs, and cancel queued or processing jobs. Team or project scope is required unless the operator explicitly enables admin scope. Retry and cancel write audit and lifecycle records while queue changes remain best effort so Postgres can reconcile the transport.

References: src/…/server.ts• L16-115 src/…/server-jobs.ts• L7-19 src/…/server-jobs.ts• L46-115 src/…/server-jobs.ts• L205-388

Updates and removal

Repair and upgrade behavior

An update replaces installed package assets and refreshes host registration while keeping the saved setup. Repair repeats runtime setup, dependency installation, parser provisioning, and launcher placement when package files are newer than the ready runtime marker.

Automatic update state records the target version, decision, attempt stage, and outcome. doctor exposes that state. Claude Code marketplace updates remain a separate setting so one updater cannot disable the only working update path.

See Installation and npx CLI for command behavior and Automatic update lifecycle for update state and recovery rules.

References: src/…/index.ts• L204-221 src/…/install.ts• L1007-1038 src/…/install.ts• L3462-3554 src/…/doctor.ts• L598-758

Uninstall boundaries

Uninstall stops local services, removes marketplace and cache registrations, disables host integrations, removes the installed launcher, and removes only Claude-Mem-managed sections from shared configuration. Project-scoped Aider and Grok Build files use their own uninstall commands.

The data directory is preserved. This lets an operator remove agent wiring without losing the memory store, logs, settings, telemetry consent, or backup state needed for a later reinstall.

References: src/…/uninstall.ts• L300-377 src/…/uninstall.ts• L380-545 src/…/AiderInstaller.ts• L659-693 src/…/GrokBuildRules.ts• L188-212

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep package metadata, marketplace entries, plugin manifests, published host assets, and standalone packages aligned.
  • Keep the package allowlist aligned with every bundle, UI asset, native harness, and host installer input.
  • When a hook or MCP command changes, check host path rules, launch behavior, generated templates, and runtime time limits.
  • When a host payload or output contract changes, update its adapter, shared hook types, handler mapping, and host definition together.
  • When settings change, check install, browser setup, repair, runtime selection, doctor, TeamBrain, external integrations, and uninstall as one contract.
  • When a host config changes, preserve unrelated user entries and make install, status, repair, and uninstall use the same ownership marker or receipt.
  • When a derived context refresh changes, keep publish ordering, exclusion handling, uninstall races, and stale-file behavior aligned.
  • When Hermes changes, keep full-provider and MCP-only ownership separate and keep YAML shape checks consistent with receipt-based uninstall.
  • When MCP-only support changes, keep the no-transcript boundary and each host's config key and path rules aligned.
  • When server jobs change, keep Postgres scope checks, lifecycle events, audit records, BullMQ reconciliation, retry idempotence, and cancellation guards aligned.
  • When memory import changes, keep vendor pagination, lifecycle filtering, provenance fingerprints, platform routing, size limits, and retry deduplication aligned.
  • When a native harness bundle changes, keep its worker address, host contract, tool schemas, skill guidance, attribution files, version metadata, and build output aligned.

Important failure modes

TriggerConsequenceGuard
Running npm install -g claude-mem instead of an integration installThe command is available, but hooks, registration, and the worker are not set up.Use npx claude-mem install or the host marketplace flow.
Bun or uv cannot be found after setupA worker install stops or vector search is unavailable.Use the installer's platform remediation and rerun setup.
A host cannot resolve a package-root variableThe configured MCP server or worker cannot start.Use installer-managed absolute paths for that host.
A worker or server is unavailable during a hook time budgetThe agent action continues, but context or capture can be delayed or absent.Use bounded calls, fallback, durable handoff, and later recovery.
A selected host fails during a multi-host installSome integrations are ready while another is incomplete.Read per-host results and rerun the failed host.
Strict marketplace npm install fails for a reason other than a peer conflictThe runtime remains incomplete.Abort unrelated failures; use the legacy peer-dependency fallback only for a confirmed peer conflict.
Codex points to a moved or incomplete local marketplaceCodex can stop loading all marketplaces.Remove the stale registration and rerun the Codex installer.
Hermes config has an unsupported YAML shapeHermes config is left unchanged and the integration is incomplete.Use block-style mappings and rerun setup.
Hermes MCP-only setup finds an existing unowned MCP entry or active Claude-Mem providerSetup refuses to replace another owner or silently enables capture.Remove the conflicting entry or provider by hand, then rerun the intended mode.
An MCP-only host is expected to capture transcriptsSearch works, but automatic capture does not.Keep explicit capture through a hook-capable host.
A shared host config is malformedThe installer refuses to overwrite it, so that host remains partly configured.Repair the config and rerun installation.
A Cursor, Aider, Grok Build, Hermes, Goose, or Zed refresh finishes after uninstall or after a newer refreshOld context can return or replace newer context.Unregister before removal and publish only the newest usable response.
A server job is operated without a team or project scopeAn operator can affect jobs outside the intended area.Require --team or --project, or set the explicit admin flag.
A server retry updates Postgres but queue republish failsThe job is recorded as queued but may wait for reconciliation.Keep Postgres canonical and reconcile the transport on startup.
A memory import sees changed totals, duplicate IDs, invalid lifecycle data, or an oversized sourceNo unsafe partial import is accepted, or the import stops before all planned notes are saved.Retry against a quiet source, narrow the limit, and validate with dry run first.
Uninstall is treated as data deletionStored memory is lost even though only host wiring needed removal.Treat the data directory as separate and preserved.

Key files

FileWhy to read it
package.jsonDefines the npm command, package boundary, published assets, standalone host packages, build lifecycle, and install policy.
scripts/build-hooks.jsShows how runtime bundles, host launch files, native harness bundles, and distribution checks are produced.
.claude-plugin/marketplace.jsonDefines marketplace entries for the main plugin and Cowork.
.codex-plugin/plugin.jsonDefines Codex skills, MCP server, hooks, and prompts.
src/…/index.tsDefines the public install, repair, update, uninstall, import, TeamBrain, telemetry, server, and host command surface.
src/…/ide-detection.tsDefines supported host detection and the integration model shown to the operator.
src/…/install.tsDefines host selection, runtime preparation, browser setup, dependency checks, and host dispatch.
src/…/hermes.tsDefines the explicit Hermes full-install and MCP-only command boundary.
src/…/import-memory.tsDefines safe model-free import and its provenance, size, and retry boundary.
src/…/teambrain.tsDefines account-safe team join, project sharing, worker restart, and leave behavior.
src/…/server-jobs.tsDefines scoped server queue inspection and operator retry or cancel behavior.
src/…/telemetry.tsDefines telemetry consent, status, opt-out, and the data boundary.
src/…/CodexCliInstaller.tsShows native Codex marketplace registration, stale-source repair, user-level hooks, and legacy cleanup.
src/…/CursorHooksInstaller.tsShows a hooks-plus-MCP editor integration with project context support and shared-hook preservation.
src/…/context-refresh.tsDefines ordered derived-context publication for overlapping refreshes.
src/…/AiderInstaller.tsShows project-scoped file context and explicit refresh without automatic capture.
src/…/GrokBuildRules.tsDefines Grok Build rules files, refresh registration, exclusions, and project cleanup.
src/…/HermesInstaller.tsShows Hermes provider, MCP-only setup, receipts, and ownership-aware cleanup.
src/…/hermes-config-yaml.tsDefines the safe, comment-preserving Hermes YAML edit boundary.
src/…/McpIntegrations.tsShows the common MCP-only model and host-specific JSON, JSONC, and YAML boundaries.
src/…/NotionExporter.tsDefines bounded asynchronous export, deduplication, rate limits, and retries.
src/…/TelegramWrapupNotifier.tsDefines project-routed wrap-ups, privacy filtering, and sent-state handling.
src/…/uninstall.tsDefines host cleanup and the boundary that preserves local memory data.