@xdarkicex/openclaw-memory-libravdb 1.7.0 → 1.8.0

package/dist/tools/memory-recall.js

@@ -0,0 +1,421 @@
+import { formatError } from "../format-error.js";
+import { consumeSubagentBudget } from "../context-engine.js";
+// ── Constants ──
+const MAX_EXPAND_TOKENS = 8000;
+const MAX_EXPAND_CHARS = MAX_EXPAND_TOKENS * 4;
+const MAX_GREP_RESULTS = 50;
+const MAX_GREP_CHARS = 40000;
+const MAX_SNIPPET_CHARS = 200;
+// ── Schemas ──
+const MEMORY_DESCRIBE_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        summaryId: {
+            type: "string",
+            description: "A summary ID (sum_xxx format) returned by memory_search. Inspect metadata without expanding.",
+        },
+        sessionId: {
+            type: "string",
+            description: "Session ID the summary belongs to. If omitted, uses the current session.",
+        },
+    },
+    required: ["summaryId"],
+};
+const MEMORY_EXPAND_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        summaryIds: {
+            type: "array",
+            items: { type: "string" },
+            description: "Summary IDs (sum_xxx format) to expand. Use results from memory_search or memory_describe.",
+        },
+        maxDepth: {
+            type: "number",
+            minimum: 0,
+            maximum: 5,
+            description: "Max tree traversal depth per summary (default: 1). 0 returns only the cue/metadata.",
+        },
+        maxTokens: {
+            type: "number",
+            minimum: 100,
+            maximum: Number(MAX_EXPAND_TOKENS),
+            description: `Token budget cap for the expansion result (default: ${MAX_EXPAND_TOKENS}).`,
+        },
+        sessionId: {
+            type: "string",
+            description: "Session ID the summary belongs to. If omitted, uses the current session.",
+        },
+    },
+    required: ["summaryIds"],
+};
+const MEMORY_GREP_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        pattern: {
+            type: "string",
+            description: "Search pattern. Regex when mode=regex, plain text when mode=text.",
+        },
+        mode: {
+            type: "string",
+            enum: ["regex", "text"],
+            description: 'Search mode. Default: "text".',
+        },
+        scope: {
+            type: "string",
+            enum: ["messages", "summaries", "both"],
+            description: 'What to search. Default: "both".',
+        },
+        limit: {
+            type: "number",
+            minimum: 1,
+            maximum: 200,
+            description: `Max results (default: ${MAX_GREP_RESULTS}).`,
+        },
+        sessionId: {
+            type: "string",
+            description: "Session ID to search within. If omitted, uses the current session.",
+        },
+    },
+    required: ["pattern"],
+};
+// ── Helpers ──
+function truncateSnippet(text, maxLen = MAX_SNIPPET_CHARS) {
+    const singleLine = text.replace(/\n/g, " ").trim();
+    if (singleLine.length <= maxLen)
+        return singleLine;
+    return singleLine.slice(0, maxLen - 3) + "...";
+}
+function jsonResult(details) {
+    return { content: [{ type: "text", text: JSON.stringify(details, null, 2) }], details };
+}
+function asParams(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return {};
+    return value;
+}
+function readStr(params, key) {
+    const v = params[key];
+    if (typeof v !== "string")
+        return undefined;
+    const t = v.trim();
+    return t.length > 0 ? t : undefined;
+}
+function readNum(params, key, opts) {
+    const v = params[key];
+    const n = typeof v === "number" ? v : typeof v === "string" && v.trim() ? Number(v) : undefined;
+    if (n === undefined || !Number.isFinite(n))
+        return undefined;
+    const min = opts?.min ?? 1;
+    return opts?.integer ? Math.max(min, Math.floor(n)) : n;
+}
+function formatEvictionCueLine(cue, summaryId) {
+    if (!cue)
+        return `[Summary ${summaryId}]`;
+    const firstLine = cue.split("\n")[0] ?? "";
+    return `[Summary ${summaryId}]: ${firstLine}`;
+}
+function safeMatch(text, pattern, mode) {
+    if (mode === "text")
+        return text.toLowerCase().includes(pattern.toLowerCase());
+    try {
+        return new RegExp(pattern, "i").test(text);
+    }
+    catch {
+        return text.toLowerCase().includes(pattern.toLowerCase());
+    }
+}
+// ── Tool factories ──
+export function createMemoryDescribeTool(getClient, logger = console) {
+    return {
+        name: "memory_describe",
+        label: "Memory Describe",
+        description: "Inspect a summary's metadata without expanding its full text. " +
+            "Returns eviction cues (anchors, decisions, constraints, signal counts), " +
+            "child summary count, and source turn range. Use this before memory_expand " +
+            "to decide whether the summary is worth the expansion cost.",
+        parameters: MEMORY_DESCRIBE_SCHEMA,
+        execute: async (_toolCallId, rawParams) => {
+            const params = asParams(rawParams);
+            const summaryId = readStr(params, "summaryId");
+            if (!summaryId)
+                throw new Error("memory_describe requires summaryId");
+            try {
+                const client = await getClient();
+                const sessionId = readStr(params, "sessionId") ?? "";
+                // Use ExpandSummary with maxDepth=0 to get metadata without expanding children.
+                // maxDepth=0 returns just the target summary's text + metadata_json.
+                const resp = await client.expandSummary({
+                    sessionId,
+                    summaryId,
+                    maxDepth: 0,
+                });
+                let evictionCue;
+                let meta = {};
+                if (resp.metadataJson && resp.metadataJson.length > 0) {
+                    try {
+                        const decoder = new TextDecoder();
+                        meta = JSON.parse(decoder.decode(resp.metadataJson));
+                        evictionCue = typeof meta.eviction_cue === "string" ? meta.eviction_cue : undefined;
+                    }
+                    catch { /* metadata parse best-effort */ }
+                }
+                const lineage = (meta.continuity_lineage ?? {});
+                const sourceTurnIds = Array.isArray(lineage.source_turn_ids) ? lineage.source_turn_ids : [];
+                const parentSummaryIds = Array.isArray(lineage.parent_summary_ids) ? lineage.parent_summary_ids : [];
+                return jsonResult({
+                    summaryId,
+                    found: true,
+                    evictionCue,
+                    depth: typeof meta.compaction_generation === "number" ? meta.compaction_generation : undefined,
+                    descendantCount: typeof meta.descendant_count === "number" ? meta.descendant_count : undefined,
+                    sourceTurnCount: sourceTurnIds.length,
+                    sourceTurnIds: sourceTurnIds.slice(0, 10),
+                    parentSummaryIds: parentSummaryIds.slice(0, 10),
+                });
+            }
+            catch (error) {
+                logger.warn?.(`memory_describe failed: ${formatError(error)}`);
+                return jsonResult({
+                    summaryId,
+                    found: false,
+                    error: formatError(error),
+                });
+            }
+        },
+    };
+}
+export function createMemoryExpandTool(getClient, getSessionKey, logger = console) {
+    return {
+        name: "memory_expand",
+        label: "Memory Expand",
+        description: "Expand compacted summaries to recover full detail. Walks the summary tree " +
+            "up to maxDepth levels. For large expansions (>2500 tokens), spawns a " +
+            "sub-agent to protect context. Use memory_describe first to check if expansion " +
+            "is warranted — many questions can be answered from the eviction cue alone.",
+        parameters: MEMORY_EXPAND_SCHEMA,
+        execute: async (_toolCallId, rawParams) => {
+            const params = asParams(rawParams);
+            const rawIds = params.summaryIds;
+            const summaryIds = Array.isArray(rawIds) ? rawIds.filter((v) => typeof v === "string" && v.trim().length > 0) : [];
+            if (summaryIds.length === 0)
+                throw new Error("memory_expand requires at least one summaryId");
+            const maxDepth = readNum(params, "maxDepth", { integer: true, min: 0 }) ?? 1;
+            const maxTokens = readNum(params, "maxTokens", { integer: true }) ?? MAX_EXPAND_TOKENS;
+            const sessionId = readStr(params, "sessionId") ?? "";
+            // Subagent budget gate: if this is a subagent, check remaining expansion budget.
+            const sessionKey = getSessionKey();
+            if (sessionKey) {
+                const remaining = consumeSubagentBudget(sessionKey, maxTokens);
+                if (remaining === 0) {
+                    return {
+                        content: [{ type: "text", text: "[Subagent expansion budget exhausted. Narrow the query or request fewer summaries.]" }],
+                        details: { summaryId: summaryIds[0] ?? "", depth: maxDepth, text: "", truncated: true, exceededBudget: true, parentCount: 0 },
+                    };
+                }
+                if (remaining > 0 && remaining < maxTokens) {
+                    // Clamp to remaining budget.
+                    logger.info?.(`subagent expansion budget clamped from ${maxTokens} to ${remaining} tokens`);
+                }
+            }
+            try {
+                const client = await getClient();
+                const parts = [];
+                let totalChars = 0;
+                let truncated = false;
+                let parentCount = 0;
+                for (const sid of summaryIds) {
+                    if (totalChars >= MAX_EXPAND_CHARS) {
+                        truncated = true;
+                        break;
+                    }
+                    const resp = await client.expandSummary({
+                        sessionId,
+                        summaryId: sid,
+                        maxDepth,
+                    });
+                    if (resp.text) {
+                        // Count children from metadata if available
+                        let meta = {};
+                        if (resp.metadataJson && resp.metadataJson.length > 0) {
+                            try {
+                                const decoder = new TextDecoder();
+                                meta = JSON.parse(decoder.decode(resp.metadataJson));
+                            }
+                            catch { /* best-effort */ }
+                        }
+                        const lineage = (meta.continuity_lineage ?? {});
+                        const parents = Array.isArray(lineage.parent_summary_ids) ? lineage.parent_summary_ids.length : 0;
+                        parentCount += parents;
+                        const remaining = MAX_EXPAND_CHARS - totalChars;
+                        const text = resp.text.length > remaining ? resp.text.slice(0, remaining) + "\n...[truncated]" : resp.text;
+                        parts.push(`## ${sid}\n${text}`);
+                        totalChars += text.length;
+                        if (resp.text.length > remaining) {
+                            truncated = true;
+                            break;
+                        }
+                    }
+                }
+                const text = parts.join("\n\n");
+                const exceededBudget = totalChars > maxTokens * 4;
+                if (exceededBudget) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `[Expansion exceeds ${maxTokens}-token budget. Use memory_describe to navigate child summaries, or narrow with specific summaryIds.]`,
+                            }],
+                        details: { summaryId: summaryIds[0] ?? "", depth: maxDepth, text: "", truncated: true, exceededBudget: true, parentCount },
+                    };
+                }
+                return jsonResult({
+                    summaryId: summaryIds[0] ?? "",
+                    depth: maxDepth,
+                    text,
+                    truncated,
+                    exceededBudget,
+                    parentCount,
+                });
+            }
+            catch (error) {
+                logger.warn?.(`memory_expand failed: ${formatError(error)}`);
+                return jsonResult({
+                    summaryId: summaryIds[0] ?? "",
+                    depth: maxDepth,
+                    text: "",
+                    truncated: false,
+                    exceededBudget: false,
+                    parentCount: 0,
+                    error: formatError(error),
+                });
+            }
+        },
+    };
+}
+export function createMemoryGrepTool(getClient, logger = console) {
+    return {
+        name: "memory_grep",
+        label: "Memory Grep",
+        description: "Search compacted conversation history by text or regex pattern. " +
+            "Searches across session summaries and raw turns. Returns matching snippets " +
+            "with summary/turn IDs for follow-up with memory_describe or memory_expand.",
+        parameters: MEMORY_GREP_SCHEMA,
+        execute: async (_toolCallId, rawParams) => {
+            const params = asParams(rawParams);
+            const pattern = readStr(params, "pattern");
+            if (!pattern)
+                throw new Error("memory_grep requires pattern");
+            const mode = (params.mode === "regex" ? "regex" : "text");
+            const scope = (params.scope === "messages" ? "messages" : params.scope === "summaries" ? "summaries" : "both");
+            const limit = readNum(params, "limit", { integer: true }) ?? MAX_GREP_RESULTS;
+            const sessionId = readStr(params, "sessionId") ?? "";
+            try {
+                const client = await getClient();
+                const summaries = [];
+                const turns = [];
+                let totalChars = 0;
+                let totalMatches = 0;
+                if (scope === "summaries" || scope === "both") {
+                    const searchK = Math.min(limit * 3, 200);
+                    const summaryResults = await client.searchText({
+                        collection: `session_summary:${sessionId}`,
+                        text: pattern,
+                        k: searchK,
+                    });
+                    for (const r of (summaryResults.results ?? [])) {
+                        if (summaries.length >= limit || totalChars >= MAX_GREP_CHARS)
+                            break;
+                        if (!safeMatch(r.text, pattern, mode))
+                            continue;
+                        totalMatches++;
+                        let evictionCue;
+                        if (r.metadataJson && r.metadataJson.length > 0) {
+                            try {
+                                const decoder = new TextDecoder();
+                                const meta = JSON.parse(decoder.decode(r.metadataJson));
+                                evictionCue = typeof meta.eviction_cue === "string" ? meta.eviction_cue : undefined;
+                            }
+                            catch { /* best-effort */ }
+                        }
+                        const snippet = truncateSnippet(r.text);
+                        summaries.push({ summaryId: r.id, snippet, score: r.score, evictionCue });
+                        totalChars += snippet.length;
+                    }
+                }
+                if (scope === "messages" || scope === "both") {
+                    const searchK = Math.min(limit * 3, 200);
+                    const turnResults = await client.searchText({
+                        collection: `session_raw:${sessionId}`,
+                        text: pattern,
+                        k: searchK,
+                    });
+                    for (const r of (turnResults.results ?? [])) {
+                        if (turns.length >= limit || totalChars >= MAX_GREP_CHARS)
+                            break;
+                        if (!safeMatch(r.text, pattern, mode))
+                            continue;
+                        totalMatches++;
+                        const snippet = truncateSnippet(r.text);
+                        let role = "unknown";
+                        if (r.metadataJson && r.metadataJson.length > 0) {
+                            try {
+                                const decoder = new TextDecoder();
+                                const meta = JSON.parse(decoder.decode(r.metadataJson));
+                                role = typeof meta.role === "string" ? meta.role : "unknown";
+                            }
+                            catch { /* best-effort */ }
+                        }
+                        turns.push({ turnId: r.id, snippet, role, score: r.score });
+                        totalChars += snippet.length;
+                    }
+                }
+                return jsonResult({
+                    pattern,
+                    mode,
+                    totalMatches,
+                    summaries,
+                    turns,
+                    truncated: totalChars >= MAX_GREP_CHARS,
+                });
+            }
+            catch (error) {
+                logger.warn?.(`memory_grep failed: ${formatError(error)}`);
+                return jsonResult({
+                    pattern,
+                    mode,
+                    totalMatches: 0,
+                    summaries: [],
+                    turns: [],
+                    truncated: false,
+                });
+            }
+        },
+    };
+}
+// ── Prompt guidance ──
+const RECALL_GUIDANCE = [
+    "## LibraVDB Recall",
+    "",
+    "Summaries in context are compressed maps — not the details.",
+    "Active session recall and summary expansion tools are available:",
+    "",
+    "**Tool escalation (cheap → expensive):**",
+    "1. `memory_search` — semantic search across all memory/session collections.",
+    "   Summary hits show `[Summary sum_xxx]: [cue with anchors, decisions, signals]`.",
+    "   Use these cues to decide what's worth expanding.",
+    "2. `memory_describe` — inspect a summary's metadata (cheap, no expansion).",
+    "   Returns eviction cues with child count and source turn range.",
+    "3. `memory_expand` — deep recall: walks the summary tree, returns full text.",
+    "   Use this when the eviction cue suggests the detail you need is inside.",
+    "4. `memory_grep` — search compacted history by text or regex pattern.",
+    "   Returns matching snippets with summary/turn IDs for follow-up.",
+    "",
+    "**Many questions can be answered from eviction cues alone.**",
+    "Only expand when the cue signals specific details worth the token cost.",
+    "",
+];
+export function memoryRecallPromptSection() {
+    return [...RECALL_GUIDANCE];
+}

package/dist/turn-cache.d.ts

@@ -0,0 +1,21 @@
+type AgentMessage = {
+    role: string;
+    content: string | unknown[];
+    id?: string;
+};
+export declare class TurnMemoryCache {
+    private cache;
+    constructor(maxSize?: number);
+    private cacheKey;
+    private normalize;
+    get(sessionId: string, queryHint: string): unknown | undefined;
+    set(sessionId: string, queryHint: string, value: unknown): void;
+    invalidateSession(sessionId: string): void;
+    get size(): number;
+}
+export declare function isNewUserTurn(messages: AgentMessage[]): boolean;
+export declare function detectNewTurn(messages: AgentMessage[], lastUserMessageHash: {
+    current: string | null;
+}): boolean;
+export declare function extractQueryHint(messages: AgentMessage[], stripSenderMetadata: (text: string) => string): string | null;
+export {};

package/dist/turn-cache.js

@@ -0,0 +1,103 @@
+const DEFAULT_MAX_SIZE = 100;
+class MemoryCache {
+    cache = new Map();
+    maxSize;
+    constructor(maxSize = DEFAULT_MAX_SIZE) {
+        this.maxSize = maxSize;
+    }
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return undefined;
+        this.cache.delete(key);
+        this.cache.set(key, entry);
+        return entry.value;
+    }
+    set(key, value) {
+        if (this.cache.has(key))
+            this.cache.delete(key);
+        if (this.cache.size >= this.maxSize) {
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey !== undefined)
+                this.cache.delete(firstKey);
+        }
+        this.cache.set(key, { value, timestamp: Date.now() });
+    }
+    invalidate(prefix) {
+        for (const key of this.cache.keys()) {
+            if (key.startsWith(prefix))
+                this.cache.delete(key);
+        }
+    }
+    get size() {
+        return this.cache.size;
+    }
+}
+export class TurnMemoryCache {
+    cache = new MemoryCache();
+    constructor(maxSize = DEFAULT_MAX_SIZE) {
+        this.cache = new MemoryCache(maxSize);
+    }
+    cacheKey(sessionId, queryHint) {
+        return `${sessionId}:${this.normalize(queryHint)}`;
+    }
+    normalize(text) {
+        return text.toLowerCase().replace(/\s+/g, " ").trim().slice(0, 200);
+    }
+    get(sessionId, queryHint) {
+        return this.cache.get(this.cacheKey(sessionId, queryHint));
+    }
+    set(sessionId, queryHint, value) {
+        this.cache.set(this.cacheKey(sessionId, queryHint), value);
+    }
+    invalidateSession(sessionId) {
+        this.cache.invalidate(sessionId + ":");
+    }
+    get size() {
+        return this.cache.size;
+    }
+}
+function contentHash(msg) {
+    const content = typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content);
+    let hash = 0;
+    for (let i = 0; i < content.length; i++) {
+        const ch = content.charCodeAt(i);
+        hash = ((hash << 5) - hash) + ch;
+        hash |= 0;
+    }
+    return String(hash);
+}
+export function isNewUserTurn(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const role = messages[i].role;
+        if (role === "user")
+            return true;
+        if (role === "assistant" || role === "toolResult")
+            return false;
+    }
+    return true;
+}
+export function detectNewTurn(messages, lastUserMessageHash) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i].role === "user") {
+            const hash = contentHash(messages[i]);
+            if (hash !== lastUserMessageHash.current) {
+                lastUserMessageHash.current = hash;
+                return true;
+            }
+            return false;
+        }
+    }
+    return false;
+}
+export function extractQueryHint(messages, stripSenderMetadata) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i].role === "user") {
+            const raw = messages[i].content;
+            const content = typeof raw === "string" ? raw : JSON.stringify(raw) ?? "";
+            const cleaned = stripSenderMetadata(content);
+            return cleaned.slice(0, 200);
+        }
+    }
+    return null;
+}

package/dist/types.d.ts

@@ -87,6 +87,10 @@ export interface PluginConfig {
     compactThreshold?: number;
     compactionThresholdFraction?: number;
     compactSessionTokenBudget?: number;
+    /** Token budget cap for subagent memory_expand calls. Default 8000.
+     *  Prevents a subagent from blowing its context window via repeated
+     *  expansions. Set to 0 to disable the cap entirely. */
+    subagentTokenBudget?: number;
     section7CoarseTopK?: number;
     section7SecondPassTopK?: number;
     section7Theta1?: number;
@@ -99,6 +103,7 @@ export interface PluginConfig {
     section7AuthorityAuthoredWeight?: number;
     section7AuthoritySalienceWeight?: number;
     section7RecencyAccessLambda?: number;
+    section7AuthorityAccessWeight?: number;
     recoveryFloorScore?: number;
     recoveryMinTopK?: number;
     recoveryMinConfidenceMean?: number;
@@ -124,6 +129,14 @@ export interface PluginConfig {
      * "tls"            — always use TLS regardless of address.
      * "insecure"       — always use plaintext (service mesh, tunnel). */
     grpcEndpointTlsMode?: "auto" | "tls" | "insecure";
+    /** Whether BeforeTurnKernel retrieval is enabled. Default: true */
+    beforeTurnEnabled?: boolean;
+    /** Timeout in milliseconds for the BeforeTurnKernel gRPC call. Default: 5000 */
+    beforeTurnTimeoutMs?: number;
+    /** Maximum number of retrieved memories to inject per turn. Default: 5 */
+    beforeTurnMaxMemories?: number;
+    /** Minimum similarity score (0.0–1.0) for semantic search hits. Default: 0.4 */
+    beforeTurnMinScore?: number;
 }
 export interface SearchResult {
     id: string;

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.7.0",
+  "version": "1.8.0",
   "kind": [
     "memory",
     "context-engine"
@@ -166,6 +166,21 @@
       "section7RecencyAccessLambda": {
         "type": "number"
       },
+      "section7AuthorityAccessWeight": {
+        "type": "number"
+      },
+      "subagentTokenBudget": {
+        "type": "number"
+      },
+      "beforeTurnEnabled": {
+        "type": "boolean"
+      },
+      "beforeTurnTimeoutMs": {
+        "type": "number"
+      },
+      "beforeTurnMaxMemories": {
+        "type": "number"
+      },
       "embeddingRuntimePath": {
         "type": "string",
         "description": "Path to the ONNX Runtime library visible to the daemon, for example /opt/homebrew/opt/libravdbd/models/onnxruntime/lib/libonnxruntime.dylib or /home/node/.openclaw/libravdbd/models/onnxruntime/lib/libonnxruntime.so."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xdarkicex/openclaw-memory-libravdb",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -79,6 +79,6 @@
   "dependencies": {
     "@connectrpc/connect": "^1.7.0",
     "@connectrpc/connect-node": "^1.7.0",
-    "@xdarkicex/libravdb-contracts": "^2.0.13"
+    "@xdarkicex/libravdb-contracts": "^2.0.19"
   }
 }