@memorilabs/openclaw-memori 0.0.11 → 0.0.13

package/README.md

@@ -75,7 +75,7 @@ It runs **after the agent responds** and does not impact latency.
 
 ---
 
-### 2. Agent-controlled recall
+### 2. Agent-Controlled Intelligent Recall
 
 Recall is **explicit and initiated by the agent**.
 

package/dist/index.js

@@ -1,7 +1,7 @@
 import { handleAugmentation } from './handlers/augmentation.js';
 import { PLUGIN_CONFIG } from './constants.js';
 import { MemoriLogger, loadSkillsContent } from './utils/index.js';
-import { registerAllTools } from './tools/index.js';
+import { registerUtilityTools, registerAuthenticatedTools } from './tools/index.js';
 import { registerCliCommands } from './cli/commands.js';
 const memoriPlugin = {
     id: PLUGIN_CONFIG.ID,
@@ -15,19 +15,20 @@ const memoriPlugin = {
             entityId: rawConfig?.entityId,
             projectId: rawConfig?.projectId,
         };
+        const logger = new MemoriLogger(api);
+        const skillsContent = loadSkillsContent(api.resolvePath.bind(api));
+        registerUtilityTools({ api, config, logger });
         if (!config.apiKey || !config.entityId) {
             api.logger.warn(`${PLUGIN_CONFIG.LOG_PREFIX} Missing apiKey or entityId in config. Plugin disabled.`);
             return;
         }
-        const logger = new MemoriLogger(api);
-        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}`);
         if (skillsContent) {
             api.on('before_prompt_build', () => ({ appendSystemContext: skillsContent }));
         }
         api.on('agent_end', (event, ctx) => handleAugmentation(event, ctx, config, logger));
-        registerAllTools({ api, config, logger });
+        registerAuthenticatedTools({ api, config, logger });
     },
 };
 export default memoriPlugin;

package/dist/tools/index.d.ts

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

package/dist/tools/index.js

@@ -3,10 +3,12 @@ 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) {
+export function registerUtilityTools(deps) {
     deps.api.registerTool(createMemoriSignupTool(deps));
-    deps.api.registerTool(createMemoriQuotaTool(deps));
+}
+export function registerAuthenticatedTools(deps) {
     deps.api.registerTool(createMemoriRecallTool(deps));
     deps.api.registerTool(createMemoriRecallSummaryTool(deps));
     deps.api.registerTool(createMemoriFeedbackTool(deps));
+    deps.api.registerTool(createMemoriQuotaTool(deps));
 }

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

@@ -6,10 +6,6 @@ export declare function createMemoriRecallTool(deps: ToolDeps): {
     parameters: {
         type: string;
         properties: {
-            query: {
-                type: string;
-                description: string;
-            };
             dateStart: {
                 type: string;
                 description: string;
@@ -37,10 +33,8 @@ export declare function createMemoriRecallTool(deps: ToolDeps): {
                 enum: string[];
             };
         };
-        required: string[];
     };
     execute(_toolCallId: string, params: {
-        query: string;
         dateStart?: string;
         dateEnd?: string;
         projectId?: string;

package/dist/tools/memori-recall.js

@@ -8,10 +8,6 @@ export function createMemoriRecallTool(deps) {
         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.',
-                },
                 dateStart: {
                     type: 'string',
                     description: 'ISO 8601 (MUST be UTC) date string to filter memories created on or after this time',
@@ -58,8 +54,6 @@ export function createMemoriRecallTool(deps) {
                     ],
                 },
             },
-            // Force the LLM to ALWAYS provide a search query
-            required: ['query'],
         },
         async execute(_toolCallId, params) {
             try {

package/dist/version.d.ts

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

package/dist/version.js

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

package/openclaw.plugin.json

@@ -1,12 +1,18 @@
 {
   "id": "openclaw-memori",
   "name": "Memori System",
-  "version": "0.0.10",
+  "version": "0.0.13",
   "description": "Hosted memory backend",
   "kind": "memory",
   "main": "dist/index.js",
   "contracts": {
-    "tools": ["memori_recall", "memori_recall_summary", "memori_feedback"]
+    "tools": [
+      "memori_recall",
+      "memori_recall_summary",
+      "memori_feedback",
+      "memori_signup",
+      "memori_quota"
+    ]
   },
   "uiHints": {
     "apiKey": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memorilabs/openclaw-memori",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "description": "Official MemoriLabs.ai long-term memory plugin for OpenClaw",
   "type": "module",
   "main": "./dist/index.js",

package/skills/clawhub/SKILL.md

@@ -1,8 +1,10 @@
 ---
 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
+description: Agent-native memory for OpenClaw that structures memory from agent trace, execution history, decisions, tool calls, and conversations into durable long-term memory primitives.
+license: Apache-2.0
+homepage: https://github.com/MemoriLabs/Memori
+repository: https://github.com/MemoriLabs/Memori.git
 compatibility:
   - openclaw
 metadata:
@@ -19,290 +21,191 @@ metadata:
       - https://api.memorilabs.ai
 ---
 
-# Memori skills file
+# Memori - Structured Long-term Memory for OpenClaw
 
-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.
+Give your OpenClaw agents persistent, structured memory derived from agent execution, tool usage, workflow history, and conversations. Memori integrates seamlessly in the background via lifecycle hooks and provides agents with the tools to retrieve context when it is relevant.
 
-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 Workflow
 
----
-
-## 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:
+Memori operates on two parallel tracks through standard OpenClaw lifecycle hooks:
 
-- 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
+### 1. Advanced Augmentation (automatic)
 
-Avoid unnecessary recall.
+After each interaction, Memori converts raw session data into structured, reusable memories asynchronously.
 
----
-
-## Recall behavior
+- 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
 
-Recall is **agent-controlled and intentional**.
+This is how structured memory is continuously built and updated over time. It runs after the agent responds and does not impact latency.
 
-Prefer targeted recall over broad queries.
+### 2. Agent-Controlled-Intelligent Recall
 
-### Supported parameters (recall only)
+Recall is explicit and initiated by the agent.
 
-- `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
+Memori separates memory creation from memory recall:
 
-> Note: If a `sessionId` is provided, a `projectId` must also be provided.
-> All timestamps are stored in **UTC**.
+- Creation is automatic (advanced augmentation)
+- Recall is intentional (agent-controlled)
 
-### Memory filters
+Agents decide:
 
-- `source`:
-  - constraint
-  - decision
-  - execution
-  - fact
-  - insight
-  - instruction
-  - status
-  - strategy
-  - task
+- When to recall
+- What scope to recall from
+- How much history to include
 
-- `signal`:
-  - commit
-  - discovery
-  - failure
-  - inference
-  - pattern
-  - result
-  - update
-  - verification
+To maintain an efficient context window, Memori equips the agent with specific tools to retrieve history when required for the conversation:
 
-Use `source` and `signal` to prioritize high-signal memory when possible.
+1. **`memori_recall`**: Searches the structured memory graph for specific facts, constraints, and prior decisions.
+2. **`memori_recall_summary`**: Retrieves structured daily briefs and rolling summaries of prior sessions.
+3. **`memori_feedback`**: Reports on memory quality to improve extraction accuracy.
 
-### Default behavior (recall)
+## Installation
 
-- No date range → **all-time memory**
-- Use time bounds when narrowing results is necessary
+```bash
+openclaw plugins install @memorilabs/openclaw-memori
+```
 
-### Best practices
+## Configuration
 
-- 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
+Add to your `~/.openclaw/openclaw.json` or use the `openclaw memori init` CLI command to set up your workspace:
 
----
+```bash
+openclaw memori init \
+  --api-key "YOUR_MEMORI_API_KEY" \
+  --entity-id "your-entity-id" \
+  --project-id "your-project-id"
+```
 
-## Summary behavior
+Alternatively, configure it directly via JSON:
 
-Summaries are used for **state awareness**, not precise retrieval.
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclaw-memori": {
+        "enabled": true,
+        "config": {
+          "apiKey": "${MEMORI_API_KEY}",
+          "entityId": "openclaw-user",
+          "projectId": "default-project"
+        }
+      }
+    }
+  }
+}
+```
 
-Use:
+### Configuration Options
 
-- `memori_recall_summary`
+- **apiKey** (required): Your Memori API key from [memorilabs.ai](https://app.memorilabs.ai/signup)
+- **entityId** (required): Unique identifier for this user's memories
+- **projectId** (required): Scopes all memories to a specific project or workspace
 
-### Supported parameters (summaries)
+## Agentic Tool Guidelines
 
-- `projectId`
-- `sessionId`
-- `dateStart`
-- `dateEnd`
+When this plugin is active, the agent is equipped with tools to manage long-term context. The agent should use its discretion to call these tools when helpful:
 
-> Summaries do **not** support `source` or `signal`.
+- **Contextual Recall**: The agent can run a `memori_recall` search to retrieve relevant details if context is missing regarding user preferences.
+- **Summaries**: The agent can utilize the `memori_recall_summary` tool to construct a brief if a user requests a recap.
+- **Account Creation**: If a user explicitly asks to create an account, the agent can use the `memori_signup` tool to initiate the process by asking for an email address. Keys are never returned in the chat. The system securely emails the credentials to the user, who must then manually configure them to activate the plugin.
+- **Quota Monitoring**: The agent can use the `memori_quota` tool to check the user's current memory usage and storage limits to communicate quota status or gracefully degrade behavior if limits are reached.
+- **Date Defaults**: If the agent chooses to search memory, providing specific start/end dates is recommended to keep context windows efficient. Omitting dates will search all available history.
 
-### Default behavior (summaries)
+## Verification
 
-- No date range → **last 24 hours**
+Check that the plugin is working and securely connected:
 
----
+```bash
+# Verify plugin is securely connected to the API
+openclaw memori status --check
 
-## Daily brief behavior
+# Check for Memori logs in gateway output
+openclaw gateway logs --filter "[Memori]"
+```
 
-At the start of a meaningful session, retrieve a structured summary.
+## Quota Management
 
-Use the daily brief to understand:
+Check your current API quota:
 
-- Current state
-- Prior decisions
-- Constraints
-- Open work
+```bash
+memori quota
+```
 
-### Expected daily brief structure
+**Example output:**
 
-- 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
+```
+ __  __                           _
+|  \/  | ___ _ __ ___   ___  _ __(_)
+| |\/| |/ _ \ '_ ` _ \ / _ \| '__| |
+| |  | |  __/ | | | | | (_) | |  | |
+|_|  |_|\___|_| |_| |_|\___/|_|  |_|
+                  perfectam memoriam
+                       memorilabs.ai
 
-Treat this as the working state of the system.
++ Maximum # of Memories: 100
++ Current # of Memories: 0
 
----
++ You are not currently over quota.
+```
 
-## Typical workflow
+Use this to monitor usage and upgrade if needed.
 
-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
+## Performance
 
----
+- **Automatic deduplication** prevents memory bloat
+- **Agent-controlled retrieval** ensures token usage remains targeted, compact, and actionable
+- **Semantic ranking** ensures relevant memories surface first
 
-## Safety and correctness
+## Privacy, Consent & Data Handling
 
-- 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
+**Explicit Opt-In Required:** Memori requires the user to explicitly configure an API key (`MEMORI_API_KEY`) and an `entityId`. **No data is captured or transmitted unless these credentials are actively provided by the user.**
 
----
+- ✅ Conversations are securely transmitted to the Memori backend (`https://api.memorilabs.ai`) only when the plugin is fully configured by the user.
+- ✅ Data is encrypted in transit and at rest.
+- ✅ Users control their data scope via their specific `projectId` and `entityId`.
+- ✅ The backend automatically filters sensitive data (API keys, passwords, secrets) prior to storage.
 
-## Memori system guidance
+For details: [Memori Privacy Policy](https://memorilabs.ai/privacy)
 
-This section defines how you should interact with Memori beyond basic recall.
+## Memory Persistence
 
----
+Memories persist safely across:
 
-### 1. Feedback (`memori_feedback`)
+- Session restarts
+- Gateway restarts
+- System reboots
+- OpenClaw upgrades
 
-You are equipped with the `memori_feedback` tool to improve memory quality over time.
+All storage is handled by the Memori backend and is scoped safely alongside your local `MEMORY.md` file without overwriting it.
 
-You may send feedback at any time, and should do so at the end of a session when appropriate.
+## Troubleshooting
 
-Feedback should be sent when:
+**Plugin not loading:**
 
-- 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
-
----
+- Verify `enabled: true` in openclaw.json
+- Check API key: `echo $MEMORI_API_KEY`
+- Restart gateway: `openclaw gateway restart`
 
-### 2. Updates
+**No memories captured:**
 
-Memori evolves over time (new features, improved recall, better summaries).
+- Check gateway logs for `[Memori]` errors
+- Verify API endpoint reachable
+- Test API key: `memori quota`
 
-When updates are exposed:
+**Memories not recalled:**
 
-- Check for updates via system message or tool
-- Adapt behavior to use new capabilities
+- Did the agent utilize the retrieval tool? Check your gateway logs for `memori_recall` tool execution. If it didn't use the tool, you can prompt it to search its memory.
+- Ensure `entityId` and `projectId` are consistent across sessions.
+- Verify memories exist: `memori quota` shows count > 0.
 
-When an update is detected:
+**Quota exceeded:**
 
-- 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
-
----
+- Run `memori quota` to check usage
+- Upgrade at [memorilabs.ai](https://app.memorilabs.ai/)
+- Or clear old memories via dashboard
 
 ## Learn More
 
@@ -311,3 +214,7 @@ Example:
 - **Documentation**: https://memorilabs.ai/docs/memori-cloud/openclaw/overview/
 - **API Dashboard**: https://app.memorilabs.ai/
 - **Support**: [GitHub Issues](https://github.com/MemoriLabs/Memori/issues)
+
+## Notes
+
+This skill informs the agent about the Memori plugin. The plugin must be installed separately via npm. Once installed, memory capture happens in the background, and the agent is empowered to explicitly query its memories when needed.