@xdarkicex/openclaw-memory-libravdb 1.10.13 → 1.10.14-beta.1

package/README.md

@@ -1,21 +1,69 @@
-# ♎ LibraVDB - Memory and Context Management
+# ♎ LibraVDB — Cognitive Memory Engine for OpenClaw
 
 <div align="center">
-  <img src="./docs/assets/libravdb-logo.svg" alt="LibraVDB" width="640">
+  <img src="./docs/assets/libravdb-logo.svg" alt="LibraVDB" width="480">
+
+  <p><strong>Local-first memory kernel with causal graph reasoning, identity tracking, and hard PII enforcement.</strong><br/>
+  <em>768-dim vector search • 6-tier cognitive classification • Zero-cloud guarantee</em></p>
+
+  <p>
+    <a href="https://www.npmjs.com/package/@xdarkicex/openclaw-memory-libravdb"><img src="https://img.shields.io/npm/v/%40xdarkicex%2Fopenclaw-memory-libravdb?label=release&color=5B21B6" alt="npm"></a>
+    <a href="https://github.com/xDarkicex/openclaw-memory-libravdb"><img src="https://img.shields.io/github/stars/xDarkicex/openclaw-memory-libravdb?style=social" alt="stars"></a>
+    <a href="https://discord.gg/DWn4BpRQAS"><img src="https://img.shields.io/badge/Discord-LibraVDB-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
+    <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License"></a>
+    <br>
+    <a href="https://github.com/xDarkicex/libravdbd"><img src="https://img.shields.io/badge/daemon-v1.9.3-00ADD8?logo=go&logoColor=white" alt="Daemon"></a>
+    <img src="https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white" alt="TS">
+    <img src="https://img.shields.io/badge/OpenClaw-2026.3%2B-111827" alt="OC">
+    <img src="https://img.shields.io/badge/K8s-ready-326CE5?logo=kubernetes&logoColor=white" alt="k8s">
+  </p>
 </div>
 
-<div align="center">
-  <a href="https://github.com/xDarkicex/libravdbd"><img src="https://img.shields.io/badge/Go-1.25%2B-00ADD8?logo=go&logoColor=white" alt="Go 1.25+"></a>
-  <a href="./package.json"><img src="https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white" alt="TypeScript 5.x"></a>
-  <a href="./openclaw.plugin.json"><img src="https://img.shields.io/badge/OpenClaw-memory%20plugin-111827" alt="OpenClaw memory plugin"></a>
-  <a href="https://www.npmjs.com/package/@xdarkicex/openclaw-memory-libravdb"><img src="https://img.shields.io/npm/v/%40xdarkicex%2Fopenclaw-memory-libravdb?label=release&color=5B21B6" alt="Release"></a>
-  <a href="https://discord.gg/DWn4BpRQAS"><img src="https://img.shields.io/badge/Discord-LibraVDB-5865F2?logo=discord&logoColor=white" alt="LibraVDB Discord"></a>
-</div>
+```mermaid
+graph TB
+    OC[OpenClaw Agent] -->|gRPC| PLUGIN[Plugin: context-engine + tools]
+    PLUGIN -->|gRPC + mTLS| DAEMON[libravdbd Memory Kernel]
+    DAEMON --> EMBED[GGUF / ONNX / Remote]
+    DAEMON --> COG[Causal Graph: BOSS + TE/LK + SAT]
+    EMBED --> DB[(Vector DB)]
+    COG --> GRAPH[(Causal DAG)]
+    PLUGIN --> AGENT[LLM Agent]
+```
+
+## 🚀 Quick Start
 
-`@xdarkicex/openclaw-memory-libravdb` is a local-first OpenClaw memory plugin
-backed by the `libravdbd` memory kernel. It replaces the lightweight default memory
-path with scoped session, user, and global memory; continuity-aware prompt
-assembly; durable recall; and kernel-owned compaction.
+```bash
+# 1. Install daemon (pick your OS)
+brew tap xDarkicex/homebrew-openclaw-libravdb-memory && brew install libravdbd && brew services start libravdbd   # macOS
+# apt install libravdbd                                                                                         # Linux
+# See Arch Linux instructions below                                                                             # Arch (AUR postponed)
+
+# 2. Install plugin
+openclaw plugins install @xdarkicex/openclaw-memory-libravdb
+
+# 3. Verify
+openclaw memory status
+```
+
+> ⚡ **Done.** Your agent has persistent vector memory, identity tracking, and causal graph reasoning.
+
+<details>
+<summary>🐳 Docker (30 seconds) · ☸️ Kubernetes</summary>
+
+```bash
+# Docker
+cd deploy && docker compose up -d
+
+# K8s with Helm
+helm install libravdbd ./deploy/helm/libravdbd
+
+# K8s with mTLS
+helm install libravdbd ./deploy/helm/libravdbd \
+  --set tls.enabled=true --set tls.cert=$(base64 -i server.crt) --set tls.key=$(base64 -i server.key)
+```
+
+Terraform modules for EKS/GKE/AKS: [`deploy/terraform/`](deploy/terraform/)
+</details>
 
 [Install](./docs/install.md) · [Full installation reference](./docs/installation.md) · [Architecture](./docs/architecture.md) · [Security](./docs/security.md) · [Performance and tuning](./docs/performance-and-tuning.md) · [Contributing](./docs/contributing.md)
 
@@ -57,10 +105,18 @@ sudo apt install libravdbd
 systemctl --user enable --now libravdbd
 ```
 
-**Linux (AUR)**
+**Linux (Arch — custom pacman repo)**
+
+AUR distribution is temporarily postponed due to the June 2026 AUR supply chain incident (new account registrations frozen). Use the official pacman repository instead:
 
 ```bash
-yay -S libravdbd-bin
+# Add the repo to /etc/pacman.conf:
+# [libravdbd]
+# SigLevel = Optional
+# Server = https://raw.githubusercontent.com/xDarkicex/aur-libravdbd-bin/main/$arch
+
+echo -e '\n[libravdbd]\nSigLevel = Optional\nServer = https://raw.githubusercontent.com/xDarkicex/aur-libravdbd-bin/main/$arch' | sudo tee -a /etc/pacman.conf
+sudo pacman -Sy libravdbd-bin
 systemctl --user enable --now libravdbd
 ```
 
@@ -142,6 +198,41 @@ If your service runs elsewhere, set `sidecarPath`:
 }
 ```
 
+## Docker & Kubernetes Deployment
+
+The daemon is K8-ready. Deployment files live in [`deploy/`](deploy/):
+
+| File | Use |
+|------|-----|
+| [`Dockerfile`](deploy/Dockerfile) | Production image (Alpine) — pulls the binary from GitHub releases |
+| [`docker-compose.yml`](deploy/docker-compose.yml) | Local dev / single-server: `docker compose up -d` |
+| [`helm/libravdbd/`](deploy/helm/libravdbd) | Full Helm chart — ConfigMap, PVC, Service, Deployment, mTLS support |
+
+```bash
+# Quick start with Docker
+cd deploy && docker compose up -d
+
+# K8s with Helm
+helm install libravdbd ./deploy/helm/libravdbd
+
+# K8s with mTLS
+helm install libravdbd ./deploy/helm/libravdbd \
+  --set tls.enabled=true \
+  --set tls.cert=$(base64 -i server.crt) \
+  --set tls.key=$(base64 -i server.key)
+```
+
+The image pulls pre-built binaries from [GitHub Releases](https://github.com/zephyr-systems/libravdbd/releases) — no build step needed. Supports `linux/amd64` and `linux/arm64`.
+
+**Terraform** modules for cloud deployment live in [`deploy/terraform/`](deploy/terraform/):
+
+| Provider | Directory | Use |
+|----------|-----------|-----|
+| AWS EKS | [`eks/`](deploy/terraform/eks) | `terraform apply -var cluster_name=my-cluster` |
+| GCP GKE | [`gke/`](deploy/terraform/gke) | `terraform apply -var project=my-project -var cluster_name=my-cluster` |
+| Azure AKS | [`aks/`](deploy/terraform/aks) | `terraform apply -var resource_group=my-rg -var cluster_name=my-cluster` |
+| Standalone VM | [`vm/`](deploy/terraform/vm) | EC2 + Docker, no k8s required |
+
 ## Highlights
 
 ### Why LibraVDB over other memory plugins
@@ -181,6 +272,51 @@ The daemon tracks **who you are** — not just what you said. Every speaker the
 - Cards participate in the causal graph (`memory_kind: "identity"`) — identity patterns detected by the cognitive scheduler at macro scale
 - `PredictiveContext` seeds the card node — BFS surfaces causally connected memories alongside identity
 
+### Bot Persona
+
+Define who the bot IS — personality, tone, boundaries, and behavior. The persona
+is stored as a user card (`__bot_persona__`) and injected at the top of every
+session as `<bot_persona>`.
+
+**Agent tools:**
+- `set_persona(persona)` — define or update the bot's personality. Prose format.
+  Empty string deletes the persona.
+- `get_persona()` — read the current persona.
+
+**Example personas:**
+
+```prose
+# Professional
+You are a senior software architect. You speak precisely, use correct
+terminology, and default to TypeScript patterns. You never apologize for
+being thorough. When asked a question, you give the answer plus the
+reasoning behind it.
+```
+
+```prose
+# Creative
+You are a playful creative assistant. You speak casually, use emoji freely,
+and default to brainstorming mode. You always offer 3-5 wild ideas before
+narrowing down. You never say "I can't" — you say "here's a different approach."
+```
+
+```prose
+# Minimalist
+You are a terse, no-nonsense assistant. You answer in as few words as
+possible. No greetings, no sign-offs, no fluff. Just the answer.
+If you don't know, you say "I don't know" — nothing else.
+```
+
+```prose
+# Character
+You are a 1920s detective. You call everyone "pal" or "doll." You use
+noir slang and describe things like a hardboiled novel. You're cynical
+but secretly have a heart of gold.
+```
+
+The persona is injected **before** the user card and rules at session start,
+so it acts as the foundational identity layer for the agent.
+
 ### PII Scrubbing & Hard Constraint Rules
 
 Agent replies are scanned for forbidden keywords before dispatch. Rules are stored
@@ -289,6 +425,13 @@ libravdbd search --tenant <key> --session <id> -k 10 "query"
 # Tenant management
 libravdbd tenant evict <key>        # force-close a tenant DB
 libravdbd migrate                   # run pending DB migrations
+
+# Database export (libravdbd v1.10.0+)
+libravdbd export                    # export all collections as JSON to stdout
+libravdbd export --tenant <key>     # export a specific tenant's data
+libravdbd export --collection <name># export a single collection
+libravdbd export --format jsonl     # newline-delimited JSON (one record per line)
+libravdbd export --output out.json  # write to file instead of stdout
 ```
 
 Use [Install](./docs/install.md) for service lifecycle commands and
@@ -611,3 +754,11 @@ service checkout. For the full source workflow, read [Development](./docs/develo
 - default macOS/Linux endpoint: `unix:$HOME/.libravdbd/run/libravdb.sock`
 - default Windows endpoint: `tcp:127.0.0.1:37421`
 
+
+---
+
+<div align="center">
+  <sub>Built with ♎ by <a href="https://github.com/xDarkicex">xDarkicex</a> — local-first, privacy-first, forever free.</sub>
+
+  [![Star History Chart](https://api.star-history.com/svg?repos=xDarkicex/openclaw-memory-libravdb&type=Date)](https://star-history.com/#xDarkicex/openclaw-memory-libravdb&Date)
+</div>

package/dist/context-engine.d.ts

@@ -12,7 +12,7 @@ type OpenClawCompatibleMessage = {
     id?: string;
     [key: string]: unknown;
 };
-type OpenClawCompatiblePromptAuthority = "preassembly_may_overflow";
+type OpenClawCompatiblePromptAuthority = "assembled" | "preassembly_may_overflow";
 type OpenClawCompatibleAssembleResult = {
     messages: OpenClawCompatibleMessage[];
     estimatedTokens: number;
@@ -31,7 +31,6 @@ type OpenClawCompatibleCompactResult = {
     reason?: string;
     result?: {
         summary?: string;
-        summaryText?: string;
         firstKeptEntryId?: string;
         tokensBefore: number;
         tokensAfter?: number;
@@ -83,7 +82,7 @@ export declare function normalizeAssembleResult(result: {
     estimatedTokens?: number;
     systemPromptAddition?: string;
     debug?: AssembleContextInternalResponse["debug"];
-}, sourceMessages?: OpenClawCompatibleMessage[]): OpenClawCompatibleAssembleResult;
+}, sourceMessages?: OpenClawCompatibleMessage[], promptAuthority?: OpenClawCompatiblePromptAuthority): OpenClawCompatibleAssembleResult;
 export declare function setSessionTrigger(sessionId: string, trigger: string | undefined): void;
 export declare function clearSessionTrigger(sessionId: string): void;
 export declare function consumeSubagentBudget(sessionKey: string, tokens: number): number;

package/dist/context-engine.js

@@ -107,7 +107,7 @@ function normalizeCompactResult(response, options = {}) {
     const threshold = options.threshold;
     const overBudget = threshold != null && tokensBefore >= threshold;
     const engineRefused = !didCompact && overBudget;
-    const tokensAfter = didCompact && typeof response?.tokensAfter === "number" && response.tokensAfter > 0
+    const tokensAfter = didCompact && typeof response?.tokensAfter === "number" && response.tokensAfter >= 0
         ? response.tokensAfter
         : undefined;
     return {
@@ -117,8 +117,7 @@ function normalizeCompactResult(response, options = {}) {
         result: {
             tokensBefore,
             ...(tokensAfter != null ? { tokensAfter } : {}),
-            ...(details.summaryMethod ? { summary: details.summaryMethod } : {}),
-            ...(details.summaryText ? { summaryText: details.summaryText } : {}),
+            ...(details.summaryText ? { summary: details.summaryText } : {}),
             details: { ...details, ...(threshold != null ? { threshold } : {}) },
         },
     };
@@ -215,6 +214,27 @@ function findLastUserMessageIndex(messages) {
     }
     return -1;
 }
+/**
+ * Selects one exact contiguous suffix from the OpenClaw transcript.
+ *
+ * The cut is moved backward to a user-message boundary so an assistant tool
+ * call and its tool results can never be separated by tail windowing. Message
+ * objects are returned untouched; daemon-normalized messages are never mapped
+ * back onto the provider transcript.
+ */
+function selectTurnAlignedSourceSuffix(messages, maxMessages) {
+    if (messages.length === 0)
+        return [];
+    let start = Math.max(0, messages.length - Math.max(1, Math.floor(maxMessages)));
+    while (start > 0 && messages[start]?.role !== "user") {
+        start -= 1;
+    }
+    if (messages[start]?.role !== "user") {
+        const firstUserIndex = messages.findIndex((message) => message.role === "user");
+        start = firstUserIndex >= 0 ? firstUserIndex : 0;
+    }
+    return messages.slice(start);
+}
 /**
  * Normalizes kernel content (string or block array) to a flat string.
  */
@@ -673,6 +693,43 @@ function trimMessagesToBudget(messages, tokenBudget) {
     }
     return [{ ...last, content: truncated }];
 }
+/**
+ * Trims a compacted source projection only at user-turn boundaries.
+ *
+ * The newest user turn is mandatory, even if it alone exceeds the budget:
+ * dropping part of an in-flight tool-call/result sequence is more dangerous
+ * than surfacing a truthful overflow. Older turns are kept only as a
+ * contiguous suffix and only when their complete bundle fits.
+ */
+function trimTurnAlignedSourceSuffixToBudget(messages, tokenBudget) {
+    if (messages.length === 0)
+        return [];
+    const userStarts = [];
+    for (let index = 0; index < messages.length; index += 1) {
+        if (messages[index]?.role === "user")
+            userStarts.push(index);
+    }
+    if (userStarts.length === 0) {
+        return messages;
+    }
+    const keptBundles = [];
+    let used = 0;
+    let bundleEnd = messages.length;
+    for (let index = userStarts.length - 1; index >= 0; index -= 1) {
+        const bundleStart = userStarts[index];
+        const bundle = messages.slice(bundleStart, bundleEnd);
+        const bundleCost = approximateMessagesTokens(bundle);
+        if (keptBundles.length > 0 && used + bundleCost > tokenBudget) {
+            break;
+        }
+        keptBundles.unshift(bundle);
+        used += bundleCost;
+        bundleEnd = bundleStart;
+        if (used >= tokenBudget)
+            break;
+    }
+    return keptBundles.flat();
+}
 /**
  * Bounds after-turn messages for ingest, trimming if over max tokens.
  */
@@ -720,6 +777,39 @@ function enforceTokenBudgetInvariant(result, tokenBudget) {
         estimatedTokens: Math.min(effectiveBudget, systemPromptTokens + trimmedEstimate),
     };
 }
+/**
+ * Enforces the model budget for a daemon-compacted projection without ever
+ * splitting the newest user/tool turn. The compacted system context and older
+ * complete turns yield budget before the live turn does.
+ */
+function enforceCompactedProjectionBudgetInvariant(result, tokenBudget) {
+    if (typeof tokenBudget !== "number" || !Number.isFinite(tokenBudget) || tokenBudget <= 0) {
+        return result;
+    }
+    const effectiveBudget = resolveEffectiveAssembleBudget(Math.max(1, Math.floor(tokenBudget)));
+    const approximateTotal = approximateTokenCount(result.systemPromptAddition) +
+        approximateMessagesTokens(result.messages);
+    if (result.estimatedTokens <= effectiveBudget && approximateTotal <= effectiveBudget) {
+        return result;
+    }
+    const lastUserIndex = findLastUserMessageIndex(result.messages);
+    const mandatoryMessages = lastUserIndex >= 0
+        ? result.messages.slice(lastUserIndex)
+        : result.messages;
+    const mandatoryTokens = approximateMessagesTokens(mandatoryMessages);
+    const systemPromptBudget = Math.max(0, effectiveBudget - mandatoryTokens);
+    const systemPromptAddition = truncateSystemPromptAdditionToTokenBudget(result.systemPromptAddition, systemPromptBudget);
+    const systemPromptTokens = approximateTokenCount(systemPromptAddition);
+    const messageBudget = Math.max(mandatoryTokens, effectiveBudget - systemPromptTokens);
+    const messages = trimTurnAlignedSourceSuffixToBudget(result.messages, messageBudget);
+    const estimatedTokens = systemPromptTokens + approximateMessagesTokens(messages);
+    return {
+        ...result,
+        messages,
+        systemPromptAddition,
+        estimatedTokens,
+    };
+}
 function buildBudgetFallbackContext(messages, tokenBudget) {
     const effectiveBudget = resolveEffectiveAssembleBudget(tokenBudget);
     const fallbackMessages = trimMessagesToBudget(messages.map((message) => ({ ...message })), effectiveBudget);
@@ -733,7 +823,11 @@ function buildBudgetFallbackContext(messages, tokenBudget) {
 const DAEMON_AUTHORED_CONTEXT_RE = /<authored_context\b[^>]*>([\s\S]*?)<\/authored_context>/gi;
 const DAEMON_AUTHORED_CONTEXT_GUIDANCE_RE = /^\s*Treat the authored entries below as active project rules and identity context\.?\s*$/i;
 const COMPACTED_SESSION_CONTEXT_RE = /<compacted_session_context\b([^>]*)>([\s\S]*?)<\/compacted_session_context>/gi;
+const HAS_COMPACTED_SESSION_CONTEXT_RE = /<compacted_session_context\b/i;
 const COMPACTED_SESSION_RENDER_LEDGER_RE = /(?:^|\n)(?:Artifacts:|Constraints:|Open Next Steps:|Extracted context anchors:)(?:\n|$)/;
+function hasCompactedSessionContext(text) {
+    return HAS_COMPACTED_SESSION_CONTEXT_RE.test(text);
+}
 function sanitizeDaemonSystemPromptAddition(text) {
     return demoteDaemonAuthoredContextBlocks(sanitizeToolCallPatterns(canonicalizeCompactedSessionContextBlocks(text)));
 }
@@ -1170,11 +1264,11 @@ function ensureReplaySafeUserTurn(assembled, sourceMessages, logger, tokenBudget
 /**
  * Normalizes a compact result into the OpenClaw-compatible assemble result format.
  */
-export function normalizeAssembleResult(result, sourceMessages) {
-    // The daemon's visibleMsgs is a filtered echo of args.Messages (toolResult
-    // stripped). Use sourceMessages directly — they carry the full transcript
-    // with tool protocol intact. The daemon contributes memory context via
-    // systemPromptAddition, not message manipulation.
+export function normalizeAssembleResult(result, sourceMessages, promptAuthority = PROMPT_AUTHORITY_PREASSEMBLY_MAY_OVERFLOW) {
+    // The daemon's visibleMsgs is a normalized projection that cannot preserve
+    // provider tool protocol. Use only an exact source transcript projection.
+    // The caller decides whether that is the full pre-compaction transcript or
+    // the user-turn-aligned suffix owned by daemon compaction.
     const systemPromptAddition = typeof result.systemPromptAddition === "string"
         ? sanitizeDaemonSystemPromptAddition(result.systemPromptAddition)
         : "";
@@ -1182,7 +1276,7 @@ export function normalizeAssembleResult(result, sourceMessages) {
         messages: sourceMessages ?? [],
         estimatedTokens: typeof result.estimatedTokens === "number" ? result.estimatedTokens : 0,
         systemPromptAddition,
-        promptAuthority: PROMPT_AUTHORITY_PREASSEMBLY_MAY_OVERFLOW,
+        promptAuthority,
         ...(result.debug != null ? { debug: result.debug } : {}),
     };
 }
@@ -1277,6 +1371,7 @@ export function buildContextEngineFactory(runtime, cfg, logger = console) {
         setOptimizationMemoCacheSize(cfg.optimizationMemoCacheSize);
     }
     const predictiveContextCache = new Map();
+    const compactedProjectionSessions = new Set();
     const PREDICTIVE_CACHE_MAX_SIZE = 100;
     // BeforeTurnKernel state
     const turnCache = new TurnMemoryCache(100);
@@ -1285,6 +1380,21 @@ export function buildContextEngineFactory(runtime, cfg, logger = console) {
     let lastUserMessageHash = null;
     let cachedIdentity = null;
     let cachedSessionKey;
+    function activateCompactedProjection(sessionId, source) {
+        const wasActive = compactedProjectionSessions.has(sessionId);
+        compactedProjectionSessions.add(sessionId);
+        predictiveContextCache.delete(sessionId);
+        postToolRecallCache.delete(sessionId);
+        turnCache.invalidateSession(sessionId);
+        if (!wasActive) {
+            logger.info?.(`LibraVDB activated daemon-owned compacted projection sessionId=${sessionId} source=${source}`);
+        }
+    }
+    function enforceAssembleBudget(result, tokenBudget, compactionProjectionActive) {
+        return compactionProjectionActive
+            ? enforceCompactedProjectionBudgetInvariant(result, tokenBudget)
+            : enforceTokenBudgetInvariant(result, tokenBudget);
+    }
     function resolveUserId(args) {
         // Framework-provided userId takes priority (channels, future SDK compat).
         const fwUserId = args?.userIdOverride?.trim();
@@ -1750,11 +1860,15 @@ export function buildContextEngineFactory(runtime, cfg, logger = console) {
         try {
             const client = await runtime.getClient();
             const threshold = getDynamicCompactThreshold(args.tokenBudget);
-            return normalizeCompactResult(await client.compactSession(request), {
+            const result = normalizeCompactResult(await client.compactSession(request), {
                 tokensBefore: args.currentTokenCount,
                 logger,
                 ...(threshold != null ? { threshold } : {}),
             });
+            if (result.ok && result.compacted) {
+                activateCompactedProjection(args.sessionId, "compact");
+            }
+            return result;
         }
         catch (error) {
             return {
@@ -1814,6 +1928,7 @@ export function buildContextEngineFactory(runtime, cfg, logger = console) {
             const sessionId = requireSessionId(args.sessionId, "bootstrap");
             predictiveContextCache.delete(sessionId);
             postToolRecallCache.delete(sessionId);
+            turnCache.invalidateSession(sessionId);
             asyncIngestionQueues.delete(sessionId);
             const userId = resolveUserId({
                 userIdOverride: args.userId,
@@ -1856,6 +1971,7 @@ export function buildContextEngineFactory(runtime, cfg, logger = console) {
         },
         async assemble(args) {
             const sessionId = requireSessionId(args.sessionId, "assemble");
+            let compactionProjectionActive = compactedProjectionSessions.has(sessionId);
             const userId = resolveUserId({
                 userIdOverride: args.userId,
                 sessionKey: args.sessionKey,
@@ -1865,10 +1981,22 @@ export function buildContextEngineFactory(runtime, cfg, logger = console) {
             // Processing the full history on every turn is O(N²) and the
             // primary source of growing turn latency.
             const normalizeWindow = 50;
-            const recentMessages = args.messages.length > normalizeWindow
-                ? args.messages.slice(-normalizeWindow)
-                : args.messages;
+            const recentMessages = selectTurnAlignedSourceSuffix(args.messages, normalizeWindow);
             const messages = normalizeKernelMessages(recentMessages);
+            const projectedSourceMessages = () => compactionProjectionActive
+                ? recentMessages
+                : args.messages;
+            const buildAssembleFallback = () => {
+                if (!compactionProjectionActive) {
+                    return buildBudgetFallbackContext(args.messages, args.tokenBudget);
+                }
+                return enforceCompactedProjectionBudgetInvariant({
+                    messages: projectedSourceMessages(),
+                    estimatedTokens: approximateMessagesTokens(projectedSourceMessages()),
+                    systemPromptAddition: "",
+                    promptAuthority: "assembled",
+                }, args.tokenBudget);
+            };
             const strippedPrompt = args.prompt
                 ? normalizeKernelContent(args.prompt, { retainOpenClawContext: false })
                 : "";
@@ -1919,10 +2047,15 @@ export function buildContextEngineFactory(runtime, cfg, logger = console) {
                     compacted: compactionResult.compacted,
                     reason: compactionResult.reason,
                 });
-                if (!compactionResult.ok) {
+                compactionProjectionActive = compactedProjectionSessions.has(sessionId);
+                if (!compactionResult.ok && !compactionProjectionActive) {
                     logger.info?.(`LibraVDB predictive compaction blocked assemble path at ${currentContextTokens} tokens ` +
                         `(threshold=${dynamicCompactThreshold}): ${compactionResult.reason ?? "compaction failed"}`);
-                    return ensureReplaySafeUserTurn(buildBudgetFallbackContext(args.messages, args.tokenBudget), args.messages, logger, args.tokenBudget);
+                    return ensureReplaySafeUserTurn(buildAssembleFallback(), args.messages, logger, args.tokenBudget);
+                }
+                if (!compactionResult.ok) {
+                    logger.info?.(`LibraVDB predictive compaction made no additional progress at ${currentContextTokens} tokens; ` +
+                        "continuing with the existing daemon-owned compacted projection.");
                 }
             }
             // BeforeTurnKernel: semantic memory retrieval against the current user query.
@@ -1976,8 +2109,13 @@ export function buildContextEngineFactory(runtime, cfg, logger = console) {
                     }
                 }
                 if (cachedSystemPrompt !== undefined) {
-                    const mockResp = { messages: args.messages, systemPromptAddition: cachedSystemPrompt };
-                    enforced = enforceTokenBudgetInvariant(normalizeAssembleResult(mockResp, args.messages), args.tokenBudget);
+                    if (hasCompactedSessionContext(cachedSystemPrompt)) {
+                        activateCompactedProjection(sessionId, "assemble");
+                        compactionProjectionActive = true;
+                    }
+                    const sourceProjection = projectedSourceMessages();
+                    const mockResp = { messages: sourceProjection, systemPromptAddition: cachedSystemPrompt };
+                    enforced = enforceAssembleBudget(normalizeAssembleResult(mockResp, sourceProjection, compactionProjectionActive ? "assembled" : PROMPT_AUTHORITY_PREASSEMBLY_MAY_OVERFLOW), args.tokenBudget, compactionProjectionActive);
                 }
                 else {
                     // Drain pending async ingestion for this session so the daemon's
@@ -2038,7 +2176,13 @@ export function buildContextEngineFactory(runtime, cfg, logger = console) {
                         }),
                         new Promise((_, reject) => setTimeout(() => reject(new Error(`AssembleContextInternal timed out after ${assembleTimeout}ms`)), assembleTimeout)),
                     ]);
-                    const assembled = normalizeAssembleResult(resp, args.messages);
+                    if (typeof resp.systemPromptAddition === "string" &&
+                        hasCompactedSessionContext(resp.systemPromptAddition)) {
+                        activateCompactedProjection(sessionId, "assemble");
+                        compactionProjectionActive = true;
+                    }
+                    const sourceProjection = projectedSourceMessages();
+                    const assembled = normalizeAssembleResult(resp, sourceProjection, compactionProjectionActive ? "assembled" : PROMPT_AUTHORITY_PREASSEMBLY_MAY_OVERFLOW);
                     const continuityContext = await injectContinuityContext({
                         client,
                         userId,
@@ -2070,13 +2214,13 @@ export function buildContextEngineFactory(runtime, cfg, logger = console) {
                             withContext = { ...withContext, systemPromptAddition: appendSystemPromptAddition(withContext.systemPromptAddition, rulesContext) };
                         }
                     }
-                    enforced = enforceTokenBudgetInvariant(await augmentWithExactRecall(withContext, {
+                    enforced = enforceAssembleBudget(await augmentWithExactRecall(withContext, {
                         queryText: retrievalQuery,
                         userId,
                         sessionId,
                         tokenBudget: args.tokenBudget,
                         reservedTokens: reservedCurrentTurnTokens,
-                    }), args.tokenBudget);
+                    }), args.tokenBudget, compactionProjectionActive);
                     const predictions = predictiveContextCache.get(sessionId) || [];
                     predictiveContextCache.delete(sessionId);
                     if (predictions.length > 0) {
@@ -2128,14 +2272,15 @@ export function buildContextEngineFactory(runtime, cfg, logger = console) {
                         systemPromptAddition: enforced.systemPromptAddition,
                     });
                 }
-                enforced = enforceTokenBudgetInvariant(enforced, args.tokenBudget);
-                // normalizeAssembleResult uses sourceMessages directly — full transcript
-                // with tool protocol intact. No message re-classification needed.
+                enforced = enforceAssembleBudget(enforced, args.tokenBudget, compactionProjectionActive);
+                // The returned transcript is always an untouched source projection.
+                // Once daemon compaction owns history, OpenClaw must precheck this
+                // assembled suffix rather than the unwindowed session transcript.
                 return ensureReplaySafeUserTurn(enforced, args.messages, logger, args.tokenBudget);
             }
             catch (error) {
                 logger.warn?.(`LibraVDB assemble failed, using budget-clamped fallback context: ${error instanceof Error ? error.message : String(error)}`);
-                return ensureReplaySafeUserTurn(buildBudgetFallbackContext(args.messages, args.tokenBudget), args.messages, logger, args.tokenBudget);
+                return ensureReplaySafeUserTurn(buildAssembleFallback(), args.messages, logger, args.tokenBudget);
             }
         },
         async compact(args) {
@@ -2343,6 +2488,7 @@ export function buildContextEngineFactory(runtime, cfg, logger = console) {
                 }
             }
             predictiveContextCache.clear();
+            compactedProjectionSessions.clear();
             postToolRecallCache.clear();
             asyncIngestionQueues.clear();
             triggerCache.clear();

package/dist/index.js

@@ -18615,10 +18615,10 @@ function buildRulesContext() {
 }
 
 // src/manifest.ts
-import * as fs2 from "fs";
-import * as path2 from "path";
-import * as crypto from "crypto";
-import * as os2 from "os";
+import * as fs2 from "node:fs";
+import * as path2 from "node:path";
+import * as crypto from "node:crypto";
+import * as os2 from "node:os";
 var TurnManifestStore = class {
   manifestDir;
   constructor() {
@@ -18923,7 +18923,7 @@ function normalizeCompactResult(response, options = {}) {
   const threshold = options.threshold;
   const overBudget = threshold != null && tokensBefore >= threshold;
   const engineRefused = !didCompact && overBudget;
-  const tokensAfter = didCompact && typeof response?.tokensAfter === "number" && response.tokensAfter > 0 ? response.tokensAfter : void 0;
+  const tokensAfter = didCompact && typeof response?.tokensAfter === "number" && response.tokensAfter >= 0 ? response.tokensAfter : void 0;
   return {
     ok: !engineRefused,
     compacted: didCompact,
@@ -18931,8 +18931,7 @@ function normalizeCompactResult(response, options = {}) {
     result: {
       tokensBefore,
       ...tokensAfter != null ? { tokensAfter } : {},
-      ...details.summaryMethod ? { summary: details.summaryMethod } : {},
-      ...details.summaryText ? { summaryText: details.summaryText } : {},
+      ...details.summaryText ? { summary: details.summaryText } : {},
       details: { ...details, ...threshold != null ? { threshold } : {} }
     }
   };
@@ -19011,6 +19010,18 @@ function findLastUserMessageIndex(messages) {
   }
   return -1;
 }
+function selectTurnAlignedSourceSuffix(messages, maxMessages) {
+  if (messages.length === 0) return [];
+  let start = Math.max(0, messages.length - Math.max(1, Math.floor(maxMessages)));
+  while (start > 0 && messages[start]?.role !== "user") {
+    start -= 1;
+  }
+  if (messages[start]?.role !== "user") {
+    const firstUserIndex = messages.findIndex((message) => message.role === "user");
+    start = firstUserIndex >= 0 ? firstUserIndex : 0;
+  }
+  return messages.slice(start);
+}
 function normalizeKernelContent(content, options = {}) {
   const text = typeof content === "string" ? content : Array.isArray(content) ? content.map(stringifyKernelBlock).filter((part) => part.length > 0).join("\n") : "";
   return stripOpenClawUntrustedMetadataEnvelope(text, {
@@ -19374,6 +19385,32 @@ function trimMessagesToBudget(messages, tokenBudget) {
   }
   return [{ ...last, content: truncated }];
 }
+function trimTurnAlignedSourceSuffixToBudget(messages, tokenBudget) {
+  if (messages.length === 0) return [];
+  const userStarts = [];
+  for (let index = 0; index < messages.length; index += 1) {
+    if (messages[index]?.role === "user") userStarts.push(index);
+  }
+  if (userStarts.length === 0) {
+    return messages;
+  }
+  const keptBundles = [];
+  let used = 0;
+  let bundleEnd = messages.length;
+  for (let index = userStarts.length - 1; index >= 0; index -= 1) {
+    const bundleStart = userStarts[index];
+    const bundle = messages.slice(bundleStart, bundleEnd);
+    const bundleCost = approximateMessagesTokens(bundle);
+    if (keptBundles.length > 0 && used + bundleCost > tokenBudget) {
+      break;
+    }
+    keptBundles.unshift(bundle);
+    used += bundleCost;
+    bundleEnd = bundleStart;
+    if (used >= tokenBudget) break;
+  }
+  return keptBundles.flat();
+}
 function boundAfterTurnMessagesForIngest(messages, logger, sessionId) {
   const estimatedTokens = approximateMessagesTokens(messages);
   if (estimatedTokens <= AFTER_TURN_INGEST_MAX_TOKENS) {
@@ -19414,6 +19451,34 @@ function enforceTokenBudgetInvariant(result, tokenBudget) {
     estimatedTokens: Math.min(effectiveBudget, systemPromptTokens + trimmedEstimate)
   };
 }
+function enforceCompactedProjectionBudgetInvariant(result, tokenBudget) {
+  if (typeof tokenBudget !== "number" || !Number.isFinite(tokenBudget) || tokenBudget <= 0) {
+    return result;
+  }
+  const effectiveBudget = resolveEffectiveAssembleBudget(Math.max(1, Math.floor(tokenBudget)));
+  const approximateTotal = approximateTokenCount(result.systemPromptAddition) + approximateMessagesTokens(result.messages);
+  if (result.estimatedTokens <= effectiveBudget && approximateTotal <= effectiveBudget) {
+    return result;
+  }
+  const lastUserIndex = findLastUserMessageIndex(result.messages);
+  const mandatoryMessages = lastUserIndex >= 0 ? result.messages.slice(lastUserIndex) : result.messages;
+  const mandatoryTokens = approximateMessagesTokens(mandatoryMessages);
+  const systemPromptBudget = Math.max(0, effectiveBudget - mandatoryTokens);
+  const systemPromptAddition = truncateSystemPromptAdditionToTokenBudget(
+    result.systemPromptAddition,
+    systemPromptBudget
+  );
+  const systemPromptTokens = approximateTokenCount(systemPromptAddition);
+  const messageBudget = Math.max(mandatoryTokens, effectiveBudget - systemPromptTokens);
+  const messages = trimTurnAlignedSourceSuffixToBudget(result.messages, messageBudget);
+  const estimatedTokens = systemPromptTokens + approximateMessagesTokens(messages);
+  return {
+    ...result,
+    messages,
+    systemPromptAddition,
+    estimatedTokens
+  };
+}
 function buildBudgetFallbackContext(messages, tokenBudget) {
   const effectiveBudget = resolveEffectiveAssembleBudget(tokenBudget);
   const fallbackMessages = trimMessagesToBudget(
@@ -19430,7 +19495,11 @@ function buildBudgetFallbackContext(messages, tokenBudget) {
 var DAEMON_AUTHORED_CONTEXT_RE = /<authored_context\b[^>]*>([\s\S]*?)<\/authored_context>/gi;
 var DAEMON_AUTHORED_CONTEXT_GUIDANCE_RE = /^\s*Treat the authored entries below as active project rules and identity context\.?\s*$/i;
 var COMPACTED_SESSION_CONTEXT_RE = /<compacted_session_context\b([^>]*)>([\s\S]*?)<\/compacted_session_context>/gi;
+var HAS_COMPACTED_SESSION_CONTEXT_RE = /<compacted_session_context\b/i;
 var COMPACTED_SESSION_RENDER_LEDGER_RE = /(?:^|\n)(?:Artifacts:|Constraints:|Open Next Steps:|Extracted context anchors:)(?:\n|$)/;
+function hasCompactedSessionContext(text) {
+  return HAS_COMPACTED_SESSION_CONTEXT_RE.test(text);
+}
 function sanitizeDaemonSystemPromptAddition(text) {
   return demoteDaemonAuthoredContextBlocks(
     sanitizeToolCallPatterns(canonicalizeCompactedSessionContextBlocks(text))
@@ -19781,13 +19850,13 @@ function ensureReplaySafeUserTurn(assembled, sourceMessages, logger, tokenBudget
     estimatedTokens: baseEstimatedTokens + approximateMessageTokens(fallbackUser)
   };
 }
-function normalizeAssembleResult(result, sourceMessages) {
+function normalizeAssembleResult(result, sourceMessages, promptAuthority = PROMPT_AUTHORITY_PREASSEMBLY_MAY_OVERFLOW) {
   const systemPromptAddition = typeof result.systemPromptAddition === "string" ? sanitizeDaemonSystemPromptAddition(result.systemPromptAddition) : "";
   return {
     messages: sourceMessages ?? [],
     estimatedTokens: typeof result.estimatedTokens === "number" ? result.estimatedTokens : 0,
     systemPromptAddition,
-    promptAuthority: PROMPT_AUTHORITY_PREASSEMBLY_MAY_OVERFLOW,
+    promptAuthority,
     ...result.debug != null ? { debug: result.debug } : {}
   };
 }
@@ -19858,6 +19927,7 @@ function buildContextEngineFactory(runtime, cfg, logger = console) {
     setOptimizationMemoCacheSize(cfg.optimizationMemoCacheSize);
   }
   const predictiveContextCache = /* @__PURE__ */ new Map();
+  const compactedProjectionSessions = /* @__PURE__ */ new Set();
   const PREDICTIVE_CACHE_MAX_SIZE = 100;
   const turnCache = new TurnMemoryCache(100);
   const circuitBreakers = /* @__PURE__ */ new Map();
@@ -19865,6 +19935,21 @@ function buildContextEngineFactory(runtime, cfg, logger = console) {
   let lastUserMessageHash = null;
   let cachedIdentity = null;
   let cachedSessionKey;
+  function activateCompactedProjection(sessionId, source) {
+    const wasActive = compactedProjectionSessions.has(sessionId);
+    compactedProjectionSessions.add(sessionId);
+    predictiveContextCache.delete(sessionId);
+    postToolRecallCache.delete(sessionId);
+    turnCache.invalidateSession(sessionId);
+    if (!wasActive) {
+      logger.info?.(
+        `LibraVDB activated daemon-owned compacted projection sessionId=${sessionId} source=${source}`
+      );
+    }
+  }
+  function enforceAssembleBudget(result, tokenBudget, compactionProjectionActive) {
+    return compactionProjectionActive ? enforceCompactedProjectionBudgetInvariant(result, tokenBudget) : enforceTokenBudgetInvariant(result, tokenBudget);
+  }
   function resolveUserId(args) {
     const fwUserId = args?.userIdOverride?.trim();
     if (fwUserId) return fwUserId;
@@ -20302,11 +20387,15 @@ ${cached}
     try {
       const client = await runtime.getClient();
       const threshold = getDynamicCompactThreshold(args.tokenBudget);
-      return normalizeCompactResult(await client.compactSession(request3), {
+      const result = normalizeCompactResult(await client.compactSession(request3), {
         tokensBefore: args.currentTokenCount,
         logger,
         ...threshold != null ? { threshold } : {}
       });
+      if (result.ok && result.compacted) {
+        activateCompactedProjection(args.sessionId, "compact");
+      }
+      return result;
     } catch (error2) {
       return {
         ok: false,
@@ -20363,6 +20452,7 @@ ${cached}
       const sessionId = requireSessionId(args.sessionId, "bootstrap");
       predictiveContextCache.delete(sessionId);
       postToolRecallCache.delete(sessionId);
+      turnCache.invalidateSession(sessionId);
       asyncIngestionQueues.delete(sessionId);
       const userId = resolveUserId({
         userIdOverride: args.userId,
@@ -20406,13 +20496,26 @@ ${cached}
     },
     async assemble(args) {
       const sessionId = requireSessionId(args.sessionId, "assemble");
+      let compactionProjectionActive = compactedProjectionSessions.has(sessionId);
       const userId = resolveUserId({
         userIdOverride: args.userId,
         sessionKey: args.sessionKey
       });
       const normalizeWindow = 50;
-      const recentMessages = args.messages.length > normalizeWindow ? args.messages.slice(-normalizeWindow) : args.messages;
+      const recentMessages = selectTurnAlignedSourceSuffix(args.messages, normalizeWindow);
       const messages = normalizeKernelMessages(recentMessages);
+      const projectedSourceMessages = () => compactionProjectionActive ? recentMessages : args.messages;
+      const buildAssembleFallback = () => {
+        if (!compactionProjectionActive) {
+          return buildBudgetFallbackContext(args.messages, args.tokenBudget);
+        }
+        return enforceCompactedProjectionBudgetInvariant({
+          messages: projectedSourceMessages(),
+          estimatedTokens: approximateMessagesTokens(projectedSourceMessages()),
+          systemPromptAddition: "",
+          promptAuthority: "assembled"
+        }, args.tokenBudget);
+      };
       const strippedPrompt = args.prompt ? normalizeKernelContent(args.prompt, { retainOpenClawContext: false }) : "";
       const lastUserIndex = findLastUserMessageIndex(messages);
       const isPostToolContinuation = lastUserIndex >= 0 && lastUserIndex < messages.length - 1 && hasLiveToolProtocolAfterLastUser(messages, lastUserIndex);
@@ -20458,17 +20561,23 @@ ${cached}
           compacted: compactionResult.compacted,
           reason: compactionResult.reason
         });
-        if (!compactionResult.ok) {
+        compactionProjectionActive = compactedProjectionSessions.has(sessionId);
+        if (!compactionResult.ok && !compactionProjectionActive) {
           logger.info?.(
             `LibraVDB predictive compaction blocked assemble path at ${currentContextTokens} tokens (threshold=${dynamicCompactThreshold}): ${compactionResult.reason ?? "compaction failed"}`
           );
           return ensureReplaySafeUserTurn(
-            buildBudgetFallbackContext(args.messages, args.tokenBudget),
+            buildAssembleFallback(),
             args.messages,
             logger,
             args.tokenBudget
           );
         }
+        if (!compactionResult.ok) {
+          logger.info?.(
+            `LibraVDB predictive compaction made no additional progress at ${currentContextTokens} tokens; continuing with the existing daemon-owned compacted projection.`
+          );
+        }
       }
       const btLog = cfg.beforeTurnDebug ? (msg) => logger.info?.(msg) : (_msg) => {
       };
@@ -20515,10 +20624,20 @@ ${cached}
           }
         }
         if (cachedSystemPrompt !== void 0) {
-          const mockResp = { messages: args.messages, systemPromptAddition: cachedSystemPrompt };
-          enforced = enforceTokenBudgetInvariant(
-            normalizeAssembleResult(mockResp, args.messages),
-            args.tokenBudget
+          if (hasCompactedSessionContext(cachedSystemPrompt)) {
+            activateCompactedProjection(sessionId, "assemble");
+            compactionProjectionActive = true;
+          }
+          const sourceProjection = projectedSourceMessages();
+          const mockResp = { messages: sourceProjection, systemPromptAddition: cachedSystemPrompt };
+          enforced = enforceAssembleBudget(
+            normalizeAssembleResult(
+              mockResp,
+              sourceProjection,
+              compactionProjectionActive ? "assembled" : PROMPT_AUTHORITY_PREASSEMBLY_MAY_OVERFLOW
+            ),
+            args.tokenBudget,
+            compactionProjectionActive
           );
         } else {
           const pending = asyncIngestionQueues.get(sessionId);
@@ -20580,7 +20699,16 @@ ${cached}
               (_, reject) => setTimeout(() => reject(new Error(`AssembleContextInternal timed out after ${assembleTimeout}ms`)), assembleTimeout)
             )
           ]);
-          const assembled = normalizeAssembleResult(resp, args.messages);
+          if (typeof resp.systemPromptAddition === "string" && hasCompactedSessionContext(resp.systemPromptAddition)) {
+            activateCompactedProjection(sessionId, "assemble");
+            compactionProjectionActive = true;
+          }
+          const sourceProjection = projectedSourceMessages();
+          const assembled = normalizeAssembleResult(
+            resp,
+            sourceProjection,
+            compactionProjectionActive ? "assembled" : PROMPT_AUTHORITY_PREASSEMBLY_MAY_OVERFLOW
+          );
           const continuityContext = await injectContinuityContext({
             client,
             userId,
@@ -20609,7 +20737,7 @@ ${cached}
               withContext = { ...withContext, systemPromptAddition: appendSystemPromptAddition(withContext.systemPromptAddition, rulesContext) };
             }
           }
-          enforced = enforceTokenBudgetInvariant(
+          enforced = enforceAssembleBudget(
             await augmentWithExactRecall(withContext, {
               queryText: retrievalQuery,
               userId,
@@ -20617,7 +20745,8 @@ ${cached}
               tokenBudget: args.tokenBudget,
               reservedTokens: reservedCurrentTurnTokens
             }),
-            args.tokenBudget
+            args.tokenBudget,
+            compactionProjectionActive
           );
           const predictions = predictiveContextCache.get(sessionId) || [];
           predictiveContextCache.delete(sessionId);
@@ -20674,9 +20803,10 @@ ${cached}
             systemPromptAddition: enforced.systemPromptAddition
           });
         }
-        enforced = enforceTokenBudgetInvariant(
+        enforced = enforceAssembleBudget(
           enforced,
-          args.tokenBudget
+          args.tokenBudget,
+          compactionProjectionActive
         );
         return ensureReplaySafeUserTurn(enforced, args.messages, logger, args.tokenBudget);
       } catch (error2) {
@@ -20684,7 +20814,7 @@ ${cached}
           `LibraVDB assemble failed, using budget-clamped fallback context: ${error2 instanceof Error ? error2.message : String(error2)}`
         );
         return ensureReplaySafeUserTurn(
-          buildBudgetFallbackContext(args.messages, args.tokenBudget),
+          buildAssembleFallback(),
           args.messages,
           logger,
           args.tokenBudget
@@ -20872,6 +21002,7 @@ ${cached}
         }
       }
       predictiveContextCache.clear();
+      compactedProjectionSessions.clear();
       postToolRecallCache.clear();
       asyncIngestionQueues.clear();
       triggerCache.clear();
@@ -31194,6 +31325,12 @@ function buildToolGuidance(availableTools) {
     return [];
   }
   const lines = [];
+  const hasSearch = availableTools.has("memory_search");
+  const hasGet = availableTools.has("memory_get");
+  const hasDescribe = availableTools.has("memory_describe");
+  const hasExpand = availableTools.has("memory_expand");
+  const hasGrep = availableTools.has("memory_grep");
+  const hasUserCard = availableTools.has("get_user_card");
   const hasGetCard = availableTools.has("get_user_card");
   const hasListCards = availableTools.has("list_user_cards");
   if (hasGetCard || hasListCards) {
@@ -31204,7 +31341,7 @@ function buildToolGuidance(availableTools) {
       hasListCards ? "- `list_user_cards()` \u2014 MANDATORY roster check. Call if unsure whether a card exists." : "",
       "Cards are the canonical record. You MUST call these tools. Do NOT answer from",
       "memory, context, or training data without checking the card first.",
-      "Only use memory_search if the card is empty or missing.",
+      hasSearch ? "Only use memory_search if the card is empty or missing." : "Use the card result as the available identity record.",
       "",
       "**Autonomous card maintenance:**",
       hasGetCard ? "- When ANY speaker is mentioned with new or changed information (status, relationships, jobs, life events, feelings), call `update_user_card` BEFORE responding. Update the card first, then reply. Do NOT wait to be asked. Build the world picture proactively. Every person the user mentions matters." : "",
@@ -31212,20 +31349,19 @@ function buildToolGuidance(availableTools) {
       ""
     );
   }
-  lines.push(
-    "Call `memory_search` once per user question for prior turns, remembered",
-    "facts, earliest interactions, and channel history. Do not answer memory",
-    "questions from prior transcript claims \u2014 perform a search every time.",
-    "After receiving results, use them directly; do not re-call in the same turn.",
-    ...availableTools.has("memory_get") ? [
-      "After a `memory_search` hit, call `memory_get` when exact wording or more context is needed.",
-      "IMPORTANT: If a search snippet is cluttered with metadata, do NOT claim nothing was found. Call `memory_get` on the hit's path to read the full record first. The data is there \u2014 expand before giving up."
-    ] : [],
-    ""
-  );
-  const hasDescribe = availableTools.has("memory_describe");
-  const hasExpand = availableTools.has("memory_expand");
-  const hasGrep = availableTools.has("memory_grep");
+  if (hasSearch) {
+    lines.push(
+      "Call `memory_search` once per user question for prior turns, remembered",
+      "facts, earliest interactions, and channel history. Do not answer memory",
+      "questions from prior transcript claims \u2014 perform a search every time.",
+      "After receiving results, use them directly; do not re-call in the same turn.",
+      ...hasGet ? [
+        "After a `memory_search` hit, call `memory_get` when exact wording or more context is needed.",
+        "IMPORTANT: If a search snippet is cluttered with metadata, do NOT claim nothing was found. Call `memory_get` on the hit's path to read the full record first. The data is there \u2014 expand before giving up."
+      ] : [],
+      ""
+    );
+  }
   if (hasDescribe || hasExpand || hasGrep) {
     lines.push(
       "**Compacted summaries \u2014 recall hierarchy (cheap \u2192 expensive):**",
@@ -31272,13 +31408,16 @@ function buildToolGuidance(availableTools) {
     ""
   );
   if (hasExpand) {
+    const traversalSteps = [
+      hasSearch ? "1. `memory_search` for the people/events in question to get record IDs" : "1. Start from a record ID already present in context or another tool result",
+      "2. `memory_expand` with the most relevant `record_id` to walk typed causal and 6W1H hop edges",
+      hasGet ? "3. Follow interesting edges; use `memory_get` for exact detail on connected records" : "3. Use the typed edge snippets to decide whether the connected records answer the question",
+      ...hasUserCard ? ["4. Use `get_user_card` to cross-reference identity context"] : []
+    ];
     lines.push(
       "### Causal Graph Traversal",
       "When the user asks about causes, patterns, or relationships:",
-      "1. `memory_search` for the people/events in question to get record IDs",
-      "2. `memory_expand` with the most relevant `record_id` to walk causal edges",
-      "3. Follow interesting edges \u2014 use `memory_get` for full detail on connected records",
-      "4. Use `get_user_card` to cross-reference identity context",
+      ...traversalSteps,
       ""
     );
   }
@@ -31466,7 +31605,7 @@ function createMemoryExpandTool(getClient, getSessionKey, logger = console, getS
   return {
     name: "memory_expand",
     label: "Memory Expand",
-    description: "Expand compacted summaries OR walk causal graph edges from ANY record. Summary mode (summaryIds): walk the summary tree up to maxDepth levels. Graph mode (record_id): walk causal edges (why_ids/how_ids/hop_targets) from a record ID. Use exact IDs from memory_search or memory_get results \u2014 any ingested turn, memory, or summary has graph edges. After get_user_card for context, search for related people/events then expand the most relevant hit. For large expansions, spawns a sub-agent. Use memory_describe first to check if expansion is warranted.",
+    description: "Expand compacted summaries OR walk causal graph edges from ANY record. Summary mode (summaryIds): walk the summary tree up to maxDepth levels. Graph mode (record_id): walk causal edges (why_ids/how_ids/hop_targets) from a record ID. Use exact IDs from memory_search or memory_get results \u2014 any ingested turn, memory, or summary has graph edges. For large expansions, spawns a sub-agent. Use memory_describe first to check if expansion is warranted.",
     parameters: MEMORY_EXPAND_SCHEMA,
     execute: async (_toolCallId, rawParams) => {
       const params = asParams(rawParams);
@@ -31481,10 +31620,16 @@ function createMemoryExpandTool(getClient, getSessionKey, logger = console, getS
           const client = await getClient();
           const resp = await client.expandSummary({ recordId, maxDepth });
           let text = resp.text ?? "";
-          const connected = resp.connected;
-          if (connected && connected.length > 0) {
+          const connected = (resp.connected ?? []).map((c) => ({
+            recordId: c.recordId,
+            text: c.text ?? "",
+            depth: c.depth,
+            edgeType: c.edgeType || "unknown",
+            edgeWeight: c.edgeWeight ?? 0
+          }));
+          if (connected.length > 0) {
             text = connected.map(
-              (c) => `[depth=${c.depth}] ${c.recordId}: ${c.text || ""}`
+              (c) => `[depth=${c.depth} edge=${c.edgeType} weight=${c.edgeWeight}] ${c.recordId}: ${c.text}`
             ).join("\n\n");
           }
           if (!text && resp.whyIds?.length) {
@@ -31494,7 +31639,7 @@ hop_targets: ${resp.hopTargets?.join(", ") ?? "none"}`;
           }
           return {
             content: [{ type: "text", text: text || "(no graph edges found)" }],
-            details: { summaryId: recordId, depth: maxDepth, text: text || "", truncated: false, exceededBudget: false, parentCount: connected?.length ?? 0 }
+            details: { summaryId: recordId, depth: maxDepth, text: text || "", truncated: false, exceededBudget: false, parentCount: connected.length, connected }
           };
         } catch (error2) {
           logger.warn?.(`memory_expand graph mode failed: ${formatError(error2)}`);

package/dist/manifest.js

@@ -1,7 +1,7 @@
-import * as fs from "fs";
-import * as path from "path";
-import * as crypto from "crypto";
-import * as os from "os";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+import * as os from "node:os";
 export class TurnManifestStore {
     manifestDir;
     constructor() {

package/dist/memory-provider.js

@@ -25,22 +25,27 @@ function buildToolGuidance(availableTools) {
         return [];
     }
     const lines = [];
+    const hasSearch = availableTools.has("memory_search");
+    const hasGet = availableTools.has("memory_get");
+    const hasDescribe = availableTools.has("memory_describe");
+    const hasExpand = availableTools.has("memory_expand");
+    const hasGrep = availableTools.has("memory_grep");
+    const hasUserCard = availableTools.has("get_user_card");
     // ── User card tools (identity-first override) ──
     const hasGetCard = availableTools.has("get_user_card");
     const hasListCards = availableTools.has("list_user_cards");
     if (hasGetCard || hasListCards) {
-        lines.push("**Identity/Entity questions — MANDATORY card lookup:**", "BEFORE answering any question about a person, pet, place, or named thing:", hasGetCard ? "- `get_user_card(user_id)` — MANDATORY lookup for a specific entity." : "", hasListCards ? "- `list_user_cards()` — MANDATORY roster check. Call if unsure whether a card exists." : "", "Cards are the canonical record. You MUST call these tools. Do NOT answer from", "memory, context, or training data without checking the card first.", "Only use memory_search if the card is empty or missing.", "", "**Autonomous card maintenance:**", hasGetCard ? "- When ANY speaker is mentioned with new or changed information (status, relationships, jobs, life events, feelings), call `update_user_card` BEFORE responding. Update the card first, then reply. Do NOT wait to be asked. Build the world picture proactively. Every person the user mentions matters." : "", hasGetCard ? "- If a card for the speaker doesn't exist yet, CREATE one with `update_user_card`. Better to have a stub card than no card at all." : "", "");
+        lines.push("**Identity/Entity questions — MANDATORY card lookup:**", "BEFORE answering any question about a person, pet, place, or named thing:", hasGetCard ? "- `get_user_card(user_id)` — MANDATORY lookup for a specific entity." : "", hasListCards ? "- `list_user_cards()` — MANDATORY roster check. Call if unsure whether a card exists." : "", "Cards are the canonical record. You MUST call these tools. Do NOT answer from", "memory, context, or training data without checking the card first.", hasSearch ? "Only use memory_search if the card is empty or missing." : "Use the card result as the available identity record.", "", "**Autonomous card maintenance:**", hasGetCard ? "- When ANY speaker is mentioned with new or changed information (status, relationships, jobs, life events, feelings), call `update_user_card` BEFORE responding. Update the card first, then reply. Do NOT wait to be asked. Build the world picture proactively. Every person the user mentions matters." : "", hasGetCard ? "- If a card for the speaker doesn't exist yet, CREATE one with `update_user_card`. Better to have a stub card than no card at all." : "", "");
+    }
+    if (hasSearch) {
+        lines.push("Call `memory_search` once per user question for prior turns, remembered", "facts, earliest interactions, and channel history. Do not answer memory", "questions from prior transcript claims — perform a search every time.", "After receiving results, use them directly; do not re-call in the same turn.", ...(hasGet
+            ? [
+                "After a `memory_search` hit, call `memory_get` when exact wording or more context is needed.",
+                "IMPORTANT: If a search snippet is cluttered with metadata, do NOT claim nothing was found. Call `memory_get` on the hit's path to read the full record first. The data is there — expand before giving up."
+            ]
+            : []), "");
     }
-    lines.push("Call `memory_search` once per user question for prior turns, remembered", "facts, earliest interactions, and channel history. Do not answer memory", "questions from prior transcript claims — perform a search every time.", "After receiving results, use them directly; do not re-call in the same turn.", ...(availableTools.has("memory_get")
-        ? [
-            "After a `memory_search` hit, call `memory_get` when exact wording or more context is needed.",
-            "IMPORTANT: If a search snippet is cluttered with metadata, do NOT claim nothing was found. Call `memory_get` on the hit's path to read the full record first. The data is there — expand before giving up."
-        ]
-        : []), "");
     // ── Summaries / recall (when available) ──
-    const hasDescribe = availableTools.has("memory_describe");
-    const hasExpand = availableTools.has("memory_expand");
-    const hasGrep = availableTools.has("memory_grep");
     if (hasDescribe || hasExpand || hasGrep) {
         lines.push("**Compacted summaries — recall hierarchy (cheap → expensive):**", "", "Summaries in search results show `[Summary sum_xxx]: [eviction cue]`.", "The cue lists what the summary covers — anchors (files, tools, versions),", "decisions, constraints, and signal counts. Many questions can be answered", "from the cue alone without expanding.", "");
         if (hasDescribe) {
@@ -58,7 +63,17 @@ function buildToolGuidance(availableTools) {
     lines.push("### Hard Constraint Rules", "Rules are injected at session start as `<hard_constraints>`. They are non-negotiable.", "Use `set_rule` to create one (max 20), `list_rules` to see current rules,", "`delete_rule` to remove one. Rules override all other instructions.", "Never reason around a rule, find loopholes, or deprioritize it.", "");
     // ── Causal graph traversal (when expand supports record_id) ──
     if (hasExpand) {
-        lines.push("### Causal Graph Traversal", "When the user asks about causes, patterns, or relationships:", "1. `memory_search` for the people/events in question to get record IDs", "2. `memory_expand` with the most relevant `record_id` to walk causal edges", "3. Follow interesting edges — use `memory_get` for full detail on connected records", "4. Use `get_user_card` to cross-reference identity context", "");
+        const traversalSteps = [
+            hasSearch
+                ? "1. `memory_search` for the people/events in question to get record IDs"
+                : "1. Start from a record ID already present in context or another tool result",
+            "2. `memory_expand` with the most relevant `record_id` to walk typed causal and 6W1H hop edges",
+            hasGet
+                ? "3. Follow interesting edges; use `memory_get` for exact detail on connected records"
+                : "3. Use the typed edge snippets to decide whether the connected records answer the question",
+            ...(hasUserCard ? ["4. Use `get_user_card` to cross-reference identity context"] : []),
+        ];
+        lines.push("### Causal Graph Traversal", "When the user asks about causes, patterns, or relationships:", ...traversalSteps, "");
     }
     lines.push("LibraVDB memory is vector-backed and retrieved through tools, not files.", "");
     return lines;

package/dist/tools/memory-recall.d.ts

@@ -26,6 +26,13 @@ type MemoryExpandDetails = {
     truncated: boolean;
     exceededBudget: boolean;
     parentCount: number;
+    connected?: Array<{
+        recordId: string;
+        text: string;
+        depth: number;
+        edgeType: string;
+        edgeWeight: number;
+    }>;
     error?: string;
 };
 type MemoryGrepDetails = {

package/dist/tools/memory-recall.js

@@ -199,8 +199,6 @@ export function createMemoryExpandTool(getClient, getSessionKey, logger = consol
             "Graph mode (record_id): walk causal edges (why_ids/how_ids/hop_targets) " +
             "from a record ID. Use exact IDs from memory_search or memory_get results — " +
             "any ingested turn, memory, or summary has graph edges. " +
-            "After get_user_card for context, search for related people/events then " +
-            "expand the most relevant hit. " +
             "For large expansions, spawns a sub-agent. " +
             "Use memory_describe first to check if expansion is warranted.",
         parameters: MEMORY_EXPAND_SCHEMA,
@@ -218,16 +216,22 @@ export function createMemoryExpandTool(getClient, getSessionKey, logger = consol
                     const client = await getClient();
                     const resp = await client.expandSummary({ recordId, maxDepth });
                     let text = resp.text ?? "";
-                    const connected = resp.connected;
-                    if (connected && connected.length > 0) {
-                        text = connected.map((c) => `[depth=${c.depth}] ${c.recordId}: ${c.text || ""}`).join("\n\n");
+                    const connected = (resp.connected ?? []).map((c) => ({
+                        recordId: c.recordId,
+                        text: c.text ?? "",
+                        depth: c.depth,
+                        edgeType: c.edgeType || "unknown",
+                        edgeWeight: c.edgeWeight ?? 0,
+                    }));
+                    if (connected.length > 0) {
+                        text = connected.map((c) => `[depth=${c.depth} edge=${c.edgeType} weight=${c.edgeWeight}] ${c.recordId}: ${c.text}`).join("\n\n");
                     }
                     if (!text && resp.whyIds?.length) {
                         text = `why_ids: ${resp.whyIds.join(", ")}\nhow_ids: ${resp.howIds?.join(", ") ?? "none"}\nhop_targets: ${resp.hopTargets?.join(", ") ?? "none"}`;
                     }
                     return {
                         content: [{ type: "text", text: text || "(no graph edges found)" }],
-                        details: { summaryId: recordId, depth: maxDepth, text: text || "", truncated: false, exceededBudget: false, parentCount: connected?.length ?? 0 },
+                        details: { summaryId: recordId, depth: maxDepth, text: text || "", truncated: false, exceededBudget: false, parentCount: connected.length, connected },
                     };
                 }
                 catch (error) {

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "libravdb-memory",
   "name": "LibraVDB Memory",
   "description": "Cognitive memory engine — causal graph reasoning, predictive context, identity tracking, and hybrid vector recall with back-door adjustment scoring",
-  "version": "1.10.13",
+  "version": "1.10.14-beta.1",
   "kind": [
     "memory",
     "context-engine"

package/package.json

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