openclaw

# Claude-Mem OpenClaw Plugin — Setup Guide

This guide walks through setting up the claude-mem plugin on an OpenClaw gateway. By the end, your agents will have persistent memory across sessions via system prompt context injection, and optionally a real-time observation feed streaming to a messaging channel.

## Quick Install (Recommended)

Run this one-liner to install everything automatically:

```bash
curl -fsSL https://install.cmem.ai/openclaw.sh | bash
```

The installer handles dependency checks (Bun, uv), plugin installation, memory slot configuration, AI provider setup, worker startup, and optional observation feed configuration — all interactively.

### Install with options

Pre-select your AI provider and API key to skip interactive prompts:

```bash
curl -fsSL https://install.cmem.ai/openclaw.sh | bash -s -- --provider=gemini --api-key=YOUR_KEY
```

For fully unattended installation (defaults to Claude Max Plan, skips observation feed):

```bash
curl -fsSL https://install.cmem.ai/openclaw.sh | bash -s -- --non-interactive
```

To upgrade an existing installation (preserves settings, updates plugin):

```bash
curl -fsSL https://install.cmem.ai/openclaw.sh | bash -s -- --upgrade
```

After installation, skip to [Step 4: Restart the Gateway and Verify](#step-4-restart-the-gateway-and-verify) to confirm everything is working.

---

## Manual Setup

The steps below are for manual installation if you prefer not to use the automated installer, or need to troubleshoot individual steps.

### Step 1: Clone the Claude-Mem Repo

First, clone the claude-mem repository to a location accessible by your OpenClaw gateway. This gives you the worker service source and the plugin code.

```bash
cd /opt  # or wherever you want to keep it
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem
npm install
npm run build
```

You'll need **bun** installed for the worker service. If you don't have it:

```bash
curl -fsSL https://bun.sh/install | bash
```

### Step 2: Get the Worker Running

The claude-mem worker is an HTTP service on port 37777. It stores observations, generates summaries, and serves the context timeline. The plugin talks to it over HTTP — it doesn't matter where the worker is running, just that it's reachable on localhost:37777.

#### Check if it's already running

If this machine also runs Claude Code with claude-mem installed, the worker may already be running:

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

**Got `{"status":"ok"}`?** The worker is already running. Skip to Step 3.

**Got connection refused or no response?** The worker isn't running. Continue below.

#### If Claude Code has claude-mem installed

If claude-mem is installed as a Claude Code plugin (at `~/.claude/plugins/marketplaces/thedotmack/`), start the worker from that installation:

```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run worker:restart
```

Verify:
```bash
curl http://localhost:37777/api/health
```

**Got `{"status":"ok"}`?** You're set. Skip to Step 3.

**Still not working?** Check `npm run worker:status` for error details, or check that bun is installed and on your PATH.

#### If there's no Claude Code installation

Run the worker from the cloned repo:

```bash
cd /opt/claude-mem  # wherever you cloned it
npm run worker:start
```

Verify:
```bash
curl http://localhost:37777/api/health
```

**Got `{"status":"ok"}`?** You're set. Move to Step 3.

**Still not working?** Debug steps:
- Check that bun is installed: `bun --version`
- Check the worker status: `npm run worker:status`
- Check if something else is using port 37777: `lsof -i :37777`
- Check logs: `npm run worker:logs` (if available)
- Try running it directly to see errors: `bun plugin/scripts/worker-service.cjs start`

### Step 3: Add the Plugin to Your Gateway

Add the `claude-mem` plugin to your OpenClaw gateway configuration:

```json
{
  "plugins": {
    "claude-mem": {
      "enabled": true,
      "config": {
        "project": "my-project",
        "syncMemoryFile": true,
        "workerPort": 37777
      }
    }
  }
}
```

#### Config fields explained

- **`project`** (string, default: `"openclaw"`) — The project name that scopes all observations in the memory database. Use a unique name per gateway/use-case so observations don't mix. For example, if this gateway runs a coding bot, use `"coding-bot"`.

- **`syncMemoryFile`** (boolean, default: `true`) — When enabled, the plugin injects the observation timeline into each agent's system prompt via the `before_prompt_build` hook. This gives agents cross-session context without writing to MEMORY.md. Set to `false` to disable context injection entirely (observations are still recorded).

- **`syncMemoryFileExclude`** (string[], default: `[]`) — Agent IDs excluded from automatic context injection. Useful for agents that curate their own memory. Observations are still recorded for excluded agents.

- **`workerPort`** (number, default: `37777`) — The port where the claude-mem worker service is listening. Only change this if you configured the worker to use a different port.

---

## Step 4: Restart the Gateway and Verify

Restart your OpenClaw gateway so it picks up the new plugin configuration. After restart, check the gateway logs for:

```
[claude-mem] OpenClaw plugin loaded — v1.0.0 (worker: 127.0.0.1:37777)
```

If you see this, the plugin is loaded. You can also verify by running `/claude_mem_status` in any OpenClaw chat:

```
Claude-Mem Worker Status
Status: ok
Port: 37777
Active sessions: 0
Observation feed: disconnected
```

The observation feed shows `disconnected` because we haven't configured it yet. That's next.

## Step 5: Verify Observations Are Being Recorded

Have an agent do some work. The plugin automatically records observations through these OpenClaw events:

1. **`before_agent_start`** — Initializes a claude-mem session when the agent starts
2. **`before_prompt_build`** — Injects the observation timeline into the agent's system prompt (cached fo