npm package: @locusgraph/openclaw-plugin
Description: LocusGraph memory plugin for OpenClaw — graph-backed memory with semantic search and insights
Author: locusgraph
Latest version: 0.1.2

# @locusgraph/openclaw-plugin

LocusGraph memory plugin for [OpenClaw](https://openclaw.ai) — replaces the built-in memory system with LocusGraph's semantic knowledge graph.

## Install

```bash
openclaw plugins install @locusgraph/openclaw-plugin
```

## Configure

Set the memory slot and plugin config in your OpenClaw config:

```json
{
  "plugins": {
    "slots": {
      "memory": "memory-locusgraph"
    },
    "entries": {
      "memory-locusgraph": {
        "enabled": true,
        "config": {
          "agentSecret": "${LOCUSGRAPH_AGENT_SECRET}",
          "graphId": "my-graph",
          "autoRecall": true,
          "autoCapture": true,
          "recallLimit": 5
        }
      }
    }
  }
}
```

Restart the gateway:

```bash
openclaw gateway restart
```

## Agent Tools

The plugin exposes 4 tools to the agent:

| Tool | Description |
|------|-------------|
| `locusgraph_store_event` | Store a memory (fact, action, decision, observation, feedback) |
| `locusgraph_retrieve_memories` | Semantic search over stored memories |
| `locusgraph_list_contexts` | Browse context types and names for filtering |
| `locusgraph_generate_insights` | Reason over memories to produce insights |

## Lifecycle Hooks

- **Auto-Recall** (`autoRecall: true`) — injects relevant memories into agent context before each turn
- **Auto-Capture** (`autoCapture: true`) — stores important agent responses as observations after each turn

## CLI

```bash
openclaw locusgraph search "what do I know about auth?"
openclaw locusgraph store "The API uses JWT tokens for authentication"
openclaw locusgraph contexts
openclaw locusgraph insights "What patterns exist in our error handling?"
```

## Config Reference

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `serverUrl` | string | no | `https://api.locusgraph.com` | LocusGraph API endpoint |
| `agentSecret` | string | **yes** | — | Agent authentication secret |
| `graphId` | string | **yes** | — | Graph ID for all memory operations |
| `autoRecall` | boolean | no | `false` | Inject relevant memories before each turn |
| `autoCapture` | boolean | no | `false` | Store key facts from conversations |
| `recallLimit` | number | no | `5` | Max memories to inject during auto-recall |

## Environment Variables

The plugin also respects:

- `LOCUSGRAPH_SERVER_URL` — API base URL (overridden by config `serverUrl`)
- `LOCUSGRAPH_AGENT_SECRET` — Agent secret (use `${LOCUSGRAPH_AGENT_SECRET}` in config)

## Deploy with Vercel Sandbox

Run OpenClaw + LocusGraph in an isolated [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) MicroVM.

### Prerequisites

- Vercel account with Sandbox access
- [Sandbox CLI](https://vercel.com/docs/vercel-sandbox/cli-reference) installed (`npm i -g sandbox && sandbox login`)
- An LLM API key (Anthropic, OpenAI, or Vercel AI Gateway)
- A LocusGraph agent secret

### 1. Create the sandbox

```bash
sandbox create \
  --timeout 30m \
  --publish-port 18789 \
  --connect
```

Save the sandbox ID:

```bash
export SANDBOX_ID=sbx_xxxxxxxx
```

### 2. Install OpenClaw + LocusGraph plugin

Inside the sandbox shell:

```bash
npm install -g openclaw
openclaw onboard
openclaw plugins install @locusgraph/openclaw-plugin
```

### 3. Configure the plugin

```bash
# Set LocusGraph as the memory backend
openclaw config set plugins.slots.memory memory-locusgraph

# Configure credentials
export LOCUSGRAPH_AGENT_SECRET="your-secret-here"
openclaw config set plugins.entries.memory-locusgraph.enabled true
openclaw config set plugins.entries.memory-locusgraph.config.agentSecret "$LOCUSGRAPH_AGENT_SECRET"
openclaw config set plugins.entries.memory-locusgraph.config.graphId "default"
openclaw config set plugins.entries.memory-locusgraph.config.autoRecall true
openclaw config set plugins.entries.memory-locusgraph.config.autoCapture true
```

### 4. Start the gateway

```bash
nohup openclaw gateway run > /tmp/gateway.log 2>&1 &
```

The dashboard is available at the public URL printed during sandbox creation (`https://sb-*-18789.vercel.run`). Append the auth token from onboarding output.

### 5. Lock down egress (recommended)

From your **local** terminal, restrict outbound traffic to only the services OpenClaw needs:

```bash
sandbox config network-policy $SANDBOX_ID \
  --network-policy restricted \
  --allowed-domain api.locusgraph.com \
  --allowed-domain api.anthropic.com \
  --allowed-domain web.whatsapp.com \
  --allowed-domain mmg.whatsapp.net
```

Adjust `--allowed-domain` based on your LLM provider:

| Provider | Domain |
|----------|--------|
| Vercel AI Gateway | `ai-gateway.vercel.sh` |
| Anthropic | `api.anthropic.com` |
| OpenAI | `api.openai.com` |
| LocusGraph | `api.locusgraph.com` |

### 6. Snapshot for faster restarts

```bash
# Create a snapshot (stops the sandbox)
sandbox snapshot $SANDBOX_ID --stop

# Next time, boot from snapshot with egress locked down
sandbox create \
  --snapshot snap_xxxxxxxx \
  --timeout 1h \
  --publish-port 18789 \
  --network-policy restricted \
  --allowed-domain api.locusgraph.com \
  --allowed-domain api.anthropic.com
```

### Reconnecting

```bash
sandbox connect $SANDBOX_ID
```

## Development

```bash
cd openclaw
pnpm install
pnpm run build

# Link for local dev
openclaw plugins install -l .
```

## License

MIT