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_commit_session → Commit & 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-5-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:

Open OpenClaw Settings (openclaw.json or via UI)
Navigate to Plugins → MemClaw → Configuration
Fill in the required fields for LLM and Embedding
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_commit_session

Commit 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://user/{user_id}/preferences - View user preferences (extracted memories)
cortex://user/{user_id}/entities - View user entities (people, projects, etc.)
cortex://agent/{agent_id}/cases - View agent problem-solution cases

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_commit_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

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

Migration Fails

Ensure OpenClaw workspace exists at ~/.openclaw/workspace
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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

MemClaw

Overview

Features

Architecture

Memory Layers

System Components

Installation

Requirements

Install Plugin

Local Development Installation

Configuration

Plugin Configuration

Configuration Options

Configuration via UI

Available Tools

cortex_search

cortex_recall

cortex_add_memory

cortex_commit_session

cortex_ls

cortex_get_abstract

cortex_get_overview

cortex_get_content

cortex_explore

cortex_migrate

cortex_maintenance

Quick Decision Flow

Troubleshooting

Plugin Not Working

Services Won't Start

Migration Fails

CLI Reference

Documentation

License

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

MemClaw

Overview

Features

Architecture

Memory Layers

System Components

Installation

Requirements

Install Plugin

Local Development Installation

Configuration

Plugin Configuration

Configuration Options

Configuration via UI

Available Tools

cortex_search

cortex_recall

cortex_add_memory

cortex_commit_session

cortex_ls

cortex_get_abstract

cortex_get_overview

cortex_get_content

cortex_explore

cortex_migrate

cortex_maintenance

Quick Decision Flow

Troubleshooting

Plugin Not Working

Services Won't Start

Migration Fails

CLI Reference

Documentation

License