@xdarkicex/openclaw-memory-libravdb 1.7.0 → 1.8.1

package/dist/libravdb-client.d.ts

@@ -1,7 +1,7 @@
 import type { Interceptor } from "@connectrpc/connect";
 import type { PartialMessage } from "@bufbuild/protobuf";
 import type { LoggerLike } from "./types.js";
-import type { AfterTurnKernelRequest, AfterTurnKernelResponse, AssembleContextInternalRequest, AssembleContextInternalResponse, BootstrapSessionKernelRequest, BootstrapSessionKernelResponse, CompactSessionRequest, CompactSessionResponse, DeleteAuthoredDocumentRequest, DeleteAuthoredDocumentResponse, DreamPromotionResponse, ExportMemoryRequest, ExportMemoryResponse, FlushNamespaceRequest, FlushNamespaceResponse, FlushRequest, FlushResponse, HealthRequest, HealthResponse, IngestMarkdownDocumentRequest, IngestMarkdownDocumentResponse, IngestMessageKernelRequest, IngestMessageKernelResponse, ListCollectionRequest, ListCollectionResponse, ListLifecycleJournalRequest, ListLifecycleJournalResponse, MarkMemorySupersededRequest, MarkMemorySupersededResponse, MemoryStatusRequest, MemoryStatusResponse, PromoteDreamEntriesRequest, RankCandidatesRequest, RankCandidatesResponse, RebuildIndexRequest, RebuildIndexResponse, ReindexAuthoredDocumentRequest, ReindexAuthoredDocumentResponse, SearchTextCollectionsRequest, SearchTextRequest, SearchTextResponse, SessionLifecycleHintRequest, SessionLifecycleHintResponse } from "@xdarkicex/libravdb-contracts";
+import type { AfterTurnKernelRequest, AfterTurnKernelResponse, BeforeTurnKernelRequest, BeforeTurnKernelResponse, AssembleContextInternalRequest, AssembleContextInternalResponse, BootstrapSessionKernelRequest, BootstrapSessionKernelResponse, CompactSessionRequest, CompactSessionResponse, DeleteAuthoredDocumentRequest, DeleteAuthoredDocumentResponse, DreamPromotionResponse, ExportMemoryRequest, ExportMemoryResponse, FlushNamespaceRequest, FlushNamespaceResponse, FlushRequest, FlushResponse, HealthRequest, HealthResponse, IngestMarkdownDocumentRequest, IngestMarkdownDocumentResponse, IngestMessageKernelRequest, IngestMessageKernelResponse, ListCollectionRequest, ListCollectionResponse, ListLifecycleJournalRequest, ListLifecycleJournalResponse, MarkMemorySupersededRequest, MarkMemorySupersededResponse, MemoryStatusRequest, MemoryStatusResponse, PromoteDreamEntriesRequest, RankCandidatesRequest, RankCandidatesResponse, RebuildIndexRequest, RebuildIndexResponse, ReindexAuthoredDocumentRequest, ReindexAuthoredDocumentResponse, SearchTextCollectionsRequest, SearchTextRequest, SearchTextResponse, SessionLifecycleHintRequest, SessionLifecycleHintResponse, SummarizeMessagesRequest, SummarizeMessagesResponse, ExpandSummaryRequest, ExpandSummaryResponse } from "@xdarkicex/libravdb-contracts";
 export interface LibravDBClientOptions {
     endpoint?: string;
     secret?: string;
@@ -59,8 +59,11 @@ export declare class LibravDBClient {
     bootstrapSessionKernel(req: PartialMessage<BootstrapSessionKernelRequest>): Promise<BootstrapSessionKernelResponse>;
     ingestMessageKernel(req: PartialMessage<IngestMessageKernelRequest>): Promise<IngestMessageKernelResponse>;
     afterTurnKernel(req: PartialMessage<AfterTurnKernelRequest>): Promise<AfterTurnKernelResponse>;
+    beforeTurnKernel(req: PartialMessage<BeforeTurnKernelRequest>): Promise<BeforeTurnKernelResponse>;
     assembleContextInternal(req: PartialMessage<AssembleContextInternalRequest>): Promise<AssembleContextInternalResponse>;
     compactSession(req: PartialMessage<CompactSessionRequest>): Promise<CompactSessionResponse>;
+    summarizeMessages(req: PartialMessage<SummarizeMessagesRequest>): Promise<SummarizeMessagesResponse>;
+    expandSummary(req: PartialMessage<ExpandSummaryRequest>): Promise<ExpandSummaryResponse>;
     rankCandidates(req: PartialMessage<RankCandidatesRequest>): Promise<RankCandidatesResponse>;
     close(): void;
 }

package/dist/libravdb-client.js

@@ -313,6 +313,10 @@ export class LibravDBClient {
         this.guardOpen();
         return this.client.afterTurnKernel(req);
     }
+    async beforeTurnKernel(req) {
+        this.guardOpen();
+        return this.client.beforeTurnKernel(req);
+    }
     async assembleContextInternal(req) {
         this.guardOpen();
         return this.client.assembleContextInternal(req);
@@ -321,6 +325,14 @@ export class LibravDBClient {
         this.guardOpen();
         return this.client.compactSession(req);
     }
+    async summarizeMessages(req) {
+        this.guardOpen();
+        return this.client.summarizeMessages(req);
+    }
+    async expandSummary(req) {
+        this.guardOpen();
+        return this.client.expandSummary(req);
+    }
     async rankCandidates(req) {
         this.guardOpen();
         return this.client.rankCandidates(req);

package/dist/memory-provider.js

@@ -1,34 +1,47 @@
 const MEMORY_PROMPT_HEADER = [
-    "## Memory",
-    "LibraVDB persistent memory is configured. Every turn is auto-ingested",
-    "into the vector store — you do not need to explicitly save anything.",
-    "When asked about past conversations, facts, preferences, decisions,",
-    "or anything the user might have told you before, call `memory_search`",
-    "once per user question. Do not answer from memory until you have",
-    "called it. Once you have results, use them — do not re-call.",
+    "## LibraVDB Memory",
+    "Every turn is auto-ingested into the vector store — you do not need",
+    "to explicitly save anything. When asked about past conversations,",
+    "facts, preferences, decisions, or anything the user might have told",
+    "you before, call `memory_search` once per user question. Do not",
+    "answer from memory until you have called it. Once you have results,",
+    "use them — do not re-call in the same turn.",
+    "",
+    "Conversations are captured automatically. Never say \"I'll remember",
+    "that,\" \"I've saved this,\" \"noted,\" or similar — these phrases suggest",
+    "manual effort where none exists. Just act on the request.",
     "",
 ];
 function buildToolGuidance(availableTools) {
     if (!availableTools?.has("memory_search")) {
         return [];
     }
-    return [
-        "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.",
-        "For earliest or oldest questions, request enough results and compare timestamps.",
-        ...(availableTools.has("memory_get")
-            ? ["After a `memory_search` hit, call `memory_get` when exact wording or more context is needed."]
-            : []),
-        "LibraVDB memory is vector-backed and retrieved through tools, not files.",
-        "",
-    ];
+    const lines = [];
+    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."]
+        : []), "");
+    // ── 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) {
+            lines.push("1. `memory_describe(summaryId)` — inspect a summary's metadata.", "   Returns eviction cues, child count, and source turn range.", "   Cheap — use this to decide whether expansion is worth it.");
+        }
+        if (hasExpand) {
+            lines.push("2. `memory_expand(summaryIds)` — deep recall. Walks the summary tree", "   and returns full detail. Use when the eviction cue signals specific", "   details you need. For large expansions may spawn a sub-agent to", "   protect your context window.");
+        }
+        if (hasGrep) {
+            lines.push("3. `memory_grep(pattern)` — search compacted history by text or regex.", "   Returns snippets with summary/turn IDs for follow-up.");
+        }
+        lines.push("", "**Do not guess specifics from a summary cue — expand if in doubt.**", "");
+    }
+    lines.push("LibraVDB memory is vector-backed and retrieved through tools, not files.", "");
+    return lines;
 }
 export function buildMemoryPromptSection(_getClient, _cfg) {
     return function memoryPromptSection({ availableTools, citationsMode: _citationsMode, }) {
-        // OpenClaw builds the memory prompt section synchronously for embedded runs.
-        // Actual retrieval and ranking happen in the context engine during assemble().
         return [...MEMORY_PROMPT_HEADER, ...buildToolGuidance(availableTools)];
     };
 }

package/dist/memory-runtime.d.ts

@@ -15,6 +15,8 @@ type MemorySearchParams = {
     agentId?: string;
     sessionId?: string;
     sessionKey?: string;
+    kind?: string;
+    signals?: string[];
     context?: {
         userId?: string;
         agentId?: string;

package/dist/memory-runtime.js

@@ -72,7 +72,7 @@ function createMemorySearchManager(getClient, cfg, defaults, initialStatus) {
                     text: queryText,
                     k,
                 })
-                : await searchResolvedCollections(client, cfg, userId, sessionId, queryText, k, searchCorpus);
+                : await searchResolvedCollections(client, cfg, userId, sessionId, queryText, k, searchCorpus, params.kind, params.signals);
             const filteredResults = minScore === undefined
                 ? result.results
                 : result.results.filter((item) => item.score >= minScore);
@@ -138,22 +138,28 @@ function createMemorySearchManager(getClient, cfg, defaults, initialStatus) {
         },
     };
 }
-async function searchResolvedCollections(client, cfg, userId, sessionId, queryText, k, corpus) {
+async function searchResolvedCollections(client, cfg, userId, sessionId, queryText, k, corpus, kind, signals) {
     const collections = resolveSearchCollections(cfg, userId, sessionId, corpus);
     if (collections.length === 0) {
         return { results: [] };
     }
+    const kindFilter = kind || undefined;
+    const signalFilter = (signals && signals.length > 0) ? signals : undefined;
     return collections.length === 1
         ? await client.searchText({
             collection: collections[0],
             text: queryText,
             k,
+            kind: kindFilter,
+            signals: signalFilter,
         })
         : await client.searchTextCollections({
             collections,
             text: queryText,
             k,
             excludeByCollection: {},
+            kind: kindFilter,
+            signals: signalFilter,
         });
 }
 function resolveSearchCollections(cfg, userId, sessionId, corpus) {

package/dist/memory-tools.js

@@ -25,6 +25,16 @@ const MEMORY_SEARCH_SCHEMA = {
             enum: ["memory", "wiki", "all", "sessions"],
             description: "Corpus filter. LibraVDB serves memory/session hits; wiki is unsupported unless another plugin owns wiki tools.",
         },
+        kind: {
+            type: "string",
+            enum: ["identity", "fact", "preference", "constraint", "decision", "episode"],
+            description: "Cognitive kind filter. Only return memories of this kind. Use 'constraint' to retrieve operating boundaries, 'decision' for past decisions, etc.",
+        },
+        signals: {
+            type: "array",
+            items: { type: "string", enum: ["deontic", "identity", "preference", "factual", "temporal"] },
+            description: "Signal bitmask filter. Only return memories carrying at least one of these signals.",
+        },
     },
     required: ["query"],
 };
@@ -57,6 +67,34 @@ const MEMORY_GET_SCHEMA = {
 export function createLibraVdbMemoryTools(getClient, cfg, logger = console) {
     const bridge = buildMemoryRuntimeBridge(getClient, cfg);
     const managers = new Map();
+    // Turn-scoped search dedup: blocks repeated searches within the same turn.
+    // The model sometimes loops memory_search with slight query variations;
+    // this enforces "once per turn" at the tool level, not just the prompt.
+    const turnSearchKeys = new Map();
+    const TURN_SEARCH_MAX_KEYS = 500;
+    function dedupKey(sessionKey, query) {
+        return `${sessionKey}:${query.toLowerCase().replace(/\s+/g, " ").trim().slice(0, 80)}`;
+    }
+    function isDuplicateSearch(sessionKey, query) {
+        if (!sessionKey)
+            return false;
+        const key = dedupKey(sessionKey, query);
+        const keys = turnSearchKeys.get(sessionKey);
+        if (!keys) {
+            turnSearchKeys.set(sessionKey, new Set([key]));
+            // Prune stale entries.
+            if (turnSearchKeys.size > TURN_SEARCH_MAX_KEYS) {
+                const oldest = turnSearchKeys.keys().next().value;
+                if (oldest !== undefined)
+                    turnSearchKeys.delete(oldest);
+            }
+            return false;
+        }
+        if (keys.has(key))
+            return true;
+        keys.add(key);
+        return false;
+    }
     async function getManager(ctx, purpose) {
         const key = managerCacheKey(ctx);
         let manager = managers.get(key);
@@ -85,7 +123,16 @@ export function createLibraVdbMemoryTools(getClient, cfg, logger = console) {
                 execute: async (_toolCallId, rawParams) => {
                     const params = asToolParamsRecord(rawParams);
                     const query = readRequiredStringParam(params, "query");
+                    const sessionKey = ctx.sessionKey ?? "";
+                    if (isDuplicateSearch(sessionKey, query)) {
+                        return jsonToolResult({
+                            results: [],
+                            error: `Duplicate search blocked. You already searched this turn — use the previous results. Do not call memory_search again.`,
+                        });
+                    }
                     const corpus = readMemoryCorpus(params.corpus);
+                    const kind = typeof params.kind === "string" ? params.kind : undefined;
+                    const signals = Array.isArray(params.signals) ? params.signals.filter((s) => typeof s === "string") : undefined;
                     const maxResults = readNumberParam(params, "maxResults", { integer: true });
                     const minScore = readNumberParam(params, "minScore");
                     if (corpus === "wiki") {
@@ -102,6 +149,8 @@ export function createLibraVdbMemoryTools(getClient, cfg, logger = console) {
                             corpus,
                             ...(maxResults !== undefined ? { maxResults } : {}),
                             ...(minScore !== undefined ? { minScore } : {}),
+                            ...(kind !== undefined ? { kind } : {}),
+                            ...(signals !== undefined ? { signals } : {}),
                             ...buildSearchContext(ctx),
                         });
                         const results = filterResultsByCorpus(rawResults, corpus);

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

@@ -0,0 +1,144 @@
+import type { ClientGetter } from "../plugin-runtime.js";
+import type { LoggerLike } from "../types.js";
+type ToolContent = {
+    type: "text";
+    text: string;
+};
+type ToolResult<T> = {
+    content: ToolContent[];
+    details: T;
+};
+type MemoryDescribeDetails = {
+    summaryId: string;
+    found: boolean;
+    evictionCue?: string;
+    depth?: number;
+    descendantCount?: number;
+    sourceTurnCount?: number;
+    sourceTurnIds?: string[];
+    parentSummaryIds?: string[];
+    error?: string;
+};
+type MemoryExpandDetails = {
+    summaryId: string;
+    depth: number;
+    text: string;
+    truncated: boolean;
+    exceededBudget: boolean;
+    parentCount: number;
+    error?: string;
+};
+type MemoryGrepDetails = {
+    pattern: string;
+    mode: "regex" | "text";
+    totalMatches: number;
+    summaries: Array<{
+        summaryId: string;
+        snippet: string;
+        score: number;
+        evictionCue?: string;
+    }>;
+    turns: Array<{
+        turnId: string;
+        snippet: string;
+        role: string;
+        score: number;
+    }>;
+    truncated: boolean;
+};
+export declare function createMemoryDescribeTool(getClient: ClientGetter, logger?: LoggerLike): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly summaryId: {
+                readonly type: "string";
+                readonly description: "A summary ID (sum_xxx format) returned by memory_search. Inspect metadata without expanding.";
+            };
+            readonly sessionId: {
+                readonly type: "string";
+                readonly description: "Session ID the summary belongs to. If omitted, uses the current session.";
+            };
+        };
+        readonly required: readonly ["summaryId"];
+    };
+    execute: (_toolCallId: string, rawParams: unknown) => Promise<ToolResult<MemoryDescribeDetails>>;
+};
+export declare function createMemoryExpandTool(getClient: ClientGetter, getSessionKey: () => string | undefined, logger?: LoggerLike): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly summaryIds: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "Summary IDs (sum_xxx format) to expand. Use results from memory_search or memory_describe.";
+            };
+            readonly maxDepth: {
+                readonly type: "number";
+                readonly minimum: 0;
+                readonly maximum: 5;
+                readonly description: "Max tree traversal depth per summary (default: 1). 0 returns only the cue/metadata.";
+            };
+            readonly maxTokens: {
+                readonly type: "number";
+                readonly minimum: 100;
+                readonly maximum: number;
+                readonly description: "Token budget cap for the expansion result (default: 8000).";
+            };
+            readonly sessionId: {
+                readonly type: "string";
+                readonly description: "Session ID the summary belongs to. If omitted, uses the current session.";
+            };
+        };
+        readonly required: readonly ["summaryIds"];
+    };
+    execute: (_toolCallId: string, rawParams: unknown) => Promise<ToolResult<MemoryExpandDetails>>;
+};
+export declare function createMemoryGrepTool(getClient: ClientGetter, logger?: LoggerLike): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly pattern: {
+                readonly type: "string";
+                readonly description: "Search pattern. Regex when mode=regex, plain text when mode=text.";
+            };
+            readonly mode: {
+                readonly type: "string";
+                readonly enum: readonly ["regex", "text"];
+                readonly description: "Search mode. Default: \"text\".";
+            };
+            readonly scope: {
+                readonly type: "string";
+                readonly enum: readonly ["messages", "summaries", "both"];
+                readonly description: "What to search. Default: \"both\".";
+            };
+            readonly limit: {
+                readonly type: "number";
+                readonly minimum: 1;
+                readonly maximum: 200;
+                readonly description: "Max results (default: 50).";
+            };
+            readonly sessionId: {
+                readonly type: "string";
+                readonly description: "Session ID to search within. If omitted, uses the current session.";
+            };
+        };
+        readonly required: readonly ["pattern"];
+    };
+    execute: (_toolCallId: string, rawParams: unknown) => Promise<ToolResult<MemoryGrepDetails>>;
+};
+export declare function memoryRecallPromptSection(): string[];
+export {};