OpenClaw | Spectron

The @surrealdb/spectron-openclaw plugin backs OpenClaw agent memory with Spectron. 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 Spectron endpoint, API key, and context id (SurrealDB Cloud or the self-hosted Spectron binary)

Install

openclaw plugins install @surrealdb/spectron-openclaw
openclaw spectron setup
openclaw gateway restart

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

Configure

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

{
  "plugins": {
    "entries": {
      "spectron": {
        "enabled": true,
        "hooks": {
          "allowConversationAccess": true,
          "allowPromptInjection": true
        },
        "config": {
          "endpoint": "${SPECTRON_ENDPOINT}",
          "apiKey": "${SPECTRON_API_KEY}",
          "context": "${SPECTRON_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	Spectron 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 Spectron's operations onto OpenClaw's agent lifecycle:

OpenClaw hook	What happens
`before_prompt_build`	Relevant memory is injected as `<spectron_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` / `spectron index`	Workspace memory files (`MEMORY.md`, `memory/**`) are seeded

Agent tools

The agent can call these directly: spectron_recall, spectron_context, spectron_remember, spectron_reflect, spectron_forget, spectron_upload, and spectron_inspect.

CLI

openclaw spectron setup [--takeover]   # print config + required hook flags
openclaw spectron status               # config, slot mode, and identity
openclaw spectron health               # check the connection
openclaw spectron index                # seed workspace memory files
openclaw spectron recall <query>       # search memory
openclaw spectron reflect <query>      # synthesise an answer from memory
openclaw spectron 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 spectron setup --takeover prints a patch that sets plugins.slots.memory to spectron, making Spectron the sole memory provider.