@xdarkicex/openclaw-memory-libravdb 1.3.12 → 1.3.13

package/README.md

@@ -1,60 +1,27 @@
-# LibraVDB Memory
+# LibraVDB Memory for OpenClaw
 
-## Install
+[![Go](https://img.shields.io/badge/Go-1.25%2B-00ADD8?logo=go&logoColor=white)](./sidecar/go.mod)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)](./package.json)
+[![OpenClaw](https://img.shields.io/badge/OpenClaw-memory%20plugin-111827)](./openclaw.plugin.json)
 
-Recommended on macOS:
+Local-first memory for OpenClaw that pairs a TypeScript plugin with a Go
+daemon, keeps recent work intact, and promotes durable memory only when the
+signal is strong enough to matter.
 
-```bash
-brew tap xDarkicex/openclaw-libravdb-memory
-brew install libravdbd
-brew services start libravdbd
-openclaw plugins install @xdarkicex/openclaw-memory-libravdb
-```
-
-Then activate the plugin in `~/.openclaw/openclaw.json`.
-
-Manual plugin install:
-
-```bash
-openclaw plugins install @xdarkicex/openclaw-memory-libravdb
-```
-
-The published plugin is connect-only. It does not spawn a local binary during install or at runtime. For durable memory, run a local `libravdbd` daemon separately and point the plugin at its endpoint.
-
-Minimum host version:
-
-- OpenClaw `>= 2026.3.22`
-
-Security note:
-
-- the published plugin package contains no `postinstall`, no `openclaw.setup`, and no direct `child_process` usage
-- the plugin only connects to a local `libravdbd` endpoint such as `unix:/Users/<you>/.clawdb/run/libravdb.sock` or `tcp:127.0.0.1:37421`
-- after install, the plugin makes no required network calls for embedding or extractive compaction
-- the only optional runtime network path is an explicitly configured remote summarizer endpoint such as `ollama-local`
-
-## Daemon
+## Install and Lifecycle
 
-Install and start `libravdbd` separately, then point the plugin at the running daemon if you do not want the default endpoint.
+- [Install guide](./docs/install.md) for Homebrew, OpenClaw / OpenClaw.ai plugin setup, and manual daemon lifecycle.
+- [Uninstall guide](./docs/uninstall.md) for clean plugin removal, daemon shutdown, and optional data cleanup.
+- [Full installation reference](./docs/installation.md) for deeper operational detail, troubleshooting, and packaging notes.
 
-Default endpoints:
+Start with the [install guide](./docs/install.md) for the supported daemon
+setup paths and activation flow. The short version is:
 
-- macOS/Linux: `unix:$HOME/.clawdb/run/libravdb.sock`
-- Windows: `tcp:127.0.0.1:37421`
+- install the plugin with `openclaw plugins install @xdarkicex/openclaw-memory-libravdb`
+- install and start `libravdbd` separately
+- assign `libravdb-memory` to the OpenClaw `memory` slot
 
-Phase 2 packaging assets now live under [`packaging/`](./packaging):
-
-- `packaging/systemd/libravdbd.service` for Linux user services
-- `packaging/launchd/com.xdarkicex.libravdbd.plist` for macOS LaunchAgents
-- `packaging/homebrew/libravdbd.rb.tmpl` as the source template for a generated Homebrew formula
-
-Recommended service startup commands:
-
-- macOS: `brew services start libravdbd`
-- Linux: `systemctl --user enable --now libravdbd.service`
-
-## Activate
-
-Add this to `~/.openclaw/openclaw.json`:
+Then activate the plugin in `~/.openclaw/openclaw.json`:
 
 ```json
 {
@@ -64,14 +31,43 @@ Add this to `~/.openclaw/openclaw.json`:
     },
     "configs": {
       "libravdb-memory": {
-        "sidecarPath": "unix:/Users/<you>/.clawdb/run/libravdb.sock"
+        "sidecarPath": "auto"
       }
     }
   }
 }
 ```
 
-Without the `plugins.slots.memory` entry, OpenClaw's default memory continues to run in parallel and this plugin does not take over the exclusive memory slot.
+The published plugin is connect-only. It does not compile or spawn a local Go
+binary during install. The `libravdbd` daemon is managed separately and the
+plugin connects to an endpoint such as `unix:$HOME/.clawdb/run/libravdb.sock`
+or `tcp:127.0.0.1:37421`.
+
+Use `sidecarPath: "auto"` or omit the field to use the platform default
+endpoint. If your daemon listens elsewhere, set an explicit endpoint such as
+`unix:/custom/path/libravdb.sock` or `tcp:127.0.0.1:9999`.
+
+## How It Works
+
+- [Hybrid retrieval and prompt assembly](./docs/mathematics-v2.md): combines semantic similarity, recency, memory scope, and budget-aware packing so the prompt keeps the most useful memory instead of only the nearest vectors.
+- [Authored context partitioning](./docs/ast-v2.md): splits authored Markdown into hard directives, soft directives, and searchable lore so critical instructions are always preserved while narrative context still competes through retrieval.
+- [Domain-Adaptive Gating](./docs/gating.md): decides which turns deserve promotion into durable memory by blending conversational and technical signals rather than treating all chats like generic prose.
+- [Continuity preservation](./docs/continuity.md): protects a recent raw session tail and lets older history compact behind it, preventing summaries from erasing the newest working context.
+
+Three practical ideas shape the runtime:
+
+- Hybrid ranking keeps session turns, durable user memory, and global memory on the same scoreboard while still respecting recency.
+- Two-pass, in-place compaction preserves continuity by refusing destructive rewrites of the newest working tail.
+- Domain-adaptive ingestion avoids over-saving noisy chatter while still retaining technical decisions, file paths, error signatures, and workflow milestones.
+
+## Runtime Model
+
+- Plugin package: `@xdarkicex/openclaw-memory-libravdb`
+- OpenClaw plugin id: `libravdb-memory`
+- Minimum host version: `openclaw >= 2026.3.22`
+- Default daemon endpoint on macOS/Linux: `unix:$HOME/.clawdb/run/libravdb.sock`
+- Default daemon endpoint on Windows: `tcp:127.0.0.1:37421`
+- Default daemon data path: `$HOME/.clawdb/data.libravdb`
 
 ## Verify
 
@@ -81,4 +77,6 @@ Run:
 openclaw memory status
 ```
 
-Expected output includes a readable status table showing the daemon is reachable, stored turn/memory counts, the active ingestion gate threshold, and whether the abstractive summarizer is provisioned.
+Expected output includes a readable status table showing whether the daemon is
+reachable, how much memory is stored, and whether the local summarization path
+is provisioned.

package/docs/README.md

@@ -5,6 +5,8 @@ legacy non-versioned predecessor also exists. Older non-versioned docs are kept
 to preserve project history and design evolution.
 
 - [installation.md](./installation.md) - Complete install, activation, verification, and troubleshooting reference.
+- [install.md](./install.md) - Practical lifecycle guide for Homebrew, the OpenClaw plugin, and manual daemon management.
+- [uninstall.md](./uninstall.md) - Clean shutdown and removal guide for the plugin, daemon, and optional local data.
 - [architecture.md](./architecture.md) - End-to-end component model, turn lifecycle, compaction flow, and degraded behavior.
 - [problem.md](./problem.md) - Technical argument for replacing the stock OpenClaw memory lifecycle in this use case.
 - [mathematics-v2.md](./mathematics-v2.md) - Formal reference for hybrid scoring, decay, token budgeting, Matryoshka retrieval, compaction, and planned two-pass retrieval.

package/docs/install.md

@@ -0,0 +1,179 @@
+# Install Guide
+
+LibraVDB Memory is a connect-only OpenClaw plugin. Install the plugin as a
+normal package, install `libravdbd` separately, and point the plugin at the
+daemon endpoint when you need a non-default location.
+
+For deeper operational detail, use the full
+[installation reference](./installation.md).
+
+## Recommended Path: Homebrew + OpenClaw Plugin
+
+On macOS, the shortest supported path is:
+
+```bash
+brew tap xDarkicex/openclaw-libravdb-memory
+brew install libravdbd
+brew services start libravdbd
+openclaw plugins install @xdarkicex/openclaw-memory-libravdb
+```
+
+This gives you:
+
+- a managed `libravdbd` service
+- a scanner-clean plugin install
+- a clean separation between plugin lifecycle and daemon lifecycle
+
+## Plugin Install
+
+Install the plugin package with the OpenClaw CLI:
+
+```bash
+openclaw plugins install @xdarkicex/openclaw-memory-libravdb
+```
+
+If you use the OpenClaw.ai plugin UI instead of the CLI, install the same
+package and then assign the plugin id `libravdb-memory` to the `memory` slot or
+the `contextEngine` slot.
+
+Activate the plugin in `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "slots": {
+      "memory": "libravdb-memory"
+    }
+  }
+}
+```
+
+If you run the daemon on a non-default endpoint, add a plugin config:
+
+```json
+{
+  "plugins": {
+    "slots": {
+      "memory": "libravdb-memory"
+    },
+    "configs": {
+      "libravdb-memory": {
+        "sidecarPath": "unix:/Users/<you>/.clawdb/run/libravdb.sock"
+      }
+    }
+  }
+}
+```
+
+## Sidecar Daemon Install
+
+The daemon owns the local database, embeddings, and JSON-RPC endpoint.
+
+Default endpoints:
+
+- macOS/Linux: `unix:$HOME/.clawdb/run/libravdb.sock`
+- Windows: `tcp:127.0.0.1:37421`
+
+Default data path:
+
+- macOS/Linux/Windows user installs: `$HOME/.clawdb/data.libravdb`
+
+### Homebrew
+
+Homebrew is the preferred daemon lifecycle on macOS:
+
+```bash
+brew tap xDarkicex/openclaw-libravdb-memory
+brew install libravdbd
+brew services start libravdbd
+```
+
+Useful lifecycle commands:
+
+```bash
+brew services restart libravdbd
+brew services stop libravdbd
+brew info libravdbd
+```
+
+### Manual Service Management
+
+If you are not using Homebrew, manage the daemon explicitly.
+
+Linux user service from the repo template:
+
+```bash
+# Replace vX.Y.Z with the latest tag from:
+# https://github.com/xDarkicex/openclaw-memory-libravdb/releases
+mkdir -p ~/.local/bin ~/.config/systemd/user
+curl -L -o ~/.local/bin/libravdbd https://github.com/xDarkicex/openclaw-memory-libravdb/releases/download/vX.Y.Z/libravdbd-linux-amd64
+chmod +x ~/.local/bin/libravdbd
+curl -L -o ~/.config/systemd/user/libravdbd.service \
+  https://raw.githubusercontent.com/xDarkicex/openclaw-memory-libravdb/main/packaging/systemd/libravdbd.service
+systemctl --user enable --now libravdbd.service
+```
+
+macOS LaunchAgent from the repo template:
+
+1. Download `com.xdarkicex.libravdbd.plist` from:
+   `https://raw.githubusercontent.com/xDarkicex/openclaw-memory-libravdb/main/packaging/launchd/com.xdarkicex.libravdbd.plist`
+2. Replace `__HOME__` with your home directory.
+3. Save it to `~/Library/LaunchAgents/com.xdarkicex.libravdbd.plist`.
+4. Load it with `launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.xdarkicex.libravdbd.plist`.
+
+### Windows
+
+Windows uses a loopback TCP endpoint by default:
+
+- `tcp:127.0.0.1:37421`
+
+This guide does not yet include a full Windows service-install walkthrough.
+For now, use the published Windows daemon asset from the GitHub releases page
+and run it under your preferred process supervisor or a manual terminal session.
+
+Foreground manual run:
+
+```bash
+libravdbd serve
+```
+
+That mode is useful for debugging or validating a local release asset before
+you wrap it in `brew services`, `systemd`, or `launchd`.
+
+## Lifecycle Management
+
+### Plugin Lifecycle
+
+- Install the package with `openclaw plugins install`.
+- Activate it by assigning `libravdb-memory` to `memory` or `contextEngine`.
+- Update it with your normal OpenClaw plugin update flow.
+- Disable it by removing the slot assignment from `~/.openclaw/openclaw.json`.
+
+The plugin does not manage the daemon process. Treat plugin activation and
+daemon supervision as separate lifecycle decisions.
+
+### Daemon Lifecycle
+
+- Start it with `brew services`, `systemd --user`, `launchctl bootstrap`, or a manual `libravdbd serve`.
+- Restart it when you change daemon-level environment variables or replace the binary.
+- Stop it before uninstalling or deleting on-disk data.
+- Point the plugin at the correct endpoint with `sidecarPath` if you do not use the default location.
+
+## Verification
+
+After the plugin and daemon are both in place, run:
+
+```bash
+openclaw memory status
+```
+
+Healthy output should show that:
+
+- the daemon answered the local health check
+- the memory slot is active
+- the plugin can read stored counts and runtime settings
+
+If OpenClaw cannot reach the daemon, verify the endpoint first:
+
+- macOS/Linux default: `unix:$HOME/.clawdb/run/libravdb.sock`
+- Windows default: `tcp:127.0.0.1:37421`

package/docs/uninstall.md

@@ -0,0 +1,100 @@
+# Uninstall Guide
+
+This guide covers safe removal of the OpenClaw / OpenClaw.ai plugin and the
+separately managed `libravdbd` daemon.
+
+If you only want to disable the memory replacement temporarily, remove the
+plugin slot assignment first and leave the daemon plus data in place.
+
+## 1. Disable the Plugin
+
+Remove the plugin from the active OpenClaw slot in `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "slots": {}
+  }
+}
+```
+
+Treat that JSON as a minimal example only. If you assigned `libravdb-memory`
+under `memory` or `contextEngine`, remove just that slot entry and leave any
+other plugin slots intact.
+
+If you installed the package through the OpenClaw.ai plugin UI, remove or
+disable the same package there as well. If you use the CLI, remove it through
+your standard OpenClaw plugin removal flow for
+`@xdarkicex/openclaw-memory-libravdb`.
+
+## 2. Stop the Daemon
+
+Stop the sidecar before deleting binaries or stored data.
+
+Homebrew:
+
+```bash
+brew services stop libravdbd
+```
+
+Linux user service:
+
+```bash
+systemctl --user disable --now libravdbd.service
+```
+
+macOS LaunchAgent:
+
+```bash
+launchctl bootout gui/$(id -u)/com.xdarkicex.libravdbd
+```
+
+Foreground manual run:
+
+- stop the `libravdbd serve` process in the terminal where it is running
+
+## 3. Remove Installed Assets
+
+### Plugin Package
+
+Remove the published plugin package from OpenClaw or OpenClaw.ai after it is no
+longer assigned to an active slot.
+
+### Homebrew Daemon
+
+```bash
+brew uninstall libravdbd
+brew untap xDarkicex/openclaw-libravdb-memory
+```
+
+### Manual Daemon Install
+
+Delete the service file or launch agent you installed, along with the daemon
+binary you copied into place.
+
+Common locations:
+
+- `~/.config/systemd/user/libravdbd.service`
+- `~/Library/LaunchAgents/com.xdarkicex.libravdbd.plist`
+- `~/.local/bin/libravdbd`
+
+## 4. Optional Full Data Cleanup
+
+Only do this if you want to permanently remove stored LibraVDB memory.
+
+Common local state:
+
+- socket directory: `~/.clawdb/run/`
+- database file: `~/.clawdb/data.libravdb`
+
+If you configured a custom Unix socket endpoint in `sidecarPath`, remove that
+socket path or containing directory if applicable. If you configured `dbPath`,
+remove that custom database location instead of the default path. TCP
+`sidecarPath` endpoints are not filesystem paths and do not have anything to
+delete during uninstall.
+
+## 5. Post-Uninstall Check
+
+After cleanup, `openclaw memory status` should no longer show this plugin as the
+active memory provider, and the daemon endpoint should no longer be reachable
+unless you intentionally kept it running for another workflow.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xdarkicex/openclaw-memory-libravdb",
-  "version": "1.3.12",
+  "version": "1.3.13",
   "type": "module",
   "publishConfig": {
     "access": "public"