# Memory Organizer

> 智能对话分析与记忆整理助手。获取并压缩指定 Agent 的对话记录，用于在用户授权/触发条件满足时，将信息分类写入 USER.md / AGENT.md / MEMORY.md（含索引与 memory/ 日志）/ IDENTITY.md / SOUL.md。

- Skill: `zhangzhengeric/memory-organizer` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add zhangzhengeric/memory-organizer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhangzhengeric/memory-organizer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: zhangzhengeric (https://skillmd.com/u/zhangzhengeric)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zhangzhengeric/memory-organizer

---


# Memory Organizer - 智能对话分析与记忆整理助手

## 目标
本技能用于两件事：
1) **对话压缩**：抓取指定时间范围内的对话，输出“可读且可追溯”的精简版，方便后续判断与提取。
2) **记忆整理（在触发条件满足时）**：将对话中可长期复用的信息，按类型写入正确的记忆文件，形成稳定的个人化与项目化知识库。

> 重要：**默认只做对话压缩，不自动更新任何记忆文件**。只有在用户明确要求/触发条件满足时才进入“记忆整理”。

## 核心原则
- 🎯 **非强制整理**：未触发时只输出压缩对话，不写文件
- 🧭 **按类型入库**：不同信息写入不同文件，避免 MEMORY.md 变成大杂烩
- 🧾 **可追溯**：新增记忆必须标注来源（日期/对话），并尽可能附“证据链接”（文件路径/产物链接/关键引用）
- 🧹 **去重与最小增量**：只新增“稳定、可复用、非一次性”的信息
- 🔒 **隐私优先**：涉及隐私/敏感信息需谨慎；不向外部发送；不将高度敏感信息写入长期索引（例如手机号/家庭住址等）

## 记忆整理范围与写入目标（你提出的 4 类）

### A. 用户习惯/偏好/个人信息 → `USER.md`
**写入内容示例**：
- 沟通偏好（语言、长度、格式、是否要先结论后细节）
- 工作流偏好（macOS、常用 repo、默认目录、命名规则）
- 长期有效的个人信息（称呼、身份、公开可存档信息）

**不写入**：临时状态、一次性偏好、明显会变化的短期安排。

**写入模板（建议）**：
```md
## 新增（来源：YYYY-MM-DD 对话）
- 偏好：...
- 习惯：...
- 个人信息：...
```

### B. 用户对助手的指导/行为约束 → `AGENT.md`
**写入内容示例**：
- 工具使用偏好（优先 CLI、本地优先、并行执行规则）
- 安全边界（破坏性操作前确认、.env/credentials 二次确认等）
- 工作空间规范（目录结构、输出要求、日志规范）

**写入模板（建议）**：
```md
## 会话新增规则（来源：YYYY-MM-DD 对话）
- ...
```

### C. 项目记忆 → `MEMORY.md`（索引） + `memory/`（详情）

#### C1. 写入策略（重要修订）
- `MEMORY.md`：只放“索引级”信息（项目结论、入口链接、关键里程碑），保持精简。
- `memory/YYYY-MM-DD.md`：写“**YYYY-MM-DD 当天实际发生的会话与产出**”的详细结论记录。
  - ✅ **日期含义**：文件名日期 = **当天发生的对话/工作**（而不是“哪天整理的”）。
  - ✅ **覆盖范围**：以当天会话为准；可以跨会话汇总，但不要把“今天做的整理工作”写成“今天发生的事情”。
  - ✅ **写法要求**：必须更详细，包含**结论 + 上下文 + 证据链接 + 影响**，以便复盘与追溯。

#### C2. memory/YYYY-MM-DD.md 的详细模板（必须遵守）
```md
### [PROJECT:项目名] 当天事项标题（YYYY-MM-DD）
- **结论**: 用 1-3 句给出最终结果/决策（可复用口径）
- **上下文**: 为什么做这件事？触发点/需求是什么？关键约束是什么？
- **关键动作**: 只写“对结果有贡献的动作”（不要流水账），可列 3-7 条
- **证据/产物**:
  - 输出文件：[...] (file://...)
  - 关键脚本/代码：[...] (file://...)
  - 关键对话摘录：引用 1-3 条带时间戳的用户原话（可选）
- **影响**:
  - 对用户/项目的价值、后续工作如何衔接
  - 风险/注意事项（如任务 id 漂移、依赖版本等）
- **后续 TODO**（可选）: ...
- **标签**: #tag1 #tag2
```

#### C3. MEMORY.md 索引模板（建议）
```md
## 重要项目
- [PROJECT:项目名] 一句话结论（来源：YYYY-MM-DD）
  - 入口：...（文件链接）
  - 关键变更：...
```

### D. 用户对 Agent 身份/语气/人格的要求 → `IDENTITY.md` 或 `SOUL.md`
**如何区分**：
- `IDENTITY.md`：角色、身份切换规则、对外代表口径、边界定义（“我是谁/如何扮演”）
- `SOUL.md`：表达风格、语气、价值观、长期行为准则（“我怎么说/怎么做”）

**写入内容示例**：
- “在群聊里以张正分身身份回复”的规则 → IDENTITY
- “语气简洁、技术化、直奔主题；不要使用某些套话” → SOUL

## 何时触发“记忆整理”
满足其一即可：
- ✅ 用户明确指令："整理记忆" / "更新记忆文件" / "把这个记住" / "沉淀到 USER/AGENT/MEMORY/IDENTITY/SOUL"
- ✅ 对话出现明显的**长期稳定信息**（偏好、约束、身份要求、项目里程碑），且用户在语境中表达希望长期保留

不触发：
- ❌ 闲聊/一次性事务/短期计划
- ❌ 信息不确定、尚未确认

## 使用方法

### 1) 获取对话（基础能力）
```bash
# 查看可用 Agent
python scripts/fetch_conversations.py --list-agents

# 获取最近 7 天对话（必须指定 agent-id）
python scripts/fetch_conversations.py --agent-id agent_93905d3d --days 7

# 获取指定时间范围的对话
python scripts/fetch_conversations.py --agent-id agent_93905d3d --start-time 2024-01-01 --end-time 2024-01-31

# 获取从某时开始到最近的对话
python scripts/fetch_conversations.py --agent-id agent_93905d3d --start-time 2024-01-01T00:00:00

# 只指定结束时间（从开始到该时间）
python scripts/fetch_conversations.py --agent-id agent_93905d3d --end-time 2024-01-31

# 保存到文件
python scripts/fetch_conversations.py --agent-id agent_93905d3d --days 7 --output /tmp/conversations.txt
```

**参数**：
- `--agent-id`: **必需**，目标 Agent ID
- `--days`: 分析天数（默认：7）
  - 与 `--start-time`/`--end-time` 互斥，不能同时使用
- `--start-time`: 开始时间，格式支持：
  - `YYYY-MM-DD`（如 2024-01-01）- 表示当天 00:00:00
  - `YYYY-MM-DDTHH:MM:SS`（如 2024-01-01T09:30:00）- 精确时间
- `--end-time`: 结束时间，格式同上
  - 如只指定日期，表示当天 23:59:59
  - 如不指定，默认为当前时间
- `--output`: 输出文件路径

### 2) 压缩策略（输出口径）
| 消息类型 | 处理方式 |
|---------|---------|
| **用户消息** | 完整保留，带时间戳 |
| **助手消息** | 默认压缩为“关键行动/结论”，带时间戳 |
| **最后一个助手回复** | 尽可能保留最终结论（允许比中间消息更完整） |
| **TOOL/中间消息** | **完全移除** |

## 执行流程（推荐）
1. **获取对话**：运行脚本输出压缩对话
2. **分类标注**：将信息按 A/B/C/D 四类归档
3. **去重校验**：检查目标文件中是否已有同类信息
4. **写入更新**（仅触发时）：
   - USER.md：偏好/个人信息
   - AGENT.md：指导与行为约束
   - MEMORY.md：项目索引
   - memory/YYYY-MM-DD.md：**当天会话的详细结论记录**（按“结论+上下文+证据+影响”模板）
   - IDENTITY.md / SOUL.md：身份/风格要求
5. **记录来源**：新增条目附 [来源：YYYY-MM-DD 对话]

## 注意事项
- ⚠️ 脚本只负责获取和压缩，**不自动更新文件**；文件更新由 Agent 在触发条件下执行
- ⚠️ 修改 `.env` 或 `credentials/` 前必须二次确认（遵循工作空间安全规范）
- ⚠️ 写入前尽量确保信息“稳定且可复用”，避免把噪声写进长期记忆

## 故障排除
- **API 连接失败**：检查 `SAGE_PORT` 环境变量
- **Agent ID 不存在**：使用 `--list-agents` 查看
- **内容过多**：减少 `--days` 参数

## 文件路径
- 脚本：`scripts/fetch_conversations.py` (相对于 Skill 根目录)
- 目标 Agent 目录：`{SAGE_ROOT}/agents/{agent_id}/`
  - `AGENT.md`: 工作空间规范和工具使用说明
  - `IDENTITY.md`: 身份定义、角色扮演的核心设定
  - `MEMORY.md`: 核心记忆索引、项目状态、待办事项
  - `SOUL.md`: 性格、行为风格和价值观
  - `USER.md`: 用户背景、偏好和沟通风格档案
  - `memory/`: 详细记忆日志文件夹（按日期记录）

---
*版本：1.5 | 最后更新：2026-03-16*