@xdarkicex/openclaw-memory-libravdb 1.4.16 → 1.4.17

package/docs/README.md

@@ -1,16 +1,31 @@
-# Documentation Index
-
-This index lists the public docs that remain in the main repo. Detailed math
-and private design notes are kept out of the public index on purpose.
-
-- [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) - Public system overview covering the plugin, daemon, storage, retrieval, and compaction flow.
-- [problem.md](./problem.md) - Technical argument for replacing the stock OpenClaw memory lifecycle in this use case.
-- [dependencies.md](./dependencies.md) - Why LibraVDB and slab-based storage were chosen for this plugin.
-- [models.md](./models.md) - ONNX model strategy, latency trade-offs, and shipped model roles.
-- [security.md](./security.md) - Security model, untrusted-memory framing, isolation guarantees, and deletion boundaries.
-- [contributing.md](./contributing.md) - Contributor workflow, prerequisites, and invariant test expectations.
-- [architecture-decisions/README.md](./architecture-decisions/README.md) - Index of the repository ADRs.
-- [embedding-profiles.md](./embedding-profiles.md) - Shipped embedding profile baseline and current profile metadata.
+# LibraVDB Memory Docs
+
+This directory holds the operational and design docs for the LibraVDB Memory
+OpenClaw plugin. The root README is the public entry point; these files go
+deeper by goal.
+
+## Start Here
+
+- [Install](./install.md) - shortest supported install and daemon lifecycle path.
+- [Installation reference](./installation.md) - requirements, activation, verification, and troubleshooting.
+- [Uninstall](./uninstall.md) - safe disable, daemon shutdown, package removal, and optional data cleanup.
+
+## Understand The System
+
+- [Problem](./problem.md) - why this plugin replaces the stock memory lifecycle.
+- [Architecture](./architecture.md) - plugin, sidecar, storage, retrieval, and compaction overview.
+- [Dependency rationale](./dependencies.md) - why LibraVDB and slab-style storage fit this workload.
+- [Architecture decisions](./architecture-decisions/README.md) - accepted ADRs.
+
+## Configure And Operate
+
+- [Features](./features.md) - markdown ingestion, Obsidian ingestion, dream promotion, and memory CLI commands.
+- [Security](./security.md) - trust boundaries, untrusted-memory framing, collection isolation, and deletion limits.
+- [Embedding profiles](./embedding-profiles.md) - shipped embedding profile metadata and defaults.
+- [Models](./models.md) - local ONNX model strategy and summarization roles.
+
+## Advanced And Source Docs
+
+- [Performance and tuning](./performance-and-tuning.md) - resource expectations and tuning knobs.
+- [Development](./development.md) - source setup, local daemon builds, generated IPC files, and validation commands.
+- [Contributing](./contributing.md) - contributor workflow and repository expectations.

package/docs/assets/libravdb-logo.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="170" viewBox="0 0 1280 170" role="img" aria-labelledby="title desc">
+  <title id="title">LibraVDB</title>
+  <desc id="desc">Dark purple LibraVDB wordmark.</desc>
+  <rect width="1280" height="170" fill="none"/>
+  <text
+    x="640"
+    y="128"
+    text-anchor="middle"
+    fill="#5B21B6"
+    font-family="Inter, Avenir Next, Helvetica Neue, Arial, sans-serif"
+    font-size="150"
+    font-weight="800"
+    letter-spacing="0">LibraVDB</text>
+</svg>

package/docs/contributing.md

@@ -1,88 +1,35 @@
 # Contributing
 
-## Prerequisites
+Use [Development](./development.md) for source setup, local daemon preparation,
+generated IPC files, and validation commands. This document covers contribution
+expectations.
 
-- Node.js `>= 22`
-- `pnpm`
-- OpenClaw CLI for end-to-end plugin testing
+## Baseline Checks
 
-## Core Validation Commands
-
-TypeScript and unit checks:
+Before opening a PR:
 
 ```bash
 pnpm check
-```
-
-Integration tests:
-
-```bash
-npm run test:integration
-```
-
-Plugin integration tests:
-
-```bash
 npm run test:integration
 ```
 
-## Local Daemon Build
+Integration tests require a running daemon or a prepared local daemon binary.
+Use:
 
 ```bash
 bash scripts/build-daemon.sh
 ```
 
-This prepares `.daemon-bin/libravdbd` for local plugin testing and copies locally available bundled assets into `.daemon-bin/`.
-
-Supported inputs:
-
-- installed daemon on `PATH` such as `brew install libravdbd`
-- `LIBRAVDBD_BINARY_PATH=/path/to/libravdbd`
-- `LIBRAVDBD_SOURCE_DIR=/path/to/libravdbd` to build from your private local daemon repo
-
-For daemon-internal Go development and release work, use the separate `libravdbd` repository.
+## Behavioral Changes
 
-## Gating Invariants
-
-Do not weaken the gate invariants casually. The daemon-owned tests in `libravdbd/compact/gate_test.go` check structural properties:
-
-- empty-memory novelty
-- saturation veto
-- convex boundedness
-- conversational collapse at `T = 0`
-- technical collapse at `T = 1`
-- non-overfiring conversational structure on code
-
-If you add a new signal, it must preserve those invariants.
-
-## Calibration Coverage
-
-There is not yet a dedicated `gate_calibration_test.go` golden set in the
-repository. Current gating correctness is enforced by the invariant suite in
-`libravdbd/compact/gate_test.go`.
-
-If you introduce new signals or change weighting behavior, do not only update
-the implementation. Add one of:
-
-- a new invariant if the change alters a structural property of the gate
-- a dedicated calibration/golden test file if the change adds new labeled
-  examples or expected decompositions
-
-Do not rewrite expectations just to make regressions disappear.
+If you change retrieval, compaction, or ranking behavior, add or update the
+matching validation coverage and avoid weakening checks just to hide a
+regression.
 
 ## PR Expectations
 
-Before opening a PR:
-
-- `pnpm check` must pass
-- plugin integration coverage must pass against a running daemon or a prepared local daemon binary
-- any new gating signal must come with calibration or invariant coverage
-- any retrieval math or gating change must be reflected in the private design notes
-
-## Release Versioning
-
-`package.json` is the source of truth for the release version.
-
-The release automation syncs `openclaw.plugin.json` from `package.json` during the
-auto-bump/tag flow, and the publish workflow refuses to publish if the Git tag,
-`package.json`, and `openclaw.plugin.json` versions do not all match.
+- Keep plugin lifecycle and daemon lifecycle separate.
+- Include focused docs updates for user-visible behavior or config changes.
+- Keep internal design changes reflected in the appropriate design notes.
+- Do not add install-time daemon bootstrap to the npm/OpenClaw package without
+  documenting the security and distribution trade-off.

package/docs/development.md

@@ -0,0 +1,98 @@
+# Development
+
+This document covers source setup and repository maintenance tasks. For user
+installation, use [Install](./install.md).
+
+## Prerequisites
+
+- Node.js `>= 22`
+- `pnpm`
+- OpenClaw CLI for end-to-end plugin testing
+- a published or locally built `libravdbd` daemon for integration tests
+
+Go is only required when building the daemon from a local daemon checkout or
+regenerating Go gRPC stubs.
+
+## Source Setup
+
+```bash
+pnpm install
+pnpm check
+```
+
+`pnpm check` runs TypeScript validation and unit tests:
+
+```bash
+tsc --noEmit
+tsc -p tsconfig.tests.json && node --test .ts-build/test/unit/*.test.js
+```
+
+## Local Daemon Build
+
+Prepare `.daemon-bin/libravdbd` for local plugin testing:
+
+```bash
+bash scripts/build-daemon.sh
+```
+
+Supported inputs:
+
+- installed daemon on `PATH`, such as `brew install libravdbd`
+- `LIBRAVDBD_BINARY_PATH=/path/to/libravdbd`
+- `LIBRAVDBD_SOURCE_DIR=/path/to/libravdbd` to build from a local daemon repo
+
+For daemon-internal Go development and release work, use the separate
+`libravdbd` repository.
+
+## Validation Commands
+
+```bash
+pnpm check
+npm run test:integration
+```
+
+Benchmark and tuning commands are documented in
+[Performance and tuning](./performance-and-tuning.md).
+
+## Generated IPC Files
+
+The plugin imports generated IPC envelope and RPC payload classes from
+`src/generated/libravdb/ipc/v1/rpc_pb.js`.
+
+Those generated files are checked in and copied into `dist/generated/` during
+`npm run build`:
+
+```bash
+npm run build
+```
+
+Do not replace those imports with the older external
+`@xdarkicex/libravdb-contracts` path. The current package resolves generated
+types from this repository.
+
+## Proto Generation
+
+The repo also contains `api/proto/intelligence_kernel/v1/kernel.proto` and a
+small `Makefile` target for Go gRPC stub generation:
+
+```bash
+make proto
+```
+
+That target assumes Homebrew-style locations for `go`, `protoc`, and the Go
+plugins. Adjust the Makefile locally if your toolchain lives elsewhere.
+
+## Release Shape
+
+The npm package contains:
+
+- `README.md`
+- `HOOK.md`
+- `index.js`
+- `openclaw.plugin.json`
+- `package.json`
+- `docs/`
+- `dist/`
+
+The package is connect-only. It does not compile Go code, download models, or
+manage the daemon process during plugin installation.

package/docs/features.md

@@ -0,0 +1,125 @@
+# Features
+
+This document covers optional plugin features that do not belong in the root
+README: markdown ingestion, Obsidian ingestion, dream promotion, and memory CLI
+commands.
+
+## Markdown Ingestion
+
+LibraVDB Memory can watch markdown roots and sync changed notes into vector
+memory without changing the sidecar RPC contract.
+
+The built-in source adapters are:
+
+- `generic` for OpenClaw-owned markdown, including stock files like `MEMORY.md`
+- `obsidian` for Obsidian vault roots, with tag-aware defaults
+
+Typical usage:
+
+- point `markdownIngestionRoots` at OpenClaw-owned markdown roots, such as
+  `.openclaw/skills/*/*.md` or a directory that contains `MEMORY.md`
+- enable the Obsidian adapter with `markdownIngestionObsidianEnabled: true` and
+  one or more vault roots
+- use include/exclude globs to narrow what gets watched
+
+Example:
+
+```json
+{
+  "plugins": {
+    "configs": {
+      "libravdb-memory": {
+        "markdownIngestionEnabled": true,
+        "markdownIngestionRoots": [
+          "/Users/<you>/.openclaw/memory"
+        ],
+        "markdownIngestionObsidianEnabled": true,
+        "markdownIngestionObsidianRoots": [
+          "/Users/<you>/Documents/Obsidian/Main"
+        ]
+      }
+    }
+  }
+}
+```
+
+Relevant config fields:
+
+| Field | Purpose |
+|---|---|
+| `markdownIngestionEnabled` | Enables or disables generic markdown ingestion. |
+| `markdownIngestionRoots` | Generic markdown roots to watch. |
+| `markdownIngestionInclude` | Optional include globs for generic roots. |
+| `markdownIngestionExclude` | Optional exclude globs for generic roots. |
+| `markdownIngestionCollection` | Target collection for generic markdown, default `global`. |
+| `markdownIngestionDebounceMs` | Watch debounce window, default `150`. |
+| `markdownIngestionObsidianEnabled` | Enables Obsidian ingestion when vault roots exist. |
+| `markdownIngestionObsidianRoots` | Obsidian vault roots to watch. |
+| `markdownIngestionObsidianInclude` | Optional include globs for Obsidian roots. |
+| `markdownIngestionObsidianExclude` | Optional exclude globs for Obsidian roots. |
+| `markdownIngestionObsidianDebounceMs` | Obsidian watch debounce window, default `150`. |
+
+By default, the Obsidian adapter auto-ingests notes that look like memory notes,
+using frontmatter tags or inline tags such as `#project`. The stock OpenClaw
+`MEMORY.md` file is always eligible through the generic adapter path.
+
+## Dream Promotion
+
+Dream promotion is an opt-in path for promoting vetted dream diary entries into
+a dedicated `dream:{userId}` collection.
+
+It does not use `MEMORY.md`. It expects a dream diary markdown file with
+candidate bullets under promotion-oriented headings such as `## Deep Sleep`.
+Each promoted bullet should include trailing metadata with the gating fields:
+
+```md
+- Preserve the recent tail buffer {score=0.82 recall=3 unique=2}
+```
+
+Only bullets that satisfy the sidecar gates are inserted. The dream collection
+is isolated from normal `user:` and `global` retrieval by default, and dream
+phrasing in chat or search queries routes there automatically.
+
+Automatic diary watching:
+
+```json
+{
+  "plugins": {
+    "configs": {
+      "libravdb-memory": {
+        "dreamPromotionEnabled": true,
+        "dreamPromotionDiaryPath": "/Users/<you>/DREAMS.md",
+        "dreamPromotionUserId": "<userId>",
+        "dreamPromotionDebounceMs": 150
+      }
+    }
+  }
+}
+```
+
+Manual run:
+
+```bash
+openclaw memory dream-promote --user-id <userId> --dream-file /path/to/DREAMS.md
+```
+
+The manual command and watcher both use the same sidecar promotion RPC, so
+admission gates and provenance metadata are identical.
+
+## Memory CLI
+
+The plugin registers `openclaw memory` commands when the host exposes the plugin
+CLI API.
+
+| Command | Purpose |
+|---|---|
+| `openclaw memory status` | Show sidecar health, counts, active thresholds, and model readiness. |
+| `openclaw memory export --user-id <userId>` | Stream stored memories as newline-delimited JSON for one durable namespace. |
+| `openclaw memory export --session-key <sessionKey>` | Export a namespace derived from a session key. |
+| `openclaw memory flush --user-id <userId>` | Delete one durable user namespace after confirmation. |
+| `openclaw memory flush --session-key <sessionKey>` | Delete a namespace derived from a session key after confirmation. |
+| `openclaw memory journal --limit 50` | Inspect bounded lifecycle hints recorded by the sidecar. |
+| `openclaw memory dream-promote --user-id <userId> --dream-file <path>` | Promote vetted dream diary bullets. |
+
+Use `--yes` with `flush` only when you intentionally want to skip the
+confirmation prompt.

package/docs/install.md

@@ -4,6 +4,10 @@ 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.
 
+OpenClaw compatibility note:
+
+- the plugin is currently verified against OpenClaw `2026.4.23`
+
 For deeper operational detail, use the full
 [installation reference](./installation.md).