@memclaw/memclaw 0.9.9

package/README.md

@@ -0,0 +1,276 @@
+# MemClaw
+
+Layered semantic memory plugin for OpenClaw with L0/L1/L2 tiered retrieval, automatic service management, and migration support from OpenClaw native memory.
+
+## Overview
+
+MemClaw is an OpenClaw plugin that provides advanced semantic memory capabilities using Cortex Memory's tiered memory architecture. It stores, searches, and recalls memories with intelligent layer-based retrieval that balances speed and context.
+
+## Features
+
+- **Three-Layer Memory Architecture**: L0 (abstract), L1 (overview), and L2 (full) layers for intelligent retrieval
+- **Automatic Service Management**: Auto-starts Qdrant vector database and cortex-mem-service
+- **Semantic Search**: Vector-based similarity search across all memory layers
+- **Session Management**: Create, list, and close memory sessions
+- **Migration Support**: One-click migration from OpenClaw native memory
+- **Cross-Platform**: Supports Windows x64 and macOS Apple Silicon
+
+## Architecture
+
+### Memory Layers
+
+| Layer | Tokens | Content | Role |
+|-------|--------|---------|------|
+| **L0 (Abstract)** | ~100 | High-level summary | Quick filtering |
+| **L1 (Overview)** | ~2000 | Key points + context | Context refinement |
+| **L2 (Full)** | Complete | Original content | Precise matching |
+
+The search engine queries all three layers internally and returns unified results with `snippet` and `content`.
+
+### System Components
+
+```
+OpenClaw + MemClaw Plugin
+         │
+         ├── cortex_search    → Search memories
+         ├── cortex_recall    → Recall with context
+         ├── cortex_add_memory → Store memories
+         ├── cortex_list_sessions → List sessions
+         ├── cortex_close_session → Close & extract
+         └── cortex_migrate   → Migrate existing memory
+                    │
+                    ▼
+         cortex-mem-service (port 8085)
+                    │
+                    ▼
+         Qdrant (port 6334)
+```
+
+## Installation
+
+### Requirements
+
+| Requirement | Details |
+|-------------|---------|
+| **Platforms** | Windows x64, macOS Apple Silicon |
+| **Node.js** | ≥ 22.0.0 |
+| **OpenClaw** | Installed and configured |
+
+### Install Plugin
+
+```bash
+openclaw plugins install @memclaw/memclaw
+```
+
+### Local Development Installation
+
+For developers who want to use a local version of memclaw or develop the plugin:
+
+```bash
+# Clone the repository
+git clone https://github.com/sopaco/cortex-mem.git
+cd cortex-mem/examples/@memclaw/plugin
+
+# Install dependencies
+bun install
+
+# Build the plugin
+bun run build
+```
+
+**Option A: Use plugins.load.paths**
+
+```json
+{
+  "plugins": {
+    "load": {
+      "paths": ["/path/to/cortex-mem/examples/@memclaw/plugin"]
+    },
+    "entries": {
+      "memclaw": { "enabled": true }
+    }
+  }
+}
+```
+
+**Option B: Symlink to extensions directory**
+
+```bash
+mkdir -p ~/.openclaw/extensions
+ln -sf "$(pwd)" ~/.openclaw/extensions/memclaw
+```
+
+Then enable in `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "memclaw": { "enabled": true }
+    }
+  }
+}
+```
+
+After making code changes, rebuild with `bun run build` and restart OpenClaw.
+
+### Configure OpenClaw
+
+Edit your `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "memclaw": {
+        "enabled": true,
+        "config": {
+          "serviceUrl": "http://localhost:8085",
+          "tenantId": "tenant_claw",
+          "autoStartServices": true
+        }
+      }
+    }
+  },
+  "agents": {
+    "defaults": {
+      "memorySearch": { "enabled": false }
+    }
+  }
+}
+```
+
+> **Note**: Set `memorySearch.enabled: false` to disable OpenClaw's built-in memory search and use MemClaw instead.
+
+### Configure LLM
+
+On first run, MemClaw creates a configuration file:
+
+| Platform | Path |
+|----------|------|
+| Windows | `%APPDATA%\memclaw\config.toml` |
+| macOS | `~/Library/Application Support/memclaw/config.toml` |
+
+Edit the configuration file and fill in required fields:
+
+```toml
+[llm]
+api_key = "xxx"  # REQUIRED: Your LLM API key
+
+[embedding]
+api_key = "xxx"  # REQUIRED: Your embedding API key (can be same as llm.api_key)
+```
+
+Then restart OpenClaw.
+
+## Available Tools
+
+### cortex_search
+
+Semantic search across all memories using L0/L1/L2 tiered retrieval.
+
+```json
+{
+  "query": "database architecture decisions",
+  "limit": 5,
+  "min_score": 0.6
+}
+```
+
+### cortex_recall
+
+Recall memories with more context (snippet + full content).
+
+```json
+{
+  "query": "user preferences for code style",
+  "limit": 10
+}
+```
+
+### cortex_add_memory
+
+Store a message for future retrieval.
+
+```json
+{
+  "content": "User prefers TypeScript with strict mode",
+  "role": "assistant",
+  "session_id": "default"
+}
+```
+
+### cortex_list_sessions
+
+List all memory sessions with status and message count.
+
+### cortex_close_session
+
+Close a session and trigger memory extraction pipeline (takes 30-60 seconds).
+
+```json
+{
+  "session_id": "default"
+}
+```
+
+### cortex_migrate
+
+Migrate from OpenClaw native memory to MemClaw. Run once during initial setup.
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `serviceUrl` | string | `http://localhost:8085` | Cortex Memory service URL |
+| `tenantId` | string | `tenant_claw` | Tenant ID for data isolation |
+| `autoStartServices` | boolean | `true` | Auto-start Qdrant and service |
+| `defaultSessionId` | string | `default` | Default session for memory operations |
+| `searchLimit` | number | `10` | Default number of search results |
+| `minScore` | number | `0.6` | Minimum relevance score (0-1) |
+
+## Quick Decision Flow
+
+1. **Need to find something** → `cortex_search`
+2. **Need more context** → `cortex_recall`
+3. **Save important information** → `cortex_add_memory`
+4. **Conversation complete** → `cortex_close_session`
+5. **First time setup** → `cortex_migrate`
+
+## Troubleshooting
+
+### Services Won't Start
+
+1. Check that ports 6333, 6334, 8085 are available
+2. Verify `api_key` fields are filled in config.toml
+3. Run `openclaw skills` to check plugin status
+
+### Search Returns No Results
+
+1. Run `cortex_list_sessions` to verify sessions exist
+2. Lower `min_score` threshold (default: 0.6)
+3. Check service health with `cortex-mem-cli stats`
+
+### Migration Fails
+
+1. Ensure OpenClaw workspace exists at `~/.openclaw/workspace`
+2. Verify memory files exist in `~/.openclaw/workspace/memory/`
+
+## CLI Reference
+
+For advanced users, use the cortex-mem-cli directly:
+
+```bash
+# List sessions
+cortex-mem-cli --config config.toml --tenant tenant_claw session list
+
+# Ensure all layers are generated
+cortex-mem-cli --config config.toml --tenant tenant_claw layers ensure-all
+
+# Rebuild vector index
+cortex-mem-cli --config config.toml --tenant tenant_claw vector reindex
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,100 @@
+/**
+ * MemClaw - Layered Semantic Memory for OpenClaw
+ *
+ * Provides:
+ * - L0/L1/L2 tiered memory retrieval
+ * - Automatic service startup (Qdrant + cortex-mem-service)
+ * - Migration from OpenClaw native memory
+ *
+ * Installation:
+ *   openclaw plugins install memclaw
+ *
+ * Configuration (in openclaw.json):
+ *   {
+ *     "plugins": {
+ *       "entries": {
+ *         "memclaw": {
+ *           "enabled": true,
+ *           "config": {
+ *             "serviceUrl": "http://localhost:8085",
+ *             "tenantId": "tenant_claw",
+ *             "autoStartServices": true
+ *           }
+ *         }
+ *       }
+ *     }
+ *   }
+ */
+export type { CortexMemClient } from './src/client.js';
+export type { MemClawConfig } from './src/config.js';
+interface PluginLogger {
+    debug?: (msg: string, ...args: unknown[]) => void;
+    info: (msg: string, ...args: unknown[]) => void;
+    warn: (msg: string, ...args: unknown[]) => void;
+    error: (msg: string, ...args: unknown[]) => void;
+}
+interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: object;
+    execute: (_id: string, params: Record<string, unknown>) => Promise<unknown>;
+    optional?: boolean;
+}
+interface PluginAPI {
+    pluginConfig?: Record<string, unknown>;
+    registerTool(tool: ToolDefinition, opts?: {
+        optional?: boolean;
+    }): void;
+    registerService(service: {
+        id: string;
+        start: () => Promise<void>;
+        stop: () => Promise<void>;
+    }): void;
+    logger: PluginLogger;
+}
+export default function memclawPlugin(api: PluginAPI): {
+    id: string;
+    name: string;
+    version: string;
+};
+export declare const plugin: {
+    id: string;
+    name: string;
+    version: string;
+    configSchema: {
+        type: string;
+        properties: {
+            serviceUrl: {
+                type: string;
+                default: string;
+            };
+            defaultSessionId: {
+                type: string;
+                default: string;
+            };
+            searchLimit: {
+                type: string;
+                default: number;
+            };
+            minScore: {
+                type: string;
+                default: number;
+            };
+            tenantId: {
+                type: string;
+                default: string;
+            };
+            autoStartServices: {
+                type: string;
+                default: boolean;
+            };
+        };
+        required: never[];
+    };
+    register(api: PluginAPI): {
+        id: string;
+        name: string;
+        version: string;
+    };
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGrD,UAAU,YAAY;IACrB,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAClD,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAChD,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAChD,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACjD;AAED,UAAU,cAAc;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,UAAU,SAAS;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,YAAY,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACxE,eAAe,CAAC,OAAO,EAAE;QACxB,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;KAC1B,GAAG,IAAI,CAAC;IACT,MAAM,EAAE,YAAY,CAAC;CACrB;AAGD,MAAM,CAAC,OAAO,UAAU,aAAa,CAAC,GAAG,EAAE,SAAS;;;;EAEnD;AAGD,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAgBJ,SAAS;;;;;CAGvB,CAAC"}

package/dist/index.js

@@ -0,0 +1,58 @@
+'use strict';
+/**
+ * MemClaw - Layered Semantic Memory for OpenClaw
+ *
+ * Provides:
+ * - L0/L1/L2 tiered memory retrieval
+ * - Automatic service startup (Qdrant + cortex-mem-service)
+ * - Migration from OpenClaw native memory
+ *
+ * Installation:
+ *   openclaw plugins install memclaw
+ *
+ * Configuration (in openclaw.json):
+ *   {
+ *     "plugins": {
+ *       "entries": {
+ *         "memclaw": {
+ *           "enabled": true,
+ *           "config": {
+ *             "serviceUrl": "http://localhost:8085",
+ *             "tenantId": "tenant_claw",
+ *             "autoStartServices": true
+ *           }
+ *         }
+ *       }
+ *     }
+ *   }
+ */
+Object.defineProperty(exports, '__esModule', { value: true });
+exports.plugin = void 0;
+exports.default = memclawPlugin;
+const plugin_impl_js_1 = require('./plugin-impl.js');
+// Default export - main plugin function
+function memclawPlugin(api) {
+	return (0, plugin_impl_js_1.createPlugin)(api);
+}
+// Named export - object style registration
+exports.plugin = {
+	id: 'memclaw',
+	name: 'MemClaw',
+	version: '0.9.9',
+	configSchema: {
+		type: 'object',
+		properties: {
+			serviceUrl: { type: 'string', default: 'http://localhost:8085' },
+			defaultSessionId: { type: 'string', default: 'default' },
+			searchLimit: { type: 'integer', default: 10 },
+			minScore: { type: 'number', default: 0.6 },
+			tenantId: { type: 'string', default: 'tenant_claw' },
+			autoStartServices: { type: 'boolean', default: true }
+		},
+		required: []
+	},
+	register(api) {
+		return (0, plugin_impl_js_1.createPlugin)(api);
+	}
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;;AAoCH,gCAEC;AApCD,qDAAgD;AAiChD,wCAAwC;AACxC,SAAwB,aAAa,CAAC,GAAc;IACnD,OAAO,IAAA,6BAAY,EAAC,GAAG,CAAC,CAAC;AAC1B,CAAC;AAED,2CAA2C;AAC9B,QAAA,MAAM,GAAG;IACrB,EAAE,EAAE,SAAS;IACb,IAAI,EAAE,SAAS;IACf,OAAO,EAAE,OAAO;IAChB,YAAY,EAAE;QACb,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACX,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,uBAAuB,EAAE;YAChE,gBAAgB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE;YACxD,WAAW,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,EAAE;YAC7C,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE;YAC1C,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,EAAE;YACpD,iBAAiB,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE;SACrD;QACD,QAAQ,EAAE,EAAE;KACZ;IACD,QAAQ,CAAC,GAAc;QACtB,OAAO,IAAA,6BAAY,EAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;CACD,CAAC"}

package/dist/plugin-impl.d.ts

@@ -0,0 +1,66 @@
+/**
+ * MemClaw Plugin Implementation
+ *
+ * Provides layered semantic memory for OpenClaw with:
+ * - Automatic service startup
+ * - Memory tools (search, recall, add, list, close)
+ * - Migration from OpenClaw native memory
+ */
+interface PluginLogger {
+    debug?: (msg: string, ...args: unknown[]) => void;
+    info: (msg: string, ...args: unknown[]) => void;
+    warn: (msg: string, ...args: unknown[]) => void;
+    error: (msg: string, ...args: unknown[]) => void;
+}
+interface CronAPI {
+    call(params: {
+        method: "add" | "remove" | "list";
+        params?: {
+            name?: string;
+            schedule?: {
+                kind: string;
+                expr: string;
+            };
+            sessionTarget?: string;
+            payload?: {
+                kind: string;
+                message: string;
+            };
+            delivery?: {
+                mode: string;
+            };
+        };
+    }): Promise<unknown>;
+}
+interface RuntimeAPI {
+    tools: {
+        get(name: "cron"): CronAPI;
+    };
+}
+interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: object;
+    execute: (_id: string, params: Record<string, unknown>) => Promise<unknown>;
+    optional?: boolean;
+}
+interface PluginAPI {
+    pluginConfig?: Record<string, unknown>;
+    registerTool(tool: ToolDefinition, opts?: {
+        optional?: boolean;
+    }): void;
+    registerService(service: {
+        id: string;
+        start: () => Promise<void>;
+        stop: () => Promise<void>;
+    }): void;
+    logger: PluginLogger;
+    runtime?: RuntimeAPI;
+}
+export declare function createPlugin(api: PluginAPI): {
+    id: string;
+    name: string;
+    version: string;
+};
+export {};
+//# sourceMappingURL=plugin-impl.d.ts.map

package/dist/plugin-impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-impl.d.ts","sourceRoot":"","sources":["../plugin-impl.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA0CH,UAAU,YAAY;IACpB,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAClD,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAChD,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAChD,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CAClD;AAED,UAAU,OAAO;IACf,IAAI,CAAC,MAAM,EAAE;QACX,MAAM,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;QAClC,MAAM,CAAC,EAAE;YACP,IAAI,CAAC,EAAE,MAAM,CAAC;YACd,QAAQ,CAAC,EAAE;gBAAE,IAAI,EAAE,MAAM,CAAC;gBAAC,IAAI,EAAE,MAAM,CAAA;aAAE,CAAC;YAC1C,aAAa,CAAC,EAAE,MAAM,CAAC;YACvB,OAAO,CAAC,EAAE;gBACR,IAAI,EAAE,MAAM,CAAC;gBACb,OAAO,EAAE,MAAM,CAAC;aACjB,CAAC;YACF,QAAQ,CAAC,EAAE;gBAAE,IAAI,EAAE,MAAM,CAAA;aAAE,CAAC;SAC7B,CAAC;KACH,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtB;AAED,UAAU,UAAU;IAClB,KAAK,EAAE;QACL,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;KAC5B,CAAC;CACH;AAED,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,UAAU,SAAS;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,YAAY,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACxE,eAAe,CAAC,OAAO,EAAE;QACvB,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;KAC3B,GAAG,IAAI,CAAC;IACT,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,CAAC,EAAE,UAAU,CAAC;CACtB;AAqPD,wBAAgB,YAAY,CAAC,GAAG,EAAE,SAAS;;;;EAwc1C"}