files-memory-system

Multi-context memory management system for OpenClaw agents with group-isolated storage, global shared memory, workspace organization, and group-specific skills isolation. Use when initializing or managing memory systems for multi-channel deployments, creating group-specific memory directories, setting up MEMORY.md for long-term cross-group memories, organizing workspace directories (projects/repos), cloning repositories to group-isolated locations, managing group-isolated skills, or handling any file operations in group chat contexts.

⚠️ CRITICAL RULES

群聊中克隆仓库的硬性规定

❌ 禁止：直接使用 git clone 命令 ✅ 必须：使用 auto-clone.sh 脚本并传入 --group 参数

当用户在群聊中要求"克隆仓库"时：

1. 不要执行 git clone <url> → 这会克隆到 /workspace/repos/
2. 必须执行 ./skills/files-memory-system/scripts/auto-clone.sh --group feishu <group_id> <url> → 这会克隆到群组目录

Group ID 获取方式：从 metadata 中的 conversation_label 字段获取（如 oc_a2b821...）

---

🔴 会话开始强制检查清单 (群聊)

OpenClaw Bug: 群聊不会自动加载群记忆文件

每次在群聊中收到消息时，必须执行以下检查：

检查 metadata.is_group_chat:
├── IF true (群聊):
│   ├── 读取 memory/group_<channel>_<conversation_label>/GLOBAL.md
│   ├── 读取 memory/group_<channel>_<conversation_label>/YYYY-MM-DD.md (today)
│   └── 读取 memory/global/GLOBAL.md
│
└── IF false (私聊):
    ├── 读取 memory/private/YYYY-MM-DD.md (today)
    └── 读取 memory/global/GLOBAL.md

禁止在群聊中执行任何操作前跳过此检查！

---

Memory System

📖 新用户？ 请先阅读 用户使用指南 了解如何快速上手！

Installation

Method 1: Auto-Install with Self-Registration (Recommended)

cd ~/.openclaw/skills/files-memory-system
./scripts/install.sh

This will:

1. ✅ Copy skill to /workspace/skills/files-memory-system/ (standard location)
2. ✅ Auto-register in AGENTS.md so the agent knows this skill exists
3. ✅ Enable auto-discovery on every agent startup

Method 2: Manual Install

# 1. Copy to standard location
mkdir -p /workspace/skills
cp -r ~/.openclaw/skills/files-memory-system /workspace/skills/

# 2. Run self-registration
cd /workspace/skills/files-memory-system
./scripts/post-install.sh

Method 3: Using clawhub

cd /workspace
clawhub install files-memory-system
# Then manually run:
./skills/files-memory-system/scripts/post-install.sh

Self-Registration Mechanism

This skill implements auto-declaration - it automatically adds a section to AGENTS.md upon installation. This ensures:

• The agent knows files-memory-system exists without being told
• Memory locations are documented where the agent reads
• No manual configuration needed after installation

To verify registration:

grep -A 20 "files-memory-system" /workspace/AGENTS.md

To unregister (remove from AGENTS.md):

sed -i '/<!-- files-memory-system: installed -->/,/<!-- files-memory-system: end -->/d' /workspace/AGENTS.md

Overview

This skill provides a complete memory management system that enables OpenClaw agents to maintain context across multiple chat groups while keeping group-specific memories and skills isolated. It includes:

• Group-isolated memory: Separate memory directories per group/channel
• Group-isolated skills: Skills installed per group, preventing cross-group pollution
• Global shared memory: Cross-group knowledge in memory/global/
• Long-term memory: MEMORY.md for curated, permanent memories
• Workspace organization: Structured projects/ and repos/ directories

Session Start - Automatic Memory Loading

⚠️ 重要: 每次进入会话时，必须自动加载对应的记忆！

群聊中的自动加载流程

当收到群聊消息时，按以下顺序加载记忆：

1. 读取群组 GLOBAL.md - 获取群组关键信息和资源索引

   memory/group_<channel>_<id>/GLOBAL.md
   

2. 读取今日和昨日记录 - 获取最近的对话上下文

   memory/group_<channel>_<id>/YYYY-MM-DD.md (today)
   memory/group_<channel>_<id>/YYYY-MM-DD.md (yesterday)
   

3. 读取跨群组全局记忆 - 获取跨群组共享的信息

   memory/global/GLOBAL.md
   

私聊中的自动加载流程

1. 读取私聊记录 - 今日和昨日

   memory/private/YYYY-MM-DD.md (today)
   memory/private/YYYY-MM-DD.md (yesterday)
   

2. 读取跨群组全局记忆

   memory/global/GLOBAL.md
   

3. 读取长期精华记忆 (仅私聊)

   MEMORY.md
   

记忆加载检查清单

群聊中必须加载：

• 当前群组的 GLOBAL.md
• 今天的群组日志 (YYYY-MM-DD.md)
• 昨天的群组日志 (回顾上下文)
• 跨群组全局记忆 (memory/global/GLOBAL.md)

私聊中必须加载：

• 私聊今日和昨日日志
• 跨群组全局记忆 (memory/global/GLOBAL.md)
• MEMORY.md (仅私聊)

Usage Scenarios

Scenario 1: User Says "Clone This Repo" in a Group Chat

Context: User in group "oc_a2b821..." says: "Clone https://github.com/user/project"

Automatic Actions:

1. Detect current group context: group_feishu_oc_a2b821...
2. Clone to: memory/group_feishu_oc_a2b821.../repos/project/
3. Update group's GLOBAL.md with project info
4. Confirm: "✅ Cloned to group repos/project/"

Manual Commands:

# Option 1: Use auto-clone script with --group parameter (推荐)
./scripts/auto-clone.sh --group feishu oc_a2b821... https://github.com/user/project

# Option 2: Direct git clone
cd memory/group_feishu_xxx/repos
git clone https://github.com/user/project

# Option 3: Using environment variables (向后兼容)
GROUP_ID="oc_xxx" CHANNEL="feishu" ./scripts/auto-clone.sh https://github.com/user/project

Agent Implementation (直接执行，无需用户交互):

当用户要求克隆仓库时，先判断当前是否在群聊中（查看 inbound metadata 中的 is_group_chat 字段），然后：

如果是群聊 (is_group_chat: true):

1. 从 metadata 读取 conversation_label 作为 group_id
2. 使用 --group 参数执行克隆：

./skills/files-memory-system/scripts/auto-clone.sh \
    --group feishu "<conversation_label>" \
    "https://github.com/user/project"

如果是私聊 (is_group_chat: false):

./skills/files-memory-system/scripts/auto-clone.sh \
    --private \
    "https://github.com/user/project"

关键要点：

• ⚠️ 群聊中必须使用 --group 参数，否则仓库会克隆到全局目录
• --group <channel> <group_id> 必须在 URL 之前
• 群组ID从 conversation_label 获取 (如 oc_a2b821...)
• 脚本会自动创建缺失的群组记忆目录
• 如果用户没指定项目名称，脚本会自动从 URL 提取

After Cloning - Update GLOBAL.md:

## 群组项目 (repos/)

| 项目名称 | 类型 | 描述 | 位置 |
|---------|------|------|------|
| project | cloned | 克隆的示例项目 | repos/project/ |

Scenario 2: Create New Project in Group Context

Context: User says: "Create a new tool for our group"

Automatic Actions:

1. Create project directory: memory/group_xxx/repos/my-tool/
2. Initialize with template if needed
3. Update GLOBAL.md
4. Start working in the group-specific location

Manual Commands:

# Create new project in group context
mkdir -p memory/group_feishu_xxx/repos/my-tool
cd memory/group_feishu_xxx/repos/my-tool
# ... create files ...

Scenario 3: Install Skill for Specific Group

Context: User says: "Install inkos skill for this group only"

Automatic Actions:

1. Install to: memory/group_xxx/skills/inkos/
2. Update group's GLOBAL.md
3. Skill is isolated to this group only

Manual Commands:

# Method 1: Using clawhub with --dir
clawhub install inkos --dir memory/group_feishu_xxx/skills

# Method 2: Manual copy
mkdir -p memory/group_feishu_xxx/skills/inkos
cp -r inkos/* memory/group_feishu_xxx/skills/inkos/

Update GLOBAL.md:

## 已安装的群组专属 Skills

| Skill | 版本 | 来源 | 描述 |
|-------|------|------|------|
| inkos | 1.0.0 | clawhub | 小说写作工具 |

Scenario 4: Record Information to Group Memory ⭐

Context: User in group chat says: "记录到群记忆里: 项目信息" / "记录到全局记忆里: API密钥" / "记住这个"

Automatic Actions (Agent Must Do):

1. Detect the intent: User wants to record information to group memory
2. Determine target location (按优先级匹配):
   • If "记录到群记忆里" → memory/group_<channel>_<id>/GLOBAL.md
   • If "记录到全局记忆里"/"记录到跨群记忆里" → memory/global/GLOBAL.md
   • If "记录到私聊里" → memory/private/GLOBAL.md
   • If "群文档"/"群组" (模糊指令) → memory/group_<channel>_<id>/GLOBAL.md
3. Write to file immediately: Do not just say "I remember", actually write to file!
4. Confirm: "✅ 已记录到群记忆" / "✅ 已保存到全局记忆"

Example 1: Record Project Info

User: "记录到群记忆里: 项目信息"
项目名称: MyApp
技术栈: React + Node.js
负责人: 张三

Agent Action:
1. Detect "记录到群记忆里" → Target: memory/group_xxx/GLOBAL.md
2. Format as table and append:

## 活跃项目

| 项目名称 | 技术栈 | 负责人 | 更新时间 |
|---------|--------|--------|----------|
| MyApp | React + Node.js | 张三 | 2026-03-23 |

3. Confirm: "✅ 已记录到群记忆"

Example 2: Record API Key (⚠️ Not Recommended)

User: "记录到全局记忆里：API密钥 sk-abc123"

⚠️ **SECURITY WARNING**:
Storing API keys in plain text in memory files is NOT recommended.
**Recommended approach: Use environment variables**

export API_KEY="sk-xxx"

Alternative (if environment variables not possible):
- Use a secrets manager
- Use encrypted storage

If user insists on storing in memory:
1. Warn: "⚠️ 存储 API 密钥到记忆文件存在安全风险，建议仅用于测试环境"
2. Detect target location based on user command
3. Format as table and append
4. Confirm: "✅ 已记录 (⚠️ 安全风险)"

Recommended User Commands:

• "记录到群记忆里: [内容]" → 仅当前群可见
• "记录到全局记忆里: [内容]" → 所有群共享
• "记录到跨群记忆里: [内容]" → 同全局记忆
• "记录到私聊里: [内容]" → 仅私聊可见

Critical Rules:

• ❌ DO NOT just say "I remember" without writing to file
• ❌ DO NOT store sensitive info without clarifying scope
• ✅ ALWAYS confirm the location where info is stored
• ✅ Use tables in GLOBAL.md for structured info
• ✅ Add timestamps for time-sensitive info

Scenario 5: Create Files in Group Chat ⭐

Context: User in group chat says: "帮我写一篇文章" / "创建一个文档" / "生成xxx文件"

Automatic Actions (Agent Must Do):

1. Detect the intent: User wants to create a file in group context
2. Determine correct location:
   • Default: memory/group_<channel>_<id>/articles/ (for articles/docs)
   • Code: memory/group_<channel>_<id>/repos/ (for code projects)
3. Create the file: Write to the correct group-specific path
4. Auto-update GLOBAL.md: ⚠️ CRITICAL - After creating file, auto-append to GLOBAL.md
5. Confirm: "✅ 已创建并记录到群文档"

Scenario 6: Working Across Multiple Groups

Context: Same user in different groups

Group A (小说创作):

• Skills: memory/group_A/skills/inkos/
• Projects: memory/group_A/repos/novel-tools/

Group B (编程学习):

• Skills: memory/group_B/skills/code-helper/
• Projects: memory/group_B/repos/exercises/

Behavior:

• In Group A: Only sees inkos, not code-helper
• In Group B: Only sees code-helper, not inkos
• No pollution between groups!

Scenario 5: Migrate Information to Global

Context: Information becomes relevant to multiple groups

Migration Process:

1. Move from: memory/group_A/GLOBAL.md
2. To: memory/global/GLOBAL.md
3. Update Group A with reference
4. All groups can now access

Example:

# Original in group_A/GLOBAL.md
## Project Configuration
Config: xxx

# After migration - in global/GLOBAL.md
## Shared Project Configuration
Config: xxx

# In group_A/GLOBAL.md - add reference
## 跨群组资源
See: memory/global/GLOBAL.md

⚠️ Security Note: Do NOT migrate API keys, passwords, or other sensitive credentials to global memory. Keep secrets in environment variables or private memory only.

Memory Architecture

Directory Structure

/workspace/
├── memory/
│   ├── global/
│   │   ├── GLOBAL.md              # Shared key information
│   │   └── YYYY-MM-DD.md          # Daily logs
│   ├── group_feishu_<id>/         # Feishu group memories
│   │   ├── GLOBAL.md              # Group key information
│   │   ├── YYYY-MM-DD.md          # Daily logs
│   │   ├── skills/                # ⭐ Group-specific skills
│   │   └── repos/                 # ⭐ Group-specific projects
│   └── private/
│       ├── GLOBAL.md
│       └── YYYY-MM-DD.md
├── MEMORY.md
├── skills/                        # Global shared skills
├── projects/
└── repos/

Automation Scripts

scripts/init-group-memory.sh - Initialize group memory structure:

./scripts/init-group-memory.sh feishu oc_xxx "小说创作群组"

scripts/ensure-group-memory.sh - Ensure group memory directory exists (on-demand):

# Auto-initializes group memory with all subdirectories
./scripts/ensure-group-memory.sh feishu oc_xxx "小说创作群组"

scripts/ensure-private-memory.sh - Ensure private memory directory exists:

# Auto-initializes private memory when in private chat context
./scripts/ensure-private-memory.sh

scripts/ensure-global-memory.sh - Ensure global memory directory exists:

# Auto-initializes global memory for cross-group information
./scripts/ensure-global-memory.sh

scripts/auto-clone.sh - Clone repo to correct location:

# Auto-detects context and clones to appropriate location
./scripts/auto-clone.sh https://github.com/user/repo

Group-Isolated Skills System

Scope	Location	Access	Priority
Group-specific	memory/group_<id>/skills/	Only current group	High
Global	/workspace/skills/	All groups	Low

Promoting Cross-Group Memory Awareness

1. Include Reference in Group GLOBAL.md

Every group's GLOBAL.md should include:

## Cross-Group Resources

📚 **Cross-Group Global Memory**: `memory/global/GLOBAL.md`

Contains information shared across all groups.

2. Key Information to Store Globally

• Relevant to multiple groups
• Common standards or conventions
• Shared resources (non-sensitive)
• Tool documentation and links

⚠️ Security Note: Do NOT store API keys, passwords, or other sensitive credentials in global memory. Use environment variables or private memory for secrets.

3. Migration from Group to Global

When information becomes relevant to multiple groups:

1. Move to memory/global/GLOBAL.md
2. Update original with reference link
3. Notify affected groups

Memory Auto-Initialization

All memory directories are automatically initialized using a dual approach (A + B):

Approach A: Installation-Time Setup

When installing files-memory-system, the following directories are automatically created:

• memory/private/ with GLOBAL.md
• memory/global/ with GLOBAL.md

Approach B: On-Demand Setup

When using auto-clone.sh or other scripts, the system automatically detects and initializes missing directories:

• Group context: Calls ensure-group-memory.sh
• Private context: Calls ensure-private-memory.sh
• Global operations: Calls ensure-global-memory.sh

This ensures all memory locations are always available when needed, even if:

• The installation step was skipped
• The directory was accidentally deleted
• Working in a new workspace

Memory Directory Comparison

Feature	Private Memory	Group Memory	Global Memory
Location	memory/private/	memory/group_<id>/	memory/global/
Auto-init A	✅ Install-time	❌ No	✅ Install-time
Auto-init B	✅ On-demand	✅ On-demand	✅ On-demand
Skills	Uses global	Can isolate	N/A
Projects	Uses global	Can isolate	N/A
Scope	1-on-1 chats	Specific group	All groups
Ensure Script	ensure-private-memory.sh	ensure-group-memory.sh	ensure-global-memory.sh
Scope	1-on-1 chats only	Specific to one group
Auto-init	✅ Yes (A+B)	✅ Yes (B only)

Security Notes

• MEMORY.md only loaded in private chats
• Group skills completely isolated
• Preserve group memory on disband