@memorilabs/openclaw-memori 0.0.5-beta → 0.0.6

package/README.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-  <i>By default, OpenClaw agents forget everything between sessions. This plugin fixes that. It watches conversations, extracts what matters, and brings it back when relevant—automatically.</i>
+  <i>Give OpenClaw persistent, structured memory with Memori. Capture what matters, recall it when relevant, and move from lightweight experimentation to production-ready memory infrastructure.</i>
 </p>
 
 <p align="center">
@@ -25,14 +25,69 @@
 
 ---
 
-## Key Features
+## Why Memori for OpenClaw?
 
-- **Auto-Recall:** Before the agent responds, the plugin searches Memori for memories that match the current context and injects them directly into the prompt.
-- **Auto-Capture:** After the agent responds, the plugin securely sends the exchange to Memori to extract new facts, update stale ones, and merge duplicates.
-- **Bulletproof Sanitization:** Automatically strips OpenClaw system metadata, internal timestamps, and thinking blocks to prevent context pollution and feedback loops.
-- **Stateless & Thread-Safe:** A completely stateless architecture ensures zero memory leaks and 100% thread safety for multi-agent OpenClaw gateways.
+OpenClaw ships with a simple file-first memory system designed for lightweight experimentation. As deployments scale into production environments, teams often run into memory problems that need more structured, deterministic infrastructure.
 
-## Getting Started
+Memori provides a drop-in memory layer purpose-built for agentic systems running OpenClaw in production. It works through OpenClaw's plugin lifecycle, so you get persistent, structured memory without changing your agent logic.
+
+## Common Challenges with Default OpenClaw Memory
+
+### 1. Fact conflicts in long-running agents
+
+OpenClaw stores memory as plain markdown files. When facts change or contradict over time, there is no deterministic conflict resolution or lifecycle management.
+
+Memori introduces structured memory with update logic, decay policies, and deterministic fact handling.
+
+### 2. Context loss from token limits
+
+As sessions grow, context must be compacted to fit within model token limits. Important details can be dropped during compression.
+
+Memori stores memory outside the prompt and retrieves the right facts at query time, eliminating compaction loss.
+
+### 3. No relationship reasoning
+
+OpenClaw retrieves semantically similar text but does not model relationships between entities.
+
+Memori builds structured memory graphs that let agents reason across linked facts, not just retrieve similar chunks.
+
+### 4. Cross-project noise
+
+When multiple projects share memory storage, irrelevant context can bleed across workflows.
+
+Memori supports scoped memory namespaces to isolate projects and workflows.
+
+### 5. No user-level isolation
+
+Default memory systems do not provide deterministic isolation across users.
+
+Memori enforces user-scoped memory boundaries for secure multi-user deployments.
+
+## What Changes When You Add Memori?
+
+The Memori plugin replaces OpenClaw's flat-file memory workflow with managed, structured memory that is scoped by `entity_id`, `process_id`, and `session_id` and enriched automatically through OpenClaw's existing hooks.
+
+| Capability | What changes |
+| --- | --- |
+| **Structured memory storage** | Instead of raw markdown blobs, Memori stores conversations, facts, preferences, and knowledge-graph triples as structured records tied to an entity, process, and session. Facts are extracted as subject-predicate-object relationships, deduplicated over time, and connected into a graph so related memories stay queryable instead of being buried in text files. |
+| **Advanced Augmentation** | After each conversation, Memori processes the user and assistant exchange asynchronously in the background, identifies facts, preferences, skills, and attributes, generates embeddings for semantic search, and updates the knowledge graph without blocking the agent's response path. |
+| **Intelligent Recall** | Before the agent responds, Memori searches the current entity's stored facts and knowledge graph, ranks memories by semantic relevance and importance, and injects the most useful context into the prompt so durable knowledge survives context-window compression. |
+| **Production-ready observability** | Memori Cloud gives you dashboard visibility into memory creation, recalls, cache hit rate, sessions, quota usage, top subjects, per-memory retrieval metrics, and knowledge-graph relationships, so you can inspect what was stored and how recall is behaving in production. |
+
+The plugin still remains drop-in: OpenClaw handles the agent loop, while Memori adds recall, augmentation, sanitization, and observability around it.
+
+
+## Quickstart
+
+Get persistent memory running in your OpenClaw gateway in three steps.
+
+### Prerequisites
+
+- [OpenClaw](https://openclaw.ai) `v2026.3.2` or later
+- A Memori API key from [app.memorilabs.ai](https://app.memorilabs.ai)
+- An Entity ID to attribute memories to, such as a user ID, tenant ID, or agent name
+
+### 1. Install and Enable
 
 Run the following commands in your terminal to install and enable the plugin:
 
@@ -47,9 +102,9 @@ openclaw plugins enable openclaw-memori
 openclaw gateway restart
 ```
 
-## Configuration
+### 2. Configure
 
-The plugin needs your Memori API key and an Entity ID to function. You can configure this via the OpenClaw CLI, your `openclaw.json` file, or environment variables.
+The plugin needs your Memori API key and an Entity ID to function. You can configure this via the OpenClaw CLI or your `openclaw.json` file.
 
 ### Option A: Via OpenClaw CLI (Recommended)
 
@@ -85,12 +140,39 @@ Add the following to your `~/.openclaw/openclaw.json` file:
 | `apiKey`   | `string` | **Yes**  | Your Memori API key.                                                                                |
 | `entityId` | `string` | **Yes**  | The unique identifier for the entity (e.g., user, agent, or tenant) to attribute these memories to. |
 
-## How It Works (The Hook Lifecycle)
+### 3. Verify
+
+Restart the gateway and inspect the logs:
+
+```bash
+openclaw gateway restart
+openclaw gateway logs --filter "[Memori]"
+```
+
+You should see:
+
+```text
+[Memori] === INITIALIZING PLUGIN ===
+[Memori] Tracking Entity ID: your-app-user-id
+```
+
+To test the full memory loop:
+
+1. Send a message with a durable preference:
+   `I always use TypeScript and prefer functional patterns.`
+2. Confirm augmentation ran:
+   `Augmentation successful!`
+3. Start a new session and ask:
+   `Write a hello world script.`
+4. Confirm recall ran:
+   `Successfully injected memory context.`
+
+## How It Works
 
-This plugin integrates deeply with OpenClaw's event lifecycle to provide seamless memory without interfering with your agent's core logic:
+This plugin integrates with OpenClaw's event lifecycle to provide persistent memory without interfering with the agent's core logic:
 
-1. **`before_prompt_build` (Recall):** When a user sends a message, the plugin intercepts the event, queries the Memori API, and safely prepends relevant memories to the agent's system context.
-2. **`agent_end` (Capture):** Once the agent finishes generating its response, the plugin captures the final `user` and `assistant` messages, sanitizes them, and sends them to the Memori integration endpoint for long-term storage and entity mapping.
+1. **`before_prompt_build` (Intelligent Recall):** When a user sends a message, the plugin intercepts the event, queries the Memori API, and safely prepends relevant memories to the agent's system context.
+2. **`agent_end` (Advanced Augmentation):** Once the agent finishes generating its response, the plugin captures the final `user` and `assistant` messages, sanitizes them, and sends them to the Memori integration endpoint for long-term storage and entity mapping.
 
 ## Contributing
 

package/dist/constants.d.ts

@@ -7,5 +7,16 @@ export declare const RECALL_CONFIG: {
     readonly MIN_PROMPT_LENGTH: 2;
 };
 export declare const AUGMENTATION_CONFIG: {
-    readonly MAX_CONTEXT_MESSAGES: 5;
+    readonly MAX_CONTEXT_MESSAGES: 20;
+};
+export declare const MESSAGE_CONSTANTS: {
+    readonly SILENT_REPLY: "SILENT_REPLY";
+    readonly NO_REPLY: "NO_REPLY";
+    readonly SYNTHETIC_RESPONSE: "Okay, I'll remember that for you.";
+};
+export declare const ROLE: {
+    readonly USER: "user";
+    readonly ASSISTANT: "assistant";
+    readonly TOOL_RESULT: "toolResult";
+    readonly SYSTEM: "system";
 };

package/dist/constants.js

@@ -7,5 +7,16 @@ export const RECALL_CONFIG = {
     MIN_PROMPT_LENGTH: 2,
 };
 export const AUGMENTATION_CONFIG = {
-    MAX_CONTEXT_MESSAGES: 5,
+    MAX_CONTEXT_MESSAGES: 20,
+};
+export const MESSAGE_CONSTANTS = {
+    SILENT_REPLY: 'SILENT_REPLY',
+    NO_REPLY: 'NO_REPLY',
+    SYNTHETIC_RESPONSE: "Okay, I'll remember that for you.",
+};
+export const ROLE = {
+    USER: 'user',
+    ASSISTANT: 'assistant',
+    TOOL_RESULT: 'toolResult',
+    SYSTEM: 'system',
 };

package/dist/handlers/augmentation.d.ts

@@ -1,3 +1,7 @@
 import { OpenClawEvent, OpenClawContext, MemoriPluginConfig } from '../types.js';
 import { MemoriLogger } from '../utils/index.js';
+/**
+ * Main handler for augmentation hook.
+ * Extracts the latest conversation turn and sends it to Memori backend.
+ */
 export declare function handleAugmentation(event: OpenClawEvent, ctx: OpenClawContext, config: MemoriPluginConfig, logger: MemoriLogger): Promise<void>;

package/dist/handlers/augmentation.js

@@ -1,78 +1,172 @@
 import { extractContext, initializeMemoriClient } from '../utils/index.js';
 import { cleanText, isSystemMessage } from '../sanitizer.js';
-import { AUGMENTATION_CONFIG } from '../constants.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,
         sdkVersion: null,
-        // integrationSdkVersion: SDK_VERSION,
-        integrationSdkVersion: '0.0.1', // TODO: move me back with first releases
+        integrationSdkVersion: SDK_VERSION,
         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 } : 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*/, ''),
+                    };
+                }
+                else if (extractedTools.length > 0) {
+                    assistantMessage = { role: msg.role, content: MESSAGE_CONSTANTS.SILENT_REPLY };
+                }
+            }
+        }
+        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 payload = buildAugmentationPayload(turn.userMessage.content, turn.assistantMessage.content, turn.tools, event);
         const context = extractContext(event, ctx, config.entityId);
         const memoriClient = initializeMemoriClient(config.apiKey, context);
-        logger.info('Capturing conversation turn...');
-        const payload = {
-            userMessage: lastUserMsg.content,
-            agentResponse: lastAiMsg.content,
-            metadata: extractLLMMetadata(event),
-        };
-        logger.info(`Sending User: ${payload.userMessage}`);
-        logger.info(`Sending Agent: ${payload.agentResponse}`);
-        logger.info(`Sending Meta: ${JSON.stringify(payload.metadata)}`);
         await memoriClient.augmentation(payload);
         logger.info('Augmentation successful!');
     }

package/dist/handlers/recall.js

@@ -5,7 +5,6 @@ export async function handleRecall(event, ctx, config, logger) {
     logger.section('RECALL HOOK START');
     try {
         const context = extractContext(event, ctx, config.entityId);
-        logger.info(`EntityID: ${context.entityId} | SessionID: ${context.sessionId} | Provider: ${context.provider}`);
         const promptText = cleanText(event.prompt);
         if (!promptText ||
             promptText.length < RECALL_CONFIG.MIN_PROMPT_LENGTH ||
@@ -23,7 +22,6 @@ export async function handleRecall(event, ctx, config, logger) {
         else {
             logger.info('No relevant memories found.');
         }
-        logger.info(`Recall Prompt: ${hookReturn?.prependContext}`);
         return hookReturn;
     }
     catch (err) {

package/dist/types.d.ts

@@ -6,12 +6,18 @@ export interface OpenClawMessageBlock {
     type?: string;
     text?: string;
     thinking?: string;
+    name?: string;
+    id?: string;
+    arguments?: unknown;
     [key: string]: unknown;
 }
 export interface OpenClawMessage {
-    role: 'user' | 'assistant' | 'system';
+    role: string;
     content: string | OpenClawMessageBlock[];
     timestamp?: number;
+    toolCallId?: string;
+    provider?: string;
+    model?: string;
     [key: string]: unknown;
 }
 export interface OpenClawEvent {
@@ -32,3 +38,19 @@ export interface OpenClawContext {
     workspaceDir?: string;
     messageProvider?: string;
 }
+export interface ExtractedToolCall {
+    name: string;
+    args: Record<string, unknown>;
+    result: unknown;
+}
+export interface ParsedTurn {
+    userMessage: {
+        role: string;
+        content: string;
+    } | null;
+    assistantMessage: {
+        role: string;
+        content: string;
+    } | null;
+    tools: ExtractedToolCall[];
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "0.0.5-beta";
+export declare const SDK_VERSION = "0.0.6";

package/dist/version.js

@@ -1 +1 @@
-export const SDK_VERSION = '0.0.5-beta';
+export const SDK_VERSION = '0.0.6';

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "openclaw-memori",
   "name": "Memori System",
-  "version": "0.0.1-beta",
+  "version": "0.0.2",
   "description": "Hosted memory backend",
   "kind": "memory",
   "main": "dist/index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memorilabs/openclaw-memori",
-  "version": "0.0.5-beta",
+  "version": "0.0.6",
   "description": "Official MemoriLabs.ai long-term memory plugin for OpenClaw",
   "type": "module",
   "main": "./dist/index.js",
@@ -62,7 +62,10 @@
   "engines": {
     "node": ">=22.0.0"
   },
+  "overrides": {
+    "@hono/node-server": "^1.19.10"
+  },
   "dependencies": {
-    "@memorilabs/memori": "^0.0.4"
+    "@memorilabs/memori": "^0.0.8"
   }
 }