@surrealdb/agent-memory-openclaw

OpenClaw plugin that backs agent memory with SurrealDB Agent Memory.

It gives an OpenClaw 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 gets tools and a CLI for deliberate memory access. Agent Memory stores memory, knowledge graphs, and documents in one ACID context, so what the agent learns stays consistent.

How it works

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

| Agent Memory | OpenClaw hook | What happens | Gated by | | --- | --- | --- | --- | | context / recall | before_prompt_build | Relevant memory is injected as <agent_memory> before the model runs | autoRecall + hooks.allowPromptInjection | | rememberMany | agent_end | The turn is persisted (platform metadata stripped) | autoCapture + hooks.allowConversationAccess | | consolidate | session_end | Recent facts are consolidated into durable observations | autoConsolidate | | documents.upload | gateway_start + agentMemory index | Workspace memory files (MEMORY.md, memory/**) are seeded | autoIndex | | remember / recall / context / reflect / forget / inspect / upload | agent tools | Deliberate memory access mid-conversation | always |

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

Prerequisites

• OpenClaw >= 2026.4.27 (the version where agent_end requires allowConversationAccess).
• An Agent Memory endpoint and API key, either SurrealDB Cloud or the self-hosted Agent Memory binary, plus a context id. Each context is its own SurrealDB namespace and database.

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. Local development install:

npm install && npm run build
openclaw plugins install -l .

Configure

Configuration lives in ~/.openclaw/openclaw.json under plugins.entries.agentMemory:

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

Both hook flags are required. allowConversationAccess lets OpenClaw deliver agent_end to the plugin (without it, per-turn persistence is silently skipped). allowPromptInjection lets the plugin inject recalled context. Connection fields accept ${ENV_VAR} references so secrets stay out of the config file.

Config reference (plugins.entries.agentMemory.config)

| Key | Default | Purpose | | --- | --- | --- | | endpoint | required | Agent Memory API origin, no trailing slash | | apiKey | required | Bearer API key (sp-...) | | context | required | Agent Memory context id (namespace + database) | | recallLens / recallScope | whole region | Read lens narrowing recall (scope path, or array of paths) | | writeScope | key default | Scope written memories are tagged with | | onBehalfOf | (none) | Principal id for delegated calls (X-AgentMemory-On-Behalf-Of) | | 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 / index | | recallK | 5 | Max hits per recall | | injectMode | "context" | context (formatted text) or recall (ranked hits) | | infer | "full" | Extraction mode: full, triples, preview, none | | requestTimeoutMs | 60000 | Per-request timeout |

Scopes follow Agent Memory's DNF syntax: a path string "team/eng", an OR of paths ["a", "b"], or a nested AND clause [["a", "b"]].

Agent tools

The agent can call these directly:

• agent_memory_recall: semantic search over memory (start here).
• agent_memory_context: memory as prompt-ready context text.
• agent_memory_remember: store a fact or note.
• agent_memory_reflect: LLM synthesis over memory, optionally persisted.
• agent_memory_forget: remove memories matching a description.
• agent_memory_upload: ingest a document body.
• agent_memory_inspect: resolve a specific entity/attribute/relation/passage/trace ref.

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

Examples

See examples/: two ready-to-merge OpenClaw configs (augment and takeover) and a runnable quickstart.ts that walks through each Agent Memory operation the plugin drives.

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 Agent Memory the sole memory provider. The slot ownership contract is inferred from the OpenClaw docs and is not yet verified against a pinned release, so treat takeover as experimental.

Verification

Unit tests run without an Agent Memory endpoint (an in-memory fake client stands in):

npm run typecheck
npm test
npm run build

End-to-end against a real Agent Memory (requires an endpoint + key):

export AGENT_MEMORY_ENDPOINT=... AGENT_MEMORY_API_KEY=... AGENT_MEMORY_CONTEXT=...
openclaw agentMemory setup
openclaw agentMemory health          # expect: healthy
# run an agent turn, then:
openclaw agentMemory recall "<something the agent just discussed>"
openclaw agentMemory status

Notes

• Built against @surrealdb/memory (alpha) and the documented OpenClaw plugin API. Both are young; pin versions and re-check the hook and CLI registration surfaces if either drifts.
• Memory "types" (working, semantic, episodic, and so on) are a conceptual framing over Agent Memory's fact/entity/document substrate, not an API parameter. Categorisation is influenced through infer and scopes.

License

Apache-2.0