# team_memory 原则与核心概念

## 模板（原则）

### 设计目标

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

### 契约原则

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

### 安全与边界

- <访问约束/护栏>

### 失败与恢复

- <调用失败时的行动>

### 术语表

- <该工具集特有术语>

## 记忆模型

team_memory 工具集采用**路径键值存储**模型，与 personal_memory 类似，但具有共享特性：

- **路径（path）**：记忆的唯一标识符，类似于文件系统路径
- **内容（content）**：记忆的实际内容，可以是任意文本
- **可见性**：内容面向团队共享；是否可写取决于当前智能体是否被授予了 team_memory 工具权限

**三分法边界：**

- `team_memory`：团队共享的长期约定 / 不变量 / 共识原则
- `personal_memory`：某成员自己的长期可复用经验与个人工作索引
- `persona / knowhow / pitfalls`：团队定义的角色级长期提示资产
- `skills`：可复用操作指引、检查清单、触发条件与边界；它是“怎么做”的提示技能资产，不是事实仓库，也不是权限系统

## 工具概览

| 工具                | 功能                           |
| ------------------- | ------------------------------ |
| add_team_memory     | 创建新共享记忆（路径不存在时） |
| replace_team_memory | 更新已有共享记忆（路径存在时） |
| drop_team_memory    | 删除共享记忆                   |
| clear_team_memory   | 清空所有共享记忆（不可恢复）   |

## 记忆生命周期

1. **创建（add）**：使用 `add_team_memory` 创建新共享记忆
2. **读取（read）**：所有团队成员都可以读取共享记忆
3. **更新（replace）**：使用 `replace_team_memory` 更新记忆内容
4. **删除（drop）**：使用 `drop_team_memory` 删除特定记忆

## 最佳实践

### 1. 路径命名规范

- 使用描述性路径：`team/project-goals`、`team/conventions/coding-style`
- 避免使用个人标识：`team/todo` 而非 `team/todo-alice`
- 使用层级结构：按主题组织记忆

### 2. 内容格式

- 保持内容简洁：每条记忆只包含一个主题
- 使用结构化格式：可以使用 Markdown 格式组织内容
- 注明更新时间：记录最后更新时间便于追踪
- 只写团队层面的稳定共识：例如共享约定、架构不变量、长期维护索引、跨成员都需要知道的判断规则
- 不要把某个成员自己的经验仓库写进 `team_memory`；那更适合 `personal_memory`
- 不要把通用操作规程、审查清单、调试套路或团队协作 SOP 写成 team memory；如果它主要回答“怎么做 / 谁在什么阶段如何协作”，应写成团队共享 skill。team memory 可以只保存当前 rtws 的事实性约定、路径索引与绑定关系，并被 skill 引用。
- 不要把任务执行期需要准实时向全队同步的当前有效状态、关键决策、下一步或仍成立阻塞写进 `team_memory`；这些更适合 Taskdoc `progress` 这一准实时任务公告牌

### 3. 使用场景

- **团队约定**：编码规范、提交信息格式、审查流程
- **项目知识**：架构决策、技术选型、长期有效的接口/入口索引
- **共享不变量**：术语表、协作原则、跨成员都应遵守的边界条件

## 与其他工具的关系

- **personal_memory**：个人记忆，仅当前智能体可见
- **skills**：可复用提示技能，承接操作方法；`allowed-tools` 不会自动授予 Dominds 权限
- **reminder**：临时提醒，会话级别
- **do_mind / mind_more / change_mind / never_mind**：创建、追加、替换或删除差遣牒章节

> 注：`team_memory` 承接团队长期共识；Taskdoc `progress` 承接任务执行期的准实时全队公告，不应混淆。

## 限制与注意事项

1. 路径护栏：不允许绝对路径；不允许包含 `..`。
2. 内容护栏：`content` 不能为空字符串。
3. `clear_team_memory` 会删除全部共享记忆，**不可恢复**。
4. 共享记忆通常应由团队治理角色维护；内容要谨慎、少量、只写稳定约定。
