@memorilabs/openclaw-memori 0.0.9 → 0.0.11

package/README.md

@@ -25,229 +25,181 @@
 
 ---
 
-## Why Memori for OpenClaw?
+# Memori for OpenClaw
 
-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.
+Memori gives OpenClaw agents a structured, long-term memory system. It automatically captures what happens and lets agents recall it on demand — so context survives across sessions without bloating the prompt.
 
-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.
+Instead of relying solely on natural-language memory, Memori structures persistent memory from both conversation and agent trace — the agent's actions, tool results, decisions, and outcomes — so it can recall what actually happened when it matters.
 
-## Common Challenges with Default OpenClaw Memory
+---
 
-### 1. Fact conflicts in long-running agents
+## The problem
 
-OpenClaw stores memory as plain markdown files. When facts change or contradict over time, there is no deterministic conflict resolution or lifecycle management.
+OpenClaw's default memory works for simple use cases, but breaks at scale:
 
-Memori introduces structured memory with update logic, decay policies, and deterministic fact handling.
+- Memory is stored as flat markdown files
+- Context is lost due to compaction
+- Important decisions and constraints disappear
+- No relationships between facts
+- Memory bleeds across users and projects
 
-### 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.
+## What Memori changes
 
-Memori stores memory outside the prompt and retrieves the right facts at query time, eliminating compaction loss.
+Memori replaces flat memory with structured, scoped memory built from:
 
-### 3. No relationship reasoning
+- Agent execution (tool calls, results, decisions, outcomes)
 
-OpenClaw retrieves semantically similar text but does not model relationships between entities.
+Instead of replaying history, agents retrieve exactly what they need.
 
-Memori builds structured memory graphs that let agents reason across linked facts, not just retrieve similar chunks.
+---
 
-### 4. Cross-project noise
+## How it works
 
-When multiple projects share memory storage, irrelevant context can bleed across workflows.
+Memori runs on two parallel systems:
 
-Memori supports scoped memory namespaces to isolate projects and workflows.
+### 1. Advanced augmentation
 
-### 5. No user-level isolation
+After each interaction, Memori converts raw session data into structured, reusable memories asynchronously.
 
-Default memory systems do not provide deterministic isolation across users.
+- Transforms raw agent sessions into structured memory units
+- Captures the agent's actions, reasoning, tool usage, responses, corrections, and failures
+- Organizes into classes to enable efficient retrieval
+- Generates embeddings for semantic retrieval
+- Updates structured memory and the knowledge graph
 
-Memori enforces user-scoped memory boundaries for secure multi-user deployments.
+This is how structured memory is continuously built and updated over time.
 
-## What Changes When You Add Memori?
+It runs **after the agent responds** and does not impact latency.
 
-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.                                                                                          |
+### 2. Agent-controlled recall
 
-The plugin still remains drop-in: OpenClaw handles the agent loop, while Memori adds recall, augmentation, sanitization, and observability around it.
+Recall is **explicit and initiated by the agent**.
 
-## Quickstart
+Memori separates memory creation from memory recall:
+
+- Creation is automatic (advanced augmentation)
+- Recall is intentional (agent-controlled)
+
+Agents decide:
 
-Get persistent memory running in your OpenClaw gateway in three steps.
+- When to recall
+- What scope to recall from
+- How much history to include
+
+Memori does not automatically inject memory into the prompt. The agent retrieves only the context it needs, keeping token usage efficient.
+
+Available tools:
+
+- **`memori_recall`** — query structured memory for facts, constraints, decisions, and patterns
+- **`memori_recall_summary`** — retrieve summaries and the daily brief
+- **`memori_feedback`** — report on memory quality to improve the system
+
+---
+
+## Quickstart
 
 ### 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
-- A Project ID to scope memories to a specific project or workspace
+- An Entity ID to scope memory to a specific user, agent, or system
+- A Project ID to scope memory to a specific project or workspace
 
-### 1. Install and Enable
+### 1. Install
 
 ```bash
-# Install the plugin from npm
 openclaw plugins install @memorilabs/openclaw-memori
-
-# Enable it in your workspace
 openclaw plugins enable openclaw-memori
 ```
 
 ### 2. Configure
 
-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: Memori CLI (Recommended)
-
 ```bash
 openclaw memori init \
   --api-key "YOUR_MEMORI_API_KEY" \
-  --entity-id "your-entity-id" \
-  --project-id "your-project-id"
+  --entity-id "your-app-user-id" \
+  --project-id "my-project"
 ```
 
-Then restart the gateway:
+### 3. Verify
 
 ```bash
 openclaw gateway restart
+openclaw memori status --check
 ```
 
-#### Option B: OpenClaw config set
+Expected:
 
-```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
-{
-  "plugins": {
-    "entries": {
-      "openclaw-memori": {
-        "enabled": true,
-        "config": {
-          "apiKey": "your-memori-api-key",
-          "entityId": "your-entity-id",
-          "projectId": "your-project-id"
-        }
-      }
-    }
-  }
-}
+Status: Ready
 ```
 
-### Configuration Options
+### 4. Test the memory loop
 
-| 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.                                             |
+1. Tell the agent something durable:
 
-### 3. Verify
+   > "I always use TypeScript and prefer functional patterns."
 
-Check that the plugin is configured and can reach the API:
+2. Start a new session and ask:
 
-```bash
-openclaw memori status --check
-```
-
-You should see:
+   > "Write a hello world script in my preferred language."
 
-```text
-Memori Plugin Status
-────────────────────────────────────
-  API Key:    ****...A3xQ
-  Entity ID:  your-entity-id
-  Project ID: your-project-id
+3. Confirm the agent used `memori_recall` to fetch your preferences:
+   ```
+   [Memori] memori_recall params: {"projectId":"my-project","query":"preferred programming language"}
+   ```
 
-Checking API connectivity... OK
-Status: Ready
-```
+If it works, you now have persistent memory across sessions.
 
-You can also inspect gateway logs to confirm the plugin loaded:
+---
 
-```bash
-openclaw gateway logs --filter "[Memori]"
-```
+## Memory model
 
-```text
-[Memori] === INITIALIZING PLUGIN ===
-[Memori] Tracking Entity ID: your-entity-id
-```
+Memory is scoped to prevent noise and ensure relevance:
 
-To test the full memory loop:
+- `entity_id` → user, agent, or system context
+- `project_id` → project or workspace context
+- `session_id` → specific session (requires `project_id`)
+- `date_start` / `date_end` → time-bounded recall (defaults to all-time if omitted)
+- `source` → type of memory (recall only)
+- `signal` → how the memory was derived (recall only)
 
-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.`
+All timestamps are stored in **UTC**.
 
 ---
 
-## 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.
+## Agent behavior (read this)
 
-```bash
-openclaw memori init \
-  --api-key <key> \
-  --entity-id <id> \
-  --project-id <id>
-```
+Agents should:
 
-### `openclaw memori status`
+- Retrieve a summary at the start of meaningful sessions
+- Use targeted recall (not broad queries)
+- Avoid recalling on every turn
+- Use memory only when context is needed
+- Send feedback when memory is missing or incorrect
 
-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
-```
+See SKILL.md for full behavior guidelines.
 
-### `openclaw memori config`
+---
 
-Fine-grained configuration management.
+## Typical workflow
 
-```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"
-```
+1. Start session → retrieve summary
+2. During task → targeted recall
+3. Missing context → send feedback
+4. End of session → memory is captured automatically
 
-Valid keys: `api-key`, `entity-id`, `project-id`.
+---
 
-## How It Works
+## Multi-agent ready
 
-This plugin integrates with OpenClaw's event lifecycle to provide persistent memory without interfering with the agent's core logic:
+The plugin is fully stateless and thread-safe. You can run it across multiple agents in the same gateway without shared state or concurrency issues.
 
-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/tools/index.js

@@ -1,7 +1,11 @@
+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';
 export function registerAllTools(deps) {
+    deps.api.registerTool(createMemoriSignupTool(deps));
+    deps.api.registerTool(createMemoriQuotaTool(deps));
     deps.api.registerTool(createMemoriRecallTool(deps));
     deps.api.registerTool(createMemoriRecallSummaryTool(deps));
     deps.api.registerTool(createMemoriFeedbackTool(deps));

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.js

@@ -4,7 +4,7 @@ export function createMemoriRecallSummaryTool(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.',
+        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. If no date range is provided, the result defaults to the last 24 hours.',
         parameters: {
             type: 'object',
             properties: {

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

@@ -10,10 +10,6 @@ export declare function createMemoriRecallTool(deps: ToolDeps): {
                 type: string;
                 description: string;
             };
-            limit: {
-                type: string;
-                description: string;
-            };
             dateStart: {
                 type: string;
                 description: string;

package/dist/tools/memori-recall.js

@@ -12,10 +12,6 @@ export function createMemoriRecallTool(deps) {
                     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',

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

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

package/dist/tools/memori-signup.js

@@ -0,0 +1,72 @@
+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 createMemoriSignupTool(deps) {
+    const { logger } = deps;
+    return {
+        name: 'memori_signup',
+        label: 'Memori Sign Up',
+        description: 'CRITICAL: You MUST use this tool when the user asks to sign up, create an account, or get an API key for Memori — or when you encounter a missing MEMORI_API_KEY error and the user provides their email. If the user has not provided an email address, ask for it first. Do not guess or hallucinate an email.',
+        parameters: {
+            type: 'object',
+            properties: {
+                email: {
+                    type: 'string',
+                    description: 'The email address to send the Memori API key to.',
+                },
+            },
+            required: ['email'],
+        },
+        async execute(_toolCallId, params) {
+            try {
+                const emailRegex = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
+                if (!emailRegex.test(params.email)) {
+                    const errorResult = {
+                        error: `The email you provided "${params.email}" is not valid. Please provide a standard email address.`,
+                    };
+                    logger.warn(`memori_signup rejected email format: ${params.email}`);
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(errorResult) }],
+                        details: null,
+                    };
+                }
+                logger.info(`memori_signup attempting to sign up: ${params.email}`);
+                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} sign-up ${params.email}`);
+                const result = {
+                    success: true,
+                    message: stdout.trim(),
+                };
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result) }],
+                    details: null,
+                };
+            }
+            catch (e) {
+                logger.warn(`memori_signup CLI failed: ${String(e)}`);
+                let output = 'An unexpected error occurred while trying to sign up 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/utils/skills-loader.js

@@ -6,7 +6,7 @@ import { readFileSync } from 'fs';
  */
 export function loadSkillsContent(resolvePath) {
     try {
-        return readFileSync(resolvePath('skills/memori/skills.md'), 'utf-8');
+        return readFileSync(resolvePath('skills/memori/SKILL.md'), 'utf-8');
     }
     catch {
         return '';

package/dist/version.d.ts

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

package/dist/version.js

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

package/openclaw.plugin.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memorilabs/openclaw-memori",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "Official MemoriLabs.ai long-term memory plugin for OpenClaw",
   "type": "module",
   "main": "./dist/index.js",
@@ -67,6 +67,6 @@
     "@hono/node-server": "^1.19.10"
   },
   "dependencies": {
-    "@memorilabs/memori": "0.1.11-beta"
+    "@memorilabs/memori": "0.1.12-beta"
   }
 }

package/skills/clawhub/SKILL.md

@@ -0,0 +1,313 @@
+---
+name: memori
+id: '@memorilabs/openclaw-memori'
+description: Long-term memory for OpenClaw agents using the Memori SDK. Automatically captures conversations and execution trace, and equips the agent with explicit tools to recall context, manage its account, and monitor usage across sessions.
+license: MIT
+compatibility:
+  - openclaw
+metadata:
+  openclaw:
+    requires:
+      env:
+        - MEMORI_API_KEY
+        - ENTITY_ID
+        - PROJECT_ID
+      bins:
+        - memori
+    primaryEnv: MEMORI_API_KEY
+    externalServices:
+      - https://api.memorilabs.ai
+---
+
+# Memori skills file
+
+You have access to Memori, agent-native memory infrastructure: an LLM-agnostic layer that structures memory from not just natural language, but also from agent trace that comes from execution.
+
+Memori automatically captures and structures memory from conversation and execution trace — including the agent's actions, tool results, decisions, and outcomes — and allows you to retrieve it on demand. Use it to maintain continuity across sessions, preserve decisions and constraints, and help the agent understand what it actually did so the next time it completes a task, it is more accurate and efficient.
+
+---
+
+## Core instruction
+
+At the start of a session, you should check the `SKILL.md` file
+
+Use it to understand:
+
+- Available capabilities
+- Tooling and integrations
+- Expected behaviors and constraints
+
+Treat `SKILL.md` as a source of truth for what you can do before taking action.
+
+---
+
+## When to use Memori
+
+Use Memori when:
+
+- The task depends on prior context
+- The user refers to previous sessions or decisions
+- You need known constraints, preferences, or patterns
+- You are starting a session and need current state
+- You want to understand what has already been done
+
+---
+
+## When not to use Memori
+
+Do not use Memori when:
+
+- The task is fully self-contained
+- The answer depends only on the current prompt
+- No historical context is required
+- The query is simple or one-off
+
+Avoid unnecessary recall.
+
+---
+
+## Recall behavior
+
+Recall is **agent-controlled and intentional**.
+
+Prefer targeted recall over broad queries.
+
+### Supported parameters (recall only)
+
+- `entityId` → user, agent, or system context
+- `projectId` → project or workspace context
+- `sessionId` → specific session
+- `dateStart` / `dateEnd` → time-bounded recall
+- `source` → type of memory
+- `signal` → how the memory was derived
+
+> Note: If a `sessionId` is provided, a `projectId` must also be provided.
+> All timestamps are stored in **UTC**.
+
+### Memory filters
+
+- `source`:
+  - constraint
+  - decision
+  - execution
+  - fact
+  - insight
+  - instruction
+  - status
+  - strategy
+  - task
+
+- `signal`:
+  - commit
+  - discovery
+  - failure
+  - inference
+  - pattern
+  - result
+  - update
+  - verification
+
+Use `source` and `signal` to prioritize high-signal memory when possible.
+
+### Default behavior (recall)
+
+- No date range → **all-time memory**
+- Use time bounds when narrowing results is necessary
+
+### Best practices
+
+- Start narrow (entity + project)
+- Add time bounds only when needed
+- Use `source` and `signal` to refine results
+- Expand scope only if needed
+- Do not recall on every turn
+
+---
+
+## Summary behavior
+
+Summaries are used for **state awareness**, not precise retrieval.
+
+Use:
+
+- `memori_recall_summary`
+
+### Supported parameters (summaries)
+
+- `projectId`
+- `sessionId`
+- `dateStart`
+- `dateEnd`
+
+> Summaries do **not** support `source` or `signal`.
+
+### Default behavior (summaries)
+
+- No date range → **last 24 hours**
+
+---
+
+## Daily brief behavior
+
+At the start of a meaningful session, retrieve a structured summary.
+
+Use the daily brief to understand:
+
+- Current state
+- Prior decisions
+- Constraints
+- Open work
+
+### Expected daily brief structure
+
+- Today at a glance
+- Top 3 next actions
+- Top 3 risks
+- Verify before acting
+- Recent decisions
+- Mission stack
+- Hard constraints
+- Current status
+- Open loops
+- Known failures and anti-patterns
+- Staleness warnings
+
+Treat this as the working state of the system.
+
+---
+
+## Typical workflow
+
+1. Start of session → retrieve summary
+2. During task → use targeted recall
+3. When memory is missing or incorrect → send feedback
+4. When limits are reached → degrade gracefully
+
+---
+
+## Safety and correctness
+
+- Do not invent memory
+- Do not assume memory is correct if it conflicts with the user
+- Verify before acting when needed
+- Treat recent instructions as higher priority than recalled memory
+
+---
+
+## Memori system guidance
+
+This section defines how you should interact with Memori beyond basic recall.
+
+---
+
+### 1. Feedback (`memori_feedback`)
+
+You are equipped with the `memori_feedback` tool to improve memory quality over time.
+
+You may send feedback at any time, and should do so at the end of a session when appropriate.
+
+Feedback should be sent when:
+
+- Recall results are irrelevant or missing key context
+- Important decisions or constraints were not captured
+- Memory quality degrades across sessions
+- Something works particularly well and should be reinforced
+
+Examples:
+
+- "Send feedback that recall missed a pricing constraint."
+- "Tell Memori the daily brief was accurate."
+- "Submit a bug report: you didn't remember my preferred language."
+
+#### Purpose
+
+Feedback improves:
+
+- Memory extraction quality
+- Recall relevance
+- Summary accuracy
+
+---
+
+### 2. Updates
+
+Memori evolves over time (new features, improved recall, better summaries).
+
+When updates are exposed:
+
+- Check for updates via system message or tool
+- Adapt behavior to use new capabilities
+
+When an update is detected:
+
+- Prefer newer recall patterns when available
+- Use improved summaries or classification outputs
+- Continue operating normally if no changes are required
+
+---
+
+### 3. Account Creation and Onboarding (`memori_signup`)
+
+You are equipped with the `memori_signup` tool to securely create an account and provision an API key for the user via the Memori CLI.
+
+Use this tool when:
+
+- The user explicitly asks to sign up, create an account, or get an API key for Memori.
+- You encounter an error indicating a missing `MEMORI_API_KEY` and the user provides their email address to get one.
+
+#### Behavior:
+
+- **Email Required:** If the user asks to sign up but **does not** provide an email address, you MUST ask them for their email first. Do not attempt to guess or hallucinate an email.
+- **Execution:** Once they provide an email, run `memori_signup` with that email.
+- **Follow-up:** The tool will trigger the underlying CLI and return a success or error message. Relay that message to the user, remind them to check their inbox for the API key, and instruct them to add it to their configuration (`~/.openclaw/openclaw.json` or `.env` file).
+- **Troubleshooting Errors:** If the tool fails with a `Permission denied`, `EACCES`, or `command not found` error, do not ask the user for permission to troubleshoot. Instead, immediately tell them that their CLI installation is broken or missing, and explicitly instruct them to run `npm install -g @memorilabs/memori` in their terminal to fix it.
+
+---
+
+### 4. Quota Awareness and Upgrades (`memori_quota`)
+
+You are equipped with the `memori_quota` tool to check the user's current memory usage and limits via the Memori CLI.
+
+Use this tool when:
+
+- The user explicitly asks about their quota, usage, storage, or how many memories they have left.
+- You encounter errors suggesting memory limits have been reached and want to confirm before degrading behavior.
+
+#### Behavior:
+
+- **No Parameters Required:** Simply invoke `memori_quota` — it requires no arguments.
+- **Execution:** The tool runs the underlying CLI and returns the user's current usage and quota.
+- **Follow-up:** Relay the result clearly to the user. If they are near or at their limit, explain the impact and suggest an upgrade.
+- **Troubleshooting Errors:** If the tool fails with a `Permission denied`, `EACCES`, or `command not found` error, do not ask the user for permission to troubleshoot. Instead, immediately tell them that their CLI installation is broken or missing, and explicitly instruct them to run `npm install -g @memorilabs/memori` in their terminal to fix it.
+
+#### When limits are reached or nearing:
+
+#### a. Degrade gracefully
+
+- Reduce recall scope (shorter time ranges)
+- Prioritize high-signal memory (decisions, constraints, key facts)
+- Avoid unnecessary or repeated recall calls
+
+#### b. Inform the human/operator
+
+Clearly communicate when limits impact performance.
+
+Example:
+
+> "Memory limits have been reached. I can continue with limited recall, or you can upgrade to restore full functionality."
+
+#### c. Suggest upgrades appropriately
+
+- Only prompt when performance is affected
+- Avoid repetitive or disruptive messaging
+- Keep messaging neutral and helpful
+
+---
+
+## Learn More
+
+- **npm Package**: https://www.npmjs.com/package/@memorilabs/openclaw-memori
+- **GitHub**: https://github.com/MemoriLabs/Memori
+- **Documentation**: https://memorilabs.ai/docs/memori-cloud/openclaw/overview/
+- **API Dashboard**: https://app.memorilabs.ai/
+- **Support**: [GitHub Issues](https://github.com/MemoriLabs/Memori/issues)

package/skills/memori/SKILL.md

@@ -0,0 +1,284 @@
+# Memori skills file
+
+You have access to Memori, agent-native memory infrastructure: an LLM-agnostic layer that structures memory from not just natural language, but also from agent trace that comes from execution.
+
+Memori automatically captures and structures memory from conversation and execution trace — including the agent's actions, tool results, decisions, and outcomes — and allows you to retrieve it on demand. Use it to maintain continuity across sessions, preserve decisions and constraints, and help the agent understand what it actually did so the next time it completes a task, it is more accurate and efficient.
+
+---
+
+## Core instruction
+
+At the start of a session, you should check the `SKILL.md` file
+
+Use it to understand:
+
+- Available capabilities
+- Tooling and integrations
+- Expected behaviors and constraints
+
+Treat `SKILL.md` as a source of truth for what you can do before taking action.
+
+---
+
+## When to use Memori
+
+Use Memori when:
+
+- The task depends on prior context
+- The user refers to previous sessions or decisions
+- You need known constraints, preferences, or patterns
+- You are starting a session and need current state
+- You want to understand what has already been done
+
+---
+
+## When not to use Memori
+
+Do not use Memori when:
+
+- The task is fully self-contained
+- The answer depends only on the current prompt
+- No historical context is required
+- The query is simple or one-off
+
+Avoid unnecessary recall.
+
+---
+
+## Recall behavior
+
+Recall is **agent-controlled and intentional**.
+
+Prefer targeted recall over broad queries.
+
+### Supported parameters (recall only)
+
+- `entityId` → user, agent, or system context
+- `projectId` → project or workspace context
+- `sessionId` → specific session
+- `dateStart` / `dateEnd` → time-bounded recall
+- `source` → type of memory
+- `signal` → how the memory was derived
+
+> Note: If a `sessionId` is provided, a `projectId` must also be provided.
+> All timestamps are stored in **UTC**.
+
+### Memory filters
+
+- `source`:
+  - constraint
+  - decision
+  - execution
+  - fact
+  - insight
+  - instruction
+  - status
+  - strategy
+  - task
+
+- `signal`:
+  - commit
+  - discovery
+  - failure
+  - inference
+  - pattern
+  - result
+  - update
+  - verification
+
+Use `source` and `signal` to prioritize high-signal memory when possible.
+
+### Default behavior (recall)
+
+- No date range → **all-time memory**
+- Use time bounds when narrowing results is necessary
+
+### Best practices
+
+- Start narrow (entity + project)
+- Add time bounds only when needed
+- Use `source` and `signal` to refine results
+- Expand scope only if needed
+- Do not recall on every turn
+
+---
+
+## Summary behavior
+
+Summaries are used for **state awareness**, not precise retrieval.
+
+Use:
+
+- `memori_recall_summary`
+
+### Supported parameters (summaries)
+
+- `projectId`
+- `sessionId`
+- `dateStart`
+- `dateEnd`
+
+> Summaries do **not** support `source` or `signal`.
+
+### Default behavior (summaries)
+
+- No date range → **last 24 hours**
+
+---
+
+## Daily brief behavior
+
+At the start of a meaningful session, retrieve a structured summary.
+
+Use the daily brief to understand:
+
+- Current state
+- Prior decisions
+- Constraints
+- Open work
+
+### Expected daily brief structure
+
+- Today at a glance
+- Top 3 next actions
+- Top 3 risks
+- Verify before acting
+- Recent decisions
+- Mission stack
+- Hard constraints
+- Current status
+- Open loops
+- Known failures and anti-patterns
+- Staleness warnings
+
+Treat this as the working state of the system.
+
+---
+
+## Typical workflow
+
+1. Start of session → retrieve summary
+2. During task → use targeted recall
+3. When memory is missing or incorrect → send feedback
+4. When limits are reached → degrade gracefully
+
+---
+
+## Safety and correctness
+
+- Do not invent memory
+- Do not assume memory is correct if it conflicts with the user
+- Verify before acting when needed
+- Treat recent instructions as higher priority than recalled memory
+
+---
+
+## Memori system guidance
+
+This section defines how you should interact with Memori beyond basic recall.
+
+---
+
+### 1. Feedback (`memori_feedback`)
+
+You are equipped with the `memori_feedback` tool to improve memory quality over time.
+
+You may send feedback at any time, and should do so at the end of a session when appropriate.
+
+Feedback should be sent when:
+
+- Recall results are irrelevant or missing key context
+- Important decisions or constraints were not captured
+- Memory quality degrades across sessions
+- Something works particularly well and should be reinforced
+
+Examples:
+
+- "Send feedback that recall missed a pricing constraint."
+- "Tell Memori the daily brief was accurate."
+- "Submit a bug report: you didn't remember my preferred language."
+
+#### Purpose
+
+Feedback improves:
+
+- Memory extraction quality
+- Recall relevance
+- Summary accuracy
+
+---
+
+### 2. Updates
+
+Memori evolves over time (new features, improved recall, better summaries).
+
+When updates are exposed:
+
+- Check for updates via system message or tool
+- Adapt behavior to use new capabilities
+
+When an update is detected:
+
+- Prefer newer recall patterns when available
+- Use improved summaries or classification outputs
+- Continue operating normally if no changes are required
+
+---
+
+### 3. Account Creation and Onboarding (`memori_signup`)
+
+You are equipped with the `memori_signup` tool to securely create an account and provision an API key for the user via the Memori CLI.
+
+Use this tool when:
+
+- The user explicitly asks to sign up, create an account, or get an API key for Memori.
+- You encounter an error indicating a missing `MEMORI_API_KEY` and the user provides their email address to get one.
+
+#### Behavior:
+
+- **Email Required:** If the user asks to sign up but **does not** provide an email address, you MUST ask them for their email first. Do not attempt to guess or hallucinate an email.
+- **Execution:** Once they provide an email, run `memori_signup` with that email.
+- **Follow-up:** The tool will trigger the underlying CLI and return a success or error message. Relay that message to the user, remind them to check their inbox for the API key, and instruct them to add it to their configuration (`~/.openclaw/openclaw.json` or `.env` file).
+- **Troubleshooting Errors:** If the tool fails with a `Permission denied`, `EACCES`, or `command not found` error, do not ask the user for permission to troubleshoot. Instead, immediately tell them that their CLI installation is broken or missing, and explicitly instruct them to run `npm install -g @memorilabs/memori` in their terminal to fix it.
+
+---
+
+### 4. Quota Awareness and Upgrades (`memori_quota`)
+
+You are equipped with the `memori_quota` tool to check the user's current memory usage and limits via the Memori CLI.
+
+Use this tool when:
+
+- The user explicitly asks about their quota, usage, storage, or how many memories they have left.
+- You encounter errors suggesting memory limits have been reached and want to confirm before degrading behavior.
+
+#### Behavior:
+
+- **No Parameters Required:** Simply invoke `memori_quota` — it requires no arguments.
+- **Execution:** The tool runs the underlying CLI and returns the user's current usage and quota.
+- **Follow-up:** Relay the result clearly to the user. If they are near or at their limit, explain the impact and suggest an upgrade.
+- **Troubleshooting Errors:** If the tool fails with a `Permission denied`, `EACCES`, or `command not found` error, do not ask the user for permission to troubleshoot. Instead, immediately tell them that their CLI installation is broken or missing, and explicitly instruct them to run `npm install -g @memorilabs/memori` in their terminal to fix it.
+
+#### When limits are reached or nearing:
+
+#### a. Degrade gracefully
+
+- Reduce recall scope (shorter time ranges)
+- Prioritize high-signal memory (decisions, constraints, key facts)
+- Avoid unnecessary or repeated recall calls
+
+#### b. Inform the human/operator
+
+Clearly communicate when limits impact performance.
+
+Example:
+
+> "Memory limits have been reached. I can continue with limited recall, or you can upgrade to restore full functionality."
+
+#### c. Suggest upgrades appropriately
+
+- Only prompt when performance is affected
+- Avoid repetitive or disruptive messaging
+- Keep messaging neutral and helpful
+
+---

package/skills/memori/skills.md

@@ -1,65 +0,0 @@
-## 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 |