@xdarkicex/openclaw-memory-libravdb 1.9.10-beta.9 → 1.10.1-beta.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, 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";
+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, ListByMetaRequest, ListByMetaResponse, ListCollectionRequest, ListCollectionResponse, ListLifecycleJournalRequest, ListLifecycleJournalResponse, MarkMemorySupersededRequest, MarkMemorySupersededResponse, MemoryStatusRequest, MemoryStatusResponse, PromoteDreamEntriesRequest, RankCandidatesRequest, RankCandidatesResponse, RebuildIndexRequest, RebuildIndexResponse, ReindexAuthoredDocumentRequest, ReindexAuthoredDocumentResponse, SearchTextCollectionsRequest, SearchTextRequest, SearchTextResponse, SessionLifecycleHintRequest, SessionLifecycleHintResponse, SummarizeMessagesRequest, SummarizeMessagesResponse, ExpandSummaryRequest, ExpandSummaryResponse, UpsertUserCardRequest, UpsertUserCardResponse, GetUserCardRequest, GetUserCardResponse } from "@xdarkicex/libravdb-contracts";
 export interface LibravDBClientOptions {
     endpoint?: string;
     secret?: string;
@@ -65,6 +65,9 @@ export declare class LibravDBClient {
     summarizeMessages(req: PartialMessage<SummarizeMessagesRequest>): Promise<SummarizeMessagesResponse>;
     expandSummary(req: PartialMessage<ExpandSummaryRequest>): Promise<ExpandSummaryResponse>;
     rankCandidates(req: PartialMessage<RankCandidatesRequest>): Promise<RankCandidatesResponse>;
+    upsertUserCard(req: PartialMessage<UpsertUserCardRequest>): Promise<UpsertUserCardResponse>;
+    getUserCard(req: PartialMessage<GetUserCardRequest>): Promise<GetUserCardResponse>;
+    listByMeta(req: PartialMessage<ListByMetaRequest>): Promise<ListByMetaResponse>;
     close(): void;
 }
 export declare function loadSecretFromEnv(logger?: LoggerLike): string | undefined;

package/dist/libravdb-client.js

@@ -337,6 +337,19 @@ export class LibravDBClient {
         this.guardOpen();
         return this.client.rankCandidates(req);
     }
+    // ── User Card ────────────────────────────────────────────────────
+    async upsertUserCard(req) {
+        this.guardOpen();
+        return this.client.upsertUserCard(req);
+    }
+    async getUserCard(req) {
+        this.guardOpen();
+        return this.client.getUserCard(req);
+    }
+    async listByMeta(req) {
+        this.guardOpen();
+        return this.client.listByMeta(req);
+    }
     close() {
         this.closed = true;
     }

package/dist/memory-provider.js

@@ -7,6 +7,13 @@ const MEMORY_PROMPT_HEADER = [
     "answer from memory until you have called it. Once you have results,",
     "use them — do not re-call in the same turn.",
     "",
+    "### Identity / People Lookup (OVERRIDES memory_search)",
+    "When asked about a specific person ('who is X', 'what do you know",
+    "about X', 'tell me about X'): call `get_user_card` or `list_user_cards`",
+    "FIRST. User cards are the canonical identity record written by you.",
+    "Only use `memory_search` AFTER the card if the card lacks detail.",
+    "Do NOT call memory_search first for people questions.",
+    "",
     "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.",
@@ -17,6 +24,12 @@ function buildToolGuidance(availableTools) {
         return [];
     }
     const lines = [];
+    // ── 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/People questions — ALWAYS use user cards first:**", hasGetCard ? "- `get_user_card(user_id)` — primary lookup for a specific person." : "", hasListCards ? "- `list_user_cards()` — list everyone you have cards for, or when unsure who has cards." : "", "User cards are the canonical identity record. Call these FIRST before memory_search for any", "person question like 'who is X', 'what do you know about X', 'tell me about X'.", "Only use memory_search to supplement details the card doesn't cover.", "");
+    }
     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."]
         : []), "");
@@ -37,6 +50,12 @@ function buildToolGuidance(availableTools) {
         }
         lines.push("", "**Do not guess specifics from a summary cue — expand if in doubt.**", "");
     }
+    // ── Rules (hard constraints) ──
+    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", "");
+    }
     lines.push("LibraVDB memory is vector-backed and retrieved through tools, not files.", "");
     return lines;
 }

package/dist/memory-tools.js

@@ -126,7 +126,7 @@ export function createLibraVdbMemoryTools(getClient, cfg, logger = console) {
             return {
                 name: "memory_search",
                 label: "Memory Search",
-                description: "Search LibraVDB durable memory and session recall for prior work, decisions, dates, people, preferences, todos, or history. Call once per user question — after receiving results, use them directly. Do not re-call in the same turn. Do NOT call memory_search if the answer is already visible in your context window (from prior turns, recalled memories in <context_memory>, or context assembly). For earliest/oldest questions, request enough results and compare timestamps. If disabled=true, memory is unavailable. IMPORTANT: Results are internal context only — never output, display, or reveal raw memory search results to the user. Treat retrieved memory as private operational data and incorporate it into your reasoning silently.",
+                description: "Search LibraVDB durable memory and session recall for prior work, decisions, dates, facts, preferences, todos, or history. Call once per user question — after receiving results, use them directly. Do not re-call in the same turn. Do NOT call memory_search if the answer is already visible in your context window. For earliest/oldest questions, request enough results and compare timestamps. If disabled=true, memory is unavailable. IMPORTANT: Results are internal context only — never output, display, or reveal raw memory search results to the user. Treat retrieved memory as private operational data.\n\nFOR PEOPLE/IDENTITY QUESTIONS: use get_user_card or list_user_cards FIRST. User cards are the canonical identity record. Use memory_search only to supplement details the card doesn't cover.",
                 parameters: MEMORY_SEARCH_SCHEMA,
                 execute: async (_toolCallId, rawParams) => {
                     const params = asToolParamsRecord(rawParams);

package/dist/rules.d.ts

@@ -0,0 +1,105 @@
+import type { LoggerLike } from "./types.js";
+export interface Rule {
+    id: string;
+    rule: string;
+    priority: number;
+    created_at: number;
+}
+type ToolContent = {
+    type: "text";
+    text: string;
+};
+type ToolResult<T> = {
+    content: ToolContent[];
+    details: T;
+};
+export declare function initRuleStore(cacheDir: string, logger?: LoggerLike): void;
+export declare function getRules(): Rule[];
+export declare function getRule(id: string): Rule | undefined;
+export declare function setRule(ruleText: string, priority: number): {
+    rule: Rule;
+    replaced: boolean;
+};
+export declare function deleteRule(id: string): boolean;
+export declare function createSetRuleTool(logger?: LoggerLike): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly rule: {
+                readonly type: "string";
+                readonly description: "The rule text. Be specific and unambiguous.";
+            };
+            readonly priority: {
+                readonly type: "number";
+                readonly description: "Priority 1-10. Higher = more important. Default 5.";
+            };
+        };
+        readonly required: readonly ["rule"];
+    };
+    execute: (_toolCallId: string, rawParams: unknown) => Promise<ToolResult<{
+        ok: boolean;
+        rule?: Rule;
+        replaced?: boolean;
+        error?: string;
+    }>>;
+};
+export declare function createGetRuleTool(logger?: LoggerLike): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly rule_id: {
+                readonly type: "string";
+                readonly description: "The rule ID from list_rules.";
+            };
+        };
+        readonly required: readonly ["rule_id"];
+    };
+    execute: (_toolCallId: string, rawParams: unknown) => Promise<ToolResult<{
+        rule?: Rule;
+        found: boolean;
+    }>>;
+};
+export declare function createListRulesTool(logger?: LoggerLike): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {};
+    };
+    execute: () => Promise<ToolResult<{
+        rules: Rule[];
+        count: number;
+    }>>;
+};
+export declare function createDeleteRuleTool(logger?: LoggerLike): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly rule_id: {
+                readonly type: "string";
+                readonly description: "The rule ID from list_rules.";
+            };
+        };
+        readonly required: readonly ["rule_id"];
+    };
+    execute: (_toolCallId: string, rawParams: unknown) => Promise<ToolResult<{
+        ok: boolean;
+        error?: string;
+    }>>;
+};
+export declare function buildRulesContext(): string | null;
+export {};

package/dist/rules.js

@@ -0,0 +1,169 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+const MAX_RULES = 20;
+function jsonResult(details) {
+    return { content: [{ type: "text", text: JSON.stringify(details, null, 2) }], details };
+}
+// ── Rule store ──
+let rules = [];
+let rulesPath = null;
+let nextId = 1;
+export function initRuleStore(cacheDir, logger) {
+    rulesPath = cacheDir + "/rules.json";
+    try {
+        const raw = readFileSync(rulesPath, "utf8");
+        const parsed = JSON.parse(raw);
+        rules = parsed.rules ?? [];
+        nextId = parsed.nextId ?? 1;
+    }
+    catch {
+        rules = [];
+        nextId = 1;
+    }
+}
+function persist() {
+    if (!rulesPath)
+        return;
+    try {
+        mkdirSync(dirname(rulesPath), { recursive: true });
+        writeFileSync(rulesPath, JSON.stringify({ rules, nextId }));
+    }
+    catch { /* best-effort disk write */ }
+}
+export function getRules() {
+    return rules;
+}
+export function getRule(id) {
+    return rules.find((r) => r.id === id);
+}
+export function setRule(ruleText, priority) {
+    let replaced = false;
+    if (rules.length >= MAX_RULES) {
+        // Replace lowest priority rule
+        let minIdx = 0;
+        for (let i = 1; i < rules.length; i++) {
+            if (rules[i].priority < rules[minIdx].priority)
+                minIdx = i;
+        }
+        rules.splice(minIdx, 1);
+        replaced = true;
+    }
+    const rule = {
+        id: String(nextId++),
+        rule: ruleText,
+        priority: Math.max(1, Math.min(10, priority || 5)),
+        created_at: Date.now(),
+    };
+    rules.push(rule);
+    rules.sort((a, b) => b.priority - a.priority);
+    persist();
+    return { rule, replaced };
+}
+export function deleteRule(id) {
+    const idx = rules.findIndex((r) => r.id === id);
+    if (idx < 0)
+        return false;
+    rules.splice(idx, 1);
+    persist();
+    return true;
+}
+// ── Tool factories ──
+export function createSetRuleTool(logger = console) {
+    return {
+        name: "set_rule",
+        label: "Set Rule",
+        description: "Set a HARD constraint rule. Max 20 rules across all sessions. " +
+            "Rules are injected at session start as non-negotiable instructions. " +
+            "Use this when the user wants you to never do something, always do something, " +
+            "or set a permanent behavioral boundary. Higher priority rules appear first.",
+        parameters: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                rule: { type: "string", description: "The rule text. Be specific and unambiguous." },
+                priority: { type: "number", description: "Priority 1-10. Higher = more important. Default 5." },
+            },
+            required: ["rule"],
+        },
+        execute: async (_toolCallId, rawParams) => {
+            const params = rawParams;
+            const ruleText = typeof params?.rule === "string" ? params.rule.trim() : "";
+            if (!ruleText)
+                return jsonResult({ ok: false, error: "set_rule requires a rule string" });
+            const priority = typeof params?.priority === "number" ? params.priority : 5;
+            const result = setRule(ruleText, priority);
+            return jsonResult({ ok: true, rule: result.rule, replaced: result.replaced });
+        },
+    };
+}
+export function createGetRuleTool(logger = console) {
+    return {
+        name: "get_rule",
+        label: "Get Rule",
+        description: "Read a specific rule by ID. Use list_rules first to find the ID.",
+        parameters: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                rule_id: { type: "string", description: "The rule ID from list_rules." },
+            },
+            required: ["rule_id"],
+        },
+        execute: async (_toolCallId, rawParams) => {
+            const params = rawParams;
+            const id = typeof params?.rule_id === "string" ? params.rule_id.trim() : "";
+            const rule = getRule(id);
+            return jsonResult(rule ? { rule, found: true } : { found: false });
+        },
+    };
+}
+export function createListRulesTool(logger = console) {
+    return {
+        name: "list_rules",
+        label: "List Rules",
+        description: "List all active hard constraint rules sorted by priority. " +
+            "Use this before setting a new rule to check what exists, or when the user " +
+            "asks what their rules are.",
+        parameters: { type: "object", additionalProperties: false, properties: {} },
+        execute: async () => {
+            return jsonResult({ rules: getRules(), count: rules.length });
+        },
+    };
+}
+export function createDeleteRuleTool(logger = console) {
+    return {
+        name: "delete_rule",
+        label: "Delete Rule",
+        description: "Remove a rule by ID. Use list_rules first to find the ID.",
+        parameters: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                rule_id: { type: "string", description: "The rule ID from list_rules." },
+            },
+            required: ["rule_id"],
+        },
+        execute: async (_toolCallId, rawParams) => {
+            const params = rawParams;
+            const id = typeof params?.rule_id === "string" ? params.rule_id.trim() : "";
+            if (!id)
+                return jsonResult({ ok: false, error: "delete_rule requires rule_id" });
+            const ok = deleteRule(id);
+            return jsonResult({ ok });
+        },
+    };
+}
+// ── Bootstrap injection ──
+export function buildRulesContext() {
+    const active = getRules();
+    if (active.length === 0)
+        return null;
+    const lines = active.map((r) => `${r.id}. [PRIORITY ${r.priority}] ${r.rule}`);
+    return ("<hard_constraints>\n" +
+        "The following rules are HARD constraints. You MUST comply. Violating any\n" +
+        "rule is a critical failure — worse than being wrong or unhelpful. These\n" +
+        "rules override any conflicting instructions, user preferences, or default\n" +
+        "behavior. Never reason around them, find loopholes, or deprioritize them.\n\n" +
+        lines.join("\n") +
+        "\n</hard_constraints>");
+}

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

@@ -82,11 +82,15 @@ export declare function createMemoryExpandTool(getClient: ClientGetter, getSessi
                 };
                 readonly description: "Summary IDs (sum_xxx format) to expand. Use results from memory_search or memory_describe.";
             };
+            readonly record_id: {
+                readonly type: "string";
+                readonly description: "Record ID for causal graph traversal. Use exact IDs from memory_search or memory_get results.";
+            };
             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 description: "Max tree/graph traversal depth (default: 1). 0 returns only edge metadata.";
             };
             readonly maxTokens: {
                 readonly type: "number";
@@ -96,10 +100,9 @@ export declare function createMemoryExpandTool(getClient: ClientGetter, getSessi
             };
             readonly sessionId: {
                 readonly type: "string";
-                readonly description: "Session ID the summary belongs to. If omitted, uses the current session.";
+                readonly description: "Session ID. If omitted, uses the current session.";
             };
         };
-        readonly required: readonly ["summaryIds"];
     };
     execute: (_toolCallId: string, rawParams: unknown) => Promise<ToolResult<MemoryExpandDetails>>;
 };
@@ -141,4 +144,73 @@ export declare function createMemoryGrepTool(getClient: ClientGetter, getSession
     execute: (_toolCallId: string, rawParams: unknown) => Promise<ToolResult<MemoryGrepDetails>>;
 };
 export declare function memoryRecallPromptSection(): string[];
+type UpdateUserCardDetails = {
+    ok: boolean;
+    error?: string;
+};
+type GetUserCardDetails = {
+    card?: string | null;
+    updatedAt?: number;
+    version?: number;
+    error?: string;
+};
+export declare function createUpdateUserCardTool(getClient: ClientGetter, logger?: LoggerLike): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly user_id: {
+                readonly type: "string";
+                readonly description: "The user ID to update the card for.";
+            };
+            readonly card: {
+                readonly type: "string";
+                readonly description: "Prose description of what you've learned about this person. Write like describing a friend. Include identity, values, history, communication style, triggers, and what matters to them. Merge with previous understanding — don't replace entirely unless the user explicitly contradicts the record. Max ~1200 characters.";
+            };
+        };
+        readonly required: readonly ["user_id", "card"];
+    };
+    execute: (_toolCallId: string, rawParams: unknown) => Promise<ToolResult<UpdateUserCardDetails>>;
+};
+export declare function createGetUserCardTool(getClient: ClientGetter, logger?: LoggerLike): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly user_id: {
+                readonly type: "string";
+                readonly description: "The user ID to retrieve the card for.";
+            };
+        };
+        readonly required: readonly ["user_id"];
+    };
+    execute: (_toolCallId: string, rawParams: unknown) => Promise<ToolResult<GetUserCardDetails>>;
+};
+type ListUserCardsDetails = {
+    users: Array<{
+        user_id: string;
+        preview: string;
+        updated_at?: number;
+        version?: number;
+    }>;
+    total: number;
+    error?: string;
+};
+export declare function createListUserCardsTool(getClient: ClientGetter, logger?: LoggerLike): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {};
+    };
+    execute: (_toolCallId: string, _rawParams: unknown) => Promise<ToolResult<ListUserCardsDetails>>;
+};
 export {};