OpenClaw Memory OS

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

Security Scan

The skill's instructions ask you to globally install and run an external npm package that has filesystem-wide collection capabilities, but the SKILL.md, readme, and registry metadata contain contradictory statements about required binaries and implemented security features — proceed with caution and audit the npm package before installing.

Purpose & Capability

The stated purpose (local conversation-memory storage) reasonably requires a CLI/runtime (Node/npm) and local storage under ~/.memory-os. However the registry metadata above lists no required binaries while SKILL.md explicitly requires Node.js >=18 and npm and a global npm install; this mismatch is incoherent and should be clarified.

Instruction Scope

SKILL.md instructs installing an external npm package and running a CLI that can scan arbitrary filesystem paths and create ~/.memory-os/. That capability is consistent with the skill's goal but the documentation contains conflicting claims about privacy protections: SKILL.md claims confirmation prompts, privacy filter, and path protection in v0.3.0, while the included readme documents older behavior (v0.2.2) where auto-trigger saved immediately and the privacy filter was not integrated. If you install the package version that lacks these safeguards, the CLI could collect sensitive files. The skill also includes keywords for auto-triggering saves — enabling that autonomously would broaden its access to the user's conversation/content.

Install Mechanism

There is no embedded code in the skill bundle; SKILL.md directs a global npm install (npmjs.com). Installing an npm package globally is a common delivery method but executes third-party code and modifies system PATH (moderate risk). The install guidance even explicitly warns about code execution and recommends inspecting the package first, which is good practice.

Credentials

The skill does not request environment variables, credentials, or config paths beyond suggesting it will create and use ~/.memory-os/. No extraneous secrets are requested in the metadata. That is proportionate to a local-memory tool, but because the CLI can scan user directories, filesystem access is the primary sensitive capability.

Persistence & Privilege

always:false and no special platform privileges are requested. The only persistent effect is installing a global CLI binary and creating ~/.memory-os/. This is expected for a CLI tool, but combined with autonomous invocation (platform default) and the ability to enable AUTO-TRIGGER, it could lead to repeated/automatic collection if the installed package implements that feature without safeguards.

Scan Findings in Context

[none_detected] expected: No regex-based findings because the skill bundle contains only documentation and no code files. Absence of findings is not proof of safety — the SKILL.md instructs installing an external npm package which was not analyzed here.

What to consider before installing

Do not install blindly. Because this skill only provides instructions to install an external npm package (which will execute third-party code and can scan your filesystem), audit the package before installing: use npm pack to inspect its contents, check package.json for postinstall scripts and the exact published version, review the repository at the verified commit referenced in the SKILL.md (confirm which commit is authoritative), and run the CLI in an isolated VM or container with network disabled first. Never enable AUTO-TRIGGER or run broad collection commands (e.g., collect --source ~/) until you confirm the installed version actually implements the path protections, confirmation prompts, and privacy filter it claims. If you lack the ability to fully audit, prefer not to install globally; instead run in a throwaway VM or avoid enabling autonomous agent invocation.

English | 中文

⚠️ CRITICAL PRIVACY & SECURITY NOTICE

READ THIS BEFORE INSTALLING OR ENABLING AUTO-TRIGGER

✅ Security Features (v0.3.0)

IMPLEMENTED:

1. ✅ Confirmation Prompts - Always asks before saving (even with AUTO-TRIGGER)
2. ✅ 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
3. ✅ Path Protection - Blocks dangerous directories by default
   • Refuses to collect: ~/.ssh/, ~/.aws/, .env files, system credentials
   • Requires --allow-dangerous flag + confirmation for sensitive paths
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 ~/.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:

1. Review collected data manually: cat ~/.memory-os/memories/*.json
2. Delete sensitive files: rm ~/.memory-os/memories/<uuid>.json
3. 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

---

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

剩余风险：

• ⚠️ 无静态加密 - 数据以明文 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