Installation and NPX CLI
The claude-mem NPX CLI is the user-facing path to install, configure, operate, repair, diagnose, update, and remove the product. It turns the published npm package into a working agent integration and gives the release process checks that protect the runnable package users receive.
CLI entrypoint
The CLI entrypoint exposes claude-mem through the package bin field. It keeps install and maintenance commands usable with Node alone, then delegates service work to the installed runtime when a command needs the worker or server.
Command routing
The command router treats a bare invocation as an interactive install. It also treats install flags placed directly after claude-mem as install options, while help and version flags remain top-level commands. This makes both npx claude-mem and scripted forms such as npx claude-mem --provider claude predictable.
The public command surface has four broad roles:
- Installation: install, update, repair, prune, and uninstall the product and its host registrations.
- Runtime control: start, stop, restart, inspect, search, and maintain local services.
- Integration utilities: manage hooks, MCP connections, transcripts, project memory, backups, team sharing, and host-specific extensions.
- Server operations: select the server runtime and manage its service, keys, worker, and generation jobs.
Most runtime commands use the installed copy rather than creating a second service implementation in the NPX package. The model-free memory import is a Node-side utility that reads a supported vendor API and sends the planned records to the installed worker. Installation also places a small claude-mem launcher on the user's PATH, which lets host hooks invoke the installed hook command without a shell.
The main operator commands are:
| Command | Product role |
|---|---|
npx claude-mem install or npx claude-mem update | Set up or refresh the package and selected hosts. |
npx claude-mem repair | Rebuild missing package material and runtime dependencies. |
npx claude-mem start, stop, restart, status | Control the local worker. |
npx claude-mem server ... | Control the server runtime, keys, workers, and jobs. |
npx claude-mem search and mcp | Reach search and MCP interfaces. |
npx claude-mem import --from ... | Copy selected memories or documents from a supported memory service. |
npx claude-mem backup ... and restore | Inspect, create, and apply local database snapshots. |
npx claude-mem teambrain ... | Join a team and control which projects it can see. |
npx claude-mem hermes ... | Add or remove the Hermes MCP connection without changing its memory provider. |
npx claude-mem doctor, prune, uninstall | Diagnose, safely trim, or remove the install. |
References: package.json• L28-31 src/…/index.ts• L1-24 src/…/index.ts• L26-104 src/…/index.ts• L176-202 src/…/index.ts• L271-337 src/…/hermes.ts• L5-49 src/…/server.ts• L16-115
Telemetry controls
Telemetry controls let a user view or change anonymous usage analytics without changing product health or runtime state. The setting is enabled by default until the user opts out, and npx claude-mem telemetry status|enable|disable provides the direct control surface.
The choice can also come from CLAUDE_MEM_TELEMETRY or DO_NOT_TRACK. DO_NOT_TRACK has priority. Events use an install identifier and coarse event fields. They exclude prompts, source code, paths, queries, keys, error text, and raw IP addresses. The install flow asks for consent only after successful setup and only in an interactive session. Install telemetry can also record bounded facts such as the package manager that launched the CLI and the detected tool versions.
References: src/…/telemetry.ts• L1-7 src/…/telemetry.ts• L22-88 src/…/telemetry.ts• L101-203 src/…/install.ts• L2470-2502 src/…/install.ts• L3994-4010 src/…/index.ts• L271-275
Installation flow
Installation copies the published product into the selected host locations and connects those hosts to a local worker or a server runtime. It uses packaged build output, so a user does not need the source checkout or a local build.
The terminal setup flow follows this order:
- Show the current install state and identify a first install, update, or repair.
- Select one or more supported hosts. Interactive setup detects likely hosts; scripted setup uses stable host identifiers.
- Select the worker or server runtime.
- Register host integrations and prepare the required runtime tools.
- Complete account pairing when the selected provider needs product services.
- Choose the provider and model, then save the settings.
- Stop the old worker before packaged files or provider settings change.
- Start the worker when automatic start is allowed, or report the server start command.
- Return a complete, partial, or aborted result.
This diagram shows how a published package becomes a working host integration.
flowchart TD
A[Published npm package] --> B[Select hosts and runtime]
B --> C[Register host integrations]
C --> D[Prepare runtime tools and dependencies]
D --> E[Configure provider and account]
E --> F[Stop old worker before cutover]
F --> G{Runtime}
G -->|Worker| H[Start or leave ready]
G -->|Server| I[Record server settings and operator command]
H --> J[Installation result]
I --> J
Host failures remain separate. One failed host can therefore produce a partial install while other selected hosts stay usable. The worker stays stopped while the installed files and settings change, which prevents a running process from using a mixed version.
References: src/…/install.ts• L2963-3026 src/…/install.ts• L3404-3466 src/…/install.ts• L3469-3490 src/…/install.ts• L3743-3777
Browser setup
Browser setup is the guided path for a fresh interactive worker install with no provider or no-autostart flag. The installer starts the worker, opens its local setup page, and waits for the browser to return a setup choice instead of asking every setup question in the terminal.
The browser can select a local path that uses the user's existing agent account or an online path that starts account pairing and checkout. The terminal holds the session open until the browser reports completion. It waits without a fixed time limit and does not restart the worker while extraction or history import is active.
This diagram shows the browser hand-off and the return to the installer.
sequenceDiagram
participant T as Terminal installer
participant W as Local worker
participant B as Browser setup page
T->>W: Start worker and open setup page
B->>W: Choose local or online setup
W-->>T: Report choice and setup progress
T->>B: Open account or checkout page when needed
B->>W: Report completion
T->>W: Restart only when boot-time settings changed
Non-interactive installs and installs with explicit provider, runtime, or autostart choices stay on the terminal path. A fresh agent-run install can print a separate instruction to rerun the worker install in a terminal when browser setup is needed. Deferred setup can save the browser hand-off for a later visit, and the resumed flow accepts a new browser submission before retrying a failed choice.
References: src/…/browser-setup.ts• L16-61 src/…/browser-setup.ts• L63-87 src/…/browser-setup.ts• L104-253 src/…/browser-setup.ts• L255-334 src/…/install.ts• L3469-3490 src/…/install.ts• L3532-3656
Host setup
Host setup maps the shared memory service to each product's extension point. Hook-based hosts receive hook registration, MCP hosts receive an MCP configuration, and transcript-based hosts receive the watcher path they need. Multiple hosts can be selected in one install.
Detection is a convenience rather than the source of truth. It checks host commands, settings folders, and editor extension folders across the supported host set, then defaults to Claude Code when it finds no likely host. The supported set includes Hermes, which can use a memory-provider integration during normal setup or an explicit MCP-only connection when its provider must remain unchanged. Windows command checks avoid treating a same-directory executable as proof that a host is installed. A host identifier must stay consistent across detection, setup, removal, help text, and telemetry.
References: src/…/ide-detection.ts• L14-24 src/…/ide-detection.ts• L26-53 src/…/ide-detection.ts• L56-189 src/…/install.ts• L360-709 src/…/hermes.ts• L5-49 src/…/index.ts• L334-337
Provider and runtime setup
Provider setup connects memory work to a model service and records that choice in user settings. The worker is the local compatibility path for hook and plugin hosts. The server is the shared HTTP path with shared storage, keys, and a separate generation worker.
Interactive terminal setup can pair the device with cmem.ai before it asks which provider to use. The account step proves identity; it does not select a paid memory provider by itself. A CMEM Pro choice can then activate cloud memory credentials, while a TeamBrain seat can provide sync without replacing the existing memory provider. Local Claude, host-observer, Codex, Gemini, and personal OpenRouter paths keep their own credential rules.
Non-interactive setup uses explicit flags where supplied. It can select worker or server, set a server URL, choose a provider, and choose a model. Server setup records the target and prints the Docker command for the operator; it bootstraps a hook key only when the server database URL is available. Pi and DeepSeek Harness currently require the worker runtime.
Provider choice also controls whether account setup is required. Local Claude and host-observer paths can finish without a cmem.ai account. Account-backed providers need browser pairing unless an existing configured account is reused. In a non-interactive run, a saved provider is kept when its required credentials exist; otherwise the installer fails instead of silently switching the product to a different provider.
The server path also supports a direct operator console for the Postgres-backed generation queue. It reports queue state, lists failed jobs, and permits scoped retry or cancel actions. Unscoped actions require explicit admin intent, and operator changes are recorded for later review.
References: src/…/install.ts• L1055-1114 src/…/install.ts• L1694-1701 src/…/install.ts• L2963-3026 src/…/install.ts• L3668-3723 src/…/server-jobs.ts• L7-19 src/…/server-jobs.ts• L46-115 src/…/server-jobs.ts• L205-312 src/…/server-jobs.ts• L314-443
TeamBrain controls
TeamBrain is the shared-memory path for teams. The CLI uses the same browser pairing as account setup, writes the team sync connection, and lets the user choose all projects, named projects, or no projects to share. The user's local memory remains private unless the user changes this sharing choice.
An install keeps one sync account and refuses to replace an existing account with another one. Join and leave protect an unreadable settings file, restart the worker when sync settings change, and settle the local connection after a team is left. A seat-only account loses sync when it leaves its last team; a Pro account keeps its normal sync connection.
References: src/…/teambrain.ts• L1-17 src/…/teambrain.ts• L91-159 src/…/teambrain.ts• L161-227 src/…/teambrain.ts• L552-649 src/…/teambrain.ts• L717-813 src/…/index.ts• L277-281
Runtime dependencies
Runtime preparation makes the installed product usable on a new machine. The installer finds or installs Bun and uv, installs the packaged plugin dependency set with a frozen lockfile, provisions tree-sitter support, and checks that the runtime modules needed by the installed services resolve before a service starts.
Bun is required for hooks and runtime services. uv supports vector search unless the user disables that feature. Tool discovery checks PATH first, then common user and system locations. It also respects environment-directed Bun installs and validates an explicitly configured Codex executable in the same way the worker will run it. A vector-search opt-out lets setup continue without uv.
The cached plugin uses Bun with the frozen lockfile and lifecycle scripts disabled. Marketplace dependencies use a strict npm install with development packages omitted and lifecycle scripts disabled. The installer retries once with --legacy-peer-deps only for a confirmed ERESOLVE peer conflict. Other failures and timeouts abort instead of receiving a broad compatibility retry. The root package keeps dependencies needed by shipped Node artifacts, while the plugin package carries the runtime closure for bundled hooks and services.
References: src/…/setup-runtime.ts• L16-69 src/…/setup-runtime.ts• L143-217 src/…/setup-runtime.ts• L219-284 src/…/setup-runtime.ts• L291-408 src/…/setup-runtime.ts• L411-557 src/…/npm-install-helper.ts• L1-15 src/…/npm-install-helper.ts• L66-75 src/…/npm-install-helper.ts• L93-205 src/…/tool-path.ts• L20-81 src/…/tool-path.ts• L93-141
Claude Code memory choice
Claude Code setup preserves native auto-memory unless the user explicitly chooses to disable it. If the user makes that choice, installation changes only the host setting that controls native auto-memory.
Removal reverses that setting only when its value is still the value written by the installer. The shared cleanup utility removes only CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 and drops an empty environment block, so a later user change and other host settings remain intact.
References: src/…/install.ts• L282-357 src/…/install.ts• L3497-3532 src/…/claude-auto-memory.ts• L1-8 src/…/uninstall.ts• L131-158
Claude Code hook compatibility
Claude Code hooks use the persistent claude-mem launcher in exec form. The installer checks the host version because hook arguments require Claude Code 2.1.139 or newer; an older host can run the launcher without the event arguments and capture nothing.
The check is advisory when the version is missing or cannot be parsed. When an older version is known, the installer and doctor show the required update instead of treating the whole installation as invalid.
References: src/…/claude-code-version.ts• L11-17 src/…/claude-code-version.ts• L19-75 src/…/install.ts• L3291-3294 src/…/doctor.ts• L860-877
Runtime utilities
After setup, the CLI is a control layer over the installed services. It checks the installed product, finds the runtime, selects the worker or server boundary, and preserves the service result and exit status.
The worker commands run the installed service with a controlled environment and with Bun's automatic package install disabled. This keeps runtime dependency choice tied to the install rather than to a package lookup that can select an unsuitable native or WebAssembly module.
The main operational surfaces are:
| Utility | Product role |
|---|---|
start, stop, restart, status | Control the local worker. |
server ... and worker ... | Control the server and preserve worker command compatibility. |
search, mcp, hook, and transcript watch | Reach runtime APIs and host event paths. |
adopt, cleanup, project, and memory ingest | Maintain project state and import memory. |
backup and restore | Create, inspect, list, and restore local database snapshots. |
teambrain ... | Share selected project memory with a team. |
| Host subcommands | Install, inspect, or remove selected native integrations. |
The server starts the optional embedding dependency only when meaning-based search is enabled. If that dependency is not available, the server still starts and reports keyword search as the available mode.
References: src/…/runtime.ts• L13-83 src/…/runtime.ts• L85-168 src/…/runtime.ts• L170-337 src/…/server.ts• L16-115 src/…/index.ts• L277-281
Backup and restore
Backup commands provide an operator view of local database snapshots without creating a second snapshot engine in the CLI. The CLI calls the running worker's backup API, which owns snapshot creation and restore state.
backup status reports the last snapshot, retention count, next run, errors, and the last restore. backup run requests one snapshot and reports when another snapshot is already running. backup list shows available files. Restore remains a separate command so a user must name the snapshot explicitly.
Restore stages a checked snapshot name and restarts the worker. The new worker applies the restore before it opens the database and keeps a pre-restore copy, so the CLI does not need direct database write access.
The backup client is read-only with respect to settings. If the worker is not running, it gives the normal start command instead of creating settings or starting a competing service.
References: src/…/backup.ts• L1-37 src/…/backup.ts• L65-166 src/…/restore.ts• L1-20 src/…/restore.ts• L27-56 src/…/index.ts• L399-409
External memory import
External memory import provides a model-free migration path from Mem0 and Supermemory into the local memory service. The command reads and validates the full source before it writes anything, which keeps a partial source read from creating a partial local import.
The command can import memories from either provider and source documents from Supermemory. It supports a dry run, a record limit, a request timeout, and a target platform. The import plan keeps source identity and provenance with each note. It skips records that are expired, merged, superseded, forgotten, or not current, then saves the remaining notes through the worker. A repeated run treats confirmed records as existing rather than creating duplicates.
References: src/…/import-memory.ts• L1-13 src/…/import-memory.ts• L15-35 src/…/import-memory.ts• L171-205 src/…/import-memory.ts• L208-259 src/…/import-memory.ts• L262-343 src/…/import-memory.ts• L347-389
Hook launcher boundary
The installed launcher is the boundary between host events and memory work. Host hooks call claude-mem hook ... directly, while the launcher reaches the installed runtime and returns a host-safe result. The installer puts it in a persistent user path rather than relying on the temporary directory used by npx.
This separation lets the NPX command install or repair the launcher while hooks continue to use the installed product. doctor excludes an NPX temporary copy from its launcher search, then checks that the command on PATH speaks the expected protocol.
References: src/…/install.ts• L3028-3073 src/…/runtime.ts• L235-257 src/…/doctor.ts• L420-595
Memory transfer utilities
The export and import scripts provide a portable path for selected memory records. Export searches through the worker and includes observations, sessions, summaries, prompts, and their ownership metadata; import sends those records back through the worker API and reports skipped or rejected rows.
These utilities use the same data-directory and worker settings rules as the product. Regular file exports use atomic replacement, while pipes and devices keep stream behavior.
References: scripts/export-memories.ts• L18-53 scripts/export-memories.ts• L57-137 scripts/export-memories.ts• L148-170 scripts/import-memories.ts• L9-14 scripts/import-memories.ts• L16-91 scripts/resolve-data-dir.cjs• L1-66
Repair, diagnostics, and removal
Repair restores a usable installed runtime when packaged files or dependencies are incomplete. It refreshes the package material, runtime tools, tree-sitter support, marketplace dependencies, and hook launcher without asking the user to select hosts or providers again.
Diagnostics
npx claude-mem doctor is read-only. It checks the runtime tools, installed plugin and dependency closure, tree-sitter support, hook launcher, marketplace state, worker health, optional Chroma health, configured observer provider, Claude Code compatibility, Windows setup-hook reachability, backup freshness, auto-update state, and the last install error.
The command reports degraded worker dependencies and Chroma process or search conditions as advisory findings. Required checks control the exit code. Intentional or non-critical conditions remain advisory, such as a stopped worker, missing uv, stale backups, optional Chroma problems, missing provider credentials, an old Claude Code version, and a missing marketplace marker for an install made by another path. This makes the command useful both to an operator and to a CI or support script.
References: src/…/doctor.ts• L128-143 src/…/doctor.ts• L188-311 src/…/doctor.ts• L354-592 src/…/doctor.ts• L643-703 src/…/doctor.ts• L803-820 src/…/doctor.ts• L1092-1210 src/…/doctor.ts• L1212-1336 src/…/doctor.ts• L1346-1367
Removal flow
Removal stops the active worker, removes product-owned registrations and host setup, clears installer-owned settings, removes the hook launcher, and preserves the user's memory data directory. It also removes stray NPX caches and product logs when it can do so safely.
When the selected runtime is the local server stack, uninstall tells the operator how to tear down the bundled Docker resources and clears server settings. An externally managed stack is left alone. If DeepSeek Harness cleanup fails, the command keeps the marketplace material needed for a safe retry while continuing unrelated cleanup.
References: src/…/uninstall.ts• L34-168 src/…/uninstall.ts• L170-282 src/…/uninstall.ts• L290-450 src/…/uninstall.ts• L452-545
Cache pruning
Cache pruning removes superseded runnable plugin versions while protecting the versions needed by a live worker, the host registration, a usable rollback path, and an open Claude Code session. npx claude-mem prune --dry-run shows the plan; --keep changes the normal retention count.
Orphaned cache folders do not consume the normal retention count. If a worker is present but its version cannot be read, pruning keeps every version. This favors a safe retry over deleting the source of a running service. The installer and the worker use the same protection rules, so unattended updates and manual pruning do not select different safety boundaries.
References: src/…/prune.ts• L1-111 src/…/prune-cache.ts• L17-30 src/…/prune-cache.ts• L42-97 src/…/prune-cache.ts• L210-231 src/…/prune-cache.ts• L323-358 src/…/prune-cache.ts• L462-491 src/…/prune-cache.ts• L519-577
Validation and distribution pipeline
The build pipeline turns source entrypoints and manifests into the files users receive through npm and host package paths. The release commands align metadata, build hooks, services, the NPX CLI, viewers, native workers, and companion distributions, then check the contracts that matter after installation.
Build outputs
The package publishes dist/…/index.js as its executable and includes the plugin trees required by supported hosts. Its published surface also includes the Eve provider export and companion package trees for OpenClaw, Hermes, ODS, Pi, and DeepSeek Harness.
The build produces the worker and server services, a small hook-only service, MCP and context tools, transcript support, hook launchers, packaged UI assets, a bug-report CLI, and companion integration artifacts. Conditional targets include the OpenClaw and OpenCode plugins. The build also produces the Eve provider, Pi extension, and DeepSeek Harness plugin so these integrations can run from published output.
The viewer build produces the browser bundle and HTML assets. It also builds the My Work application from its own locked package set and places that output in the plugin so the local view can render after an offline install.
The worker and standalone Windows binary embed the deep-search child program. This keeps deep queries runnable without a source checkout, a node_modules tree, or a writable temporary directory. The Windows distribution keeps native media support beside the executable as a locked sidecar dependency rather than pretending that the native decoder is part of the portable JavaScript bundle.
Build output uses source maps and rejects bundles that do not parse or that contain build-machine paths. It also checks size and runtime boundaries for short-lived hooks and Node-launched MCP services, because a heavy dependency can make a host hook slow or make a host unable to load it.
Plugin manifests are synchronized from the root package metadata before distribution. The sync step keeps the public identity and version aligned across Claude, Codex, Qoder, Devin, Grok, OpenClaw, DeepSeek Harness, and Cursor-related manifests. The package dependency boundary keeps live dependencies needed by shipped artifacts separate from build-only dependencies. The generated plugin lockfile and copied runtime files must therefore match the bundles that the installer later materializes.
References: package.json• L28-78 package.json• L80-135 scripts/build-hooks.js• L502-638 scripts/build-hooks.js• L1185-1308 scripts/build-hooks.js• L1310-1416 scripts/build-viewer.js• L13-80 scripts/build-native-worker.js• L1-25 scripts/build-worker-binary.js• L6-60 scripts/worker-binary-build-options.js• L1-21 scripts/deep-search-build.js• L1-17 scripts/sync-plugin-manifests.js• L10-170
Release checks
Release checks protect failures that appear only after a user installs the package. They confirm that required plugin and companion files exist, bundles can load without build-machine paths, hook commands follow the canonical launcher rules, and the published entrypoint can start from a clean package install.
The post-install guard protects the dependency boundary. Every direct plugin dependency with an install script must be in the reviewed allowlist. Missing dependency metadata is also treated as uninspectable, and the root and plugin allowScripts declarations must match that same list. prepublishOnly runs the build and this guard before publication.
Manifest synchronization also fails early when a supported distribution manifest is missing. This prevents a release from updating only part of the host metadata set.
This diagram shows the release path to the consumer command.
flowchart LR
A[Source and package metadata] --> B[Build bundles and manifests]
B --> C[Generate plugin dependency lockfile]
C --> D[Check distribution contracts]
D --> E[Check install-script allowlist]
E --> F[npm publish]
F --> G[npx claude-mem install]
The clean-room smoke flow installs the plugin and npm tarball in temporary locations, then loads the published entrypoint. It also checks the worker's runtime closure and media decoder behavior. This checks the same package boundary that a new user receives rather than only the repository checkout.
The cross-platform mirror utility supports the release paths that need an rsync-like copy on Windows. It preserves links, permissions, and times, deletes stale non-excluded files, and refuses overlapping source and destination roots before it changes either tree.
References: package.json• L123-135 scripts/build-hooks.js• L1320-1398 scripts/sync-plugin-manifests.js• L121-170 scripts/check-postinstall-allowlist.js• L1-19 scripts/check-postinstall-allowlist.js• L21-43 scripts/check-postinstall-allowlist.js• L45-101 scripts/check-postinstall-allowlist.js• L104-153 scripts/smoke-clean-room.cjs• L1-35 scripts/smoke-clean-room.cjs• L117-221 scripts/smoke-clean-room.cjs• L224-395 scripts/mirror-dir.cjs• L17-30 scripts/mirror-dir.cjs• L182-286
Test lanes
The test command splits validation into a fast lane and an integration lane. The fast lane is the default local check. The integration lane covers browser, installation, smart-file-read, packaging, native runtime, and other work that needs real external time or services.
The lane tool keeps the two sets disjoint and checks that every discovered test belongs to one lane. On Windows it batches long test commands so the operating system command-line limit does not hide part of the suite. The package scripts expose these choices as test, test:integration, test:all, and test:lanes:check.
The read-gate evaluation is a separate product-level check. It starts isolated workers with the gate enabled and disabled, provisions the same parser used by a real install, runs real host evaluations, compares the traces and costs, and fails when requested cases do not complete.
The synthetic tool-use search benchmark measures index build, read latency, mutations, storage, and backup behavior in a temporary database. It does not open or qualify the user's memory database.
References: scripts/test-lanes.ts• L1-13 scripts/test-lanes.ts• L16-59 scripts/test-lanes.ts• L61-109 scripts/test-lanes.ts• L112-157 scripts/eval-read-gate.ts• L1-23 scripts/eval-read-gate.ts• L35-93 scripts/eval-read-gate.ts• L248-315 scripts/eval-read-gate.ts• L371-475 scripts/bench-tool-use-search.ts• L1-16 scripts/bench-tool-use-search.ts• L25-76
Release support utilities
Release support scripts keep generated output and operator evidence consistent. The changelog generator reads published GitHub releases and adds only missing entries. The comment stripper uses parsers for tracked source and documentation files, preserves build directives, and has check and dry-run modes so cleanup cannot silently reformat a file.
The worker log utility follows the current data-directory rule, prints a bounded tail, and continues across log rotation without keeping a full log entry in memory. These scripts support distribution and support work without becoming alternate runtime paths.
References: scripts/generate-changelog.js• L1-15 scripts/generate-changelog.js• L17-37 scripts/generate-changelog.js• L71-126 scripts/strip-comments.ts• L15-73 scripts/strip-comments.ts• L76-116 scripts/strip-comments.ts• L326-498 scripts/worker-logs.cjs• L1-39 scripts/worker-logs.cjs• L41-111
Related pages
- Distribution integrations explains how packaging connects the product to agent and editor hosts.
- Automatic update lifecycle explains unattended updates that reuse the install and cache contracts.
- Plugin hooks and agent modes explains the hook and agent contracts that installation enables.
- Cursor integration explains the Cursor host path that installation can register.
- Grok bot integration explains the Grok host path included in manifest synchronization.
- Cowork integration explains the Cowork distribution path.
- OpenClaw integration explains the OpenClaw package built for distribution.
- Native harness integrations explains native host registrations that installation can enable.
- Additional agent integrations explains companion agent packages built alongside the main plugin.
- External notification integrations explains notification features exposed through installed integrations.
- Hermes integration explains the host-specific Hermes path exposed by this CLI.
- ODS native integration explains the ODS native distribution included in the package.
- Eve integration explains the Eve memory provider export.
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the package
bin, build output, published file list, engine versions, and clean-room entrypoint check aligned. - When changing a CLI command, update its router, help text, namespace usage, and runtime dispatch together.
- When changing install host identifiers, update detection, setup, removal cleanup, and telemetry as one contract.
- When changing Hermes setup, keep the detected host, normal provider integration, MCP-only command, absolute project path check, and uninstall ownership aligned.
- When changing TeamBrain setup, keep invite pairing, one-account protection, sync settings, worker restart behavior, project sharing, and leave cleanup aligned.
- When changing external memory import, keep vendor selection, source scope, provenance, platform mapping, limits, and worker duplicate handling aligned.
- When changing runtime dependencies, update the root or plugin dependency boundary, frozen lockfile, module checks, install-script allowlist, and clean-room check.
- When changing marketplace npm installation, preserve strict-first behavior, the narrow
ERESOLVEfallback, timeout handling,--ignore-scripts, and inheritedallow-scriptscleanup. - When changing Bun,
uv, tree-sitter, or tool lookup, preserve alternate path discovery, version markers, vector-search opt-out behavior, Codex path rules, and the severity used by install versus repair. - When changing launcher behavior, keep PATH placement, launcher protocol, Claude Code compatibility warnings, self-heal behavior, code-sign checks, and doctor checks consistent.
- When changing browser setup, keep worker setup state, browser hand-off, checkout state, background-work waiting, and restart rules aligned.
- When changing provider or runtime selection, keep worker and server settings, account requirements, supported host limits, server key bootstrap, server job scope, and uninstall teardown aligned.
- When changing backup commands, preserve the worker API contract, read-only settings behavior, safe snapshot selection, conflict response, and restore status reporting.
- When changing diagnostics, keep required checks separate from advisory checks so intentional stopped services do not become hard failures.
- When changing plugin metadata or companion distributions, sync all published manifests, native sidecars, generated lockfiles, package exports, and required-file checks before publishing.
- When changing bundle entrypoints, preserve embedded deep-search behavior, source-map placement, path-leak checks, host runtime limits, and the Node-versus-Bun module boundary.
- When changing test classification or evaluation scripts, keep fast and integration lanes disjoint, cover every discovered test file, isolate real worker data, and fail incomplete evaluation cases.
- When changing data-directory or mirror helpers, keep the CommonJS and TypeScript path rules in parity and keep mirror roots disjoint before deletion begins.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| dist/…/index.js is absent from the package | npx claude-mem cannot start | Build output, package bin, and clean-room tarball check |
| A selected host setup fails | That host has no working integration | Per-host result reporting and partial-install summary |
| The installed launcher is missing, stale, unsigned on macOS, or resolves to the temporary NPX copy | Host hooks cannot reach the persistent runtime | PATH launcher installation, NPX-path exclusion, protocol and signature checks, and doctor validation |
| Bun is unavailable after setup | Hooks and runtime services cannot start | Tool discovery, version checks, and install error remediation |
uv is unavailable while vector search is enabled | Vector search is disabled or setup becomes incomplete | Runtime check and explicit vector-search opt-out handling |
A configured Codex path starts with ~ or is not executable | Codex-backed observation generation is paused | Explicit path validation and doctor provider warning |
Claude Code is older than 2.1.139 | Hook arguments are ignored and memory capture can stop | Installer warning and advisory version check |
| A packaged dependency, tree-sitter CLI, or required Zod subpath cannot resolve | A later service or smart search operation cannot start | Dependency install, critical module checks, provisioning, and repair guidance |
Marketplace npm install fails without ERESOLVE | Setup aborts instead of hiding a package or network error | Strict-first npm policy and fail-loud error handling |
| A dependency install script is not reviewed or cannot be inspected | Package installation can run an unexpected script or publication can pass an unknown dependency | Shared allowlist, complete dependency tree, and root/plugin declaration drift check |
| Browser setup loses worker contact or is restarted during background work | Setup state or imported memory can be left incomplete | Worker state polling, visible failure, and delayed restart |
| The server embedder is unavailable | The server starts with keyword search only | Optional dependency install before server start and explicit fallback message |
| A server job command has no scope or admin marker | The command could affect another team or project | Required --team/--project scope or CLAUDE_MEM_SERVER_ADMIN=1, plus audit rows |
| The worker is not running for a backup command | The command cannot inspect or create a snapshot | Read-only worker request and clear start command |
| A restore name is outside the backup directory | The CLI could read an unintended file | Snapshot path containment check before staging restart |
| A backup is enabled but no recent snapshot exists | Local recovery coverage may be stale | Informational backup check in doctor |
| A worker is present but its cache version cannot be read | Pruning could delete the live worker's source | Retain-all protection during prune |
| A live host session still uses an old cache version | Its hooks can stop when the folder is removed | .in_use process protection during prune |
| A source vendor changes its total, pagination cursor, or record state during import | The local plan can be incomplete or contain stale records | Full-source validation, count checks, cursor checks, lifecycle filtering, and no-write failure before apply |
| An import repeats a source record or receives an unsafe source payload | A note can be duplicated or control data can be polluted | Stable source fingerprints, bounded response sizes, source metadata nesting, and worker duplicate confirmation |
| A server runtime uses an external Docker stack | Uninstall must not remove resources it does not own | Runtime-aware teardown message and server setting cleanup |
| DeepSeek Harness cleanup fails during uninstall | Its registration can remain while other integrations are removed | Keep required marketplace material and return a retryable failure |
| A required doctor check fails | The command exits non-zero for support or CI use | Required versus advisory check classification |
| A built bundle, native sidecar, or required companion file is missing | A host integration or support command is incomplete after publish | Distribution file, bundle integrity, and clean-room checks |
Root and plugin allowScripts declarations drift from the reviewed list | npm and Bun can use different install-script policy | Allowlist source of truth and manifest drift guard |
| A supported plugin manifest is missing before synchronization | The build cannot produce a complete metadata set | Required-manifest existence check in the sync step |
| Test files fall into both lanes or neither lane | Local and CI results do not represent the full suite | test:lanes:check coverage and disjointness check |
| A TeamBrain invite targets another host or another sync account is already saved | The install can connect to the wrong service or overwrite another account's sync identity | Host-origin validation, one-account refusal, and settings read/write checks |
Hermes install lacks --mcp-only or an absolute existing project directory | The Hermes integration is not configured | Strict command parsing and project directory validation |
Key files
| File | Why to read it |
|---|---|
| package.json | Defines the executable, package boundary, supported runtimes, published companion paths, build commands, test lanes, and release checks. |
| src/…/index.ts | Shows the public command map, install flag handling, and the NPX-to-installed-runtime boundary. |
| src/…/install.ts | Defines host setup, provider choice, browser setup, runtime selection, worker cutover, and install results. |
| src/…/ide-detection.ts | Shows how the installer selects likely hosts and preserves stable host identifiers. |
| src/…/hermes.ts | Defines Hermes MCP-only setup and owned integration removal. |
| src/…/teambrain.ts | Defines team pairing, project sharing, one-account protection, and leave cleanup. |
| src/…/browser-setup.ts | Defines the terminal-to-browser setup hand-off and safe restart behavior. |
| src/…/tool-path.ts | Defines cross-platform discovery for Bun and Codex tools. |
| src/…/setup-runtime.ts | Defines runtime tool discovery, dependency setup, tree-sitter provisioning, module checks, and install freshness. |
| src/…/npm-install-helper.ts | Defines the bounded marketplace npm process and peer-conflict retry policy. |
| src/…/runtime.ts | Shows worker and server process control, search access, and runtime dependency fallback. |
| src/…/import-memory.ts | Defines the safe, model-free import path from supported external memory services. |
| src/…/server-jobs.ts | Shows scoped server queue inspection and operator retry or cancel behavior. |
| src/…/backup.ts and src/…/restore.ts | Show the thin worker API client and staged restore flow for local snapshots. |
| src/…/doctor.ts | Defines read-only health checks and required versus advisory findings. |
| src/…/prune.ts and src/…/prune-cache.ts | Show safe cache retention and live-worker and host-session protection. |
| src/…/uninstall.ts and src/…/claude-auto-memory.ts | Show removal scope and safe reversal of the installer-owned host memory setting. |
| src/…/telemetry.ts | Defines the telemetry controls and the fields that the CLI explains to users. |
| scripts/build-hooks.js | Defines service bundles, companion outputs, launcher rules, integrity checks, and required distribution files. |
| scripts/sync-plugin-manifests.js | Synchronizes package identity and version data across the host and companion manifests before distribution. |
| scripts/build-viewer.js | Builds the packaged viewer and the offline My Work web application. |
| scripts/build-native-worker.js, scripts/build-worker-binary.js, and scripts/worker-binary-build-options.js | Define the standalone worker build and its Windows native-media boundary. |
| scripts/deep-search-build.js | Defines the embedded deep-search child used by bundled and standalone workers. |
| scripts/check-postinstall-allowlist.js | Checks reviewed install scripts and keeps root and plugin manifest policy aligned. |
| scripts/smoke-clean-room.cjs | Models fresh plugin and npm package installs and loads the published entrypoints. |
| scripts/mirror-dir.cjs | Provides the safe cross-platform mirror used where rsync is not available. |
| scripts/test-lanes.ts and scripts/eval-read-gate.ts | Define suite coverage and the isolated real-worker read-gate evaluation. |
| scripts/bench-tool-use-search.ts | Measures synthetic search storage and timing without opening user data. |
| scripts/export-memories.ts, scripts/import-memories.ts, and scripts/worker-logs.cjs | Provide support paths for memory transfer and bounded worker-log inspection. |
| scripts/generate-changelog.js and scripts/strip-comments.ts | Keep release notes and tracked source cleanup repeatable. |