{"id":47716182,"url":"https://github.com/xdarkicex/openclaw-memory-libravdb","last_synced_at":"2026-05-12T18:10:26.896Z","repository":{"id":347753040,"uuid":"1195159308","full_name":"xDarkicex/openclaw-memory-libravdb","owner":"xDarkicex","description":"Persistent local memory engine for OpenClaw — replaces default memory-system with a full context lifecycle: hybrid vector recall, automatic compaction, and domain-adaptive gating over LibraVDB","archived":false,"fork":false,"pushed_at":"2026-04-16T00:30:20.000Z","size":859,"stargazers_count":3,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-16T02:29:18.183Z","etag":null,"topics":["ai-memory","compaction","context-engine","golang","hybrid-search","libravdb","local-first","memory","nlp","onnx","openclaw","openclaw-plugin","slab-allocator","slabby","typescript","vector-database"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xDarkicex.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-29T10:01:37.000Z","updated_at":"2026-04-16T00:30:24.000Z","dependencies_parsed_at":null,"dependency_job_id":"e2a114bf-ed78-48f2-b309-ee8e45d2e335","html_url":"https://github.com/xDarkicex/openclaw-memory-libravdb","commit_stats":null,"previous_names":["xdarkicex/openclaw-memory-libravdb"],"tags_count":33,"template":false,"template_full_name":null,"purl":"pkg:github/xDarkicex/openclaw-memory-libravdb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xDarkicex%2Fopenclaw-memory-libravdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xDarkicex%2Fopenclaw-memory-libravdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xDarkicex%2Fopenclaw-memory-libravdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xDarkicex%2Fopenclaw-memory-libravdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xDarkicex","download_url":"https://codeload.github.com/xDarkicex/openclaw-memory-libravdb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xDarkicex%2Fopenclaw-memory-libravdb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32154688,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T17:06:48.269Z","status":"ssl_error","status_checked_at":"2026-04-22T17:06:19.037Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-memory","compaction","context-engine","golang","hybrid-search","libravdb","local-first","memory","nlp","onnx","openclaw","openclaw-plugin","slab-allocator","slabby","typescript","vector-database"],"created_at":"2026-04-02T18:58:18.822Z","updated_at":"2026-05-12T18:10:26.884Z","avatar_url":"https://github.com/xDarkicex.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ♎ LibraVDB - Memory and Context Management\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"./docs/assets/libravdb-logo.svg\" alt=\"LibraVDB\" width=\"640\"\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/xDarkicex/libravdbd\"\u003e\u003cimg src=\"https://img.shields.io/badge/Go-1.25%2B-00ADD8?logo=go\u0026logoColor=white\" alt=\"Go 1.25+\"\u003e\u003c/a\u003e\n  \u003ca href=\"./package.json\"\u003e\u003cimg src=\"https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript\u0026logoColor=white\" alt=\"TypeScript 5.x\"\u003e\u003c/a\u003e\n  \u003ca href=\"./openclaw.plugin.json\"\u003e\u003cimg src=\"https://img.shields.io/badge/OpenClaw-memory%20plugin-111827\" alt=\"OpenClaw memory plugin\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@xdarkicex/openclaw-memory-libravdb\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/%40xdarkicex%2Fopenclaw-memory-libravdb?label=release\u0026color=5B21B6\" alt=\"Release\"\u003e\u003c/a\u003e\n\u003c/div\u003e\n\n`@xdarkicex/openclaw-memory-libravdb` is a local-first OpenClaw memory plugin\nbacked by the `libravdbd` vector service. It replaces the lightweight default memory\npath with scoped session, user, and global memory; continuity-aware prompt\nassembly; durable recall; and sidecar-owned compaction.\n\n[Install](./docs/install.md) · [Full installation reference](./docs/installation.md) · [Architecture](./docs/architecture.md) · [Security](./docs/security.md) · [Performance and tuning](./docs/performance-and-tuning.md) · [Contributing](./docs/contributing.md)\n\nNew install? Start here: [Install guide](./docs/install.md).\n\n## Install\n\nInstall `libravdbd` with your system package manager, then install\nthe OpenClaw plugin.\n\n**macOS (Homebrew)**\n\n```bash\nbrew tap xDarkicex/homebrew-openclaw-libravdb-memory\nbrew install libravdbd\nbrew services start libravdbd\n```\n\n**Linux (APT)**\n\n```bash\nsudo apt install libravdbd\nsystemctl --user enable --now libravdbd\n```\n\n**Linux (AUR)**\n\n```bash\nyay -S libravdbd-bin\nsystemctl --user enable --now libravdbd\n```\n\n**Plugin (all platforms)**\n\n```bash\nopenclaw plugins install @xdarkicex/openclaw-memory-libravdb\n```\n\nThen activate the plugin in `~/.openclaw/openclaw.json`:\n\n```json\n{\n  \"plugins\": {\n    \"slots\": {\n      \"memory\": \"libravdb-memory\"\n    },\n    \"entries\": {\n      \"libravdb-memory\": {\n        \"enabled\": true,\n        \"config\": {\n          \"sidecarPath\": \"auto\"\n        }\n      }\n    }\n  }\n}\n```\n\nVerify the service and plugin:\n\n```bash\nopenclaw memory status\n```\n\nHealthy output should show `Sidecar=running`, stored memory counts, the active\ngate threshold, and the loaded embedding profile.\n\n## Quick Start\n\nRuntime requirements:\n\n- OpenClaw `\u003e= 2026.3.22`\n- Node.js `\u003e= 22`\n- a separately installed `libravdbd` service\n\nCompatibility note:\n\n- this plugin is currently verified against OpenClaw `2026.4.23`\n\nDefault endpoints:\n\n- macOS/Linux user-local service: `unix:$HOME/.libravdbd/run/libravdb.sock`\n- Homebrew service on Apple Silicon: `unix:/opt/homebrew/var/libravdbd/run/libravdb.sock`\n- Windows service: `tcp:127.0.0.1:37421`\n\nIf your service runs elsewhere, set `sidecarPath`:\n\n```json\n{\n  \"plugins\": {\n    \"entries\": {\n      \"libravdb-memory\": {\n        \"enabled\": true,\n        \"config\": {\n          \"sidecarPath\": \"tcp:127.0.0.1:37421\"\n        }\n      }\n    }\n  }\n}\n```\n\n## Highlights\n\n- **Memory capability ownership** - owns the OpenClaw `memory` slot and\n  registers the context engine capability at runtime.\n- **Memory runtime bridge** - routes built-in `memory_search` calls to the same\n  libraVDB-backed sidecar on hosts that expose the runtime API.\n- **Three memory scopes** - keeps active session, durable user, and global memory\n  separate.\n- **Hybrid retrieval** - blends semantic similarity, scope, recency, and summary\n  quality instead of relying on cosine similarity alone.\n- **Continuity-aware assembly** - preserves the recent working tail while fitting\n  recalled memory into a bounded prompt budget.\n- **Sidecar compaction** - summarizes older session turns without flattening the\n  newest working context.\n- **Local-first inference** - uses local embedding and compaction paths by\n  default, with optional external summarizer configuration.\n- **Explicit service lifecycle** - the npm/OpenClaw package stays connect-only;\n  `libravdbd` is installed and supervised separately.\n\n## Security Defaults\n\nStored memory is treated as untrusted historical context. Retrieved memory is\nframed before it reaches the downstream model, memory collections are scoped by\nsession/user/global namespace, and service installation is outside the npm plugin\npackage.\n\nBefore exposing OpenClaw over remote channels, read [Security](./docs/security.md).\n\n## Operator Quick Refs\n\n```bash\nopenclaw memory status [--deep] [--json]\nopenclaw memory index --force\nopenclaw memory search \"prior context\"\nopenclaw memory export --user-id \u003cuserId\u003e\nopenclaw memory flush --user-id \u003cuserId\u003e\nopenclaw memory journal --limit 50\nopenclaw memory dream-promote --user-id \u003cuserId\u003e --dream-file ~/DREAMS.md\n```\n\nUse [Install](./docs/install.md) for service lifecycle commands and\n[Uninstall](./docs/uninstall.md) for safe shutdown and removal.\n\n## Configuration\n\nAll keys are optional. For the full reference, see [Configuration](./docs/configuration.md).\n\n| Key | Type | Default | |\n|---|---|---|---|\n| `sidecarPath` | string | `auto` | `\"auto\"` probes standard paths; set `unix:/path` or `tcp:host:port` to override |\n| `embeddingProfile` | string | `nomic-embed-text-v1.5` | Primary embedding model |\n| `fallbackProfile` | string | `bge-small-en-v1.5` | Fallback profile for dimension mismatches |\n| `onnxDevice` | string | `auto` | ONNX execution provider; set `cpu` to bypass CoreML/MPS on Intel Macs |\n| `userId` | string | auto-derived | Stable identity for cross-session durable memory |\n| `crossSessionRecall` | boolean | `true` | When `false`, only session-scoped memories are retrieved |\n| `compactSessionTokenBudget` | number | `2000` | Auto-compaction token threshold; `0` disables |\n\n## Optional Features\n\n- **Markdown ingestion** watches OpenClaw-owned markdown roots or Obsidian vaults\n  and syncs eligible notes into memory. See [Features](./docs/features.md).\n- **Dream promotion** promotes vetted dream diary bullets into an isolated\n  `dream:{userId}` collection. See [Features](./docs/features.md).\n- **Embedding profiles** default to `nomic-embed-text-v1.5` with `bge-small-en-v1.5`\n  fallback. See [Embedding profiles](./docs/embedding-profiles.md).\n\n## Docs By Goal\n\n- New install: [Install](./docs/install.md), [Installation reference](./docs/installation.md)\n- Understand the design: [Problem](./docs/problem.md), [Architecture](./docs/architecture.md), [ADRs](./docs/architecture-decisions/README.md)\n- Configure: [Configuration](./docs/configuration.md), [Features](./docs/features.md), [Embedding profiles](./docs/embedding-profiles.md), [Models](./docs/models.md)\n- Operate safely: [Security](./docs/security.md), [Uninstall](./docs/uninstall.md)\n- Advanced operations: [Performance and tuning](./docs/performance-and-tuning.md)\n- Work from source: [Development](./docs/development.md), [Contributing](./docs/contributing.md)\n\n## From Source\n\n```bash\npnpm install\npnpm check\nbash scripts/build-daemon.sh\n```\n\n`scripts/build-daemon.sh` prepares `.daemon-bin/libravdbd` for local plugin\ntesting when you have a published service binary, a Homebrew service, or a local\nservice checkout. For the full source workflow, read [Development](./docs/development.md).\n\n## Runtime Facts\n\n- npm package: `@xdarkicex/openclaw-memory-libravdb`\n- OpenClaw plugin id: `libravdb-memory`\n- plugin kind: `memory`, `context-engine`\n- minimum OpenClaw host version: `\u003e= 2026.3.22`\n- default data path: `$HOME/.libravdbd/data_nomic-embed-text-v1_5.libravdb`\n- default macOS/Linux endpoint: `unix:$HOME/.libravdbd/run/libravdb.sock`\n- default Windows endpoint: `tcp:127.0.0.1:37421`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxdarkicex%2Fopenclaw-memory-libravdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxdarkicex%2Fopenclaw-memory-libravdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxdarkicex%2Fopenclaw-memory-libravdb/lists"}