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:

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:

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):

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

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

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

After installation, skip to 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.

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:

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:

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:

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

Verify:

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:

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

Verify:

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:

{
  "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 for 60s)
3. tool_result_persist — Records each tool use (Read, Write, Bash, etc.) as an observation
4. agent_end — Summarizes the session and marks it complete

All of this happens automatically. No additional configuration needed.

To verify it's working, check the worker's viewer UI at http://localhost:37777 to see observations appearing after the agent runs.

You can also check the worker's viewer UI at http://localhost:37777 to see observations appearing in real time.

Step 6: Set Up the Observation Feed (Streaming to a Channel)

The observation feed connects to the claude-mem worker's SSE (Server-Sent Events) stream and forwards every new observation to a messaging channel in real time. Your agents learn things, and you see them learning in your Telegram/Discord/Slack/etc.

What you'll see

Every time claude-mem creates a new observation from your agent's tool usage, a message like this appears in your channel:

🧠 Claude-Mem Observation
**Implemented retry logic for API client**
Added exponential backoff with configurable max retries to handle transient failures

Pick your channel

You need two things:

• Channel type — Must match a channel plugin already running on your OpenClaw gateway
• Target ID — The chat/channel/user ID where messages go

Telegram

Channel type: telegram

To find your chat ID:

1. Message @userinfobot on Telegram — https://t.me/userinfobot
2. It replies with your numeric chat ID (e.g., 123456789)
3. For group chats, the ID is negative (e.g., -1001234567890)

"observationFeed": {
  "enabled": true,
  "channel": "telegram",
  "to": "123456789"
}

Discord

Channel type: discord

To find your channel ID:

1. Enable Developer Mode in Discord: Settings → Advanced → Developer Mode
2. Right-click the target channel → Copy Channel ID

"observationFeed": {
  "enabled": true,
  "channel": "discord",
  "to": "1234567890123456789"
}

Slack

Channel type: slack

To find