Setting Up memoclaw-hooks: Zero-Code Persistent Memory for Your OpenClaw Agent

Your OpenClaw agent forgets everything between sessions. It reads MEMORY.md, sure, but that file grows stale, eats context window, and doesn’t scale. You end up with a 2,000-line markdown file that your agent greps through hoping to find something relevant.

memoclaw-hooks fixes this. It plugs MemoClaw’s semantic memory directly into OpenClaw’s lifecycle. Your agent automatically recalls relevant memories when a session starts, stores important context when it ends, and consolidates duplicates in the background.

No code changes. No prompt engineering. Three commands and a restart.

What You’ll Build

By the end of this tutorial, your OpenClaw agent will:

  • Recall relevant memories at the start of every session, based on what the user says
  • Store important context when a session ends or resets (via /new)
  • Preserve key information before context compaction throws it away
  • Consolidate duplicate memories every 6 hours
  • Restore recent context when the gateway restarts

All of this happens automatically. Your agent doesn’t need to call any commands or know that MemoClaw exists.

Prerequisites

  • OpenClaw installed and running (openclaw gateway status should show it’s active)
  • Node.js 18+ (node --version)
  • A terminal with shell access

You don’t need a crypto wallet yet. memoclaw init will generate one for you, and the free tier gives you 100 API calls to test with.

Step 1: Install the MemoClaw CLI

npm install -g memoclaw

Verify it’s installed:

memoclaw --version

Step 2: Initialize Your Wallet

MemoClaw uses your wallet address as your identity. No accounts, no API keys, no registration.

memoclaw init

This generates a new EVM wallet and saves the config to ~/.memoclaw/config.json. You’ll see output like:

✓ Generated new wallet
  Address: 0x1234...abcd
  Config saved to ~/.memoclaw/config.json
  Free tier: 100 API calls remaining

Keep the private key safe. It’s your identity and payment method rolled into one.

If you already have a wallet you want to use:

memoclaw init --private-key 0xYourExistingKey

Step 3: Install and Enable the Hook

openclaw hooks install memoclaw-hooks
openclaw hooks enable memoclaw

That’s it. The hook pack is now registered with OpenClaw.

Step 4: Set Your Private Key

The hook needs your wallet’s private key to authenticate API calls. You can set it as an environment variable:

export MEMOCLAW_PRIVATE_KEY=0xYourPrivateKey

Or add it to your OpenClaw config for persistence:

# In your OpenClaw config
env:
  MEMOCLAW_PRIVATE_KEY: "0xYourPrivateKey"

Step 5: Restart the Gateway

openclaw gateway restart

The hook activates on gateway startup. When it loads, it recalls the 3 most recent memories to restore agent continuity.

Step 6: Verify Everything Works

Check that the hook is loaded:

openclaw hooks list --verbose

You should see memoclaw in the list with status enabled.

Run the health check:

openclaw hooks check

This confirms the hook can reach the MemoClaw API and your wallet is configured correctly.

What Happens Under the Hood

Once installed, the hook fires on five OpenClaw lifecycle events:

Session Start

When a user sends their first message, the hook takes that message, runs a semantic recall against your stored memories, and injects the results as system context. Your agent sees something like:

[MemoClaw] Relevant memories:
- (0.92) User prefers direct communication, no fluff
- (0.87) Project uses PostgreSQL with JSONB columns
- (0.81) Last session: shipped v2.1 auth migration

The scores (0.92, 0.87, etc.) are semantic similarity to the user’s message. Higher scores mean more relevant context.

/new Command

When the user runs /new to reset the session, the hook extracts important facts from the conversation and stores them before wiping the slate. This uses the extract endpoint, which costs $0.01 per call.

Context Compaction

OpenClaw compresses context when the conversation gets long. Before that compression happens, the hook stores key information so it isn’t lost. Your agent might not remember the full conversation, but the important bits persist in MemoClaw.

Heartbeat (Every 6 Hours)

The hook runs consolidate during heartbeat cycles. This merges duplicate or near-duplicate memories. If your agent stored “user likes dark mode” in three different sessions, consolidation merges them into one clean memory.

You can adjust the interval:

export MEMOCLAW_HOOK_CONSOLIDATE_INTERVAL_MS=43200000  # 12 hours

Gateway Startup

When the gateway restarts, the hook recalls the 3 most recent memories. This gives your agent some continuity even before the first user message.

Configuring Namespaces for Multi-Agent Setups

If you run multiple agents on the same wallet, use namespaces to keep their memories separate:

# Agent-specific memories
export MEMOCLAW_NAMESPACE=agent-frontend

# Or shared memories across agents
export MEMOCLAW_NAMESPACE=shared-project

Same wallet + different namespaces = isolated recall. Same wallet + same namespace = shared memory. This is useful for agent-to-agent knowledge sharing — a research agent can store findings that a writing agent later recalls.

Adding Manual Memory Commands

The hooks handle the automatic lifecycle, but sometimes your agent needs to store or recall memories mid-conversation. Install the MemoClaw skill for that:

clawhub install anajuliabit/memoclaw

Now your agent can run commands like:

memoclaw store "User's deployment target is Vercel" --importance 0.9 --tags stack
memoclaw recall "What's the deployment setup?"

The skill and hooks complement each other: hooks handle background automation, the skill gives your agent direct control when it needs it.

Costs

The hooks are lightweight. A typical session lifecycle makes 2–4 API calls:

  • Session start recall: $0.005
  • Session end extract + store: $0.01 + $0.005
  • Consolidation (every 6h): $0.01

At normal usage, you’re looking at a few cents per day. The free tier (100 calls) covers initial testing.

All core memory, list, and stats endpoints are free and don’t count toward your quota.

Troubleshooting

Hook not showing in hooks list?

Make sure you ran both install and enable:

openclaw hooks install memoclaw-hooks
openclaw hooks enable memoclaw

“Wallet not configured” error?

The hook can’t find your private key. Check that MEMOCLAW_PRIVATE_KEY is set in the environment where OpenClaw runs:

echo $MEMOCLAW_PRIVATE_KEY

If it’s empty, re-export it or add it to your OpenClaw config.

No memories appearing on session start?

On a fresh install, there are no memories to recall. Have a conversation, run /new to trigger extraction, then start a new session. The hook will recall what it stored.

Consolidation not running?

The default interval is 6 hours. Check the interval setting:

echo $MEMOCLAW_HOOK_CONSOLIDATE_INTERVAL_MS

You can trigger a manual consolidation via the CLI:

memoclaw consolidate --namespace default

What’s Next