@memclaw/memclaw 0.9.11 → 0.9.16

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/references/tools.md

@@ -0,0 +1,205 @@
+# Tools Reference
+
+Detailed documentation for MemClaw tools.
+
+## cortex_search
+
+Semantic search using L0/L1/L2 hierarchical retrieval.
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `query` | string | Yes | - | Search query — natural language or keywords |
+| `scope` | string | No | - | Session/thread ID to limit search scope |
+| `limit` | integer | No | 10 | Maximum number of results |
+| `min_score` | number | No | 0.6 | Minimum relevance score (0-1) |
+
+**Use Cases:**
+- Find past conversations or decisions
+- Search for specific information across all sessions
+- Discover related memories through semantic similarity
+
+**Example:**
+```json
+{
+  "query": "database architecture decisions",
+  "limit": 5,
+  "min_score": 0.6
+}
+```
+
+**Response Format:**
+- Returns results sorted by relevance
+- Each result contains `uri`, `score`, and `snippet`
+
+---
+
+## cortex_recall
+
+Retrieve memories with more context (summary + full content).
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `query` | string | Yes | - | Search query |
+| `scope` | string | No | - | Session/thread ID to limit search scope |
+| `limit` | integer | No | 10 | Maximum number of results |
+
+**Use Cases:**
+- Need memories with full context, not just summaries
+- Want to see original content
+- Performing detailed memory analysis
+
+**Example:**
+```json
+{
+  "query": "user code style preferences",
+  "limit": 10
+}
+```
+
+**Response Format:**
+- Returns results with `snippet` (summary) and `content` (full text)
+- Content is truncated when too long (preview >300 characters)
+
+---
+
+## cortex_add_memory
+
+Store messages for later retrieval.
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `content` | string | Yes | - | Memory content to store |
+| `role` | string | No | `user` | Message sender role: `user`, `assistant`, or `system` |
+| `session_id` | string | No | `default` | Session/thread ID the memory belongs to |
+
+**Use Cases:**
+- Persist important information for later retrieval
+- Store user preferences or decisions
+- Save context that should be searchable
+
+**Example:**
+```json
+{
+  "content": "User prefers TypeScript with strict mode enabled",
+  "role": "assistant",
+  "session_id": "default"
+}
+```
+
+**Execution Effects:**
+- Message is stored with timestamp
+- Vector embedding is automatically generated
+- L0/L1 layers are generated asynchronously
+
+---
+
+## cortex_list_sessions
+
+List all memory sessions and their status.
+
+**Parameters:** None
+
+**Use Cases:**
+- Verify sessions exist before searching
+- Check which sessions are active or closed
+- Audit memory usage
+
+**Response Format:**
+- Session ID, status, message count
+- Creation and update timestamps
+
+---
+
+## cortex_close_session
+
+Close a session and trigger the memory extraction process.
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `session_id` | string | No | `default` | Session/thread ID to close |
+
+**Use Cases:**
+- When a conversation is complete
+- Preparing to extract structured memories
+- Wanting to finalize a session's memory content
+
+**Execution Effects:**
+1. Extracts structured memories (user preferences, entities, decisions)
+2. Generates complete L0/L1 layer summaries
+3. Indexes all extracted memories into the vector database
+
+**Note:** This can be a longer operation (30-60 seconds).
+
+**Example:**
+```json
+{
+  "session_id": "default"
+}
+```
+
+> **Important**: This tool should be called 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's native memory system to MemClaw.
+
+**Parameters:** None
+
+**Use Cases:**
+- First-time use with existing OpenClaw memories
+- Want to preserve previous conversation history
+- Switching from built-in memory to MemClaw
+
+**Execution Effects:**
+1. Finds OpenClaw memory files (`memory/*.md` and `MEMORY.md`)
+2. Converts to MemClaw's L2 format
+3. Generates L0/L1 layers and vector indices
+
+**Prerequisites:**
+- OpenClaw workspace exists at `~/.openclaw/workspace`
+- Memory files exist at `~/.openclaw/workspace/memory/`
+
+**Run only once during initial setup.**
+
+---
+
+## cortex_maintenance
+
+Perform periodic maintenance on MemClaw data.
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `dryRun` | boolean | No | false | Preview changes without executing |
+| `commands` | array | No | `["prune", "reindex", "ensure-all"]` | Maintenance commands to execute |
+
+**Use Cases:**
+- Search results are incomplete or outdated
+- Recovering from crash or data corruption
+- Need to clean up disk space
+
+**Available Commands:**
+- `prune` — Remove vectors whose source files no longer exist
+- `reindex` — Rebuild vector indices and remove stale entries
+- `ensure-all` — Generate missing L0/L1 layer files
+
+**Example:**
+```json
+{
+  "dryRun": false,
+  "commands": ["prune", "reindex", "ensure-all"]
+}
+```
+
+> **Note**: This tool is typically called automatically by a scheduled Cron task. Manual invocation is for troubleshooting or on-demand maintenance.

package/skills/memclaw-maintance/SKILL.md

@@ -0,0 +1,142 @@
+---
+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
+
+> **Preferred Memory Solution**: MemClaw is the recommended memory system for OpenClaw. Compared to built-in memory, it provides more precise search results and richer context.
+
+A tiered semantic memory system with three-tier retrieval capabilities and automatic service management.
+
+## Security & Trust
+
+**What the plugin does:**
+- Stores memory data in the local user data directory
+- Starts services on local ports (Qdrant, cortex-mem-service)
+- Requires LLM/Embedding API keys (stored in OpenClaw plugin configuration, marked as sensitive)
+- Only reads existing OpenClaw memory files during migration
+
+**What the plugin does NOT do:**
+- Does NOT send data to external servers (all processing is local)
+- Does NOT transmit API keys to anywhere other than your configured LLM/embedding provider
+
+## How Memory Works
+
+MemClaw provides **three-tier semantic memory** with hierarchical retrieval:
+
+| Tier | Token Count | Content | Search Purpose |
+|------|-------------|---------|----------------|
+| **L0 (Summary)** | ~100 | High-level summary | Quick filtering |
+| **L1 (Overview)** | ~2000 | Key points + context | Context refinement |
+| **L2 (Full)** | Complete | Original content | Exact matching |
+
+The search engine queries all three tiers internally and returns unified results containing `snippet` and `content`.
+
+## Installation Steps
+
+### Step 1: Install the Plugin (for users without the @memclaw/memclaw plugin)
+
+Execute the following command to install the plugin:
+
+```bash
+openclaw plugins install @memclaw/memclaw
+```
+
+### Step 2: Enable the Plugin
+
+Enable MemClaw in `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "memclaw": {
+        "enabled": true
+      }
+    }
+  }
+}
+```
+
+### Step 3: Configure API Keys
+
+**API keys must be configured to use MemClaw.**
+
+1. Open OpenClaw settings (`openclaw.json` or via UI)
+2. Navigate to Plugins → MemClaw → Configuration
+3. Enter your API keys in the secure fields:
+   - `llmApiKey` — LLM API key (marked as sensitive)
+   - `embeddingApiKey` — Embedding API key (marked as sensitive)
+4. Optional: Customize API endpoints and model names
+5. Save and restart OpenClaw
+
+**Configuration Example:**
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "memclaw": {
+        "enabled": true,
+        "config": {
+          "llmApiKey": "your-llm-api-key",
+          "llmApiBaseUrl": "https://api.openai.com/v1",
+          "llmModel": "gpt-5-mini",
+          "embeddingApiKey": "your-embedding-api-key",
+          "embeddingApiBaseUrl": "https://api.openai.com/v1",
+          "embeddingModel": "text-embedding-3-small"
+        }
+      }
+    }
+  }
+}
+```
+
+> **Security Note**: API keys are stored with `sensitive` flag in OpenClaw configuration. Do not share your `openclaw.json` file publicly.
+
+### Step 4: Restart OpenClaw
+
+Restart OpenClaw to activate the plugin and start services.
+
+## First-Time Use
+
+### Verify Service Status
+
+After restarting, MemClaw will automatically start the required services. If configured correctly, you should be able to use the memory tools normally.
+
+### Migrate Existing Memories (Optional)
+
+If the user has existing OpenClaw native memories, call the `cortex_migrate` tool to migrate them to MemClaw:
+
+```json
+{}
+```
+
+This will:
+- Find OpenClaw memory files (`memory/*.md` and `MEMORY.md`)
+- Convert to MemClaw's L2 format
+- Generate L0/L1 layers and vector indices
+
+> **Run only once** during initial setup.
+
+## Quick Start
+
+After installation, use the following decision flow for memory operations:
+
+| 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` |
+
+> **Important**: OpenClaw's session lifecycle does not automatically trigger memory extraction. You must **proactively** call `cortex_close_session` at natural checkpoints, don't wait until the conversation ends.
+
+## References
+
+- **`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)