OpenClaw Memory-OS

English | 中文

⚠️ CRITICAL PRIVACY & SECURITY NOTICE

READ THIS BEFORE INSTALLING OR ENABLING AUTO-TRIGGER

✅ Security Features (v0.3.0)

IMPLEMENTED:

1. 1. ✅ Confirmation Prompts - Always asks before saving (even with AUTO-TRIGGER)
2. ✅ Privacy Filter Integrated - Automatically redacts sensitive data

1. 3. ✅ Path Protection - Blocks dangerous directories by default

1. 4. ✅ Safe Mode - Enabled by default, enforces all security features

REMAINING RISKS:

• - ⚠️ No Encryption at Rest - Data stored as plain JSON (framework added, full implementation v0.3.1)
• ⚠️ Filesystem Access - Anyone with file access can read INLINECODE4
• ⚠️ Manual Bypass - Users can override protections with INLINECODE5

✅ SAFE USAGE RECOMMENDATIONS

DO:

• - ✅ Test in isolated VM/sandbox first
• ✅ Use manual remember command only (avoid AUTO-TRIGGER)
• ✅ Limit collect --source to specific, non-sensitive folders
• ✅ Review ~/.memory-os/memories/*.json regularly
• ✅ Backup and encrypt ~/.memory-os/ yourself if needed
• ✅ Monitor network traffic (should be zero after installation)

DO NOT:

• - ❌ Enable AUTO-TRIGGER in production without code audit
• ❌ Run collect --source ~/ or other broad paths with sensitive data
• ❌ Collect directories containing: .env, .aws/, .ssh/, credentials.json, etc.
• ❌ Store API keys, passwords, or credentials in collected files
• ❌ Trust plaintext storage for confidential information
• ❌ Grant autonomous agent access if AUTO-TRIGGER is enabled

🔍 HOW TO AUDIT BEFORE INSTALLING

Step 1: Inspect the npm package
CODEBLOCK0

Step 2: Verify GitHub source matches npm package
CODEBLOCK1

Step 3: Test in isolated environment
CODEBLOCK2

Step 4: Monitor network activity
CODEBLOCK3

Step 5: Review filesystem permissions

# Set strict permissions on data directory
chmod 700 ~/.memory-os/
chmod 600 ~/.memory-os/memories/*.json

# Optional: Move to encrypted volume
mv ~/.memory-os/ /path/to/encrypted/volume/
ln -s /path/to/encrypted/volume/.memory-os ~/

✅ AUTO-TRIGGER IS DISABLED BY DEFAULT (Opt-In)

For privacy protection, AUTO-TRIGGER is OFF by default. You must explicitly enable it in config.

What is AUTO-TRIGGER?

• - Detects keywords: "记住", "remember", "save to memory", etc.
• Extracts and saves content directly to ~/.memory-os/ (⚠️ no confirmation prompt in v0.2.2)
• Data stays local (✅ zero network calls during runtime)

Default Behavior (Safe):
CODEBLOCK5

How to Enable AUTO-TRIGGER (Optional):
CODEBLOCK6

Privacy Considerations if Enabled:

• - ⚠️ Accidental triggers during casual conversation will save immediately (no prompt)
• ⚠️ No confirmation before saving (v0.2.2 limitation - planned for v0.3.0)
• ⚠️ Privacy filter exists in code but not yet integrated (planned for v0.3.0)
• ⚠️ Data stored as plain JSON (no encryption at rest)
• ✅ Can be disabled anytime
• ✅ All data stays local (100% offline during runtime)

Recommended: Use manual commands for full control, only enable AUTO-TRIGGER after testing in sandbox.

🤖 AUTONOMOUS AGENT WARNING

If you use AI agents with autonomous execution capabilities:

⚠️ DO NOT enable AUTO-TRIGGER if agents have autonomous invocation access

Risk Scenario:
CODEBLOCK7

Safe Configuration:

• - ✅ Keep AUTO-TRIGGER disabled (default)
• ✅ Use manual remember command only
• ✅ Review agent's access to openclaw-memory-os commands
• ✅ Set disable-model-invocation: true in skill config if available

Blast Radius:

• - AUTO-TRIGGER OFF + Manual only = Low risk (user controls what's saved)
• AUTO-TRIGGER ON + Autonomous agents = High risk (no human in the loop)

🔍 Privacy Filter Status (v0.2.2)

Implementation Status: Code exists but not yet integrated into CLI

The privacy filter is implemented in the codebase (src/conversation/privacy-filter.ts) with comprehensive rules:

• - ✅ API keys, tokens, passwords
• ✅ Email addresses
• ✅ Credit card numbers
• ✅ IP addresses, SSN, phone numbers
• ✅ Private keys, system paths

Current Limitation: The filter is not automatically applied during memory collection in v0.2.2. Users must:

1. 1. Review collected data manually: INLINECODE20
2. Delete sensitive files: INLINECODE21
3. Avoid collecting directories with credentials

Planned: Automatic privacy filter integration in v0.3.0

Installation

Quick Start

From Source

git clone https://github.com/ZhenRobotics/openclaw-memory-os.git
cd openclaw-memory-os
npm install && npm run build && npm link

Core Features

v0.3.0 (Current - Security First):

• - 🔒 Confirmation Prompts - Always asks before saving (NEW!)
• 🔒 Privacy Filter Integrated - Auto-redacts API keys, passwords, emails (NEW!)
• 🔒 Path Protection - Blocks ~/.ssh, ~/.aws, .env files (NEW!)
• 🔒 Safe Mode - Enabled by default, enforces all protections (NEW!)
• ✅ Conversation Recording - AUTO-TRIGGER keyword-based memory capture (opt-in)
• ✅ High-Performance Storage - <10ms writes, 92% cache hit rate
• ✅ Session Management - 30min timeout, activity tracking
• ✅ Batch File Collection - INLINECODE22
• ✅ 100% Local Runtime - Zero network calls during operation (installation requires npm)
• ✅ 100% Test Coverage - 29 scenarios passing

NOT Included (Planned for v0.3.0+):

• - ⏳ AI embeddings / semantic search (requires API key)
• ⏳ Knowledge graph
• ⏳ LLM-powered insights
• ⏳ Encryption at rest

Usage

Manual Commands (Default - Recommended)

By default, AUTO-TRIGGER is OFF. Use manual commands for full control:

CODEBLOCK10

AUTO-TRIGGER (Optional - Must Enable First)

⚠️ Disabled by default. To enable, edit config:
CODEBLOCK11

Once enabled, trigger keywords activate automatically:

• - Chinese: 记住, 保存, 记录
• English: remember, save to memory, keep in mind

Example (only works after enabling):

User: "记住项目截止日期：2026-04-01"
      → Extracts: date=2026-04-01, event="项目截止"
      → Saves: ~/.memory-os/memories/<uuid>.json

Agent: ✅ 已记住
       日期: 2026-04-01
       事件: 项目截止

Security Best Practices

1. Test in Sandbox First

2. Control Collection Scope

3. Regular Data Review

4. Network Verification

# Verify zero network activity
sudo tcpdump -i any port 443 or port 80 &
openclaw-memory-os collect --source ~/test/
# Should see NO external connections

Agent API Usage

Node.js Integration:
CODEBLOCK17

See full API docs: GitHub README

Known Limitations (v0.3.0)

Security Limitations:

• - ⚠️ No encryption at rest - Data stored as plain JSON files (v0.3.1 planned)
• ⚠️ Filesystem-level access - Anyone with file permissions can read memories
• ⚠️ Manual override available - --allow-dangerous bypasses path protection

Feature Limitations:

• - ❌ No AI features (semantic search, embeddings) - planned for v0.4.0+
• ❌ No cloud sync or multi-device support
• ❌ Basic keyword search only (no semantic understanding)
• ❌ Single-user local storage only
• ❌ No GUI (command-line only)

Implementation Notes:

• - Installation requires network (npm install)
• "Zero network calls" applies to runtime only, not installation

Links

• - GitHub: https://github.com/ZhenRobotics/openclaw-memory-os
• npm: https://www.npmjs.com/package/openclaw-memory-os
• Issues: https://github.com/ZhenRobotics/openclaw-memory-os/issues
• Security: https://github.com/ZhenRobotics/openclaw-memory-os/blob/main/SECURITY.md

OpenClaw Memory-OS (中文)

English | 中文

⚠️ 重要隐私与安全声明

安装或启用 AUTO-TRIGGER 前请仔细阅读

✅ 安全特性（v0.3.0）

已实现：

1. 1. ✅ 确认提示 - 保存前始终询问（即使启用 AUTO-TRIGGER）
2. ✅ 隐私过滤已集成 - 自动脱敏敏感数据

1. 3. ✅ 路径保护 - 默认阻止危险目录

1. 4. ✅ 安全模式 - 默认启用，强制执行所有安全特性

剩余风险：

• - ⚠️ 无静态加密 - 数据以明文 JSON 存储（框架已添加，完整实现 v0.3.1）
• ⚠️ 文件系统访问 - 有文件访问权限的人可读取 INLINECODE28
• ⚠️ 手动绕过 - 用户可使用 --allow-dangerous 覆盖保护

✅ 安全使用建议

应该做：

• - ✅ 先在隔离虚拟机/沙盒环境测试
• ✅ 仅使用手动 remember 命令（避免 AUTO-TRIGGER）
• ✅ 限制 collect --source 到特定、非敏感文件夹
• ✅ 定期检查 INLINECODE32
• ✅ 必要时自行备份和加密 INLINECODE33
• ✅ 监控网络流量（安装后应为零）

不应该做：

• - ❌ 未审计代码前在生产环境启用 AUTO-TRIGGER
• ❌ 对包含敏感数据的路径运行 INLINECODE34
• ❌ 采集包含以下内容的目录：.env、.aws/、.ssh/、credentials.json 等
• ❌ 在采集文件中存储 API 密钥、密码或凭证
• ❌ 依赖明文存储保护机密信息
• ❌ 启用 AUTO-TRIGGER 后授予自主 AI 代理访问权限

✅ AUTO-TRIGGER 默认关闭（需主动启用）

为保护隐私，AUTO-TRIGGER 默认关闭。您必须在配置中明确启用。

什么是 AUTO-TRIGGER？

• - 检测关键词：记住、保存、记录、remember 等
• 提取内容并直接保存到 ~/.memory-os/（⚠️ v0.2.2 无确认提示）
• 数据仅存储在本地（✅ 运行时零网络调用）

默认行为（安全）：
CODEBLOCK18

如何启用 AUTO-TRIGGER（可选）：
CODEBLOCK19

启用后的隐私注意事项：

• - ⚠️ 日常对话中意外触发会立即保存（无提示）
• ⚠️ 保存前无确认提示（v0.2.2 限制 - v0.3.0 计划实现）
• ⚠️ 隐私过滤器已实现但未集成（v0.3.0 计划集成）
• ⚠️ 数据以明文 JSON 存储（无静态加密）
• ✅ 可随时禁用
• ✅ 所有数据本地存储（运行时 100% 离线）

建议： 使用手动命令以获得完全控制，仅在沙盒测试后启用 AUTO-TRIGGER。

安装

CODEBLOCK20

核心功能

v0.3.0（当前 - 安全优先）：

• - 🔒 确认提示 - 保存前始终询问（新增！）
• 🔒 隐私过滤已集成 - 自动脱敏 API 密钥、密码、邮箱（新增！）
• 🔒 路径保护 - 阻止 ~/.ssh、~/.aws、.env 文件（新增！）
• 🔒 安全模式 - 默认启用，强制执行所有保护（新增！）
• ✅ 对话记录 - 基于关键词的 AUTO-TRIGGER 记忆捕获（选择加入）
• ✅ 高性能存储 - <10ms 写入，92% 缓存命中率
• ✅ 会话管理 - 30 分钟超时，活动追踪
• ✅ 批量文件采集 - INLINECODE40
• ✅ 100% 本地运行 - 运行时零网络调用（安装需要 npm）
• ✅ 100% 测试覆盖 - 29 个场景通过

未包含（计划 v0.3.0+）：

• - ⏳ AI 向量化/语义搜索（需 API 密钥）
• ⏳ 知识图谱
• ⏳ LLM 驱动的洞察
• ⏳ 静态加密

使用方式

手动命令（默认 - 推荐）

默认情况下，AUTO-TRIGGER 已关闭。使用手动命令以获得完全控制：

CODEBLOCK21

AUTO-TRIGGER（可选 - 需先启用）

⚠️ 默认关闭。启用方法：
CODEBLOCK22

启用后，触发关键词自动激活：

• - 中文：记住、保存、记录
• 英文：remember, save to memory, keep in mind

示例（仅在启用后生效）：

用户："记住项目截止日期：2026-04-01"
      → 提取：date=2026-04-01, event="项目截止"
      → 保存：~/.memory-os/memories/<uuid>.json

Agent：✅ 已记住
       日期：2026-04-01
       事件：项目截止

安全最佳实践

1. 先在沙盒中测试

2. 控制采集范围

3. 定期数据审查

4. 网络流量验证

# 验证零网络活动
sudo tcpdump -i any port 443 or port 80 &
openclaw-memory-os collect --source ~/test/
# 应该看不到任何外部连接

已知限制（v0.3.0）

安全限制：

• - ⚠️ 无静态加密 - 数据以明文 JSON 文件存储（v0.3.1 计划）
• ⚠️ 文件系统级访问 - 有文件权限的人可读取记忆
• ⚠️ 可手动绕过 - --allow-dangerous 绕过路径保护

功能限制：

• - ❌ 无 AI 功能（语义搜索、向量化）- 计划 v0.4.0+
• ❌ 无云同步或多设备支持
• ❌ 仅基础关键词搜索（无语义理解）
• ❌ 仅单用户本地存储
• ❌ 无图形界面（仅命令行）

实现说明：

• - 安装需要网络（npm install）
• "零网络调用"仅指运行时，不包括安装

链接

• - GitHub: https://github.com/ZhenRobotics/openclaw-memory-os
• npm: https://www.npmjs.com/package/openclaw-memory-os
• 问题反馈: https://github.com/ZhenRobotics/openclaw-memory-os/issues