# OpenClaw

OpenClaw plugin that backs agent memory with SurrealDB Agent Memory.

The `@surrealdb/spectron-openclaw` plugin backs [OpenClaw](https://docs.openclaw.ai/) 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](#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

```bash
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:

```json
{
  "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 | 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 `<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

```bash
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 SurrealDB Agent Memory the sole memory provider.