@memclaw/memclaw 0.9.13 → 0.9.16

package/dist/index.js

@@ -38,7 +38,7 @@ function memclawPlugin(api) {
 exports.plugin = {
     id: 'memclaw',
     name: 'MemClaw',
-    version: '0.9.13',
+    version: '0.9.16',
     configSchema: {
         type: 'object',
         properties: {

package/openclaw.plugin.json

@@ -1,10 +1,10 @@
 {
 	"id": "memclaw",
 	"name": "MemClaw",
-	"version": "0.9.13",
+	"version": "0.9.16",
 	"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": ["skills/memclaw", "skills/memclaw-maintance"],
 	"platforms": ["darwin-arm64", "win32-x64"],
 	"osRestriction": ["darwin-arm64", "win32-x64"],
 	"configSchema": {
@@ -85,14 +85,7 @@
 				"default": "text-embedding-3-small"
 			}
 		},
-		"required": [
-			"llmApiKey",
-			"embeddingApiKey",
-			"llmApiBaseUrl",
-			"llmModel",
-			"embeddingApiBaseUrl",
-			"embeddingModel"
-		]
+		"required": []
 	},
 	"uiHints": {
 		"serviceUrl": {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@memclaw/memclaw",
-	"version": "0.9.13",
+	"version": "0.9.16",
 	"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": {
@@ -36,7 +36,8 @@
 			"dist/index.js"
 		],
 		"skills": [
-			"skills/memclaw"
+			"skills/memclaw",
+			"skills/memclaw-maintance"
 		]
 	},
 	"devDependencies": {

package/skills/memclaw/SKILL.md

@@ -13,8 +13,7 @@ A tiered semantic memory system with three-tier retrieval capabilities and autom
 
 **What the plugin does:**
 - Stores memory data in the local user data directory
-- Starts services on local ports (Qdrant, Cortex Memory)
-- Requires LLM/Embedding API keys (stored in OpenClaw plugin configuration, marked as sensitive)
+- Based on advanced Cortex Memory technology, providing outstanding memory management capabilities with high performance and accuracy.
 - Only reads existing OpenClaw memory files during migration
 
 **What the plugin does NOT do:**
@@ -35,31 +34,12 @@ The search engine queries all three tiers internally and returns unified results
 
 ## Configuration
 
-### Modifying API Configuration
-
-To modify API 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. Modify the desired fields
-4. Save and restart OpenClaw
-
-### Configuration Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `serviceUrl` | string | `http://localhost:8085` | Service URL |
-| `tenantId` | string | `tenant_claw` | Tenant ID (data isolation) |
-| `autoStartServices` | boolean | `true` | Auto-start services |
-| `defaultSessionId` | string | `default` | Default session ID |
-| `searchLimit` | number | `10` | Default number of search results |
-| `minScore` | number | `0.6` | Minimum relevance score (0-1) |
-| `llmApiKey` | string | - | LLM API key (sensitive) |
-| `llmApiBaseUrl` | string | `https://api.openai.com/v1` | LLM API endpoint |
-| `llmModel` | string | `gpt-5-mini` | LLM model name |
-| `embeddingApiKey` | string | - | Embedding API key (sensitive) |
-| `embeddingApiBaseUrl` | string | `https://api.openai.com/v1` | Embedding API endpoint |
-| `embeddingModel` | string | `text-embedding-3-small` | Embedding model name |
+3. Verify or update the required fields
+4. Save changes and **restart OpenClaw Gateway** for changes to take effect
 
 ## Usage Guide
 
@@ -98,15 +78,37 @@ To modify API configuration:
 { "content": "User prefers TypeScript with strict mode enabled", "role": "assistant" }
 ```
 
-## Common Issues
+## Troubleshooting
+
+If MemClaw is not working properly, follow these steps:
+
+### Step 1: Check Plugin Configuration
+
+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
+
+### Step 2: Restart OpenClaw Gateway
+
+After making configuration changes, **you MUST restart OpenClaw Gateway** for the changes to take effect.
+
+### Step 3: Verify Services
+
+If issues persist after restart:
+- Run `cortex_list_sessions` to check if the service is responding
+- Check if Qdrant and cortex-mem-service are running (auto-start should handle this)
 
 | Issue | Solution |
 |-------|----------|
-| Service won't start | Check if ports 6333, 6334, 8085 are in use; confirm API keys are configured |
-| No search results | Run `cortex_list_sessions` to verify; lower `min_score` threshold |
-| LLM/Embedding errors | Verify `llmApiKey` and `embeddingApiKey` are configured correctly |
-| Migration failed | Confirm OpenClaw workspace is at `~/.openclaw/workspace` |
+| No search results | Run `cortex_list_sessions` to verify; lower `min_score` threshold; ensure memories have been stored |
+| 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 |
 
 ## References
 
+- **`references/best-practices.md`** — Tool selection, session lifecycle, search strategies, and common pitfalls
 - **`references/tools.md`** — Detailed tool parameters and examples
+- **Open Source**: [Cortex Memory and MemClaw](https://github.com/sopaco/cortex-mem)
+- **README**: [MemClaw README](https://raw.githubusercontent.com/sopaco/cortex-mem/refs/heads/main/examples/%40memclaw/plugin/README.md)

package/skills/memclaw/references/best-practices.md

@@ -0,0 +1,319 @@
+# MemClaw Best Practices
+
+This guide provides proven strategies and decision frameworks for using MemClaw effectively in OpenClaw.
+
+## Tool Selection Decision Tree
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    What do you need to do?                      │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+        ┌─────────────────────┼─────────────────────┐
+        ▼                     ▼                     ▼
+   Find Info            Save Info             Manage Sessions
+        │                     │                     │
+        ▼                     ▼                     ▼
+┌───────────────┐    ┌───────────────┐    ┌───────────────┐
+│ Need context? │    │   What kind?  │    │    What?      │
+└───────────────┘    └───────────────┘    └───────────────┘
+        │                     │                     │
+   ┌────┴────┐           ┌────┴────┐          ┌────┴────┐
+   ▼         ▼           ▼         ▼          ▼         ▼
+ Quick    Full        Facts    Conversation  List    Close &
+ Search   Context               History     Sessions  Extract
+   │         │           │         │           │         │
+   ▼         ▼           ▼         ▼           ▼         ▼
+cortex_   cortex_   cortex_   cortex_     cortex_   cortex_
+search    recall    add_      add_        list_     close_
+                    memory    memory      sessions  session
+```
+
+### Quick Reference
+
+| Scenario | Tool | Why |
+|----------|------|-----|
+| Quick lookup, need summary only | `cortex_search` | Fast, returns snippets |
+| Need full context/details | `cortex_recall` | Returns content + snippet |
+| User stated preference/decision | `cortex_add_memory` | Explicit persistence |
+| Important conversation content | Let it accumulate | Auto-stored in session |
+| Task/topic completed | `cortex_close_session` | Trigger extraction |
+| Check if memories exist | `cortex_list_sessions` | Verify before search |
+
+## Session Lifecycle Management
+
+### The Golden Rule
+
+> **OpenClaw does NOT automatically trigger memory extraction.** You must proactively call `cortex_close_session` at natural checkpoints.
+
+### When to Close a Session
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│                    Timing Decision Flow                        │
+└────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+                    ┌─────────────────┐
+                    │ Task completed? │
+                    └─────────────────┘
+                         │      │
+                        Yes     No
+                         │      │
+                         ▼      ▼
+                  ┌──────────┐  ┌─────────────────┐
+                  │ CLOSE IT │  │ Topic shifted?  │
+                  └──────────┘  └─────────────────┘
+                                     │      │
+                                    Yes     No
+                                     │      │
+                                     ▼      ▼
+                              ┌──────────┐  ┌─────────────────┐
+                              │ CLOSE IT │  │ 10+ exchanges?  │
+                              └──────────┘  └─────────────────┘
+                                                 │      │
+                                                Yes     No
+                                                 │      │
+                                                 ▼      ▼
+                                          ┌──────────┐  ┌────────┐
+                                          │ CLOSE IT │  │ WAIT   │
+                                          └──────────┘  └────────┘
+```
+
+### Rhythm Guidelines
+
+| Conversation Type | Close Frequency | Reason |
+|-------------------|-----------------|--------|
+| Quick Q&A | End of conversation | Minimal content to extract |
+| Task-oriented | After each task completion | Captures task-specific memories |
+| Long discussion | Every 10-20 exchanges | Prevents memory loss |
+| Exploratory chat | When topic shifts | Organizes memories by topic |
+
+### Anti-Patterns to Avoid
+
+| ❌ Don't Do This | ✅ Do This Instead |
+|-------------------|-------------------|
+| Call `close_session` after every message | Call at natural checkpoints |
+| Wait until conversation ends (user may forget) | Proactively close during conversation |
+| Close without accumulating content | Let 5-10 exchanges happen first |
+| Never close sessions | Establish a rhythm |
+
+## Memory Storage Strategy
+
+### What to Explicitly Store
+
+Use `cortex_add_memory` for:
+
+1. **Explicit User Preferences**
+   ```
+   "User prefers dark theme in all editors"
+   "User wants commit messages in conventional format"
+   ```
+
+2. **Important Decisions**
+   ```
+   "Decided to use PostgreSQL instead of MySQL for this project"
+   "User chose React over Vue for the frontend"
+   ```
+
+3. **Key Information That May Be Lost**
+   ```
+   "User's timezone is UTC+8"
+   "Project deadline: March 30, 2026"
+   ```
+
+### What to Let Accumulate
+
+Don't use `cortex_add_memory` for:
+
+- Regular conversation content (auto-stored in session)
+- Contextual information (captured on close_session)
+- Temporary preferences (not worth persisting)
+
+### Role Parameter Usage
+
+| Role | When to Use |
+|------|-------------|
+| `user` | User's statements, preferences, questions (default) |
+| `assistant` | Your responses, explanations, code you wrote |
+| `system` | Important context, rules, constraints |
+
+## Search Strategies
+
+### Query Formulation
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│                    Query Formulation Tips                      │
+└────────────────────────────────────────────────────────────────┘
+
+BAD:  "it"                          — Too vague
+GOOD: "database choice"             — Specific topic
+
+BAD:  "the user said something"     — Unfocused
+GOOD: "user preference for testing" — Clear intent
+
+BAD:  "code"                        — Too broad
+GOOD: "authentication implementation" — Specific domain
+```
+
+### Score Threshold Guidelines
+
+| Score | Use Case |
+|-------|----------|
+| 0.8+ | Need high-confidence matches only |
+| 0.6 (default) | Balanced precision/recall |
+| 0.4-0.5 | Exploratory search, finding related items |
+| <0.4 | Usually too noisy, not recommended |
+
+### Scope Parameter Usage
+
+```
+# Search across all sessions (default)
+{ "query": "database decisions" }
+
+# Search within specific session
+{ "query": "preferences", "scope": "project-alpha" }
+```
+
+Use `scope` when:
+- You know the relevant session ID
+- Working within a specific project context
+- Want to limit noise from other sessions
+
+## Common Pitfalls
+
+### 1. Memory Not Found After Close
+
+**Symptom:** You closed a session but search returns nothing.
+
+**Cause:** Memory extraction is asynchronous and may take 30-60 seconds.
+
+**Solution:** Wait briefly after close_session before searching, or:
+```
+1. Close session
+2. Continue with other work
+3. Memory will be indexed automatically
+```
+
+### 2. Duplicate Memories
+
+**Symptom:** Same information appears multiple times.
+
+**Cause:** Both explicit `add_memory` and `close_session` extraction captured the same content.
+
+**Solution:** Use `add_memory` only for information that:
+- Won't naturally be captured in conversation
+- Needs explicit emphasis
+- Is a correction or override of previous information
+
+### 3. Irrelevant Search Results
+
+**Symptom:** Search returns unrelated content.
+
+**Cause:** Query too vague or score threshold too low.
+
+**Solution:**
+- Make queries more specific
+- Increase `min_score` threshold
+- Use `scope` to limit search range
+
+### 4. Lost Session Content
+
+**Symptom:** Important conversation not in memory.
+
+**Cause:** Session was never closed.
+
+**Solution:** Establish a habit of closing sessions at checkpoints. If you realize too late, the raw messages may still exist in the session - close it now.
+
+### 5. Configuration Issues
+
+**Symptom:** Tools return errors about service/API.
+
+**Cause:** LLM/Embedding credentials not configured.
+
+**Solution:** See SKILL.md → Troubleshooting section.
+
+## Workflow Examples
+
+### Example 1: New Project Discussion
+
+```
+1. User starts discussing a new project
+   → Just listen and respond naturally
+
+2. User makes architecture decisions
+   → Optionally: cortex_add_memory for explicit decisions
+
+3. Discussion shifts to another topic
+   → cortex_close_session (captures project discussion memories)
+
+4. Continue with new topic
+   → Fresh start, memories from step 3 are now searchable
+```
+
+### Example 2: Finding Previous Context
+
+```
+1. User asks: "What did we decide about auth?"
+
+2. cortex_search({ query: "authentication decision" })
+
+3. If results show snippets but need details:
+   cortex_recall({ query: "authentication implementation details" })
+
+4. Summarize findings to user
+```
+
+### Example 3: User States Preference
+
+```
+1. User: "I always want TypeScript strict mode"
+
+2. cortex_add_memory({
+     content: "User requires TypeScript strict mode in all projects",
+     role: "user"
+   })
+
+3. Acknowledge and remember for future
+```
+
+## Memory Architecture Reference
+
+### L0/L1/L2 Tier System
+
+| Tier | Content | Size | Purpose | Search Role |
+|------|---------|------|---------|-------------|
+| L0 | Abstract summary | ~100 tokens | Quick filtering | First pass |
+| L1 | Key points + context | ~2000 tokens | Context refinement | Second pass |
+| L2 | Full original content | Complete | Exact matching | Final retrieval |
+
+### How Search Works Internally
+
+```
+Query → L0 Filter → L1 Refine → L2 Retrieve → Ranked Results
+          │             │             │
+          ▼             ▼             ▼
+      Quick scan    Contextual    Full content
+      by summary    refinement    for precision
+```
+
+### Automatic Processes
+
+| Process | Trigger | Duration |
+|---------|---------|----------|
+| Vector embedding | On `add_memory` | Seconds |
+| L0/L1 generation | On `add_memory` (async) | Seconds |
+| Full extraction | On `close_session` | 30-60s |
+| Maintenance | Every 3 hours (auto) | Minutes |
+
+## Summary Checklist
+
+Before ending a conversation or topic transition, ask yourself:
+
+- [ ] Have we accumulated meaningful content?
+- [ ] Did the user share important preferences or decisions?
+- [ ] Is this a natural checkpoint?
+- [ ] Should I close the session now?
+
+If yes to any, call `cortex_close_session`.

package/skills/{memclaw-setup → memclaw-maintance}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: memclaw-setup
-description: MemClaw Setup Guide — Installation and configuration guidance for users without the @memclaw/memclaw plugin installed. After completing installation, use the `memclaw` skill for daily usage help.
+name: memclaw-maintance
+description: MemClaw Maintance Guide — Installation and configuration guidance for users especially without the @memclaw/memclaw plugin installed. For normal use cases, use the `memclaw` skill for daily usage help.
 ---
 
 # MemClaw Setup Guide
@@ -35,7 +35,7 @@ The search engine queries all three tiers internally and returns unified results
 
 ## Installation Steps
 
-### Step 1: Install the Plugin
+### Step 1: Install the Plugin (for users without the @memclaw/memclaw plugin)
 
 Execute the following command to install the plugin:
 
@@ -43,12 +43,7 @@ Execute the following command to install the plugin:
 openclaw plugins install @memclaw/memclaw
 ```
 
-The installation process will:
-- Download the plugin from the package registry (npm, clawhub)
-- Automatically install platform-specific binary dependencies
-- Register the plugin in OpenClaw
-
-### Step 1: Enable the Plugin
+### Step 2: Enable the Plugin
 
 Enable MemClaw in `openclaw.json`:
 
@@ -143,3 +138,5 @@ After installation, use the following decision flow for memory operations:
 
 - **`references/tools.md`** — Detailed tool parameters and examples
 - **`references/troubleshooting.md`** — Common troubleshooting issues
+- **Open Source**: [Cortex Memory and MemClaw](https://github.com/sopaco/cortex-mem)
+- **README**: [MemClaw README](https://raw.githubusercontent.com/sopaco/cortex-mem/refs/heads/main/examples/%40memclaw/plugin/README.md)