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

> Install thedotmackclaude-mem locally with our complete guide. Follow simple steps to run npm install and start the daemon on port 37777 for seamless local development.

- Repository: [Alex Newman/claude-mem](https://github.com/thedotmack/claude-mem)
- Tags: getting-started
- Published: 2026-02-16

---

**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`](https://github.com/thedotmack/claude-mem/blob/main/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`](https://github.com/thedotmack/claude-mem/blob/main/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.

```bash
/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.

```bash

# 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`](https://github.com/thedotmack/claude-mem/blob/main/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.

```bash

# 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`](https://github.com/thedotmack/claude-mem/blob/main/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`](https://github.com/thedotmack/claude-mem/blob/main/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`](https://github.com/thedotmack/claude-mem/blob/main/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`](https://github.com/thedotmack/claude-mem/blob/main/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`](https://github.com/thedotmack/claude-mem/blob/main/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`](https://github.com/thedotmack/claude-mem/blob/main/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`](https://github.com/thedotmack/claude-mem/blob/main/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.