@xdarkicex/openclaw-memory-libravdb 1.8.0 → 1.8.1

package/README.md

@@ -144,19 +144,53 @@ If your service runs elsewhere, set `sidecarPath`:
 
 ## Highlights
 
-- **Unified Cognitive Scoring** - moves beyond standard semantic search by mathematically blending cosine similarity with frequency, recency, authored salience, and cognitive authority composite weights (`ω(c)`).
-- **Topological Causal Graphs** - internally models temporal memory chains via directed acyclic graphs (`WhyIDs`), injecting causal proximity into retrieval scoring to anticipate temporally connected context.
-- **Zero-GC Slab Allocation** - manages model tensor and inference data via a custom contiguous slab allocator (`slabby`), completely bypassing Go garbage collection pauses during high-throughput memory assembly.
-- **Deontic & Salience Retrieval** - applies structural authority weightings and deontic logic rules to ensure critical behavioral constraints mathematically outrank conversational chatter.
-- **Matryoshka Representation Learning** - natively supports dynamically tiered embedding dimensions (e.g., slicing 768d vectors down to 64d) for ultra-fast cascading coarse search followed by precision reranking.
-- **Cognitive Routing Circuit Breakers** - strictly monitors remote endpoint health via stateful circuit breakers that trip and safely auto-disable complex ML routing during downstream outages, preserving foundational search uptime.
-- **Zero-ML Local Compaction** - evaluates contextual gating thresholds to execute purely localized session summarization and compaction cycles natively within the vector service.
-- **True multi-tenancy** - routes multiple OpenClaw agents to strictly isolated, per-agent vector databases within a single lightweight vector service process.
-- **Zero-copy caching** - shares a memory-mapped, cross-tenant embedding cache across all active agents to keep hardware utilization incredibly low.
-- **Three memory scopes** - keeps active session, durable user, and global memory separate.
-- **Local-first inference** - uses local embedding paths by default, with optional remote model configurations.
-- **Operational tooling** - provides a dedicated CLI (`libravdbd status`, `migrate`, `tenant evict`) for live observability and safe health management without interrupting active sessions.
-- **Explicit service lifecycle** - the npm/OpenClaw package stays connect-only; `libravdbd` is installed and supervised separately over a secure gRPC transport.
+### Why LibraVDB over other memory plugins
+
+- **Truly local.** All embedding, search, and compaction runs on your hardware through a dedicated vector service. No cloud API calls, no data leaving your machine, no subscription fees. Works offline.
+- **Handles long conversations.** Sessions with hundreds of turns are automatically compacted into searchable summaries. The agent can recall what was discussed in turn 5 even when you're on turn 200 — without blowing the context window.
+- **Never forgets a constraint.** Behavioral rules, preferences, and operating boundaries ("always use TLS", "prefers dark mode") are automatically detected and surfaced higher in recall than conversational noise. The agent can ask "what are my constraints?" and get a surgical answer.
+- **Automatic contradiction detection.** When you say "my email changed to jeff@anthropic.com", the old email is automatically marked as outdated — no manual cleanup, no stale facts confusing the agent.
+- **BM25 + vector hybrid search.** Lexical matching (exact identifiers, file paths, error codes) is fused with semantic similarity. A query for `docker-compose.yml` finds the file even if you described it as "the container config."
+- **Summary recall with expansion tools.** Compacted conversation history can be explored without flooding context. `memory_describe` peeks at what a summary covers; `memory_expand` drills into specifics; `memory_grep` searches by pattern. The agent decides how deep to go.
+- **Subagent-safe expansion.** When a summary is too large to expand directly, `memory_expand` enforces a token budget and delegates to a sub-agent — protecting the main agent's context window.
+- **Predictive memory.** The vector service pre-computes what the agent is likely to ask next after each turn, injecting relevant context before the model even sees the prompt.
+- **Three memory scopes.** Session memory (current conversation), user memory (everything you've ever told the agent), and global memory (shared across users) are kept separate. Searches can target specific scopes.
+- **Cognitive kind and signal filters.** Memories are classified as identity, fact, preference, constraint, decision, or episode. `memory_search(kind="constraint")` returns only operating boundaries — no conversational noise.
+- **True multi-tenancy.** Isolated per-agent vector databases within a single vector service process. Each agent sees only its own data.
+- **Memory-mapped embedding cache.** Frequently embedded text is cached in a file-backed mmap region that survives daemon restarts. Cold starts are faster, repeat queries are instant.
+- **Pluggable summarization backend.** The vector service's extractive summarization can replace LLM-based compaction — zero tokens burned on summarization.
+- **Local-first inference.** GGUF, ONNX, or remote embedding backends. Hardware-native acceleration on Apple Silicon and NVIDIA. No cloud required.
+- **Operational CLI.** `libravdbd status`, `health`, `search`, `tenant evict`, `migrate` — live observability and management without interrupting active sessions.
+
+### Technical Architecture
+
+- **Unified Cognitive Scoring** — mathematically blends cosine similarity with frequency, recency, authored salience, and cognitive authority composite weights (`ω(c)`).
+- **Section 7 Two-Pass Retrieval** — coarse cascade search (coarse top-K) followed by precision reranking (second-pass top-K) with hop expansion and temporal comparison profiling.
+- **BM25 + Vector RRF Fusion** — lexical BM25 scoring fused with vector similarity via Reciprocal Rank Fusion across all 11 recall paths.
+- **Content-Addressed Summaries** — deterministic SHA256-based summary IDs: same inputs produce identical IDs across crashes and retries.
+- **Structured Eviction Cues** — ~60-token deterministic metadata pointers on summary records (anchors, decisions, constraints, signal counts) — no LLM needed.
+- **Topological Causal Graphs** — temporal memory chains via directed acyclic graphs (`WhyIDs`), injecting causal proximity into retrieval scoring.
+- **Zero-GC Slab Allocation** — manages model tensor and inference data via a custom contiguous slab allocator (`slabby`), bypassing Go garbage collection pauses.
+- **Deontic & Salience Retrieval** — structural authority weightings and deontic logic rules ensure critical behavioral constraints mathematically outrank conversational chatter.
+- **Matryoshka Representation Learning** — dynamically tiered embedding dimensions (e.g., slicing 768d vectors down to 64d) for cascading coarse search followed by precision reranking.
+- **Cognitive Routing Circuit Breakers** — stateful circuit breakers on remote endpoints, auto-disabling complex ML routing during outages while preserving foundational search.
+- **Zero-ML Local Compaction** — purely localized session summarization and compaction cycles natively within the vector service. L1-L8 pipeline with deterministic state skeleton.
+- **Anchor-Based Contradiction Detection** — regex anchor extraction with Jaccard dedup and automatic `MarkSuperseded` — zero LLM overhead.
+- **Access Frequency in Omega** — `log2(accessCount+1)/10` term in the authority composite: frequently-retrieved memories surface higher without dominating relevance.
+- **True multi-tenancy** — strictly isolated, per-agent vector databases within a single lightweight vector service process.
+- **Zero-copy caching** — memory-mapped cross-tenant embedding cache across all active agents. Tenant-scoped keys prevent cross-tenant collision.
+- **Three memory scopes** — active session, durable user, and global memory kept separate.
+- **Local-first inference** — GGUF, ONNX, or remote embedding backends. Hardware-native acceleration on Apple Silicon and NVIDIA.
+- **Pluggable compaction backend** — exposes the vector service's extractive summarization as an OpenClaw `CompactionProvider` — replaces LLM summarization.
+- **Operational tooling** — dedicated CLI (`libravdbd status`, `health`, `search`, `migrate`, `tenant evict`) for live observability.
+- **Half-Life Decay per Cognitive Kind** — each memory kind decays at its own rate: identity, constraint, and decision have infinite half-life (permanent); facts decay over 180 days; preferences over 365 days. Mathematical support accumulation prevents thrashing.
+- **Deterministic State Skeleton (L8)** — extracts structured decisions, constraints, and next steps from raw turns using pure heuristics — no LLM call needed. Line-level scoring with commitment-verb and future-intent detection.
+- **Deterministic Tool Output Compression** — 3-phase compression of tool outputs before summarization: JSON key sampling, log-line deduplication (FNV-64a), and fenced-block tagging. Reduces token pressure without losing deontic markers.
+- **Seven Budget Channels** — waterfall token allocation across retrieval floor, mandatory continuity tail, hard-authored items, elevated guidance, soft-authored items, retrieval remainder, and recovery reserve. Each channel has its own budget fraction.
+- **Temporal Comparison Profiling** — witness scoring with diachronicity detection for "how did this change?" queries. Slot decomposition, discriminative membership, and position-weighted specificity.
+- **Merkle Chain Ingest** — content-hash-based session manifest with cursor reconciliation between plugin and vector service. Guarantees idempotent ingestion across crashes and retries.
+- **Nonce-Chaining HMAC Auth** — per-request challenge-response authentication with single-use cryptographic nonces. Supports mTLS for secure multi-machine deployments.
+- **Explicit service lifecycle** — the npm/OpenClaw package stays connect-only; `libravdbd` is installed and supervised separately over a secure gRPC transport.
 
 ## Embedding Backend Providers
 
@@ -193,11 +227,11 @@ openclaw memory journal --limit 50
 openclaw memory dream-promote --user-id <userId> --dream-file ~/DREAMS.md
 ```
 
-### Vector Service CLI (libravdbd v1.5.0+)
+### Vector Service CLI (libravdbd v1.6.0+)
 
 ```bash
 # Service health and status
-libravdbd status                    # tenants, cache, DB sizes
+libravdbd status                    # tenants, cache, DB sizes, CPU load
 libravdbd health                    # OK/UNHEALTHY
 
 # Search tenant memory (same collections memory_search queries)

package/dist/index.js

@@ -36020,6 +36020,27 @@ var MEMORY_GET_SCHEMA = {
 function createLibraVdbMemoryTools(getClient, cfg, logger = console) {
   const bridge = buildMemoryRuntimeBridge(getClient, cfg);
   const managers = /* @__PURE__ */ new Map();
+  const turnSearchKeys = /* @__PURE__ */ new Map();
+  const TURN_SEARCH_MAX_KEYS = 500;
+  function dedupKey(sessionKey, query) {
+    return `${sessionKey}:${query.toLowerCase().replace(/\s+/g, " ").trim().slice(0, 80)}`;
+  }
+  function isDuplicateSearch(sessionKey, query) {
+    if (!sessionKey) return false;
+    const key = dedupKey(sessionKey, query);
+    const keys = turnSearchKeys.get(sessionKey);
+    if (!keys) {
+      turnSearchKeys.set(sessionKey, /* @__PURE__ */ new Set([key]));
+      if (turnSearchKeys.size > TURN_SEARCH_MAX_KEYS) {
+        const oldest = turnSearchKeys.keys().next().value;
+        if (oldest !== void 0) turnSearchKeys.delete(oldest);
+      }
+      return false;
+    }
+    if (keys.has(key)) return true;
+    keys.add(key);
+    return false;
+  }
   async function getManager(ctx, purpose) {
     const key = managerCacheKey(ctx);
     let manager = managers.get(key);
@@ -36045,6 +36066,13 @@ function createLibraVdbMemoryTools(getClient, cfg, logger = console) {
         execute: async (_toolCallId, rawParams) => {
           const params = asToolParamsRecord(rawParams);
           const query = readRequiredStringParam(params, "query");
+          const sessionKey = ctx.sessionKey ?? "";
+          if (isDuplicateSearch(sessionKey, query)) {
+            return jsonToolResult({
+              results: [],
+              error: `Duplicate search blocked. You already searched this turn \u2014 use the previous results. Do not call memory_search again.`
+            });
+          }
           const corpus = readMemoryCorpus(params.corpus);
           const kind = typeof params.kind === "string" ? params.kind : void 0;
           const signals = Array.isArray(params.signals) ? params.signals.filter((s) => typeof s === "string") : void 0;

package/dist/memory-tools.js

@@ -67,6 +67,34 @@ const MEMORY_GET_SCHEMA = {
 export function createLibraVdbMemoryTools(getClient, cfg, logger = console) {
     const bridge = buildMemoryRuntimeBridge(getClient, cfg);
     const managers = new Map();
+    // Turn-scoped search dedup: blocks repeated searches within the same turn.
+    // The model sometimes loops memory_search with slight query variations;
+    // this enforces "once per turn" at the tool level, not just the prompt.
+    const turnSearchKeys = new Map();
+    const TURN_SEARCH_MAX_KEYS = 500;
+    function dedupKey(sessionKey, query) {
+        return `${sessionKey}:${query.toLowerCase().replace(/\s+/g, " ").trim().slice(0, 80)}`;
+    }
+    function isDuplicateSearch(sessionKey, query) {
+        if (!sessionKey)
+            return false;
+        const key = dedupKey(sessionKey, query);
+        const keys = turnSearchKeys.get(sessionKey);
+        if (!keys) {
+            turnSearchKeys.set(sessionKey, new Set([key]));
+            // Prune stale entries.
+            if (turnSearchKeys.size > TURN_SEARCH_MAX_KEYS) {
+                const oldest = turnSearchKeys.keys().next().value;
+                if (oldest !== undefined)
+                    turnSearchKeys.delete(oldest);
+            }
+            return false;
+        }
+        if (keys.has(key))
+            return true;
+        keys.add(key);
+        return false;
+    }
     async function getManager(ctx, purpose) {
         const key = managerCacheKey(ctx);
         let manager = managers.get(key);
@@ -95,6 +123,13 @@ export function createLibraVdbMemoryTools(getClient, cfg, logger = console) {
                 execute: async (_toolCallId, rawParams) => {
                     const params = asToolParamsRecord(rawParams);
                     const query = readRequiredStringParam(params, "query");
+                    const sessionKey = ctx.sessionKey ?? "";
+                    if (isDuplicateSearch(sessionKey, query)) {
+                        return jsonToolResult({
+                            results: [],
+                            error: `Duplicate search blocked. You already searched this turn — use the previous results. Do not call memory_search again.`,
+                        });
+                    }
                     const corpus = readMemoryCorpus(params.corpus);
                     const kind = typeof params.kind === "string" ? params.kind : undefined;
                     const signals = Array.isArray(params.signals) ? params.signals.filter((s) => typeof s === "string") : undefined;

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.8.0",
+  "version": "1.8.1",
   "kind": [
     "memory",
     "context-engine"

package/package.json

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