Memclaw

Name: Memclaw
Rating: 3.5 (1 reviews)
Author: sopaco

By sopaco 👁 9 views ▲ 0 votes

The openclaw's memory context engine and plugin implementation of cortex memory

Homepage GitHub

Install

npm install @memclaw/memclaw`

Configuration Example

{
  "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"
        }
      }
    },
    "slots": {
      // Optional: if you want to use Context Engine instead
      // "contextEngine": "memclaw-context-engine"
    }
  },
  "agents": {
    "defaults": {
      "memorySearch": { "enabled": false }  // Disable OpenClaw built-in memory
    }
  }
}

README

<p align="center">
    <img src="./assets/intro_banner_glance.webp">
</p>
<h1 align="center">MemClaw</h1>

<p align="center">
    <a href="./README.md">English</a>
    |
    <a href="./README_zh.md">中文</a>
</p>

<p align="center">
    <a href="https://github.com/openclaw/openclaw"><img alt="OpenClaw Compatible" src="https://img.shields.io/badge/OpenClaw-compatible-brightgreen"/></a>
    <a href="https://raw.githubusercontent.com/sopaco/cortex-mem/refs/heads/main/assets/benchmark/cortex_mem_vs_openclaw_3.png?raw=true"><img alt="Benchmark" src="https://img.shields.io/badge/Benchmark-Perfect-green?logo=speedtest&labelColor=%231150af&color=%2300b89f"></a>
    <a href="https://github.com/sopaco/cortex-mem/tree/main/litho.docs/en"><img alt="Litho Docs" src="https://img.shields.io/badge/Litho-Docs-green?logo=Gitbook&color=%23008a60"/></a>
    <a href="https://github.com/sopaco/cortex-mem/tree/main/litho.docs/zh"><img alt="Litho Docs" src="https://img.shields.io/badge/Litho-中文-green?logo=Gitbook&color=%23008a60"/></a>
</p>

> **MemClaw** — A [Cortex Memory](https://github.com/sopaco/cortex-mem) enhancement suite for OpenClaw, providing production-grade L0/L1/L2 layered semantic memory with native Context Engine integration.

---

## TL;DR

MemClaw seamlessly integrates [Cortex Memory](https://github.com/sopaco/cortex-mem)'s three-tier memory architecture into [OpenClaw](https://docs.openclaw.ai/zh-CN), enabling AI Agents to **automatically remember the past, proactively recall relevant memories, and browse the complete memory space on demand** — all while achieving **up to 95% token savings** compared to OpenClaw's built-in memory solution.

| LoCoMo **#1** in memory recall capability | Slash token use by **90%** |
| :--- | :--- |
| ![Layered Context Loading](./assets/intro_overview.webp) | ![architecture_style_modern](./assets/intro_benchmark.webp) |

---

## Table of Contents

- [Why MemClaw](#why-memclaw)
- [Project Structure](#project-structure)
- [Core Features](#core-features)
- [Architecture Overview](#architecture-overview)
- [Three-Tier Memory Architecture](#three-tier-memory-architecture)
- [Quick Start](#quick-start)
  - [Install Memory Plugin](#install-memory-plugin)
  - [Install Context Engine](#install-context-engine)
- [Configuration Guide](#configuration-guide)
- [Available Tools](#available-tools)
- [Memory Plugin vs Context Engine — Which Should I Choose](#memory-plugin-vs-context-engine--which-should-i-choose)
- [Relationship with Other Projects](#relationship-with-other-projects)
- [Performance Benchmarks](#performance-benchmarks)
- [Troubleshooting](#troubleshooting)
- [FAQ](#faq)
- [License](#license)

---

## Why MemClaw

OpenClaw is a powerful AI Agent gateway, but its built-in memory solution has the following limitations:

| Issue | OpenClaw Built-in Memory | MemClaw Solution |
|-------|--------------------------|------------------|
| Token Consumption | Loads complete history every time, ~15,982 tokens/query | Layered loading, ~2,900 tokens/query |
| Memory Accuracy | 35.65% (LoCoMo10) | **68.42%** |
| Multi-hop Reasoning | Weak | **84.29%** (Cat 4) |
| Memory Organization | Flat list | L0/L1/L2 structured hierarchy |
| Context Management | Built-in fixed strategy | Pluggable Context Engine |

MemClaw solves these problems — transforming stateless Agents into intelligent assistants that can **remember user preferences, learn across sessions, and provide personalized interactions**.

---

## Project Structure

MemClaw consists of two independently installable OpenClaw plugins. Users can choose one or install both:

```
memclaw/
├── plugin/              # @memclaw/memclaw — Memory Plugin (passive memory storage)
│   ├── dist/            #   Build artifacts
│   ├── skills/          #   Agent skill files (tool usage guides, best practices)
│   ├── src/             #   Source code
│   ├── openclaw.plugin.json
│   └── README.md        #   Plugin detailed documentation
│
├── context-engine/      # @memclaw/context-engine — Context Engine (active context management)
│   ├── dist/            #   Build artifacts
│   ├── index.ts         #   Plugin entry point
│   ├── context-engine.ts #  Context Engine lifecycle implementation
│   ├── client.ts        #   Cortex Memory client
│   ├── tools.ts         #   Tool definitions
│   ├── config.ts        #   Configuration management
│   ├── binaries.ts      #   Binary service management
│   └── TECH_DESIGN.md   #   Technical design document
│
├── bin-darwin-arm64/    # macOS Apple Silicon pre-compiled binary package
│   └── bin/
│       ├── qdrant              # Qdrant vector database
│       └── cortex-mem-service  # Cortex Memory REST API service
│
├── bin-linux-x64/       # Linux x64 pre-compiled binary package (same structure)
├── bin-win-x64/         # Windows x64 pre-compiled binary package (same structure)
│
└── LICENSE
```

### What Does Each Directory Do?

| Directory | NPM Package Name | Type | Purpose |
|-----------|------------------|------|---------|
| `plugin/` | `@memclaw/memclaw` | Memory Plugin (`kind: "memory"`) | Provides memory tools, requires Agent to actively call them |
| `context-engine/` | `@memclaw/context-engine` | Context Engine (`kind: "context-engine"`) | Automatically manages context, lifecycle hook driven |
| `bin-*/` | `@memclaw/bin-*` | Pre-compiled binary distribution | Qdrant + cortex-mem-service ready to use out of the box |

---

## Core Features

### Provided by Both Plugins

- **Three-Tier Memory Architecture** — L0 abstract (~100 tokens) / L1 overview (~2000 tokens) / L2 full content, progressive disclosure
- **Semantic Vector Search** — Vector similarity retrieval based on Qdrant, supports multi-layer weighted scoring
- **Automatic Service Management** — Automatically starts Qdrant and cortex-mem-service when plugin launches, no manual ops required
- **One-Click Migration** — Seamlessly migrate from OpenClaw native memory to MemClaw
- **Cross-Platform** — Full coverage for Windows x64, macOS Apple Silicon, Linux x64
- **Zero External Dependency Installation** — Qdrant and cortex-mem-service are pre-compiled and packaged, works with `npm install`

### Memory Plugin (`plugin/`) Exclusive

- **Manual Tool-Driven** — Agent operates memory by calling tools like `cortex_search`, `cortex_add_memory`, `cortex_commit_session`, etc.
- **Fine-Grained Layer Control** — Each search can specify which layers (L0/L1/L2) to return
- **Memory Filesystem Browsing** — `cortex_ls` to browse `cortex://` URI space

### Context Engine (`context-engine/`) Exclusive

- **Fully Automatic Context Management** — No need for Agent to call tools, automatically recalls relevant memories before each model run
- **Automatic Message Capture** — Automatically writes each conversation turn to memory, triggers commit when threshold is reached
- **Smart Compression Takeover** — `ownsCompaction: true`, fully controls context compression strategy
- **Archive Expansion** — `cortex_archive_expand` tool to backtrack original conversations from compressed summaries
- **Bypass Mode** — Configure `bypassSessionPatterns` to disable engine for specific sessions

---

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────┐
│  OpenClaw Gateway                                            │
│                                                              │
│  ┌──────────────────┐    ┌──────────────────────────────┐   │
│  │  Memory Plugin   │    │   Context Engine             │   │
│  │  (@memclaw/      │    │   (@memclaw/                 │   │
│  │   memclaw)       │    │    context-engine)           │   │
│  │                  │    │                              │   │
│  │  • cortex_search │    │   • ingest()  ← message recv │   │
│  │  • cortex_recall │    │   • assemble() ← ctx assemble│   │
│  │  • cortex_add_*  │    │   • afterTurn() ← write+commit   │
│  │  • cortex_commit │    │   • compact() ← compress+extract  │
│  │  • cortex_ls     │    │                              │   │
│  │  • cortex_migrate│   │   + full toolset             │   │
│  └───────┬──────────┘    └──────────┬─────────────────┘   │
│          │                          │                      │
│          └──────────┬───────────────┘                      │
│                     ▼                                      │
│  ┌────────────────────────────────────────────────────┐    │
│  │  cortex-mem-service (HTTP REST API, port 8085)     │    │
│  │                                                     │    │
│  │  POST /api/v2/sessions           create session    │    │
│  │  POST /.../sessions/{id}/messages write message    │    │
│  │  POST /.../sessions/{id}/commit   commit+extract   │    │
│  │  GET  /.../sessions/{id}/context  get context      │    │
│  │  POST /api/v2/search              semantic search  │    │
│  │  GET  /api/v2/filesystem/*        virtual filesystem│   │
│  └──────────────────────┬─────────────────────────────┘    │
│                         │                                  │
│          ┌──────────────┴──────────────┐                   │
│          ▼                             ▼                   │
│  ┌───────────────┐          ┌────────────────────┐        │
│  │ Local FS      │          │  Qdrant Vector DB  │        │
│  │               │          │  (port 6333/6334)   │        │
│  │  session/     │          │                     │        │
│  │  user/        │          │  Vector index +     │        │
│  │  agent/       │          │  semantic retrieval │        │
│  │  resources/   │          │                     │        │
│  └───────────────┘          └────────────────────┘        │
│                                                            │
└────────────────────────────────────────────────────────────┘
```

---

## Three-Tier Memory Architecture

MemClaw's core innovation is the L0/L1/L2 three-tier memory system, mimicking the progressive process of human memory from "vague impression" to "clear recollection":

| Layer | Filen

... (truncated)

tools