♎ LibraVDB - Memory and Context Management

@xdarkicex/openclaw-memory-libravdb is a local-first OpenClaw memory plugin backed by the libravdbd daemon. It replaces the lightweight default memory path with scoped session, user, and global memory; continuity-aware prompt assembly; durable recall; and sidecar-owned compaction.

Install · Full installation reference · Architecture · Security · Performance and tuning · Contributing

New install? Start here: Install guide. Preferred setup on macOS: install libravdbd with Homebrew, install the OpenClaw plugin, then assign the plugin to both required slots.

Install

brew tap xDarkicex/homebrew-openclaw-libravdb-memory
brew install libravdbd
brew services start libravdbd
openclaw plugins install @xdarkicex/openclaw-memory-libravdb

Then activate both plugin slots in ~/.openclaw/openclaw.json:

{
  "plugins": {
    "slots": {
      "memory": "libravdb-memory",
      "contextEngine": "libravdb-memory"
    },
    "configs": {
      "libravdb-memory": {
        "sidecarPath": "auto"
      }
    }
  }
}

Verify the daemon and plugin:

Healthy output should show Sidecar=running, stored memory counts, the active gate threshold, and the loaded embedding profile.

Quick Start

Runtime requirements:

• OpenClaw >= 2026.3.22
• Node.js >= 22
• a separately installed libravdbd daemon

Compatibility note:

• this plugin is currently verified against OpenClaw 2026.4.23

Default endpoints:

• macOS/Linux user-local daemon: unix:$HOME/.clawdb/run/libravdb.sock
• Homebrew daemon on Apple Silicon: unix:/opt/homebrew/var/clawdb/run/libravdb.sock
• Windows daemon: tcp:127.0.0.1:37421

If your daemon runs elsewhere, set sidecarPath:

{
  "plugins": {
    "configs": {
      "libravdb-memory": {
        "sidecarPath": "tcp:127.0.0.1:37421"
      }
    }
  }
}

Highlights

• Dual slot ownership - owns both OpenClaw memory and contextEngine.
• Memory runtime bridge - routes built-in memory_search calls to the same libraVDB-backed sidecar on hosts that expose the runtime API.
• Three memory scopes - keeps active session, durable user, and global memory separate.
• Hybrid retrieval - blends semantic similarity, scope, recency, and summary quality instead of relying on cosine similarity alone.
• Continuity-aware assembly - preserves the recent working tail while fitting recalled memory into a bounded prompt budget.
• Sidecar compaction - summarizes older session turns without flattening the newest working context.
• Local-first inference - uses local embedding and compaction paths by default, with optional external summarizer configuration.
• Explicit daemon lifecycle - the npm/OpenClaw package stays connect-only; libravdbd is installed and supervised separately.

Security Defaults

Stored memory is treated as untrusted historical context. Retrieved memory is framed before it reaches the downstream model, memory collections are scoped by session/user/global namespace, and daemon installation is outside the npm plugin package.

Before exposing OpenClaw over remote channels, read Security.

Operator Quick Refs

openclaw memory status
openclaw memory index --force
openclaw memory search "prior context"
openclaw memory export --user-id <userId>
openclaw memory flush --user-id <userId>
openclaw memory journal --limit 50
openclaw memory dream-promote --user-id <userId> --dream-file /path/to/DREAMS.md

Use Install for daemon lifecycle commands and Uninstall for safe shutdown and removal.

Optional Features

• Markdown ingestion watches OpenClaw-owned markdown roots or Obsidian vaults and syncs eligible notes into memory. See Features.
• Dream promotion promotes vetted dream diary bullets into an isolated dream:{userId} collection. See Features.
• Embedding profiles expose local model metadata defaults for MiniLM and Nomic. See Embedding profiles.

Docs By Goal

• New install: Install, Installation reference
• Understand the design: Problem, Architecture, ADRs
• Operate safely: Security, Uninstall
• Configure optional inputs: Features, Embedding profiles, Models
• Advanced operations: Performance and tuning
• Work from source: Development, Contributing

From Source

pnpm install
pnpm check
bash scripts/build-daemon.sh

scripts/build-daemon.sh prepares .daemon-bin/libravdbd for local plugin testing when you have a published daemon binary, a Homebrew daemon, or a local daemon checkout. For the full source workflow, read Development.

Runtime Facts

• npm package: @xdarkicex/openclaw-memory-libravdb
• OpenClaw plugin id: libravdb-memory
• plugin kind: memory, context-engine
• minimum OpenClaw host version: >= 2026.3.22
• default data path: $HOME/.clawdb/data.libravdb
• default macOS/Linux endpoint: unix:$HOME/.clawdb/run/libravdb.sock
• default Windows endpoint: tcp:127.0.0.1:37421