Project Memory — память проекта для любого AI-агента

Что это одной фразой: папка с текстовыми файлами, которая даёт любому AI-агенту «память» о вашем проекте — чтобы он не забывал, что уже сделано, после закрытия чата.

---

Зачем это нужно

Представьте обычную работу с AI-агентом: вы открываете новый чат, объясняете контекст, агент помогает — и всё это забывается, когда чат закрывается. В следующий раз вы начинаете сначала: «наш проект — это вот это, мы уже сделали вот то, решили так-то».

Эта система решает проблему простыми средствами: в репозитории хранятся несколько текстовых файлов-записок о проекте. Перед началом любой сессии агент читает записки, после сессии — дописывает, что произошло. Следующая сессия стартует уже «в курсе».

• ✅ Без API-ключей и платных сервисов
• ✅ Работает с любой моделью и любым агентом (Claude, ChatGPT, Gemini, Copilot, Codebuff, локальные модели — любые)
• ✅ Вся память лежит в git: версионируется вместе с кодом, не теряется
• ✅ Платформенезависимо: не зависит от того, где вы запускаете агента

Настоятельно рекомендуется использовать Git в любом проекте — в нём живут все записки: они версионируются, не теряются и страхованы от краша. Git нет? Просто попросите ИИ-агента: «Установи Git и подключи систему памяти к моему проекту» — сам подскажет, установит и активирует.

---

Что внутри

Файл	Зачем он
.project-memory/AGENTS.md	Правила игры. Что читать в начале сессии и что писать в конце. Агент читает его первым.
.project-memory/CONTEXT.md	Снимок проекта сейчас: что это, на чём написано, как запускать, что дальше.
.project-memory/SESSIONS.md	Журнал сессий. append-only: после каждой сессии сюда дописывается запись, что было сделано. Старые записи не правятся.
.project-memory/DECISIONS.md	Решения. Почему выбрали так, а не иначе, и какие ограничения это накладывает.
.project-memory/archive/	Архив. Если журнал сессии становится слишком большим, старые записи уезжают сюда по месяцам.
.project-memory/.in-progress.md	Черновой блокнот сессии. Краткие заметки по ходу работы — страховка на случай краша.
.project-memory/README.md	Памятка для пользователя. Что в папке, зачем каждый файл и откуда система.
.project-memory/memory-autosave.sh	Спасательный коммит. Фиксирует несохранённую память в git одной командой.
.project-memory/pre-commit	Опциональный хук. Подмешивает изменения памяти в каждый коммит автоматически.

---

Как пользоваться — протокол из 4 шагов

Перед началом работы (сессия)

1. Прочитать .project-memory/AGENTS.md — правила.
2. Прочитать .project-memory/CONTEXT.md — текущее состояние проекта.
3. Прочитать последние 3 записи в .project-memory/SESSIONS.md — что было в недавних сессиях.

Всё. Теперь агент «в курсе».

После окончания работы

1. Дописать запись в .project-memory/SESSIONS.md по шаблону:

   ## 2026-11-08 — Название сессии
   - Request: что просили.
   - Done: что сделано.
   - Verified: что проверено и с каким результатом.
   - Not done / limitations: что осталось.
   - Next: следующий шаг.
   
   

   (запись начинается с пустой строки; старые не трогаем).
2. Обновить .project-memory/CONTEXT.md — разделы «Текущее состояние» и «Следующие шаги».
3. Записать решение в .project-memory/DECISIONS.md, если принималось архитектурное решение.
4. По желанию ротировать архив — если в журнале больше 8 записей, самые старые уезжают в archive/YYYY-MM.md. (Необязательно: журнал можно вести бесконечно.)

Пользователю в конце сессии ничего не нужно. Все шаги выше выполняет сам агент — достаточно сказать «готово» или просто закрыть чат. Даже если вы ничего не сказали — ничего не потеряется: заметки из .in-progress.md остаются на диске, агент при следующем запуске сам восстановит их и доделает закрывающую работу.

---

---

Пример: как выглядит обычная сессия

Агент (начало): «Прочитал .project-memory/AGENTS.md, CONTEXT.md и последние 3 записи журнала. Проект — это веб-сервис на Flask, вчера закончили аутентификацию, следующий шаг — API для загрузки файлов. Продолжаем?»

Вы: «Да, делай API загрузки файлов.»

Агент (конец): «Готово. Дописал запись в SESSIONS.md, обновил CONTEXT.md (статус: API загрузки готов, следующий шаг — тесты).»

В следующий раз агент начнёт с той же точки.

---

Что если сессия упала (краш, пропала электричество)

Протокол рассчитан не только на «идеальное завершение», но и на аварийные сценарии:

1. По ходу работы агент ведёт .project-memory/.in-progress.md — краткие заметки о сделанном (маркер status: open). Если процесс умирает, прогресс не теряется: он уже на диске.
2. Следующая сессия при старте находит status: open и понимает: «предыдущая сессия аварийно завершилась». По протоколу заметки превращаются в запись журнала с пометкой о восстановлении, а вас предупреждают, что было спасено.
3. .project-memory/memory-autosave.sh — одной командой фиксирует все несохранённые изменения памяти в git. Запускается при старте сессии, чтобы даже незакоммиченная память не пропала между сессиями.
4. (Опционально) pre-commit хук — подмешивает изменения памяти в любой коммит, чтобы они случайно не остались незакоммиченными. Включение одной командой: git config core.hooksPath .project-memory.

---

Слои памяти (что что)

Память делится на три уровня, чтобы любой агент мог открыть проект и сразу понять, чем заниматься:

L0 — Universal protocol (AGENTS.md)

Инструкция: что читать, когда обновлять, как восстанавливать после краша, какую команду запускать для проверки. Проект-независимый: можно вынести в отдельный шаблон и подключить к любому другому репозиторию.

L1 — Local scratch (.in-progress.md)

Локальный след текущей сессии с маркером status: open/closed. Едиственная запись, которая сохраняется по ходу работы (не в конце). При аварийном завершении следующий агент восстанавливает её в журнал.

L2 — Project state (transferable)

• TASK.md — текущая задача: статус, цель, что сделано, следующий конкретный шаг, проверочные команды, блокеры, ссылки на решения.
• QUESTIONS.md — только нерешённые вопросы и отвергнутые альтернативы с причиной.
• CONTEXT.md — проект в целом.
• DECISIONS.md — принятые решения с причиной и отвергнутыми альтернативами.
• SESSIONS.md — журнал (полная история).

Почему так:

• Агент при старте не должен «угадывать» текущий ход из журнала. Θεός читает TASK.md и сразу видит, что делать.
• Компактные файлы (≤ ~60 строк активной части) — чтобы память не раздувала контекст.

---

Как это выглядит в жизни

Первый запуск (агент открывает проект)

1. Читает .project-memory/AGENTS.md (протокол).
2. Читает TASK.md — видит, что делать сейчас (или что простаивает).
3. Читает QUESTIONS.md — видит, какие решения ещё не приняты.
4. Читает CONTEXT.md — проект в целом.
5. Читает последние 3 записи SESSIONS.md — недавний контекст.
6. Даёт короткий статус: «проект X, в данный момент — задача Y, открытые вопросы — Z, можно продолжать?".

Во время работы

Агент обновляет по событиям, а не по каждому сообщению:

• Сделал значимый шаг? Обновил TASK.md (статус, next step).
• Принял решение? Добавил в DECISIONS.md и обновил TASK.md.
• Закрыл/открыл вопрос? Обновил QUESTIONS.md.
• Изменился контекст проекта? Обновил CONTEXT.md.

После сессии

Агент дописывает SESSIONS.md (журнал), обновляет TASK.md (статус idle/продолжение), обновляет CONTEXT.md, закрывает .in-progress.md (status: closed). Всё фиксируется в git вместе с кодом.

Что если краш, пропал питание, упал сервер?

1. Агент ведёт .in-progress.md по ходу (локальный след).
2. Следующий запуск: агент видит status: open, превращает заметки в запись SESSIONS.md с пометкой о восстановлении, сообщает вам, что было спасено, и ждёт подтверждения.
3. .project-memory/memory-autosave.sh — спасает несохранённую память в git.
4. .project-memory/pre-commit — молча проверяет состояние памяти при любом коммите, блокирует только при серьёзных проблемах (не устарело, нет битых ссылок, нет секретов).

---

Как перезапустить проект для любого приложения / агента

Самое важное: папка готова к открытию в любой среде, где агент умеет читать и писать файлы.

Если проект лежит в git

1. Агент читает .project-memory/AGENTS.md → .project-memory/TASK.md → .project-memory/QUESTIONS.md → .project-memory/CONTEXT.md → последние 3 SESSIONS.md.
2. Получает короткое резюме и продолжает.

Если нет git-доступа (только файлы)

Агент читает те же файлы локально. Память — просто текстовые файлы; без git-доступа агент всё равно видит всё, кроме git-версии.

Если даёте ссылку на GitHub

Дайте агенту ссылку на репозиторий или на AGENTS.md. Например:

https://github.com/<user>/<repo>/raw/main/.project-memory/AGENTS.md

Агент прочитает протокол и сможет работать.

---

Что делает агент при первом открытии проекта сюда

Чтобы было явно, агент должен:

1. Читать AGENTS.md.
2. Прочитать TASK.md, QUESTIONS.md, CONTEXT.md, последние 3 SESSIONS.md.
3. Дать краткое резюме по задаче и открытым вопросам.
4. Ждать подтверждения перед новыми действиями.

Если агент не подхватывает AGENTS.md автоматически — добавьте в первое сообщение: «Работай по протоколу из .project-memory/AGENTS.md».

---

Что если SESSIONS.md стал огромным?

Ротация: старые записи уезжают в archive/YYYY-MM.md, в журнале остаются последние 8. Если больше 8 — скрипт memory-check.sh предупреждает.

---

Что делать разработчику, чтобы подключить память к своему проекту

1. Скопируйте .project-memory/ в корень вашего проекта.
2. Заполните TASK.md (если есть текущая задача) и CONTEXT.md.
3. В работе с агентом: используйте протокол из AGENTS.md.

---

Установка

Вариант A — вы используете агент с доступом к файлам (рекомендуется)

1. Убедитесь, что .project-memory/ лежит в корне проекта.
2. В первом сообщении агенту: «Работай по протоколу из .project-memory/AGENTS.md».

Вариант B — публикация на GitHub

1. Загрузите репозиторий на GitHub.
2. Дайте агенту ссылку на репозиторий или на AGENTS.md.
3. Без настроек на стороне GitHub — это обычные markdown-файлы.

---

Структура файлов

Файл	Зачем он
.project-memory/README.md	Памятка для пользователя: что в папке, зачем, откуда
.project-memory/AGENTS.md	Протокол (L0)
.project-memory/TASK.md	Текущая задача (L2)
.project-memory/QUESTIONS.md	Открытые вопросы (L2)
.project-memory/CONTEXT.md	Проект в целом (L2)
.project-memory/DECISIONS.md	Принятые решения (L2)
.project-memory/SESSIONS.md	Журнал (жизнь)
.project-memory/archive/	Архив старых сессий
.project-memory/.in-progress.md	Локальный след сессии (L1)
.project-memory/memory-check.sh	Проверка здоровья памяти (вызывается хуком)
.project-memory/memory-autosave.sh	Спасательный коммит
.project-memory/pre-commit	Опциональный git-хук: подмешивает память в коммит, запускает проверку

---

FAQ

Работает с моей моделью/агентом? Да, если агент умеет читать и писать файлы.

Нужны ли API? Нет, только текстовые файлы.

Можно ли работать без агента? Да, вручную по тем же правилам.

Что мне делать в конце сессии? Ничего. Агент сам допишет журнал, обновит файлы и сделает коммит. Просто закройте чат — если вы ничего не сказали, агент при следующем запуске сам восстановит всё из .in-progress.md.

Что если краш? .in-progress.md уже на диске; следующий агент восстановит.

Можно ли дать ссылку любому агенту? Да, на репозиторий или на AGENTS.md.

Кому принадлежит? Свободное использование.

---

Лицензия

Проект распространяется под MIT — см. файл LICENSE.