AgentBay + OpenClaw
Give your OpenClaw agent a persistent brain. Memories survive restarts, context transfers between sessions, and knowledge shares across your agent fleet.
OpenClaw connects to AgentBay via the website installer plus the setup CLI (curl -sSL https://www.aiagentsbay.com/install-openclaw.sh | bash) or plain MCP. The installer downloads the current AgentBay OpenClaw package archive from the AgentBay website, builds it locally, installs a stable agentbay-openclaw wrapper, then runs the setup CLI. The setup CLI now installs or refreshes the AgentBay plugin automatically and, in strict mode, disables OpenClaw's bundled memory-core plugin so AgentBay becomes the default explicit memory layer. The plugin injects an AgentBay-first operating protocol before each turn, auto-loads a runtime context pack, auto-captures learnings after each turn, and the setup CLI installs stronger runtime defaults.
┌─────────────────────────────────────────────────────────┐
│ Your Machine │
│ │
│ ┌──────────────┐ ┌──────────────────────────┐ │
│ │ │ MCP │ │ │
│ │ OpenClaw │────────▶│ AgentBay MCP Server │ │
│ │ Agent │◀────────│ (npx aiagentsbay-mcp) │ │
│ │ │ │ │ │
│ └──────────────┘ └────────────┬─────────────┘ │
│ │ │
└────────────────────────────────────────┼────────────────┘
│ HTTPS
▼
┌───────────────────────┐
│ │
│ AgentBay Cloud │
│ │
│ ┌─────────────────┐ │
│ │ Memory Engine │ │
│ │ ┌───┐ ┌───┐ │ │
│ │ │FTS│ │VEC│ │ │
│ │ └───┘ └───┘ │ │
│ │ ┌───┐ ┌───┐ │ │
│ │ │TAG│ │ALI│ │ │
│ │ └───┘ └───┘ │ │
│ └─────────────────┘ │
│ │
│ ┌─────────────────┐ │
│ │ Knowledge DB │ │
│ │ (encrypted) │ │
│ └─────────────────┘ │
│ │
└───────────────────────┘Figure 1: Single Agent — Memory Flow
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ OpenClaw │ │ Claude Code │ │ Cursor │
│ (Mac Mini) │ │ (Laptop) │ │ (IDE) │
└──────┬───────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
│ MCP │ MCP │
▼ ▼ ▼
┌────────────────────────────────────────────────────┐
│ AgentBay Cloud │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Brain A │ │ Brain B │ │ Brain C │ │
│ │(OpenClaw)│ │(Claude) │ │(Cursor) │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ └──────────────┼──────────────┘ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Shared Team │ │
│ │ Knowledge │ │
│ │ │ │
│ │ Auto-shared │ │
│ │ pitfalls, │ │
│ │ decisions, │ │
│ │ patterns │ │
│ └──────────────────┘ │
│ │
└────────────────────────────────────────────────────┘Figure 2: Multi-Agent Team — Shared Knowledge
Local-first option: OpenClaw can use AgentBay in pure local mode by running the Python SDK against a SQLite store on the same machine. Install with pip install agentbay and call AgentBay() from a small skill — no signup, no API key, fully offline. Use the native plugin or MCP setup below when you want shared cloud memory across the OpenClaw daemon and other agents.
Honest limitation: strict mode disables OpenClaw's bundled memory-core plugin, but AgentBay still does not own the full runtime lifecycle. OpenClaw's core runtime still controls compaction behavior and other internal turn mechanics, and there is still no native pre-compaction hook exposed directly to external setup scripts. There is also a stock OpenClaw boundary for CLI-backed agents such as openai-codex/*: those runs go through OpenClaw's runCliAgent path, which does not wire plugin hooks. Strict setup applies an AgentBay CLI runtime patch for that path so recall and capture are automatic for those agents too.
Setup Guide
Run the installer. It pulls the current AgentBay OpenClaw package archive from the AgentBay website, builds it locally, installs the agentbay-openclaw wrapper in ~/.local/bin, then runs strict setup automatically:
export AGENTBAY_API_KEY="ab_live_YOUR_KEY_HERE" export AGENTBAY_PROJECT="proj_YOUR_PROJECT_ID" curl -sSL https://www.aiagentsbay.com/install-openclaw.sh | bash
The installer accepts either AGENTBAY_API_KEY or AGENTBAY_SETUP_TOKEN. Use AGENTBAY_OPENCLAW_MODE=compatible only if you intentionally want to keep OpenClaw's bundled memory-core plugin enabled as a local cache.
This gives you:
- Context packs — AgentBay assembles relevant recall, working state, architecture, dependencies, pitfalls, and likely next context before turns; strict mode patches OpenClaw's CLI runner for
openai-codex/*agents - Auto-capture — extracts capturable learnings after turns and stores them, including through the strict CLI runtime patch
- AgentBay-first protocol — every turn gets the same recall / store / sub-agent briefing rules
- 8 agent tools — memory_context_pack, memory_checkpoint, memory_policy_status, memory_search, memory_store, memory_list, memory_get, memory_forget
- Runtime defaults — 600s timeout, larger working context, gpt-5.4 fallback
- Strict memory mode by default — disables
memory-coreso AgentBay owns the explicit memory tool surface - Compatible mode available — keep
memory-coreonly when you explicitly choose it
The setup CLI also writes AGENTBAY-SOUL.md and AGENTBAY-BOOTSTRAP.md reference files into your OpenClaw workspace, runs the first cache warm (pull), and installs a LaunchAgent for sync automation (macOS). It detects a running gateway and reminds you to restart it. No API key yet? Create a free account.
If you already have the package installed locally, the underlying direct command is agentbay-openclaw setup --api-key "$AGENTBAY_API_KEY" --project "$AGENTBAY_PROJECT".
Use --force-runtime-defaults only when you want AgentBay to overwrite your existing OpenClaw fallback-model chain with the recommended defaults.
After setup, verify everything:
# Check integration health (PASS / WARN / FAIL for each component) agentbay-openclaw doctor # Prove runtime is operational with real API round-trips and runtime patch checks agentbay-openclaw verify-runtime # Seed a sentinel memory, run a real OpenClaw agent turn, and prove injected recall + capture agentbay-openclaw verify-live --agent research
If your configured agents use a known CLI-backed model family such as openai-codex/*,verify-runtime checks that the AgentBay CLI runtime patch is installed. That patch is what makes automatic recall and capture work for stock OpenClaw's CLI-backed path. verify-live is the stronger proof: it stores a sentinel in AgentBay, runs OpenClaw, requires the model to echo that sentinel from injected context, and accepts either immediate capture or a local capture queue entry when AgentBay write rate limits are active.
- Go to aiagentsbay.com/register and create a free account
- Open Dashboard → API Keys
- Click Create API Key — copy the
ab_live_...key
Add the MCP server to your openclaw.json:
// In openclaw.json, add:
{
"mcp": {
"servers": {
"agentbay": {
"command": "/path/to/npx",
"args": ["-y", "aiagentsbay-mcp@latest", "--api-key", "ab_live_YOUR_KEY"]
}
}
}
}Use the full path to npx (e.g. /opt/homebrew/opt/node@22/bin/npx) since OpenClaw's daemon may not inherit your shell PATH. The MCP path gives access to all tools but does not include auto-recall/auto-capture hooks or the runtime defaults installed by install-openclaw.sh / agentbay-openclaw setup — use the native plugin path for that.
If you are using the MCP path or a local-first AgentBay skill instead of the native plugin, use the same operating protocol the setup CLI installs for native-plugin users.
# AgentBay Memory Skill for OpenClaw - Build a context pack before non-trivial work or before spawning a sub-agent. - Store patterns, pitfalls, decisions, and architecture notes after meaningful work. - Save active task state with a checkpoint before compaction or handoff. - Use the policy report when you need to verify recent work is actually touching AgentBay. - Add filePaths and subsystem tags so future recall is code-aware. - Use handoffs for active task state; use memory for durable lessons. - Never store raw code, shell noise, or secrets.
Versioned copies are available at /docs/agentbay-openclaw-skill.md, /docs/agentbay-openclaw-soul.md, and /docs/agentbay-openclaw-bootstrap.md.
Once connected, your OpenClaw agent can build a full context pack, checkpoint active state, and store durable memory using MCP tools.
# Your agent calls these MCP tools automatically: # Build a runtime context pack memory_context_pack( query="debug the JWT refresh regression in auth.ts", filePaths=["src/auth.ts"] ) # → Returns relevant recall + working state + pitfalls + likely next memories # Store a pattern agentbay_memory_store( title="Auth uses JWT with 24h expiry", content="The authentication system uses JWT tokens...", type="PATTERN", tags=["auth", "jwt", "security"] ) # Recall relevant memories agentbay_memory_recall( query="how does authentication work?" ) # → Returns matching memories ranked by relevance # Save resumable working state memory_checkpoint( title="JWT refresh debugging state", content="Confirmed refresh token rotation bug is in middleware ordering", filePaths=["src/auth.ts"] )
Projects scope memories to a specific codebase. Your agent gets full context on join.
# Create a project agentbay_project_create(name="my-app") # One-call onboarding — agent gets everything: agentbay_project_onboard(project_id="...") # → Returns: file tree, tasks, knowledge, failures, directives # Store project-scoped knowledge agentbay_knowledge_record( project_id="...", title="Database migration pattern", content="Always use prisma db push, never migrate dev in prod", type="PITFALL" )
Teams let multiple agents share knowledge. When one agent learns a pitfall, every agent on the team sees it.
# Your OpenClaw agent joins a team with other agents # (Claude Code, Cursor, custom agents) # Set auto-share policy — pitfalls propagate automatically agentbay_team_set_policy( team_id="...", auto_share_types=["PITFALL", "DECISION", "ARCHITECTURE"] ) # Now when OpenClaw stores a PITFALL: # → Auto-shared to Claude Code and Cursor # → They see it before making the same mistake
Every memory goes through a lifecycle that keeps knowledge fresh and relevant.
Agent stores memory
│
▼
┌──────────────┐
│ Validation │──── Poison detection (20+ patterns)
│ & Dedup │──── Duplicate check (title + type)
└──────┬────────┘
│
▼
┌──────────────┐
│ Persist & │──── Encrypt content (AES-256)
│ Embed │──── Generate search vectors
└──────┬────────┘
│
▼
┌──────────────┐
│ Entity │──── Extract: files, functions, tools
│ Extraction │──── Auto-link related entries
└──────┬────────┘
│
▼
┌──────────────┐
│ Team │──── If type matches auto-share policy
│ Auto-Share │──── Copy to team scope
└──────┬────────┘
│
│ ┌──────────────────────┐
│ Nightly ────────▶│ Dreaming Cycle │
│ │ │
│ │ • Promote entries │
│ │ • Synthesize related │
│ │ • Find conflicts │
│ │ • Update vectors │
│ └──────────────────────┘
│
▼
┌──────────────┐
│ Recall │──── 4-strategy fusion search
│ (on query) │──── Confidence-weighted ranking
└──────────────┘Figure 3: Memory Lifecycle — From Store to Consolidation
When your agent recalls a memory, AgentBay runs four independent search strategies in parallel and fuses the results for maximum accuracy.
┌─────────────┐
│ Query │
│ "auth bug" │
└──────┬──────┘
│
┌────────────┼────────────┐
│ │ │
▼ ▼ ▼
┌────────────┐ ┌───────────┐ ┌───────────┐
│ Alias │ │ Tag │ │ Full-Text │
│ Matching │ │ Intersect │ │ Search │
│ │ │ │ │ (BM25) │
│ Exact name │ │ Category │ │ Keyword │
│ lookups │ │ matching │ │ ranking │
└─────┬──────┘ └─────┬─────┘ └─────┬─────┘
│ │ │
└──────────────┼──────────────┘
│
▼
┌─────────────────┐
│ RRF Fusion │
│ │
│ Combines all │
│ strategies │
│ by rank │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Confidence │
│ Weighting │
│ │
│ Fresh > Stale │
│ Verified > New │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Top Results │
│ (ranked) │
└─────────────────┘Figure 4: Multi-Strategy Search Fusion
This multi-strategy approach means your agent finds the right memory whether the query is an exact function name (getUserById), a tag-based category (auth), or a natural language question (how does the login flow work?).
Store These
- PATTERN Reusable code patterns
- PITFALL Bugs and their root causes
- DECISION Why you chose X over Y
- ARCHITECTURE System design choices
- DEPENDENCY Library configurations
- PERFORMANCE Optimization notes
- CONTEXT Deploy configs, env vars
- TEST_INSIGHT Testing strategies
Don't Store These
- Raw logs or stack traces (store the fix, not the noise)
- Temporary status updates
- Secrets or API keys (use env vars)
- Entire file contents (store patterns from the file)
- Duplicate information (auto-dedup handles this)
┌─────────────────────────────────────────────┐
│ Agent Request │
└─────────────────────┬───────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Authentication │ API key validation │
│ │ Rate limiting │
└─────────────────────┬───────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Content Safety │ Poison detection │
│ │ (prompt injection, │
│ │ data exfiltration, │
│ │ destructive cmds) │
└─────────────────────┬───────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Encryption │ AES-256 at rest │
│ │ HTTPS in transit │
└─────────────────────┬───────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Access Control │ Project-scoped │
│ │ Team roles │
│ │ Agent permissions │
└─────────────────────────────────────────────┘Figure 5: Security Layers
Every memory write is scanned for prompt injection, data exfiltration, and destructive commands before storage. Content is encrypted at rest. Team sharing uses role-based access control (admin, contributor, viewer, auditor).
For deeper integration, use the Python SDK alongside MCP.
from agentbay import AgentBay
# Connect to your brain
brain = AgentBay("ab_live_your_key", project_id="your-project")
# Auto-memory chat — wraps any LLM call
response = brain.chat(
[{"role": "user", "content": "Fix the auth session bug"}],
provider="openai",
model="gpt-4o"
)
# Automatically: recalls relevant memories → injects context → calls LLM → stores learnings
# Direct memory operations
brain.store("Always hash passwords with bcrypt cost 12",
title="Password hashing", type="PATTERN")
results = brain.recall("password security")
# Team operations
brain.team("my-team").set_policy(auto_share_types=["PITFALL", "DECISION"])
brain.team("my-team").invite("cursor-agent", role="contributor")