dootask/.claude/rules/graphiti.md

# Graphiti 长期记忆集成

本项目使用 Graphiti 作为「长期记忆层」，用于持久化用户偏好、工作流程、重要约束和关键事实。

**统一 group_id**: `dootask-main`

## 任务开始前（读取记忆）

在进行实质性工作（写代码、设计方案、做大改动）前，应先通过 Graphiti 查询已有记忆：

- 使用节点搜索（如 `search_nodes`）在 `group_id = "dootask-main"` 下查找与当前任务相关的 Preference / Procedure / Requirement
- 使用事实搜索（如 `search_facts`）查找相关事实与实体关系
- 查询语句中可包含：任务类型（Bug 修复 / 重构 / 新功能等）、涉及模块（任务、项目、对话、WebSocket、报表等）以及关键字 `dootask`

发现与当前任务高度相关的偏好 / 流程 / 约束时，应优先遵守；如存在冲突，应在回答中说明并做合理选择。

## 什么时候写入 Graphiti

| 类型 | 说明 | 示例 |
|------|------|------|
| **偏好 (Preferences)** | 用户表达持续性偏好时 | 语言、输出格式、技术选型 |
| **流程 (Procedures)** | 形成稳定的开发/发布/调试流程时 | 可复用步骤 |
| **约束 (Requirements)** | 项目长期有效的决策 | 不再支持某版本、架构约定 |
| **事实 (Facts)** | 模块边界、服务调用关系、外部集成方式 | AgoraIO、Manticore Search |

### 写入建议

- 默认使用 `source: "text"`，在 `episode_body` 中用简洁结构化自然语言描述背景、类型、范围、具体内容
- 需要结构化数据时可用 `source: "json"`，保证 `episode_body` 是合法 JSON 字符串
- 所有写入默认使用 `group_id: "dootask-main"`

## 更新与更正

- 偏好 / 流程发生变化时，新增一条 episode 说明新约定，并标明这是对旧习惯的更新
- 用户要求「忘记」某些记忆时，可通过删除或更正相关 episode / 关系的方式处理
- 尽量通过新增 episode 记录「更正 / 废弃说明」，而不是直接改写历史事实

## 使用原则

- **尊重已存偏好**：编码风格、回答结构、工具选择等应对齐已知偏好
- **遵循已有流程**：若图谱中已有与当前任务匹配的 Procedure，应尽量按步骤执行
- **利用事实**：理解系统行为、模块边界、历史决策时优先查已存 Facts
- **代码优先**：如 Graphiti 与当前代码实际冲突，应以代码实际为准，并视情况新增 episode 更新事实

## 不要写入的内容

- 敏感信息（密钥、密码、隐私数据）
- 只与当前一次任务相关、未来不会复用的临时信息
- 体量巨大的原始数据（完整日志、长脚本全文），应只存摘要和关键结论

## 最佳实践

1. **先查再做**：在提出方案或改动架构前，优先查阅 Graphiti 中已有的设计、偏好和约束
2. **能复用就沉淀**：只要发现某个偏好 / 流程 / 约束未来会反复用到，就尽快写入 Graphiti
3. **保持一致**：确保 Graphiti 中的记忆与实际代码长期保持一致，避免「记忆漂移」