@xdarkicex/openclaw-memory-libravdb 1.3.13 → 1.3.18

package/docs/installation.md

@@ -7,7 +7,7 @@ This document is the full installation reference for `@xdarkicex/openclaw-memory
 | Requirement | Minimum | Recommended | Notes |
 |---|---|---|---|
 | Node.js | `22.0.0` | Latest LTS | Enforced in [`package.json`](../package.json) `engines.node` |
-| OpenClaw | `2026.3.22` | Current stable | Pinned by [`package.json`](../package.json) `peerDependencies.openclaw`; this is the earliest local tag confirmed to expose `definePluginEntry`, `registerContextEngine`, `registerMemoryPromptSection`, and the plugin API shape this repo uses |
+| OpenClaw | `2026.3.22` | Current stable | Pinned by [`package.json`](../package.json) `peerDependencies.openclaw`; this is the earliest local tag confirmed to expose `definePluginEntry`, `registerContextEngine`, `registerMemoryPromptSection`, and the base plugin API shape this repo uses. Newer hosts may also expose the optional `registerMemoryRuntime` seam, which this plugin now adopts when available |
 | Go | `1.22` | Latest stable | Required only for local daemon development, not for normal plugin install |
 | Disk | about `1 GB` free for default Nomic install | `2 GB+` if provisioning optional T5 and leaving room for DB growth | See Resource Requirements below |
 | RAM | about `512 MB` for embed-only runtime | `1 GB+` if optional T5 summarizer is provisioned | Based on local RSS measurements below |
@@ -183,6 +183,8 @@ The release workflow generates a publish-ready `libravdbd.rb` formula asset from
 - `libravdbd-linux-amd64`
 - `libravdbd-linux-arm64`
 
+The generated Homebrew formula also stages the bundled ONNX Runtime archive, the shipped embedding profile assets, and the T5 summarizer bundle into the install prefix so the daemon can start without a separate manual asset unpack step.
+
 If your GitHub Actions configuration includes:
 
 - repository variable `HOMEBREW_TAP_REPO`, for example `xDarkicex/homebrew-openclaw-libravdb-memory`
@@ -196,7 +198,8 @@ Example plugin config:
 {
   "plugins": {
     "slots": {
-      "memory": "libravdb-memory"
+      "memory": "libravdb-memory",
+      "contextEngine": "libravdb-memory"
     },
     "configs": {
       "libravdb-memory": {
@@ -217,7 +220,7 @@ Installed plugin: libravdb-memory
 
 ## Activation
 
-The plugin declares `kind: ["memory", "context-engine"]` and registers for both the `memory` and `context-engine` slots. Either slot assignment activates the plugin.
+The plugin declares `kind: ["memory", "context-engine"]` and is intended to own both the `memory` and `contextEngine` slots together. Treat partial slot assignment as a misconfiguration.
 
 Add this to `~/.openclaw/openclaw.json`:
 
@@ -225,18 +228,7 @@ Add this to `~/.openclaw/openclaw.json`:
 {
   "plugins": {
     "slots": {
-      "memory": "libravdb-memory"
-    }
-  }
-}
-```
-
-If your OpenClaw build uses the `contextEngine` slot instead, you can assign it there:
-
-```json
-{
-  "plugins": {
-    "slots": {
+      "memory": "libravdb-memory",
       "contextEngine": "libravdb-memory"
     }
   }
@@ -245,8 +237,13 @@ If your OpenClaw build uses the `contextEngine` slot instead, you can assign it
 
 Notes:
 
-- Either `memory` or `contextEngine` slot assignment activates the plugin. You do not need both.
+- This plugin should own both `memory` and `contextEngine`. Do not assign only one of them.
 - The plugin id is `libravdb-memory`. The npm package name used at install time is `@xdarkicex/openclaw-memory-libravdb`.
+- On newer OpenClaw versions, the plugin also registers a memory runtime bridge so the built-in `memory_search` tool can query libraVDB through the same sidecar-backed retrieval path.
+- On newer OpenClaw versions, the plugin also listens for `before_reset` and `session_end` so it can send best-effort lifecycle hints into the sidecar.
+- Those hints are journaled internally by the sidecar and can be inspected with `openclaw memory journal` without exposing them to normal memory export or recall.
+- The journal keeps only a bounded number of newest entries. Override that cap with `plugins.configs.libravdb-memory.lifecycleJournalMaxEntries` if you need a different retention window.
+- The plugin does not currently register `registerMemoryFlushPlan`; transcript ingest and compaction remain owned by the context-engine lifecycle and the sidecar.
 
 Without a slot entry, OpenClaw's default memory can continue to run in parallel.
 

package/docs/mathematics-v2.md

@@ -5,7 +5,9 @@ by the plugin. The gating scalar is documented separately in
 [gating.md](./gating.md). The continuity model and recent-tail preservation
 layer are documented in [continuity.md](./continuity.md). The authored
 invariant/variant partitioning rules are documented in
-[ast-v2.md](./ast-v2.md). Earlier non-versioned math docs are preserved for
+[ast-v2.md](./ast-v2.md). The protected-shadow-rule Tier 1.5 model is
+documented in [elevated-guidance.md](./elevated-guidance.md). Earlier
+non-versioned math docs are preserved for
 historical context, but the reviewed `*-v*` documents are authoritative when
 both forms exist.
 
@@ -603,6 +605,69 @@ $$
 
 This makes compaction load-bearing in retrieval rather than archival only.
 
+### 5.6 Optional Lossless Compaction Extension
+
+The current implementation replaces compacted session turns in the searchable
+session collection after summary insertion succeeds. A stronger future variant
+is to preserve compacted raw turns in an immutable session-history layer and
+treat summary records as derived view nodes over that history. This extension is
+inspired by the immutable-store and expandable-summary architecture in the LCM
+paper ([Ehrlich and Blackman, 2026](https://papers.voltropy.com/LCM)), but the
+formalization here is adapted to this repository's existing compaction and
+continuity math.
+
+Let:
+
+$$
+\mathcal{R}_{\mathrm{session}}=\langle r_1,\dots,r_n\rangle
+$$
+
+be the immutable raw session history, and let:
+
+$$
+\mathbf{S}=\{s_1,s_2,\dots\}
+$$
+
+be the set of compacted summary nodes. Define the summary-coverage DAG:
+
+$$
+\mathcal{G}_{\mathrm{cont}}=(\mathbf{S}\cup\mathcal{R}_{\mathrm{session}}, E_{\triangleleft})
+$$
+
+with:
+
+$$
+E_{\triangleleft}\subseteq (\mathbf{S}\times\mathbf{S})\cup(\mathbf{S}\times\mathcal{R}_{\mathrm{session}})
+$$
+
+Recursive raw expansion is:
+
+$$
+\mathrm{Expand}^{*}(x)=
+\begin{cases}
+\{x\} & \text{if } x\in\mathcal{R}_{\mathrm{session}} \\
+\bigcup_{y:(x,y)\in E_{\triangleleft}} \mathrm{Expand}^{*}(y) & \text{if } x\in\mathbf{S}
+\end{cases}
+$$
+
+The continuity contract for this extension is:
+
+$$
+\forall s\in\mathbf{S},\ \mathrm{Expand}^{*}(s)\neq\emptyset
+$$
+
+and:
+
+$$
+\forall r\in\mathcal{R}_{\mathrm{session}},\ \exists x\in \mathbf{S}\cup T_{\mathrm{recent}} \text{ such that } r\in\mathrm{Expand}^{*}(x)
+$$
+
+Under this extension, compaction changes the active retrievable view and the
+assembly surface, but not the existence of raw historical evidence. This is
+compatible with the section-1 through section-5 retrieval math because the
+hybrid score still applies to the injected/searchable nodes; the extension only
+strengthens the recoverability contract beneath those nodes.
+
 ## 6. Why These Pieces Compose
 
 The full quality loop is:
@@ -1226,3 +1291,98 @@ Q(d)\in[1-\delta,\,1]\subseteq[0,1]
 $$
 
 for all valid inputs with $\delta\in[0,1]$.
+
+## 8. Theory Boundary And Future Refinement
+
+Cross-review of this document and [`continuity.md`](./continuity.md) surfaced a
+useful mathematical boundary that this reference should keep explicit:
+
+1. storage and continuity axioms
+2. primary retrieval and assembly math
+3. optional recoverability policy
+
+### 8.1 What Is Core Math
+
+The core retrieval theorem in this document is the scored, budgeted selection
+of retrievable nodes from $\mathcal{V}_{\mathrm{rest}}$ together with authored
+invariants and the exact recent tail. In other words, the primary law remains:
+
+$$
+C_{\mathrm{total}}(q)=\mathcal{I}_1\cup \mathcal{I}_2^{*}\cup T_{\mathrm{recent}}\cup \mathrm{Proj}(\mathcal{V}_{\mathrm{rest}}, q)
+$$
+
+with the retrieval side governed by:
+
+$$
+S_{\mathrm{final}}(d)=S_{\mathrm{base}}(d)\cdot Q(d)
+$$
+
+and the budget side governed by the residual variant budget
+$\tau_{\mathcal{V}}(q)$ defined in Section 7.8.
+
+### 8.2 What Is Not Core Math
+
+The following should be treated as policy or heuristic unless they are derived
+from the governing score equations and budget laws:
+
+- automatic query-time summary expansion
+- fixed expansion penalties
+- fixed expansion token sub-budgets
+- confidence thresholds for expansion eligibility
+- recursion-depth limits for summary expansion
+
+These controls may be useful in runtime experiments, but they are not theorem
+terms by default. They should not be mistaken for new axioms of the scoring
+model.
+
+### 8.3 Lossless Does Not Mean Always Expand
+
+The lossless extension in Section 5.6 strengthens the storage and
+recoverability contract. It does not imply that every relevant summary should be
+expanded into raw turns during ordinary retrieval.
+
+The mathematically safe reading is:
+
+- raw immutability is an axiom
+- $\mathrm{Expand}^{*}$ is a recoverability theorem over the summary DAG
+- query-time expansion is **explicit recovery/audit only** — it was removed from
+  the hot retrieval path and is not the default behavior; any expansion beyond
+  the core $C_{\mathrm{total}}(q)$ assembly must be triggered deliberately, not
+  applied silently to ranked candidates
+
+This distinction preserves the design goal that continuity and recoverability
+support retrieval without silently replacing it.
+
+### 8.4 Preferred Direction For Future Refinement
+
+If a future version wants query-time expansion inside the main retrieval path,
+the preferred direction is to re-derive it from the existing two-pass and
+multi-hop framework rather than introduce standalone penalties and thresholds
+that float outside the score model.
+
+In practical terms, future refinement should prefer one of two paths:
+
+1. keep summary expansion as a separate recovery or audit layer
+2. formally unify summary expansion with the existing hop-expansion math
+
+What this document should avoid is an in-between state where recoverability
+logic behaves like a second retrieval theorem without being derived as one.
+
+### 8.5 Preserved Research Ideas
+
+The review process also surfaced several strong theoretical ideas that are worth
+retaining for future work:
+
+- rate-distortion views of compaction quality
+- information-adaptive clustering instead of equal-size chronological buckets
+- hot-spot preservation tiers driven by access concentration
+- causal-centrality-aware compaction penalties or vetoes
+- entropy-based tail selection
+- retrieval-failure-triggered raw-history recovery (the specific observable
+  signals S1/S2/S3 are defined in the vNext spec slice; this entry refers to the
+  general concept, not the current implementation)
+- closed-loop compaction tuning driven by observed retrieval quality
+
+These ideas are intentionally preserved as future mathematics rather than
+current contract. The present document remains normative only for the formulas
+and invariants already defined above.

package/docs/uninstall.md

@@ -19,8 +19,8 @@ Remove the plugin from the active OpenClaw slot in `~/.openclaw/openclaw.json`:
 ```
 
 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.
+under both `memory` and `contextEngine`, remove those two slot entries 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

package/openclaw.plugin.json

@@ -10,6 +10,7 @@
     "properties": {
       "dbPath": { "type": "string" },
       "sidecarPath": { "type": "string" },
+      "useSessionSummarySearchExperiment": { "type": "boolean" },
       "embeddingRuntimePath": { "type": "string" },
       "embeddingBackend": { "type": "string", "enum": ["bundled", "onnx-local", "custom-local"] },
       "embeddingProfile": {
@@ -64,6 +65,10 @@
         "type": "number",
         "default": 10
       },
+      "lifecycleJournalMaxEntries": {
+        "type": "number",
+        "default": 500
+      },
       "compactionQualityWeight": {
         "type": "number",
         "default": 0.5,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xdarkicex/openclaw-memory-libravdb",
-  "version": "1.3.13",
+  "version": "1.3.18",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -27,6 +27,13 @@
     "check": "./.ts-toolchain/node_modules/.bin/tsc --noEmit && pnpm run test:ts",
     "test:ts": "./.ts-toolchain/node_modules/.bin/tsc -p tsconfig.tests.json && node --test .ts-build/test/unit/*.test.js",
     "test:integration": "./.ts-toolchain/node_modules/.bin/tsc -p tsconfig.tests.json && node --test .ts-build/test/integration/checklist-validation.test.js .ts-build/test/integration/host-flow.test.js .ts-build/test/integration/sidecar-lifecycle.test.js",
+    "benchmark:session_search_mid": "./.ts-toolchain/node_modules/.bin/tsc -p tsconfig.tests.json && OPENCLAW_PROFILE_ASSEMBLE=1 node --test --test-name-pattern=\"real sidecar mid-sized session search benchmark\" .ts-build/test/integration/host-flow.test.js",
+    "gate:assemble_optimization": "./.ts-toolchain/node_modules/.bin/tsc -p tsconfig.tests.json && OPENCLAW_PROFILE_ASSEMBLE=1 OPENCLAW_ENFORCE_ASSEMBLE_EVIDENCE_GATE=1 node --test --test-name-pattern=\"real sidecar mid-sized session search benchmark\" .ts-build/test/integration/host-flow.test.js",
+    "probe:session_recall": "./.ts-toolchain/node_modules/.bin/tsc -p tsconfig.tests.json && OPENCLAW_PROFILE_ASSEMBLE=1 node --test --test-name-pattern=\"real sidecar mid-sized session search benchmark\" .ts-build/test/integration/host-flow.test.js",
+    "probe:session_recall_threshold": "./.ts-toolchain/node_modules/.bin/tsc -p tsconfig.tests.json && OPENCLAW_PROFILE_ASSEMBLE=1 node --test --test-name-pattern=\"real sidecar session_recall index threshold probe\" .ts-build/test/integration/host-flow.test.js",
+    "benchmark:longmemeval": "./.ts-toolchain/node_modules/.bin/tsc -p tsconfig.tests.json && node --test .ts-build/test/integration/longmemeval-benchmark.test.js",
+    "benchmark:longmemeval:score": "node scripts/longmemeval-score.mjs",
+    "benchmark:longmemeval:diagnose": "node scripts/longmemeval-diagnose.mjs",
     "build:daemon": "bash scripts/build-daemon.sh"
   },
   "dependencies": {

package/packaging/README.md

@@ -11,16 +11,51 @@ The templates assume the default daemon endpoint contract used by the plugin:
 - macOS/Linux: `unix:$HOME/.clawdb/run/libravdb.sock`
 - Windows: `tcp:127.0.0.1:37421`
 
+## LaunchAgent plist
+
 Before loading the macOS plist, replace:
 
 - `__LIBRAVDBD_PATH__` with the absolute path to the `libravdbd` binary
 - `__HOME__` with the current user's home directory
+- `__ONNX_RUNTIME_LIB__` with the absolute path to the ONNX runtime shared library (e.g. `/path/to/onnxruntime/onnxruntime-osx-arm64-1.23.0/lib/libonnxruntime.dylib`)
+
+## Provisioning models and runtime
+
+**Primary install path:** The Homebrew formula (`brew install libravdbd`)
+provisions all required assets — ONNX Runtime, nomic-embed-text-v1.5,
+all-minilm-l6-v2, and t5-small — inline during `brew install`.  No
+additional steps are needed for a clean install.
+
+**Repair / recovery:** If assets are deleted or corrupted after install,
+`scripts/provision.sh` can rebuild them.  This is an operator tool, not
+the normal install path.
+
+```bash
+bash scripts/provision.sh                     # provisions into .daemon-bin/
+bash scripts/provision.sh --target /opt/libravdbd/assets  # custom target
+bash scripts/provision.sh --skip-summarizer   # skip optional t5-small model
+```
+
+The script downloads models from HuggingFace and the ONNX runtime from
+GitHub Releases, verifies SHA-256 checksums, and writes the `embedding.json`
+manifests that `libravdbd` needs at startup.  It is idempotent — existing
+verified assets are left in place.
+
+The npm package does not include `provision.sh` or any install-time
+provisioning hooks.  The `scripts/` directory is excluded from the
+published npm tarball via the `files` whitelist in `package.json`.
+
+## Homebrew formula
 
 The release workflow now generates `dist/libravdbd.rb` from this template using
 the release version and SHA-256 files. If `HOMEBREW_TAP_REPO` and
 `HOMEBREW_TAP_TOKEN` are configured in GitHub Actions, the workflow also updates
 the tap automatically.
 
+The Homebrew formula stages the bundled ONNX Runtime archive, the shipped
+embedding profile assets, and the T5 summarizer bundle into the install prefix
+so the daemon can boot without an extra asset-unpack step.
+
 Expected GitHub configuration:
 
 - repository variable `HOMEBREW_TAP_REPO`, for example `xDarkicex/homebrew-openclaw-libravdb-memory`
@@ -33,3 +68,4 @@ Template placeholders:
 - `__SHA256_DARWIN_AMD64__`
 - `__SHA256_LINUX_ARM64__`
 - `__SHA256_LINUX_AMD64__`
+- `__SHA256_PROVISION__`

package/packaging/homebrew/libravdbd.rb.tmpl

@@ -23,15 +23,199 @@ class Libravdbd < Formula
     end
   end
 
+  if OS.mac?
+    resource "onnxruntime" do
+      url "https://github.com/microsoft/onnxruntime/releases/download/v1.23.0/onnxruntime-osx-universal2-1.23.0.tgz"
+      sha256 :no_check
+    end
+  elsif OS.linux?
+    if Hardware::CPU.arm?
+      resource "onnxruntime" do
+        url "https://github.com/microsoft/onnxruntime/releases/download/v1.23.0/onnxruntime-linux-aarch64-1.23.0.tgz"
+        sha256 :no_check # TODO: pin real checksum when Linux ARM64 CI is available
+      end
+    else
+      resource "onnxruntime" do
+        url "https://github.com/microsoft/onnxruntime/releases/download/v1.23.0/onnxruntime-linux-x64-1.23.0.tgz"
+        sha256 :no_check # TODO: pin real checksum when Linux AMD64 CI is available
+      end
+    end
+  end
+
+  resource "nomic-embed-text-v1.5-model" do
+    url "https://huggingface.co/nomic-ai/nomic-embed-text-v1.5/resolve/main/onnx/model.onnx"
+    sha256 "147d5aa88c2101237358e17796cf3a227cead1ec304ec34b465bb08e9d952965"
+  end
+
+  resource "nomic-embed-text-v1.5-tokenizer" do
+    url "https://huggingface.co/nomic-ai/nomic-embed-text-v1.5/resolve/main/tokenizer.json"
+    sha256 "d241a60d5e8f04cc1b2b3e9ef7a4921b27bf526d9f6050ab90f9267a1f9e5c66"
+  end
+
+  resource "all-minilm-l6-v2-model" do
+    url "https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/onnx/model.onnx"
+    sha256 "6fd5d72fe4589f189f8ebc006442dbb529bb7ce38f8082112682524616046452"
+  end
+
+  resource "all-minilm-l6-v2-tokenizer" do
+    url "https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/tokenizer.json"
+    sha256 "be50c3628f2bf5bb5e3a7f17b1f74611b2561a3a27eeab05e5aa30f411572037"
+  end
+
+  resource "t5-small-encoder" do
+    url "https://huggingface.co/optimum/t5-small/resolve/main/encoder_model.onnx"
+    sha256 "41d326633f1b85f526508cc0db78a5d40877c292c1b6dccae2eacd7d2a53480d"
+  end
+
+  resource "t5-small-decoder" do
+    url "https://huggingface.co/optimum/t5-small/resolve/main/decoder_model.onnx"
+    sha256 "0a1451011d61bcc796a87b7306c503562e910f110f884d0cc08532972c2cc584"
+  end
+
+  resource "t5-small-tokenizer" do
+    url "https://huggingface.co/optimum/t5-small/resolve/main/tokenizer.json"
+    sha256 "5f0ed8ab5b8cfa9812bb73752f1d80c292e52bcf5a87a144dc9ab2d251056cbb"
+  end
+
+  resource "t5-small-tokenizer-config" do
+    url "https://huggingface.co/optimum/t5-small/resolve/main/tokenizer_config.json"
+    sha256 "4969f8d76ef05a16553bd2b07b3501673ae8d36972aea88a0f78ad31a3ff2de9"
+  end
+
+  resource "t5-small-config" do
+    url "https://huggingface.co/optimum/t5-small/resolve/main/config.json"
+    sha256 "d112428e703aa7ea0d6b17a77e9739fcc15b87653779d9b7942d5ecbc61c00ed"
+  end
+
+  resource "provision" do
+    url "https://github.com/xDarkicex/openclaw-memory-libravdb/releases/download/v__VERSION__/provision.sh"
+    sha256 "__SHA256_PROVISION__"
+  end
+
   def install
     bin.install Dir["libravdbd*"].first => "libravdbd"
+
+    models_dir = prefix/"models"
+    runtime_dir = models_dir/"onnxruntime"
+    nomic_dir = models_dir/"nomic-embed-text-v1.5"
+    minilm_dir = models_dir/"all-minilm-l6-v2"
+    t5_dir = models_dir/"t5-small"
+
+    runtime_dir.mkpath
+    nomic_dir.mkpath
+    minilm_dir.mkpath
+    t5_dir.mkpath
+
+    resource("onnxruntime").stage do
+      # Homebrew may auto-strip the top-level dir from the tgz
+      subdir = Dir["onnxruntime-*"].first
+      if subdir
+        cp_r "#{subdir}/.", runtime_dir
+      else
+        cp_r ".", runtime_dir
+      end
+    end
+
+    resource("nomic-embed-text-v1.5-model").stage do
+      cp "model.onnx", nomic_dir/"model.onnx"
+    end
+    resource("nomic-embed-text-v1.5-tokenizer").stage do
+      cp "tokenizer.json", nomic_dir/"tokenizer.json"
+    end
+    write_embedding_manifest(nomic_dir, "nomic-embed-text-v1.5", 768)
+
+    resource("all-minilm-l6-v2-model").stage do
+      cp "model.onnx", minilm_dir/"model.onnx"
+    end
+    resource("all-minilm-l6-v2-tokenizer").stage do
+      cp "tokenizer.json", minilm_dir/"tokenizer.json"
+    end
+    write_embedding_manifest(minilm_dir, "all-minilm-l6-v2", 384)
+
+    resource("t5-small-encoder").stage do
+      cp "encoder_model.onnx", t5_dir/"encoder_model.onnx"
+    end
+    resource("t5-small-decoder").stage do
+      cp "decoder_model.onnx", t5_dir/"decoder_model.onnx"
+    end
+    resource("t5-small-tokenizer").stage do
+      cp "tokenizer.json", t5_dir/"tokenizer.json"
+    end
+    resource("t5-small-tokenizer-config").stage do
+      cp "tokenizer_config.json", t5_dir/"tokenizer_config.json"
+    end
+    resource("t5-small-config").stage do
+      cp "config.json", t5_dir/"config.json"
+    end
+    write_summarizer_manifest(t5_dir, "t5-small")
+
+    resource("provision").stage do
+      libexec.install "provision.sh"
+    end
+    chmod 0755, libexec/"provision.sh"
+  end
+
+  def post_install
+    (var/"clawdb").mkpath
+    (var/"clawdb/run").mkpath
+  end
+
+  def caveats
+    <<~EOS
+      libravdbd requires ONNX embedding models to function.  Models are
+      automatically provisioned during `brew install`.  To re-provision
+      or repair assets manually:
+
+        #{libexec}/provision.sh --target #{prefix}/models
+
+      Data directory:   #{var}/clawdb
+      Database file:    #{var}/clawdb/data.libravdb
+      Socket directory: #{var}/clawdb/run
+    EOS
+  end
+
+  private
+
+  def write_embedding_manifest(dir, profile, dimensions)
+    File.write(dir/"embedding.json", <<~JSON)
+      {
+        "backend": "onnx-local",
+        "profile": "#{profile}",
+        "family": "#{profile}",
+        "model": "model.onnx",
+        "tokenizer": "tokenizer.json",
+        "dimensions": #{dimensions},
+        "normalize": true,
+        "inputNames": ["input_ids", "attention_mask", "token_type_ids"],
+        "outputName": "last_hidden_state",
+        "pooling": "mean",
+        "addSpecialTokens": true
+      }
+    JSON
+  end
+
+  def write_summarizer_manifest(dir, profile)
+    File.write(dir/"summarizer.json", <<~JSON)
+      {
+        "backend": "onnx-local",
+        "profile": "#{profile}",
+        "family": "#{profile}",
+        "encoder": "encoder_model.onnx",
+        "decoder": "decoder_model.onnx",
+        "tokenizer": "tokenizer.json",
+        "maxContextTokens": 512
+      }
+    JSON
   end
 
   service do
     run [opt_bin/"libravdbd", "serve"]
-    environment_variables LIBRAVDB_RPC_ENDPOINT: "unix:#{ENV["HOME"]}/.clawdb/run/libravdb.sock"
+    environment_variables LIBRAVDB_RPC_ENDPOINT: "unix:#{var}/clawdb/run/libravdb.sock",
+                          LIBRAVDB_DB_PATH: "#{var}/clawdb/data.libravdb",
+                          LIBRAVDB_ONNX_RUNTIME: "#{opt_prefix}/models/onnxruntime/lib/libonnxruntime.dylib",
+                          LIBRAVDB_SUMMARIZER_BACKEND: "bundled"
     keep_alive true
-    working_dir ENV["HOME"]
+    working_dir var/"clawdb"
   end
 
   test do

package/packaging/launchd/com.xdarkicex.libravdbd.plist

@@ -13,6 +13,12 @@
     <dict>
       <key>LIBRAVDB_RPC_ENDPOINT</key>
       <string>unix:__HOME__/.clawdb/run/libravdb.sock</string>
+      <key>LIBRAVDB_DB_PATH</key>
+      <string>__HOME__/.clawdb/data</string>
+      <key>LIBRAVDB_ONNX_RUNTIME</key>
+      <string>__ONNX_RUNTIME_LIB__</string>
+      <key>LIBRAVDB_SUMMARIZER_BACKEND</key>
+      <string>bundled</string>
     </dict>
     <key>RunAtLoad</key>
     <true/>

package/src/cli.ts

@@ -9,6 +9,7 @@ type StatusResult = {
   message?: string;
   turnCount?: number;
   memoryCount?: number;
+  lifecycleHintCount?: number;
   gatingThreshold?: number;
   abstractiveReady?: boolean;
   embeddingProfile?: string;
@@ -25,9 +26,18 @@ type ExportResult = {
 
 type CliOptionBag = {
   userId?: string;
+  sessionId?: string;
+  limit?: string | number;
   yes?: boolean;
 };
 
+type JournalResult = {
+  results?: Array<{
+    id: string;
+    metadata: Record<string, unknown>;
+  }>;
+};
+
 type CliCommand = {
   commands?: CliCommand[];
   command(name: string): CliCommand;
@@ -74,6 +84,12 @@ export function registerMemoryCli(
         .description("Stream stored memories as newline-delimited JSON");
       exportCmd.option("--user-id <userId>", "Restrict export to a single user namespace");
       exportCmd.action((opts) => void runExport(runtime, opts, logger));
+
+      const journal = ensureCommand(root, "journal")
+        .description("Inspect internal lifecycle journal hints");
+      journal.option("--session-id <sessionId>", "Restrict journal entries to one session id");
+      journal.option("--limit <limit>", "Maximum journal entries to show");
+      journal.action((opts) => void runJournal(runtime, opts, logger));
     },
     {
       descriptors: [
@@ -108,6 +124,7 @@ async function runStatus(runtime: PluginRuntime, cfg: PluginConfig, logger: Logg
       Sidecar: status.ok ? "running" : "down",
       "Turns stored": status.turnCount ?? 0,
       "Memories stored": status.memoryCount ?? 0,
+      "Lifecycle hints": status.lifecycleHintCount ?? 0,
       "Gate threshold": status.gatingThreshold ?? cfg.ingestionGateThreshold ?? 0.35,
       "Abstractive model": status.abstractiveReady ? "ready" : "not provisioned",
       "Embedding profile": status.embeddingProfile ?? "unknown",
@@ -119,6 +136,7 @@ async function runStatus(runtime: PluginRuntime, cfg: PluginConfig, logger: Logg
       Sidecar: "down",
       "Turns stored": "n/a",
       "Memories stored": "n/a",
+      "Lifecycle hints": "n/a",
       "Gate threshold": cfg.ingestionGateThreshold ?? 0.35,
       "Abstractive model": "unknown",
       "Embedding profile": "unknown",
@@ -169,6 +187,22 @@ async function runExport(runtime: PluginRuntime, opts: CliOptionBag | undefined,
   }
 }
 
+async function runJournal(runtime: PluginRuntime, opts: CliOptionBag | undefined, logger: LoggerLike): Promise<void> {
+  try {
+    const rpc = await runtime.getRpc();
+    const result = await rpc.call<JournalResult>("list_lifecycle_journal", {
+      sessionId: opts?.sessionId?.trim() || undefined,
+      limit: normalizeLimit(opts?.limit),
+    });
+    for (const record of result.results ?? []) {
+      stdout.write(`${JSON.stringify(record)}\n`);
+    }
+  } catch (error) {
+    logger.error(`LibraVDB journal lookup failed: ${formatError(error)}`);
+    process.exitCode = 1;
+  }
+}
+
 async function confirm(prompt: string): Promise<boolean> {
   const rl = createInterface({ input: stdin, output: stdout });
   try {
@@ -186,6 +220,19 @@ function formatError(error: unknown): string {
   return String(error);
 }
 
+function normalizeLimit(limit: string | number | undefined): number | undefined {
+  if (typeof limit === "number" && Number.isFinite(limit) && limit > 0) {
+    return Math.floor(limit);
+  }
+  if (typeof limit === "string") {
+    const parsed = Number.parseInt(limit, 10);
+    if (Number.isFinite(parsed) && parsed > 0) {
+      return parsed;
+    }
+  }
+  return undefined;
+}
+
 type CliRegistrar = {
   registerCli?(
     builder: (ctx: { program: CliProgram }) => void,