@memclaw/memclaw 0.9.16 → 0.9.17

package/README.md

@@ -1,5 +1,7 @@
 # MemClaw
 
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
 Layered semantic memory plugin for OpenClaw with L0/L1/L2 tiered retrieval, automatic service management, and migration support from OpenClaw native memory.
 
 ## Overview
@@ -13,6 +15,7 @@ MemClaw is an OpenClaw plugin that provides advanced semantic memory capabilitie
 - **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
+- **Easy Configuration**: Configure LLM/Embedding directly through OpenClaw plugin settings
 - **Cross-Platform**: Supports Windows x64 and macOS Apple Silicon
 
 ## Architecture
@@ -53,7 +56,7 @@ OpenClaw + MemClaw Plugin
 | Requirement | Details |
 |-------------|---------|
 | **Platforms** | Windows x64, macOS Apple Silicon |
-| **Node.js** | ≥ 22.0.0 |
+| **Node.js** | ≥ 20.0.0 |
 | **OpenClaw** | Installed and configured |
 
 ### Install Plugin
@@ -114,9 +117,11 @@ Then enable in `openclaw.json`:
 
 After making code changes, rebuild with `bun run build` and restart OpenClaw.
 
-### Configure OpenClaw
+## Configuration
+
+### Plugin Configuration
 
-Edit your `openclaw.json`:
+Configure MemClaw directly through OpenClaw plugin settings in `openclaw.json`:
 
 ```json
 {
@@ -127,7 +132,13 @@ Edit your `openclaw.json`:
         "config": {
           "serviceUrl": "http://localhost:8085",
           "tenantId": "tenant_claw",
-          "autoStartServices": true
+          "autoStartServices": true,
+          "llmApiBaseUrl": "https://api.openai.com/v1",
+          "llmApiKey": "your-llm-api-key",
+          "llmModel": "gpt-4o-mini",
+          "embeddingApiBaseUrl": "https://api.openai.com/v1",
+          "embeddingApiKey": "your-embedding-api-key",
+          "embeddingModel": "text-embedding-3-small"
         }
       }
     }
@@ -142,26 +153,33 @@ Edit your `openclaw.json`:
 
 > **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` |
+### Configuration Options
 
-Edit the configuration file and fill in required fields:
+| 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) |
+| `qdrantPort` | number | `6334` | Qdrant port (gRPC) |
+| `servicePort` | number | `8085` | cortex-mem-service port |
+| `llmApiBaseUrl` | string | `https://api.openai.com/v1` | LLM API endpoint URL |
+| `llmApiKey` | string | - | LLM API key (required) |
+| `llmModel` | string | `gpt-5-mini` | LLM model name |
+| `embeddingApiBaseUrl` | string | `https://api.openai.com/v1` | Embedding API endpoint URL |
+| `embeddingApiKey` | string | - | Embedding API key (required) |
+| `embeddingModel` | string | `text-embedding-3-small` | Embedding model name |
 
-```toml
-[llm]
-api_key = "xxx"  # REQUIRED: Your LLM API key
+### Configuration via UI
 
-[embedding]
-api_key = "xxx"  # REQUIRED: Your embedding API key (can be same as llm.api_key)
-```
+You can also configure the plugin through OpenClaw UI:
 
-Then restart OpenClaw.
+1. Open OpenClaw Settings (`openclaw.json` or via UI)
+2. Navigate to Plugins → MemClaw → Configuration
+3. Fill in the required fields for LLM and Embedding
+4. Save and **restart OpenClaw Gateway** for changes to take effect
 
 ## Available Tools
 
@@ -214,42 +232,47 @@ Close a session and trigger memory extraction pipeline (takes 30-60 seconds).
 }
 ```
 
+> **Important**: Call this tool proactively at natural checkpoints, not just when the conversation ends. Ideal timing: after completing important tasks, topic transitions, or accumulating enough conversation content.
+
 ### cortex_migrate
 
 Migrate from OpenClaw native memory to MemClaw. Run once during initial setup.
 
-## Configuration Options
+### cortex_maintenance
 
-| 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) |
+Perform periodic maintenance on MemClaw data (prune, reindex, ensure-all layers).
 
 ## 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`
+| Scenario | Tool |
+|----------|------|
+| Need to find information | `cortex_search` |
+| Need more context | `cortex_recall` |
+| Save important information | `cortex_add_memory` |
+| Complete a task/topic | `cortex_close_session` |
+| First-time use with existing memories | `cortex_migrate` |
+
+For detailed guidance on tool selection, session lifecycle, and best practices, see the [Skills Documentation](skills/memclaw/SKILL.md).
 
 ## Troubleshooting
 
+### Plugin Not Working
+
+1. **Check Configuration**: Open OpenClaw settings and verify MemClaw plugin configuration, especially LLM and Embedding settings
+2. **Restart OpenClaw Gateway**: Configuration changes require a gateway restart to take effect
+3. **Verify Services**: Run `cortex_list_sessions` to check if the service is responding
+
 ### Services Won't Start
 
 1. Check that ports 6333, 6334, 8085 are available
-2. Verify `api_key` fields are filled in config.toml
+2. Verify LLM and Embedding credentials are configured correctly
 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`
+3. Ensure memories have been stored (run `cortex_close_session` to extract memories)
 
 ### Migration Fails
 
@@ -271,6 +294,12 @@ cortex-mem-cli --config config.toml --tenant tenant_claw layers ensure-all
 cortex-mem-cli --config config.toml --tenant tenant_claw vector reindex
 ```
 
+## Documentation
+
+- **[Skills Documentation](skills/memclaw/SKILL.md)** — Agent skill guide with troubleshooting
+- **[Best Practices](skills/memclaw/references/best-practices.md)** — Tool selection, session lifecycle, search strategies
+- **[Tools Reference](skills/memclaw/references/tools.md)** — Detailed tool parameters and examples
+
 ## License
 
 MIT

package/dist/index.js

@@ -1,4 +1,4 @@
-"use strict";
+'use strict';
 /**
  * MemClaw - Layered Semantic Memory for OpenClaw
  *
@@ -26,33 +26,33 @@
  *     }
  *   }
  */
-Object.defineProperty(exports, "__esModule", { value: true });
+Object.defineProperty(exports, '__esModule', { value: true });
 exports.plugin = void 0;
 exports.default = memclawPlugin;
-const plugin_impl_js_1 = require("./plugin-impl.js");
+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);
+	return (0, plugin_impl_js_1.createPlugin)(api);
 }
 // Named export - object style registration
 exports.plugin = {
-    id: 'memclaw',
-    name: 'MemClaw',
-    version: '0.9.16',
-    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);
-    }
+	id: 'memclaw',
+	name: 'MemClaw',
+	version: '0.9.17',
+	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
+//# sourceMappingURL=index.js.map

package/dist/src/config.js

@@ -1,44 +1,63 @@
-"use strict";
+'use strict';
 /**
  * Configuration management for MemClaw
  *
  * Handles platform-specific config paths, config file generation,
  * and auto-opening config files for user editing.
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
+var __createBinding =
+	(this && this.__createBinding) ||
+	(Object.create
+		? function (o, m, k, k2) {
+				if (k2 === undefined) k2 = k;
+				var desc = Object.getOwnPropertyDescriptor(m, k);
+				if (!desc || ('get' in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+					desc = {
+						enumerable: true,
+						get: function () {
+							return m[k];
+						}
+					};
+				}
+				Object.defineProperty(o, k2, desc);
+			}
+		: function (o, m, k, k2) {
+				if (k2 === undefined) k2 = k;
+				o[k2] = m[k];
+			});
+var __setModuleDefault =
+	(this && this.__setModuleDefault) ||
+	(Object.create
+		? function (o, v) {
+				Object.defineProperty(o, 'default', { enumerable: true, value: v });
+			}
+		: function (o, v) {
+				o['default'] = v;
+			});
+var __importStar =
+	(this && this.__importStar) ||
+	(function () {
+		var ownKeys = function (o) {
+			ownKeys =
+				Object.getOwnPropertyNames ||
+				function (o) {
+					var ar = [];
+					for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+					return ar;
+				};
+			return ownKeys(o);
+		};
+		return function (mod) {
+			if (mod && mod.__esModule) return mod;
+			var result = {};
+			if (mod != null)
+				for (var k = ownKeys(mod), i = 0; i < k.length; i++)
+					if (k[i] !== 'default') __createBinding(result, mod, k[i]);
+			__setModuleDefault(result, mod);
+			return result;
+		};
+	})();
+Object.defineProperty(exports, '__esModule', { value: true });
 exports.getDataDir = getDataDir;
 exports.getConfigPath = getConfigPath;
 exports.generateConfigTemplate = generateConfigTemplate;
@@ -48,28 +67,29 @@ exports.parseConfig = parseConfig;
 exports.validateConfig = validateConfig;
 exports.updateConfigFromPlugin = updateConfigFromPlugin;
 exports.mergeConfigWithPlugin = mergeConfigWithPlugin;
-const fs = __importStar(require("fs"));
-const path = __importStar(require("path"));
-const os = __importStar(require("os"));
-const child_process_1 = require("child_process");
+const fs = __importStar(require('fs'));
+const path = __importStar(require('path'));
+const os = __importStar(require('os'));
+const child_process_1 = require('child_process');
 // Platform-specific paths
 function getDataDir() {
-    const platform = process.platform;
-    if (platform === 'win32') {
-        return path.join(process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'), 'memclaw');
-    }
-    else if (platform === 'darwin') {
-        return path.join(os.homedir(), 'Library', 'Application Support', 'memclaw');
-    }
-    else {
-        return path.join(os.homedir(), '.local', 'share', 'memclaw');
-    }
+	const platform = process.platform;
+	if (platform === 'win32') {
+		return path.join(
+			process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'),
+			'memclaw'
+		);
+	} else if (platform === 'darwin') {
+		return path.join(os.homedir(), 'Library', 'Application Support', 'memclaw');
+	} else {
+		return path.join(os.homedir(), '.local', 'share', 'memclaw');
+	}
 }
 function getConfigPath() {
-    return path.join(getDataDir(), 'config.toml');
+	return path.join(getDataDir(), 'config.toml');
 }
 function generateConfigTemplate() {
-    return `# MemClaw Configuration
+	return `# MemClaw Configuration
 #
 # This file was auto-generated. Please fill in the required values below.
 # All sections are required - missing sections will cause config to be ignored.
@@ -100,6 +120,7 @@ timeout_secs = 30
 [server]
 host = "localhost"
 port = 8085
+cors_origins = ["*"]
 
 # Logging Configuration
 [logging]
@@ -113,230 +134,222 @@ enable_intent_analysis = false
 `;
 }
 function ensureConfigExists() {
-    const dataDir = getDataDir();
-    const configPath = getConfigPath();
-    if (!fs.existsSync(dataDir)) {
-        fs.mkdirSync(dataDir, { recursive: true });
-    }
-    if (!fs.existsSync(configPath)) {
-        const template = generateConfigTemplate();
-        fs.writeFileSync(configPath, template, 'utf-8');
-        return { created: true, path: configPath };
-    }
-    return { created: false, path: configPath };
+	const dataDir = getDataDir();
+	const configPath = getConfigPath();
+	if (!fs.existsSync(dataDir)) {
+		fs.mkdirSync(dataDir, { recursive: true });
+	}
+	if (!fs.existsSync(configPath)) {
+		const template = generateConfigTemplate();
+		fs.writeFileSync(configPath, template, 'utf-8');
+		return { created: true, path: configPath };
+	}
+	return { created: false, path: configPath };
 }
 function openConfigFile(configPath) {
-    return new Promise((resolve, reject) => {
-        const platform = process.platform;
-        let command;
-        let args = [];
-        if (platform === 'win32') {
-            command = 'cmd';
-            args = ['/c', 'start', '""', configPath];
-        }
-        else if (platform === 'darwin') {
-            command = 'open';
-            args = [configPath];
-        }
-        else {
-            command = 'xdg-open';
-            args = [configPath];
-        }
-        const proc = (0, child_process_1.spawn)(command, args, { detached: true, stdio: 'ignore' });
-        proc.on('error', (err) => {
-            reject(err);
-        });
-        proc.unref();
-        resolve();
-    });
+	return new Promise((resolve, reject) => {
+		const platform = process.platform;
+		let command;
+		let args = [];
+		if (platform === 'win32') {
+			command = 'cmd';
+			args = ['/c', 'start', '""', configPath];
+		} else if (platform === 'darwin') {
+			command = 'open';
+			args = [configPath];
+		} else {
+			command = 'xdg-open';
+			args = [configPath];
+		}
+		const proc = (0, child_process_1.spawn)(command, args, { detached: true, stdio: 'ignore' });
+		proc.on('error', (err) => {
+			reject(err);
+		});
+		proc.unref();
+		resolve();
+	});
 }
 function parseConfig(configPath) {
-    const content = fs.readFileSync(configPath, 'utf-8');
-    const config = {};
-    let currentSection = '';
-    for (const line of content.split('\n')) {
-        const trimmed = line.trim();
-        // Skip comments and empty lines
-        if (trimmed.startsWith('#') || trimmed === '')
-            continue;
-        // Section header
-        const sectionMatch = trimmed.match(/^\[(\w+)\]$/);
-        if (sectionMatch) {
-            currentSection = sectionMatch[1];
-            config[currentSection] = {};
-            continue;
-        }
-        // Key-value pair
-        const kvMatch = trimmed.match(/^(\w+)\s*=\s*"([^"]*)"(?:\s*$|\s*#)/) ||
-            trimmed.match(/^(\w+)\s*=\s*(\d+(?:\.\d+)?)(?:\s*$|\s*#)/) ||
-            trimmed.match(/^(\w+)\s*=\s*(true|false)(?:\s*$|\s*#)/);
-        if (kvMatch && currentSection) {
-            const key = kvMatch[1];
-            let value = kvMatch[2];
-            // Convert to appropriate type
-            if (value === 'true')
-                value = true;
-            else if (value === 'false')
-                value = false;
-            else if (/^\d+$/.test(value))
-                value = parseInt(value, 10);
-            else if (/^\d+\.\d+$/.test(value))
-                value = parseFloat(value);
-            config[currentSection] = config[currentSection] || {};
-            config[currentSection][key] = value;
-        }
-    }
-    // Apply defaults
-    return {
-        qdrant: {
-            url: 'http://localhost:6334',
-            collection_name: 'memclaw',
-            timeout_secs: 30,
-            ...(config.qdrant || {})
-        },
-        llm: {
-            api_base_url: 'https://api.openai.com/v1',
-            api_key: '',
-            model_efficient: 'gpt-5-mini',
-            temperature: 0.1,
-            max_tokens: 4096,
-            ...(config.llm || {})
-        },
-        embedding: {
-            api_base_url: 'https://api.openai.com/v1',
-            api_key: '',
-            model_name: 'text-embedding-3-small',
-            batch_size: 10,
-            timeout_secs: 30,
-            ...(config.embedding || {})
-        },
-        server: {
-            host: 'localhost',
-            port: 8085,
-            ...(config.server || {})
-        },
-        logging: {
-            enabled: false,
-            log_directory: 'logs',
-            level: 'info',
-            ...(config.logging || {})
-        },
-        cortex: {
-            enable_intent_analysis: false,
-            ...(config.cortex || {})
-        }
-    };
+	const content = fs.readFileSync(configPath, 'utf-8');
+	const config = {};
+	let currentSection = '';
+	for (const line of content.split('\n')) {
+		const trimmed = line.trim();
+		// Skip comments and empty lines
+		if (trimmed.startsWith('#') || trimmed === '') continue;
+		// Section header
+		const sectionMatch = trimmed.match(/^\[(\w+)\]$/);
+		if (sectionMatch) {
+			currentSection = sectionMatch[1];
+			config[currentSection] = {};
+			continue;
+		}
+		// Key-value pair
+		const kvMatch =
+			trimmed.match(/^(\w+)\s*=\s*"([^"]*)"(?:\s*$|\s*#)/) ||
+			trimmed.match(/^(\w+)\s*=\s*(\d+(?:\.\d+)?)(?:\s*$|\s*#)/) ||
+			trimmed.match(/^(\w+)\s*=\s*(true|false)(?:\s*$|\s*#)/);
+		if (kvMatch && currentSection) {
+			const key = kvMatch[1];
+			let value = kvMatch[2];
+			// Convert to appropriate type
+			if (value === 'true') value = true;
+			else if (value === 'false') value = false;
+			else if (/^\d+$/.test(value)) value = parseInt(value, 10);
+			else if (/^\d+\.\d+$/.test(value)) value = parseFloat(value);
+			config[currentSection] = config[currentSection] || {};
+			config[currentSection][key] = value;
+		}
+	}
+	// Apply defaults
+	return {
+		qdrant: {
+			url: 'http://localhost:6334',
+			collection_name: 'memclaw',
+			timeout_secs: 30,
+			...(config.qdrant || {})
+		},
+		llm: {
+			api_base_url: 'https://api.openai.com/v1',
+			api_key: '',
+			model_efficient: 'gpt-5-mini',
+			temperature: 0.1,
+			max_tokens: 4096,
+			...(config.llm || {})
+		},
+		embedding: {
+			api_base_url: 'https://api.openai.com/v1',
+			api_key: '',
+			model_name: 'text-embedding-3-small',
+			batch_size: 10,
+			timeout_secs: 30,
+			...(config.embedding || {})
+		},
+		server: {
+			host: 'localhost',
+			port: 8085,
+			...(config.server || {})
+		},
+		logging: {
+			enabled: false,
+			log_directory: 'logs',
+			level: 'info',
+			...(config.logging || {})
+		},
+		cortex: {
+			enable_intent_analysis: false,
+			...(config.cortex || {})
+		}
+	};
 }
 function validateConfig(config) {
-    const errors = [];
-    if (!config.llm.api_key || config.llm.api_key === '') {
-        errors.push('llm.api_key is required');
-    }
-    if (!config.embedding.api_key || config.embedding.api_key === '') {
-        // Allow using llm.api_key for embedding if not specified
-        if (config.llm.api_key && config.llm.api_key !== '') {
-            config.embedding.api_key = config.llm.api_key;
-        }
-        else {
-            errors.push('embedding.api_key is required');
-        }
-    }
-    return {
-        valid: errors.length === 0,
-        errors
-    };
+	const errors = [];
+	if (!config.llm.api_key || config.llm.api_key === '') {
+		errors.push('llm.api_key is required');
+	}
+	if (!config.embedding.api_key || config.embedding.api_key === '') {
+		// Allow using llm.api_key for embedding if not specified
+		if (config.llm.api_key && config.llm.api_key !== '') {
+			config.embedding.api_key = config.llm.api_key;
+		} else {
+			errors.push('embedding.api_key is required');
+		}
+	}
+	return {
+		valid: errors.length === 0,
+		errors
+	};
 }
 /**
  * Update config.toml with values from OpenClaw plugin config
  * Only updates fields that are provided (non-empty) in pluginConfig
  */
 function updateConfigFromPlugin(pluginConfig) {
-    const configPath = getConfigPath();
-    // Ensure config file exists
-    ensureConfigExists();
-    // Parse existing config
-    const existingConfig = parseConfig(configPath);
-    // Track if any changes were made
-    let updated = false;
-    // Build updated config sections
-    const updates = [];
-    // LLM config updates
-    if (pluginConfig.llmApiKey && pluginConfig.llmApiKey !== '') {
-        updates.push({ section: 'llm', key: 'api_key', value: pluginConfig.llmApiKey });
-        updated = true;
-    }
-    if (pluginConfig.llmApiBaseUrl && pluginConfig.llmApiBaseUrl !== '') {
-        updates.push({ section: 'llm', key: 'api_base_url', value: pluginConfig.llmApiBaseUrl });
-        updated = true;
-    }
-    if (pluginConfig.llmModel && pluginConfig.llmModel !== '') {
-        updates.push({ section: 'llm', key: 'model_efficient', value: pluginConfig.llmModel });
-        updated = true;
-    }
-    // Embedding config updates
-    if (pluginConfig.embeddingApiKey && pluginConfig.embeddingApiKey !== '') {
-        updates.push({ section: 'embedding', key: 'api_key', value: pluginConfig.embeddingApiKey });
-        updated = true;
-    }
-    if (pluginConfig.embeddingApiBaseUrl && pluginConfig.embeddingApiBaseUrl !== '') {
-        updates.push({
-            section: 'embedding',
-            key: 'api_base_url',
-            value: pluginConfig.embeddingApiBaseUrl
-        });
-        updated = true;
-    }
-    if (pluginConfig.embeddingModel && pluginConfig.embeddingModel !== '') {
-        updates.push({ section: 'embedding', key: 'model_name', value: pluginConfig.embeddingModel });
-        updated = true;
-    }
-    if (!updated) {
-        return { updated: false, path: configPath };
-    }
-    // Read current content
-    let content = fs.readFileSync(configPath, 'utf-8');
-    // Apply each update
-    for (const { section, key, value } of updates) {
-        // Escape value for TOML string
-        const escapedValue = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-        // Pattern to match the key in the correct section
-        // This handles both existing keys and missing keys
-        const sectionPattern = new RegExp(`(\\[${section}\\][^\\[]*?)(${key}\\s*=\\s*)"[^"]*"`, 's');
-        const keyExistsInSection = sectionPattern.test(content);
-        if (keyExistsInSection) {
-            // Update existing key
-            content = content.replace(sectionPattern, `$1$2"${escapedValue}"`);
-        }
-        else {
-            // Add key to section
-            const sectionStartPattern = new RegExp(`(\\[${section}\\]\\n)`, '');
-            if (sectionStartPattern.test(content)) {
-                content = content.replace(sectionStartPattern, `$1${key} = "${escapedValue}"\n`);
-            }
-        }
-    }
-    // Write updated content
-    fs.writeFileSync(configPath, content, 'utf-8');
-    return { updated: true, path: configPath };
+	const configPath = getConfigPath();
+	// Ensure config file exists
+	ensureConfigExists();
+	// Parse existing config
+	const existingConfig = parseConfig(configPath);
+	// Track if any changes were made
+	let updated = false;
+	// Build updated config sections
+	const updates = [];
+	// LLM config updates
+	if (pluginConfig.llmApiKey && pluginConfig.llmApiKey !== '') {
+		updates.push({ section: 'llm', key: 'api_key', value: pluginConfig.llmApiKey });
+		updated = true;
+	}
+	if (pluginConfig.llmApiBaseUrl && pluginConfig.llmApiBaseUrl !== '') {
+		updates.push({ section: 'llm', key: 'api_base_url', value: pluginConfig.llmApiBaseUrl });
+		updated = true;
+	}
+	if (pluginConfig.llmModel && pluginConfig.llmModel !== '') {
+		updates.push({ section: 'llm', key: 'model_efficient', value: pluginConfig.llmModel });
+		updated = true;
+	}
+	// Embedding config updates
+	if (pluginConfig.embeddingApiKey && pluginConfig.embeddingApiKey !== '') {
+		updates.push({ section: 'embedding', key: 'api_key', value: pluginConfig.embeddingApiKey });
+		updated = true;
+	}
+	if (pluginConfig.embeddingApiBaseUrl && pluginConfig.embeddingApiBaseUrl !== '') {
+		updates.push({
+			section: 'embedding',
+			key: 'api_base_url',
+			value: pluginConfig.embeddingApiBaseUrl
+		});
+		updated = true;
+	}
+	if (pluginConfig.embeddingModel && pluginConfig.embeddingModel !== '') {
+		updates.push({ section: 'embedding', key: 'model_name', value: pluginConfig.embeddingModel });
+		updated = true;
+	}
+	if (!updated) {
+		return { updated: false, path: configPath };
+	}
+	// Read current content
+	let content = fs.readFileSync(configPath, 'utf-8');
+	// Apply each update
+	for (const { section, key, value } of updates) {
+		// Escape value for TOML string
+		const escapedValue = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+		// Pattern to match the key in the correct section
+		// This handles both existing keys and missing keys
+		const sectionPattern = new RegExp(`(\\[${section}\\][^\\[]*?)(${key}\\s*=\\s*)"[^"]*"`, 's');
+		const keyExistsInSection = sectionPattern.test(content);
+		if (keyExistsInSection) {
+			// Update existing key
+			content = content.replace(sectionPattern, `$1$2"${escapedValue}"`);
+		} else {
+			// Add key to section
+			const sectionStartPattern = new RegExp(`(\\[${section}\\]\\n)`, '');
+			if (sectionStartPattern.test(content)) {
+				content = content.replace(sectionStartPattern, `$1${key} = "${escapedValue}"\n`);
+			}
+		}
+	}
+	// Write updated content
+	fs.writeFileSync(configPath, content, 'utf-8');
+	return { updated: true, path: configPath };
 }
 /**
  * Merge plugin config with file config, preferring plugin config values
  */
 function mergeConfigWithPlugin(fileConfig, pluginConfig) {
-    return {
-        ...fileConfig,
-        llm: {
-            ...fileConfig.llm,
-            api_base_url: pluginConfig.llmApiBaseUrl || fileConfig.llm.api_base_url,
-            api_key: pluginConfig.llmApiKey || fileConfig.llm.api_key,
-            model_efficient: pluginConfig.llmModel || fileConfig.llm.model_efficient
-        },
-        embedding: {
-            ...fileConfig.embedding,
-            api_base_url: pluginConfig.embeddingApiBaseUrl || fileConfig.embedding.api_base_url,
-            api_key: pluginConfig.embeddingApiKey || fileConfig.embedding.api_key,
-            model_name: pluginConfig.embeddingModel || fileConfig.embedding.model_name
-        }
-    };
+	return {
+		...fileConfig,
+		llm: {
+			...fileConfig.llm,
+			api_base_url: pluginConfig.llmApiBaseUrl || fileConfig.llm.api_base_url,
+			api_key: pluginConfig.llmApiKey || fileConfig.llm.api_key,
+			model_efficient: pluginConfig.llmModel || fileConfig.llm.model_efficient
+		},
+		embedding: {
+			...fileConfig.embedding,
+			api_base_url: pluginConfig.embeddingApiBaseUrl || fileConfig.embedding.api_base_url,
+			api_key: pluginConfig.embeddingApiKey || fileConfig.embedding.api_key,
+			model_name: pluginConfig.embeddingModel || fileConfig.embedding.model_name
+		}
+	};
 }
-//# sourceMappingURL=config.js.map
+//# sourceMappingURL=config.js.map

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
 	"id": "memclaw",
 	"name": "MemClaw",
-	"version": "0.9.16",
+	"version": "0.9.17",
 	"description": "Layered semantic memory for OpenClaw with L0/L1/L2 tiered retrieval, easy setup, and migration from native memory",
 	"kind": "memory",
 	"skills": ["skills/memclaw", "skills/memclaw-maintance"],

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@memclaw/memclaw",
-	"version": "0.9.16",
+	"version": "0.9.17",
 	"description": "MemClaw - The Cortex Memory plugin for OpenClaw. Layered semantic memory for OpenClaw with easy setup and migration",
 	"homepage": "https://github.com/sopaco/cortex-mem",
 	"repository": {

package/skills/lagacy/references/setup.md

@@ -145,6 +145,7 @@ timeout_secs = 30
 [server]
 host = "localhost"
 port = 8085
+cors_origins = ["*"]
 
 # Logging Configuration
 [logging]
@@ -174,11 +175,6 @@ Check that Qdrant and cortex-mem-service are accessible:
 
 If `autoStartServices` is `true` in plugin config, MemClaw will start Qdrant automatically.
 
-To start manually, run the Qdrant binary from the platform package with:
-- `--storage-path` pointing to a storage directory
-- `--http-port 6333`
-- `--grpc-port 6334`
-
 **Starting cortex-mem-service:**
 
 **CRITICAL**: cortex-mem-service MUST be started with `--data-dir` flag pointing to the directory containing `config.toml`.

package/skills/memclaw/SKILL.md

@@ -34,12 +34,7 @@ The search engine queries all three tiers internally and returns unified results
 
 ## Configuration
 
-All configuration is managed through OpenClaw plugin settings. To view or modify:
-
-1. Open OpenClaw settings (`openclaw.json` or via UI)
-2. Navigate to Plugins → MemClaw → Configuration
-3. Verify or update the required fields
-4. Save changes and **restart OpenClaw Gateway** for changes to take effect
+All configuration is managed through OpenClaw plugin settings. However, when the plugin is first used, incomplete configuration items may cause it to fail. If the plugin or tools cannot be used, proactively inform the user and assist in completing the necessary configurations. For details, refer to the 'Troubleshooting' section below.
 
 ## Usage Guide
 
@@ -88,11 +83,12 @@ Open OpenClaw settings and verify MemClaw plugin configuration:
 
 1. Open `openclaw.json` or navigate to Settings → Plugins → MemClaw
 2. Ensure all required fields are correctly filled, especially the configuration sections related to LLM and Embedding.
-3. Save the configuration file
+3. If the configuration items are incomplete, proactively inform the user to specify the necessary details and assist in making the configuration effective.
+4. Save changes and **restart OpenClaw Gateway** for changes to take effect
 
 ### Step 2: Restart OpenClaw Gateway
 
-After making configuration changes, **you MUST restart OpenClaw Gateway** for the changes to take effect.
+After making configuration changes and saved, **you MUST restart OpenClaw Gateway** for the changes to take effect.
 
 ### Step 3: Verify Services
 
@@ -106,6 +102,14 @@ If issues persist after restart:
 | Service connection errors | Verify `serviceUrl` is correct; check if services are running |
 | LLM/Embedding errors | Verify API URLs and credentials in plugin configuration; restart OpenClaw Gateway after changes |
 
+Check that Qdrant and cortex-mem-service are accessible:
+> Note: MemClaw does not require users to install any Docker environment. All dependencies are prepared during the openclaw's memclaw plugin installation.
+
+| Service | Port | Health Check |
+|---------|------|--------------|
+| Qdrant | 6333 (HTTP), 6334 (gRPC) | HTTP GET to `http://localhost:6333` should return Qdrant version info |
+| cortex-mem-service | 8085 | HTTP GET to `http://localhost:8085/health` should return `{"status":"ok"}` |
+
 ## References
 
 - **`references/best-practices.md`** — Tool selection, session lifecycle, search strategies, and common pitfalls

package/skills/memclaw-maintance/SKILL.md

@@ -105,6 +105,15 @@ Restart OpenClaw to activate the plugin and start services.
 
 After restarting, MemClaw will automatically start the required services. If configured correctly, you should be able to use the memory tools normally.
 
+Check that Qdrant and cortex-mem-service are accessible:
+
+> Note: MemClaw does not require users to install any Docker environment. All dependencies are prepared during the openclaw's memclaw plugin installation.
+
+| Service | Port | Health Check |
+|---------|------|--------------|
+| Qdrant | 6333 (HTTP), 6334 (gRPC) | HTTP GET to `http://localhost:6333` should return Qdrant version info |
+| cortex-mem-service | 8085 | HTTP GET to `http://localhost:8085/health` should return `{"status":"ok"}` |
+
 ### Migrate Existing Memories (Optional)
 
 If the user has existing OpenClaw native memories, call the `cortex_migrate` tool to migrate them to MemClaw: