OpenClaw Memory OS

v0.1.21

OpenClaw Memory-OS - Digital immortality service with conversation recording infrastructure (Phase 1) | 数字永生服务对话记录基础设施（第一阶段）

0· 584· 22 versions· 0 current· 0 all-time· Updated 11h ago· MIT-0

byJustin Liu@zhenstaff

Security Scans

VirusTotalSuspicious ClawScanSuspicious Static analysisBenign

Install

openclaw skills install openclaw-memory-os

OpenClaw Memory-OS

English | 中文

⚠️ CRITICAL PRIVACY & SECURITY NOTICE

READ THIS BEFORE INSTALLING OR ENABLING AUTO-TRIGGER

✅ Security Features (v0.3.0)

IMPLEMENTED:

✅ Confirmation Prompts - Always asks before saving (even with AUTO-TRIGGER)
✅ Privacy Filter Integrated - Automatically redacts sensitive data
- Detects and redacts: API keys, passwords, emails, credit cards, IP addresses, SSH keys
- Shows "[REDACTED]" for filtered content
- Displays filtering statistics
✅ Path Protection - Blocks dangerous directories by default
- Refuses to collect: ~/.ssh/, ~/.aws/, .env files, system credentials
- Requires --allow-dangerous flag + confirmation for sensitive paths
✅ 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 ~/.memory-os/
⚠️ Manual Bypass - Users can override protections with --allow-dangerous

✅ 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

# View package contents before installing
npm view openclaw-memory-os@0.3.0

# Check for postinstall scripts (should be none)
npm show openclaw-memory-os@0.3.0 scripts

# Download and inspect without installing
npm pack openclaw-memory-os@0.3.0
tar -xzf openclaw-memory-os-0.2.2.tgz
cat package/package.json

Step 2: Verify GitHub source matches npm package

# Clone verified commit
git clone https://github.com/ZhenRobotics/openclaw-memory-os.git
cd openclaw-memory-os
git checkout 091eeab814533d2e3ae1738693445d2de8b3ab4d

# Review critical files
cat src/cli/index.ts          # CLI entry point
cat src/conversation/privacy-filter.ts  # Privacy filter implementation (exists but not integrated)
cat src/storage/local-storage.ts        # Storage mechanism

Step 3: Test in isolated environment

# Use Docker for isolation
docker run -it --rm --network none node:18 bash
npm install -g openclaw-memory-os@0.3.0
openclaw-memory-os init
openclaw-memory-os remember "test data"

# Inspect what was created
ls -la ~/.memory-os/
cat ~/.memory-os/memories/*.json

Step 4: Monitor network activity

# In one terminal
sudo tcpdump -i any 'port 443 or port 80'

# In another terminal
openclaw-memory-os remember "test"
# Should see ZERO network traffic after installation

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):

You: "记住我的名字是刘小容"
     → Nothing happens (AUTO-TRIGGER is OFF)

To save, use manual command:
$ openclaw-memory-os remember "我的名字是刘小容"

How to Enable AUTO-TRIGGER (Optional):

# Method 1: Edit config
nano ~/.memory-os/config.json
{"auto_trigger": true}

# Method 2: During init (if implemented)
openclaw-memory-os init --enable-auto-trigger

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:

1. Agent autonomously decides to "remember" something
2. AUTO-TRIGGER detects keyword → saves immediately (no prompt)
3. Saved content may include API keys from agent's context
4. No confirmation, no filtering, plaintext storage

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:

Review collected data manually: cat ~/.memory-os/memories/*.json
Delete sensitive files: rm ~/.memory-os/memories/<uuid>.json
Avoid collecting directories with credentials

Planned: Automatic privacy filter integration in v0.3.0

Installation

Quick Start

# 1. Install
npm install -g openclaw-memory-os@0.3.0

# 2. Initialize
openclaw-memory-os init

# 3. Test (optional)
mkdir ~/test-memories
echo "Test note" > ~/test-memories/note.txt
openclaw-memory-os collect --source ~/test-memories/
openclaw-memory-os search "test"

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 - collect --source ~/notes/
✅ 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:

# Batch collect files
openclaw-memory-os collect --source ~/notes/ --exclude node_modules

# Save specific memory
openclaw-memory-os remember "项目截止日期：2026-04-01"

# Search memories
openclaw-memory-os search "deadline"

# View status
openclaw-memory-os status

AUTO-TRIGGER (Optional - Must Enable First)

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

nano ~/.memory-os/config.json
{"auto_trigger": true}

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

# VM/container test
docker run -it --rm ubuntu:22.04 bash
npm install -g openclaw-memory-os@0.3.0
openclaw-memory-os init
# Say trigger words and check ~/.memory-os/

2. Control Collection Scope

# ✅ Good: Specific directory
openclaw-memory-os collect --source ~/project-notes/

# ✅ Good: With exclusions
openclaw-memory-os collect --source ~/Documents/ --exclude sensitive

# ❌ Avoid: Broad scope
openclaw-memory-os collect --source ~/  # Too broad

3. Regular Data Review

# List all memories
ls ~/.memory-os/memories/

# Search for sensitive data
grep -r "password\|secret" ~/.memory-os/

# Delete unwanted data
rm ~/.memory-os/memories/<uuid>.json

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:

import { MemoryOS, MemoryType } from 'openclaw-memory-os';

const memory = new MemoryOS({ storePath: '~/.memory-os' });
await memory.init();

// Save memory
await memory.collect({
  type: MemoryType.TEXT,
  content: 'User prefers TypeScript',
  metadata: { tags: ['preference'], source: 'manual' }
});

// Search (local keyword matching)
const results = await memory.search({ query: 'TypeScript', limit: 5 });

// Timeline
const timeline = await memory.timeline({
  date: new Date('2024-03-01'),
  range: 'day'
});

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

OpenClaw Memory-OS (中文)

English | 中文

⚠️ 重要隐私与安全声明

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

✅ 安全特性（v0.3.0）

已实现：

✅ 确认提示 - 保存前始终询问（即使启用 AUTO-TRIGGER）
✅ 隐私过滤已集成 - 自动脱敏敏感数据
- 检测并脱敏：API 密钥、密码、邮箱、银行卡号、IP 地址、SSH 密钥
- 敏感内容显示为 "[REDACTED]"
- 显示过滤统计信息
✅ 路径保护 - 默认阻止危险目录
- 拒绝采集：~/.ssh/、~/.aws/、.env 文件、系统凭证
- 敏感路径需要 --allow-dangerous 标志 + 确认
✅ 安全模式 - 默认启用，强制执行所有安全特性

剩余风险：

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

✅ 安全使用建议

应该做：

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

不应该做：

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

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

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

什么是 AUTO-TRIGGER？

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

默认行为（安全）：

用户："记住我的名字是刘小容"
     → 无反应（AUTO-TRIGGER 已关闭）

如需保存，使用手动命令：
$ openclaw-memory-os remember "我的名字是刘小容"

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

# 方法 1: 编辑配置
nano ~/.memory-os/config.json
{"auto_trigger": true}

# 方法 2: 初始化时启用（如果已实现）
openclaw-memory-os init --enable-auto-trigger

启用后的隐私注意事项：

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

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

安装

# 1. 安装
npm install -g openclaw-memory-os@0.3.0

# 2. 初始化
openclaw-memory-os init

# 3. 测试
mkdir ~/test-memories
echo "测试笔记" > ~/test-memories/note.txt
openclaw-memory-os collect --source ~/test-memories/
openclaw-memory-os search "测试"

核心功能

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

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

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

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

使用方式

手动命令（默认 - 推荐）

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

# 批量采集文件
openclaw-memory-os collect --source ~/notes/ --exclude node_modules

# 保存特定记忆
openclaw-memory-os remember "项目截止日期：2026-04-01"

# 搜索记忆
openclaw-memory-os search "截止"

# 查看状态
openclaw-memory-os status

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

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

nano ~/.memory-os/config.json
{"auto_trigger": true}

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

中文：记住、保存、记录
英文：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. 先在沙盒中测试

docker run -it --rm ubuntu:22.04 bash
npm install -g openclaw-memory-os@0.3.0
openclaw-memory-os init
# 说触发词并检查 ~/.memory-os/

2. 控制采集范围

# ✅ 推荐：特定目录
openclaw-memory-os collect --source ~/project-notes/

# ❌ 避免：过于广泛
openclaw-memory-os collect --source ~/  # 范围太大

3. 定期数据审查

# 列出所有记忆
ls ~/.memory-os/memories/

# 搜索敏感数据
grep -r "密码\|secret" ~/.memory-os/

# 删除不需要的数据
rm ~/.memory-os/memories/<uuid>.json

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

License: MIT-0 · Memory-OS v0.2.2 - 100% Local, 0% Cloud, Your Data, Your Control

Version tags

latestvk97dt99n68cqrm52ec0ybdnwdn83x7jz