Episode 2: Installing Claude-Mem — Zero to Running

This episode's scenario: You've decided to set up Claude-Mem for your blog project. Installation is easy, but there's a gap between "installed" and "actually working" — and that gap is verification.

2.1 Prerequisites Checklist

Before installing, confirm each item:

# ✅ Check Node.js version (requires ≥ 18)
node -v
# Expected: v18.x.x or higher

# ✅ Check Claude Code is installed
claude --version
# Expected: claude-code/x.x.x

# ✅ These two auto-install — no manual action needed:
# Bun — JavaScript runtime (powers the Worker)
# uv — Python package manager (for vector search dependencies)

⚠️ Windows users: If your terminal shows npm: The term 'npm' is not recognized, Node.js wasn't added to your system PATH. Reinstall from nodejs.org and check "Add to PATH."

2.2 Method 1 (Recommended): CLI Install

Run in any terminal:

npx claude-mem install

This single command handles everything automatically:

graph TD
    A["npx claude-mem install"] --> B["Register hook scripts to
~/.claude/plugins/"]
    B --> C{"Bun installed?"}
    C -->|No| D["Auto-install Bun"]
    C -->|Yes| E["Skip"]
    D --> F{"uv installed?"}
    E --> F
    F -->|No| G["Auto-install uv"]
    F -->|Yes| H["Skip"]
    G --> I["Create ~/.claude-mem/ directory"]
    H --> I
    I --> J["Generate settings.json
(default config)"]
    J --> K["Start Worker Service
(port 37777)"]
    K --> L["✅ Installation complete"]

    style A fill:#6366f1,color:#fff
    style L fill:#10b981,color:#fff

2.3 Method 2: Plugin Marketplace

If you prefer working inside Claude Code:

# Inside a Claude Code session:
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

Both methods produce identical results.

2.4 ⚠️ This Command Is WRONG

# ❌ Never do this
npm install -g claude-mem

Why? Because npm install only downloads the Claude-Mem SDK library, but does NOT:

• ❌ Register lifecycle hooks (no hooks = no auto-capture)
• ❌ Start the Worker service (no Worker = nowhere to store data)
• ❌ Create the config directory and database

Remember: Always use npx claude-mem install.

2.5 The 5-Step Verification

After installation, restart Claude Code. Then verify step by step:

Step 1: Restart Claude Code

# Fully quit and reopen Claude Code
# For terminal version:
claude

Step 2: Open the Web UI

Navigate to:

http://localhost:37777

You should see a live memory stream interface. If the page doesn't load, the Worker isn't running.

Step 3: Health Check

curl http://localhost:37777/api/health

Expected response:

{"status":"ok"}

Step 4: Check the Database File

ls -la ~/.claude-mem/claude-mem.db

You should see a SQLite database file.

Step 5: Check Configuration

cat ~/.claude-mem/settings.json

You should see something like:

{
  "CLAUDE_MEM_MODE": "code",
  "WORKER_PORT": 37777,
  "LOG_LEVEL": "info"
}

All 5 steps pass? Congratulations, Claude-Mem is up and running! 🎉

2.6 First Use: Let Claude-Mem Start Recording

Now let's start the first memory-enabled session on your blog project:

# Navigate to your blog project
cd ~/my-blog

# Launch Claude Code
claude

Then work normally. For example:

You: Initialize a Next.js project for a personal tech blog.

Claude will start executing operations (creating files, installing dependencies, editing configs). Meanwhile, open another browser tab at http://localhost:37777 and you'll see:

• 🟢 Real-time Observation entries appearing continuously
• Each Observation has a title, type label, and timestamp
• Raw operations automatically compressed into concise notes

That's Claude-Mem working. You don't need to do anything — it's fully automatic.

2.7 Troubleshooting Installation

Hands-On Exercise

1. ✅ Run npx claude-mem install
2. ✅ Restart Claude Code
3. ✅ Complete the 5-step verification
4. ✅ Start a session in the blog project; observe Observations appearing in the Web UI
5. ✅ Take a screenshot of the Web UI homepage (proof of successful install)

Coming Up Next

Installation done. Next episode, we crack open Claude-Mem's "brain" and see exactly what your dev history looks like when stored. Why does it need both SQLite and ChromaDB? What does an Observation look like? We'll show you with actual SQL queries.

➡️ Episode 3: Inside Claude-Mem's Brain — Data Storage Architecture