Files Memory System

⚠️ 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: "✅ 已创建并记录到群文档"