@xdarkicex/openclaw-memory-libravdb 1.4.5 → 1.4.7

package/dist/dream-promotion.js

@@ -0,0 +1,363 @@
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { getHashBackendName, hashBytes } from "./markdown-hash.js";
+const DEFAULT_DEBOUNCE_MS = 150;
+const DEFAULT_MIN_SCORE = 0.6;
+const DEFAULT_MIN_RECALL_COUNT = 2;
+const DEFAULT_MIN_UNIQUE_QUERIES = 2;
+const DREAM_PROMOTION_VERSION = 1;
+const DREAM_SOURCE_KIND = "dream";
+export function createDreamPromotionHandle(cfg, getRpc, logger = console, fsApi = createRealFsApi()) {
+    const diaryPath = normalizeDiaryPath(cfg.dreamPromotionDiaryPath);
+    const userId = cfg.dreamPromotionUserId?.trim() ?? "";
+    if (cfg.dreamPromotionEnabled !== true || !diaryPath || !userId) {
+        return {
+            async start() { },
+            async refresh() { },
+            async stop() { },
+        };
+    }
+    const state = {
+        watching: false,
+        dirty: false,
+        timer: null,
+        watcher: null,
+    };
+    let lastFileState = null;
+    const debounceMs = cfg.dreamPromotionDebounceMs ?? DEFAULT_DEBOUNCE_MS;
+    return {
+        async start() {
+            if (state.watching) {
+                return;
+            }
+            state.watching = true;
+            await refreshDiary();
+        },
+        async refresh() {
+            await refreshDiary();
+        },
+        async stop() {
+            state.watching = false;
+            if (state.timer) {
+                clearTimeout(state.timer);
+                state.timer = null;
+            }
+            if (state.watcher) {
+                state.watcher.close();
+                state.watcher = null;
+            }
+        },
+    };
+    async function refreshDiary() {
+        if (!state.watching) {
+            return;
+        }
+        if (state.timer) {
+            state.dirty = true;
+            return;
+        }
+        state.timer = setTimeout(() => {
+            state.timer = null;
+            void scanDiary().catch((error) => {
+                logger.warn?.(`[dream-promotion] refresh failed for ${diaryPath}: ${formatError(error)}`);
+            });
+        }, debounceMs);
+    }
+    async function scanDiary() {
+        if (!state.watching) {
+            return;
+        }
+        await ensureWatcher();
+        const stat = await safeStat(diaryPath);
+        if (!stat) {
+            lastFileState = null;
+            return;
+        }
+        if (lastFileState && lastFileState.size === stat.size && lastFileState.mtimeMs === stat.mtimeMs) {
+            return;
+        }
+        const bytes = await safeReadFile(diaryPath);
+        if (!bytes) {
+            lastFileState = null;
+            return;
+        }
+        const fileHash = hashBytes(bytes);
+        if (lastFileState && lastFileState.fileHash === fileHash) {
+            lastFileState = {
+                size: stat.size,
+                mtimeMs: stat.mtimeMs,
+                fileHash,
+            };
+            return;
+        }
+        const text = textDecoder.decode(bytes);
+        const candidates = parseDreamPromotionCandidates(text);
+        if (candidates.length === 0) {
+            lastFileState = {
+                size: stat.size,
+                mtimeMs: stat.mtimeMs,
+                fileHash,
+            };
+            return;
+        }
+        const rpc = await getRpc();
+        const params = {
+            userId,
+            sourceDoc: diaryPath,
+            sourceRoot: path.dirname(diaryPath),
+            sourcePath: path.basename(diaryPath),
+            sourceKind: DREAM_SOURCE_KIND,
+            fileHash,
+            sourceSize: stat.size,
+            sourceMtimeMs: stat.mtimeMs,
+            ingestVersion: DREAM_PROMOTION_VERSION,
+            hashBackend: getHashBackendName(),
+            entries: candidates.map((candidate, index) => ({
+                ...candidate,
+                sourceLine: candidate.line,
+                line: index + 1,
+            })),
+        };
+        await rpc.call("promote_dream_entries", params);
+        lastFileState = {
+            size: stat.size,
+            mtimeMs: stat.mtimeMs,
+            fileHash,
+        };
+        if (state.dirty) {
+            state.dirty = false;
+            await refreshDiary();
+        }
+    }
+    async function safeStat(filePath) {
+        try {
+            return await fsApi.stat(filePath);
+        }
+        catch {
+            return null;
+        }
+    }
+    async function safeReadFile(filePath) {
+        try {
+            return await fsApi.readFile(filePath);
+        }
+        catch {
+            return null;
+        }
+    }
+    async function ensureWatcher() {
+        if (state.watcher) {
+            return;
+        }
+        const parentDir = path.dirname(diaryPath);
+        try {
+            const watcher = fsApi.watch(parentDir, (_event, filename) => {
+                if (filename && path.basename(String(filename)) !== path.basename(diaryPath)) {
+                    return;
+                }
+                state.dirty = true;
+                void refreshDiary();
+            });
+            watcher.on("error", (error) => {
+                logger.warn?.(`[dream-promotion] watch error for ${parentDir}: ${formatError(error)}`);
+            });
+            state.watcher = watcher;
+        }
+        catch (error) {
+            logger.warn?.(`[dream-promotion] watch unavailable for ${parentDir}: ${formatError(error)}`);
+        }
+    }
+}
+export async function promoteDreamDiaryFile(rpc, opts) {
+    const diaryPath = normalizeDiaryPath(opts.diaryPath);
+    if (!diaryPath) {
+        throw new Error("dream diary path is required");
+    }
+    const userId = opts.userId.trim();
+    if (!userId) {
+        throw new Error("user id is required");
+    }
+    let text = opts.text;
+    let fileHash = opts.fileHash;
+    let sourceSize = opts.sourceSize;
+    let sourceMtimeMs = opts.sourceMtimeMs;
+    if (text == null) {
+        const bytes = await fsp.readFile(diaryPath);
+        text = textDecoder.decode(bytes);
+        fileHash = fileHash ?? hashBytes(bytes);
+        const stat = await fsp.stat(diaryPath);
+        sourceSize = sourceSize ?? stat.size;
+        sourceMtimeMs = sourceMtimeMs ?? stat.mtimeMs;
+    }
+    const candidates = parseDreamPromotionCandidates(text);
+    return await rpc.call("promote_dream_entries", {
+        userId,
+        sourceDoc: diaryPath,
+        sourceRoot: path.dirname(diaryPath),
+        sourcePath: path.basename(diaryPath),
+        sourceKind: DREAM_SOURCE_KIND,
+        fileHash: fileHash ?? "",
+        sourceSize: sourceSize ?? 0,
+        sourceMtimeMs: sourceMtimeMs ?? 0,
+        ingestVersion: DREAM_PROMOTION_VERSION,
+        hashBackend: getHashBackendName(),
+        entries: candidates.map((candidate, index) => ({
+            ...candidate,
+            sourceLine: candidate.line,
+            line: index + 1,
+        })),
+    });
+}
+export function parseDreamPromotionCandidates(text) {
+    const candidates = [];
+    const lines = text.split("\n");
+    let inFence = false;
+    let activeSection = "";
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index] ?? "";
+        const trimmed = line.trimStart();
+        if (trimmed.startsWith("```") || trimmed.startsWith("~~~")) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence) {
+            continue;
+        }
+        const heading = parseHeading(trimmed);
+        if (heading) {
+            activeSection = heading;
+            continue;
+        }
+        if (!isPromotionSection(activeSection)) {
+            continue;
+        }
+        const bullet = parseBulletCandidate(line);
+        if (!bullet) {
+            continue;
+        }
+        const metadata = parseTrailingMetadata(bullet.body);
+        if (!metadata) {
+            continue;
+        }
+        const textValue = bullet.body.slice(0, metadata.bodyStart).trim();
+        if (!textValue) {
+            continue;
+        }
+        candidates.push({
+            text: textValue,
+            score: metadata.score,
+            recallCount: metadata.recallCount,
+            uniqueQueries: metadata.uniqueQueries,
+            section: activeSection,
+            line: index + 1,
+        });
+    }
+    return candidates;
+}
+function parseHeading(value) {
+    const match = /^(#{2,6})\s+(.+)$/.exec(value);
+    if (!match) {
+        return null;
+    }
+    return normalizeSectionName(match[2] ?? "");
+}
+function isPromotionSection(section) {
+    return section.includes("deep sleep") || section.includes("promot") || section.includes("dream");
+}
+function parseBulletCandidate(line) {
+    const match = /^\s*[-*+]\s+(.+)$/.exec(line);
+    if (!match) {
+        return null;
+    }
+    return { body: match[1] ?? "" };
+}
+function parseTrailingMetadata(body) {
+    const trimmed = body.trimEnd();
+    if (!trimmed.endsWith("}")) {
+        return null;
+    }
+    const open = trimmed.lastIndexOf("{");
+    if (open < 0) {
+        return null;
+    }
+    const metadataText = trimmed.slice(open + 1, -1).trim();
+    const text = trimmed.slice(0, open).trimEnd();
+    if (!metadataText || !text) {
+        return null;
+    }
+    const fields = new Map();
+    for (const token of metadataText.split(/[,\s]+/)) {
+        if (!token) {
+            continue;
+        }
+        const equals = token.indexOf("=");
+        if (equals <= 0) {
+            continue;
+        }
+        const key = token.slice(0, equals).trim().toLowerCase();
+        const value = token.slice(equals + 1).trim();
+        if (key && value) {
+            fields.set(key, value);
+        }
+    }
+    const score = parseNumber(fields.get("score"));
+    const recallCount = parseInteger(fields.get("recall") ?? fields.get("recallcount"));
+    const uniqueQueries = parseInteger(fields.get("unique") ?? fields.get("uniquequeries"));
+    if (score == null || recallCount == null || uniqueQueries == null) {
+        return null;
+    }
+    return {
+        bodyStart: text.length,
+        score,
+        recallCount,
+        uniqueQueries,
+    };
+}
+function parseNumber(value) {
+    if (!value) {
+        return null;
+    }
+    const parsed = Number.parseFloat(value);
+    if (!Number.isFinite(parsed)) {
+        return null;
+    }
+    return parsed;
+}
+function parseInteger(value) {
+    if (!value) {
+        return null;
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed)) {
+        return null;
+    }
+    return parsed;
+}
+function normalizeSectionName(value) {
+    return value.trim().toLowerCase().replace(/\s+/g, " ");
+}
+function normalizeDiaryPath(value) {
+    const trimmed = value?.trim();
+    if (!trimmed) {
+        return "";
+    }
+    return path.resolve(trimmed);
+}
+function createRealFsApi() {
+    return {
+        readFile: async (file) => fsp.readFile(file),
+        stat: async (file) => {
+            const stat = await fsp.stat(file);
+            return { size: stat.size, mtimeMs: stat.mtimeMs };
+        },
+        watch: (dir, onChange) => fs.watch(dir, onChange),
+    };
+}
+function formatError(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+const textDecoder = new TextDecoder();

package/dist/dream-routing.d.ts

@@ -0,0 +1,6 @@
+export interface DreamQuerySignal {
+    active: boolean;
+    matchedPatterns: string[];
+}
+export declare function detectDreamQuerySignal(queryText: string): DreamQuerySignal;
+export declare function resolveDreamCollection(userId: string): string;

package/dist/dream-routing.js

@@ -0,0 +1,31 @@
+const DREAM_COLLECTION_PREFIX = "dream:";
+const DREAM_PATTERN_RULES = [
+    {
+        label: "dream",
+        patterns: [
+            /\bdream(?:s|ed|ing)?\b/i,
+            /\btell\s+me\s+about\s+(?:your\s+)?dreams?\b/i,
+            /\bwhat\s+did\s+i\s+dream\s+about\b/i,
+            /\bwhat\s+was\s+i\s+dreaming\s+about\b/i,
+        ],
+    },
+];
+const DREAM_MATCHED_PATTERNS = ["dream"];
+const EMPTY_MATCHED_PATTERNS = [];
+export function detectDreamQuerySignal(queryText) {
+    for (const rule of DREAM_PATTERN_RULES) {
+        if (rule.patterns.some((pattern) => pattern.test(queryText))) {
+            return {
+                active: true,
+                matchedPatterns: DREAM_MATCHED_PATTERNS,
+            };
+        }
+    }
+    return {
+        active: false,
+        matchedPatterns: EMPTY_MATCHED_PATTERNS,
+    };
+}
+export function resolveDreamCollection(userId) {
+    return `${DREAM_COLLECTION_PREFIX}${userId.trim()}`;
+}

package/dist/durable-namespace.d.ts

@@ -0,0 +1,6 @@
+export declare function resolveDurableNamespace(params: {
+    userId?: string;
+    sessionKey?: string;
+    agentId?: string;
+    fallback?: string;
+}): string;

package/dist/durable-namespace.js

@@ -0,0 +1,24 @@
+const SESSION_KEY_NAMESPACE_PREFIX = "session-key:";
+const AGENT_ID_NAMESPACE_PREFIX = "agent-id:";
+export function resolveDurableNamespace(params) {
+    const explicitUserId = firstNonEmpty(params.userId);
+    if (explicitUserId) {
+        return explicitUserId;
+    }
+    const sessionKey = firstNonEmpty(params.sessionKey);
+    if (sessionKey) {
+        return `${SESSION_KEY_NAMESPACE_PREFIX}${sessionKey}`;
+    }
+    const agentId = firstNonEmpty(params.agentId);
+    if (agentId) {
+        return `${AGENT_ID_NAMESPACE_PREFIX}${agentId}`;
+    }
+    return firstNonEmpty(params.fallback) ?? "default";
+}
+function firstNonEmpty(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}

package/dist/grpc-client.d.ts

@@ -0,0 +1,23 @@
+export interface GrpcClientOptions {
+    endpoint: string;
+    secret?: string;
+    timeoutMs?: number;
+}
+export declare class GrpcKernelClient {
+    private client;
+    private readonly secret;
+    private readonly timeoutMs;
+    private nonceHex;
+    constructor(options: GrpcClientOptions);
+    private getMetadata;
+    private call;
+    initializeSession(req: any): Promise<any>;
+    assembleContext(req: any): Promise<any>;
+    rankCandidates(req: any): Promise<any>;
+    ingestMessage(req: any): Promise<any>;
+    afterTurn(req: any): Promise<any>;
+    bootstrapSession(req: any): Promise<any>;
+    compactSession(req: any): Promise<any>;
+    getStatus(req?: any): Promise<any>;
+    close(): void;
+}

package/dist/grpc-client.js

@@ -0,0 +1,104 @@
+import { createHmac } from "node:crypto";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as grpc from "@grpc/grpc-js";
+import * as protoLoader from "@grpc/proto-loader";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// The proto file is expected to be copied to dist/proto/ at build time.
+// In source, it's at api/proto/.
+const PROTO_PATH = path.resolve(__dirname, "./proto/intelligence_kernel/v1/kernel.proto");
+export class GrpcKernelClient {
+    client;
+    secret;
+    timeoutMs;
+    nonceHex;
+    constructor(options) {
+        this.secret = options.secret;
+        this.timeoutMs = options.timeoutMs ?? 30000;
+        const packageDefinition = protoLoader.loadSync(PROTO_PATH, {
+            keepCase: true,
+            longs: String,
+            enums: String,
+            defaults: true,
+            oneofs: true,
+        });
+        const protoDescriptor = grpc.loadPackageDefinition(packageDefinition);
+        const kernelService = protoDescriptor.intelligence_kernel.v1.IntelligenceKernel;
+        const target = options.endpoint.startsWith("tcp:")
+            ? options.endpoint.substring(4)
+            : options.endpoint.startsWith("unix:")
+                ? options.endpoint.substring(5)
+                : options.endpoint;
+        this.client = new kernelService(target, grpc.credentials.createInsecure());
+    }
+    getMetadata(signed = true) {
+        const md = new grpc.Metadata();
+        if (this.secret && signed) {
+            if (!this.nonceHex) {
+                throw new Error("call initializeSession before authenticated RPCs");
+            }
+            const hmac = createHmac("sha256", Buffer.from(this.nonceHex, "hex"));
+            hmac.update(this.secret);
+            const signature = hmac.digest("hex");
+            md.add("x-libravdb-auth", signature);
+        }
+        return md;
+    }
+    call(method, req, signed = true) {
+        return new Promise((resolve, reject) => {
+            const deadline = new Date(Date.now() + this.timeoutMs);
+            this.client[method](req, this.getMetadata(signed), { deadline }, (err, resp) => {
+                if (err) {
+                    reject(err);
+                }
+                else {
+                    resolve(resp);
+                }
+            });
+        });
+    }
+    async initializeSession(req) {
+        return new Promise((resolve, reject) => {
+            const deadline = new Date(Date.now() + this.timeoutMs);
+            this.client.InitializeSession(req, this.getMetadata(false), { deadline }, (err, resp) => {
+                if (err) {
+                    reject(err);
+                    return;
+                }
+                const nonce = resp?.server_metadata?.nonce;
+                if (this.secret && (typeof nonce !== "string" || nonce.length === 0)) {
+                    reject(new Error("InitializeSession response missing auth nonce"));
+                    return;
+                }
+                if (typeof nonce === "string" && nonce.length > 0) {
+                    this.nonceHex = nonce;
+                }
+                resolve(resp);
+            });
+        });
+    }
+    async assembleContext(req) {
+        return this.call("AssembleContext", req);
+    }
+    async rankCandidates(req) {
+        return this.call("RankCandidates", req);
+    }
+    async ingestMessage(req) {
+        return this.call("IngestMessage", req);
+    }
+    async afterTurn(req) {
+        return this.call("AfterTurn", req);
+    }
+    async bootstrapSession(req) {
+        return this.call("BootstrapSession", req);
+    }
+    async compactSession(req) {
+        return this.call("CompactSession", req);
+    }
+    async getStatus(req = {}) {
+        return this.call("GetStatus", req);
+    }
+    close() {
+        this.client.close();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { type OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
+declare const _default: {
+    id: string;
+    name: string;
+    description: string;
+    kind?: "memory" | "context-engine" | Array<"memory" | "context-engine">;
+    configSchema?: unknown;
+    register(api: OpenClawPluginApi): void | Promise<void>;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,40 @@
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { registerMemoryCli } from "./cli.js";
+import { buildContextEngineFactory } from "./context-engine.js";
+import { createBeforeResetHook, createSessionEndHook } from "./lifecycle-hooks.js";
+import { createDreamPromotionHandle } from "./dream-promotion.js";
+import { createMarkdownIngestionHandle } from "./markdown-ingest.js";
+import { buildMemoryPromptSection } from "./memory-provider.js";
+import { buildMemoryRuntimeBridge } from "./memory-runtime.js";
+import { createRecallCache } from "./recall-cache.js";
+import { createPluginRuntime } from "./plugin-runtime.js";
+export default definePluginEntry({
+    id: "libravdb-memory",
+    name: "LibraVDB Memory",
+    description: "Persistent vector memory with three-tier hybrid scoring",
+    kind: "context-engine",
+    register(api) {
+        const cfg = api.pluginConfig;
+        const recallCache = createRecallCache();
+        const runtime = createPluginRuntime(cfg, api.logger ?? console);
+        const markdownIngestion = createMarkdownIngestionHandle(cfg, runtime.getRpc, api.logger ?? console);
+        const dreamPromotion = createDreamPromotionHandle(cfg, runtime.getRpc, api.logger ?? console);
+        void markdownIngestion.start().catch((error) => {
+            api.logger?.warn?.(`LibraVDB markdown ingestion failed to start: ${error instanceof Error ? error.message : String(error)}`);
+        });
+        void dreamPromotion.start().catch((error) => {
+            api.logger?.warn?.(`LibraVDB dream promotion failed to start: ${error instanceof Error ? error.message : String(error)}`);
+        });
+        registerMemoryCli(api, runtime, cfg, api.logger ?? console);
+        api.registerContextEngine("libravdb-memory", () => buildContextEngineFactory(runtime, cfg, recallCache, api.logger ?? console));
+        api.registerMemoryPromptSection(buildMemoryPromptSection(runtime.getRpc, cfg, recallCache));
+        api.registerMemoryRuntime?.(buildMemoryRuntimeBridge(runtime.getRpc, cfg));
+        api.on("before_reset", createBeforeResetHook(runtime, api.logger ?? console));
+        api.on("session_end", createSessionEndHook(runtime, api.logger ?? console));
+        api.on("gateway_stop", async () => {
+            await dreamPromotion.stop();
+            await markdownIngestion.stop();
+            await runtime.shutdown();
+        });
+    },
+});

package/dist/lifecycle-hooks.d.ts

@@ -0,0 +1,4 @@
+import type { PluginRuntime } from "./plugin-runtime.js";
+import type { LoggerLike } from "./types.js";
+export declare function createBeforeResetHook(runtime: PluginRuntime, logger?: LoggerLike): (event: unknown, ctx: unknown) => Promise<void>;
+export declare function createSessionEndHook(runtime: PluginRuntime, logger?: LoggerLike): (event: unknown, ctx: unknown) => Promise<void>;

package/dist/lifecycle-hooks.js

@@ -0,0 +1,64 @@
+export function createBeforeResetHook(runtime, logger = console) {
+    return async (event, ctx) => {
+        const typedEvent = asBeforeResetEvent(event);
+        const typedCtx = asAgentContext(ctx);
+        try {
+            await runtime.emitLifecycleHint({
+                hook: "before_reset",
+                reason: typedEvent.reason,
+                sessionFile: typedEvent.sessionFile,
+                sessionId: typedCtx.sessionId,
+                sessionKey: typedCtx.sessionKey,
+                agentId: typedCtx.agentId,
+                workspaceDir: typedCtx.workspaceDir,
+                messageCount: Array.isArray(typedEvent.messages) ? typedEvent.messages.length : undefined,
+            });
+        }
+        catch (error) {
+            logger.warn?.(`LibraVDB before_reset hint failed: ${formatError(error)}`);
+        }
+    };
+}
+export function createSessionEndHook(runtime, logger = console) {
+    return async (event, ctx) => {
+        const typedEvent = asSessionEndEvent(event);
+        const typedCtx = asAgentContext(ctx);
+        try {
+            await runtime.emitLifecycleHint({
+                hook: "session_end",
+                reason: typedEvent.reason,
+                sessionFile: typedEvent.sessionFile,
+                sessionId: typedEvent.sessionId ?? typedCtx.sessionId,
+                sessionKey: typedEvent.sessionKey ?? typedCtx.sessionKey,
+                agentId: typedCtx.agentId,
+                workspaceDir: typedCtx.workspaceDir,
+                messageCount: typedEvent.messageCount,
+                durationMs: typedEvent.durationMs,
+                transcriptArchived: typedEvent.transcriptArchived,
+                nextSessionId: typedEvent.nextSessionId,
+                nextSessionKey: typedEvent.nextSessionKey,
+            });
+        }
+        catch (error) {
+            logger.warn?.(`LibraVDB session_end hint failed: ${formatError(error)}`);
+        }
+    };
+}
+function asAgentContext(value) {
+    return isRecord(value) ? value : {};
+}
+function asBeforeResetEvent(value) {
+    return isRecord(value) ? value : {};
+}
+function asSessionEndEvent(value) {
+    return isRecord(value) ? value : {};
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function formatError(error) {
+    if (error instanceof Error && error.message.trim()) {
+        return error.message;
+    }
+    return String(error);
+}

package/dist/markdown-hash.d.ts

@@ -0,0 +1,3 @@
+export declare function hashBytes(bytes: Uint8Array): string;
+export declare function hashText(text: string): string;
+export declare function getHashBackendName(): string;