How to Set Up thedotmack/claude-mem Locally: Complete Installation Guide

Run npm install to trigger the smart-install script, then npm run worker:start to launch the daemon on port 37777.

Setting up thedotmack/claude-mem locally requires installing the Bun runtime and uv package manager, building the TypeScript hooks, and starting the worker service that orchestrates SQLite and Chroma vector storage. This guide covers both the automated marketplace installation and the manual development setup using the actual source file paths and initialization logic found in the repository.

Prerequisites and Architecture Overview

Before you set up thedotmack/claude-mem locally, understand the three-layer architecture that handles dependency management, service orchestration, and data persistence.

Smart-Install Script Architecture

The plugin/scripts/smart-install.js file acts as the entry point for all installations. It detects whether Bun (JavaScript runtime) and uv (Python package manager for Chroma) are present, auto-installs them if missing, runs bun install with an npm fallback, and adds a claude-mem shell alias or function. The script enforces Bun version 1.1.14 or higher; if an older version exists, it triggers bun upgrade automatically.

Worker Service Components

The src/services/worker-service.ts file contains the main orchestrator. It starts an Express HTTP server on the default port 37777, creates the SQLite store, launches a local Chroma vector DB when CLAUDE_MEM_CHROMA_MODE=local, connects to the Claude-Code MCP bridge, and registers all API routes (/api/*). The worker can run as a daemon (spawned by the CLI) or in-process for a single hook.

Step-by-Step Local Setup Guide

You can set up thedotmack/claude-mem locally using either the Claude-Code marketplace for a hands-off experience or a manual clone for development and customization.

Option 1: Marketplace Installation (Recommended)

The fastest way to set up thedotmack/claude-mem locally is through the Claude-Code plugin marketplace. This method triggers the smart-install script automatically.

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

After the second command runs, the smart-install script ensures Bun and uv are present, installs all Node modules, and registers the claude-mem command. The next Claude-Code session automatically launches the worker via the SessionStart hook stored in ~/.claude/plugins/marketplaces/thedotmack/hooks.

Option 2: Manual Clone and Development Setup

For developers who need to modify the source or run bleeding-edge commits, clone the repository and run the build pipeline manually.

# 1. Clone and enter the repository

git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem

# 2. Install dependencies (triggers smart-install for Bun/uv)

npm install

# 3. Build TypeScript and generate hooks

npm run build

# 4. Start the worker daemon

npm run worker:start

# 5. Verify status

npm run worker:status

The npm run build command compiles the TypeScript source to dist/ and generates hooks.json with absolute paths. The npm run worker:start command spawns the daemon, writes the PID to ~/.claude-mem/.worker.pid, and begins listening on port 37777.

Verifying the Installation

Confirm that thedotmack/claude-mem is running correctly by checking the health endpoints and web viewer.

# Check CLI status

claude-mem status

# Or use the underlying npm script

npm run worker:status

Open http://localhost:37777 in a browser to access the web viewer defined in src/ui/viewer/constants/ui.ts. The UI displays real-time memory observations, token usage statistics, and searchable session history.

Understanding the Data Storage Layer

When you set up thedotmack/claude-mem locally, the system initializes two persistence layers: SQLite for structured metadata and Chroma for vector embeddings.

SQLite Database Configuration

The src/services/worker/DatabaseManager.ts file manages the SQLite schema stored at ~/.claude-mem/claude-mem.db by default. This database stores observations, summaries, and processing queue metadata. You can override the location by setting the CLAUDE_MEM_DATA_DIR environment variable before starting the worker.

Chroma Vector Database Setup

The src/services/worker/sync/ChromaServerManager.ts file handles the local Chroma instance. When CLAUDE_MEM_CHROMA_MODE is set to local (the default), the worker launches a Chroma server storing embeddings in ~/.claude-mem/vector-db/. To use a remote Chroma instance instead, set CLAUDE_MEM_CHROMA_MODE=remote and configure the endpoint via environment variables.

Common Installation Issues and Solutions

The smart-install script and worker service include specific guards against common pitfalls when you set up thedotmack/claude-mem locally.

Handling Missing Bun or uv Dependencies

If plugin/scripts/smart-install.js detects that Bun is not on PATH or in ~/.bun/bin/bun, it automatically runs the official installer via curl (Linux/macOS) or PowerShell (Windows). For uv, it executes the official uv installer if the command is missing. The script enforces Bun version 1.1.14 or higher; if an older version exists, it triggers bun upgrade before proceeding.

Resolving Port Conflicts and Stale PID Files

The worker service in src/services/worker-service.ts includes cleanStalePidFile() to remove PID files when the associated process no longer exists, preventing "worker already running" false positives. On Windows, shouldSkipSpawnOnWindows() creates a lock file .worker-start-attempted to suppress repeated spawning attempts for two minutes after a failure, preventing bun.exe pop-up loops. If port 37777 is already in use, the worker logs the conflict and you can override the port by setting the PORT environment variable before starting the service.

Summary

To set up thedotmack/claude-mem locally:

• Run the smart-install script (npm install) to auto-detect and install Bun (≥1.1.14) and uv, then install Node dependencies.
• Execute npm run build to compile TypeScript and generate Claude-Code hooks in ~/.claude/plugins/marketplaces/thedotmack/hooks.
• Start the worker daemon with npm run worker:start to launch the Express server on port 37777, initialize SQLite at ~/.claude-mem/claude-mem.db, and start the local Chroma vector store.
• Verify operation via npm run worker:status or the web viewer at http://localhost:37777.

Frequently Asked Questions

What is the minimum Node.js version required to run claude-mem locally?

The system requires Node.js 18 or higher to run the worker service and CLI commands. While the smart-install script prefers Bun as the runtime for dependency installation, Node.js remains the baseline requirement for executing the compiled TypeScript output in dist/.

How do I access the web viewer after setting up claude-mem?

Once the worker is running, open your browser and navigate to http://localhost:37777. This endpoint serves the real-time UI defined in src/ui/viewer/constants/ui.ts, displaying memory observations, token usage statistics, and a searchable timeline of session history.

Can I run claude-mem without installing Bun?

Yes, though Bun is the preferred runtime for installation speed. The plugin/scripts/smart-install.js automatically falls back to npm install if Bun installation fails or if the --force-npm flag is used. However, Bun version 1.1.14 or higher is still recommended for features like SQLite migration support.

Where does claude-mem store conversation history and embeddings?

By default, all data resides in ~/.claude-mem/. The SQLite database (claude-mem.db) stores structured observations and summaries, while vector embeddings live in the vector-db/ subdirectory managed by the local Chroma instance. You can override these locations by setting the CLAUDE_MEM_DATA_DIR environment variable before starting the worker.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}