feat: Switch to persistent Chroma HTTP server

[bigph00t]

Summary

• Replaces MCP subprocess approach with persistent Chroma HTTP server
• Uses chromadb npm package's built-in ChromaClient and npx chroma run
• Adds configuration for future cloud/remote Chroma support

Changes

• NEW: ChromaServerManager.ts - Manages local Chroma server lifecycle
• REFACTOR: ChromaSync.ts - Uses ChromaClient instead of MCP
• UPDATE: worker-service.ts - Starts server on initialization
• UPDATE: GracefulShutdown.ts - Stops server on shutdown
• UPDATE: SettingsDefaultsManager.ts - New Chroma configuration options

Benefits

• Eliminates subprocess spawn latency on first query
• Single server process instead of per-operation subprocesses
• No Python/uvx dependency for local mode
• Future-ready for cloud-hosted Chroma (claude-mem pro)
• Cross-platform: Linux, macOS, Windows

Configuration

CLAUDE_MEM_CHROMA_MODE=local|remote
CLAUDE_MEM_CHROMA_HOST=127.0.0.1
CLAUDE_MEM_CHROMA_PORT=8000
CLAUDE_MEM_CHROMA_SSL=false

Test Plan

• Fresh install works
• Upgrade from previous version works (existing data)
• Vector search returns correct results
• Clean shutdown kills server process
• Linux/macOS/Windows tested

🤖 Generated with Claude Code

[greptile-apps]

Greptile Overview

Greptile Summary

Replaces MCP subprocess approach with persistent HTTP server using chromadb npm package and npx chroma run. Eliminates per-operation subprocess spawning, removes Python/uvx dependency for local mode, and enables Windows support (previously disabled due to console popup issues).

Key architectural changes:

• New ChromaServerManager singleton manages local Chroma server lifecycle (startup on worker init, graceful shutdown on exit)
• ChromaSync refactored from MCP StdioClientTransport to HTTP ChromaClient with direct REST API calls
• Added configuration for future remote/cloud Chroma support with tenant isolation and API key auth
• New ProcessRegistry system tracks and cleans up zombie Claude subprocesses (addresses Issue Worker-service spawns subagents that don't terminate, causing zombie accumulation thedotmack/claude-mem#737)

Integration points:

• Worker service starts Chroma server during background initialization, verifies readiness with 60s timeout
• Graceful shutdown sequence stops Chroma server with SIGTERM escalating to SIGKILL after 5s
• Session deletion now waits for subprocess exit confirmation to prevent zombie accumulation
• Orphan reaper runs every 5 minutes to kill stray processes

Configuration added:

• CLAUDE_MEM_CHROMA_MODE: local (default) or remote
• CLAUDE_MEM_CHROMA_HOST, CLAUDE_MEM_CHROMA_PORT, CLAUDE_MEM_CHROMA_SSL
• Multi-tenancy: CLAUDE_MEM_CHROMA_TENANT, CLAUDE_MEM_CHROMA_DATABASE, CLAUDE_MEM_CHROMA_API_KEY

Previous review comments about undefined pid at line 253 have been addressed with proper check at line 253.

Confidence Score: 4/5

• This PR is generally safe to merge with minor issues that should be verified during testing
• The refactoring is well-architected with proper separation of concerns (ChromaServerManager for lifecycle, ChromaSync for operations). The HTTP approach is cleaner than MCP subprocess spawning. The process tracking system addresses real zombie process issues. However, score is 4 not 5 due to: (1) complex cross-platform process management with detached processes and process groups that needs thorough testing, (2) startup race conditions possible if server fails during waitForReady timeout, and (3) significant behavior change from per-op subprocesses to persistent server may reveal edge cases in production
• Pay close attention to src/services/sync/ChromaServerManager.ts (process lifecycle management) and src/services/worker/ProcessRegistry.ts (zombie cleanup logic) during testing, especially on Windows where process group behavior differs

Important Files Changed

Filename	Overview
src/services/sync/ChromaServerManager.ts	New server manager with process lifecycle handling; has undefined pid handling issue on line 253
src/services/sync/ChromaSync.ts	Refactored from MCP to HTTP client using chromadb package; cleaner architecture, Windows support enabled
src/services/worker-service.ts	Integrated ChromaServerManager startup on initialization and orphan reaper for zombie process cleanup
src/services/infrastructure/GracefulShutdown.ts	Added Chroma server stop to shutdown sequence; clean integration with existing shutdown flow
src/services/worker/ProcessRegistry.ts	New zombie process tracking and cleanup system to prevent subprocess accumulation (Issue thedotmack#737)
package.json	Added chromadb and @chroma-core/default-embed dependencies; updated exports for SDK

Sequence Diagram

sequenceDiagram
    participant WS as WorkerService
    participant CSM as ChromaServerManager
    participant Server as Chroma Server (npx)
    participant CS as ChromaSync
    participant GS as GracefulShutdown

    Note over WS: Worker Startup
    WS->>CSM: getInstance(config)
    CSM-->>WS: singleton instance
    WS->>CSM: start()
    CSM->>CSM: Check existing server (heartbeat)
    alt Server already running
        CSM-->>WS: reuse existing
    else No server found
        CSM->>Server: spawn npx chroma run
        CSM->>Server: Poll heartbeat
        Server-->>CSM: ready
    end
    WS->>CSM: waitForReady(60s)
    CSM-->>WS: server ready

    Note over CS: First Vector Operation
    CS->>CSM: isServerReachable()
    CSM->>Server: GET /api/v2/heartbeat
    Server-->>CSM: 200 OK
    CSM-->>CS: true
    CS->>Server: HTTP operations (add/query)

    Note over WS: Worker Shutdown
    WS->>GS: performGracefulShutdown()
    GS->>CSM: stop()
    alt Unix/Linux/macOS
        CSM->>Server: kill(-pid, SIGTERM)
    else Windows
        CSM->>Server: kill(SIGTERM)
    end
    alt Graceful exit
        Server-->>CSM: exit event
    else Timeout (5s)
        CSM->>Server: kill(SIGKILL)
    end
    CSM-->>GS: stopped
    GS-->>WS: shutdown complete

Loading

[greptile-apps]

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

pid could be undefined if the process was never assigned a PID. The non-null assertion on undefined will cause process.kill(-undefined!) to pass NaN to kill().

Suggested change

	process.kill(-pid!, 'SIGTERM');
	if (pid !== undefined) {
	try {
	process.kill(-pid, 'SIGTERM');
	} catch (err) {
	// Process group kill failed, try direct kill
	proc.kill('SIGTERM');
	}
	} else {
	proc.kill('SIGTERM');
	}

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/services/sync/ChromaServerManager.ts
Line: 215:215

Comment:
`pid` could be undefined if the process was never assigned a PID. The non-null assertion on undefined will cause `process.kill(-undefined!)` to pass `NaN` to kill().

```suggestion
        if (pid !== undefined) {
          try {
            process.kill(-pid, 'SIGTERM');
          } catch (err) {
            // Process group kill failed, try direct kill
            proc.kill('SIGTERM');
          }
        } else {
          proc.kill('SIGTERM');
        }
```

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}