chroma-mcp subprocess leak on macOS — zombie uv+python3.13 process pairs accumulate across sessions

[ZSI2017]

Before submitting

• I searched existing issues and confirmed this is not a
  duplicate

---

📝 Manual Bug Report

Bug Description

When CLAUDE_MEM_CHROMA_ENABLED=true (default), zombie uv +
python3.13 process pairs accumulate over time until the system has
hundreds of processes consuming several GB of memory. Observed: 600+
python processes consuming ~6.5 GB of RAM, requiring a manual
kill-all to recover.

Steps to Reproduce

1. Enable CLAUDE_MEM_CHROMA_ENABLED=true (this is the default)
2. Open 3–5 Claude Code sessions simultaneously across different
   projects
3. Use Claude actively for several hours (generating
   observations/syncs)
4. Run ps aux | grep python3 | grep -v grep | wc -l

The process count grows proportionally to: session count × sync
frequency × kill failure rate.

Expected Behavior

Old subprocess should be fully terminated before spawning a new one.
If killProcessTree fails, it should retry or use process group kill
(kill -pgid) instead of silently swallowing the error.

Root Cause Analysis

Three issues combine to produce this:

1. killProcessTree is best-effort and silently swallowed

In worker-service.cjs, when chroma-mcp closes unexpectedly:

  t.killProcessTree(u).catch(d => {
    v.debug("CHROMA_MCP", "Background tree-kill after onclose finished
  (best-effort)", ...)
    // error is silently ignored — old process keeps running
  })

On macOS, kill -9 on the uv parent does not reliably kill the
python3.13 child. The child becomes an orphan. Since the error is
swallowed, there is no retry or fallback.

2. Short-connection pattern — no connection reuse

Every chroma sync spawns a new uvx --python 3.13 chroma-mcp
subprocess, connects, uses it, then closes. Connections are never
reused. This results in 30+ connect/disconnect cycles over a few
hours of active use.

3. Concurrent sessions cause lock contention → timeout → reconnect
   loop

Multiple Claude Code sessions each try to connect to the same chroma
persistent data dir simultaneously. The file lock causes connection
attempts to hang past the 30s timeout, each leaving an un-killed uv

• python3.13 pair. The next retry spawns a new pair on top of the
  orphaned ones.

Suggested Fixes

1. Use process group kill on macOS/Linux instead of single-PID kill:
   process.kill(-pgid, 'SIGKILL') // kills entire process group
2. Reuse the chroma-mcp connection across sync operations instead of
   spawn-per-sync
3. Add a concurrency lock so only one worker connects to the local
   chroma data dir at a time
4. Verify kill success before spawning a new subprocess

Environment

• Claude-mem version: 13.4.2
• Claude Code version: 2.1.169
• OS: macOS 26.5.1
• Platform: arm64

Logs

[WARN ] [CHROMA_MCP] Connection failed, killing subprocess tree to
prevent zombie {error=MCP connection to chroma-mcp timed out after
30000ms}
[ERROR] [CHROMA_MCP] Connection attempt failed MCP connection to
chroma-mcp timed out after 30000ms
[ERROR] [CHROMA_SYNC] Backfill failed for project: MCP
connection to chroma-mcp timed out after 30000ms

[WARN ] [CHROMA_MCP] chroma-mcp subprocess closed unexpectedly,
applying reconnect backoff

The timeout pattern repeated 4 times in a single day (roughly every
1–4 hours of active use), and the unexpected-close event occurred
once additionally.

Additional Context

Workaround: Set CLAUDE_MEM_CHROMA_ENABLED=false in
~/.claude-mem/settings.json. This disables semantic search but
eliminates the leak entirely.

The uvx command used to spawn chroma-mcp:
uvx --python 3.13 --with onnxruntime>=1.20 --with protobuf<7
chroma-mcp==0.2.6 --client-type persistent

[LXChild]

Confirming this on a single machine — and adding a data point on the query-side impact, since the report focuses on process/memory bloat.

Env: claude-mem 13.6.x (worker runtime), macOS arm64, CLAUDE_MEM_CHROMA_ENABLED=true (default).

Observed: only 3 orphaned uv + python3.13 pairs (PPID=1, aged 6 / 8 / 14 days, one per prior session), all bound to the same --data-dir ~/.claude-mem/chroma. Not hundreds — but 3 was already enough to break reads.

Symptom (new angle): semantic search via the MCP search tool hung the full 30s and fell back to keyword search ("Semantic search failed: MCP connection to chroma-mcp timed out after 30000ms. Falling back to keyword search"). Write-side CHROMA_SYNC kept logging fine throughout, so the leak silently degrades retrieval while looking healthy in logs. A stale Worker OAuth token was a red herring — refreshing it fixed the outer Worker API timeout but search still failed until the orphans were killed.

Fix that worked: kill all orphaned chroma-mcp PIDs → next search respawned a single clean instance → semantic search returned immediately, no fallback warning.

This supports suggested fix #3 (single-connection lock on the local chroma data dir): the SQLite lock contention degrades the read path even at very low orphan counts, not just under the hundreds-of-processes scenario.

[devajmeireles]

Same here!

[dhruvDMG]

Still present on 13.11.0 (plugin cache thedotmack/claude-mem/13.11.0), macOS 15 / Darwin 25.5.0.

Fresh data point:

• 354 orphaned chroma-mcp procs (177 uv tool uvx wrappers + 177 python3.13 children), holding 541 MB RSS, accumulated over ~1 day.
• 176 of the wrappers had ppid=1 — confirms the parent (worker-service.cjs / hook-parent) died and the tree-kill never reaped them, matching the swallowed-killProcessTree root cause above.
• The paired python3.13 children still pointed at their (dead-soon) wrapper as parent, so they reparent to launchd on the next wrapper death — a single kill pass only catches the top of each pair.
• 11 mcp-server.cjs node parents also lingering (up to 4 days old), some already detached.

Confirms the diagnosis: single-PID kill on the uv parent doesn't take the python3.13 child on macOS; process-group kill (kill -- -<pgid>) is the right fix.

Stopgap for anyone hurting now — a SessionStart/SessionEnd reaper that kills only claude-mem procs whose parent is already dead (ppid==1), so it never touches a live session. Two passes because killing an orphaned wrapper reparents its child to ppid=1:

#!/usr/bin/env bash
set -u
PAT='\.claude-mem/chroma|claude-mem/[0-9.]+/scripts/mcp-server\.cjs'
reap() {
  ps -eo pid,ppid,command | awk -v pat="$PAT" '
    $2==1 && $0 ~ pat && $0 !~ /reap-chroma-mcp|awk/ { print $1 }
  ' | while read -r pid; do kill -TERM "$pid" 2>/dev/null; done
}
reap; sleep 1; reap

Wired into ~/.claude/settings.json hooks (SessionStart:startup + SessionEnd, async:true). Mop, not a fix — the real fix is process-group kill + connection reuse as described.