memory-vastbase

VastBase-backed long-term memory plugin for OpenClaw with vector + full-text hybrid search.

Overview

memory-vastbase replaces the default SQLite-based memory storage with VastBase (an openGauss-based database), using its native floatvector + graph_index vector engine and fulltext index for BM25 keyword search, with Reciprocal Rank Fusion (RRF) or linear weighted fusion for hybrid retrieval.

Features

• Vector Search — semantic search via embedding vectors stored in floatvector columns with graph_index
• Full-Text Search — keyword search via fulltext index with Chinese tokenizer support
• Hybrid Search — configurable RRF or linear fusion combining vector + text scores
• Auto-Capture — automatically extracts and stores important facts from conversations
• Auto-Recall — injects relevant memories into prompt context before each agent turn
• Memory Tools — memory_recall, memory_store, memory_forget for manual memory management
• CLI — openclaw vbm commands for stats, search, and diagnostics

Requirements

• VastBase server (openGauss-based, PostgreSQL wire-protocol compatible)
• Embedding provider — any OpenAI-compatible embeddings API (OpenAI, SiliconFlow, ZhipuAI, etc.)

Quick Start

1. Create the database

Connect to your VastBase server and create a database:

CREATE DATABASE openclaw_memory;

The plugin creates all required tables and indexes automatically on first startup.

2. Configure the plugin

Add to your ~/.openclaw/openclaw.json:

{
  "plugins": {
    "slots": {
      "memory": "memory-vastbase"
    },
    "entries": {
      "memory-vastbase": {
        "enabled": true,
        "config": {
          "connection": {
            "host": "localhost",
            "port": 5432,
            "database": "openclaw_memory",
            "user": "openclaw",
            "password": "your-password"
          },
          "embedding": {
            "apiKey": "sk-your-embedding-api-key",
            "baseUrl": "https://api.openai.com/v1",
            "model": "text-embedding-3-small"
          },
          "autoCapture": true,
          "autoRecall": true
        }
      }
    }
  }
}

3. Restart

openclaw gateway restart

Configuration Reference

connection (required)

VastBase database connection parameters.

| Field | Type | Default | Description | |-------|------|---------|-------------| | host | string | localhost | VastBase server hostname | | port | number | 5432 | VastBase server port | | database | string | openclaw_memory | Database name | | user | string | openclaw | Database user | | password | string | required | Database password. Supports ${VASTBASE_PASSWORD} env var substitution | | ssl | boolean | false | Enable SSL connection | | maxPoolSize | number | 10 | Maximum connection pool size |

embedding (required)

Embedding API configuration for generating vector representations.

| Field | Type | Default | Description | |-------|------|---------|-------------| | apiKey | string | required | API key. Supports ${EMBEDDING_API_KEY} env var substitution | | baseUrl | string | https://api.openai.com/v1 | OpenAI-compatible API base URL | | model | string | text-embedding-3-small | Embedding model name | | dimensions | number | auto | Vector dimensions (auto-detected per model). Must match your model's output |

Embedding provider examples:

| Provider | baseUrl | Recommended Model | Dimensions | |----------|-----------|-------------------|------------| | OpenAI | https://api.openai.com/v1 | text-embedding-3-small | 1536 | | SiliconFlow | https://api.siliconflow.cn/v1 | BAAI/bge-m3 | 1024 | | ZhipuAI | https://open.bigmodel.cn/api/paas/v4 | embedding-3 | 2048 |

search (optional)

Hybrid search tuning.

| Field | Type | Default | Description | |-------|------|---------|-------------| | mode | "vector" | "keyword" | "hybrid" | hybrid | Default search mode | | vectorWeight | number | 0.7 | Vector score weight in linear fusion | | textWeight | number | 0.3 | Text score weight in linear fusion | | fusion | "linear" | "rrf" | linear | Fusion algorithm |

autoCapture & autoRecall

| Field | Type | Default | Description | |-------|------|---------|-------------| | autoCapture | boolean | false | Auto-store important facts after each conversation | | autoRecall | boolean | true | Auto-inject relevant memories into prompt context |

captureMaxChars (advanced)

| Field | Type | Default | Description | |-------|------|---------|-------------| | captureMaxChars | number | 2000 | Max message length eligible for auto-capture (100–10000) |

dreaming (advanced)

Opaque pass-through configuration for the dreaming subsystem. See Dreaming for details.

Environment variable substitution

Password and API key fields support ${ENV_VAR} syntax:

{
  "connection": {
    "password": "${VASTBASE_PASSWORD}"
  },
  "embedding": {
    "apiKey": "${EMBEDDING_API_KEY}"
  }
}

Proof of Concept (for Chinese users)

Working configuration using SiliconFlow + VastBase on WSL2:

{
  "plugins": {
    "slots": { "memory": "memory-vastbase" },
    "entries": {
      "memory-vastbase": {
        "enabled": true,
        "config": {
          "connection": {
            "host": "172.21.224.1",
            "port": 5434,
            "database": "openclaw_memory",
            "user": "vbadmin",
            "password": "Vbase@admin"
          },
          "embedding": {
            "apiKey": "sk-...",
            "baseUrl": "https://api.siliconflow.cn/v1",
            "model": "BAAI/bge-m3",
            "dimensions": 1024
          },
          "autoCapture": true,
          "autoRecall": true
        }
      }
    }
  }
}

CLI Reference

# Show memory statistics
openclaw vbm stats

# Search memories
openclaw vbm search "query keywords"

# List memory count
openclaw vbm list

Tools

The plugin registers three tools available to agents:

| Tool | Description | |------|-------------| | memory_recall | Semantic search through stored memories | | memory_store | Save new memory (auto-generates embedding, checks duplicates) | | memory_forget | Delete memories by ID or search query |

Architecture

• Self-contained — no modifications to OpenClaw core
• PostgreSQL wire-protocol — connects via pg (node-postgres)
• Lazy initialization — VastBase connection and schema are created on first use
• Per-agent isolation — each agent workspace gets its own schema via agent_registry
• Hooks — before_prompt_build for auto-recall, agent_end for auto-capture

Troubleshooting

"database does not exist"

The plugin requires the database to be pre-created on the VastBase server. Connect and run:

CREATE DATABASE openclaw_memory;

Then restart the gateway.

"recall returned no relevant memories"

• Ensure autoRecall is true in config
• Check that your embedding API is reachable and returning valid vectors
• Verify the VastBase floatvector extension is available
• Check openclaw vbm stats to confirm memories have been captured

Plugin not loading

Ensure plugins.slots.memory is set to "memory-vastbase" in your config. The slot must match the plugin ID exactly.