@xmemo/openclaw-memory 1.0.0

package/dist/src/auto-capture.js

@@ -0,0 +1,267 @@
+// Auto-capture lifecycle hooks for XMemo.
+//
+// After a successful agent run, inspect user messages for high-signal snippets
+// (preferences, decisions, facts, contact info) and store them in XMemo. XMemo
+// handles embeddings remotely, so no local vector store is required.
+import { resolveLivePluginConfigObject } from "openclaw/plugin-sdk/plugin-config-runtime";
+import { XMemoClient } from "./client.js";
+import { resolveXMemoMemoryConfig } from "./config.js";
+const CURSORS = new Map();
+const LEADING_TIMESTAMP_RE = /^\[[A-Za-z]{3} \d{4}-\d{2}-\d{2} \d{2}:\d{2}[^\]]*\] */;
+const MEDIA_ATTACHED_RE = /\[media attached(?:\s+\d+\/\d+)?:[^\]]*\]/gi;
+const ACTIVE_MEMORY_RE = /<active_memory_plugin>[\s\S]*?<\/active_memory_plugin>/g;
+const UNTRUSTED_CONTEXT_RE = /^Untrusted context \(metadata[\s\S]*$/m;
+const RELEVANT_MEMORIES_RE = /<relevant-memories>[\s\S]*?<\/relevant-memories>/g;
+const MEMORY_TRIGGERS = [
+    /\b(remember|recall|save this|keep in mind|don't forget|note that)\b/i,
+    /\b(prefer|preference|like|love|hate|want|need)\b/i,
+    /\b(decided|decision|we will use|let's use|going forward|from now on)\b/i,
+    /\b(my name is|i am|my email|my phone|my address|contact me at)\b/i,
+    /\b(always|never|important|crucial|critical)\b/i,
+    /\b(记住|记下|保存|不要忘记|注意)\b/i,
+    /\b(喜欢|偏好|讨厌|想要|需要)\b/i,
+    /\b(决定|我们使用|以后|重要)\b/i,
+    /\b(覚えて|記憶して|忘れないで|好み|いつも|絶対|重要)\b/i,
+    /\b(기억해|기억해줘|잊지 마|좋아|싫어|항상|절대|중요)\b/i,
+];
+function asRecord(value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    return undefined;
+}
+function messageFingerprint(message) {
+    const obj = asRecord(message);
+    if (!obj) {
+        return `${typeof message}:${String(message)}`;
+    }
+    try {
+        return JSON.stringify({ role: obj.role, content: obj.content });
+    }
+    catch {
+        return `${String(obj.role)}:${String(obj.content)}`;
+    }
+}
+function extractUserTextContent(message) {
+    const obj = asRecord(message);
+    if (!obj || obj.role !== "user") {
+        return [];
+    }
+    const content = obj.content;
+    if (typeof content === "string") {
+        return [content];
+    }
+    if (!Array.isArray(content)) {
+        return [];
+    }
+    const texts = [];
+    for (const block of content) {
+        const blockObj = asRecord(block);
+        if (blockObj?.type === "text" && typeof blockObj.text === "string") {
+            texts.push(blockObj.text);
+        }
+    }
+    return texts;
+}
+function resolveStartIndex(messages, cursor) {
+    if (!cursor) {
+        return 0;
+    }
+    if (cursor.lastMessageFingerprint && cursor.nextIndex > 0) {
+        for (let index = messages.length - 1; index >= 0; index -= 1) {
+            if (messageFingerprint(messages[index]) === cursor.lastMessageFingerprint) {
+                return index + 1;
+            }
+        }
+        return 0;
+    }
+    if (cursor.nextIndex <= messages.length) {
+        return cursor.nextIndex;
+    }
+    return 0;
+}
+function sanitizeForCapture(text) {
+    let cleaned = text.length > 10_000 ? text.slice(0, 10_000) : text;
+    cleaned = cleaned.replace(LEADING_TIMESTAMP_RE, "");
+    cleaned = cleaned.replace(MEDIA_ATTACHED_RE, "");
+    cleaned = cleaned.replace(ACTIVE_MEMORY_RE, "");
+    cleaned = cleaned.replace(RELEVANT_MEMORIES_RE, "");
+    const untrustedMatch = UNTRUSTED_CONTEXT_RE.exec(cleaned);
+    if (untrustedMatch?.index !== undefined) {
+        cleaned = cleaned.slice(0, untrustedMatch.index);
+    }
+    cleaned = cleaned
+        .replace(/\n{3,}/g, "\n\n")
+        .replace(/[ \t]{2,}/g, " ")
+        .trim();
+    return cleaned;
+}
+function matchesCustomTrigger(text, customTriggers) {
+    if (!customTriggers || customTriggers.length === 0) {
+        return false;
+    }
+    const lower = text.toLocaleLowerCase();
+    return customTriggers.some((trigger) => lower.includes(trigger.toLocaleLowerCase()));
+}
+function looksLikeEnvelopeSludge(text) {
+    if (!text) {
+        return false;
+    }
+    return (/^Untrusted context \(metadata/m.test(text) ||
+        text.includes("(untrusted metadata):") ||
+        /\[media attached/i.test(text) ||
+        /<active_memory_plugin>/i.test(text) ||
+        /<relevant-memories>/i.test(text) ||
+        /^\[Channel /m.test(text) ||
+        /^Conversation info /m.test(text));
+}
+function looksLikePromptInjection(text) {
+    return /<\s*(system|assistant|developer|tool|function|relevant-memories)\b/i.test(text);
+}
+function shouldCapture(text, options) {
+    if (looksLikeEnvelopeSludge(text)) {
+        return false;
+    }
+    if (text.length > options.maxChars) {
+        return false;
+    }
+    if (text.includes("<relevant-memories>")) {
+        return false;
+    }
+    if (text.startsWith("<") && text.includes("</")) {
+        return false;
+    }
+    if (looksLikePromptInjection(text)) {
+        return false;
+    }
+    const hasTrigger = MEMORY_TRIGGERS.some((r) => r.test(text)) || matchesCustomTrigger(text, options.customTriggers);
+    if (!hasTrigger) {
+        return false;
+    }
+    if (text.length < 10) {
+        return false;
+    }
+    return true;
+}
+function detectCategory(text) {
+    const lower = text.toLowerCase();
+    if (/prefer|like|love|hate|want|need|偏好|喜欢|喜歡|讨厌|討厭|愛|好き|嫌い|좋아|싫어|원해|필요/.test(lower)) {
+        return "preference";
+    }
+    if (/decided|decision|will use|going forward|决定|決定|以后都用|以後都用|これから|앞으로/.test(lower)) {
+        return "decision";
+    }
+    if (/my name|email|phone|address|contact|is called|\+\d{10,}|@[\w.-]+\.\w+/.test(lower)) {
+        return "entity";
+    }
+    if (/\b(is|are|has|have|je|má|jsou)\b/i.test(lower)) {
+        return "fact";
+    }
+    return "other";
+}
+function resolveCurrentConfig(api, startupConfig) {
+    const runtimeLoader = api.runtime?.config?.current
+        ? () => api.runtime.config.current()
+        : undefined;
+    const live = resolveLivePluginConfigObject(runtimeLoader, "xmemo-memory", api.pluginConfig);
+    if (!live) {
+        return startupConfig;
+    }
+    return {
+        ...startupConfig,
+        autoCapture: live.autoCapture ?? startupConfig.autoCapture,
+        captureMaxChars: live.captureMaxChars ?? startupConfig.captureMaxChars,
+        customTriggers: Array.isArray(live.customTriggers)
+            ? live.customTriggers
+            : startupConfig.customTriggers,
+    };
+}
+function buildClient(cfg) {
+    if (!cfg.apiKey) {
+        return null;
+    }
+    return new XMemoClient(cfg.baseUrl, cfg.apiKey, cfg.agentId, cfg.agentInstanceId, cfg.authMode);
+}
+export function registerXMemoAutoCapture(api) {
+    const startupConfig = resolveXMemoMemoryConfig(api.config);
+    api.on("agent_end", async (event, ctx) => {
+        const cfg = resolveCurrentConfig(api, startupConfig);
+        if (!cfg.autoCapture) {
+            return;
+        }
+        if (!event.success || !event.messages || event.messages.length === 0) {
+            return;
+        }
+        const client = buildClient(cfg);
+        if (!client) {
+            return;
+        }
+        const cursorKey = ctx.sessionKey ?? ctx.sessionId;
+        const startIndex = resolveStartIndex(event.messages, cursorKey ? CURSORS.get(cursorKey) : undefined);
+        let stored = 0;
+        let capturableSeen = 0;
+        for (let index = startIndex; index < event.messages.length; index += 1) {
+            const message = event.messages[index];
+            let messageProcessed = false;
+            try {
+                for (const text of extractUserTextContent(message)) {
+                    const sanitized = sanitizeForCapture(text);
+                    if (!sanitized ||
+                        !shouldCapture(sanitized, {
+                            maxChars: cfg.captureMaxChars,
+                            customTriggers: cfg.customTriggers,
+                        })) {
+                        continue;
+                    }
+                    capturableSeen += 1;
+                    if (capturableSeen > 3) {
+                        continue;
+                    }
+                    const category = detectCategory(sanitized);
+                    try {
+                        const controller = new AbortController();
+                        const timeout = setTimeout(() => controller.abort(), 10_000);
+                        try {
+                            await client.remember({
+                                content: sanitized,
+                                path: cfg.bucket,
+                                bucket: cfg.bucket,
+                                scope: cfg.scope ?? null,
+                                team_id: cfg.teamId ?? null,
+                                memory_type: "auto",
+                                importance: 0.7,
+                                source: "openclaw-auto-capture",
+                                metadata: { category },
+                            }, controller.signal);
+                            stored += 1;
+                        }
+                        finally {
+                            clearTimeout(timeout);
+                        }
+                    }
+                    catch (err) {
+                        api.logger.warn(`xmemo-memory: auto-capture store failed: ${String(err)}`);
+                    }
+                }
+                messageProcessed = true;
+            }
+            finally {
+                if (messageProcessed && cursorKey) {
+                    CURSORS.set(cursorKey, {
+                        nextIndex: index + 1,
+                        lastMessageFingerprint: messageFingerprint(message),
+                    });
+                }
+            }
+        }
+        if (stored > 0) {
+            api.logger.info(`xmemo-memory: auto-captured ${stored} memories`);
+        }
+    });
+    api.on("session_end", (_event, ctx) => {
+        const cursorKey = ctx.sessionKey ?? ctx.sessionId;
+        if (cursorKey) {
+            CURSORS.delete(cursorKey);
+        }
+    });
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/memory-core-host-runtime-core";
+export declare function registerXMemoCli(api: OpenClawPluginApi): void;

package/dist/src/cli.js

@@ -0,0 +1,73 @@
+// XMemo plugin CLI commands.
+import { XMemoClient } from "./client.js";
+import { resolveXMemoMemoryConfig } from "./config.js";
+import { XMemoSearchManager } from "./search-manager.js";
+export function registerXMemoCli(api) {
+    api.registerCli(({ program }) => {
+        const xmemo = program.command("xmemo").description("XMemo memory commands for OpenClaw");
+        xmemo
+            .command("status")
+            .description("Show XMemo memory backend status")
+            .option("--json", "Output machine-readable JSON")
+            .action(async (opts) => {
+            const cfg = resolveXMemoMemoryConfig(api.config);
+            const configured = Boolean(cfg.apiKey);
+            let connected = false;
+            let lastError;
+            if (configured) {
+                const client = new XMemoClient(cfg.baseUrl, cfg.apiKey, cfg.agentId, cfg.agentInstanceId, cfg.authMode);
+                const manager = new XMemoSearchManager(client, cfg);
+                const controller = new AbortController();
+                const timeout = setTimeout(() => controller.abort(), 10_000);
+                try {
+                    connected = await manager.probeConnectivity(controller.signal);
+                }
+                finally {
+                    clearTimeout(timeout);
+                }
+                const status = manager.status();
+                if (status.custom && typeof status.custom.lastError === "string") {
+                    lastError = status.custom.lastError;
+                }
+            }
+            const status = {
+                backend: "xmemo",
+                provider: "xmemo-memory",
+                configured,
+                connected,
+                baseUrl: cfg.baseUrl,
+                bucket: cfg.bucket,
+                scope: cfg.scope,
+                teamId: cfg.teamId,
+                agentId: cfg.agentId,
+                agentInstanceId: cfg.agentInstanceId,
+                autoCapture: cfg.autoCapture,
+                ...(lastError ? { lastError } : {}),
+            };
+            if (opts.json) {
+                console.log(JSON.stringify(status, null, 2));
+            }
+            else {
+                console.log(`XMemo memory backend: ${configured ? "configured" : "not configured"}`);
+                console.log(`  Connected: ${connected ? "yes" : "no"}`);
+                console.log(`  Base URL: ${status.baseUrl}`);
+                console.log(`  Bucket: ${status.bucket}`);
+                if (status.scope) {
+                    console.log(`  Scope: ${status.scope}`);
+                }
+                if (status.teamId) {
+                    console.log(`  Team: ${status.teamId}`);
+                }
+                console.log(`  Agent: ${status.agentId}`);
+                console.log(`  Auto capture: ${status.autoCapture}`);
+                if (lastError) {
+                    console.log(`  Last error: ${lastError}`);
+                }
+            }
+        });
+    }, {
+        descriptors: [
+            { name: "xmemo", description: "XMemo memory commands for OpenClaw", hasSubcommands: true },
+        ],
+    });
+}

package/dist/src/client.d.ts

@@ -0,0 +1,253 @@
+import type { XMemoAuthMode } from "./config.js";
+export type XMemoRememberRequest = {
+    content: string;
+    path?: string;
+    bucket?: string;
+    scope?: string | null;
+    team_id?: string | null;
+    memory_type?: "auto" | "semantic" | "episodic" | "procedural" | "working" | "identity";
+    semantic_key?: string | null;
+    importance?: number;
+    confidence?: number;
+    expires_at?: string | null;
+    source?: string | null;
+    metadata?: Record<string, unknown>;
+    provenance?: Record<string, unknown>;
+};
+export type XMemoRememberResponse = {
+    id: string;
+    status?: string;
+};
+export type XMemoRecallContextRequest = {
+    query: string;
+    path?: string;
+    bucket?: string;
+    scope?: string | null;
+    team_id?: string | null;
+    memory_type?: string;
+    status?: string;
+    threshold?: number;
+    max_items?: number;
+    max_tokens?: number;
+    prefer_working?: boolean;
+};
+export type XMemoRecallContextItem = {
+    id: string;
+    content: string;
+    snippet?: string;
+    path?: string;
+    bucket?: string;
+    scope?: string | null;
+    score?: number;
+    memory_type?: string;
+    updated_at?: string;
+};
+export type XMemoRecallContextResponse = {
+    items: XMemoRecallContextItem[];
+    context_text?: string;
+    budget?: {
+        tokens?: number;
+        items?: number;
+    };
+    coverage?: unknown;
+    agent_boundary?: unknown;
+};
+export type XMemoSearchMemoryRequest = {
+    query: string;
+    path?: string;
+    bucket?: string;
+    scope?: string | null;
+    team_id?: string | null;
+    max_items?: number;
+    threshold?: number;
+};
+export type XMemoSearchMemoryResult = {
+    id: string;
+    content: string;
+    path?: string;
+    bucket?: string;
+    scope?: string | null;
+    score?: number;
+    memory_type?: string;
+};
+export type XMemoSearchMemoryResponse = {
+    results: XMemoSearchMemoryResult[];
+    coverage?: unknown;
+    agent_boundary?: unknown;
+};
+export type XMemoMemory = {
+    id: string;
+    content: string;
+    path?: string;
+    bucket?: string;
+    scope?: string | null;
+    memory_type?: string;
+    status?: string;
+    importance?: number;
+    confidence?: number;
+    updated_at?: string;
+    created_at?: string;
+};
+export type XMemoUpdateMemoryRequest = {
+    content?: string | null;
+    path?: string | null;
+    bucket?: string | null;
+    scope?: string | null;
+    team_id?: string | null;
+    memory_type?: string | null;
+    status?: string | null;
+    importance?: number;
+    confidence?: number;
+    metadata?: Record<string, unknown>;
+    merge_metadata?: boolean;
+    merge_provenance?: boolean;
+    detect_conflicts?: boolean;
+};
+export type XMemoForgetMemoryRequest = {
+    mode?: "soft_delete" | "hard_delete" | "redact";
+    reason?: string | null;
+    replacement_content?: string | null;
+};
+export type XMemoReminderRequest = {
+    content: string;
+    bucket?: string;
+    scope?: string | null;
+    team_id?: string | null;
+    due_at?: string | null;
+    metadata?: Record<string, unknown>;
+};
+export type XMemoReminder = {
+    id: string;
+    content: string;
+    status?: string;
+    due_at?: string;
+};
+export type XMemoReminderListResponse = {
+    reminders: XMemoReminder[];
+};
+export type XMemoTimelineEventRequest = {
+    content: string;
+    event_type?: string;
+    bucket?: string;
+    scope?: string | null;
+    team_id?: string | null;
+    session_id?: string | null;
+    occurred_at?: string | null;
+    importance?: number;
+    confidence?: number;
+    source?: string | null;
+    metadata?: Record<string, unknown>;
+};
+export type XMemoTimelineEvent = {
+    id: string;
+    content: string;
+    event_type?: string;
+    occurred_at?: string;
+};
+export type XMemoRestartSnapshotRequest = {
+    label?: string | null;
+    bucket?: string;
+    scope?: string | null;
+    team_id?: string | null;
+    metadata?: Record<string, unknown>;
+};
+export type XMemoRestartSnapshot = {
+    id: string;
+    label?: string | null;
+    created_at?: string;
+};
+export type XMemoRestartRestoreRequest = {
+    snapshot_id?: string | null;
+    bucket?: string;
+    scope?: string | null;
+    team_id?: string | null;
+};
+export type XMemoRestartRestoreResponse = {
+    id?: string;
+    memory_id?: string;
+    status?: string;
+    restored?: boolean;
+    snapshot_id?: string;
+};
+export type XMemoLedgerMonthlySummaryParams = {
+    month?: number;
+    year?: number;
+    currency?: string;
+};
+export type XMemoLedgerMonthlySummary = {
+    month: string;
+    currency: string;
+    total: number;
+    count: number;
+};
+export type XMemoAuditEvent = {
+    id: string;
+    action: string;
+    target_id?: string;
+    created_at?: string;
+};
+export type XMemoAuditEventsParams = {
+    action?: string;
+    target_id?: string;
+    limit?: number;
+    since?: string;
+    until?: string;
+};
+export type XMemoAuditEventsResponse = {
+    events: XMemoAuditEvent[];
+};
+export type XMemoAuditConsolidationParams = {
+    action_type?: string;
+    limit?: number;
+    since?: string;
+    until?: string;
+};
+export type XMemoAuditConsolidationResponse = Record<string, unknown>;
+export type XMemoTokenValidateResponse = {
+    status: "valid";
+    scopes?: string[];
+    setup_state?: string;
+};
+/** Structured HTTP error from the XMemo REST client. */
+export declare class XMemoClientError extends Error {
+    readonly status?: number | undefined;
+    readonly pathname?: string | undefined;
+    constructor(message: string, status?: number | undefined, pathname?: string | undefined);
+}
+export declare class XMemoClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly agentId;
+    private readonly agentInstanceId;
+    private readonly authMode;
+    constructor(baseUrl: string, apiKey: string, agentId: string, agentInstanceId: string, authMode?: XMemoAuthMode);
+    isConfigured(): boolean;
+    private headers;
+    private request;
+    private buildSearchParams;
+    remember(request: XMemoRememberRequest, signal?: AbortSignal): Promise<XMemoRememberResponse>;
+    validateToken(signal?: AbortSignal): Promise<XMemoTokenValidateResponse>;
+    recallContext(request: XMemoRecallContextRequest, signal?: AbortSignal): Promise<XMemoRecallContextResponse>;
+    searchMemory(request: XMemoSearchMemoryRequest, signal?: AbortSignal): Promise<XMemoSearchMemoryResponse>;
+    getMemory(id: string, signal?: AbortSignal): Promise<XMemoMemory>;
+    updateMemory(id: string, request: XMemoUpdateMemoryRequest, signal?: AbortSignal): Promise<XMemoMemory>;
+    forgetMemory(id: string, request?: XMemoForgetMemoryRequest, signal?: AbortSignal): Promise<unknown>;
+    createReminder(request: XMemoReminderRequest, signal?: AbortSignal): Promise<XMemoReminder>;
+    listReminders(params?: {
+        bucket?: string;
+        scope?: string | null;
+        item_status?: string;
+    }, signal?: AbortSignal): Promise<XMemoReminderListResponse>;
+    completeReminder(id: string, signal?: AbortSignal): Promise<XMemoReminder>;
+    recordEvent(request: XMemoTimelineEventRequest, signal?: AbortSignal): Promise<XMemoTimelineEvent>;
+    getTimeline(params?: {
+        bucket?: string;
+        scope?: string | null;
+        limit?: number;
+    }, signal?: AbortSignal): Promise<XMemoTimelineEvent[]>;
+    saveRestartSnapshot(request: XMemoRestartSnapshotRequest, signal?: AbortSignal): Promise<XMemoRestartSnapshot>;
+    restoreRestartSnapshot(request?: XMemoRestartRestoreRequest, signal?: AbortSignal): Promise<XMemoRestartRestoreResponse>;
+    getLedgerMonthlySummary(params?: XMemoLedgerMonthlySummaryParams, signal?: AbortSignal): Promise<XMemoLedgerMonthlySummary>;
+    getAuditEvents(params?: XMemoAuditEventsParams, signal?: AbortSignal): Promise<XMemoAuditEventsResponse>;
+    getAuditConsolidation(params?: XMemoAuditConsolidationParams, signal?: AbortSignal): Promise<XMemoAuditConsolidationResponse>;
+}