@memclaw/memclaw 0.9.16 → 0.9.18

package/skills/memclaw/references/security.md

@@ -0,0 +1,31 @@
+# Security & Trust
+
+MemClaw is designed with user privacy and data security as top priorities.
+
+## What the Plugin Does
+
+- **Local Data Storage**: All memory data is stored in the local user data directory
+- **Local Processing**: Based on advanced Cortex Memory technology, providing outstanding memory management capabilities with high performance and accuracy
+- **Migration Safety**: Only reads existing OpenClaw memory files during migration
+
+## What the Plugin Does NOT Do
+
+- **No External Data Transmission**: Does NOT send data to external servers (all processing is local)
+- **No API Key Leakage**: Does NOT transmit API keys to anywhere other than your configured LLM/embedding provider
+
+## Data Storage Location
+
+| Platform | Path |
+|----------|------|
+| macOS | `~/Library/Application Support/memclaw` |
+| Windows | `%LOCALAPPDATA%\memclaw` |
+| Linux | `~/.local/share/memclaw` |
+
+## API Key Security
+
+API keys are configured through OpenClaw plugin settings and are marked as sensitive fields. OpenClaw handles secure storage of these credentials.
+
+**Best Practices:**
+- Never share your `openclaw.json` configuration file publicly
+- Use environment-specific API keys when possible
+- Rotate API keys periodically according to your provider's recommendations

package/skills/memclaw/references/tools.md

@@ -1,205 +1,326 @@
-# Tools Reference
+# MemClaw Tools Reference
 
-Detailed documentation for MemClaw tools.
+Complete reference for all MemClaw tools.
 
-## cortex_search
+## Search Tools
 
-Semantic search using L0/L1/L2 hierarchical retrieval.
+### cortex_search
 
-**Parameters:**
+Layered semantic search with L0/L1/L2 tiered retrieval.
 
-| 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) |
+**Parameters:**
 
-**Use Cases:**
-- Find past conversations or decisions
-- Search for specific information across all sessions
-- Discover related memories through semantic similarity
+| Name | 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) |
+| return_layers | ("L0" \| "L1" \| "L2")[] | No | ["L0"] | Which layers to return |
 
-**Example:**
+**Response:**
 ```json
 {
-  "query": "database architecture decisions",
-  "limit": 5,
-  "min_score": 0.6
+  "results": [
+    {
+      "uri": "cortex://session/abc123/timeline/...",
+      "score": 0.85,
+      "snippet": "L0 abstract text...",
+      "overview": "L1 overview text (if requested)...",
+      "content": "L2 full content (if requested)...",
+      "layers": ["L0", "L1"],
+      "source": "layered_vector"
+    }
+  ],
+  "total": 5
 }
 ```
 
-**Response Format:**
-- Returns results sorted by relevance
-- Each result contains `uri`, `score`, and `snippet`
+**Example:**
+```typescript
+// Minimal tokens - just abstracts
+cortex_search({ query: "API design", return_layers: ["L0"] })
+
+// More context needed
+cortex_search({ query: "authentication flow", return_layers: ["L0", "L1"] })
+
+// Full content retrieval
+cortex_search({ query: "exact error message", return_layers: ["L0", "L1", "L2"] })
+```
 
 ---
 
-## cortex_recall
+### cortex_recall
 
-Retrieve memories with more context (summary + full content).
+Convenience wrapper returning L0 + L2 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 |
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| query | string | Yes | - | Search query |
+| scope | string | No | - | Session/thread ID to limit 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
+**Response:** Same as `cortex_search` with `return_layers: ["L0", "L2"]`
 
-**Example:**
+---
+
+## Filesystem Tools
+
+### cortex_ls
+
+List directory contents to browse memory structure.
+
+**Parameters:**
+
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| uri | string | No | "cortex://session" | Directory URI to list |
+| recursive | boolean | No | false | Recursively list subdirectories |
+| include_abstracts | boolean | No | false | Include L0 abstracts for files |
+
+**Response:**
 ```json
 {
-  "query": "user code style preferences",
-  "limit": 10
+  "uri": "cortex://session",
+  "total": 3,
+  "entries": [
+    {
+      "uri": "cortex://session/abc123",
+      "name": "abc123",
+      "is_directory": true,
+      "size": 0,
+      "modified": "2024-01-15T10:30:00Z"
+    },
+    {
+      "uri": "cortex://session/xyz789",
+      "name": "xyz789",
+      "is_directory": true,
+      "size": 0,
+      "modified": "2024-01-14T15:00:00Z",
+      "abstract_text": "Discussion about API design..."
+    }
+  ]
 }
 ```
 
-**Response Format:**
-- Returns results with `snippet` (summary) and `content` (full text)
-- Content is truncated when too long (preview >300 characters)
+**Example:**
+```typescript
+// List all sessions
+cortex_ls({ uri: "cortex://session" })
+
+// Browse with abstracts
+cortex_ls({ 
+  uri: "cortex://session/abc123/timeline", 
+  include_abstracts: true 
+})
+
+// Recursive listing
+cortex_ls({ 
+  uri: "cortex://session/abc123", 
+  recursive: true 
+})
+```
 
 ---
 
-## cortex_add_memory
+### cortex_explore
 
-Store messages for later retrieval.
+Smart exploration combining search and browsing.
 
 **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
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| query | string | Yes | - | Exploration query |
+| start_uri | string | No | "cortex://session" | Starting URI |
+| return_layers | ("L0" \| "L1" \| "L2")[] | No | ["L0"] | Layers to return in matches |
 
-**Example:**
+**Response:**
 ```json
 {
-  "content": "User prefers TypeScript with strict mode enabled",
-  "role": "assistant",
-  "session_id": "default"
+  "query": "authentication",
+  "exploration_path": [
+    {
+      "uri": "cortex://session/abc123/timeline",
+      "relevance_score": 0.92,
+      "abstract_text": "Discussion about OAuth..."
+    }
+  ],
+  "matches": [
+    {
+      "uri": "cortex://session/abc123/timeline/...",
+      "score": 0.88,
+      "snippet": "OAuth implementation...",
+      "layers": ["L0"]
+    }
+  ],
+  "total_explored": 5,
+  "total_matches": 2
 }
 ```
 
-**Execution Effects:**
-- Message is stored with timestamp
-- Vector embedding is automatically generated
-- L0/L1 layers are generated asynchronously
+---
+
+## Tiered Access Tools
+
+### cortex_get_abstract (L0)
+
+Get ~100 token summary for quick relevance check.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| uri | string | Yes | Content URI |
+
+**Response:**
+```json
+{
+  "uri": "cortex://session/abc123/timeline/...",
+  "content": "Short abstract...",
+  "layer": "L0",
+  "token_count": 95
+}
+```
 
 ---
 
-## cortex_list_sessions
+### cortex_get_overview (L1)
 
-List all memory sessions and their status.
+Get ~2000 token overview with key information.
 
-**Parameters:** None
+**Parameters:**
 
-**Use Cases:**
-- Verify sessions exist before searching
-- Check which sessions are active or closed
-- Audit memory usage
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| uri | string | Yes | Content URI |
 
-**Response Format:**
-- Session ID, status, message count
-- Creation and update timestamps
+**Response:**
+```json
+{
+  "uri": "cortex://session/abc123/timeline/...",
+  "content": "Detailed overview...",
+  "layer": "L1",
+  "token_count": 1850
+}
+```
 
 ---
 
-## cortex_close_session
+### cortex_get_content (L2)
 
-Close a session and trigger the memory extraction process.
+Get full original content.
 
 **Parameters:**
 
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `session_id` | string | No | `default` | Session/thread ID to close |
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| uri | string | Yes | Content URI (file only) |
 
-**Use Cases:**
-- When a conversation is complete
-- Preparing to extract structured memories
-- Wanting to finalize a session's memory content
+**Response:**
+```json
+{
+  "uri": "cortex://session/abc123/timeline/...",
+  "content": "Full original content...",
+  "layer": "L2",
+  "token_count": 5420
+}
+```
 
-**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).
+## Storage Tools
 
-**Example:**
+### cortex_add_memory
+
+Store a message in memory.
+
+**Parameters:**
+
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| content | string | Yes | - | Message content |
+| role | string | No | "user" | Message role: "user", "assistant", "system" |
+| session_id | string | No | default | Session/thread ID |
+| metadata | object | No | - | Optional metadata (tags, importance, etc.) |
+
+**Response:**
 ```json
 {
-  "session_id": "default"
+  "success": true,
+  "message_uri": "cortex://session/default/timeline/2024-01/15/10_30_00_abc123.md"
 }
 ```
 
-> **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.
+**Example:**
+```typescript
+cortex_add_memory({
+  content: "User prefers dark mode in all applications",
+  role: "assistant",
+  metadata: {
+    tags: ["preference", "ui"],
+    importance: "medium"
+  }
+})
+```
 
 ---
 
-## cortex_migrate
-
-Migrate from OpenClaw's native memory system to MemClaw.
+### cortex_close_session
 
-**Parameters:** None
+Trigger memory extraction pipeline.
 
-**Use Cases:**
-- First-time use with existing OpenClaw memories
-- Want to preserve previous conversation history
-- Switching from built-in memory to MemClaw
+**Parameters:**
 
-**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
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| session_id | string | No | Session/thread ID (uses default if not specified) |
 
-**Prerequisites:**
-- OpenClaw workspace exists at `~/.openclaw/workspace`
-- Memory files exist at `~/.openclaw/workspace/memory/`
+**Response:**
+```json
+{
+  "success": true,
+  "session": {
+    "thread_id": "abc123",
+    "status": "closed",
+    "message_count": 42
+  }
+}
+```
 
-**Run only once during initial setup.**
+**Important:** Call this periodically, not just at conversation end.
 
 ---
 
-## cortex_maintenance
+## Maintenance Tools
 
-Perform periodic maintenance on MemClaw data.
+### cortex_maintenance
+
+Perform periodic maintenance.
 
 **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 |
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| dryRun | boolean | No | false | Preview changes without executing |
+| commands | string[] | No | ["prune", "reindex", "ensure-all"] | Commands to run |
+
+---
 
-**Use Cases:**
-- Search results are incomplete or outdated
-- Recovering from crash or data corruption
-- Need to clean up disk space
+### cortex_migrate
 
-**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
+Migrate from OpenClaw native memory.
 
-**Example:**
+**Parameters:** None
+
+**Response:**
 ```json
 {
-  "dryRun": false,
-  "commands": ["prune", "reindex", "ensure-all"]
+  "dailyLogsMigrated": 15,
+  "memoryMdMigrated": true,
+  "sessionsCreated": ["migrated_2024-01-15"],
+  "errors": []
 }
-```
-
-> **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

@@ -1,13 +1,24 @@
 ---
 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.
+description: MemClaw Maintenance Guide — Installation, configuration, and maintenance guidance. For daily usage and tool operations, use the [`memclaw` skill](https://clawhub.ai/sopaco/memclaw) instead.
 ---
 
-# MemClaw Setup Guide
+# MemClaw Maintenance 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.
+> **Recommended Memory Solution**: MemClaw is the recommended memory system for OpenClaw, providing tiered semantic memory with three-layer retrieval capabilities and automatic service management.
 
-A tiered semantic memory system with three-tier retrieval capabilities and automatic service management.
+## Important: Skill Usage Guide
+
+| Purpose | Use This Skill |
+|---------|---------------|
+| **Daily usage** — searching, browsing, storing memories | [`memclaw`](https://clawhub.ai/sopaco/memclaw) |
+| **Installation & Setup** | `memclaw-maintance` (this skill) |
+| **Configuration** | `memclaw-maintance` (this skill) |
+| **Troubleshooting & Maintenance** | `memclaw-maintance` (this skill) |
+
+> **For memory operations like `cortex_search`, `cortex_ls`, `cortex_add_memory`, etc., please use the [`memclaw` skill](https://clawhub.ai/sopaco/memclaw) which provides comprehensive usage documentation.**
+
+---
 
 ## Security & Trust
 
@@ -21,23 +32,11 @@ A tiered semantic memory system with three-tier retrieval capabilities and autom
 - 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)
+## Installation
 
-Execute the following command to install the plugin:
+### Step 1: Install the Plugin
 
 ```bash
 openclaw plugins install @memclaw/memclaw
@@ -61,7 +60,7 @@ Enable MemClaw in `openclaw.json`:
 
 ### Step 3: Configure API Keys
 
-**API keys must be configured to use MemClaw.**
+**API keys are required to use MemClaw.**
 
 1. Open OpenClaw settings (`openclaw.json` or via UI)
 2. Navigate to Plugins → MemClaw → Configuration
@@ -99,15 +98,24 @@ Enable MemClaw in `openclaw.json`:
 
 Restart OpenClaw to activate the plugin and start services.
 
-## First-Time Use
+---
+
+## Verify Installation
+
+### Service Status Check
 
-### Verify Service Status
+After restarting, MemClaw will automatically start the required services.
 
-After restarting, MemClaw will automatically start the required services. If configured correctly, you should be able to use the memory tools normally.
+| 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"}` |
+
+> **Note**: MemClaw does not require users to install any Docker environment. All dependencies are prepared during the plugin installation.
 
 ### Migrate Existing Memories (Optional)
 
-If the user has existing OpenClaw native memories, call the `cortex_migrate` tool to migrate them to MemClaw:
+If the user has existing OpenClaw native memories, call `cortex_migrate` to migrate them:
 
 ```json
 {}
@@ -120,23 +128,52 @@ This will:
 
 > **Run only once** during initial setup.
 
-## Quick Start
+---
+
+## Maintenance
 
-After installation, use the following decision flow for memory operations:
+### Periodic Maintenance
 
-| Scenario | Tool |
+Use `cortex_maintenance` for periodic maintenance:
+
+```json
+{
+  "dryRun": false,
+  "commands": ["prune", "reindex", "ensure-all"]
+}
+```
+
+**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
+
+> **Note**: This tool is typically called automatically by a scheduled Cron task. Manual invocation is for troubleshooting or on-demand maintenance.
+
+---
+
+## Data Management
+
+### Data Location
+
+| Platform | Path |
 |----------|------|
-| 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` |
+| macOS | `~/Library/Application Support/memclaw` |
+| Windows | `%LOCALAPPDATA%\memclaw` |
+| Linux | `~/.local/share/memclaw` |
 
-> **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.
+### 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
+
+---
 
 ## 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)
+- **[troubleshooting.md](./references/troubleshooting.md)** — Common issues and solutions
+- **[tools.md](./references/tools.md)** — Maintenance-related tool documentation
+- **`memclaw` skill** — For daily memory operations and usage patterns
+- **Open Source**: [The Project 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)