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
• Easy Configuration: Configure LLM/Embedding directly through OpenClaw plugin settings
• Cross-Platform: Supports Windows x64, macOS Apple Silicon, and Linux x64

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        → Layered semantic search
         ├── cortex_recall        → Recall with context
         ├── cortex_add_memory    → Store memories
         ├── cortex_close_session → Close & extract
         ├── cortex_migrate       → Migrate existing memory
         ├── cortex_maintenance   → Periodic maintenance
         ├── cortex_ls            → Browse memory filesystem
         ├── cortex_get_abstract  → L0 quick preview
         ├── cortex_get_overview  → L1 moderate detail
         ├── cortex_get_content   → L2 full content
         └── cortex_explore       → Smart exploration
                    │
                    ▼
         cortex-mem-service (port 8085)
                    │
                    ▼
         Qdrant (port 6334)

Installation

Requirements

| Requirement | Details | |-------------|---------| | Platforms | Windows x64, macOS Apple Silicon, Linux x64 | | Node.js | ≥ 20.0.0 | | OpenClaw | Installed and configured |

Install Plugin

openclaw plugins install @memclaw/memclaw

Local Development Installation

For developers who want to use a local version of memclaw or develop the plugin:

# 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

Option A: Use plugins.load.paths

{
  "plugins": {
    "load": {
      "paths": ["/path/to/cortex-mem/examples/@memclaw/plugin"]
    },
    "entries": {
      "memclaw": { "enabled": true }
    }
  }
}

Option B: Symlink to extensions directory

mkdir -p ~/.openclaw/extensions
ln -sf "$(pwd)" ~/.openclaw/extensions/memclaw

Then enable in openclaw.json:

{
  "plugins": {
    "entries": {
      "memclaw": { "enabled": true }
    }
  }
}

After making code changes, rebuild with bun run build and restart OpenClaw.

Configuration

Plugin Configuration

Configure MemClaw directly through OpenClaw plugin settings in openclaw.json:

{
  "plugins": {
    "entries": {
      "memclaw": {
        "enabled": true,
        "config": {
          "serviceUrl": "http://localhost:8085",
          "tenantId": "tenant_claw",
          "autoStartServices": true,
          "llmApiBaseUrl": "https://api.openai.com/v1",
          "llmApiKey": "your-llm-api-key",
          "llmModel": "gpt-4o-mini",
          "embeddingApiBaseUrl": "https://api.openai.com/v1",
          "embeddingApiKey": "your-embedding-api-key",
          "embeddingModel": "text-embedding-3-small"
        }
      }
    }
  },
  "agents": {
    "defaults": {
      "memorySearch": { "enabled": false }
    }
  }
}

Note: Set memorySearch.enabled: false to disable OpenClaw's built-in memory search and use MemClaw instead.

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | serviceUrl | string | http://localhost: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) | | qdrantPort | number | 6334 | Qdrant port (gRPC) | | servicePort | number | 8085 | cortex-mem-service port | | llmApiBaseUrl | string | https://api.openai.com/v1 | LLM API endpoint URL | | llmApiKey | string | - | LLM API key (required) | | llmModel | string | gpt-5-mini | LLM model name | | embeddingApiBaseUrl | string | https://api.openai.com/v1 | Embedding API endpoint URL | | embeddingApiKey | string | - | Embedding API key (required) | | embeddingModel | string | text-embedding-3-small | Embedding model name |

Configuration via UI

You can also configure the plugin through OpenClaw UI:

1. Open OpenClaw Settings (openclaw.json or via UI)
2. Navigate to Plugins → MemClaw → Configuration
3. Fill in the required fields for LLM and Embedding
4. Save and restart OpenClaw Gateway for changes to take effect

Available Tools

cortex_search

Layered semantic search with fine-grained control over returned content.

Key Parameters:

• return_layers: ["L0"] (default, ~100 tokens), ["L0","L1"] (~2100 tokens), ["L0","L1","L2"] (full)

{
  "query": "database architecture decisions",
  "limit": 5,
  "min_score": 0.6,
  "return_layers": ["L0"]
}

For more context, use return_layers: ["L0","L1"]. For full content, use ["L0","L1","L2"].

cortex_recall

Recall memories with more context (snippet + full content).

{
  "query": "user preferences for code style",
  "limit": 10
}

cortex_add_memory

Store a message for future retrieval with optional metadata.

{
  "content": "User prefers TypeScript with strict mode",
  "role": "assistant",
  "session_id": "default",
  "metadata": {
    "tags": ["preference", "typescript"],
    "importance": "high"
  }
}

Parameters:

• content: The message content (required)
• role: "user", "assistant", or "system" (default: user)
• session_id: Session/thread ID (uses default if not specified)
• metadata: Optional metadata like tags, importance, or custom fields

cortex_close_session

Close a session and trigger memory extraction pipeline (takes 30-60 seconds).

{
  "session_id": "default"
}

Important: Call this tool proactively at natural checkpoints, not just when the conversation ends. Ideal timing: after completing important tasks, topic transitions, or accumulating enough conversation content.

cortex_ls

List directory contents to browse the memory space like a virtual filesystem.

{
  "uri": "cortex://session",
  "recursive": false,
  "include_abstracts": false
}

Parameters:

• uri: Directory URI to list (default: cortex://session)
• recursive: List all subdirectories recursively
• include_abstracts: Show L0 abstracts for quick preview

Common URIs:

• cortex://session - List all sessions
• cortex://session/{session_id} - Browse a specific session
• cortex://session/{session_id}/timeline - View timeline messages
• cortex://session/{session_id}/memories - View extracted memories

cortex_get_abstract

Get L0 abstract layer (~100 tokens) for quick relevance checking.

{
  "uri": "cortex://session/abc123/timeline/2024-01-15_001.md"
}

Use this to quickly determine if content is relevant before reading more.

cortex_get_overview

Get L1 overview layer (~2000 tokens) with core information and context.

{
  "uri": "cortex://session/abc123/timeline/2024-01-15_001.md"
}

Use when you need more detail than the abstract but not the full content.

cortex_get_content

Get L2 full content layer - the complete original content.

{
  "uri": "cortex://session/abc123/timeline/2024-01-15_001.md"
}

Use only when you need the complete, unprocessed content.

cortex_explore

Smart exploration combining search and browsing for guided discovery.

{
  "query": "authentication flow",
  "start_uri": "cortex://session",
  "return_layers": ["L0"]
}

Returns an exploration path with relevance scores and matching results.

cortex_migrate

Migrate from OpenClaw native memory to MemClaw. Run once during initial setup.

cortex_maintenance

Perform periodic maintenance on MemClaw data (prune, reindex, ensure-all layers).

{
  "dryRun": false,
  "commands": ["prune", "reindex", "ensure-all"]
}

Parameters:

• dryRun: Preview changes without executing (default: false)
• commands: Which maintenance commands to run (default: all)

This tool runs automatically every 3 hours. Call manually when search results seem incomplete or stale.

Quick Decision Flow

┌─────────────────────────────────────────────────────────────────┐
│                     How to Access Memories                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Do you know WHERE the information is?                          │
│       │                                                          │
│       ├── YES ──► Use Direct Tiered Access                       │
│       │           cortex_ls → cortex_get_abstract/overview/content│
│       │                                                          │
│       └── NO ──► Do you know WHAT you're looking for?            │
│                    │                                             │
│                    ├── YES ──► Use Semantic Search               │
│                    │            cortex_search                     │
│                    │                                             │
│                    └── NO ──► Use Exploration                    │
│                                 cortex_explore                    │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

| Scenario | Tool | |----------|------| | Find information across all sessions | cortex_search | | Browse memory structure | cortex_ls | | Quick relevance check for URI | cortex_get_abstract | | Get more details on relevant URI | cortex_get_overview | | Need exact full content | cortex_get_content | | Explore with purpose | cortex_explore | | Save important information | cortex_add_memory | | Complete a task/topic | cortex_close_session | | First-time use with existing memories | cortex_migrate | | Data maintenance | cortex_maintenance |

For detailed guidance on tool selection, session lifecycle, and best practices, see the Skills Documentation.

Troubleshooting

Plugin Not Working

Services Won't Start

1. Check that ports 6333, 6334, 8085 are available
2. Verify LLM and Embedding credentials are configured correctly
3. Run openclaw skills to check plugin status

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:

# 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

Documentation

• Skills Documentation — Agent skill guide with troubleshooting
• Best Practices — Tool selection, session lifecycle, search strategies
• Tools Reference — Detailed tool parameters and examples

License

MIT