@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