@memorilabs/openclaw-memori 0.0.8 → 0.0.9

package/README.md

@@ -67,16 +67,15 @@ Memori enforces user-scoped memory boundaries for secure multi-user deployments.
 
 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. |
+| 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.
@@ -86,36 +85,47 @@ Get persistent memory running in your OpenClaw gateway in three steps.
 - [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
+- A Project ID to scope memories to a specific project or workspace
 
 ### 1. Install and Enable
 
-Run the following commands in your terminal to install and enable the plugin:
-
 ```bash
-# 1. Install the plugin from npm
+# Install the plugin from npm
 openclaw plugins install @memorilabs/openclaw-memori
 
-# 2. Enable it in your workspace
+# Enable it in your workspace
 openclaw plugins enable openclaw-memori
-
-# 3. Restart the OpenClaw gateway
-openclaw gateway restart
 ```
 
 ### 2. Configure
 
-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.
+The plugin requires an API key, an Entity ID, and a Project ID. Use the built-in `memori` CLI to configure it in one step.
 
-### Option A: Via OpenClaw CLI (Recommended)
+#### Option A: Memori CLI (Recommended)
 
 ```bash
-openclaw config set plugins.entries.openclaw-memori.config.apiKey "YOUR_MEMORI_API_KEY"
-openclaw config set plugins.entries.openclaw-memori.config.entityId "your-app-user-id"
+openclaw memori init \
+  --api-key "YOUR_MEMORI_API_KEY" \
+  --entity-id "your-entity-id" \
+  --project-id "your-project-id"
 ```
 
-### Option B: Via `openclaw.json`
+Then restart the gateway:
+
+```bash
+openclaw gateway restart
+```
 
-Add the following to your `~/.openclaw/openclaw.json` file:
+#### Option B: OpenClaw config set
+
+```bash
+openclaw config set plugins.entries.openclaw-memori.config.apiKey "YOUR_MEMORI_API_KEY"
+openclaw config set plugins.entries.openclaw-memori.config.entityId "your-entity-id"
+openclaw config set plugins.entries.openclaw-memori.config.projectId "your-project-id"
+openclaw gateway restart
+```
+
+#### Option C: Direct JSON (`~/.openclaw/openclaw.json`)
 
 ```json
 {
@@ -125,7 +135,8 @@ Add the following to your `~/.openclaw/openclaw.json` file:
         "enabled": true,
         "config": {
           "apiKey": "your-memori-api-key",
-          "entityId": "your-app-user-id"
+          "entityId": "your-entity-id",
+          "projectId": "your-project-id"
         }
       }
     }
@@ -135,25 +146,42 @@ Add the following to your `~/.openclaw/openclaw.json` file:
 
 ### Configuration Options
 
-| Option     | Type     | Required | Description                                                                                         |
-| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------- |
-| `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. |
+| Option      | Type     | Required | Description                                                                                         |
+| ----------- | -------- | -------- | --------------------------------------------------------------------------------------------------- |
+| `apiKey`    | `string` | **Yes**  | Your Memori API key from [app.memorilabs.ai](https://app.memorilabs.ai).                            |
+| `entityId`  | `string` | **Yes**  | The unique identifier for the entity (e.g., user, agent, or tenant) to attribute these memories to. |
+| `projectId` | `string` | **Yes**  | Scopes all memories to a specific project or workspace.                                             |
 
 ### 3. Verify
 
-Restart the gateway and inspect the logs:
+Check that the plugin is configured and can reach the API:
 
 ```bash
-openclaw gateway restart
-openclaw gateway logs --filter "[Memori]"
+openclaw memori status --check
 ```
 
 You should see:
 
+```text
+Memori Plugin Status
+────────────────────────────────────
+  API Key:    ****...A3xQ
+  Entity ID:  your-entity-id
+  Project ID: your-project-id
+
+Checking API connectivity... OK
+Status: Ready
+```
+
+You can also inspect gateway logs to confirm the plugin loaded:
+
+```bash
+openclaw gateway logs --filter "[Memori]"
+```
+
 ```text
 [Memori] === INITIALIZING PLUGIN ===
-[Memori] Tracking Entity ID: your-app-user-id
+[Memori] Tracking Entity ID: your-entity-id
 ```
 
 To test the full memory loop:
@@ -167,6 +195,53 @@ To test the full memory loop:
 4. Confirm recall ran:
    `Successfully injected memory context.`
 
+---
+
+## CLI Reference
+
+The plugin registers a `memori` command group in the OpenClaw CLI.
+
+### `openclaw memori init`
+
+Configure the plugin with your credentials. All three flags are required.
+
+```bash
+openclaw memori init \
+  --api-key <key> \
+  --entity-id <id> \
+  --project-id <id>
+```
+
+### `openclaw memori status`
+
+Show the current configuration and whether the plugin is ready to run. Add `--check` to test live API connectivity.
+
+```bash
+openclaw memori status
+openclaw memori status --check
+```
+
+### `openclaw memori config`
+
+Fine-grained configuration management.
+
+```bash
+# Show all current values
+openclaw memori config show
+
+# Get a single value (API key is masked)
+openclaw memori config get api-key
+openclaw memori config get entity-id
+openclaw memori config get project-id
+
+# Set a single value
+openclaw memori config set api-key "NEW_KEY"
+openclaw memori config set entity-id "new-entity"
+openclaw memori config set project-id "new-project"
+```
+
+Valid keys: `api-key`, `entity-id`, `project-id`.
+
 ## How It Works
 
 This plugin integrates with OpenClaw's event lifecycle to provide persistent memory without interfering with the agent's core logic:

package/dist/cli/commands.d.ts

@@ -0,0 +1,2 @@
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+export declare function registerCliCommands(api: OpenClawPluginApi): void;

package/dist/cli/commands.js

@@ -0,0 +1,143 @@
+import { createRecallClient } from '../utils/memori-client.js';
+import { CONFIG_KEY_MAP, readPluginConfig, writePluginConfig } from './config-file.js';
+function maskKey(key) {
+    if (key.length <= 8)
+        return '****';
+    return `****...${key.slice(-4)}`;
+}
+function isReady(cfg) {
+    return Boolean(cfg.apiKey && cfg.entityId && cfg.projectId);
+}
+export function registerCliCommands(api) {
+    api.registerCli(({ program }) => {
+        const memori = program
+            .command('memori')
+            .description('Memori memory plugin commands')
+            .configureHelp({ sortSubcommands: true });
+        // ── init ────────────────────────────────────────────────────────────────
+        memori
+            .command('init')
+            .description('Configure the Memori plugin with your API credentials')
+            .option('--api-key <key>', 'Memori API key (from app.memorilabs.ai)')
+            .option('--entity-id <id>', 'Entity ID to scope all memories to')
+            .option('--project-id <id>', 'Project ID to scope all memories to')
+            .action((opts) => {
+            const missing = [];
+            if (!opts.apiKey)
+                missing.push('--api-key');
+            if (!opts.entityId)
+                missing.push('--entity-id');
+            if (!opts.projectId)
+                missing.push('--project-id');
+            if (missing.length > 0) {
+                console.error(`Error: missing required option(s): ${missing.join(', ')}`);
+                console.error('\nUsage:\n  openclaw memori init --api-key <key> --entity-id <id> --project-id <id>');
+                process.exitCode = 1;
+                return;
+            }
+            writePluginConfig({
+                apiKey: opts.apiKey,
+                entityId: opts.entityId,
+                projectId: opts.projectId,
+            });
+            console.log('\nMemori configured successfully.\n');
+            console.log(`  API Key:    ${maskKey(opts.apiKey || '')}`);
+            console.log(`  Entity ID:  ${opts.entityId}`);
+            console.log(`  Project ID: ${opts.projectId}`);
+            console.log('\nRestart the gateway to apply changes:');
+            console.log('  openclaw gateway restart\n');
+        });
+        // ── status ──────────────────────────────────────────────────────────────
+        memori
+            .command('status')
+            .description('Show current configuration and verify API connectivity')
+            .option('--check', 'Test live API connectivity')
+            .action(async (opts) => {
+            const cfg = readPluginConfig();
+            const ready = isReady(cfg);
+            console.log('\nMemori Plugin Status');
+            console.log('─'.repeat(36));
+            console.log(`  API Key:    ${cfg.apiKey ? maskKey(cfg.apiKey) : '(not set)'}`);
+            console.log(`  Entity ID:  ${cfg.entityId ?? '(not set)'}`);
+            console.log(`  Project ID: ${cfg.projectId ?? '(not set)'}`);
+            console.log();
+            if (!ready) {
+                console.log('Status: Not configured.');
+                console.log('Run:    openclaw memori init --api-key <key> --entity-id <id> --project-id <id>\n');
+                process.exitCode = 1;
+                return;
+            }
+            if (opts.check) {
+                process.stdout.write('Checking API connectivity... ');
+                try {
+                    const client = createRecallClient(cfg.apiKey || '', cfg.entityId || '');
+                    await client.agentRecall({ projectId: cfg.projectId });
+                    console.log('OK');
+                }
+                catch (e) {
+                    console.log('FAILED');
+                    console.error(`  ${String(e)}\n`);
+                    process.exitCode = 1;
+                    return;
+                }
+            }
+            console.log('Status: Ready\n');
+        });
+        // ── config ──────────────────────────────────────────────────────────────
+        const configCmd = memori
+            .command('config')
+            .description('Manage plugin configuration')
+            .configureHelp({ sortSubcommands: true });
+        const KEYS = Object.keys(CONFIG_KEY_MAP).join(', ');
+        configCmd
+            .command('show')
+            .description('Display current configuration')
+            .action(() => {
+            const cfg = readPluginConfig();
+            console.log('\nMemori Plugin Configuration');
+            console.log('─'.repeat(36));
+            console.log(`  api-key:    ${cfg.apiKey ? maskKey(cfg.apiKey) : '(not set)'}`);
+            console.log(`  entity-id:  ${cfg.entityId ?? '(not set)'}`);
+            console.log(`  project-id: ${cfg.projectId ?? '(not set)'}`);
+            console.log();
+        });
+        configCmd
+            .command('get')
+            .argument('<key>', `Config key — one of: ${KEYS}`)
+            .description('Get a specific config value')
+            .action((key) => {
+            if (!(key in CONFIG_KEY_MAP)) {
+                console.error(`Unknown key "${key}". Valid keys: ${KEYS}`);
+                process.exitCode = 1;
+                return;
+            }
+            const field = CONFIG_KEY_MAP[key];
+            const value = readPluginConfig()[field];
+            if (value === undefined) {
+                console.log('(not set)');
+            }
+            else {
+                console.log(field === 'apiKey' ? maskKey(value) : value);
+            }
+        });
+        configCmd
+            .command('set')
+            .argument('<key>', `Config key — one of: ${KEYS}`)
+            .argument('<value>', 'Value to set')
+            .description('Set a specific config value')
+            .action((key, value) => {
+            if (!(key in CONFIG_KEY_MAP)) {
+                console.error(`Unknown key "${key}". Valid keys: ${KEYS}`);
+                process.exitCode = 1;
+                return;
+            }
+            const field = CONFIG_KEY_MAP[key];
+            writePluginConfig({ [field]: value });
+            console.log(`Set ${key}.`);
+        });
+    }, {
+        descriptors: [
+            { name: 'memori', description: 'Memori memory plugin commands', hasSubcommands: true },
+        ],
+    });
+}

package/dist/cli/config-file.d.ts

@@ -0,0 +1,8 @@
+export interface MemoriCLIConfig {
+    apiKey?: string;
+    entityId?: string;
+    projectId?: string;
+}
+export declare function readPluginConfig(): MemoriCLIConfig;
+export declare function writePluginConfig(updates: Partial<MemoriCLIConfig>): void;
+export declare const CONFIG_KEY_MAP: Record<string, keyof MemoriCLIConfig>;

package/dist/cli/config-file.js

@@ -0,0 +1,64 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, join } from 'path';
+const PLUGIN_ID = 'openclaw-memori';
+const CONFIG_PATH = join(homedir(), '.openclaw', 'openclaw.json');
+function readFullConfig() {
+    if (!existsSync(CONFIG_PATH))
+        return {};
+    try {
+        return JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'));
+    }
+    catch (e) {
+        throw new Error(`Failed to parse OpenClaw config at ${CONFIG_PATH}: ${String(e)}`);
+    }
+}
+function writeFullConfig(config) {
+    mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+    writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}
+function ensurePluginStructure(config) {
+    if (!config.plugins || typeof config.plugins !== 'object')
+        config.plugins = {};
+    const plugins = config.plugins;
+    if (!plugins.entries || typeof plugins.entries !== 'object')
+        plugins.entries = {};
+    const entries = plugins.entries;
+    if (!entries[PLUGIN_ID] || typeof entries[PLUGIN_ID] !== 'object')
+        entries[PLUGIN_ID] = {};
+    const entry = entries[PLUGIN_ID];
+    if (!entry.config || typeof entry.config !== 'object')
+        entry.config = {};
+}
+function getPluginConfigBlock(full) {
+    const plugins = full.plugins;
+    const entries = plugins?.entries;
+    const entry = entries?.[PLUGIN_ID];
+    return entry?.config;
+}
+export function readPluginConfig() {
+    const cfg = getPluginConfigBlock(readFullConfig());
+    if (!cfg)
+        return {};
+    return {
+        apiKey: cfg.apiKey,
+        entityId: cfg.entityId,
+        projectId: cfg.projectId,
+    };
+}
+export function writePluginConfig(updates) {
+    const full = readFullConfig();
+    ensurePluginStructure(full);
+    const entry = full.plugins.entries[PLUGIN_ID];
+    const cfg = entry.config;
+    for (const [key, value] of Object.entries(updates)) {
+        if (value)
+            cfg[key] = value;
+    }
+    writeFullConfig(full);
+}
+export const CONFIG_KEY_MAP = {
+    'api-key': 'apiKey',
+    'entity-id': 'entityId',
+    'project-id': 'projectId',
+};

package/dist/handlers/augmentation.js

@@ -1,5 +1,5 @@
 import { extractContext, initializeMemoriClient } from '../utils/index.js';
-import { cleanText, isSystemMessage } from '../sanitizer.js';
+import { cleanText, extractContentType, isSystemMessage } from '../sanitizer.js';
 import { AUGMENTATION_CONFIG, MESSAGE_CONSTANTS, ROLE } from '../constants.js';
 import { SDK_VERSION } from '../version.js';
 /**
@@ -73,7 +73,9 @@ function extractToolCalls(msg, toolResults) {
  */
 function parseUserMessage(msg) {
     const cleanedContent = cleanText(msg.content);
-    return cleanedContent ? { role: msg.role, content: cleanedContent } : null;
+    return cleanedContent
+        ? { role: msg.role, content: cleanedContent, type: extractContentType(msg.content) }
+        : null;
 }
 /**
  * Parses the most recent conversation turn from messages.
@@ -102,10 +104,15 @@ function parseTurnFromMessages(messages) {
                     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 };
+                    assistantMessage = {
+                        role: msg.role,
+                        content: MESSAGE_CONSTANTS.SILENT_REPLY,
+                        type: extractContentType(msg.content),
+                    };
                 }
             }
         }
@@ -164,8 +171,8 @@ export async function handleAugmentation(event, ctx, config, logger) {
             logger.info('Assistant used tool-based messaging. Using synthetic response.');
             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 payload = buildAugmentationPayload(turn.userMessage, turn.assistantMessage, turn.tools, event);
+        const context = extractContext(event, ctx, config.entityId, config.projectId);
         const memoriClient = initializeMemoriClient(config.apiKey, context);
         await memoriClient.augmentation(payload);
         logger.info('Augmentation successful!');

package/dist/index.js

@@ -1,26 +1,33 @@
-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 { registerAllTools } 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,
         };
         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);
+        const skillsContent = loadSkillsContent(api.resolvePath.bind(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));
+        if (skillsContent) {
+            api.on('before_prompt_build', () => ({ appendSystemContext: skillsContent }));
+        }
         api.on('agent_end', (event, ctx) => handleAugmentation(event, ctx, config, logger));
+        registerAllTools({ 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,3 @@
+import type { ToolDeps } from './types.js';
+export declare function registerAllTools(deps: ToolDeps): void;
+export type { ToolDeps };

package/dist/tools/index.js

@@ -0,0 +1,8 @@
+import { createMemoriRecallTool } from './memori-recall.js';
+import { createMemoriRecallSummaryTool } from './memori-recall-summary.js';
+import { createMemoriFeedbackTool } from './memori-feedback.js';
+export function registerAllTools(deps) {
+    deps.api.registerTool(createMemoriRecallTool(deps));
+    deps.api.registerTool(createMemoriRecallSummaryTool(deps));
+    deps.api.registerTool(createMemoriFeedbackTool(deps));
+}

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-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;
+    }>;
+};

package/dist/tools/memori-recall-summary.js

@@ -0,0 +1,58 @@
+import { createRecallClient } from '../utils/memori-client.js';
+export function createMemoriRecallSummaryTool(deps) {
+    const { config, logger } = deps;
+    return {
+        name: 'memori_recall_summary',
+        label: 'Recall Memory Summary',
+        description: 'CRITICAL: You MUST use this tool BEFORE answering any requests for a summary, status update, daily brief, or high-level overview of a project or past sessions. Fetch summarized views of stored memories from Memori within a specific date range.',
+        parameters: {
+            type: 'object',
+            properties: {
+                dateStart: {
+                    type: 'string',
+                    description: 'ISO 8601 (MUST be UTC) date string to filter summaries created on or after this time',
+                },
+                dateEnd: {
+                    type: 'string',
+                    description: 'ISO 8601 (MUST be UTC) date string to filter summaries created on or before this time',
+                },
+                projectId: {
+                    type: 'string',
+                    description: 'CRITICAL: Leave this EMPTY to use the configured default project. ONLY provide a value if the user explicitly asks to search a different project by name.',
+                },
+                sessionId: {
+                    type: 'string',
+                    description: 'Filter to a specific session. Cannot be used without projectId.',
+                },
+            },
+        },
+        async execute(_toolCallId, params) {
+            try {
+                const finalParams = { projectId: config.projectId, ...params };
+                if (finalParams.sessionId && !finalParams.projectId) {
+                    const errorResult = { error: 'sessionId cannot be provided without projectId' };
+                    logger.warn(`memori_recall_summary rejected: ${JSON.stringify(errorResult)}`);
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(errorResult) }],
+                        details: null,
+                    };
+                }
+                logger.info(`memori_recall_summary params: ${JSON.stringify(finalParams)}`);
+                const client = createRecallClient(config.apiKey, config.entityId);
+                const result = await client.agentRecallSummary(finalParams);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result) }],
+                    details: null,
+                };
+            }
+            catch (e) {
+                logger.warn(`memori_recall_summary failed: ${String(e)}`);
+                const errorResult = { error: 'Recall summary failed' };
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(errorResult) }],
+                    details: null,
+                };
+            }
+        },
+    };
+}

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

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

package/dist/tools/memori-recall.js

@@ -0,0 +1,99 @@
+import { createRecallClient } from '../utils/memori-client.js';
+export function createMemoriRecallTool(deps) {
+    const { config, logger } = deps;
+    return {
+        name: 'memori_recall',
+        label: 'Recall Memory',
+        description: 'CRITICAL: You MUST use this tool to search for past context BEFORE claiming you do not know the user, their preferences, or past events. Explicitly fetch relevant memories from Memori using filters...',
+        parameters: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'REQUIRED: The natural language search query to find specific facts (e.g., "What database did we decide to use?", "Ryan\'s dogs"). DO NOT use wildcards like "*" or regex. This is a semantic search, so use real words.',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum number of memories to return (default: 10)',
+                },
+                dateStart: {
+                    type: 'string',
+                    description: 'ISO 8601 (MUST be UTC) date string to filter memories created on or after this time',
+                },
+                dateEnd: {
+                    type: 'string',
+                    description: 'ISO 8601 (MUST be UTC) date string to filter memories created on or before this time',
+                },
+                projectId: {
+                    type: 'string',
+                    description: 'CRITICAL: Leave this EMPTY to use the configured default project. ONLY provide a value if the user explicitly asks to search a different project by name.',
+                },
+                sessionId: {
+                    type: 'string',
+                    description: 'Filter to a specific session. Cannot be used without projectId.',
+                },
+                signal: {
+                    type: 'string',
+                    description: 'Filter to a specific fact signal. MUST be one of the allowed enum values.',
+                    enum: [
+                        'commit',
+                        'discovery',
+                        'failure',
+                        'inference',
+                        'pattern',
+                        'result',
+                        'update',
+                        'verification',
+                    ],
+                },
+                source: {
+                    type: 'string',
+                    description: 'Filter to a specific source origin. MUST be one of the allowed enum values.',
+                    enum: [
+                        'constraint',
+                        'decision',
+                        'execution',
+                        'fact',
+                        'insight',
+                        'instruction',
+                        'status',
+                        'strategy',
+                        'task',
+                    ],
+                },
+            },
+            // Force the LLM to ALWAYS provide a search query
+            required: ['query'],
+        },
+        async execute(_toolCallId, params) {
+            try {
+                // If params.projectId is undefined, it falls back to config.projectId.
+                // If the LLM intentionally provides one, it overwrites the config.
+                const finalParams = { projectId: config.projectId, ...params };
+                if (finalParams.sessionId && !finalParams.projectId) {
+                    const errorResult = { error: 'sessionId cannot be provided without projectId' };
+                    logger.warn(`memori_recall rejected: ${JSON.stringify(errorResult)}`);
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(errorResult) }],
+                        details: null,
+                    };
+                }
+                logger.info(`memori_recall params: ${JSON.stringify(finalParams)}`);
+                const client = createRecallClient(config.apiKey, config.entityId);
+                const result = await client.agentRecall(finalParams);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result) }],
+                    details: null,
+                };
+            }
+            catch (e) {
+                logger.warn(`memori_recall failed: ${String(e)}`);
+                const errorResult = { error: 'Recall failed' };
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(errorResult) }],
+                    details: null,
+                };
+            }
+        },
+    };
+}

package/dist/tools/types.d.ts

@@ -0,0 +1,8 @@
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+import type { MemoriPluginConfig } from '../types.js';
+import type { MemoriLogger } from '../utils/logger.js';
+export interface ToolDeps {
+    api: OpenClawPluginApi;
+    config: MemoriPluginConfig;
+    logger: MemoriLogger;
+}

package/dist/tools/types.js

@@ -0,0 +1 @@
+export {};

package/dist/types.d.ts

@@ -1,6 +1,8 @@
+import { IntegrationMessage } from '@memorilabs/memori/integrations';
 export interface MemoriPluginConfig {
     apiKey: string;
     entityId: string;
+    projectId: string;
 }
 export interface OpenClawMessageBlock {
     type?: string;
@@ -44,13 +46,7 @@ export interface ExtractedToolCall {
     result: unknown;
 }
 export interface ParsedTurn {
-    userMessage: {
-        role: string;
-        content: string;
-    } | null;
-    assistantMessage: {
-        role: string;
-        content: string;
-    } | null;
+    userMessage: IntegrationMessage | null;
+    assistantMessage: IntegrationMessage | null;
     tools: ExtractedToolCall[];
 }

package/dist/utils/context.d.ts

@@ -6,6 +6,7 @@ export interface ExtractedContext {
     entityId: string;
     sessionId: string;
     provider: string;
+    projectId: string;
 }
 /**
  * Extracts and normalizes context information from OpenClaw event and context objects.
@@ -14,7 +15,8 @@ export interface ExtractedContext {
  * @param event - OpenClaw event object
  * @param ctx - OpenClaw context object
  * @param configuredEntityId - Hardcoded entity ID from plugin config
- * @returns Normalized context with entityId, sessionId, and provider
+ * @param configuredProjectId - Project ID from plugin config
+ * @returns Normalized context with entityId, sessionId, provider, and projectId
  * @throws Error If entityId, sessionId, or provider cannot be determined
  */
-export declare function extractContext(event: OpenClawEvent, ctx: OpenClawContext, configuredEntityId: string): ExtractedContext;
+export declare function extractContext(event: OpenClawEvent, ctx: OpenClawContext, configuredEntityId: string, configuredProjectId: string): ExtractedContext;

package/dist/utils/context.js

@@ -5,10 +5,11 @@
  * @param event - OpenClaw event object
  * @param ctx - OpenClaw context object
  * @param configuredEntityId - Hardcoded entity ID from plugin config
- * @returns Normalized context with entityId, sessionId, and provider
+ * @param configuredProjectId - Project ID from plugin config
+ * @returns Normalized context with entityId, sessionId, provider, and projectId
  * @throws Error If entityId, sessionId, or provider cannot be determined
  */
-export function extractContext(event, ctx, configuredEntityId) {
+export function extractContext(event, ctx, configuredEntityId, configuredProjectId) {
     const sessionId = ctx.sessionKey || event.sessionId;
     const provider = ctx.messageProvider || event.messageProvider;
     if (!sessionId) {
@@ -21,5 +22,6 @@ export function extractContext(event, ctx, configuredEntityId) {
         entityId: configuredEntityId,
         sessionId,
         provider,
+        projectId: configuredProjectId,
     };
 }

package/dist/utils/index.d.ts

@@ -1,3 +1,4 @@
 export { extractContext, type ExtractedContext } from './context.js';
 export { MemoriLogger } from './logger.js';
-export { initializeMemoriClient } from './memori-client.js';
+export { initializeMemoriClient, createRecallClient } from './memori-client.js';
+export { loadSkillsContent } from './skills-loader.js';

package/dist/utils/index.js

@@ -1,3 +1,4 @@
 export { extractContext } from './context.js';
 export { MemoriLogger } from './logger.js';
-export { initializeMemoriClient } from './memori-client.js';
+export { initializeMemoriClient, createRecallClient } from './memori-client.js';
+export { loadSkillsContent } from './skills-loader.js';

package/dist/utils/memori-client.d.ts

@@ -8,3 +8,14 @@ import { ExtractedContext } from './context.js';
  * @returns Configured OpenClawIntegration instance
  */
 export declare function initializeMemoriClient(apiKey: string, context: ExtractedContext): OpenClawIntegration;
+/**
+ * Creates a minimal Memori client scoped only to an entity, with no session or project
+ * context pre-set. Intended for use in tool execute handlers where OpenClaw does not
+ * reliably provide session context — callers supply projectId/sessionId as explicit
+ * parameters instead.
+ *
+ * @param apiKey - Memori API key
+ * @param entityId - Entity ID for attribution
+ * @returns Configured OpenClawIntegration instance
+ */
+export declare function createRecallClient(apiKey: string, entityId: string): OpenClawIntegration;

package/dist/utils/memori-client.js

@@ -11,7 +11,25 @@ export function initializeMemoriClient(apiKey, context) {
     const memori = new Memori();
     memori.config.apiKey = apiKey;
     const openclaw = memori.integrate(OpenClawIntegration);
-    openclaw.setAttribution(context.entityId, context.provider);
-    openclaw.setSession(context.sessionId);
+    openclaw
+        .scope(context.sessionId, context.projectId)
+        .attribution(context.entityId, context.provider);
+    return openclaw;
+}
+/**
+ * Creates a minimal Memori client scoped only to an entity, with no session or project
+ * context pre-set. Intended for use in tool execute handlers where OpenClaw does not
+ * reliably provide session context — callers supply projectId/sessionId as explicit
+ * parameters instead.
+ *
+ * @param apiKey - Memori API key
+ * @param entityId - Entity ID for attribution
+ * @returns Configured OpenClawIntegration instance
+ */
+export function createRecallClient(apiKey, entityId) {
+    const memori = new Memori();
+    memori.config.apiKey = apiKey;
+    const openclaw = memori.integrate(OpenClawIntegration);
+    openclaw.attribution(entityId);
     return openclaw;
 }

package/dist/utils/skills-loader.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Loads the Memori skills document at plugin registration time.
+ * Returns an empty string if the file cannot be read so the plugin
+ * degrades gracefully rather than failing to register.
+ */
+export declare function loadSkillsContent(resolvePath: (input: string) => string): string;

package/dist/utils/skills-loader.js

@@ -0,0 +1,14 @@
+import { readFileSync } from 'fs';
+/**
+ * Loads the Memori skills document at plugin registration time.
+ * Returns an empty string if the file cannot be read so the plugin
+ * degrades gracefully rather than failing to register.
+ */
+export function loadSkillsContent(resolvePath) {
+    try {
+        return readFileSync(resolvePath('skills/memori/skills.md'), 'utf-8');
+    }
+    catch {
+        return '';
+    }
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "0.0.8";
+export declare const SDK_VERSION = "0.0.9";

package/dist/version.js

@@ -1 +1 @@
-export const SDK_VERSION = '0.0.8';
+export const SDK_VERSION = '0.0.9';

package/openclaw.plugin.json

@@ -1,10 +1,13 @@
 {
   "id": "openclaw-memori",
   "name": "Memori System",
-  "version": "0.0.2",
+  "version": "0.0.8",
   "description": "Hosted memory backend",
   "kind": "memory",
   "main": "dist/index.js",
+  "contracts": {
+    "tools": ["memori_recall", "memori_recall_summary", "memori_feedback"]
+  },
   "uiHints": {
     "apiKey": {
       "label": "Memori API Key",
@@ -16,6 +19,11 @@
       "label": "Entity ID",
       "placeholder": "e.g., your-app-user-id",
       "help": "Required. The unique identifier to attribute these memories to."
+    },
+    "projectId": {
+      "label": "Project ID",
+      "placeholder": "e.g., my-project",
+      "help": "Required. Scopes all memories to this project."
     }
   },
   "configSchema": {
@@ -29,7 +37,12 @@
       "entityId": {
         "type": "string",
         "title": "Entity ID",
-        "description": "Required. Hardcode a specific Entity ID for memories."
+        "description": "Required. The unique identifier to attribute these memories to."
+      },
+      "projectId": {
+        "type": "string",
+        "title": "Project ID",
+        "description": "Required. Scopes all memories to this project."
       }
     },
     "required": []

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@memorilabs/openclaw-memori",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "Official MemoriLabs.ai long-term memory plugin for OpenClaw",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "skills",
     "openclaw.plugin.json"
   ],
   "scripts": {
@@ -66,6 +67,6 @@
     "@hono/node-server": "^1.19.10"
   },
   "dependencies": {
-    "@memorilabs/memori": "^0.0.11"
+    "@memorilabs/memori": "0.1.11-beta"
   }
 }

package/skills/memori/skills.md

@@ -0,0 +1,65 @@
+## Memori — Your Persistent Memory Layer
+
+You have access to Memori, a structured long-term memory backend.
+
+**Automatic augmentation** (`agent_end`): After you respond, the conversation turn is automatically sent to Memori to extract and store facts, preferences, decisions, and relationships for future sessions. You do not need to do this manually.
+
+**Manual Recall (IMPORTANT)**: You do NOT automatically receive context from past sessions.
+**RULE:** You must NEVER say "I don't know" about the user, their preferences, or past events without FIRST running a `memori_recall` search to check if you remember it. If a user asks a question about themselves, you MUST search Memori before responding.
+
+---
+
+### Memory Retrieval Tools
+
+Use these to search your memory explicitly:
+
+**`memori_recall`** — Fetch granular memory facts using a search query and optional filters. Use this when you need specific details (e.g., "what database did we choose?").
+
+| Parameter   | Type   | Description                                                                                                                                     |
+| ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `query`     | string | **Required.** A natural language semantic search query (e.g. "dogs"). **DO NOT use wildcards like `*`.**                                        |
+| `dateStart` | string | ISO 8601 (MUST be UTC) — memories on or after this time                                                                                         |
+| `dateEnd`   | string | ISO 8601 (MUST be UTC) — memories on or before this time                                                                                        |
+| `projectId` | string | CRITICAL: Leave EMPTY to use the current project. ONLY provide a value if the user explicitly names a different project.                        |
+| `sessionId` | string | Scope to a specific session — **requires `projectId`**                                                                                          |
+| `signal`    | string | Filter by signal type. Allowed values: `commit`, `discovery`, `failure`, `inference`, `pattern`, `result`, `update`, `verification`.            |
+| `source`    | string | Filter by source origin. Allowed values: `constraint`, `decision`, `execution`, `fact`, `insight`, `instruction`, `status`, `strategy`, `task`. |
+
+**`memori_recall_summary`** — Fetch summarized views of stored memories. **RULE:** You must NEVER guess or make up a status update, daily brief, or project overview. If the user asks "what did we do last time" or "give me a summary", you MUST use this tool before answering.
+
+| Parameter   | Type   | Description                                                                                                              |
+| ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------ |
+| `dateStart` | string | ISO 8601 (MUST be UTC) — summaries on or after this time                                                                 |
+| `dateEnd`   | string | ISO 8601 (MUST be UTC) — summaries on or before this time                                                                |
+| `projectId` | string | CRITICAL: Leave EMPTY to use the current project. ONLY provide a value if the user explicitly names a different project. |
+| `sessionId` | string | Scope to a specific session — **requires `projectId`**                                                                   |
+
+> `sessionId` cannot be used without `projectId`. The backend will reject it.
+
+---
+
+### Feedback Tool
+
+**RULE:** You must ALWAYS use this tool immediately if the user asks you to send feedback, report a bug, suggest a feature, or complains about the system. Do NOT just say "I will let the developers know"—you must actually execute the tool to send the message.
+
+**`memori_feedback`** — Send feedback, suggestions, or issues directly to the Memori team.
+
+| Parameter | Type   | Description                                                              |
+| --------- | ------ | ------------------------------------------------------------------------ |
+| `content` | string | **Required.** The feedback text to send (positive, negative, bugs, etc.) |
+
+### Memory Scoping
+
+All memories are scoped to the current `entityId` and `projectId`. The current project is applied by default — you only need to pass `projectId` when explicitly overriding it for a cross-project lookup.
+
+---
+
+### Coexistence With File Memory
+
+Memori works alongside local file memory (e.g., `MEMORY.md`), it does not replace it:
+
+| Layer                     | Scope                                 | Lifetime                    |
+| ------------------------- | ------------------------------------- | --------------------------- |
+| Session context           | Current conversation                  | Dies with session           |
+| File memory (`MEMORY.md`) | Curated strategic facts               | Persistent on disk          |
+| Memori                    | Auto-extracted facts, knowledge graph | Cloud — survives compaction |

package/dist/handlers/recall.d.ts

@@ -1,5 +0,0 @@
-import { OpenClawEvent, OpenClawContext, MemoriPluginConfig } from '../types.js';
-import { MemoriLogger } from '../utils/index.js';
-export declare function handleRecall(event: OpenClawEvent, ctx: OpenClawContext, config: MemoriPluginConfig, logger: MemoriLogger): Promise<{
-    prependContext: string;
-} | undefined>;

package/dist/handlers/recall.js

@@ -1,34 +0,0 @@
-import { cleanText, isSystemMessage } from '../sanitizer.js';
-import { RECALL_CONFIG } from '../constants.js';
-import { extractContext, initializeMemoriClient } from '../utils/index.js';
-export async function handleRecall(event, ctx, config, logger) {
-    logger.section('RECALL HOOK START');
-    try {
-        const context = extractContext(event, ctx, config.entityId);
-        const promptText = cleanText(event.prompt);
-        if (!promptText ||
-            promptText.length < RECALL_CONFIG.MIN_PROMPT_LENGTH ||
-            isSystemMessage(promptText)) {
-            logger.info('Prompt too short or is a system message. Aborting recall.');
-            return undefined;
-        }
-        const memoriClient = initializeMemoriClient(config.apiKey, context);
-        logger.info('Executing SDK Recall...');
-        const recallText = await memoriClient.recall(promptText);
-        const hookReturn = recallText ? { prependContext: recallText } : undefined;
-        if (hookReturn) {
-            logger.info('Successfully injected memory context.');
-        }
-        else {
-            logger.info('No relevant memories found.');
-        }
-        return hookReturn;
-    }
-    catch (err) {
-        logger.error(`Recall failed: ${err instanceof Error ? err.message : String(err)}`);
-        return undefined;
-    }
-    finally {
-        logger.endSection('RECALL HOOK END');
-    }
-}