Skill: zhenstaff/openclaw-memory-os (version 0.1.21)

--- 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 # v0.2.0 Phase 1 - Conversation Recording Foundation # ⚠️ CRITICAL: This is NOT an instruction-only skill # This skill REQUIRES external binaries and package installation runtime_dependencies: required_binaries: [node, npm] # Must have Node.js >=18 and npm installed 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 # Downloads and installs executable binary 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 # REQUIRED - not optional - npm # REQUIRED - not optional api_keys: [] # No API keys needed after installation # Security & Privacy Declaration security: data_storage: local_only network_calls: none_at_runtime # Zero network calls during operation (installation requires npm/git) external_apis: none auto_collection: trigger_based # Activates on keyword detection when enabled trigger_keywords: ["记住", "保存", "记录", "remember", "save to memory", "keep in mind"] default_enabled: false # AUTO-TRIGGER is OFF by default (opt-in for privacy) confirmation_required: true # ✅ IMPLEMENTED in v0.3.0 - Always prompts before saving privacy_filter: integrated # ✅ IMPLEMENTED in v0.3.0 - Automatic redaction of sensitive data path_protection: enforced # ✅ IMPLEMENTED in v0.3.0 - Blocks ~/.ssh, ~/.aws, .env files safe_mode: true # ✅ IMPLEMENTED in v0.3.0 - Forces confirmation + filter + path checks opt_in: configurable # Can be enabled in ~/.memory-os/config.json encryption: optional # Framework added, full implementation in v0.3.1 --- # OpenClaw Memory-OS **English** | [中文](#openclaw-memory-os-中文) ## ⚠️ 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** ```bash # 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** ```bash # 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** ```bash # 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** ```bash # 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** ```bash # 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):** ```bash # 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 ```bash # 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 ```bash 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:** ```bash # 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:** ```bash 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 ```bash # 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 ```bash # ✅ 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 ```bash # 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 ```bash # 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:** ```typescript 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](https://github.com/ZhenRobotics/openclaw-memory-os/blob/main/README.md) --- ## 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](#openclaw-memory-os)** | 中文 ## ⚠️ 重要隐私与安全声明 **安装或启用 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（可选）：** ```bash # 方法 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。 --- ## 安装 ```bash # 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 已关闭。使用手动命令以获得完全控制：** ```bash # 批量采集文件 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（可选 - 需先启用） **⚠️ 默认关闭。启用方法：** ```bash 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. 先在沙盒中测试 ```bash docker run -it --rm ubuntu:22.04 bash npm install -g openclaw-memory-os@0.3.0 openclaw-memory-os init # 说触发词并检查 ~/.memory-os/ ``` ### 2. 控制采集范围 ```bash # ✅ 推荐：特定目录 openclaw-memory-os collect --source ~/project-notes/ # ❌ 避免：过于广泛 openclaw-memory-os collect --source ~/ # 范围太大 ``` ### 3. 定期数据审查 ```bash # 列出所有记忆 ls ~/.memory-os/memories/ # 搜索敏感数据 grep -r "密码\|secret" ~/.memory-os/ # 删除不需要的数据 rm ~/.memory-os/memories/<uuid>.json ``` ### 4. 网络流量验证 ```bash # 验证零网络活动 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

path: readme.md
content: # OpenClaw Memory-OS

**English** | [中文](#openclaw-memory-os-中文版)

## 🛡️ Security & Privacy Notice (v0.2.2)

**Current Version:** 0.2.2
**Status:** 100% Local, Zero External APIs, Privacy-First Conversation Memory

**🔒 Privacy Notice (v0.2.2):**
- ✅ **AUTO-TRIGGER is OFF by default** (opt-in only)
- ⚠️ **No confirmation prompt** when enabled (saves immediately - planned for v0.3.0)
- ⚠️ **Privacy filter exists but not integrated** (code implemented, CLI integration pending)
- ⚠️ **No encryption at rest** (plain JSON files)
- ✅ **100% local runtime** - zero network calls during operation (installation requires npm)

**What This Version Does:**
- ✅ Local file-based memory storage (JSON format)
- ✅ Basic keyword search (all local computation)
- ✅ Batch file collection (user-triggered CLI)
- ✅ **Conversation memory extraction** (extract from natural language)
- ✅ **Auto-trigger support** (opt-in, saves immediately without confirmation in v0.2.2)
- ✅ Recursive directory scanning with progress display
- ✅ Automatic file type detection (TEXT vs CODE)
- ✅ Timeline and statistics (local only)

**What This Version Does NOT Do:**
- ❌ No AI embeddings or semantic search
- ❌ No LLM or external API calls
- ❌ No automatic background collection
- ❌ No network activity whatsoever
- ❌ No API keys required

**Your Data:**
- Stored: `~/.memory-os/` (local JSON files)
- Control: You decide what to collect and when
- Ownership: You own all data files
- Deletion: `rm -rf ~/.memory-os/` removes everything

**Recommended Safe Usage:**
1. Test in sandbox/VM first
2. Review files before collection
3. Use specific paths (not broad patterns like `~/Documents`)
4. Inspect collected data in `~/.memory-os/memories/`
5. Monitor network activity (should be zero)

See full security details: [SECURITY.md](https://github.com/ZhenRobotics/openclaw-memory-os/blob/main/SECURITY.md)

---

## Overview

Memory-OS is an open-source personal memory management system designed for digital immortality and cognitive continuity. It can collect, store, retrieve, and intelligently process all your digital memories, build personal knowledge graphs, and provide the ability to have conversations with your digitized "self".

**v0.2.2 Focus:** Opt-in conversation memory with local-only storage. AUTO-TRIGGER is disabled by default and saves directly when enabled (no confirmation prompt in v0.2.2). Privacy filter code exists but CLI integration pending. Extract and store information from natural conversations. AI features (semantic search, LLM integration) are planned but NOT implemented in this version.

## Core Features

**Current (v0.2.2):**
- **Opt-In Design** - AUTO-TRIGGER disabled by default
- **Local Storage** - JSON-based file storage, no cloud dependency, no encryption
- **Conversation Memory** - Extract information from natural language
- **Auto-Trigger** - Opt-in, saves immediately (no confirmation prompt)
- **Entity Extraction** - Automatically extracts names, dates, events
- **Privacy Filter** - Code implemented, CLI integration pending v0.3.0
- **Batch File Collection** - Import entire directories with one command
- **Recursive Scanning** - Automatically processes subdirectories
- **Type Detection** - Distinguishes CODE from TEXT files automatically
- **Real-time Progress** - Shows filenames during import
- **Basic Search** - Keyword and tag-based filtering (local)
- **Timeline Tracking** - Temporal organization of memories
- **Privacy-First** - All data stays on your machine
- **Extensible** - Modular architecture for future enhancements

**Planned (v0.2.0+):**
- **Semantic Search** - AI-powered understanding (will require API key)
- **Knowledge Graph** - Automatic relationship discovery (will require API key)
- **LLM Chat** - Conversation with your memories (will require API key)

## Quick Start

### Installation

```bash
# Install via npm
npm install -g openclaw-memory-os

# Or install from source
git clone https://github.com/ZhenRobotics/openclaw-memory-os.git
cd openclaw-memory-os
npm install
npm run build
npm link
```

### Initialization

```bash
# Initialize Memory-OS (creates ~/.memory-os/)
openclaw-memory-os init

# Configure basic information (optional)
openclaw-memory-os config set owner.name "Your Name"
openclaw-memory-os config set owner.email "[REDACTED_SECRET]"
```

### Basic Usage

```bash
# Conversation memory (with confirmation prompt)
openclaw-memory-os remember "记住我的名字：刘小容"
openclaw-memory-os remember "Remember the project deadline is 2026-04-01"

# Batch file collection
openclaw-memory-os collect --source ~/my-notes/
openclaw-memory-os collect --source ~/Documents/ --exclude node_modules .git

# Search memories (local keyword search)
openclaw-memory-os search "AI discussions"
openclaw-memory-os search --type code "function"

# View statistics
openclaw-memory-os status
```

### Security Verification

```bash
# Verify data location
ls -la ~/.memory-os/memories/

# Inspect collected memories
cat ~/.memory-os/memories/*.json | jq '.'

# View collection statistics
openclaw-memory-os status

# Monitor network activity (should be ZERO for v0.1.1)
# In one terminal:
sudo tcpdump -i any port 443 or port 80

# In another terminal:
openclaw-memory-os collect --source ~/test-data/
# Should see NO network traffic
```

## Core Concepts

### Memory Unit

The smallest memory unit in Memory-OS, containing:

```typescript
interface Memory {
  id: string;              // Unique identifier (UUID)
  type: MemoryType;        // Type: text, code, chat, file, media, activity
  content: any;            // Content (stored as-is)
  metadata: {
    source: string;        // Source identifier
    timestamp: Date;       // Creation timestamp
    tags: string[];        // User-defined tags
    context: string;       // Optional context
  };
  createdAt: Date;
  updatedAt: Date;
}
```

### Collectors

Collect memories from different data sources:

- `FileCollector` - Documents, notes (.txt, .md, .json, code files)
- `ChatCollector` - Chat history (planned)
- `CodeCollector` - Code repositories (planned)
- `MediaCollector` - Images, audio, video (planned)
- `ActivityCollector` - System activities (planned)

**v0.1.0:** Only `FileCollector` is implemented.

### Storage Layer

**v0.1.1:** Local file system storage

- JSON files in `~/.memory-os/memories/`
- Index file for fast lookup
- Human-readable format
- No encryption (can be added manually)
- Content stored as searchable strings

**Future versions:** Optional vector storage, graph storage, cloud sync.

## Use Cases

### 1. Personal Knowledge Management

```bash
# Import your notes
openclaw-memory-os collect --source ~/Documents/Notes/

# Search for specific topics
openclaw-memory-os search "machine learning algorithms"

# View by timeline
openclaw-memory-os timeline --range "last month"
```

### 2. Memory Recall

```bash
# View activities on a specific day
openclaw-memory-os timeline --date 2024-01-15

# Search for specific content
openclaw-memory-os search --type text --query "project ideas"
```

### 3. API Integration

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

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

await memory.init();

// Collect memory
await memory.collect({
  type: MemoryType.TEXT,
  content: 'Important note about project X',
  metadata: {
    tags: ['project', 'important'],
    source: 'manual',
  },
});

// Search memories
const results = await memory.search({
  query: 'project',
  limit: 10,
});

// View statistics
const stats = await memory.stats();
console.log(`Total memories: ${stats.totalMemories}`);
```

## Documentation

- [README](https://github.com/ZhenRobotics/openclaw-memory-os#readme) - Complete guide
- [SECURITY](https://github.com/ZhenRobotics/openclaw-memory-os/blob/main/SECURITY.md) - Security and privacy details
- [ARCHITECTURE](https://github.com/ZhenRobotics/openclaw-memory-os/blob/main/ARCHITECTURE.md) - System design
- [QUICKSTART](https://github.com/ZhenRobotics/openclaw-memory-os/blob/main/QUICKSTART.md) - 5-minute guide

## Community

- **GitHub**: https://github.com/ZhenRobotics/openclaw-memory-os
- **npm**: https://www.npmjs.com/package/openclaw-memory-os
- **ClawHub**: https://clawhub.ai/skills/openclaw-memory-os
- **Issues**: https://github.com/ZhenRobotics/openclaw-memory-os/issues

## Contributing

Contributions of code, documentation, and ideas are welcome! Please read [CONTRIBUTING.md](https://github.com/ZhenRobotics/openclaw-memory-os/blob/main/CONTRIBUTING.md).

## License

MIT-0 License

---

**Memory-OS - Make Memory Eternal, Make Cognition Continue**

---

# OpenClaw Memory-OS (中文版)

**[English](#openclaw-memory-os)** | 中文

## 🛡️ 安全与隐私声明（v0.2.2）

**当前版本：** 0.2.2
**状态：** 100% 本地，零外部 API，隐私优先的对话记忆

**🔒 隐私声明（v0.2.2）：**
- ✅ **AUTO-TRIGGER 默认关闭**（仅限选择加入）
- ⚠️ **启用后无确认提示**（立即保存 - v0.3.0 计划实现）
- ⚠️ **隐私过滤器已实现但未集成**（代码完成，CLI 集成待实现）
- ⚠️ **无静态加密**（明文 JSON 文件）
- ✅ **100% 本地运行** - 运行时零网络调用（安装需要 npm）

**此版本功能：**
- ✅ 本地文件记忆存储（JSON 格式）
- ✅ 基本关键词搜索（全部本地计算）
- ✅ 批量文件采集功能（用户触发的 CLI）
- ✅ **对话记忆提取**（从自然语言提取）
- ✅ **自动触发支持**（选择加入，v0.2.2 无确认提示立即保存）
- ✅ 递归目录扫描并显示进度
- ✅ 自动文件类型检测（TEXT vs CODE）
- ✅ 时间线和统计（仅本地）

**此版本不包含：**
- ❌ 无 AI 向量化或语义搜索
- ❌ 无 LLM 或外部 API 调用
- ❌ 无自动后台收集
- ❌ 无任何网络活动
- ❌ 无需 API 密钥

**您的数据：**
- 存储位置：`~/.memory-os/`（本地 JSON 文件）
- 控制权：您决定收集什么和何时收集
- 所有权：您拥有所有数据文件
- 删除方式：`rm -rf ~/.memory-os/` 删除所有内容

**推荐安全使用：**
1. 先在沙盒/虚拟机中测试
2. 收集前检查文件
3. 使用明确路径（不要用 `~/Documents` 等广泛模式）
4. 检查收集的数据在 `~/.memory-os/memories/`
5. 监控网络活动（应该为零）

详见完整安全说明：[SECURITY.md](https://github.com/ZhenRobotics/openclaw-memory-os/blob/main/SECURITY.md)

---

## 概述

Memory-OS 是一个开源的个人记忆管理系统，旨在实现数字永生和认知延续。它能够采集、存储、检索和智能化处理你的所有数字记忆，构建个人知识图谱，并提供与数字化"自我"对话的能力。

**v0.2.2 重点：** 选择加入的对话记忆，纯本地存储。AUTO-TRIGGER 默认关闭，启用后直接保存（v0.2.2 无确认提示）。隐私过滤器代码已实现但 CLI 集成待完成。从自然对话中提取并存储信息。AI 功能（语义搜索、LLM 集成）已计划但此版本未实现。

## 核心特性

**当前版本（v0.2.2）：**
- **选择加入设计** - AUTO-TRIGGER 默认关闭
- **本地存储** - 基于 JSON 文件，无云端依赖，无加密
- **对话记忆** - 从自然语言提取信息
- **自动触发** - 选择加入，立即保存（无确认提示）
- **实体提取** - 自动提取姓名、日期、事件
- **隐私过滤** - 代码已实现，CLI 集成待完成 v0.3.0
- **批量采集** - 从指定文件和目录
- **基本搜索** - 关键词和标签过滤（本地）
- **时间线追踪** - 记忆的时间组织
- **可扩展** - 模块化架构便于未来增强

**计划功能（v0.2.0+）：**
- **语义搜索** - AI 驱动的理解（需要 API 密钥）
- **知识图谱** - 自动关系发现（需要 API 密钥）
- **LLM 对话** - 与您的记忆对话（需要 API 密钥）

## 快速开始

[安装和使用说明与英文版相同]

## 文档

- [README](https://github.com/ZhenRobotics/openclaw-memory-os#readme) - 完整指南
- [安全](https://github.com/ZhenRobotics/openclaw-memory-os/blob/main/SECURITY.md) - 安全和隐私详情
- [架构](https://github.com/ZhenRobotics/openclaw-memory-os/blob/main/ARCHITECTURE.md) - 系统设计
- [快速入门](https://github.com/ZhenRobotics/openclaw-memory-os/blob/main/QUICKSTART.md) - 5分钟指南

## 社区

- **GitHub**: https://github.com/ZhenRobotics/openclaw-memory-os
- **npm**: https://www.npmjs.com/package/openclaw-memory-os
- **ClawHub**: https://clawhub.ai/skills/openclaw-memory-os
- **问题反馈**: https://github.com/ZhenRobotics/openclaw-memory-os/issues

## 贡献

欢迎贡献代码、文档和想法！请阅读 [CONTRIBUTING.md](https://github.com/ZhenRobotics/openclaw-memory-os/blob/main/CONTRIBUTING.md)。

## 许可证

MIT-0 License

---

**Memory-OS - 让记忆永存，让认知延续**

---

**Version:** 0.2.2
**Verified Commit:** 091eeab
**Security Status:** Local-Only, Zero External APIs, Opt-In Design
**Production Ready:** Test in sandbox first (no confirmation prompt, privacy filter pending)


path: USAGE_EXAMPLES.md
content: # Memory-OS 具体使用示例

## 方式 1: 在 Claude Code 中使用 Skill（推荐给普通用户）

### 安装

```bash
# 1. 安装 Skill
clawhub install openclaw-memory-os

# 2. 安装 npm 包（后端）
npm install -g openclaw-memory-os

# 3. 初始化
openclaw-memory-os init
```

### 使用示例

#### 示例 1: 保存选股规则

**您说：**
> "请帮我记住：我的选股标准是 PE<15, ROE>15%, 营收增长>20%, 偏好科技和医疗股"

**Claude 会：**
1. 使用 Memory-OS Skill 自动保存这条记忆
2. 提取关键词作为标签（stock, investment, rules）
3. 分类为 TEXT 类型
4. 存储到 `~/.memory-os/data/memories/`

**响应：**
```
✓ 已保存到记忆系统
记忆 ID: abc123...
标签: stock-selection, investment-rules
```

#### 示例 2: 回忆之前的规则

**您说（第二天）：**
> "我之前的选股标准是什么？"

**Claude 会：**
1. 自动从 Memory-OS 搜索相关记忆
2. 找到昨天保存的选股规则
3. 返回完整内容

**响应：**
```
根据您的记忆，您的选股标准是：
1. 市盈率 PE < 15
2. 净资产收益率 ROE > 15%
3. 营收增长率 > 20%
4. 行业偏好：科技、医疗

这是您在 2024-03-20 保存的规则。
```

#### 示例 3: 分析股票时自动应用规则

**您说：**
> "帮我分析中芯国际这只股票"

**Claude 会：**
1. 自动检索您的选股规则记忆
2. 应用规则分析股票
3. 给出符合您标准的分析

**响应：**
```
让我根据您的选股标准分析中芯国际：

根据您的规则（PE<15, ROE>15%, 营收增长>20%）：
- PE: 12.5 ✅ 符合
- ROE: 18.2% ✅ 符合
- 营收增长: 25.3% ✅ 符合
- 行业: 科技（半导体）✅ 符合偏好

综合评估：完全符合您的选股标准，建议关注。
```

---

## 方式 2: 使用 CLI 命令行

### 基本操作流程

#### 1. 保存笔记到记忆

```bash
# 创建测试笔记
mkdir ~/my-notes
echo "学习了 TypeScript 的高级类型系统" > ~/my-notes/typescript-notes.txt
echo "React Server Components 性能优化技巧" > ~/my-notes/react-notes.txt

# 采集到记忆系统
openclaw-memory-os collect --source ~/my-notes/

# 输出：
# ✓ 已采集 2 个文件
# ✓ 创建 2 条记忆
```

#### 2. 搜索记忆

```bash
# 搜索 TypeScript 相关笔记
openclaw-memory-os search "TypeScript"

# 输出：
# 找到 1 条记忆：
# [text] 学习了 TypeScript 的高级类型系统
#   来源: ~/my-notes/typescript-notes.txt
#   时间: 2024-03-20 10:30:15
```

#### 3. 查看时间线

```bash
# 查看今天的记忆
openclaw-memory-os timeline --date 2024-03-20

# 输出：
# 2024-03-20 的记忆：
# 10:30 - [text] TypeScript 学习笔记
# 10:35 - [text] React 性能优化笔记
# 总计: 2 条记忆
```

#### 4. 查看统计

```bash
openclaw-memory-os stats

# 输出：
# 记忆统计：
# 总记忆数: 2
# 按类型: {"text": 2}
# 按来源: {"file-collector": 2}
# 存储大小: 1.2 KB
```

---

## 方式 3: 编程 API

### 完整示例：构建选股助手

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

async function main() {
  // 1. 初始化
  const memory = new MemoryOS({
    storePath: '~/.memory-os'
  });
  await memory.init();

  // 2. 保存选股规则
  await memory.collect({
    type: MemoryType.TEXT,
    content: `
选股规则：
1. PE < 15
2. ROE > 15%
3. 营收增长 > 20%
4. 偏好：科技、医疗
    `,
    metadata: {
      tags: ['stock', 'rules'],
      source: 'user-input',
      category: 'investment'
    }
  });

  console.log('✓ 规则已保存');

  // 3. 分析股票时回忆规则
  async function analyzeStock(stockName: string, stockData: any) {
    // 检索规则
    const rules = await memory.search({
      tags: ['stock', 'rules']
    });

    if (rules.length > 0) {
      console.log('应用规则:', rules[0].memory.content);

      // 应用规则分析
      const pe = stockData.pe;
      const roe = stockData.roe;

      const result = {
        stock: stockName,
        peCheck: pe < 15 ? '✓' : '✗',
        roeCheck: roe > 15 ? '✓' : '✗',
        recommendation: (pe < 15 && roe > 15) ? '推荐' : '不推荐'
      };

      return result;
    }
  }

  // 4. 使用
  const analysis = await analyzeStock('中芯国际', {
    pe: 12.5,
    roe: 18.2
  });

  console.log(analysis);
  // {
  //   stock: '中芯国际',
  //   peCheck: '✓',
  //   roeCheck: '✓',
  //   recommendation: '推荐'
  // }
}

main();
```

---

## 实际场景：从零开始使用

### 场景：管理投资笔记

#### Day 1: 设定规则

```bash
# 1. 初始化
openclaw-memory-os init

# 2. 创建投资规则文件
cat > ~/investment-rules.txt << 'EOF'
我的投资原则：
1. 只投资自己理解的行业
2. PE < 15, ROE > 15%
3. 长期持有，不追涨杀跌
4. 单只股票仓位 < 10%
EOF

# 3. 采集规则
openclaw-memory-os collect --source ~/investment-rules.txt
```

#### Day 7: 分析新股票

```bash
# 搜索之前的规则
openclaw-memory-os search "投资原则"

# 输出会显示 Day 1 保存的规则
# 然后根据规则分析新股票
```

#### Day 30: 回顾投资决策

```bash
# 查看整个月的投资相关记忆
openclaw-memory-os timeline --range "last 30 days"

# 搜索所有分析过的股票
openclaw-memory-os search "股票"
```

---

## 数据查看和验证

### 查看原始数据

```bash
# 1. 查看记忆文件
ls -la ~/.memory-os/data/memories/

# 2. 查看单个记忆（JSON 格式）
cat ~/.memory-os/data/memories/abc123.json | jq '.'

# 输出示例：
{
  "id": "abc123-...",
  "type": "text",
  "content": "我的选股标准是 PE<15...",
  "metadata": {
    "source": "user-input",
    "timestamp": "2024-03-20T10:30:00Z",
    "tags": ["stock", "rules"]
  },
  "createdAt": "2024-03-20T10:30:00Z",
  "updatedAt": "2024-03-20T10:30:00Z"
}
```

### 验证零网络调用

```bash
# Terminal 1: 监控网络
sudo tcpdump -i any port 443 or port 80

# Terminal 2: 使用 Memory-OS
openclaw-memory-os collect --source ~/test-data/
openclaw-memory-os search "test"

# 应该看到：ZERO 网络流量（v0.1.0 完全本地）
```

---

## 常见问题

### Q: Skill 会自动保存所有对话吗？
**A:** 不会。只有当您明确要求"记住XXX"或使用关键词时才会保存。

### Q: 数据存储在哪里？
**A:** `~/.memory-os/data/` - 您的本地机器，JSON 格式，人类可读。

### Q: 如何删除某条记忆？
**A:**
```bash
# 找到记忆 ID
openclaw-memory-os search "要删除的内容"

# 删除文件
rm ~/.memory-os/data/memories/<memory-id>.json

# 或删除所有
rm -rf ~/.memory-os/
```

### Q: v0.1.0 需要 API key 吗？
**A:** 不需要。完全本地运行，零外部 API 调用。

### Q: 如何备份记忆？
**A:**
```bash
# 备份整个目录
cp -r ~/.memory-os ~/backups/memory-os-backup-$(date +%Y%m%d)

# 或导出（如果实现了）
openclaw-memory-os export ~/backups/memories.json
```

---

## 最佳实践

1. **明确路径**：使用 `~/specific-folder/` 而不是 `~/Documents/`
2. **定期检查**：`ls ~/.memory-os/data/memories/` 查看收集了什么
3. **测试先行**：先在 `~/test-data/` 测试，再用真实数据
4. **备份重要记忆**：定期备份 `~/.memory-os/` 目录
5. **使用标签**：保存时添加有意义的标签，方便后续搜索

---

**总结：**
- ClawHub Skill = 最简单（自然语言）
- CLI = 最灵活（批量操作）
- API = 最强大（自定义应用）

选择适合您的方式开始使用！


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)