OpenClaw | Agent frameworks

The @surrealdb/agent-memory-openclaw plugin backs OpenClaw agent memory with SurrealDB Agent Memory. It gives an agent long-term memory that survives session restarts and fresh chats: relevant memory is recalled before each turn, each turn is persisted afterwards, and the agent gains tools and a CLI for deliberate memory access.

By default the plugin augments OpenClaw's built-in memory. It can optionally take over the memory slot (see Memory modes).

Prerequisites

OpenClaw 2026.4.27 or newer
a SurrealDB Agent Memory endpoint, API key, and context id (SurrealDB Cloud or the self-hosted Agent Memory binary)

Install

openclaw plugins install @surrealdb/agent-memory-openclaw
openclaw agentMemory setup
openclaw gateway restart

openclaw agentMemory setup prints the config block and the two hook flags to add.

Configure

Configuration lives in ~/.openclaw/openclaw.json under plugins.entries.agentMemory. Connection fields accept ${ENV_VAR} references so secrets stay out of the file:

{
  "plugins": {
    "entries": {
      "agentMemory": {
        "enabled": true,
        "hooks": {
          "allowConversationAccess": true,
          "allowPromptInjection": true
        },
        "config": {
          "endpoint": "${AGENT_MEMORY_ENDPOINT}",
          "apiKey": "${AGENT_MEMORY_API_KEY}",
          "context": "${AGENT_MEMORY_CONTEXT}"
        }
      }
    }
  }
}

Important

Both hook flags are required. allowConversationAccess lets OpenClaw deliver the agent_end event to the plugin. Without it, per-turn persistence is silently skipped. allowPromptInjection lets the plugin inject recalled context.

Config reference

Key	Default	Purpose
`endpoint`	required	SurrealDB Agent Memory API origin, no trailing slash
`apiKey`	required	Bearer API key
`context`	required	Context id (namespace and database)
`recallScope`	whole region	Read lens narrowing recall (scope path, or array of paths)
`writeScope`	key default	Scope written memories are tagged with
`autoRecall`	`true`	Inject memory before each turn
`autoCapture`	`true`	Persist each turn
`autoConsolidate`	`true`	Consolidate at session end
`autoIndex`	`true`	Seed workspace memory files on start or `index`
`recallK`	`5`	Max hits per recall
`injectMode`	`"context"`	`context` (formatted text) or `recall` (ranked hits)

How it works

The plugin maps SurrealDB Agent Memory's operations onto OpenClaw's agent lifecycle:

OpenClaw hook	What happens
`before_prompt_build`	Relevant memory is injected as `<agent_memory>` before the model runs
`agent_end`	The turn is persisted, with platform metadata stripped
`session_end`	Recent facts are consolidated into durable observations
`gateway_start` / `agentMemory index`	Workspace memory files (`MEMORY.md`, `memory/**`) are seeded

Agent tools

The agent can call these directly: agent_memory_recall, agent_memory_context, agent_memory_remember, agent_memory_reflect, agent_memory_forget, agent_memory_upload, and agent_memory_inspect.

CLI

openclaw agentMemory setup [--takeover]   # print config + required hook flags
openclaw agentMemory status               # config, slot mode, and identity
openclaw agentMemory health               # check the connection
openclaw agentMemory index                # seed workspace memory files
openclaw agentMemory recall <query>       # search memory
openclaw agentMemory reflect <query>      # synthesise an answer from memory
openclaw agentMemory forget <query>       # forget matching memories

Memory modes

Augment (default): runs alongside the built-in memory core. Nothing about the memory slot changes.
Takeover (experimental): openclaw agentMemory setup --takeover prints a patch that sets plugins.slots.memory to agentMemory, making SurrealDB Agent Memory the sole memory provider.