Documentation

LibraVDB Memory docs

Install the daemon, configure local or network transport, enable TLS or mTLS, connect agent hosts, and operate memory as infrastructure.

Quickstart

LibraVDB Memory is a daemon plus thin host integrations. Start local with Homebrew, verify daemon health, then point OpenClaw, Hermes, or MCP at the daemon endpoint.

brew tap xDarkicex/homebrew-openclaw-libravdb-memory
brew install libravdbd
brew services start libravdbd
libravdbd health

Default local transports use a Unix socket or loopback TCP. Remote TCP should use TLS, and mTLS is available when the daemon is configured with a client CA.

Install the daemon

The daemon release workflow publishes binaries and package metadata from the closed-source daemon repository. Homebrew and Chocolatey pull release assets from xDarkicex/homebrew-openclaw-libravdb-memory; Debian metadata is committed to xDarkicex/apt-libravdbd.

macOS or Linuxbrew

brew tap xDarkicex/homebrew-openclaw-libravdb-memory
brew install libravdbd
brew services start libravdbd
libravdbd health

Debian or Ubuntu

curl -fsSL https://xDarkicex.github.io/apt-libravdbd/gpg.key | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/libravdbd.gpg
echo "deb [arch=$(dpkg --print-architecture)] https://xDarkicex.github.io/apt-libravdbd stable main" | sudo tee /etc/apt/sources.list.d/libravdbd.list
sudo apt update
sudo apt install libravdbd
sudo /usr/lib/libravdbd/provision.sh --target /var/lib/libravdbd
systemctl --user enable --now libravdbd
libravdbd health

Arch Linux

yay -S libravdbd-bin
sudo /usr/lib/libravdbd/provision.sh --target /var/lib/libravdbd
systemctl --user enable --now libravdbd

Windows

choco install libravdbd
libravdbd health

Package sources

Release assetshomebrew-openclaw-libravdb-memory releases contain daemon binaries, checksums, and provision.sh.

HomebrewxDarkicex/homebrew-openclaw-libravdb-memory is the tap repository.

aptxDarkicex/apt-libravdbd stores the signed apt repository, gpg.key, dists/stable, and release .deb artifacts.

AURxDarkicex/aur-libravdbd-bin receives generated PKGBUILD updates from daemon releases.

ChocolateyThe daemon workflow builds a libravdbd.nupkg and pushes it to Chocolatey using the packaged Windows binary.

Daemon configuration

Configuration can come from YAML or environment variables. Set LIBRAVDB_CONFIG to point at a YAML file; environment variables override YAML values. The OpenClaw plugin repo includes premade daemon YAML examples because the daemon source is closed.

GGUF YAMLdocs/yaml/default-gguf.yaml is the recommended CPU-oriented baseline.

ONNX YAMLdocs/yaml/default-onnx.yaml covers ONNX Runtime, GPU/NPU provider selection, and model paths.

sudo install -d -m 0755 /etc/libravdbd
sudo curl -fsSL https://raw.githubusercontent.com/xDarkicex/openclaw-memory-libravdb/main/docs/yaml/default-gguf.yaml -o /etc/libravdbd/config.yaml
LIBRAVDB_CONFIG=/etc/libravdbd/config.yaml libravdbd health

LIBRAVDB_DB_PATHSingle-tenant database path. Leave empty when using LIBRAVDB_AGENT_DB_ROOT.

LIBRAVDB_CONFIGPath to daemon YAML. Example: /etc/libravdbd/config.yaml.

LIBRAVDB_EMBEDDING_BACKENDbundled, gguf, onnx-local, or remote. Remote is operator configured only.

LIBRAVDB_EMBEDDING_PROFILEDefault nomic-embed-text-v1.5; fallback profile defaults to bge-small-en-v1.5.

LIBRAVDB_ONNX_DEVICEauto, cpu, cuda, coreml, openvino, or directml.

LIBRAVDB_LLAMA_LIBPath to libllama.dylib or libllama.so when using GGUF outside packaged defaults.

LIBRAVDB_AUTH_SECRET_FILEPath to shared HMAC auth secret. Empty disables auth and should be limited to development/local-only setups.

LIBRAVDB_AGENT_DB_ROOTRoot directory for per-tenant databases. Mutually exclusive with LIBRAVDB_DB_PATH.

LIBRAVDB_TENANT_MODEauto creates tenant DBs from tenant keys; strict requires YAML tenant allowlist entries.

LIBRAVDB_DRAIN_TIMEOUTGraceful gRPC shutdown window. Default 25s; keep below Kubernetes terminationGracePeriodSeconds.

Daemon configuration reference

This is the operator-facing daemon surface from libravdbd/config/config.go. YAML keys are snake_case; environment variables override YAML.

Storage and tenancy

db_pathLIBRAVDB_DB_PATH. Single-tenant DB path. Default is profile-derived under ~/.libravdbd.

agent_db_rootLIBRAVDB_AGENT_DB_ROOT. Root for per-tenant DBs. Mutually exclusive with db_path.

tenant_modeLIBRAVDB_TENANT_MODE. auto accepts new tenant keys; strict requires YAML tenant allowlist.

tenant_max_openLIBRAVDB_TENANT_MAX_OPEN. Concurrent open tenant DB cap. Default 64.

tenantsYAML-only strict-mode tenant map. Each tenant can define a db_path.

force_db_openLIBRAVDB_FORCE_DB_OPEN. Recovery-only bypass for DB format fingerprint mismatch.

Embedding and local inference

embedding_backendLIBRAVDB_EMBEDDING_BACKEND. bundled, gguf, onnx-local, or remote.

embedding_profileLIBRAVDB_EMBEDDING_PROFILE. Default nomic-embed-text-v1.5.

fallback_profileLIBRAVDB_FALLBACK_PROFILE. Default bge-small-en-v1.5.

embedding_model_pathLIBRAVDB_EMBEDDING_MODEL. Local model directory/path override.

embedding_tokenizer_pathLIBRAVDB_EMBEDDING_TOKENIZER. Tokenizer JSON override.

embedding_dimensionsLIBRAVDB_EMBEDDING_DIMENSIONS. Vector dimension override.

embedding_normalizeLIBRAVDB_EMBEDDING_NORMALIZE. L2 normalization toggle. Default true.

embedding_mtiersLIBRAVDB_EMBEDDING_MTIERS. Comma-separated Matryoshka tiers, for example 64,256,768.

onnx_runtime_pathLIBRAVDB_ONNX_RUNTIME. Path to ONNX Runtime shared library.

onnx_deviceLIBRAVDB_ONNX_DEVICE. auto, cpu, cuda, coreml, openvino, or directml.

llama_lib_pathLIBRAVDB_LLAMA_LIB. Path to libllama used by GGUF deployments outside package defaults.

embed_timeoutLIBRAVDB_EMBED_TIMEOUT. Per-embedding call deadline. Default 5s.

Remote embedding and summarization

embedding_endpointLIBRAVDB_EMBEDDING_ENDPOINT. OpenAI-compatible remote embedding base URL. Only used with remote backend.

embedding_remote_modelLIBRAVDB_EMBEDDING_REMOTE_MODEL. Remote embedding model name.

embedding_api_keyLIBRAVDB_EMBEDDING_API_KEY. Bearer token for remote embedding. Operator supplied only.

embed_cache_sizeLIBRAVDB_EMBED_CACHE_SIZE. Remote embedding LRU cache size. 0 disables.

circuit_max_failuresLIBRAVDB_CIRCUIT_MAX_FAILURES. Remote embedder circuit breaker threshold. Default 3.

circuit_cooldownLIBRAVDB_CIRCUIT_COOLDOWN. Circuit breaker cooldown. Default 60s.

summarizer_backendLIBRAVDB_SUMMARIZER_BACKEND. Default bundled; remote summarization is not a hidden default.

summarizer_modelLIBRAVDB_SUMMARIZER_MODEL. Remote/custom summarizer model name.

summarizer_endpointLIBRAVDB_SUMMARIZER_ENDPOINT. Remote summarizer endpoint when explicitly configured.

Transport, auth, lifecycle

grpc_endpointLIBRAVDB_GRPC_ENDPOINT or legacy LIBRAVDB_RPC_ENDPOINT. Enables daemon gRPC transport.

grpc_tls_certLIBRAVDB_GRPC_TLS_CERT. Server certificate PEM.

grpc_tls_keyLIBRAVDB_GRPC_TLS_KEY. Server private key PEM.

grpc_tls_caLIBRAVDB_GRPC_TLS_CA. Client CA; enables mTLS client certificate verification.

auth_secret_fileLIBRAVDB_AUTH_SECRET_FILE. Shared secret for HMAC challenge-response auth.

drain_timeoutLIBRAVDB_DRAIN_TIMEOUT. Graceful shutdown drain. Default 25s.

pid_fileLIBRAVDB_PID_FILE. PID file path. Empty is container-safe default.

lifecycle_journal_max_entriesLIBRAVDB_LIFECYCLE_JOURNAL_MAX_ENTRIES. Default 500.

Gating weights

gating_thresholdLIBRAVDB_GATING_THRESHOLD. Minimum composite score for ingestion. Default 0.35.

gating_w1c / w2c / w3cLIBRAVDB_GATING_W1C, W2C, W3C. Conversational gating weights.

gating_w1t / w2t / w3tLIBRAVDB_GATING_W1T, W2T, W3T. Technical gating weights.

gating_tech_normLIBRAVDB_GATING_TECH_NORM. Technical gating normalization. Default 1.5.

Transport and TCP/IP

The daemon gRPC server is enabled by LIBRAVDB_GRPC_ENDPOINT. The older LIBRAVDB_RPC_ENDPOINT is accepted as an alias. Use Unix sockets for same-host agents, loopback TCP for local Windows/simple dev, and remote TCP with TLS for containers or networked agents.

Unix socketLIBRAVDB_GRPC_ENDPOINT=unix:$HOME/.libravdbd/run/libravdb.sock

Loopback TCPLIBRAVDB_GRPC_ENDPOINT=tcp:127.0.0.1:9090

Container/K8s TCPLIBRAVDB_GRPC_ENDPOINT=tcp:0.0.0.0:9090 inside the daemon container; clients use the Service DNS name.

OpenClaw localPlugin config sidecarPath: "auto" probes standard socket paths, or set grpcEndpoint explicitly.

Hermes localHermes accepts LIBRAVDB_GRPC_ENDPOINT or an endpoint in libravdb.json.

LIBRAVDB_GRPC_ENDPOINT=tcp:0.0.0.0:9090 \
LIBRAVDB_DB_PATH=/var/lib/libravdbd/data.libravdb \
LIBRAVDB_CONFIG=/etc/libravdbd/config.yaml \
libravdbd

TLS and mTLS

Daemon TLS is controlled server-side by certificate environment variables. Supplying a server cert/key enables TLS. Supplying a CA additionally requires and verifies client certificates, which is mTLS.

Server TLSLIBRAVDB_GRPC_TLS_CERT and LIBRAVDB_GRPC_TLS_KEY

mTLS client CALIBRAVDB_GRPC_TLS_CA makes the daemon require client certs signed by that CA.

OpenClaw CAgrpcEndpointTlsCa points the plugin at a private CA bundle.

OpenClaw client certgrpcEndpointTlsClientCert and grpcEndpointTlsClientKey enable mTLS client authentication.

OpenClaw modegrpcEndpointTlsMode: auto, tls, or insecure. Auto uses plaintext for Unix/loopback and TLS for remote TCP.

HermesHermes uses plaintext for Unix/loopback and TLS with system CAs for remote TCP. Custom CA and mTLS are not currently implemented in the Hermes plugin.

LIBRAVDB_GRPC_ENDPOINT=tcp:0.0.0.0:9090 \
LIBRAVDB_GRPC_TLS_CERT=/etc/libravdbd/tls/server.crt \
LIBRAVDB_GRPC_TLS_KEY=/etc/libravdbd/tls/server.key \
LIBRAVDB_GRPC_TLS_CA=/etc/libravdbd/tls/client-ca.crt \
libravdbd

{
"grpcEndpoint": "tcp:libravdb.internal:9090",
"grpcEndpointTlsCa": "/etc/certs/company-ca.pem",
"grpcEndpointTlsClientCert": "/etc/certs/openclaw-client.crt",
"grpcEndpointTlsClientKey": "/etc/certs/openclaw-client.key"
}

Containers and Kubernetes

There is no separate memory kernel inside the plugins. In containers or Kubernetes, run libravdbd as the daemon process with a persistent volume, then connect host plugins over the Service endpoint.

Container smoke test

docker build --platform linux/amd64 -f test/linux-apt-install.Dockerfile /path/to/libravdbd
docker build --platform linux/arm64 -f test/linux-apt-install.Dockerfile /path/to/libravdbd

Kubernetes shape

env:
- name: LIBRAVDB_GRPC_ENDPOINT
value: tcp:0.0.0.0:9090
- name: LIBRAVDB_CONFIG
value: /etc/libravdbd/config.yaml
- name: LIBRAVDB_AGENT_DB_ROOT
value: /var/lib/libravdbd/tenants
- name: LIBRAVDB_DRAIN_TIMEOUT
value: 25s
ports:
- name: grpc
containerPort: 9090
volumeMounts:
- name: data
mountPath: /var/lib/libravdbd
terminationGracePeriodSeconds: 30

For remote clients, terminate TLS at the daemon or mesh. If a mesh terminates TLS, set OpenClaw grpcEndpointTlsMode: "insecure" only for the inside-the-mesh plaintext hop.

Operate and upgrade

Use daemon health/status before debugging host plugins. After daemon upgrades, restart the service so the installed binary replaces the running process.

libravdbd health
libravdbd status
libravdbd search --tenant <tenant-key> -k 10 "prior context"
brew services restart libravdbd
systemctl --user restart libravdbd

ExportUse host CLI export commands before destructive cleanup or migration.

Forget/flushDeletion is operator controlled through daemon or host integration tools.

JournalLifecycle journal entries are bounded and useful for debugging host/daemon behavior.

HostedThe waitlist is for managed LibraVDB Memory. Hosted privacy, billing, and policy are separate from local daemon guarantees.

MCP server

mcp-memory-libravdb is the official MCP server for the libravdbd cognitive memory kernel. Give any MCP-compatible coding agent — Claude Code, Codex, Cursor, Cline, Zed, Aider — persistent semantic, causal-graph memory with zero configuration.

Install

macOSbrew install xDarkicex/homebrew-mcp-libravdb/mcp-memory-libravdb

Linuxsudo apt install mcp-memory-libravdb (APT repo at xDarkicex.github.io/apt-mcp-libravdb)

Gogo install github.com/xDarkicex/mcp-libravdb-server/cmd/mcp-memory-libravdb@latest

Dockerdocker pull ghcr.io/xdarkicex/mcp-memory-libravdb

Quickstart

libravdbd
mcp-memory-libravdb stdio
claude mcp add libravdb-memory -- mcp-memory-libravdb stdio

Start the daemon, start the MCP server, connect your client. Three steps. Works with any MCP-compatible client — Claude Code, Codex, Cursor, Cline, Zed, or Aider.

Configuration

--backend-addrgRPC backend address. Default: unix://~/.libravdbd/run/libravdb.sock

--tenant-keyTenant key for data isolation. Default: libravdb-mcp-server

--sharedDisable per-workspace isolation. All projects share one tenant.

--workspaceExplicit workspace name. Default: auto-derived from CWD hash.

--degraded-okStart even if daemon is unavailable. Default: false.

--log-leveldebug, info, warn, error. Default: info.

--auth-tokenBearer token for HTTP auth (Streamable HTTP mode).

--http-portHTTP server port (Streamable HTTP mode). Default: 8082.

All flags map to environment variables with LIBRAVDB_ prefix.

CLI reference

stdioStart MCP server over stdio (recommended for local use).

httpStart MCP server over Streamable HTTP (remote / multi-process).

statusDaemon health, tenant list, and MCP server process info. -v for verbose, --json for machine-readable.

workspacesFocused tenant list.

tenant listAll open tenants.

tenant inspect <k>Tenant details for key k.

tenant evict <k>Unload tenant by key.

MCP tools

memory.searchSemantic search across all collections with keyword, temporal, and kind filters.

memory.addInsert a memory record with optional kind classification and metadata.

memory.recallSearch with deontic gating enrichment — results scored through obligation, prohibition, and permission filters.

memory.graphWalk the causal graph from any record — traverse why-edges, how-edges, and associative links.

memory.predictPredict next relevant memories from causal proximity and temporal recency.

memory.statsNode counts, cognitive kind breakdowns, tier distributions, daemon health.

memory.deleteDelete a memory by ID with tenant-scoped authorization.

Client setup

Claude Codeclaude mcp add libravdb-memory -- mcp-memory-libravdb stdio

Claude DesktopAdd to .mcp.json or Desktop config — same command, same transport.

CodexConfigure in ~/.codex/config.toml under [mcp_servers].

CursorDrop config in ~/.cursor/mcp.json — picked up on next launch.

ClineSettings → MCP Servers → add stdio: mcp-memory-libravdb stdio.

ZedAdd to ~/.config/zed/settings.json under context_servers.

AiderConfigure via .aider.conf.yml or --mcp-server flag.

Architecture

The daemon does the intelligence — cognitive classification across six kinds, deontic two-pass gating, causal graph traversal, and workspace IAM. This server translates MCP tool calls into gRPC requests over a Unix socket with HMAC authentication and per-tenant isolation. One protocol translation layer. Zero memory intelligence reimplemented in the client.

Claude / Codex / Cursor / Cline / Zed / Aider MCP stdio or Streamable HTTP mcp-memory-libravdb gRPC + HMAC auth libravdbd cognitive kernel

Agent host integrations

OpenClaw

openclaw plugins install @xdarkicex/openclaw-memory-libravdb
openclaw daemon restart
openclaw memory status

Requires OpenClaw >= 2026.3.22, Node.js >= 22, and a separately installed daemon. OpenClaw supports explicit CA, TLS mode, and mTLS client certificate configuration.

Hermes

pip install hermes-memory-libravdb
hermes-memory-libravdb-setup install
hermes memory setup
hermes libravdb status

Requires Hermes Agent >= 0.14, Python >= 3.9, and a separately installed daemon. Set memory.provider: "libravdb" to activate. Hermes source supports endpoint override, HMAC auth, TLS mode, custom CA, and mTLS client certificate fields.

OpenClaw plugin configuration

OpenClaw has the broadest plugin-side configuration surface. These keys live in the OpenClaw plugin config and are passed through to daemon transport or host-side memory behavior.

Connection and security

sidecarPathLegacy endpoint alias. auto probes standard sockets; may be unix:/path or tcp:host:port.

grpcEndpointPreferred daemon endpoint override.

grpcEndpointTlsModeauto, tls, or insecure.

grpcEndpointTlsCaPrivate/self-signed CA PEM for server verification.

grpcEndpointTlsClientCertClient certificate PEM for mTLS.

grpcEndpointTlsClientKeyClient private key PEM for mTLS. Must be paired with client cert.

rpcTimeoutMsPer-call daemon RPC timeout. Default 30000.

dbPathExplicit daemon DB path override for local sidecar-style deployments.

Identity and scope

tenantIdStable tenant identifier for isolated per-agent daemon storage.

userIdStable durable memory identity. Empty auto-derives from OS/user state.

identityPathCustom path for persisted auto-derived identity JSON.

crossSessionRecallWhen false, disables user-scoped durable recall and uses session memory only.

useSessionRecallProjectionUse session recall projection collection.

useSessionSummarySearchExperimentUse session summaries as a search source.

Retrieval, compaction, and context

topKMax results per search.

alpha / beta / gammaSemantic, recency, and summary-quality scoring weights.

ingestionGateThresholdHost-side minimum semantic relevance score. Default 0.35.

compactThresholdAbsolute token threshold for forced compaction.

compactionThresholdFractionDynamic compaction threshold as active token budget fraction. Default 0.8.

compactSessionTokenBudgetAuto-compact token ceiling. Default 2000; 0 disables.

compactionQualityWeightHow strongly summary quality affects retrieval.

tokenBudgetFractionFraction of host token budget allocated to memory context.

authoredHardBudgetFractionBudget for hard-authored recall.

authoredSoftBudgetFractionBudget for soft-authored recall.

elevatedGuidanceBudgetFractionBudget for elevated guidance recall.

beforeTurnEnabledEnable before-turn retrieval. Default true.

beforeTurnTimeoutMsBefore-turn RPC timeout. Default 5000.

assembleTimeoutMsContext assembly RPC timeout. Default 30000.

beforeTurnMaxMemoriesMaximum injected memories per turn. Default 5.

beforeTurnMinScoreMinimum before-turn similarity score. Default 0.4.

Models and local runtimes

embeddingBackendbundled, gguf, onnx-local, custom-local, or remote.

embeddingProfilePrimary embedding profile.

fallbackProfileFallback embedding profile.

embeddingRuntimePathDaemon-visible ONNX Runtime library path.

embeddingModelPathDaemon-visible embedding model path.

embeddingTokenizerPathTokenizer path override.

embeddingDimensionsEmbedding dimension override.

embeddingNormalizeEmbedding normalization toggle.

onnxDeviceauto, cpu, cuda, coreml, directml, or openvino.

embeddingEndpointRemote embedder endpoint when explicitly configured.

embeddingRemoteModelRemote embedding model id.

embeddingAPIKeyRemote embedding API key. Operator supplied only.

summarizerBackendbundled, onnx-local, ollama-local, or custom-local.

summarizerEndpointExternal summarizer URL when configured.

ollamaUrl / compactModelOllama and compaction model shortcuts.

Markdown, Obsidian, dream diary

markdownIngestionEnabledEnable generic markdown ingestion.

markdownIngestionRootsGeneric markdown roots to watch.

markdownIngestionInclude / ExcludeInclude/exclude globs. Defaults exclude dependency/build directories.

markdownIngestionDebounceMsGeneric markdown debounce. Default 150.

markdownIngestionPriorityModemtime, ctime, size, or fifo.

markdownIngestionMaxTokensPerFilePer-file token cap.

markdownIngestionSnapshotPathSnapshot path for generic markdown ingestion state.

markdownIngestionObsidianEnabledEnable Obsidian vault ingestion.

markdownIngestionObsidianRootsObsidian vault roots.

markdownIngestionObsidianSnapshotPathSnapshot path for Obsidian ingestion state.

dreamPromotionEnabledEnable dream diary promotion.

dreamPromotionDiaryPathPath to dream diary markdown file.

dreamPromotionUserIdUser scope for dream diary promotion.

dreamPromotionDebounceMsDream diary debounce. Default 150.

Advanced scoring and recovery

section7*section7Theta1, Kappa, HopEta, HopThreshold, coarse/second-pass top-K, authority weights, and recency access lambda.

continuity*continuityMinTurns, prior-context token budget, and tail budget.

recovery*recoveryFloorScore, recoveryMinTopK, and recoveryMinConfidenceMean.

recencyLambda*Session, user, and global recency decay factors.

sessionTTLSession retention TTL in seconds.

subagentTokenBudgetCap for subagent memory_expand calls. Default 8000; 0 disables.

optimizationMemoCacheSizeContext-engine string memoization cache size. Default 1000.

logLeveldebug, info, warn, or error.

Hermes plugin configuration

Hermes stores provider settings in $HERMES_HOME/libravdb.json. Environment variables override file values. Current source supports TLS and mTLS transport fields even where older Hermes docs still describe them as future work.

endpointConfig key for daemon endpoint. auto, unix:/path/to/socket, or tcp:host:port.

grpcEndpointAccepted alias used by the shared transport resolver.

LIBRAVDB_GRPC_ENDPOINTEnvironment override for endpoint.

userIdStable durable memory identity. Empty auto-derives identity from OS username and hostname.

topKDefault recalled memory hit count. Default 8.

minScoreMinimum semantic score threshold. Default 0.35.

ingestionGateThresholdFallback threshold used by CLI/provider score resolution when daemon value is unavailable.

rpcTimeoutMsDaemon RPC timeout. Default 30000.

summarizerEndpointProvider stores and reports summarizer endpoint when configured.

markdownIngestionEnabledCLI checks this before markdown ingestion commands.

Hermes auth and TLS

LIBRAVDB_AUTH_SECRETDirect HMAC secret. Runtime only; not written to libravdb.json.

LIBRAVDB_AUTH_SECRET_FILEPath to HMAC secret file.

grpcEndpointTlsModeauto, tls, or insecure. Auto uses plaintext for Unix/loopback and TLS for remote TCP.

grpcEndpointTlsCaPrivate/self-signed CA PEM for server verification.

grpcEndpointTlsClientCertClient certificate PEM for mTLS.

grpcEndpointTlsClientKeyClient private key PEM for mTLS. Must be paired with client cert.

HERMES_HOMEConfig root. Default ~/.hermes.

hermes memory setup
export LIBRAVDB_GRPC_ENDPOINT="tcp:libravdb.internal:9090"
export LIBRAVDB_AUTH_SECRET_FILE="/etc/libravdbd/client.secret"
hermes libravdb status

libraVDB database engine

libraVDB is the public Go database library underneath LibraVDB Memory storage paths. The daemon adds memory semantics, compaction, recall policy, transport, auth, and host integration; libraVDB provides the embedded vector-graph database substrate: single-file durability, vector search, metadata filters, graph hooks, transactions, batch ingestion, and operational health.

Repositorygithub.com/xDarkicex/libraVDB

Go packagegithub.com/xDarkicex/libravdb/libravdb

Installgo get github.com/xDarkicex/libravdb. Requires Go 1.25+; no CGo or external system runtime is required by the library quickstart.

Local source~/Development/golang/src/github.com/xDarkicex/libraVDB

Role herePersistent vector, metadata, and graph storage used by the daemon; not a hosted dependency and not a separate cloud service.

Database capabilities

Hybrid vector-graph

Vector similarity search plus directed typed edges, graph traversal, reverse lookups, and graph-filtered search.

Index choices

HNSW, IVF-PQ, and Flat indexes. Auto selection defaults toward Flat for small exact sets, HNSW for general ANN, and IVF-PQ for very large memory-efficient collections.

Single-file persistence

Databases persist as portable *.libravdb files with a page-based single-file LSM engine, transaction-bracketed WAL, dual metapages, and copy-on-write checkpointing.

Metadata filtering

Query builder supports vector search with typed metadata filters such as equality, ranges, containment, and boolean composition.

Memory efficiency

Product/scalar quantization, memory mapping, cache policy hooks, and off-heap hot paths reduce process pressure.

Streaming and batch writes

Batch insert, streaming ingestion, backpressure, bounded write admission, and context-aware cancellation are part of the public API surface.

Public API shape

Openlibravdb.Open(libravdb.WithStoragePath("./memory.libravdb")), with options for metrics, logging, memory limits, and bounded write admission.

CollectionsCreateCollection, GetCollection, ListCollections, DeleteCollection, and context-aware lifecycle methods.

Collection optionsWithDimension, WithMetric, WithHNSW, WithFlat, WithIVFPQ, WithAutoIndexSelection, WithSharding, WithMemoryLimit, WithMemoryMapping.

QuantizationWithProductQuantization, WithScalarQuantization, and custom quantization configuration.

CRUD/searchInsert, Get, Update, Upsert, Delete, Search, Query, Iterate, ListByMetadata, Count.

HealthHealth(ctx), Stats(), Prometheus metrics, health checks, and circuit-breaker/degradation primitives expose runtime condition.

Transactions and consistency

Cross-collection txBeginTx(ctx) and WithTx(ctx, fn) stage mutations in memory, then atomically commit through the WAL.

CAS updatesUpdateIfVersion and DeleteIfVersion use record versions and return ErrVersionConflict / VersionConflictError on mismatch.

Commit pathCommit acquires touched collection locks, validates CAS preconditions, assigns ordinals, writes a storage transaction, updates indexes, and invokes post-commit hooks.

Graph hooksInsertHook and DeleteHook can update graph edges in the same transaction scope as vector mutations.

Concurrency and ingestion

Write admissionWithMaxConcurrentWrites bounds parallel writers; WithMaxWriteQueueDepth bounds queued writers and can return ErrWriteQueueFull.

Locking modelDatabase registry locks, per-collection locks, ID stripe locks, and optional sharded collections keep writes bounded while preserving concurrent reads where possible.

Batch operationsNewBatchInsert, NewBatchUpdate, and NewBatchDelete support chunking, bounded workers, retries, progress callbacks, fail-fast mode, and optional rollback.

StreamingNewStreamingBatchInsert, Send, SendBatch, Results, Errors, Stats, and Wait provide backpressure-aware ingestion for large datasets.

Hot pathsBatch and streaming paths use a scratch arena pool for temporary allocations; memory mapping and slab/vector-store options are available for large collections.

go get github.com/xDarkicex/libravdb

db, err := libravdb.Open(libravdb.WithStoragePath("./agent-memory.libravdb"), libravdb.WithMetrics(true), libravdb.WithMaxConcurrentWrites(8))
collection, err := db.CreateCollection(ctx, "memories", libravdb.WithDimension(768), libravdb.WithMetric(libravdb.CosineDistance), libravdb.WithAutoIndexSelection(true), libravdb.WithMetadataSchema(schema), libravdb.WithIndexedFields("scope", "kind"))
metadata := map[string]interface{}{"scope": "user", "kind": "decision"}
err = collection.Insert(ctx, "memory-1", embedding, metadata)
results, err := collection.Query(ctx).WithVector(query).Eq("scope", "user").Limit(10).Execute()

Read the upstream docs for direct database use: getting started, API reference, architecture, storage, transactions, concurrency, and batch operations.