@xdarkicex/openclaw-memory-libravdb 1.6.10 → 1.6.12

package/dist/dream-promotion.d.ts

@@ -42,4 +42,5 @@ export declare function promoteDreamDiaryFile(client: LibravDBClient, opts: {
     sourceMtimeMs?: number;
 }): Promise<DreamPromotionResult>;
 export declare function parseDreamPromotionCandidates(text: string): DreamPromotionCandidate[];
+export declare function normalizeDiaryPath(value?: string): string;
 export {};

package/dist/dream-promotion.js

@@ -279,7 +279,7 @@ function parseHeading(value) {
     return normalizeSectionName(match[2] ?? "");
 }
 function isPromotionSection(section) {
-    return section.includes("deep sleep") || section.includes("promot") || section.includes("dream");
+    return /^(?:deep sleep|dream promotion(?: candidates?)?|promotion candidates?|promote candidates?)$/.test(section);
 }
 function parseBulletCandidate(line) {
     const match = /^\s*[-*+]\s+(.+)$/.exec(line);
@@ -357,18 +357,23 @@ function parseInteger(value) {
 function normalizeSectionName(value) {
     return value.trim().toLowerCase().replace(/\s+/g, " ");
 }
-function normalizeDiaryPath(value) {
+export function normalizeDiaryPath(value) {
     const trimmed = value?.trim();
     if (!trimmed) {
         return "";
     }
+    // Expand ~ to home directory before resolving. path.resolve does not
+    // expand tilde, so "~/dreams.md" would resolve to "<cwd>/~/dreams.md".
+    const expanded = trimmed.startsWith("~")
+        ? path.join(os.homedir(), trimmed.slice(1))
+        : trimmed;
     // Reject traversal components — even though path.resolve collapses them,
     // their presence signals an attempt to escape intended boundaries.
-    const segments = trimmed.split(/[/\\]+/);
+    const segments = expanded.split(/[/\\]+/);
     if (segments.some((s) => s === "..")) {
         throw new Error(`dream diary path must not contain ".." traversal: ${trimmed}`);
     }
-    const resolved = path.resolve(trimmed);
+    const resolved = path.resolve(expanded);
     // Restrict to known-safe locations to prevent arbitrary file reads.
     // Allowed roots: home directory and the configured OpenClaw state dir.
     const allowedRoots = [

package/dist/index.js

@@ -25601,7 +25601,7 @@ function parseHeading(value) {
   return normalizeSectionName(match[2] ?? "");
 }
 function isPromotionSection(section) {
-  return section.includes("deep sleep") || section.includes("promot") || section.includes("dream");
+  return /^(?:deep sleep|dream promotion(?: candidates?)?|promotion candidates?|promote candidates?)$/.test(section);
 }
 function parseBulletCandidate(line) {
   const match = /^\s*[-*+]\s+(.+)$/.exec(line);
@@ -25684,13 +25684,14 @@ function normalizeDiaryPath(value) {
   if (!trimmed) {
     return "";
   }
-  const segments = trimmed.split(/[/\\]+/);
+  const expanded = trimmed.startsWith("~") ? path.join(os.homedir(), trimmed.slice(1)) : trimmed;
+  const segments = expanded.split(/[/\\]+/);
   if (segments.some((s) => s === "..")) {
     throw new Error(
       `dream diary path must not contain ".." traversal: ${trimmed}`
     );
   }
-  const resolved = path.resolve(trimmed);
+  const resolved = path.resolve(expanded);
   const allowedRoots = [
     os.homedir(),
     process.env.OPENCLAW_STATE_DIR
@@ -36796,14 +36797,15 @@ function extractHost(target) {
   const sep = withoutDns.lastIndexOf(":");
   return sep > 0 ? withoutDns.slice(0, sep) : withoutDns;
 }
-function loadSecretFromEnv() {
+function loadSecretFromEnv(logger) {
   const secret = process.env.LIBRAVDB_AUTH_SECRET?.trim();
   if (secret) return secret;
   const secretPath = process.env.LIBRAVDB_AUTH_SECRET_FILE;
   if (secretPath) {
     try {
       return fs3.readFileSync(secretPath, "utf8").trim() || void 0;
-    } catch {
+    } catch (error2) {
+      logger?.warn?.(`LibraVDB: failed to read auth secret file "${secretPath}": ${formatError(error2)}`);
       return void 0;
     }
   }

package/dist/libravdb-client.d.ts

@@ -1,5 +1,6 @@
 import type { Interceptor } from "@connectrpc/connect";
 import type { PartialMessage } from "@bufbuild/protobuf";
+import type { LoggerLike } from "./types.js";
 import type { AfterTurnKernelRequest, AfterTurnKernelResponse, AssembleContextInternalRequest, AssembleContextInternalResponse, BootstrapSessionKernelRequest, BootstrapSessionKernelResponse, CompactSessionRequest, CompactSessionResponse, DeleteAuthoredDocumentRequest, DeleteAuthoredDocumentResponse, DreamPromotionResponse, ExportMemoryRequest, ExportMemoryResponse, FlushNamespaceRequest, FlushNamespaceResponse, FlushRequest, FlushResponse, HealthRequest, HealthResponse, IngestMarkdownDocumentRequest, IngestMarkdownDocumentResponse, IngestMessageKernelRequest, IngestMessageKernelResponse, ListCollectionRequest, ListCollectionResponse, ListLifecycleJournalRequest, ListLifecycleJournalResponse, MarkMemorySupersededRequest, MarkMemorySupersededResponse, MemoryStatusRequest, MemoryStatusResponse, PromoteDreamEntriesRequest, RankCandidatesRequest, RankCandidatesResponse, RebuildIndexRequest, RebuildIndexResponse, ReindexAuthoredDocumentRequest, ReindexAuthoredDocumentResponse, SearchTextCollectionsRequest, SearchTextRequest, SearchTextResponse, SessionLifecycleHintRequest, SessionLifecycleHintResponse } from "@xdarkicex/libravdb-contracts";
 export interface LibravDBClientOptions {
     endpoint?: string;
@@ -56,5 +57,5 @@ export declare class LibravDBClient {
     rankCandidates(req: PartialMessage<RankCandidatesRequest>): Promise<RankCandidatesResponse>;
     close(): void;
 }
-export declare function loadSecretFromEnv(): string | undefined;
+export declare function loadSecretFromEnv(logger?: LoggerLike): string | undefined;
 export {};

package/dist/libravdb-client.js

@@ -3,6 +3,7 @@ import { createGrpcTransport } from "@connectrpc/connect-node";
 import { LibravDB } from "@xdarkicex/libravdb-contracts/client";
 import { createHmac } from "node:crypto";
 import fs from "node:fs";
+import { formatError } from "./format-error.js";
 import net from "node:net";
 import os from "node:os";
 import path from "node:path";
@@ -279,7 +280,7 @@ function extractHost(target) {
     const sep = withoutDns.lastIndexOf(":");
     return sep > 0 ? withoutDns.slice(0, sep) : withoutDns;
 }
-export function loadSecretFromEnv() {
+export function loadSecretFromEnv(logger) {
     const secret = process.env.LIBRAVDB_AUTH_SECRET?.trim();
     if (secret)
         return secret;
@@ -288,7 +289,8 @@ export function loadSecretFromEnv() {
         try {
             return fs.readFileSync(secretPath, "utf8").trim() || undefined;
         }
-        catch {
+        catch (error) {
+            logger?.warn?.(`LibraVDB: failed to read auth secret file "${secretPath}": ${formatError(error)}`);
             return undefined;
         }
     }

package/docs/configuration.md

@@ -15,6 +15,8 @@ CPU when a provider is unavailable.
 | `grpcEndpoint` | string | — | gRPC kernel endpoint. See `grpcEndpointTlsMode` for credential control. |
 | `grpcEndpointTlsCa` | string | — | Path to CA certificate PEM file. Only needed for self-signed or private CA certs. Omit when using Let's Encrypt or cert-manager. |
 | `grpcEndpointTlsMode` | string | `"auto"` | gRPC credential mode. `"auto"`: loopback/unix → plaintext, remote → TLS. `"tls"`: always TLS. `"insecure"`: always plaintext. |
+| `grpcEndpointTlsClientCert` | string | — | Path to client certificate PEM for mTLS. Must be paired with `grpcEndpointTlsClientKey`. |
+| `grpcEndpointTlsClientKey` | string | — | Path to client private key PEM for mTLS. Must be paired with `grpcEndpointTlsClientCert`. |
 | `rpcTimeoutMs` | number | `30000` | Per-call timeout for service RPC (ms) |
 | `dbPath` | string | auto-named | Explicit DB path; when set bypasses model-specific naming |
 
@@ -56,6 +58,19 @@ Set `grpcEndpointTlsCa` to the path of the CA certificate PEM file:
 The daemon must be configured with matching TLS cert and key via
 `LIBRAVDB_GRPC_TLS_CERT` and `LIBRAVDB_GRPC_TLS_KEY`.
 
+**Remote daemon with mTLS (mutual TLS):**
+When the daemon requires client certificate authentication, set both
+`grpcEndpointTlsClientCert` and `grpcEndpointTlsClientKey` (they must both
+be present or both be omitted):
+```json
+{
+  "grpcEndpoint": "tcp:yourdaemon.internal:50051",
+  "grpcEndpointTlsCa": "/etc/certs/ca.pem",
+  "grpcEndpointTlsClientCert": "/etc/certs/client-cert.pem",
+  "grpcEndpointTlsClientKey": "/etc/certs/client-key.pem"
+}
+```
+
 **Local daemon with TLS enabled:**
 If the daemon has `LIBRAVDB_GRPC_TLS_CERT`/`LIBRAVDB_GRPC_TLS_KEY` set on a loopback
 address, explicitly set `grpcEndpointTlsMode: "tls"` to match:
@@ -147,11 +162,49 @@ The plugin exposes `ingestionGateThreshold` for host-side gating decisions:
 | `markdownIngestionObsidianInclude` | string[] | — | Obsidian glob include patterns |
 | `markdownIngestionObsidianExclude` | string[] | same defaults as above | Obsidian glob exclude patterns; defaults to the same set as generic markdown ingestion |
 | `markdownIngestionObsidianDebounceMs` | number | `150` | Obsidian debounce window |
+| `markdownIngestionSnapshotPath` | string | — | Path to snapshot file for generic markdown ingestion state |
+| `markdownIngestionObsidianSnapshotPath` | string | — | Path to snapshot file for Obsidian ingestion state |
 
 Configured markdown roots are ignored unless the matching enable flag is set to
 `true`. Set `markdownIngestionEnabled: true` for generic roots and
 `markdownIngestionObsidianEnabled: true` for Obsidian vault roots.
 
+## Continuity
+
+| Key | Type | Default | Notes |
+|---|---|---|---|
+| `continuityMinTurns` | number | — | Minimum conversation turns before continuity retrieval activates |
+| `continuityPriorContextTokens` | number | — | Token budget allocated to prior context in continuity retrieval |
+| `continuityTailBudgetTokens` | number | — | Token budget for tail-end context in continuity retrieval |
+
+## Recovery
+
+| Key | Type | Default | Notes |
+|---|---|---|---|
+| `recoveryFloorScore` | number | — | Minimum score floor for recovery-phase retrieval |
+| `recoveryMinConfidenceMean` | number | — | Minimum mean confidence threshold for recovery candidates |
+| `recoveryMinTopK` | number | — | Minimum number of top-K results required for recovery |
+
+## Section 7 scoring
+
+Two-pass retrieval scoring subsystem. These keys control the authority-weighted
+and recency-adjusted scoring pass that runs after the initial vector search.
+
+| Key | Type | Default | Notes |
+|---|---|---|---|
+| `section7Theta1` | number | — | Primary theta parameter for first-pass scoring |
+| `section7Kappa` | number | — | Kappa scaling factor for authority scoring |
+| `section7HopEta` | number | — | Eta decay for hop-distance scoring |
+| `section7HopThreshold` | number | — | Hop distance threshold for second-pass eligibility |
+| `section7CoarseTopK` | number | — | Top-K for coarse (first-pass) retrieval |
+| `section7SecondPassTopK` | number | — | Top-K for second-pass refined retrieval |
+| `section7AuthorityRecencyLambda` | number | — | Lambda for recency decay in authority scoring (commented out in code) |
+| `section7AuthorityRecencyWeight` | number | — | Weight for authority recency in combined score |
+| `section7AuthorityFrequencyWeight` | number | — | Weight for authority frequency in combined score |
+| `section7AuthorityAuthoredWeight` | number | — | Weight for authority authored signal in combined score |
+| `section7AuthoritySalienceWeight` | number | — | Weight for authority salience in combined score |
+| `section7RecencyAccessLambda` | number | — | Lambda for access-based recency decay |
+
 ## Dream promotion
 
 | Key | Type | Default | Notes |

package/docs/embedding-profiles.md

@@ -35,6 +35,34 @@ How it works:
 - The sidecar store persists an embedding fingerprint, so reopening an existing store with a different effective model profile will fail instead of silently mixing vector spaces.
 - `onnxDevice` is passed through as `LIBRAVDB_ONNX_DEVICE` for daemon versions that support execution-provider selection (`auto`, `cpu`, `cuda`, `coreml`, `directml`, `openvino`).
 
+## Store Compatibility and Upgrades
+
+The persisted embedding fingerprint is part of the database compatibility check.
+That is intentional: if a daemon opens a store with a different effective model
+profile, the safest outcome is to stop before mixing vector spaces.
+
+When updating `libravdbd`, keep the same effective embedding profile unless you
+intend to rebuild the store. The effective profile includes the profile family,
+dimensions, normalization setting, and any metadata supplied by the model
+manifest or daemon defaults.
+
+Legacy local setups can be more fragile than the current packaged profiles. For
+example, older `all-minilm-l6-v2` stores may fail to reopen after a daemon update
+if the daemon now computes different metadata for that local profile. This does
+not imply that current packaged `nomic-embed-text-v1.5` or
+`bge-small-en-v1.5` stores are incompatible; it means the old local profile must
+be treated as a separate vector space unless a migration path is provided.
+
+If a daemon update reports that the database format or embedding profile is
+incompatible:
+
+1. back up both the `.libravdb` file and its `.embedding.json` metadata file;
+2. either downgrade to the previous daemon that created the store, or move the
+   old store aside and let the new daemon initialize a fresh database;
+3. rebuild/reingest memories with the new effective embedding profile.
+
+Do not delete the old store until the replacement has been verified.
+
 Recommended usage:
 
 - `bundled` for the shipped default path, which uses `nomic-embed-text-v1.5`.

package/docs/installation.md

@@ -171,6 +171,30 @@ For foreground debugging:
 libravdbd serve
 ```
 
+### Incompatible database or embedding profile
+
+If the daemon exits with `database format is incompatible` or `database
+embedding profile is incompatible`, it is refusing to open a store whose saved
+format or embedding fingerprint differs from the current daemon settings. This
+fail-closed behavior protects the store from mixing incompatible vector spaces.
+
+Before changing anything, back up both files for the affected store:
+
+- the database file, such as `$HOME/.libravdbd/data_nomic-embed-text-v1_5.libravdb`
+- the adjacent `.embedding.json` metadata file
+
+Then choose one recovery path:
+
+- downgrade to the daemon version that created the store; or
+- move the old store aside, start the new daemon so it creates a fresh store,
+  and rebuild/reingest memories with the current embedding profile.
+
+This can affect legacy local profiles such as older `all-minilm-l6-v2` setups
+when daemon defaults or model metadata change across releases. It is not
+expected for stores that stay on the current packaged profiles and assets. See
+[Embedding Profiles](./embedding-profiles.md#store-compatibility-and-upgrades)
+for more detail.
+
 ### Hash mismatch
 
 Do not bypass a checksum mismatch. Delete the corrupt or stale asset and rerun

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "libravdb-memory",
   "name": "LibraVDB Memory",
   "description": "Persistent vector memory with three-tier hybrid scoring",
-  "version": "1.6.10",
+  "version": "1.6.12",
   "kind": [
     "memory",
     "context-engine"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xdarkicex/openclaw-memory-libravdb",
-  "version": "1.6.10",
+  "version": "1.6.12",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",