files-memory-system

Multi-context memory management system for OpenClaw agents with group-isolated storage, global shared memory, workspace organization, and group-specific skil...

Security Scan

The skill's code and instructions mostly match its stated purpose (group-scoped file-based memory), but there are several inconsistencies and operational risks (auto-registration that modifies workspace files, cloning arbitrary repos, an rm -rf fallback, and a few contradictory/buggy instructions) that you should review before installing.

Purpose & Capability

The name/description (multi-context file-backed memory) aligns with the included files and scripts: they create /workspace/memory/*, manage per-group directories, and provide an auto-clone script. The skill auto-registers itself in /workspace/AGENTS.md and creates memory directories during install — this is coherent with a memory-management skill but may be surprising because the installer modifies workspace metadata files automatically.

Instruction Scope

SKILL.md requires the agent to read conversation metadata (is_group_chat, conversation_label) and to always load group/global memory files before handling group messages; that is consistent with purpose but broad. The skill also mandates using its auto-clone script for group clones and gives the agent permission to run several scripts (install, post-install, auto-clone, ensure-*-memory). Those scripts perform filesystem writes and run git clone on arbitrary repository URLs — expected for the stated features but increases risk. Additionally, SKILL.md contains contradictory guidance (it says "禁止直接使用 git clone" in group chats but also lists direct git clone as an option) and the auto-clone script has a buggy environment-variable fallback (the BLOCK that tries to set GROUP_ID from env is self-contradictory).

Install Mechanism

There is no external download/install spec (instruction-only skill), but included install.sh will copy files into /workspace/skills/, create /workspace/memory/*, and auto-register the skill by appending to /workspace/AGENTS.md. install.sh attempts to delete an existing install directory and prefers using 'trash' but falls back to rm -rf if trash is unavailable — the script prompts for confirmation, but rm -rf fallback is a risky operation if misused. No remote binary downloads are performed by the installer itself.

Credentials

The skill declares no required environment variables or credentials. It does reference optional env usages (CHANNEL, GROUP_ID) as backward compatibility. It instructs users not to store secrets in memory files and to use environment variables for credentials. There is no request for unrelated cloud credentials or tokens in the package metadata.

Persistence & Privilege

The skill is not always:true and is user-invocable. However, post-install auto-registration appends to /workspace/AGENTS.md and installation creates persistent directories and marker files under /workspace. Combined with autonomous invocation (the platform default), this gives the skill the ability to be invoked and to read/write workspace files and clone remote repos — behavior that fits its purpose but raises the blast radius if the skill were malicious or if cloned code is executed later.

What to consider before installing

Before installing, review the included shell scripts yourself (install.sh, post-install.sh, auto-clone.sh, ensure-*.sh). Pay particular attention to: 1) install.sh's delete-and-copy behavior — it will prompt but can fall back to rm -rf if 'trash' is absent; 2) auto-clone.sh will run 'git clone' on arbitrary URLs (avoid cloning untrusted repositories into your workspace); 3) post-install.sh appends content to /workspace/AGENTS.md (inspect AGENTS.md after installation); 4) there are small bugs/contradictions in SKILL.md and scripts (env fallback bug for GROUP_ID and contradictory guidance about direct git clone) — these suggest the package may be sloppy and worth manual testing in a sandbox first. If you plan to install in a production workspace, consider installing in an isolated/test workspace, ensure you have backups of /workspace, and verify the scripts (or modify them) to remove any rm -rf fallbacks or to require stricter confirmations. Finally, never store secrets in the memory files created by this skill; keep credentials in environment variables as the documentation recommends.

⚠️ 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