# Files Memory System - 用户使用指南

## 📖 简介

**Files Memory System** 是一个为 OpenClaw Agent 设计的**多上下文记忆管理系统**。

### 它能做什么？

- 🏠 **群组隔离记忆** - 每个聊天群组有独立的记忆空间
- 🌍 **全局共享记忆** - 跨群组的通用知识
- 🔒 **技能隔离** - 每个群组可以有专属的技能
- 📁 **项目隔离** - 每个群组可以有专属的项目目录

---

## 🚀 快速开始

### 第一步：安装 Skill

```bash
# 从 ClawHub 安装
clawhub install files-memory-system

# 进入 skill 目录
 cd /workspace/skills/files-memory-system

# 运行安装脚本（自动创建基础目录）
./scripts/install.sh
```

安装完成后，会自动创建：
- `memory/private/` - 私聊记忆
- `memory/global/` - 全局共享记忆

> 💡 **提示**：群组记忆的初始化是**自动**的！当 Agent 进入群聊并需要记录信息时，会自动创建 `memory/group_xxx/` 目录结构，无需手动执行初始化脚本。

---

## 📂 记忆目录结构

```
/workspace/
├── memory/
│   ├── global/              # 📚 跨群组共享
│   │   ├── GLOBAL.md        # 全局关键信息
│   │   └── 2024-01-15.md    # 每日记录
│   ├── group_feishu_xxx/    # 👥 群组专属
│   │   ├── GLOBAL.md        # 群组信息
│   │   ├── 2024-01-15.md    # 每日记录
│   │   ├── skills/          # 群组技能
│   │   └── repos/           # 群组项目
│   └── private/             # 🔒 私聊专属
│       ├── GLOBAL.md
│       └── 2024-01-15.md
└── MEMORY.md                # 🧠 长期精华记忆
```

---

## 💡 使用场景

### 场景 1：在群聊中克隆项目

**你说**："克隆这个仓库 https://github.com/user/project"

**系统自动处理**：
1. 识别你在当前群组
2. 把项目克隆到该群专属的项目文件夹
3. 更新群文档记录，方便以后查找

**你不用关心**：项目存在哪里、路径是什么，系统会自动处理。

---

### 场景 2：给群安装专属工具

**你说**："给这个群安装 inkos 写作助手"

**系统自动处理**：
1. 在当前群安装 inkos 工具
2. 该工具仅当前群可用，其他群看不到
3. 更新群的工具清单

**你不用关心**：安装路径、怎么隔离，系统自动确保工具只在当前群可用。

---

### 场景 3：记录重要信息

**使用明确的指令格式**：

| 你说的话 | Agent 会这样做 | 记录位置 |
|---------|---------------|---------|
| "记录到群记忆里: 项目架构讨论" | 写入群组记忆 | `memory/group_xxx/GLOBAL.md` |
| "记录到全局记忆里: API 密钥 xxx" | 写入全局共享 | `memory/global/GLOBAL.md` |
| "记录到跨群记忆里: 团队规范" | 写入全局共享 | `memory/global/GLOBAL.md` |
| "记录到私聊里: 个人笔记" | 写入私聊记忆 | `memory/private/GLOBAL.md` |

**💡 提示**：使用 "记录到X记忆里" 的格式，Agent 会立即写入对应位置，而不会只是口头说"我记住了"。

---

## 📝 记录规则速查

| 你想记录什么 | 使用指令 | 写入哪里 | 安全提示 |
|-------------|---------|---------|---------|
| 仅当前群组可见的信息 | "记录到群记忆里: xxx" | `memory/group_xxx/GLOBAL.md` | 适合一般信息 |
| 所有群组共享的信息 | "记录到全局记忆里: xxx" | `memory/global/GLOBAL.md` | ⚠️ 不要存储敏感凭证 |
| 跨群共享（同全局） | "记录到跨群记忆里: xxx" | `memory/global/GLOBAL.md` | ⚠️ 不要存储敏感凭证 |
| 仅私聊可见的信息 | "记录到私聊里: xxx" | `memory/private/GLOBAL.md` | 适合个人笔记，⚠️ 不存储敏感凭证 |
| 今日对话记录 | 自动 | `memory/group_xxx/YYYY-MM-DD.md` | - |

---

## 🔍 搜索优先级

当 Agent 搜索记忆时，按以下顺序：
1. **当前群组目录** - 最相关
2. **全局目录** - 跨群组共享
3. **其他群组** - 仅在必要时

---

## ❓ 常见问题

### Q: 为什么需要群组隔离？
**A**: 防止不同群组的记忆互相污染。比如小说创作群和编程学习群的 skill 不应该混在一起。

### Q: 群组解散了怎么办？
**A**: 记忆会保留在 `memory/group_xxx/` 中，不会删除。可用于历史回顾或重新激活群组时恢复上下文。

### Q: 如何迁移信息到全局？
**A**: 使用指令 "记录到全局记忆里"，或把内容从群记忆移动到 `memory/global/GLOBAL.md`。

### Q: Agent 怎么知道这些目录？
**A**: 安装时系统会自动注册，Agent 启动时会读取配置，你不需要手动设置。

### Q: 我可以存储 API 密钥或密码吗？
**A**: ⚠️ **不可以**。不要将敏感凭证（API 密钥、密码、Token）存储在记忆系统中：
- **✅ 推荐**: 使用环境变量（`export API_KEY="xxx"`）
- **❌ 避免**: 不要存储在"记录到群记忆里"
- **❌ 避免**: 不要存储在"记录到全局记忆里"
- **❌ 避免**: 不要存储在"记录到私聊里"

所有记忆文件都是明文存储，不适合保存敏感信息。

---

## 🔒 安全最佳实践

### 敏感信息处理
| 信息类型 | 推荐存储方式 | 风险等级 |
|---------|-------------|---------|
| API 密钥、Token | **环境变量** | ✅ 安全 |
| 密码 | **环境变量** | ✅ 安全 |
| 个人敏感信息 | **环境变量** | ✅ 安全 |
| 一般配置信息 | 群/全局记忆 | ✅ 安全 |
| 公开文档链接 | 群/全局记忆 | ✅ 安全 |

⚠️ **重要提醒**：**不要将任何敏感凭证（API 密钥、密码、Token）存储在记忆系统中**。始终使用环境变量存储敏感信息。

### 环境变量设置方法

1. **在启动前设置环境变量**（推荐方式）：
   - 在终端配置文件（如 ~/.bashrc、~/.zshrc 或 ~/.bash_profile）中添加环境变量定义
   - 或在启动 OpenClaw 前临时导出：`export 变量名="值"`

2. **运行时告知 AI**：
   - 告诉 AI："使用环境变量中的 API 密钥"
   - AI 会自动读取已设置的环境变量，无需在对话中暴露凭证

3. **安全提示**：
   - 不要在聊天记录、记忆文件或代码中直接写入敏感凭证
   - 环境变量仅在当前会话有效，不会持久化到磁盘上的记忆文件

---

## 📚 进阶阅读

### 技术文档
- `SKILL.md` - 完整技术文档
- `references/architecture.md` - 架构设计说明

### 可用脚本（技术用户）
| 脚本 | 用途 |
|------|------|
| `install.sh` | 安装 skill |
| `auto-clone.sh` | 自动克隆项目 |
| `ensure-group-memory.sh` | 确保群组目录 |
| `ensure-global-memory.sh` | 确保全局目录 |

### 模板文件
- `assets/templates/` - 各种模板文件

---

## 🆘 获取帮助

如果在 ClawHub 上查看此 skill，可以：
1. 阅读 `SKILL.md` 获取完整技术细节
2. 查看 `references/architecture.md` 了解架构设计
3. 运行 `./scripts/install.sh --help` 查看安装选项

---

**版本**: v1.10.2  
**作者**: wxwzl  
**许可证**: MIT