claude-mem

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](#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