@memclaw/memclaw 0.9.13 → 0.9.17

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,7 @@ The search engine queries all three tiers internally and returns unified results
 
 ## Configuration
 
-### Modifying API Configuration
-
-To modify API configuration:
-
-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 |
+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
 
@@ -98,15 +73,46 @@ 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. 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 and saved, **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 |
+
+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
 - **`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`:
 
@@ -110,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:
@@ -143,3 +147,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)