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 中的记忆与实际代码长期保持一致，避免「记忆漂移」