@memclaw/memclaw 0.9.11 → 0.9.16

package/skills/memclaw-maintance/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/references/troubleshooting.md

@@ -0,0 +1,134 @@
+# Troubleshooting Guide
+
+Common MemClaw issues and their solutions.
+
+## Installation Issues
+
+### Platform Not Supported
+
+**Symptoms**: "Platform not supported" error is displayed
+
+**Solutions**:
+- Confirm you are using macOS Apple Silicon (M1/M2/M3) or Windows x64
+- Other platforms are not currently supported
+
+### Plugin Installation Failed
+
+**Symptoms**: `openclaw plugins install @memclaw/memclaw` fails
+
+**Solutions**:
+1. Check network connection
+2. Confirm npm registry is accessible
+3. Try using a proxy or mirror source
+
+## Configuration Issues
+
+### Invalid API Key
+
+**Symptoms**: Search or memory operations return API errors
+
+**Solutions**:
+1. Verify `llmApiKey` and `embeddingApiKey` are correctly configured in OpenClaw plugin settings
+2. Confirm API keys are valid and have sufficient quota
+3. Confirm `llmApiBaseUrl` and `embeddingApiBaseUrl` are correct for your provider
+4. Verify network connectivity to API endpoints
+
+### Configuration Not Taking Effect
+
+**Symptoms**: Service behavior doesn't change after modifying configuration
+
+**Solutions**:
+1. Ensure configuration file was saved
+2. Restart OpenClaw to apply changes
+3. Check configuration file syntax for errors (JSON format)
+
+## Service Issues
+
+### Service Won't Start
+
+**Symptoms**: Service fails to start when plugin loads
+
+**Solutions**:
+1. Check if ports 6333, 6334, 8085 are occupied by other applications
+2. Confirm API keys are configured in OpenClaw plugin settings
+3. Check OpenClaw logs for detailed error messages
+
+### Service Unreachable
+
+**Symptoms**: Tool calls return connection errors
+
+**Solutions**:
+1. Confirm OpenClaw has been restarted and plugin is loaded
+2. Check if `autoStartServices` configuration is set to `true` (default)
+3. Verify firewall allows local connections on these ports
+
+## Usage Issues
+
+### No Search Results
+
+**Symptoms**: `cortex_search` returns empty results
+
+**Solutions**:
+1. Run `cortex_list_sessions` to verify sessions exist
+2. Lower `min_score` threshold (e.g., from 0.6 to 0.4)
+3. Try different query terms or synonyms
+4. Confirm that `cortex_add_memory` or `cortex_close_session` has been called previously to store memories
+
+### Memory Extraction Failed
+
+**Symptoms**: `cortex_close_session` fails or produces incomplete results
+
+**Solutions**:
+1. Verify LLM API configuration is correct
+2. Check if API quota is sufficient
+3. Check OpenClaw logs for detailed error messages
+
+### Migration Failed
+
+**Symptoms**: `cortex_migrate` fails to execute
+
+**Solutions**:
+1. Confirm OpenClaw workspace is located at `~/.openclaw/workspace`
+2. Confirm memory files exist at `~/.openclaw/workspace/memory/`
+3. Verify file permissions are correct
+
+## Data Issues
+
+### Data Location
+
+MemClaw data storage locations:
+
+| Platform | Path |
+|----------|------|
+| macOS | `~/Library/Application Support/memclaw` |
+| Windows | `%LOCALAPPDATA%\memclaw` |
+| Linux | `~/.local/share/memclaw` |
+
+### Data Safety
+
+- **Backup**: Existing OpenClaw memory files are preserved before migration
+- **Local Storage**: All memory data is stored locally
+- **No Cloud Sync**: Data remains on the local machine
+
+## Error Messages Reference
+
+| Error Message | Possible Cause | Solution |
+|---------------|----------------|----------|
+| `Service not running` | Service not started | Restart OpenClaw or enable `autoStartServices` |
+| `API error: 401` | Invalid API key | Check API key configuration |
+| `API error: 429` | Rate limit exceeded | Wait and retry, or upgrade API plan |
+| `Connection refused` | Service unreachable | Check port usage and service status |
+| `No sessions found` | No memory data | Use `cortex_add_memory` to add memories |
+
+## Getting Help
+
+If the above solutions don't resolve your issue:
+
+1. Check OpenClaw logs for detailed error messages
+2. Submit an issue report at [GitHub Issues](https://github.com/sopaco/cortex-mem/issues)
+3. Provide the following information:
+   - Operating system and version
+   - OpenClaw version
+   - MemClaw plugin version
+   - Relevant log snippets
+   - Steps to reproduce