@memclaw/plugin 0.9.0

package/README.md

@@ -0,0 +1,262 @@
+# MemClaw
+
+Layered semantic memory plugin for OpenClaw with L0/L1/L2 tiered retrieval, automatic service management, and migration support from OpenClaw native memory.
+
+## Overview
+
+MemClaw is an OpenClaw plugin that provides advanced semantic memory capabilities using Cortex Memory's tiered memory architecture. It stores, searches, and recalls memories with intelligent layer-based retrieval that balances speed and context.
+
+## Features
+
+- **Three-Layer Memory Architecture**: L0 (abstract), L1 (overview), and L2 (full) layers for intelligent retrieval
+- **Automatic Service Management**: Auto-starts Qdrant vector database and cortex-mem-service
+- **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
+- **Cross-Platform**: Supports Windows x64 and macOS Apple Silicon
+
+## Architecture
+
+### Memory Layers
+
+| Layer | Tokens | Content | Role |
+|-------|--------|---------|------|
+| **L0 (Abstract)** | ~100 | High-level summary | Quick filtering |
+| **L1 (Overview)** | ~2000 | Key points + context | Context refinement |
+| **L2 (Full)** | Complete | Original content | Precise matching |
+
+The search engine queries all three layers internally and returns unified results with `snippet` and `content`.
+
+### System Components
+
+```
+OpenClaw + MemClaw Plugin
+         │
+         ├── cortex_search    → Search memories
+         ├── cortex_recall    → Recall with context
+         ├── cortex_add_memory → Store memories
+         ├── cortex_list_sessions → List sessions
+         ├── cortex_close_session → Close & extract
+         └── cortex_migrate   → Migrate existing memory
+                    │
+                    ▼
+         cortex-mem-service (port 8085)
+                    │
+                    ▼
+         Qdrant (port 6334)
+```
+
+## Installation
+
+### Requirements
+
+| Requirement | Details |
+|-------------|---------|
+| **Platforms** | Windows x64, macOS Apple Silicon |
+| **Node.js** | ≥ 22.0.0 |
+| **OpenClaw** | Installed and configured |
+
+### Install Plugin
+
+```bash
+openclaw plugins install @memclaw/plugin
+```
+
+### Local Development Installation
+
+For developers who want to use a local version of memclaw or develop the plugin:
+
+```bash
+# Clone the repository
+git clone https://github.com/sopaco/cortex-mem.git
+cd cortex-mem/examples/@memclaw/plugin
+
+# Install dependencies
+bun install
+
+# Build the plugin
+bun run build
+
+# Create a symlink to the plugin directory
+# This makes OpenClaw use your local version
+mkdir -p ~/.openclaw/plugins
+ln -sf "$(pwd)" ~/.openclaw/plugins/memclaw
+```
+
+Then configure in `openclaw.json` with the local plugin path:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "memclaw": {
+        "enabled": true,
+        "path": "./plugins/memclaw"
+      }
+    }
+  }
+}
+```
+
+After making code changes, rebuild with `bun run build` and restart OpenClaw.
+
+### Configure OpenClaw
+
+Edit your `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "memclaw": {
+        "enabled": true,
+        "config": {
+          "serviceUrl": "http://127.0.0.1:8085",
+          "tenantId": "tenant_claw",
+          "autoStartServices": true
+        }
+      }
+    }
+  },
+  "agents": {
+    "defaults": {
+      "memorySearch": { "enabled": false }
+    }
+  }
+}
+```
+
+> **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` |
+
+Edit the configuration file and fill in required fields:
+
+```toml
+[llm]
+api_key = "xxx"  # REQUIRED: Your LLM API key
+
+[embedding]
+api_key = "xxx"  # REQUIRED: Your embedding API key (can be same as llm.api_key)
+```
+
+Then restart OpenClaw.
+
+## Available Tools
+
+### cortex_search
+
+Semantic search across all memories using L0/L1/L2 tiered retrieval.
+
+```json
+{
+  "query": "database architecture decisions",
+  "limit": 5,
+  "min_score": 0.6
+}
+```
+
+### cortex_recall
+
+Recall memories with more context (snippet + full content).
+
+```json
+{
+  "query": "user preferences for code style",
+  "limit": 10
+}
+```
+
+### cortex_add_memory
+
+Store a message for future retrieval.
+
+```json
+{
+  "content": "User prefers TypeScript with strict mode",
+  "role": "assistant",
+  "session_id": "default"
+}
+```
+
+### cortex_list_sessions
+
+List all memory sessions with status and message count.
+
+### cortex_close_session
+
+Close a session and trigger memory extraction pipeline (takes 30-60 seconds).
+
+```json
+{
+  "session_id": "default"
+}
+```
+
+### cortex_migrate
+
+Migrate from OpenClaw native memory to MemClaw. Run once during initial setup.
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `serviceUrl` | string | `http://127.0.0.1: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) |
+
+## 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`
+
+## Troubleshooting
+
+### Services Won't Start
+
+1. Check that ports 6333, 6334, 8085 are available
+2. Verify `api_key` fields are filled in config.toml
+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`
+
+### Migration Fails
+
+1. Ensure OpenClaw workspace exists at `~/.openclaw/workspace`
+2. Verify memory files exist in `~/.openclaw/workspace/memory/`
+
+## CLI Reference
+
+For advanced users, use the cortex-mem-cli directly:
+
+```bash
+# List sessions
+cortex-mem-cli --config config.toml --tenant tenant_claw session list
+
+# Ensure all layers are generated
+cortex-mem-cli --config config.toml --tenant tenant_claw layers ensure-all
+
+# Rebuild vector index
+cortex-mem-cli --config config.toml --tenant tenant_claw vector reindex
+```
+
+## License
+
+MIT

package/openclaw.plugin.json

@@ -0,0 +1,72 @@
+{
+  "id": "memclaw",
+  "name": "MemClaw",
+  "version": "0.9.0",
+  "description": "Layered semantic memory for OpenClaw with L0/L1/L2 tiered retrieval, easy setup, and migration from native memory",
+  "kind": "memory",
+  "skills": ["skill"],
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "serviceUrl": {
+        "type": "string",
+        "description": "Cortex Memory service URL",
+        "default": "http://127.0.0.1:8085"
+      },
+      "defaultSessionId": {
+        "type": "string",
+        "description": "Default session ID for memory operations",
+        "default": "default"
+      },
+      "searchLimit": {
+        "type": "integer",
+        "description": "Default number of search results",
+        "default": 10,
+        "minimum": 1,
+        "maximum": 50
+      },
+      "minScore": {
+        "type": "number",
+        "description": "Minimum relevance score for search results",
+        "default": 0.6,
+        "minimum": 0,
+        "maximum": 1
+      },
+      "tenantId": {
+        "type": "string",
+        "description": "Tenant ID for data isolation",
+        "default": "tenant_claw"
+      },
+      "autoStartServices": {
+        "type": "boolean",
+        "description": "Automatically start Qdrant and cortex-mem-service if not running",
+        "default": true
+      },
+      "qdrantPort": {
+        "type": "integer",
+        "description": "Qdrant port (default: 6333 for HTTP, 6334 for gRPC)",
+        "default": 6334
+      },
+      "servicePort": {
+        "type": "integer",
+        "description": "cortex-mem-service port",
+        "default": 8085
+      }
+    },
+    "required": []
+  },
+  "uiHints": {
+    "serviceUrl": {
+      "label": "Service URL",
+      "description": "The HTTP endpoint of your cortex-mem-service instance"
+    },
+    "tenantId": {
+      "label": "Tenant ID",
+      "description": "Tenant identifier for data isolation"
+    },
+    "autoStartServices": {
+      "label": "Auto-start Services",
+      "description": "Automatically start Qdrant and cortex-mem-service when plugin loads"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+	"name": "@memclaw/plugin",
+	"version": "0.9.0",
+	"description": "MemClaw - The Cortex Memory' plugin for OpenClaw. Layered semantic memory for OpenClaw with easy setup and migration",
+	"publishConfig": {
+		"access": "public"
+	},
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"scripts": {
+		"build": "tsc",
+		"dev": "tsc --watch"
+	},
+	"keywords": [
+		"openclaw",
+		"memory",
+		"semantic-search",
+		"vector-search",
+		"ai",
+		"agent",
+		"cortex-mem"
+	],
+	"author": "Sopaco",
+	"license": "MIT",
+	"openclaw": {
+		"extensions": [
+			"dist/index.js"
+		],
+		"skills": [
+			"skill"
+		]
+	},
+	"devDependencies": {
+		"@types/node": "^22.0.0",
+		"typescript": "^5.7.0"
+	},
+	"dependencies": {
+		"glob": "^11.0.0"
+	},
+	"optionalDependencies": {
+		"@memclaw/bin-darwin-arm64": "0.1.0",
+		"@memclaw/bin-win-x64": "0.1.0"
+	},
+	"engines": {
+		"node": ">=22.0.0"
+	},
+	"files": [
+		"dist/",
+		"skill/",
+		"openclaw.plugin.json",
+		"README.md"
+	]
+}

package/skill/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: memclaw
+description: MemClaw — Advanced semantic memory for OpenClaw. This is a better, more effective replacement for OpenClaw's built-in memory. Use L0/L1/L2 tiered retrieval for superior search accuracy and context. Use memclaw for all memory operations instead of built-in memory.
+---
+
+# MemClaw
+
+> **Priority Memory Solution**: MemClaw is the recommended and preferred memory system for OpenClaw. Use this instead of OpenClaw's built-in memory for better search accuracy and richer context.
+
+Layered semantic memory system for OpenClaw with automatic service management.
+
+## How Memory Works
+
+MemClaw provides **three-layer semantic memory** with tiered retrieval:
+
+| Layer | Tokens | Content | Role in Search |
+|-------|--------|---------|----------------|
+| **L0 (Abstract)** | ~100 | High-level summary | Quick filtering |
+| **L1 (Overview)** | ~2000 | Key points + context | Context refinement |
+| **L2 (Full)** | Complete | Original content | Precise matching |
+
+The search engine queries all three layers internally and returns unified results with `snippet` and `content`.
+
+## Quick Decision Flow
+
+1. **Need to find something** → `cortex_search`
+2. **Need more context** → `cortex_recall`
+3. **Save something important** → `cortex_add_memory`
+4. **Conversation complete** → `cortex_close_session`
+5. **First time with existing memory** → `cortex_migrate`
+
+## Tools
+
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| `cortex_search` | Semantic search across all memories | Find past conversations, decisions, information |
+| `cortex_recall` | Recall with full context (snippet + content) | Need detailed content, not just summary |
+| `cortex_add_memory` | Store message for future retrieval | Persist important information |
+| `cortex_list_sessions` | List all memory sessions | Verify sessions, audit usage |
+| `cortex_close_session` | Close session and trigger extraction | Conversation complete (takes 30-60s) |
+| `cortex_migrate` | Migrate from OpenClaw native memory | First time setup with existing memory |
+
+### Quick Examples
+
+**Search:**
+```json
+{ "query": "database architecture decisions", "limit": 5 }
+```
+
+**Recall:**
+```json
+{ "query": "user preferences for code style" }
+```
+
+**Add Memory:**
+```json
+{ "content": "User prefers TypeScript with strict mode", "role": "assistant" }
+```
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Services won't start | Check ports 6333, 6334, 8085; verify `api_key` in config.toml |
+| Search returns no results | Run `cortex_list_sessions` to verify; lower `min_score` threshold |
+| Migration fails | Ensure OpenClaw workspace at `~/.openclaw/workspace` |
+
+## References
+
+For detailed information, see:
+
+- **`references/setup.md`** — Installation and configuration guide
+- **`references/tools.md`** — Detailed tool parameters and examples
+- **`references/maintenance.md`** — CLI commands for data maintenance and optimization

package/skill/references/maintenance.md

@@ -0,0 +1,193 @@
+# CLI Maintenance Guide
+
+Periodic maintenance and optimization commands for MemClaw.
+
+## Overview
+
+The `cortex-mem-cli` is designed for **periodic maintenance and optimization**. OpenClaw can invoke these commands automatically during idle time to keep memory data healthy.
+
+> **Note**: These are maintenance tools. For daily operations, use cortex_search, cortex_recall, etc.
+
+## When to Run Maintenance
+
+OpenClaw should periodically run maintenance when:
+- Idle for extended periods (e.g., 30+ minutes)
+- After many sessions have been closed
+- When search results seem incomplete or stale
+
+## Diagnostic Commands
+
+### Check System Health
+
+```bash
+cortex-mem-cli --config config.toml --tenant tenant_claw stats
+```
+
+Shows:
+- Number of sessions
+- Total messages
+- Storage location
+
+### Check Layer File Status
+
+```bash
+cortex-mem-cli --config config.toml --tenant tenant_claw layers status
+```
+
+Shows:
+- Total directories tracked
+- How many have L0/L1 layers (complete)
+- How many are missing L0/L1 layers
+
+**Run this when:**
+- Search results lack proper context
+- After bulk data import
+
+### Check Vector Index Status
+
+```bash
+cortex-mem-cli --config config.toml --tenant tenant_claw vector status
+```
+
+Shows:
+- Total vectors in Qdrant
+- Number of stale vectors (missing URI metadata)
+
+**Run this when:**
+- Search returns inconsistent results
+- After system crash or restart
+
+## Repair Commands
+
+### Generate Missing L0/L1 Layers
+
+```bash
+cortex-mem-cli --config config.toml --tenant tenant_claw layers ensure-all
+```
+
+Scans filesystem and generates `.abstract.md` and `.overview.md` files for directories that lack them.
+
+**Run this when:**
+- `layers status` shows missing directories
+- Search results lack proper context/snippets
+- After manual data recovery
+
+**What it does:**
+1. Scans all session directories
+2. Identifies directories without L0/L1 files
+3. Uses LLM to generate abstracts and overviews
+4. Saves generated files
+
+### Rebuild Vector Index
+
+```bash
+cortex-mem-cli --config config.toml --tenant tenant_claw vector reindex
+```
+
+Cleans up stale vectors (no URI) and re-syncs all files to the vector database.
+
+**Run this when:**
+- `vector status` shows stale vectors
+- Search returns inconsistent results
+- After manual data recovery
+- Vector database corruption suspected
+
+**What it does:**
+1. Removes vectors without URI metadata
+2. Re-scans all files
+3. Generates new embeddings
+4. Syncs to Qdrant
+
+### Prune Dangling Vectors
+
+```bash
+cortex-mem-cli --config config.toml --tenant tenant_claw vector prune
+```
+
+Removes vectors whose source files no longer exist on disk.
+
+**Run this when:**
+- After deleting session files
+- Disk space is a concern
+- Index cleanup is needed
+
+**Preview mode (recommended first):**
+```bash
+cortex-mem-cli --config config.toml --tenant tenant_claw vector prune --dry-run
+```
+
+Shows what would be deleted without making changes.
+
+### Regenerate Oversized Abstracts
+
+```bash
+cortex-mem-cli --config config.toml --tenant tenant_claw layers regenerate-oversized
+```
+
+Regenerates `.abstract.md` files that exceed the size limit.
+
+**Run this when:**
+- Abstract files have grown too large
+- Search performance is degraded
+
+## Recommended Maintenance Schedule
+
+| Frequency | Command | Purpose |
+|-----------|---------|---------|
+| Daily | `stats` | Quick health check |
+| Weekly | `layers status` + `vector status` | Detect anomalies early |
+| As needed | `layers ensure-all` | Fix missing layers |
+| As needed | `vector reindex` | Fix index corruption |
+| Monthly | `vector prune` | Clean up dangling data |
+
+## Quick Fix Flow
+
+1. **Search not working well?**
+   ```bash
+   cortex-mem-cli --config config.toml --tenant tenant_claw layers status
+   cortex-mem-cli --config config.toml --tenant tenant_claw vector status
+   ```
+
+2. **Missing L0/L1 layers detected?**
+   ```bash
+   cortex-mem-cli --config config.toml --tenant tenant_claw layers ensure-all
+   ```
+
+3. **Stale vectors detected?**
+   ```bash
+   cortex-mem-cli --config config.toml --tenant tenant_claw vector reindex
+   ```
+
+4. **Still having issues?**
+   ```bash
+   cortex-mem-cli --config config.toml --tenant tenant_claw vector prune
+   ```
+
+## Troubleshooting
+
+### CLI Not Found
+
+Ensure `cortex-mem-cli` is in your PATH or use the full path:
+```bash
+/path/to/cortex-mem-cli --config config.toml ...
+```
+
+### Connection Refused
+
+Check that cortex-mem-service is running:
+```bash
+curl http://localhost:8085/health
+```
+
+### Qdrant Connection Issues
+
+Verify Qdrant is accessible:
+```bash
+curl http://localhost:6333/collections
+```
+
+### Layer Generation Fails
+
+1. Check LLM API key in config.toml
+2. Verify network connectivity to API endpoint
+3. Check for rate limiting or quota issues

package/skill/references/setup.md

@@ -0,0 +1,150 @@
+# Setup Guide
+
+Installation and configuration guide for MemClaw.
+
+## Requirements
+
+| Requirement | Details |
+|-------------|---------|
+| **Platforms** | Windows x64, macOS Apple Silicon |
+| **Node.js** | ≥ 22.0.0 |
+| **OpenClaw** | Installed and configured |
+
+## Installation
+
+### Method 1: Install from npm
+
+```bash
+openclaw plugins install @memclaw/plugin
+```
+
+### Method 2: Local Development Installation
+
+For developers using a local version or developing the plugin:
+
+```bash
+# Clone the repository
+git clone https://github.com/sopaco/cortex-mem.git
+cd cortex-mem/examples/@memclaw/plugin
+
+# Install dependencies
+bun install
+
+# Build the plugin
+bun run build
+
+# Create symlink to plugin directory
+mkdir -p ~/.openclaw/plugins
+ln -sf "$(pwd)" ~/.openclaw/plugins/memclaw
+```
+
+Configure in `openclaw.json` with local path:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "memclaw": {
+        "enabled": true,
+        "path": "./plugins/memclaw"
+      }
+    }
+  }
+}
+```
+
+After code changes, rebuild with `bun run build` and restart OpenClaw.
+
+## OpenClaw Configuration
+
+Edit your `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "memclaw": {
+        "enabled": true,
+        "config": {
+          "serviceUrl": "http://127.0.0.1:8085",
+          "tenantId": "tenant_claw",
+          "autoStartServices": true
+        }
+      }
+    }
+  },
+  "agents": {
+    "defaults": {
+      "memorySearch": { "enabled": false }
+    }
+  }
+}
+```
+
+> **Important**: Set `memorySearch.enabled: false` to disable OpenClaw's built-in memory search and use MemClaw instead.
+
+## LLM Configuration
+
+On first run, MemClaw creates a configuration file:
+
+| Platform | Path |
+|----------|------|
+| Windows | `%APPDATA%\memclaw\config.toml` |
+| macOS | `~/Library/Application Support/memclaw/config.toml` |
+
+Edit the configuration file and fill in required fields:
+
+```toml
+# LLM Configuration [REQUIRED for memory processing]
+[llm]
+# Your LLM API endpoint (OpenAI-compatible)
+api_base_url = "https://api.openai.com/v1"
+# Your API key [REQUIRED]
+api_key = "sk-xxx"
+# Model for memory extraction and layer generation
+model_efficient = "gpt-4o-mini"
+temperature = 0.1
+max_tokens = 4096
+
+# Embedding Configuration [REQUIRED for vector search]
+[embedding]
+# Your embedding API endpoint (OpenAI-compatible)
+api_base_url = "https://api.openai.com/v1"
+# Your API key [REQUIRED - can be same as llm.api_key]
+api_key = "sk-xxx"
+model_name = "text-embedding-3-small"
+batch_size = 10
+```
+
+Then restart OpenClaw.
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `serviceUrl` | string | `http://127.0.0.1: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) |
+
+## Troubleshooting
+
+### Services Won't Start
+
+1. Check that ports 6333, 6334, 8085 are available
+2. Verify `api_key` fields are filled in config.toml
+3. Run `openclaw skills` to check plugin status
+
+### Configuration File Not Created
+
+1. Ensure OpenClaw has write permissions to the config directory
+2. Check OpenClaw logs for error messages
+3. Manually create the directory and restart OpenClaw
+
+### API Key Issues
+
+1. Verify your API key is valid and has sufficient credits
+2. Ensure `api_base_url` is correct for your provider
+3. Check network connectivity to the API endpoint

package/skill/references/tools.md

@@ -0,0 +1,170 @@
+# Tools Reference
+
+Detailed documentation for MemClaw tools.
+
+## cortex_search
+
+Semantic search across all memories using L0/L1/L2 tiered retrieval.
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `query` | string | Yes | - | The 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) |
+
+**When to use:**
+- Find past conversations or decisions
+- Search for specific information across all sessions
+- Discover related memories by semantic similarity
+
+**Example:**
+```json
+{
+  "query": "database architecture decisions",
+  "limit": 5,
+  "min_score": 0.6
+}
+```
+
+**Response format:**
+- Returns ranked results with relevance scores
+- Each result includes `uri`, `score`, and `snippet`
+
+---
+
+## cortex_recall
+
+Recall memories with more context (snippet + full content).
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `query` | string | Yes | - | The search query |
+| `scope` | string | No | - | Session/thread ID to limit search scope |
+| `limit` | integer | No | 10 | Maximum number of results |
+
+**When to use:**
+- Need memories with full context, not just summaries
+- Want to see the original content, not just snippets
+- Conducting detailed memory analysis
+
+**Example:**
+```json
+{
+  "query": "user preferences for code style",
+  "limit": 10
+}
+```
+
+**Response format:**
+- Returns results with both `snippet` (summary) and `content` (full text)
+- Content is truncated if very long (>300 chars preview)
+
+---
+
+## cortex_add_memory
+
+Store a message for future retrieval.
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `content` | string | Yes | - | The content to store in memory |
+| `role` | string | No | `user` | Role of the message sender: `user`, `assistant`, or `system` |
+| `session_id` | string | No | `default` | Session/thread ID for the memory |
+
+**When to use:**
+- Persist important information for future retrieval
+- Store user preferences or decisions
+- Save context that should be searchable later
+
+**Example:**
+```json
+{
+  "content": "User prefers TypeScript with strict mode enabled and explicit return types",
+  "role": "assistant",
+  "session_id": "default"
+}
+```
+
+**What happens:**
+- Message is stored with timestamp
+- Vector embedding is generated automatically
+- L0/L1 layers are generated asynchronously
+
+---
+
+## cortex_list_sessions
+
+List all memory sessions with their status.
+
+**Parameters:** None
+
+**When to use:**
+- Verify sessions exist before searching
+- Check which sessions are active or closed
+- Audit memory usage
+
+**Response format:**
+- Session IDs, status, message counts
+- Creation and update timestamps
+
+---
+
+## cortex_close_session
+
+Close a session and trigger memory extraction pipeline.
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `session_id` | string | No | `default` | Session/thread ID to close |
+
+**When to use:**
+- Conversation is complete
+- Ready to extract structured memories
+- Want to finalize the session's memory content
+
+**What happens:**
+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 is a potentially long-running operation (30-60 seconds).
+
+**Example:**
+```json
+{
+  "session_id": "default"
+}
+```
+
+---
+
+## cortex_migrate
+
+Migrate memories from OpenClaw's native memory system to MemClaw.
+
+**Parameters:** None
+
+**When to use:**
+- First time setup with existing OpenClaw memory
+- Want to preserve previous conversation history
+- Switching from built-in memory to MemClaw
+
+**What happens:**
+1. Finds OpenClaw memory files (`memory/*.md` and `MEMORY.md`)
+2. Converts them to MemClaw's L2 format
+3. Generates L0/L1 layers and vector index
+
+**Prerequisites:**
+- OpenClaw workspace exists at `~/.openclaw/workspace`
+- Memory files exist in `~/.openclaw/workspace/memory/`
+
+**Run only once during initial setup.**