Problem: npm dependency install fails —— Trove problem library

What you will run into

npm install -g claude-mem errors out or fails silently in the background, and afterwards the claude-mem command doesn't work.

You retry a few times with the same result - most often it's a network/registry issue, occasionally a missing runtime: newer claude-mem (since v7.1.0) swapped the worker from pm2 to Bun, and without Bun on the machine, install or first start goes wrong.

Why this happens

• Main cause of install failure: the default npm official registry is unstable in CN and the dependency tree doesn't fully download;
• Silent failure: some network errors only produce npm warnings; you only notice the command is missing after install;
• Runtime difference: old docs say "manage the worker with pm2" (old versions); newer versions depend on the Bun runtime - following old tutorials to check pm2 sends you in the wrong direction.

The success criterion of npm install -g is only "the package's binaries are linked into the global bin directory" — npm does not check what the package needs at runtime, it only manages the JS dependency tree.

claude-mem's worker is a separate process hosted by the Bun runtime since v7.1.0, and npm never verifies Bun exists: after install the claude-mem command itself appears (it is just the JS package entry), and the worker only crashes when it actually starts on Bun.

That is the full chain behind "installed but the command doesn't work": network problems -> dependency tree downloads incompletely (npm often only warns, no error) -> command missing; runtime problems -> command exists but worker won't start.

So the confirmation order is fixed in three steps: claude-mem --version (is the command there?

network layer) -> bun --version (is the runtime there? runtime layer) -> claude-mem status (is the worker ready? service layer) — fix whichever layer breaks.

Step by step

1. Retry with a different registry — Required

npm_config_registry=https://registry.npmmirror.com npm install -g claude-mem

Measured: npmmirror global install succeeded (first ~50s, ~5s with cache).

2. Dependency anomalies: force install + restart the worker — Required

npm ci && npm install --force
claude-mem restart

3. Confirm the runtime (Bun) — Required

bun --version

Without Bun, install it first (curl -fsSL https://bun.sh/install | bash); the pm2 scenario in old docs only matches old versions - don't copy it.

How to confirm it works

claude-mem --version && claude-mem status

The command works and the worker is ready = success (measured: install succeeded after switching registry; version prints normally).

Other environments

Symptom

npm install -g claude-mem errors or fails silently; the claude-mem command doesn't work.

Cause

Dependency tree/network issues; old versions manage the worker with pm2 (PM2->Bun since v7.1.0, needs the Bun runtime).

Solution

1. Retry with a different registry: npm_config_registry=https://registry.npmmirror.com npm install -g claude-mem.
2. Dependency anomalies: npm ci or npm install --force, then restart the worker.
3. Confirm the runtime: bun --version (install Bun if missing; the pm2 scenario in old docs matches old versions).