@memorilabs/openclaw-memori 0.0.6 → 0.0.7-beta

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/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/SKILL.md'), 'utf-8');
+    }
+    catch {
+        return '';
+    }
+}

package/dist/version.d.ts

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

package/dist/version.js

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

package/openclaw.plugin.json

@@ -1,10 +1,20 @@
 {
   "id": "openclaw-memori",
   "name": "Memori System",
-  "version": "0.0.2",
+  "version": "0.0.13",
   "description": "Hosted memory backend",
   "kind": "memory",
   "main": "dist/index.js",
+  "contracts": {
+    "tools": [
+      "memori_recall",
+      "memori_recall_summary",
+      "memori_compaction",
+      "memori_feedback",
+      "memori_signup",
+      "memori_quota"
+    ]
+  },
   "uiHints": {
     "apiKey": {
       "label": "Memori API Key",
@@ -16,6 +26,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 +44,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.6",
+  "version": "0.0.7-beta",
   "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.8"
+    "@memorilabs/memori": "^0.1.23-beta"
   }
 }

package/skills/clawhub/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: memori
+id: '@memorilabs/openclaw-memori'
+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:
+  openclaw:
+    requires:
+      env:
+        - MEMORI_API_KEY
+        - ENTITY_ID
+        - PROJECT_ID
+      bins:
+        - memori
+    primaryEnv: MEMORI_API_KEY
+    externalServices:
+      - https://api.memorilabs.ai
+---
+
+# Memori - Structured Long-term Memory for OpenClaw
+
+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.
+
+## Core Workflow
+
+Memori operates on two parallel tracks through standard OpenClaw lifecycle hooks:
+
+### 1. Advanced Augmentation (automatic)
+
+After each interaction, Memori converts raw session data into structured, reusable memories asynchronously.
+
+- 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
+
+This is how structured memory is continuously built and updated over time. It runs after the agent responds and does not impact latency.
+
+### 2. Agent-Controlled-Intelligent Recall
+
+Recall is explicit and initiated by the agent.
+
+Memori separates memory creation from memory recall:
+
+- Creation is automatic (advanced augmentation)
+- Recall is intentional (agent-controlled)
+
+Agents decide:
+
+- When to recall
+- What scope to recall from
+- How much history to include
+
+To maintain an efficient context window, Memori equips the agent with specific tools to retrieve history when required for the conversation:
+
+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_compaction`**: Retrieves structured post-compaction brief to continue task without interruption.
+4. **`memori_feedback`**: Reports on memory quality to improve extraction accuracy.
+
+## Installation
+
+```bash
+openclaw plugins install @memorilabs/openclaw-memori
+```
+
+## Configuration
+
+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"
+```
+
+Alternatively, configure it directly via JSON:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclaw-memori": {
+        "enabled": true,
+        "config": {
+          "apiKey": "${MEMORI_API_KEY}",
+          "entityId": "openclaw-user",
+          "projectId": "default-project"
+        }
+      }
+    }
+  }
+}
+```
+
+### Configuration Options
+
+- **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
+
+## Agentic Tool Guidelines
+
+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:
+
+- **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.
+
+## Verification
+
+Check that the plugin is working and securely connected:
+
+```bash
+# Verify plugin is securely connected to the API
+openclaw memori status --check
+
+# Check for Memori logs in gateway output
+openclaw gateway logs --filter "[Memori]"
+```
+
+## Quota Management
+
+Check your current API quota:
+
+```bash
+memori quota
+```
+
+**Example output:**
+
+```
+ __  __                           _
+|  \/  | ___ _ __ ___   ___  _ __(_)
+| |\/| |/ _ \ '_ ` _ \ / _ \| '__| |
+| |  | |  __/ | | | | | (_) | |  | |
+|_|  |_|\___|_| |_| |_|\___/|_|  |_|
+                  perfectam memoriam
+                       memorilabs.ai
+
++ Maximum # of Memories: 100
++ Current # of Memories: 0
+
++ You are not currently over quota.
+```
+
+Use this to monitor usage and upgrade if needed.
+
+## Performance
+
+- **Automatic deduplication** prevents memory bloat
+- **Agent-controlled retrieval** ensures token usage remains targeted, compact, and actionable
+- **Semantic ranking** ensures relevant memories surface first
+
+## Privacy, Consent & Data Handling
+
+**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.
+
+For details: [Memori Privacy Policy](https://memorilabs.ai/privacy)
+
+## Memory Persistence
+
+Memories persist safely across:
+
+- Session restarts
+- Gateway restarts
+- System reboots
+- OpenClaw upgrades
+
+All storage is handled by the Memori backend and is scoped safely alongside your local `MEMORY.md` file without overwriting it.
+
+## Troubleshooting
+
+**Plugin not loading:**
+
+- Verify `enabled: true` in openclaw.json
+- Check API key: `echo $MEMORI_API_KEY`
+- Restart gateway: `openclaw gateway restart`
+
+**No memories captured:**
+
+- Check gateway logs for `[Memori]` errors
+- Verify API endpoint reachable
+- Test API key: `memori quota`
+
+**Memories not recalled:**
+
+- 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.
+
+**Quota exceeded:**
+
+- Run `memori quota` to check usage
+- Upgrade at [memorilabs.ai](https://app.memorilabs.ai/)
+- Or clear old memories via dashboard
+
+## 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)
+
+## 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.