Dev

README.md

@@ -13,7 +13,7 @@
 <p align="center">
     <strong>🧠 The AI-native memory framework for building intelligent, context-aware applications 🧠</strong>
 </p>
-<p align="center">Built with Rust, Cortex Memory is a high-performance, persistent, and intelligent long-term memory system that gives your AI agents the ability to remember, learn, and personalize interactions across sessions.</p>
+<p align="center">Built with Rust, Cortex Memory is a high-performance, persistent, and intelligent long-term memory system that gives your AI agents / OpenClaw the ability to remember, learn, and personalize interactions across sessions.</p>
 
 <p align="center">
     <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>
@@ -276,6 +276,52 @@ bun run dev
 
 The dashboard will be available at `http://localhost:5173` and will proxy API requests to the backend service.
 
+
+# 🦞 Community Showcase: MemClaw
+
+**MemClaw** is a deeply customized memory enhancement plugin for the OpenClaw ecosystem, powered by the locally-running Cortex Memory engine. It delivers superior memory capabilities compared to OpenClaw's built-in memory system, achieving **over 80% token savings** while maintaining exceptional memory accuracy, security, and performance.
+
+## Why MemClaw?
+
+| OpenClaw Native Memory | MemClaw |
+|------------------------|---------|
+| Basic memory storage | **Three-tier L0/L1/L2 architecture** for intelligent retrieval |
+| Higher token consumption | **80%+ token savings** with layered context loading |
+| Limited search precision | **Vector search + Agentic VFS exploration** for complex scenarios |
+
+## Key Features
+
+- **🎯 Low Token & Hardware Resource Usage**: Rust-powered high-performance memory components with progressive retrieval for optimal context loading
+- **🔒 Complete Data Privacy**: All memories stored locally with zero cloud dependency
+- **🚀 One-Click Migration**: Seamlessly migrate from OpenClaw native memory to MemClaw
+- **⚙️ Easy Configuration**: Zero runtime dependencies, one-line installation, minimal config to get started
+
+## Available Tools
+
+| Tool | Purpose |
+|------|---------|
+| `cortex_search` | Semantic search across all memories with tiered retrieval |
+| `cortex_recall` | Recall memories with extended context (snippet + full content) |
+| `cortex_add_memory` | Store messages for future retrieval |
+| `cortex_close_session` | Close session and trigger memory extraction pipeline |
+| `cortex_migrate` | One-click migration from OpenClaw native memory |
+| `cortex_maintenance` | Periodic maintenance (prune, reindex, layer generation) |
+
+## Quick Start
+
+```bash
+# Install via OpenClaw
+openclaw plugins install @memclaw/memclaw
+```
+
+> **Note**: Set `memorySearch.enabled: false` to disable OpenClaw's built-in memory and use MemClaw instead.
+
+## Documentation
+
+For detailed configuration, troubleshooting, and best practices, see the [MemClaw README](examples/@memclaw/plugin/README.md).
+
+---
+
 # 🌟 Community Showcase: Cortex TARS
 
 Meet **Cortex TARS** — a production-ready AI-native TUI (Terminal User Interface) application that demonstrates the true power of Cortex Memory. Built as a "second brain" companion, Cortex TARS brings **auditory presence** to your AI experience and can truly hear and remember your voice in the real world, showcases how persistent memory transforms AI interactions from fleeting chats into lasting, intelligent partnerships.

README_zh.md

@@ -13,7 +13,7 @@
 <p align="center">
     <strong>🧠 为构建智能、上下文感知应用而生的AI原生内存框架 🧠</strong>
 </p>
-<p align="center">基于Rust构建，Cortex Memory是一个高性能、持久化、智能的长期内存系统，赋予您的AI代理跨会话记住、学习和个性化交互的能力。</p>
+<p align="center">基于Rust构建，Cortex Memory是一个高性能、持久化、智能的长期内存系统，赋予您的OpenClaw等各类自主AI代理跨会话记住、学习和个性化交互的能力。</p>
 
 <p align="center">
     <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>
@@ -278,7 +278,52 @@ bun run dev
 
 仪表板将在`http://localhost:5173`上可用，并将API请求代理到后端服务。
 
-# 🌟 社区展示：Cortex TARS
+# 🦞 社区Showcase：MemClaw
+
+**MemClaw** 是一款为 OpenClaw 生态深度定制的记忆增强插件，由本地化运行的 Cortex Memory 引擎驱动。相比 OpenClaw 内置记忆系统，MemClaw 提供更强大的记忆能力，**节省超过 80% 的 token 消耗**，同时保持卓越的记忆准确性、安全性和性能。
+
+## 为什么选择 MemClaw？
+
+| OpenClaw 原生记忆 | MemClaw |
+|-------------------|---------|
+| 基础记忆存储 | **三层 L0/L1/L2 架构** 实现智能检索 |
+| 较高的 token 消耗 | **节省 80%+ token** 通过分层上下文加载 |
+| 搜索精度有限 | **向量搜索 + Agentic VFS探索** 灵活应对各类复杂场景 |
+
+## 核心特性
+
+- **🎯 低Token与硬件资源消耗**：由Rust驱动的极致高性能内存组件，渐进式检索架构实现最优上下文加载
+- **🔒 完全数据隐私**：所有记忆存储在本地，零云端存储依赖
+- **🚀 一键迁移**：从 OpenClaw 原生记忆无缝迁移到 MemClaw
+- **⚙️ 便捷配置**：零运行时依赖，一行命令全部搞定安装，只需最简化配置即可使用。
+
+## 可用工具
+
+| 工具 | 用途 |
+|------|------|
+| `cortex_search` | 跨所有记忆的语义搜索，支持分层检索 |
+| `cortex_recall` | 带扩展上下文的记忆召回（摘要 + 完整内容） |
+| `cortex_add_memory` | 存储消息以供后续检索 |
+| `cortex_close_session` | 关闭会话并触发记忆提取流程 |
+| `cortex_migrate` | 从 OpenClaw 原生记忆一键迁移 |
+| `cortex_maintenance` | 定期维护（清理、重建索引、层生成） |
+
+## 快速开始
+
+```bash
+# 通过 OpenClaw 安装
+openclaw plugins install @memclaw/memclaw
+```
+
+> **注意**：设置 `memorySearch.enabled: false` 以禁用 OpenClaw 内置记忆系统，改用 MemClaw。
+
+## 文档
+
+详细的配置说明、故障排查和最佳实践，请参阅 [MemClaw README](examples/@memclaw/plugin/README_zh.md)。
+
+---
+
+# 🌟 社区Showcase：Cortex TARS
 
 认识**Cortex TARS** - 一个生产就绪的AI原生TUI（终端用户界面）应用程序，展示了Cortex Memory的真正强大功能。作为"第二大脑"同伴构建，Cortex TARS为您的AI体验带来**听觉存在感**，可以在现实世界中真正听到并记住您的声音，展示了持久内存如何将AI交互从短暂的聊天转变为持久的、智能的伙伴关系。
 

examples/@memclaw/plugin/.gitignore

@@ -3,3 +3,4 @@ bun.lock
 pnpm.lock
 npm.lock
 yarn.lock
+skills/lagacy

examples/@memclaw/plugin/README.md

@@ -1,5 +1,7 @@
 # MemClaw
 
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
 Layered semantic memory plugin for OpenClaw with L0/L1/L2 tiered retrieval, automatic service management, and migration support from OpenClaw native memory.
 
 ## Overview
@@ -13,6 +15,7 @@ MemClaw is an OpenClaw plugin that provides advanced semantic memory capabilitie
 - **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 and macOS Apple Silicon
 
 ## Architecture
@@ -53,7 +56,7 @@ OpenClaw + MemClaw Plugin
 | Requirement | Details |
 |-------------|---------|
 | **Platforms** | Windows x64, macOS Apple Silicon |
-| **Node.js** | ≥ 22.0.0 |
+| **Node.js** | ≥ 20.0.0 |
 | **OpenClaw** | Installed and configured |
 
 ### Install Plugin
@@ -114,9 +117,11 @@ Then enable in `openclaw.json`:
 
 After making code changes, rebuild with `bun run build` and restart OpenClaw.
 
-### Configure OpenClaw
+## Configuration
+
+### Plugin Configuration
 
-Edit your `openclaw.json`:
+Configure MemClaw directly through OpenClaw plugin settings in `openclaw.json`:
 
 ```json
 {
@@ -127,7 +132,13 @@ Edit your `openclaw.json`:
         "config": {
           "serviceUrl": "http://localhost:8085",
           "tenantId": "tenant_claw",
-          "autoStartServices": true
+          "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"
         }
       }
     }
@@ -142,26 +153,33 @@ Edit your `openclaw.json`:
 
 > **Note**: Set `memorySearch.enabled: false` to disable OpenClaw's built-in memory search and use MemClaw instead.
 
-### Configure LLM
-
-On first run, MemClaw creates a configuration file:
-
-| Platform | Path |
-|----------|------|
-| Windows | `%APPDATA%\memclaw\config.toml` |
-| macOS | `~/Library/Application Support/memclaw/config.toml` |
+### Configuration Options
 
-Edit the configuration file and fill in required fields:
+| 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 |
 
-```toml
-[llm]
-api_key = "xxx"  # REQUIRED: Your LLM API key
+### Configuration via UI
 
-[embedding]
-api_key = "xxx"  # REQUIRED: Your embedding API key (can be same as llm.api_key)
-```
+You can also configure the plugin through OpenClaw UI:
 
-Then restart OpenClaw.
+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
 
@@ -214,42 +232,47 @@ Close a session and trigger memory extraction pipeline (takes 30-60 seconds).
 }
 ```
 
+> **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_migrate
 
 Migrate from OpenClaw native memory to MemClaw. Run once during initial setup.
 
-## Configuration Options
+### cortex_maintenance
 
-| 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) |
+Perform periodic maintenance on MemClaw data (prune, reindex, ensure-all layers).
 
 ## Quick Decision Flow
 
-1. **Need to find something** → `cortex_search`
-2. **Need more context** → `cortex_recall`
-3. **Save important information** → `cortex_add_memory`
-4. **Conversation complete** → `cortex_close_session`
-5. **First time setup** → `cortex_migrate`
+| Scenario | Tool |
+|----------|------|
+| Need to find information | `cortex_search` |
+| Need more context | `cortex_recall` |
+| Save important information | `cortex_add_memory` |
+| Complete a task/topic | `cortex_close_session` |
+| First-time use with existing memories | `cortex_migrate` |
+
+For detailed guidance on tool selection, session lifecycle, and best practices, see the [Skills Documentation](skills/memclaw/SKILL.md).
 
 ## Troubleshooting
 
+### Plugin Not Working
+
+1. **Check Configuration**: Open OpenClaw settings and verify MemClaw plugin configuration, especially LLM and Embedding settings
+2. **Restart OpenClaw Gateway**: Configuration changes require a gateway restart to take effect
+3. **Verify Services**: Run `cortex_list_sessions` to check if the service is responding
+
 ### Services Won't Start
 
 1. Check that ports 6333, 6334, 8085 are available
-2. Verify `api_key` fields are filled in config.toml
+2. Verify LLM and Embedding credentials are configured correctly
 3. Run `openclaw skills` to check plugin status
 
 ### Search Returns No Results
 
 1. Run `cortex_list_sessions` to verify sessions exist
 2. Lower `min_score` threshold (default: 0.6)
-3. Check service health with `cortex-mem-cli stats`
+3. Ensure memories have been stored (run `cortex_close_session` to extract memories)
 
 ### Migration Fails
 
@@ -271,6 +294,12 @@ cortex-mem-cli --config config.toml --tenant tenant_claw layers ensure-all
 cortex-mem-cli --config config.toml --tenant tenant_claw vector reindex
 ```
 
+## Documentation
+
+- **[Skills Documentation](skills/memclaw/SKILL.md)** — Agent skill guide with troubleshooting
+- **[Best Practices](skills/memclaw/references/best-practices.md)** — Tool selection, session lifecycle, search strategies
+- **[Tools Reference](skills/memclaw/references/tools.md)** — Detailed tool parameters and examples
+
 ## License
 
 MIT