Внедрить Lore Protocol как систему long-term memory для агентов через git commit messages

[ivan-hilckov]

Внедрить Lore Protocol как систему long-term memory для агентов через git commit messages

Контекст

Сейчас скилы /task, /plan, /do, /review работают как изолированные сессии — каждый запуск начинается с нуля, без знания о предыдущих решениях, отвергнутых подходах и активных ограничениях проекта. При этом каждый коммит, сделанный /do, теряет Decision Shadow — контекст решений, который существовал в голове агента в момент написания кода, но не попал в историю.

Lore Protocol ([arXiv:2603.15566](https://arxiv.org/html/2603.15566v1)) предлагает использовать git commit messages с нативными git trailers как структурированный канал знаний между агентами. Это даёт нам long-term memory с нулевой инфраструктурой — только git.

См. также:

• [Разбор с Perplexity](https://gist.github.com/ivan-hilckov/e62df6e30895b768eea4b37d160cb10a)
• [GCC — Git Context Controller](https://arxiv.org/html/2508.00031v1)
• [DiffMem — git as differential memory](https://github.com/Growth-Kinetics/DiffMem)

Цель

Сделать git-историю проекта основным источником институциональной памяти для всех скилов SP. Каждый скил, который читает или модифицирует код, должен:

1. Читать Lore-контекст из истории перед началом работы (read side)
2. Писать Lore-enriched коммиты по завершении работы (write side)

Архитектура решения

Два слоя: плагин (distributable) + project rule (scaffolded)

sp/ (плагин — распространяется через маркетплейс)
├── skills/
│   ├── lore/                          # NEW — Lore read/write скил
│   │   ├── SKILL.md                   # Основной скил с агрессивным description
│   │   └── reference/
│   │       ├── lore-commit-guide.md   # Write side: формат, трейлеры, примеры
│   │       └── lore-reading-guide.md  # Read side: команды, паттерны, стратегии
│   │
│   ├── lore-init/                     # NEW — scaffolder для project rules
│   │   ├── SKILL.md
│   │   └── templates/
│   │       └── lore-protocol.rule.md  # Шаблон для .claude/rules/
│   │
│   ├── do/
│   │   ├── SKILL.md                   # MODIFY — добавить Lore read + write шаги
│   │   └── reference/
│   │       └── commit-convention.md   # REPLACE — заменить на ссылку к lore-commit-guide
│   ├── task/
│   │   └── SKILL.md                   # MODIFY — добавить Lore read на этапе исследования
│   ├── plan/
│   │   └── SKILL.md                   # MODIFY — добавить Lore read на этапе дизайна
│   └── review/
│       └── SKILL.md                   # MODIFY — добавить Lore read для контекста решений
│
└── commands/
    └── gca.md                         # MODIFY — заменить формат на Lore Protocol

<user-project>/ (создаётся через /lore-init — не часть плагина)
└── .claude/
    └── rules/
        └── lore-protocol.md           # Always-on триггеры (~40 строк)

Почему два слоя

Проблема дистрибуции: .claude/rules/ загружается always-on при старте сессии — идеально для read-side триггеров ("перед модификацией файла проверь Lore-историю"). Но плагин не может записать файлы в .claude/rules/ пользователя.

Решение: graceful degradation.

• Без /lore-init (free tier) — скилы SP сами читают/пишут Lore по своей внутренней логике. Работает когда пользователь явно вызывает /sp:task, /sp:do и т.д.
• С /lore-init (full install) — project rule гарантирует что Lore-контекст проверяется ВСЕГДА, даже при ручной работе вне SP-скилов. Один раз вызвал — команда получает always-on memory через git.

---

Компоненты

1. skills/lore/ — основной Lore скил

SKILL.md description (агрессивный, для максимального триггеринга):

name: lore
description: >
  Lore Protocol — structured long-term memory through git commits.
  Use BEFORE modifying any file to read decision history (constraints,
  rejected alternatives, directives). Use AFTER completing work to write
  Lore-enriched commits. Triggers: any code modification, git commit,
  refactoring, bug investigation, understanding unfamiliar code,
  "why was this done", "what was tried before", code archaeology.

reference/lore-commit-guide.md (write side):

• Формат Lore atom: intent line → body → trailers
• Trailer vocabulary (Table 1 из paper): Constraint:, Rejected:, Confidence:, Scope-risk:, Reversibility:, Directive:, Tested:, Not-tested:, Related:
• Процедура рефлексии Decision Shadow перед коммитом
• One-shot примеры (полный + минимальный)
• Anti-patterns

reference/lore-reading-guide.md (read side):

• Git команды для чтения Lore:
  • git log -n 20 --format="%h %s" -- <path> — быстрый обзор intent lines
  • git log -n 10 -- <path> — полные сообщения с трейлерами
  • git log --all --trailer=Constraint: -- <path> — активные ограничения
  • git log --all --trailer=Directive: -- <path> — предупреждения
  • git log --all --trailer=Rejected: -- <path> — отвергнутые подходы
  • git blame <file> + git show <hash> — line-level контекст
  • git log --all --grep="keyword" — поиск по всей истории
  • git log --follow -- <path> — история с переименованиями
• Стратегии чтения: когда какую команду использовать
• Интерпретация: как использовать Rejected: чтобы не повторять dead ends, как учитывать Directive: при модификации

2. skills/lore-init/ — scaffolder

При вызове /sp:lore-init:

1. Создаёт .claude/rules/lore-protocol.md из шаблона
2. Опционально: добавляет commit-msg git hook для валидации Lore-трейлеров
3. Опционально: добавляет строку в корневой CLAUDE.md проекта
4. Выводит инструкцию: "Lore Protocol initialized. All agents will now read decision history before modifying code."

templates/lore-protocol.rule.md (~40 строк, always-on):

# Lore Protocol

This project uses Lore Protocol for institutional memory via git commits.

## Before modifying any file

1. Run `git log -n 10 -- <path>` to read recent Lore context
2. Check `Constraint:` trailers — these are active rules you must respect
3. Check `Directive:` trailers — these are warnings from previous authors
4. Check `Rejected:` trailers — do NOT re-propose rejected approaches without new evidence

## Before proposing an approach

Run `git log --all --trailer=Rejected: -- <path>` to see what was already tried and dismissed.

## When encountering unfamiliar code

Run `git blame <file>`, pick the relevant commit hash, run `git show <hash>` to read the full Lore atom.

## When committing

For full format instructions, read the Lore commit guide from the sp plugin.
Write intent (why, not what) as the first line. Add Lore trailers: Constraint, Rejected, Confidence, Scope-risk, Reversibility, Directive, Tested, Not-tested.

3. Интеграция в существующие скилы

/task — добавить Lore read в исследование

В task-explorer agent: перед анализом кодовой базы запустить Lore context harvest для релевантных файлов. Включить найденные Constraint: и Directive: в секцию constraints task-файла. Включить Rejected: в секцию "previously attempted approaches".

/plan — добавить Lore read в design decisions

В plan-designer agent: перед принятием design decisions проверить Lore-историю затрагиваемых модулей. Использовать Rejected: из истории для обоснования выбора подходов — "approach X was rejected in commit abc1234 because of Y, we use approach Z instead". Включить активные Constraint: в ограничения плана.

/do — Lore read + write

• Read: task-executor agent перед модификацией каждого файла проверяет Lore-контекст (constraints, directives). Если находит конфликт между планом и Lore-constraint — останавливается и докладывает.
• Write: заменить текущий commit-convention.md на ссылку к lore-commit-guide.md. Агент, выполнивший работу, сам пишет Lore-enriched коммит (НЕ делегирует сабагенту — Decision Shadow теряется на границе агентов).

/review — Lore read для контекста

При анализе изменений подтягивать Lore-контекст коммитов для объяснения в review-файле: "This approach was chosen because constraint X exists (see commit abc1234), alternative Y was rejected due to Z".

commands/gca — заменить формат

Текущий формат коммитов заменить на Lore Protocol. Команда /gca должна:

1. Прочитать lore-commit-guide.md
2. Проанализировать staged changes
3. Провести рефлексию Decision Shadow
4. Сформировать Lore-enriched commit message с трейлерами

---

Порядок реализации

Phase 1: Write side (фундамент)

• Создать skills/lore/reference/lore-commit-guide.md
• Создать skills/lore/SKILL.md (write-only на первом этапе)
• Модифицировать commands/gca — переключить на Lore format
• Модифицировать skills/do/ — заменить commit-convention на Lore
• Начать накапливать Lore-enriched коммиты в самом sp-репозитории

Phase 2: Read side (чтение)

• Создать skills/lore/reference/lore-reading-guide.md
• Обновить skills/lore/SKILL.md — добавить read instructions
• Интегрировать Lore read в skills/task/ (task-explorer)
• Интегрировать Lore read в skills/plan/ (plan-designer)
• Интегрировать Lore read в skills/review/
• Интегрировать Lore read в skills/do/ (task-executor, перед модификацией)

Phase 3: Distribution (дистрибуция)

• Создать skills/lore-init/ с шаблоном project rule
• Добавить опциональный commit-msg hook для валидации трейлеров
• Обновить README с описанием Lore Protocol
• Dogfood: перевести сам sp на Lore-коммиты и убедиться в работоспособности read side на реальной истории

---

Критерии успеха

1. Write: каждый коммит через /do или /gca содержит минимум Confidence: + Scope-risk: + один Constraint: или Directive:
2. Read: /task включает Lore-constraints в output, /plan учитывает Rejected: из истории при design decisions
3. Feedback loop: агент, запускающий /do на задаче, обнаруживает через Lore что определённый подход уже был отвергнут, и не повторяет его
4. Distribution: /lore-init корректно создаёт project rule, after which даже ручная работа вне SP-скилов получает Lore awareness

Ссылки

• Lore Protocol paper: https://arxiv.org/html/2603.15566v1
• Git trailers: https://git-scm.com/docs/git-interpret-trailers
• GCC paper: https://arxiv.org/html/2508.00031v1
• DiffMem: https://github.com/Growth-Kinetics/DiffMem
• Claude Code memory system: https://code.claude.com/docs/en/memory

[ivan-hilckov]

https://github.com/coleam00/context-engineering-intro/blob/main/use-cases/ai-coding-wisc-framework/.claude/commands/commit.md

[ivan-hilckov]

https://gist.github.com/ivan-hilckov/e62df6e30895b768eea4b37d160cb10a - разбор с перплексити

Lore Protocol - https://arxiv.org/html/2603.15566v1
GCC - https://arxiv.org/html/2508.00031v1

https://www.reddit.com/r/LocalLLaMA/comments/1mvgw9k/diffmem_using_git_as_a_differential_memory/
https://github.com/Growth-Kinetics/DiffMem

• доработать комнду /gca
• доработать скилы что бы они делали комиты по Lore Protocol
• реализовать скилл который "научит и обучит" как работать с Lore protocol