openclaw-memory-os

name	openclaw-memory-os
description	OpenClaw Memory-OS - Digital immortality service with conversation recording infrastructure (Phase 1) | 数字永生服务对话记录基础设施（第一阶段）
tags	["memory","knowledge-management","digital-immortality","cognitive-continuity","ai-memory","conversation-storage","session-management","privacy-filter","agent-memory","long-term-memory","openclaw","infrastructure","security","privacy-first"]
version	0.3.0
license	MIT-0
repository	https://github.com/ZhenRobotics/openclaw-memory-os
homepage	https://github.com/ZhenRobotics/openclaw-memory-os
documentation	https://github.com/ZhenRobotics/openclaw-memory-os/blob/main/README.md
runtime_dependencies	{"required_binaries":["node","npm"],"system_requirements":["Node.js >=18.0.0 (NOT optional - required for execution)","npm package manager (required for installation)","~50MB disk space for package and dependencies","Write permissions for ~/.memory-os/"]}
install	{"type":"npm_package","mechanism":"global_npm_install","steps":[{"command":"npm install -g openclaw-memory-os@0.3.0","description":"Install the Memory-OS CLI globally (creates system binary)","network_required":true},{"command":"openclaw-memory-os init","description":"Initialize local storage at ~/.memory-os/","creates_files":true}],"security_notes":["npm install executes code from npmjs.com registry","Global install creates binaries in system PATH","Verify package before installing (see audit section below)"]}
requires	{"packages":[{"name":"openclaw-memory-os","source":"npm","version":">=0.3.0","verified_repo":"https://github.com/ZhenRobotics/openclaw-memory-os","verified_commit":"9254fcab35308b82ce55d3f23e297d44b7021977"}],"tools":["node>=18","npm"],"api_keys":[]}
security	{"data_storage":"local_only","network_calls":"none_at_runtime","external_apis":"none","auto_collection":"trigger_based","trigger_keywords":["记住","保存","记录","remember","save to memory","keep in mind"],"default_enabled":false,"confirmation_required":true,"privacy_filter":"integrated","path_protection":"enforced","safe_mode":true,"opt_in":"configurable","encryption":"optional"}

OpenClaw Memory-OS

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