@memclaw/memclaw

v0.9.53

Published

a month ago

MemClaw - The Cortex Memory plugin for OpenClaw. Layered semantic memory for OpenClaw with easy setup and migration

0High
0Medium
0Low

sopaco

openclaw memory semantic-search vector-search ai agent cortex-mem

@memclaw/memclaw — Memory Plugin

Layered semantic memory plugin for OpenClaw. Provides L0/L1/L2 tiered retrieval, automatic service management (Qdrant + cortex-mem-service), and one-click migration from OpenClaw native memory.

Overview

MemClaw is an OpenClaw Memory Plugin (kind: "memory") that brings Cortex Memory's production-grade three-layer memory architecture to your AI agents. Unlike OpenClaw's built-in memory, MemClaw uses L0/L1/L2 tiered retrieval to balance speed and context — achieving 68.42% accuracy on LoCoMo10 vs. 35.65% for native memory, while using ~82% fewer tokens per query.

The plugin is tool-driven: the AI agent explicitly calls tools like cortex_search, cortex_add_memory, and cortex_commit_session to manage memories. This gives you full control over when and how memories are stored and retrieved.

Features

Three-Layer Memory Architecture — L0 (abstract ~100 tokens), L1 (overview ~2000 tokens), L2 (full content) for intelligent tiered retrieval
Automatic Service Management — Auto-starts Qdrant vector database and cortex-mem-service on plugin load
Semantic Search — Vector-based similarity search across all memory layers with weighted scoring (L0 20% + L1 30% + L2 50%)
Virtual Filesystem Browsing — Browse memory space via cortex:// URIs with cortex_ls
Tiered Access — Fine-grained control over which layers to read per request
Smart Exploration — Guided discovery combining search and browsing
Migration Support — One-click migration from OpenClaw native memory files
AGENTS.md Auto-Enhancement — Automatically injects MemClaw usage guidelines into your workspace's AGENTS.md
Periodic Maintenance — Auto-scheduled maintenance (prune, reindex, ensure-all layers) every 3 hours
Cross-Platform — Windows x64, macOS Apple Silicon, Linux x64
Zero External Dependencies — Qdrant and cortex-mem-service are pre-compiled and bundled; no manual installation needed

Architecture

Memory Layers

| Layer | File Suffix | Size | Content | Weight | Role | |-------|-------------|------|---------|--------|------| | L0 (Abstract) | .abstract.md | ~100 tokens | High-level one-line summary | 20% | Quick relevance filtering | | L1 (Overview) | .overview.md | ~500-2000 tokens | Structured summary: key points, entities, decisions | 30% | Context refinement | | L2 (Full) | .md | Original size | Complete original content | 50% | Precise matching |

Progressive disclosure: search queries all three layers via Qdrant, score with weighted ranking, then return results from the requested layers. This dramatically reduces token consumption compared to loading full conversation history.

System Components

OpenClaw + MemClaw Plugin
         │
         ├── cortex_search         → Layered semantic search
         ├── cortex_recall         → Quick recall (L0 + L2)
         ├── cortex_add_memory     → Store a message
         ├── cortex_commit_session → Commit & extract memories
         ├── 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_migrate        → Migrate from native memory
         └── cortex_maintenance    → Periodic maintenance
                    │
                    ▼
         cortex-mem-service (HTTP REST API, port 8085)
                    │
                    ▼
         Qdrant (vector database, ports 6333/6334)
                    │
                    ▼
         Local filesystem (Markdown files)

Installation

Requirements

| Requirement | Details | |-------------|---------| | Platforms | Windows x64, macOS Apple Silicon, Linux x64 | | Node.js | ≥ 20.0.0 | | OpenClaw | ≥ 2026.3.8 (installed and configured) | | LLM API | OpenAI-compatible API key (for memory extraction & summarization) | | Embedding API | OpenAI-compatible Embedding API key (for vector search) |

From npm

openclaw plugins install @memclaw/memclaw

Then enable in your openclaw.json:

{
  "plugins": {
    "entries": {
      "memclaw": {
        "enabled": true,
        "config": {
          "tenantId": "tenant_claw",
          "autoStartServices": true,
          "llmApiKey": "your-llm-api-key",
          "llmModel": "gpt-5-mini",
          "embeddingApiKey": "your-embedding-api-key",
          "embeddingModel": "text-embedding-3-small"
        }
      }
    }
  },
  "agents": {
    "defaults": {
      "memorySearch": { "enabled": false }
    }
  }
}

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

Local Development

git clone https://github.com/sopaco/memclaw.git
cd memclaw/plugin

# Install dependencies
bun install

# Build
bun run build

Option A: Use plugins.load.paths

{
  "plugins": {
    "load": {
      "paths": ["/path/to/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 as shown above. After code changes, rebuild with bun run build and restart OpenClaw.

Configuration

Plugin Configuration

MemClaw is configured directly through OpenClaw's plugin settings in openclaw.json. On first run, a config.toml file is also created at a platform-specific location:

| Platform | Config Path | |----------|------------| | macOS | ~/Library/Application Support/memclaw/config.toml | | Windows | %LOCALAPPDATA%\memclaw\config.toml | | Linux | ~/.local/share/memclaw/config.toml |

The plugin settings in openclaw.json take precedence over the TOML file. LLM and Embedding API keys from openclaw.json are automatically synced to the TOML file.

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | serviceUrl | string | http://localhost:8085 | Cortex Memory service URL | | tenantId | string | tenant_claw | Tenant ID for multi-user data isolation | | autoStartServices | boolean | true | Auto-start Qdrant and cortex-mem-service | | defaultSessionId | string | default | Default session ID for memory operations | | searchLimit | number | 10 | Default number of search results | | minScore | number | 0.6 | Minimum relevance score (0-1) | | qdrantPort | number | 6334 | Qdrant gRPC port | | servicePort | number | 8085 | cortex-mem-service port | | llmApiBaseUrl | string | https://api.openai.com/v1 | LLM API endpoint | | llmApiKey | string | — | LLM API key (required) | | llmModel | string | gpt-5-mini | LLM model name | | embeddingApiBaseUrl | string | https://api.openai.com/v1 | Embedding API endpoint | | embeddingApiKey | string | — | Embedding API key (required) | | embeddingModel | string | text-embedding-3-small | Embedding model name | | enhanceClawAgent | boolean | true | Auto-inject MemClaw guidelines into AGENTS.md |

Via UI

Open OpenClaw Settings (openclaw.json or via UI)
Navigate to Plugins → MemClaw → Configuration
Fill in the required LLM and Embedding fields
Save and restart OpenClaw Gateway

Available Tools

cortex_search

Layered semantic search across all memories with fine-grained control over returned content layers.

{
  "query": "database architecture decisions",
  "scope": "cortex://user/default",    // optional — omit to search ALL memories
  "limit": 5,
  "min_score": 0.6,
  "return_layers": ["L0"]              // ["L0"] | ["L0","L1"] | ["L0","L1","L2"]
}

return_layers guide:

| Layers | Tokens | When to Use | |--------|--------|-------------| | ["L0"] | ~100 per result | Quick scanning, finding candidates | | ["L0", "L1"] | ~2100 per result | Need context and key points | | ["L0", "L1", "L2"] | Full | Need exact details or quotes |

cortex_recall

Convenience wrapper for cortex_search with return_layers=["L0", "L2"] — returns both the snippet and full content.

{
  "query": "user preferences for code style",
  "scope": "cortex://user/default",  // optional
  "limit": 10
}

cortex_add_memory

Store a message for future retrieval with optional metadata.

{
  "content": "User prefers TypeScript with strict mode and 2-space indentation",
  "role": "user",                     // "user" | "assistant" | "system"
  "session_id": "default",            // optional
  "metadata": {                       // optional
    "tags": ["preference", "typescript"],
    "importance": "high"
  }
}

cortex_commit_session

Commit accumulated conversation content and trigger the complete memory extraction pipeline. Call proactively at natural checkpoints, not just at conversation end.

{
  "session_id": "default"
}

When to call: After completing a task, topic transitions, after the user shares important preferences, or every 10-20 exchanges. Takes 30-60 seconds, runs asynchronously.

cortex_ls

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

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

Common URIs:

| URI | Description | |-----|-------------| | cortex://session | List all sessions | | cortex://session/{id} | Browse a specific session | | cortex://session/{id}/timeline | Timeline messages | | cortex://user/{id}/preferences | User preferences | | cortex://user/{id}/entities | User entities (people, projects) | | cortex://agent/{id}/cases | Agent cases |

cortex_get_abstract

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

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

cortex_get_overview

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

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

cortex_get_content

Get L2 full content layer — the complete original content.

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

cortex_explore

Smart exploration combining search and browsing for guided discovery within a scope.

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

cortex_migrate

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

memory/*.md daily logs → session timeline files
MEMORY.md → user preferences
Generates L0/L1 layers and vector index

cortex_maintenance

Perform periodic maintenance: vector prune, reindex, and ensure-all layers.

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

Runs automatically every 3 hours via a scheduled timer.

Tool Selection Guide

┌─────────────────────────────────────────────────────────────────┐
│                    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 | | Quick recall with snippet + content | cortex_recall | | Browse memory structure | cortex_ls | | Quick relevance check for a URI | cortex_get_abstract | | Get more details on a 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 or topic | cortex_commit_session | | First-time setup with existing memories | cortex_migrate | | Data maintenance (auto-scheduled) | cortex_maintenance |

Best Practices

Token Optimization

Start with L0: Use return_layers: ["L0"] for initial searches to minimize token usage
Escalate as needed: Only add L1 or L2 when L0 results are relevant but insufficient
Scope wisely: Omit scope to search all memories, or narrow to cortex://user/default for preferences only

Session Management

Commit periodically: Call cortex_commit_session at natural checkpoints, not just at the end
Good rhythm: Once per significant topic completion (every 10-20 exchanges)
Avoid over-committing: Don't call after every single message

Search Strategy

Use natural language: The semantic search understands context, not just keywords
Iterate: If results are poor, rephrase the query or try cortex_explore
Browse when stuck: cortex_ls can reveal memory organization patterns

Metadata Recommendations

When using cortex_add_memory, consider adding:

tags: Array of topic labels (e.g., ["typescript", "debugging"])
importance: "high", "medium", or "low"
category: "preference", "decision", "fact", "entity"

Troubleshooting

Plugin Not Working

Run openclaw skills to check plugin load status
Verify "enabled": true in openclaw.json
Check OpenClaw logs for [memclaw] errors

Services Won't Start

Check that ports 6333 (Qdrant HTTP), 6334 (Qdrant gRPC), and 8085 (cortex-mem-service) are available
Verify LLM and Embedding API keys are configured
Set autoStartServices: false to disable auto-start and manage services manually

Memory Extraction Fails

Ensure cortex_commit_session was called after the conversation
Check that LLM API key is valid and has sufficient rate limits
Processing takes 30-60 seconds — be patient

Migration Fails

Ensure OpenClaw workspace exists at ~/.openclaw/workspace
Verify memory files exist in ~/.openclaw/workspace/memory/
Migration is idempotent — safe to re-run

Search Results Seem Stale

Run cortex_maintenance manually to rebuild indexes
Check that cortex-mem-service is healthy: curl http://localhost:8085/health

CLI Reference

For advanced users, the cortex-mem-cli is available directly:

# List sessions
cortex-mem-cli --config config.toml --tenant tenant_claw session list

# Generate missing layers
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

# Vector pruning
cortex-mem-cli --config config.toml --tenant tenant_claw vector prune

The CLI binary is automatically resolved from the platform-specific npm package (@memclaw/bin-darwin-arm64, @memclaw/bin-linux-x64, or @memclaw/bin-win-x64).

Security

All data stored locally — no external transmission
API keys handled through OpenClaw's sensitive field system (masked in UI)
Network binding — Qdrant and cortex-mem-service bind to localhost only
Ports used: 6333 (Qdrant HTTP), 6334 (Qdrant gRPC), 8085 (cortex-mem-service)

See SECURITY.md for details.

Project Structure

plugin/
├── index.ts                    # Plugin entry point (exports default + named plugin object)
├── plugin-impl.ts              # Core implementation: service lifecycle, 11 tools, config sync
├── package.json                # NPM package manifest (@memclaw/memclaw v0.9.36)
├── openclaw.plugin.json        # OpenClaw plugin manifest (id, kind, configSchema, uiHints)
├── tsconfig.json               # TypeScript config (ES2022, NodeNext, strict)
├── SECURITY.md                 # Security documentation
├── README.md                   # This file
├── README_zh.md                # Chinese documentation
│
├── src/
│   ├── client.ts               # HTTP client for cortex-mem-service REST API
│   ├── config.ts               # Config management: TOML parsing, plugin sync, validation
│   ├── binaries.ts             # Binary resolution & service management (Qdrant + service)
│   ├── migrate.ts              # OpenClaw native memory migration
│   └── agents-md-injector.ts   # AGENTS.md auto-enhancement with legacy pattern detection
│
├── skills/
│   ├── memclaw/
│   │   ├── SKILL.md            # Agent skill: daily memory operations
│   │   └── references/
│   │       ├── tools.md        # Complete tool parameter reference
│   │       ├── best-practices.md # Token optimization, tool selection, session management
│   │       ├── memory-structure.md # URI structure, three-layer architecture
│   │       └── security.md     # Security best practices
│   │
│   └── memclaw-maintance/
│       ├── SKILL.md            # Agent skill: installation & maintenance
│       └── references/
│           ├── tools.md        # Migration & maintenance tool reference
│           └── troubleshooting.md # Comprehensive troubleshooting guide
│
└── dist/                       # Compiled JavaScript output

License

MIT