Tools
Memclaw
By The openclaw's memory context engine and plugin implementation of cortex memory
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%** |
| :--- | :--- |
|  |  |
---
## 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
Comments
Sign in to leave a comment