Persistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Cla
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add thedotmack/claude-mem --skill openclaw -a cursor -y
Persistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More
Persistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More
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.
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.
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.
The steps below are for manual installation if you prefer not to use the automated installer, or need to troubleshoot individual steps.
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
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.
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-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.
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:
bun --versionnpm run worker:statuslsof -i :37777npm run worker:logs (if available)bun plugin/scripts/worker-service.cjs startAdd the claude-mem plugin to your OpenClaw gateway configuration:
{
"plugins": {
"claude-mem": {
"enabled": true,
"config": {
"project": "my-project",
"syncMemoryFile": true,
"workerPort": 37777
}
}
}
}
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.
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.
Have an agent do some work. The plugin automatically records observations through these OpenClaw events:
before_agent_start — Initializes a claude-mem session when the agent startsbefore_prompt_build — Injects the observation timeline into the agent's system prompt (cached for 60s)after_tool_call — Records each tool use (Read, Write, Bash, etc.) as an observationagent_end — Summarizes the session and marks it completeAll 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.
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.
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
You need two things:
Channel type: telegram
To find your chat ID:
123456789)-1001234567890)"observationFeed": {
"enabled": true,
"channel": "telegram",
"to": "123456789"
}
Channel type: discord
To find your channel ID:
"observationFeed": {
"enabled": true,
"channel": "discord",
"to": "1234567890123456789"
}
Channel type: slack
To find your channel ID (not the channel name):
C01ABC2DEFG"observationFeed": {
"enabled": true,
"channel": "slack",
"to": "C01ABC2DEFG"
}
Channel type: signal
Use the phone number or group ID configured in your OpenClaw gateway's Signal plugin.
"observationFeed": {
"enabled": true,
"channel": "signal",
"to": "+1234567890"
}
Channel type: whatsapp
Use the phone number or group JID configured in your OpenClaw gateway's WhatsApp plugin.
"observationFeed": {
"enabled": true,
"channel": "whatsapp",
"to": "+1234567890"
}
Channel type: line
Use the user ID or group ID from the LINE Developer Console.
"observationFeed": {
"enabled": true,
"channel": "line",
"to": "U1234567890abcdef"
}
Your complete plugin config should now look like this (using Telegram as an example):
{
"plugins": {
"claude-mem": {
"enabled": true,
"config": {
"project": "my-project",
"syncMemoryFile": true,
"workerPort": 37777,
"observationFeed": {
"enabled": true,
"channel": "telegram",
"to": "123456789"
}
}
}
}
}
Restart the gateway. Check the logs for these three lines in order:
[claude-mem] Observation feed starting — channel: telegram, target: 123456789
[claude-mem] Connecting to SSE stream at http://localhost:37777/stream
[claude-mem] Connected to SSE stream
Then run /claude_mem_feed in any OpenClaw chat:
Claude-Mem Observation Feed
Enabled: yes
Channel: telegram
Target: 123456789
Connection: connected
If Connection shows connected, you're done. Have an agent do some work and watch observations stream to your channel.
The plugin registers two commands:
Reports worker health and current session state.
/claude_mem_status
Output:
Claude-Mem Worker Status
Status: ok
Port: 37777
Active sessions: 2
Observation feed: connected
Shows observation feed status. Accepts optional on/off argument.
/claude_mem_feed — show status
/claude_mem_feed on — request enable (update config to persist)
/claude_mem_feed off — request disable (update config to persist)
OpenClaw Gateway
│
├── before_agent_start ───→ Init session
├── before_prompt_build ──→ Inject context into system prompt
├── after_tool_call ──────→ Record observation
├── agent_end ────────────→ Summarize + Complete session
└── gateway_start ────────→ Reset session tracking + context cache
│
▼
Claude-Mem Worker (localhost:37777)
├── POST /api/sessions/init
├── POST /api/sessions/observations
├── POST /api/sessions/summarize
├── POST /api/sessions/complete
├── GET /api/context/inject ──→ System prompt context
└── GET /stream ─────────────→ SSE → Messaging channels
The plugin injects the observation timeline into each agent's system prompt via the before_prompt_build hook. The content comes from the worker's GET /api/context/inject endpoint. Context is cached for 60 seconds per project to avoid re-fetching on every LLM turn. The cache is cleared on gateway restart.
This keeps MEMORY.md under the agent's control for curated long-term memory, while the observation timeline is delivered through the system prompt.
Every tool use (Read, Write, Bash, etc.) is sent to the claude-mem worker as an observation. The worker's AI agent processes it into a structured observation with title, subtitle, facts, concepts, and narrative. Tools prefixed with memory_ are skipped to avoid recursive recording.
before_agent_start — Creates a session in the worker.before_prompt_build — Fetches the observation timeline and returns it as appendSystemContext. Cached for 60s.after_tool_call — Records observation (fire-and-forget) from the call's params and result; a failed call's response starts with its error text. Tool responses are truncated to 1000 characters.agent_end — Sends the last assistant message for summarization, then completes the session. Both fire-and-forget.gateway_start — Clears all session tracking (session IDs, context cache) so agents start fresh.A background service connects to the worker's SSE stream and forwards new_observation events to a configured messaging channel. The connection auto-reconnects with exponential backoff (1s → 30s max).
| Problem | What to check |
|---|---|
| Worker health check fails | Is bun installed? (bun --version). Is something else on port 37777? (lsof -i :37777). Try running directly: bun plugin/scripts/worker-service.cjs start |
| Worker started from Claude Code install but not responding | Check cd ~/.claude/plugins/marketplaces/thedotmack && npm run worker:status. May need npm run worker:restart. |
| Worker started from cloned repo but not responding | Check cd /path/to/claude-mem && npm run worker:status. Make sure you ran npm install && npm run build first. |
| No context in agent system prompt | Check that syncMemoryFile is not set to false. Check that the agent's ID is not in syncMemoryFileExclude. Verify the worker is running and has observations. |
| Observations not being recorded | Check gateway logs for [claude-mem] messages. The worker must be running and reachable on localhost:37777. |
Feed shows disconnected | Worker's /stream endpoint not reachable. Check workerPort matches the actual worker port. |
Feed shows reconnecting | Connection dropped. The plugin auto-reconnects — wait up to 30 seconds. |
Unknown channel type in logs | The channel plugin (e.g., telegram) isn't loaded on your gateway. Make sure the channel is configured and running. |
Observation feed disabled in logs | Set observationFeed.enabled to true in your config. |
Observation feed misconfigured in logs | Both observationFeed.channel and observationFeed.to are required. |
No messages in channel despite connected | The feed only sends processed observations, not raw tool usage. There's a 1-2 second delay. Make sure the worker is actually processing observations (check http://localhost:37777). |
{
"plugins": {
"claude-mem": {
"enabled": true,
"config": {
"project": "openclaw",
"syncMemoryFile": true,
"workerPort": 37777,
"observationFeed": {
"enabled": false,
"channel": "telegram",
"to": "123456789"
}
}
}
}
}
| Field | Type | Default | Description |
|---|---|---|---|
project | string | "openclaw" | Project name scoping observations in the database |
syncMemoryFile | boolean | true | Inject observation context into agent system prompt |
syncMemoryFileExclude | string[] | [] | Agent IDs excluded from context injection |
workerPort | number | 37777 | Claude-mem worker service port |
observationFeed.enabled | boolean | false | Stream observations to a messaging channel |
observationFeed.channel | string | — | Channel type: telegram, discord, slack, signal, whatsapp, line |
observationFeed.to | string | — | Target chat/channel/user ID |