# personal_memory 原则与核心概念

## 模板（原则）

### 设计目标

- <目标 1>
- <目标 2>

### 契约原则

- <输入/输出契约规则>

### 安全与边界

- <访问约束/护栏>

### 失败与恢复

- <调用失败时的行动>

### 术语表

- <该工具集特有术语>

## 记忆模型

personal_memory 工具集采用**路径键值存储**模型：

- **路径（path）**：记忆的唯一标识符，类似于文件系统路径，例如 `project/todo` 或 `user/preferences/theme`
- **内容（content）**：记忆的实际内容，可以是任意文本

**隔离性与首次创建：**

- 个人记忆仅对当前智能体可见。
- 磁盘上会自动隔离到：`.minds/memory/individual/<member-id>/...`。
- 因此 `path` 不应包含你的成员 id（不要写 `<member-id>/...`）。
- 若你当前还没有任何个人记忆条目，直接调用 `add_personal_memory` 即可：目录会由系统自动创建。

## 工具概览

| 工具                    | 功能                           |
| ----------------------- | ------------------------------ |
| add_personal_memory     | 创建新个人记忆（路径不存在时） |
| replace_personal_memory | 更新已有个人记忆（路径存在时） |
| drop_personal_memory    | 删除个人记忆                   |
| clear_personal_memory   | 清空所有个人记忆（不可恢复）   |

## 记忆生命周期

1. **创建（add）**：使用 `add_personal_memory` 创建新记忆
2. **读取（read）**：智能体在生成回复时可读取已有记忆
3. **更新（replace）**：使用 `replace_personal_memory` 更新记忆内容
4. **删除（drop）**：使用 `drop_personal_memory` 删除特定记忆

## 最佳实践

### 1. 路径命名规范

- 使用描述性路径：`project/architecture`、`user/preferences/language`
- 允许用 `/` 组织层级（这就是推荐用法），但必须遵守护栏：
  - 不允许绝对路径（不能以 `/` 开头）
  - 不允许路径穿越（`..` 禁止）
  - 避免使用 `\\`（跨平台可读性差，统一用 `/`）
- 保持路径扁平：优先少量主题文件，而不是深层目录树（个人记忆的目标是“快速索引”，不是建文件系统）。

### 2. 内容格式

- 把个人记忆当作“长期随身携带的稳定事实备忘”：让你在职责范围内尽量做到 **0 次 ripgrep 就能开工**。
- 内容只写稳定事实：**落点（文件/符号）+ 一句话语义 + 关键契约/优先级（≤3 条）**。
- 记忆文件更少更好：按“未来会一起更新的内容”合并在同一文件里；不要为了“看起来整齐”引入额外的“目录套目录”。
- `personal_memory` 优先承接“还没上升到团队角色资产，但对你未来仍有价值”的知识：例如你自己的入口地图、检索关键词、排障入口线索、长期工作偏好。
- 与 skills 的边界：工作区关联强的事实、路径、局部契约、职责域索引写进 `personal_memory`；独立于工作区内容的操作方法、检查清单、触发条件与边界写进 skill。若两者混在一起，请拆开维护，避免 skill 藏着容易过期的仓库事实。
- 不要把任务进度/当天状态写进个人记忆：
  - 需要向全队同步的当前有效状态、关键决策、下一步与仍成立阻塞，用 Taskdoc `progress` 这一准实时任务公告牌
  - 只供当前任务/当前对话短期持有的接续细节、临时 bridge 信息与手头工作提示，用 reminders

### 3. 推荐边界

- **角色级长期定义资产**：`persona / knowhow / pitfalls`
- **成员自己的长期可复用经验与个人工作索引**：`personal_memory`
- **可复用操作指引 / 检查清单 / 触发条件与边界**：`skills`
- **Taskdoc `progress`**：全队共享的准实时任务公告牌，承接当前有效状态、关键决策、下一步与仍成立阻塞
- **reminders**：当前任务/当前对话短期手头工作、接续包、容易丢的临时细节
- **团队共享的长期约定 / 不变量 / 共识原则**：`team_memory`

> 注：如果信息的主要目的，是让全队快速同步“现在到哪了、哪些决策已生效、下一步是什么、哪些阻塞仍成立”，它更适合进入 Taskdoc `progress` 这一准实时公告牌，而不是 `personal_memory`。
>
> 同样地，如果你想写的是某个角色的长期职责边界、长期工作方法、或持久有效的正反例，那么更适合进入该角色的 `persona / knowhow / pitfalls`，而不是 `personal_memory`。

## 与其他工具的关系

- **team_memory**：团队共享记忆，所有成员可见
- **skills**：可复用提示技能；承接“怎么做”的操作指导，不承接工作区事实仓库，也不授予工具权限
- **reminder**：临时提醒，会话级别
- **do_mind / mind_more / change_mind / never_mind**：创建、追加、替换或删除差遣牒章节

## 限制与注意事项

1. 路径护栏：不允许绝对路径；不允许包含 `..`。
2. 内容护栏：`content` 不能为空字符串。
3. `clear_personal_memory` 会删除当前智能体的全部个人记忆，**不可恢复**。

> 建议：即使当前实现没有硬性 size 限制，也应保持记忆内容精炼，否则会显著增加上下文成本与过期风险。
