@memorilabs/openclaw-memori 0.0.5 → 0.0.6-beta

package/dist/handlers/augmentation.js

@@ -1,10 +1,13 @@
 import { extractContext, initializeMemoriClient } from '../utils/index.js';
-import { cleanText, isSystemMessage } from '../sanitizer.js';
-import { AUGMENTATION_CONFIG } from '../constants.js';
+import { cleanText, extractContentType, isSystemMessage } from '../sanitizer.js';
+import { AUGMENTATION_CONFIG, MESSAGE_CONSTANTS, ROLE } from '../constants.js';
 import { SDK_VERSION } from '../version.js';
+/**
+ * Extracts metadata about the LLM provider and model used during the turn.
+ */
 function extractLLMMetadata(event) {
     const messages = event.messages || [];
-    const lastAssistant = messages.findLast((m) => m.role === 'assistant');
+    const lastAssistant = messages.findLast((m) => m.role === ROLE.ASSISTANT);
     return {
         provider: lastAssistant?.provider || null,
         model: lastAssistant?.model || null,
@@ -13,62 +16,164 @@ function extractLLMMetadata(event) {
         platform: 'openclaw',
     };
 }
+/**
+ * Extracts all tool results from messages and maps them by tool call ID.
+ */
+function extractToolResults(messages) {
+    const resultsMap = new Map();
+    for (const msg of messages) {
+        if (msg.role === ROLE.TOOL_RESULT && msg.toolCallId) {
+            resultsMap.set(msg.toolCallId, cleanText(msg.content));
+        }
+    }
+    return resultsMap;
+}
+/**
+ * Parses tool arguments from various formats into a structured object.
+ */
+function parseToolArguments(rawArgs) {
+    if (typeof rawArgs === 'string') {
+        try {
+            return JSON.parse(rawArgs);
+        }
+        catch {
+            return {};
+        }
+    }
+    if (typeof rawArgs === 'object' && rawArgs !== null) {
+        return rawArgs;
+    }
+    return {};
+}
+/**
+ * Extracts tool calls from an assistant message.
+ * Iterates backward through content blocks to match original extraction order.
+ */
+function extractToolCalls(msg, toolResults) {
+    if (!Array.isArray(msg.content)) {
+        return [];
+    }
+    const tools = [];
+    for (let i = msg.content.length - 1; i >= 0; i--) {
+        const block = msg.content[i];
+        if (block.type === 'toolCall' || block.type === 'tool_use') {
+            const rawArgs = block.arguments ?? block.input;
+            // Unshift to maintain chronological order within the message
+            tools.unshift({
+                name: block.name,
+                args: parseToolArguments(rawArgs),
+                result: toolResults.get(block.id) ?? null,
+            });
+        }
+    }
+    return tools;
+}
+/**
+ * Parses a user message, extracting the cleaned content.
+ */
+function parseUserMessage(msg) {
+    const cleanedContent = cleanText(msg.content);
+    return cleanedContent
+        ? { role: msg.role, content: cleanedContent, type: extractContentType(msg.content) }
+        : null;
+}
+/**
+ * Parses the most recent conversation turn from messages.
+ * Walks backward to find the last user message and assistant response.
+ * Collects all tool calls from assistant messages in the turn.
+ */
+function parseTurnFromMessages(messages) {
+    const tools = [];
+    const toolResults = extractToolResults(messages);
+    let userMessage = null;
+    let assistantMessage = null;
+    // Walk backwards to find the last complete turn
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (msg.role === ROLE.ASSISTANT) {
+            // Extract tool calls from ALL assistant messages in the turn
+            const extractedTools = extractToolCalls(msg, toolResults);
+            if (extractedTools.length > 0) {
+                // Prepend to maintain chronological order
+                tools.unshift(...extractedTools);
+            }
+            // Capture the text response from the FIRST (most recent) assistant message
+            if (!assistantMessage) {
+                const cleanedContent = cleanText(msg.content);
+                if (cleanedContent) {
+                    assistantMessage = {
+                        role: msg.role,
+                        content: cleanedContent.replace(/^\[\[.*?\]\]\s*/, ''),
+                        type: extractContentType(msg.content),
+                    };
+                }
+                else if (extractedTools.length > 0) {
+                    assistantMessage = {
+                        role: msg.role,
+                        content: MESSAGE_CONSTANTS.SILENT_REPLY,
+                        type: extractContentType(msg.content),
+                    };
+                }
+            }
+        }
+        else if (msg.role === ROLE.USER) {
+            userMessage = parseUserMessage(msg);
+            break; // Found the user message that started this turn
+        }
+    }
+    return { userMessage, assistantMessage, tools };
+}
+/**
+ * Builds the augmentation payload to send to Memori backend.
+ */
+function buildAugmentationPayload(userMessage, agentResponse, tools, event) {
+    const payload = {
+        userMessage,
+        agentResponse,
+        metadata: extractLLMMetadata(event),
+    };
+    if (tools.length > 0) {
+        payload.trace = { tools };
+    }
+    return payload;
+}
+/**
+ * Helper to skip augmentation and log the reason.
+ */
+function skipAugmentation(logger, reason) {
+    logger.info(reason);
+    logger.endSection('AUGMENTATION HOOK END');
+}
+/**
+ * Main handler for augmentation hook.
+ * Extracts the latest conversation turn and sends it to Memori backend.
+ */
 export async function handleAugmentation(event, ctx, config, logger) {
     logger.section('AUGMENTATION HOOK START');
     if (!event.success || !event.messages || event.messages.length < 2) {
-        logger.info('No messages or unsuccessful event. Skipping augmentation.');
-        logger.endSection('AUGMENTATION HOOK END');
+        skipAugmentation(logger, 'No messages or unsuccessful event. Skipping augmentation.');
         return;
     }
     try {
         const recentMessages = event.messages.slice(-AUGMENTATION_CONFIG.MAX_CONTEXT_MESSAGES);
-        let lastUserMsg;
-        let lastAiMsg;
-        for (let i = recentMessages.length - 1; i >= 0; i--) {
-            const msg = recentMessages[i];
-            const role = msg.role;
-            if (role !== 'user' && role !== 'assistant')
-                continue;
-            const cleanedContent = cleanText(msg.content);
-            if (!cleanedContent)
-                continue;
-            let finalContent = cleanedContent;
-            if (role === 'assistant') {
-                finalContent = finalContent.replace(/^\[\[.*?\]\]\s*/, '');
-            }
-            if (role === 'assistant' && !lastAiMsg) {
-                lastAiMsg = { role, content: finalContent };
-            }
-            if (role === 'user' && !lastUserMsg) {
-                lastUserMsg = { role, content: finalContent };
-            }
-            if (lastUserMsg && lastAiMsg)
-                break;
-        }
-        if (!lastUserMsg || !lastAiMsg) {
-            logger.info('Missing user or assistant message. Skipping.');
-            logger.endSection('AUGMENTATION HOOK END');
+        const turn = parseTurnFromMessages(recentMessages);
+        if (!turn.userMessage || !turn.assistantMessage) {
+            skipAugmentation(logger, 'Missing user or assistant message. Skipping.');
             return;
         }
-        if (isSystemMessage(lastUserMsg.content)) {
-            logger.info('User message is a system message. Skipping augmentation.');
-            logger.endSection('AUGMENTATION HOOK END');
+        if (isSystemMessage(turn.userMessage.content)) {
+            skipAugmentation(logger, 'User message is a system message. Skipping augmentation.');
             return;
         }
-        if (lastAiMsg.content === 'NO_REPLY' || lastAiMsg.content === 'SILENT_REPLY') {
+        // Resolve synthetic responses for pure-tool executions
+        if (turn.assistantMessage.content === MESSAGE_CONSTANTS.SILENT_REPLY ||
+            turn.assistantMessage.content === MESSAGE_CONSTANTS.NO_REPLY) {
             logger.info('Assistant used tool-based messaging. Using synthetic response.');
-            lastAiMsg = {
-                role: 'assistant',
-                content: "Okay, I'll remember that for you.",
-            };
+            turn.assistantMessage.content = MESSAGE_CONSTANTS.SYNTHETIC_RESPONSE;
         }
-        const context = extractContext(event, ctx, config.entityId);
+        const payload = buildAugmentationPayload(turn.userMessage, turn.assistantMessage, turn.tools, event);
+        const context = extractContext(event, ctx, config.entityId, config.projectId);
         const memoriClient = initializeMemoriClient(config.apiKey, context);
-        const payload = {
-            userMessage: lastUserMsg.content,
-            agentResponse: lastAiMsg.content,
-            metadata: extractLLMMetadata(event),
-        };
         await memoriClient.augmentation(payload);
         logger.info('Augmentation successful!');
     }

package/dist/index.js

@@ -1,26 +1,35 @@
-import { handleRecall } from './handlers/recall.js';
 import { handleAugmentation } from './handlers/augmentation.js';
 import { PLUGIN_CONFIG } from './constants.js';
-import { MemoriLogger } from './utils/index.js';
+import { MemoriLogger, loadSkillsContent } from './utils/index.js';
+import { registerUtilityTools, registerAuthenticatedTools } from './tools/index.js';
+import { registerCliCommands } from './cli/commands.js';
 const memoriPlugin = {
     id: PLUGIN_CONFIG.ID,
     name: PLUGIN_CONFIG.NAME,
     description: 'Hosted memory backend',
     register(api) {
+        registerCliCommands(api);
         const rawConfig = api.pluginConfig;
         const config = {
             apiKey: rawConfig?.apiKey,
             entityId: rawConfig?.entityId,
+            projectId: rawConfig?.projectId,
         };
+        const logger = new MemoriLogger(api);
+        const skillsContent = loadSkillsContent(api.resolvePath.bind(api));
+        registerUtilityTools({ api, config, logger });
         if (!config.apiKey || !config.entityId) {
             api.logger.warn(`${PLUGIN_CONFIG.LOG_PREFIX} Missing apiKey or entityId in config. Plugin disabled.`);
             return;
         }
-        const logger = new MemoriLogger(api);
         logger.info(`\n=== ${PLUGIN_CONFIG.LOG_PREFIX} INITIALIZING PLUGIN ===`);
         logger.info(`${PLUGIN_CONFIG.LOG_PREFIX} Tracking Entity ID: ${config.entityId}`);
-        api.on('before_prompt_build', (event, ctx) => handleRecall(event, ctx, config, logger));
+        const configContext = `Memori plugin configuration: projectId="${config.projectId}", entityId="${config.entityId}"`;
+        api.on('before_prompt_build', () => ({
+            appendSystemContext: [skillsContent, configContext].filter(Boolean).join('\n\n'),
+        }));
         api.on('agent_end', (event, ctx) => handleAugmentation(event, ctx, config, logger));
+        registerAuthenticatedTools({ api, config, logger });
     },
 };
 export default memoriPlugin;

package/dist/sanitizer.d.ts

@@ -1,2 +1,3 @@
 export declare function isSystemMessage(text: string): boolean;
+export declare function extractContentType(rawContent: unknown): string;
 export declare function cleanText(rawContent: unknown): string;

package/dist/sanitizer.js

@@ -19,7 +19,7 @@ export function isSystemMessage(text) {
  *
  * OpenClaw wraps metadata in markdown code fences (triple tick).
  * The actual message is always after the LAST closing fence.
- * The message might aslo contain a timestamp prefix like: [Day YYYY-MM-DD HH:MM TZ], that will need to be removed
+ * The message might also contain a timestamp prefix like: [Day YYYY-MM-DD HH:MM TZ], that will need to be removed
  */
 function extractRawUserMessage(content) {
     let message = content;
@@ -49,11 +49,19 @@ function extractMessageText(content) {
     }
     return '';
 }
+export function extractContentType(rawContent) {
+    if (typeof rawContent === 'string' || !rawContent)
+        return 'text';
+    if (isMessageBlockArray(rawContent)) {
+        const primary = rawContent.find((block) => (block.type === 'text' || typeof block.text === 'string') && block.text);
+        return primary?.type ?? 'text';
+    }
+    return 'text';
+}
 export function cleanText(rawContent) {
     let text = extractMessageText(rawContent);
     if (!text)
         return '';
     text = extractRawUserMessage(text);
-    text = text.replace(/<memori_context>[\s\S]*?<\/memori_context>\s*/g, '');
     return text.trim();
 }

package/dist/tools/index.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDeps } from './types.js';
+export declare function registerUtilityTools(deps: ToolDeps): void;
+export declare function registerAuthenticatedTools(deps: ToolDeps): void;
+export type { ToolDeps };

package/dist/tools/index.js

@@ -0,0 +1,16 @@
+import { createMemoriSignupTool } from './memori-signup.js';
+import { createMemoriQuotaTool } from './memori-quota.js';
+import { createMemoriRecallTool } from './memori-recall.js';
+import { createMemoriRecallSummaryTool } from './memori-recall-summary.js';
+import { createMemoriFeedbackTool } from './memori-feedback.js';
+import { createMemoriCompactionTool } from './memori-compaction.js';
+export function registerUtilityTools(deps) {
+    deps.api.registerTool(createMemoriSignupTool(deps));
+}
+export function registerAuthenticatedTools(deps) {
+    deps.api.registerTool(createMemoriRecallTool(deps));
+    deps.api.registerTool(createMemoriRecallSummaryTool(deps));
+    deps.api.registerTool(createMemoriFeedbackTool(deps));
+    deps.api.registerTool(createMemoriQuotaTool(deps));
+    deps.api.registerTool(createMemoriCompactionTool(deps));
+}

package/dist/tools/memori-compaction.d.ts

@@ -0,0 +1,35 @@
+import type { ToolDeps } from './types.js';
+export declare function createMemoriCompactionTool(deps: ToolDeps): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        type: string;
+        required: string[];
+        properties: {
+            projectId: {
+                type: string;
+                description: string;
+            };
+            sessionId: {
+                type: string;
+                description: string;
+            };
+            numMessages: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+    execute(_toolCallId: string, params: {
+        projectId?: string;
+        sessionId?: string;
+        numMessages?: number;
+    }): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: null;
+    }>;
+};

package/dist/tools/memori-compaction.js

@@ -0,0 +1,119 @@
+import { QuotaExceededError } from '@memorilabs/memori';
+import { createRecallClient } from '../utils/memori-client.js';
+export function createMemoriCompactionTool(deps) {
+    const { config, logger } = deps;
+    return {
+        name: 'memori_compaction',
+        label: 'Compact Agent Memory',
+        description: `Use this tool to restore working state after context compaction. Returns a structured snapshot of the agent's long-term memory to enable continuation without replaying the full prior session.
+
+WHEN TO USE:
+- The agent resumes after compaction
+- A long-running workflow has lost conversational detail
+- The agent needs to continue operational work without replaying the full prior session
+- The agent needs durable state, standing instructions, environment details, open loops, or the next expected action
+
+WHEN NOT TO USE:
+- Do NOT call this on every turn — it costs 100 memory credits per execution
+- Do NOT use this for targeted memory search — use memori_recall for that instead
+- Do NOT call this if the agent is starting a brand-new task with no prior context
+- Compaction is not a replacement for precise memory retrieval
+
+The compaction result returns:
+- **environment**: environment variable context captured during prior sessions
+- **standing_orders**: persistent instructions the agent must continue to follow
+- **state**: active_tasks (work in progress), open_loops (unresolved threads), pending_results
+- **timeline**: a chronological narrative of agent activity (when available)
+- **workspace_changes**: recent file or system changes made by the agent
+- **continuation**: last_action (what the agent did last) and next_expected_action (what it should do next)
+- **messages**: a tail of recent conversation messages for continuity
+
+HOW TO USE THE RESULT:
+Treat the compaction result as the agent's resume state — use it to understand what environment the agent was operating in, which standing orders must continue to be followed, which tasks are active, what happened across the prior session window, and what the agent should do next.
+
+The compaction result should guide continuation, not override explicit user instructions. Before acting on operational details, verify any state that may have changed since compaction.
+
+Pay special attention to:
+- Standing orders
+- Hard constraints
+- Alerting rules
+- Expected response formats
+- Open loops
+- Staleness warnings
+- Next expected action
+
+If the compaction result contains a required output format, follow it exactly unless the user gives a newer instruction.`,
+        parameters: {
+            type: 'object',
+            required: ['projectId'],
+            properties: {
+                projectId: {
+                    type: 'string',
+                    description: 'The project to compact. REQUIRED — always pass the configured project ID. This scopes the compaction to the correct workspace.',
+                },
+                sessionId: {
+                    type: 'string',
+                    description: 'Scope the compaction to a specific agent session. Leave empty to compact across all sessions in the project. Cannot be used without projectId.',
+                },
+                numMessages: {
+                    type: 'number',
+                    description: 'Number of recent conversation messages to include in the result. Defaults to 5. Increase (up to ~20) only if the user explicitly asks for more conversation context.',
+                },
+            },
+        },
+        async execute(_toolCallId, params) {
+            try {
+                // Config projectId is the fallback; an explicit LLM-provided value overrides it.
+                const finalParams = { projectId: config.projectId, ...params };
+                if (!finalParams.projectId) {
+                    const errorResult = { error: 'projectId is required but was not configured' };
+                    logger.warn(`memori_compaction rejected: ${JSON.stringify(errorResult)}`);
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(errorResult) }],
+                        details: null,
+                    };
+                }
+                if (finalParams.sessionId && !finalParams.projectId) {
+                    const errorResult = { error: 'sessionId cannot be provided without projectId' };
+                    logger.warn(`memori_compaction rejected: ${JSON.stringify(errorResult)}`);
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(errorResult) }],
+                        details: null,
+                    };
+                }
+                logger.info(`memori_compaction params: ${JSON.stringify(finalParams)}`);
+                const client = createRecallClient(config.apiKey, config.entityId);
+                const result = await client.agentCompaction(finalParams);
+                if (result === null) {
+                    const errorResult = { error: 'Compaction failed' };
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(errorResult) }],
+                        details: null,
+                    };
+                }
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result) }],
+                    details: null,
+                };
+            }
+            catch (e) {
+                if (e instanceof QuotaExceededError) {
+                    logger.warn('memori_compaction quota exceeded');
+                    const errorResult = {
+                        error: 'Quota exceeded: compaction costs 100 memory credits and your organization has exhausted its Recall Execution quota.',
+                    };
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(errorResult) }],
+                        details: null,
+                    };
+                }
+                logger.warn(`memori_compaction failed: ${String(e)}`);
+                const errorResult = { error: 'Compaction failed' };
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(errorResult) }],
+                    details: null,
+                };
+            }
+        },
+    };
+}

package/dist/tools/memori-feedback.d.ts

@@ -0,0 +1,25 @@
+import type { ToolDeps } from './types.js';
+export declare function createMemoriFeedbackTool(deps: ToolDeps): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            content: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    execute(_toolCallId: string, params: {
+        content: string;
+    }): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: null;
+    }>;
+};

package/dist/tools/memori-feedback.js

@@ -0,0 +1,40 @@
+import { createRecallClient } from '../utils/memori-client.js';
+export function createMemoriFeedbackTool(deps) {
+    const { config, logger } = deps;
+    return {
+        name: 'memori_feedback',
+        label: 'Memori Feedback',
+        description: 'CRITICAL: You MUST use this tool immediately whenever the user asks you to send feedback, report a bug, suggest a feature, or complain about Memori. Send feedback directly to the Memori team (positive or negative).',
+        parameters: {
+            type: 'object',
+            properties: {
+                content: {
+                    type: 'string',
+                    description: 'REQUIRED: The feedback message to send.',
+                },
+            },
+            required: ['content'],
+        },
+        async execute(_toolCallId, params) {
+            try {
+                logger.info(`memori_feedback sending: ${params.content}`);
+                const client = createRecallClient(config.apiKey, config.entityId);
+                await client.agentFeedback(params.content);
+                const result = { success: true, message: 'Feedback sent successfully.' };
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result) }],
+                    details: null,
+                };
+            }
+            catch (e) {
+                logger.warn(`memori_feedback failed: ${String(e)}`);
+                const errorResult = { error: 'Feedback failed to send.' };
+                logger.info(`memori_feedback error result: ${JSON.stringify(errorResult)}`);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(errorResult) }],
+                    details: null,
+                };
+            }
+        },
+    };
+}

package/dist/tools/memori-quota.d.ts

@@ -0,0 +1,17 @@
+import type { ToolDeps } from './types.js';
+export declare function createMemoriQuotaTool(deps: ToolDeps): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {};
+    };
+    execute(_toolCallId: string): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: null;
+    }>;
+};

package/dist/tools/memori-quota.js

@@ -0,0 +1,55 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import * as os from 'os';
+import * as path from 'path';
+const execAsync = promisify(exec);
+export function createMemoriQuotaTool(deps) {
+    const { logger } = deps;
+    return {
+        name: 'memori_quota',
+        label: 'Memori Quota',
+        description: 'Retrieves the current memory usage and maximum allowed quota for the user. Use this when the user asks about their limits, storage, or how many memories they have left — or when you encounter errors suggesting memory limits have been reached and want to confirm before degrading behavior.',
+        parameters: {
+            type: 'object',
+            properties: {},
+        },
+        async execute(_toolCallId) {
+            try {
+                logger.info('memori_quota checking usage...');
+                const tmpDir = os.tmpdir();
+                await execAsync(`npm install --prefix ${tmpDir} --no-save @memorilabs/memori@0.1.12-beta`);
+                const binPath = path.join(tmpDir, 'node_modules', '.bin', 'memori');
+                const { stdout } = await execAsync(`${binPath} quota`);
+                const result = {
+                    success: true,
+                    message: stdout.trim(),
+                };
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result) }],
+                    details: null,
+                };
+            }
+            catch (e) {
+                logger.warn(`memori_quota CLI failed: ${String(e)}`);
+                let output = 'An unexpected error occurred while trying to fetch quota via the CLI.';
+                if (typeof e === 'object' && e !== null) {
+                    const errObj = e;
+                    const stdout = typeof errObj.stdout === 'string' ? errObj.stdout.trim() : '';
+                    const stderr = typeof errObj.stderr === 'string' ? errObj.stderr.trim() : '';
+                    const msg = typeof errObj.message === 'string' ? errObj.message : '';
+                    output = stdout || stderr || msg || output;
+                }
+                else if (typeof e === 'string') {
+                    output = e;
+                }
+                const errorResult = {
+                    error: output,
+                };
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(errorResult) }],
+                    details: null,
+                };
+            }
+        },
+    };
+}

package/dist/tools/memori-recall-summary.d.ts

@@ -0,0 +1,39 @@
+import type { ToolDeps } from './types.js';
+export declare function createMemoriRecallSummaryTool(deps: ToolDeps): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            dateStart: {
+                type: string;
+                description: string;
+            };
+            dateEnd: {
+                type: string;
+                description: string;
+            };
+            projectId: {
+                type: string;
+                description: string;
+            };
+            sessionId: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+    execute(_toolCallId: string, params: {
+        dateStart?: string;
+        dateEnd?: string;
+        projectId?: string;
+        sessionId?: string;
+    }): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: null;
+    }>;
+};