graph-memory-bank

Graph Memory Bank

Цель

Сформировать и поддерживать графовую память проекта (как в Obsidian), чтобы ИИ-агенты быстро собирали точный минимальный контекст:

• много маленьких файлов, каждый про одну сущность/идею;
• связи через обычные markdown-ссылки;
• у каждого узла есть краткий YAML frontmatter (машиночитаемый);
• есть обратные ссылки (backlinks), чтобы граф был двунаправленным.

Результат (что должно получиться)

Обычно: docs/graph/ в репозитории, где есть 3 слоя:

1. tasks/ (история изменений: релизы/задачи/коммиты, “что менялось”)
2. project/ (семантика: архитектура, ключевые сущности, контракты, API, БД, интеграции, “куда смотреть в коде”)
3. processes/ или process/ (процессы: правила ведения графа, как обновлять, как читать, качество, генераторы)

Важно: если в репозитории уже есть один из вариантов (process/ или processes/) или другая устоявшаяся структура, не переименовывай “ради красоты”. Подстраивайся под текущую структуру, а в индексах дай явные ссылки.

Если слой процессов пока не нужен, начинай с первых двух, но держи место под третий слой.

Инварианты (жесткие правила)

1. Дроби информацию: один файл = одна сущность/идея/контракт.
2. Держи узлы короткими: как правило, до 200-300 строк; если разрастается, выноси подузлы.
3. У каждого узла есть YAML frontmatter (минимум: id, type, title, description, status, tags).
4. Всегда добавляй связи:
   • outbound links: “см. также”, “используется в”, “зависит от”
   • backlinks: “где используется” (явные ссылки обратно на индексы/хабы)
5. Если в проекте есть _generated/ или другие generated-секции: не редактируй руками, правь генератор или исходный узел.
6. Если есть сомнения/риски: подсвечивай и задавай вопросы (лучше уточнить, чем зацементировать неверную семантику).

Рекомендованная схема frontmatter (минимум)

Делай frontmatter максимально стабильным (для индексирования агентами):

• id: глобально уникальный идентификатор узла
• type: тип узла (project, dev_task, release_review, screen, rf_procedure, db_table, ...)
• title: человекочитаемое имя
• description: 1 предложение “зачем этот узел”
• status: stub | curated | generated
• tags: плоский список тегов (короткие)

Опционально (если реально помогает): releases, source_paths, owner, risk_level.

Как оформлять индексы (важно)

В индексах пиши не только ссылки, но и микро-аннотацию, чтобы не открывать каждый файл:

• - [DEV-12345](...): 6-10 слов, что внутри.

Что НЕ делать

• Не тащи секреты/токены/пароли в docs/ (максимум: “ищется в переменных окружения X/Y”).
• Не дублируй большие куски кода/SQL: вместо этого “якоря” + короткая выжимка + ссылка на файл.

Быстрый workflow (универсальный)

0) Подготовка

1. Создай отдельную ветку (например graph+memory).
2. Уточни ограничение записи:
   • по умолчанию пиши только в docs/ (или другой явно согласованный каталог).
3. Найди, есть ли уже документация/конвенции (docs/, ADR, mkdocs, docusaurus).

1) Сбор каркаса (bootstrap)

1. Создай docs/graph/index.md (входная точка).
2. Создай индексы:
   • docs/graph/tasks/index.md
   • docs/graph/project/index.md
   • docs/graph/processes/index.md или docs/graph/process/index.md (в зависимости от структуры репозитория)
3. Зафиксируй соглашения:
   • схема id (обычно префикс + путь, например graph:project/<slug>)
   • статусы: stub | curated | generated
   • теги: короткие, стабильные (не плодить)

Шаблоны и чек-листы: см. references/templates.md и references/quality-bar.md.

2) 按发布版本/标签梳理（以发布为驱动）

目标：快速找出实际发生过变更的“重要实体”。

对每个发布版本：

1. 找到发布产物：发布说明 / 标签 / 更新日志 / 合并提交。
2. 计算 Git 范围（通常为发布说明或标签对应提交之间的范围）。
3. 提取“实体列表”：
   • 任务 / 工单
   • 变更路径（模块 / 子系统）
   • 新增 / 变更的界面 / 契约 / DB 迁移
4. 创建发布审查节点（类型为 release_review），并列出实体。
5. 对于每个 DEV 任务：
   • 创建 / 更新 dev_task 节点
   • 添加 source_paths（最少的锚点列表）
   • 与语义节点（project/*）建立关联
6. 更新索引和反向链接。

3) 按实体梳理（以实体为驱动）

目标：补齐“所有关键实体”方面的空白，而不仅限于发布版本中涉及的实体。

重要：“实体”应具备通用性。在 WMS 中，实体可以是 屏幕/RF 流程；在网站中，可以是 页面/API；在 CRM 中，可以是 对象/销售流程；在数据总线中，可以是 主题/架构/连接器。

算法：

1. 划分出 5-12 个对项目真正重要的实体类别。
2. 为每个类别整理一个目录（索引 / 中心），然后逐个补充节点。
3. 确保每个实体都具备“交叉关联”：UI / 操作 / 数据 / 集成 / 配置。

建议的类别（选择相关类别，无需全部采用）：

1. 交互入口（entrypoints）：
   • Web/UI：页面、路由、关键组件、表单。
   • API：端点、控制器 / 处理器、公共契约。
   • CLI/Jobs：命令、cron/quartz、工作进程、后台任务。
   • Events/Streams：主题、事件、消费者 / 生产者。
2. 操作 / 命令 / 场景（actions）：
   • “系统会做什么”：用例、服务方法、命令、工作流步骤。
3. 数据和契约（data/contracts）：
   • DB 表 / 模型、迁移、消息架构、DTO、OpenAPI/AsyncAPI、JSON schema。
4. 集成（integrations）：
   • 外部系统、协议（HTTP/JMS/Kafka/SFTP）、重试、超时、幂等性。
5. 配置和标志（config/feature flags）：
   • 运行时设置、功能标志、环境参数、机密（仅记录“来源”，不记录值）。
6. 安全和访问（security）：
   • 身份验证 / 授权、角色 / 权限、SSO、审计。
7. 可靠性和运维（ops）：
   • 指标 / 日志 / 链路追踪、告警、SLO、降级、恢复流程。

核心原则：不要试图“手动描述一切”。应当创建：

• 目录和中心（系列 / 模块 / 领域）；
• 带有证据的原子节点；
• 类别间的关联（例如：页面 -> API -> 服务 -> 表 -> 事件）。

4) 随变更维护（增量维护）

对于 main 中的每个新提交：

1. 确定受影响的实体（根据 diff / 路径 / 关键词）。
2. 更新相应节点，不要扩展不必要的上下文：
   • 添加 1-3 句“变更内容”
   • 添加契约 / 代码 / DB 的链接
   • 更新反向链接 / 索引
3. 运行快速检查：
   • 重复的 id
   • 缺少 frontmatter
   • 节点间的链接失效
   • 孤立节点（docs/graph 内没有入站链接的节点）
   • 相对链接失效（如果有时间）

基本检查可以使用 scripts/graph_memory_lint.py。

示例：

python3 scripts/graph_memory_lint.py --root docs/graph

也可以选择关闭部分检查：

python3 scripts/graph_memory_lint.py --root docs/graph --no-check-links
python3 scripts/graph_memory_lint.py --root docs/graph --no-check-orphans

skill 中的资源

• references/templates.md：精简的节点模板。
• references/quality-bar.md：质量标准和“危险信号”。
• scripts/graph_memory_lint.py：快速代码检查工具（frontmatter + 重复的 id）。

**适用于：**模板、样板代码、文档模板、图像、图标、字体，或任何旨在复制或用于最终输出的文件。

---

并非每项 skill 都需要这三类资源。