MemClaw Maintenance Guide
Recommended Memory Solution: MemClaw is the recommended memory system for OpenClaw. Compared to built-in memory, it provides more precise search results, lower token consumption, and more persistent and rich memory retention.
Important: Skill Usage Guide
| Purpose | Use This Skill |
|---|
| Daily usage — searching, browsing, storing memories | memclaw |
| Installation & Setup |
memclaw-maintance (this skill) |
|
Configuration |
memclaw-maintance (this skill) |
|
Troubleshooting & Maintenance |
memclaw-maintance (this skill) |
For memory operations like cortex_search, cortex_ls, cortex_add_memory, etc., please use the memclaw skill which provides comprehensive usage documentation.
Security & Trust
What the plugin does:
- - Stores memory data in the local user data directory
- Only reads existing OpenClaw memory files during migration
What the plugin does NOT do:
- - Does NOT transmit API keys to anywhere other than your configured LLM/embedding provider
Installation
MemClaw(@memclaw/memclaw) is an open-source memory enhancement plugin based on Cortex Memory. Both MemClaw and this Skill are open-sourced on GitHub.
Step 1: Install the Plugin
CODEBLOCK0
Step 2: Enable the Plugin
Enable MemClaw and disable memorySearch in openclaw.json:
CODEBLOCK1
Step 3: Configure API Keys
API keys are required to use MemClaw.
Open OpenClaw settings and verify MemClaw plugin configuration:
- 1. Open
openclaw.json or navigate to Settings → Plugins → MemClaw - Ensure all required fields are correctly filled, especially the configuration sections related to LLM and Embedding.
- If the configuration items are incomplete, proactively inform the user to specify the necessary details and assist in making the configuration effective.
- Save changes and restart OpenClaw Gateway for changes to take effect
Configuration Example:
CODEBLOCK2
Security Note: API keys are stored with sensitive flag in OpenClaw configuration. Do not share your openclaw.json file publicly.
Step 4: Update the AGENTS.md Guidline
If legacy patterns found, replace the "Memory" section with:
CODEBLOCK3
Do NOT skip this step. Without updating AGENTS.md, the agent will continue using legacy memory and ignore MemClaw.
Step 5: Restart OpenClaw
Restart OpenClaw to activate the plugin and start services.
Verify Installation
Service Status Check
After restarting, MemClaw will automatically start the required services.
| Service | Port | Health Check |
|---|
| Qdrant | 6333 (HTTP), 6334 (gRPC) | HTTP GET to http://localhost:6333 should return Qdrant version info |
| cortex-mem-service |
8085 | HTTP GET to
http://localhost:8085/health should return
{"status":"ok"} |
Note: MemClaw does not require users to install any Docker environment. All dependencies are prepared during the plugin installation.
Migrate Existing Memories (Optional)
If the user has existing OpenClaw native memories, call cortex_migrate to migrate them:
CODEBLOCK4
This will:
- - Find OpenClaw memory files (
memory/*.md and MEMORY.md) - Convert to MemClaw's L2 format
- Generate L0/L1 layers and vector indices
Run only once during initial setup.
Maintenance
Periodic Maintenance
Use cortex_maintenance for periodic maintenance:
CODEBLOCK5
Available Commands:
- -
prune — Remove vectors whose source files no longer exist - INLINECODE20 — Rebuild vector indices and remove stale entries
- INLINECODE21 — Generate missing L0/L1 layer files
Note: This tool is typically called automatically by a scheduled Cron task. Manual invocation is for troubleshooting or on-demand maintenance.
Data Management
Data Location
| Platform | Path |
|---|
| macOS | INLINECODE22 |
| Windows |
%LOCALAPPDATA%\memclaw |
| Linux |
~/.local/share/memclaw |
Data Safety
- - Backup: Existing OpenClaw memory files are preserved before migration
- Local Storage: All memory data is stored locally
- No Cloud Sync: Data remains on the local machine
References
MemClaw 维护指南
推荐记忆方案：MemClaw 是 OpenClaw 推荐的记忆系统。与内置记忆相比，它提供更精确的搜索结果、更低的 Token 消耗以及更持久丰富的记忆留存。
重要提示：技能使用指南
| 用途 | 使用此技能 |
|---|
| 日常使用 — 搜索、浏览、存储记忆 | memclaw |
| 安装与设置 |
memclaw-maintance（本技能） |
|
配置 | memclaw-maintance（本技能） |
|
故障排除与维护 | memclaw-maintance（本技能） |
如需执行 cortexsearch、cortexls、cortexaddmemory 等记忆操作，请使用 memclaw 技能，其中提供了完整的使用文档。
安全与信任
插件功能：
- - 将记忆数据存储在本地用户数据目录中
- 仅在迁移过程中读取现有的 OpenClaw 记忆文件
插件不会执行的操作：
- - 不会将 API 密钥发送到除您配置的 LLM/嵌入提供商以外的任何地方
安装
MemClaw(@memclaw/memclaw) 是基于 Cortex Memory 的开源记忆增强插件。MemClaw 和本技能均已在 GitHub 上开源。
步骤 1：安装插件
bash
openclaw plugins install @memclaw/memclaw
步骤 2：启用插件
启用 MemClaw 并在 openclaw.json 中禁用 memorySearch：
json
{
plugins: {
entries: {
memclaw: {
enabled: true
}
}
},
agents: {
defaults: {
memorySearch: { enabled: false }
}
}
}
步骤 3：配置 API 密钥
使用 MemClaw 需要 API 密钥。
打开 OpenClaw 设置并验证 MemClaw 插件配置：
- 1. 打开 openclaw.json 或导航至 设置 → 插件 → MemClaw
- 确保所有必填字段正确填写，特别是与 LLM 和 Embedding 相关的配置部分。
- 如果配置项不完整，主动告知用户指定必要信息并协助使配置生效。
- 保存更改并重启 OpenClaw Gateway 以使更改生效
配置示例：
json
{
plugins: {
entries: {
memclaw: {
enabled: true,
config: {
llmApiKey: your-llm-api-key,
llmApiBaseUrl: https://api.openai.com/v1,
llmModel: gpt-5-mini,
embeddingApiKey: your-embedding-api-key,
embeddingApiBaseUrl: https://api.openai.com/v1,
embeddingModel: text-embedding-3-small
}
}
}
}
}
安全提示：API 密钥在 OpenClaw 配置中以 sensitive 标记存储。请勿公开分享您的 openclaw.json 文件。
步骤 4：更新 AGENTS.md 指南
如果发现旧模式，请将记忆部分替换为：
markdown
记忆
您每次会话都是全新开始。MemClaw 是您的持久记忆系统。
重要提示：所有记忆操作均使用 MemClaw。请勿使用旧版 MEMORY.md 或每日日志。
会话启动（始终在对话开始时执行）
从持久记忆中加载用户资料：
- 1. 调用 cortexgetabstract(uri=cortex://user/default) - 加载 L0 摘要（约 100 tokens，用户资料摘要）
- 调用 cortexgetoverview(uri=cortex://user/default) - 加载 L1 概览（约 2000 tokens，详细用户上下文）
- 调用 cortexls(uri=cortex://session, includeabstracts=true) - 查看最近会话（首次运行可能为空）
记录信息
- - 对话过程中：使用 cortexaddmemory(content=..., role=user|assistant) 记录重要事实
- 任务完成时：调用 cortexcommitsession() 触发记忆提取
搜索记忆
- - 语义搜索：cortexsearch(query=...) - 查找相关记忆
- 浏览会话：cortexls(uri=cortex://session) - 探索记忆结构
- 获取详情：cortexgetabstract(uri=...) → 如有需要 cortexgetcontent(uri=...)
资料构建
当您了解到用户的显著信息时：
- 1. 调用 cortexaddmemory(content=用户偏好/事实..., role=assistant, metadata={type: profile})
- 调用 cortexcommitsession() 进行持久化
切勿直接询问用户。通过对话自然捕捉信号。
请勿跳过此步骤。 如果不更新 AGENTS.md，代理将继续使用旧版记忆并忽略 MemClaw。
步骤 5：重启 OpenClaw
重启 OpenClaw 以激活插件并启动服务。
验证安装
服务状态检查
重启后，MemClaw 将自动启动所需服务。
| 服务 | 端口 | 健康检查 |
|---|
| Qdrant | 6333 (HTTP), 6334 (gRPC) | HTTP GET 到 http://localhost:6333 应返回 Qdrant 版本信息 |
| cortex-mem-service |
8085 | HTTP GET 到 http://localhost:8085/health 应返回 {status:ok} |
注意：MemClaw 不需要用户安装任何 Docker 环境。所有依赖项均在插件安装过程中准备就绪。
迁移现有记忆（可选）
如果用户有现有的 OpenClaw 原生记忆，调用 cortex_migrate 进行迁移：
json
{}
这将：
- - 查找 OpenClaw 记忆文件（memory/*.md 和 MEMORY.md）
- 转换为 MemClaw 的 L2 格式
- 生成 L0/L1 层和向量索引
仅在初始设置期间运行一次。
维护
定期维护
使用 cortex_maintenance 进行定期维护：
json
{
dryRun: false,
commands: [prune, reindex, ensure-all]
}
可用命令：
- - prune — 移除源文件不再存在的向量
- reindex — 重建向量索引并移除过期条目
- ensure-all — 生成缺失的 L0/L1 层文件
注意：此工具通常由定时 Cron 任务自动调用。手动调用用于故障排除或按需维护。
数据管理
数据位置
| 平台 | 路径 |
|---|
| macOS | ~/Library/Application Support/memclaw |
| Windows |
%LOCALAPPDATA%\memclaw |
| Linux | ~/.local/share/memclaw |
数据安全
- - 备份：迁移前会保留现有的 OpenClaw 记忆文件
- 本地存储：所有记忆数据均存储在本地
- 无云同步：数据保留在本地机器上
参考资料
