---
title: "Файловая память для ИИ-агента: воркспейс из markdown, который переживает сессию"
canonical_url: https://evstygney.ru/articles/ai-agent-file-memory/
date_published: 2026-08-13
date_modified: 2026-08-13
author: Егор (https://evstygney.ru/about/)
summary: "Как устроить память ИИ-агента на файлах: три контракта воркспейса, паттерн «шим», тест инструкции свежим агентом и грабли дистрибуции."
tags: ["ИИ и инструменты"]
---

# Файловая память для ИИ-агента: воркспейс из markdown, который переживает сессию
**TL;DR.** Контекст ИИ-агента умирает вместе с сессией: завтра он снова не знает ни ваших проектов, ни принятых решений, ни того, что вы уже пробовали. Четыре месяца я живу с файловым решением: память проектов, карта, правила и база знаний лежат в markdown на диске, агент читает их на входе в работу и обновляет на выходе. В статье — архитектура из трёх контрактов, разбор допущений, паттерн «шим» для навыков и тест инструкции свежим агентом в режиме «трудный пользователь»: 16 находок, 7 правок. Каркас — в [репозитории под MIT](https://github.com/evstygney/ai-workspace-starter). Чтение займёт минут десять.

**Простыми словами.** ИИ-агент — это LLM с доступом к файлам и терминалу (Claude Code, Cursor, Codex CLI). Он читает и пишет файлы на вашем диске по инструкциям на естественном языке. Дальше считаю, что вы таким пользовались.

## Почему не хватает того, что есть из коробки

Задача: в понедельник агент помог с проектом, в четверг открываю новую сессию — и хочу продолжить с места, где остановились, а не пересказывать проект заново. Штатные способы упираются каждый в свой предел.

**Длинная сессия.** Контекстное окно конечно, при переполнении история сжимается автосаммари. Что именно выживет при сжатии — вы не контролируете: первыми обычно теряются мотивировки решений («почему выбрали B, а не A»), сами решения остаются. И сессия всё равно когда-нибудь закрывается.

**Один большой CLAUDE.md.** Рабочий приём до определённого размера. Дальше файл превращается в свалку: контексты десяти проектов вперемешку, агент тащит в каждую задачу всё подряд, стоимость и шум растут.

**Встроенная память агента.** У Claude Code есть автоматическая память. Она полезна, но непрозрачна ровно настолько, насколько автоматична: вы не выбираете, что в неё попадёт, она не переносится между инструментами и не читается глазами как единый документ.

**RAG поверх заметок.** Векторная база, пайплайн индексации, обновление эмбеддингов — инфраструктура ради задачи «не пересказывать проект». Для личной работы одного человека это пушка по воробьям; к тому же результат поиска по эмбеддингам не отревьюишь так же просто, как файл.

Файловый воркспейс закрывает ту же задачу дешевле: обычные папки и markdown, полная прозрачность (всё читается глазами и лежит в git), переносимость между агентами. Плата — дисциплина структуры. Её и разбираем.

## Архитектура: три контракта

За четыре месяца структура устоялась такой (35 проектов, база знаний на 15 тем):

```
workspace/
├── main.md                  ← карта: все проекты и разделы, по строке на каждый
├── CLAUDE.md                ← контракт поведения: агент читает сам при старте
├── AGENTS.md                ← однострочник «читай CLAUDE.md» для других агентов
├── .claude/skills/          ← автозапуск навыка-хранителя (шим, о нём ниже)
├── _inbox/                  ← приёмник непонятного; разбирается раз в неделю
├── _meta/templates/         ← шаблоны: README проекта, память, wiki-заметка
├── rules/global/            ← правила устройства воркспейса
├── skills/                  ← навыки агента (источники)
├── knowledge-base/
│   ├── AGENTS.md            ← контракт ведения базы знаний
│   └── <домен>/main.md      ← карта домена + страницы
└── projects/<имя>/
    ├── README.md            ← что это и зачем
    ├── memory.md            ← память проекта: агент читает первым
    ├── docs/ prompts/ assets/
    └── app/                 ← код, отдельный git-репозиторий
```

Несущих элемента три, остальное — обвязка.

**Контракт №1: memory.md на проект.** Файл с фиксированными секциями: что это за проект, ключевые решения с мотивировками, текущий статус, следующий шаг, договорённости с агентом. Правило в CLAUDE.md: при входе в проект читать память первой, после значимого шага — обновлять. Новая сессия стартует не с нуля, а с последнего чекпоинта. По сути это ручной, человекочитаемый снапшот контекста — и в отличие от автосаммари, что в него попадает, решаете вы (точнее, агент по вашим правилам, а вы ревьюите глазами).

**Контракт №2: main.md как карта.** По строке на проект и домен знаний. Агенту не нужно сканировать дерево, чтобы понять, что где лежит: одна загрузка карты — и он знает, куда идти. Это же спасает от дублей: прежде чем создать проект, агент сверяется с картой.

**Контракт №3: правила поведения, записанные файлами.** Договорённость «клади файлы аккуратно» агент забудет со сменой сессии — контракт должен лежать там, откуда он читается автоматически. У меня это три уровня: CLAUDE.md в корне (краткий контракт, подхватывается при старте), правило в `rules/` (полная версия с обоснованиями) и навык-хранитель в `skills/` (операционные рецепты: куда положить, как назвать, какой frontmatter). Тройное дублирование намеренное: инструкции для LLM исполняются вероятностно, и вероятность соблюдения растёт с числом мест, откуда правило может попасть в контекст.

**Замечание.** База знаний устроена отдельным паттерном — три слоя с разными правами записи: `raw/` (первоисточники, агент только читает), wiki-страницы (агент пишет и перезаписывает), схема-контракт (меняется редко, руками). Плюс правило противоречий: новый факт, конфликтующий со старым, не затирает его молча, а помечается блоком с указанием источников. Это тема отдельной статьи; схема лежит в [references репозитория](https://github.com/evstygney/ai-workspace-starter/blob/main/references/knowledge-base.md).

## Допущения, которые пришлось принять

Каждое решение в структуре — ответ на конкретный отказ. Три показательных.

**Архив вместо удаления.** Агент (и человек) плохо предсказывает, что «точно больше не понадобится». Правило: ничего не удаляется, устаревшее переезжает в `archive/` рядом с оригиналом. Перемещение обратимо, удаление — нет, а диск дешевле восстановления удалённого.

**Латиница и kebab-case в путях.** Кириллица и пробелы в путях ломаются на стыках: git на разных ОС, shell-скрипты, часть инструментов. Контент заметок — на любом языке, пути — только `latin-kebab-case`. Скучное правило, которое экономит часы отладки.

**Код отдельно от заметок.** Код проекта живёт в `app/` со своим git-репозиторием; workspace-репозиторий его игнорирует (`projects/*/app/` в .gitignore). У кода и заметок разные жизненные циклы: заметки хочется коммитить пачкой раз в день, код — атомарно и с CI.

## Паттерн «шим»: один источник для навыка

Инженерная деталь, на которой я застрял. Claude Code автоматически подхватывает навыки из скрытой `.claude/skills/`, а «витринная» `skills/` воркспейса для него — просто папка с файлами. Хочется и автозапуск, и видимый пользователю источник. Держать две копии — гарантированный рассинхрон: правишь одну, вторая молча устаревает.

**Решение.** В `.claude/skills/workspace-organizer/SKILL.md` кладётся файл-переадресация: тот же YAML-frontmatter с description (по нему движок решает, когда навык триггерить), а вместо тела — три строки: «прочитай и выполни `../../../skills/workspace-organizer/SKILL.md`; здесь ничего не редактировать». Автотриггер работает, источник один, дублируется только description. Если источник переименуют или удалят — шим прямым текстом скажет об этом пользователю и предложит восстановить навык повторным запуском мастера.

## Инструкция для LLM — это код. Тестируйте соответственно

Каркас воркспейса я упаковал в скилл-мастер: интервью из пяти блоков (путь, кто вы, проекты, темы, настройки) → план → постройка → заполнение памяти ответами. Написал, трижды перечитал, всё выглядело однозначным.

Потом я запустил тест: **отдельный экземпляр агента, который скилл никогда не видел**, получил инструкцию «выполни этот SKILL.md буквально, не привнося своих представлений о замысле» и сценарий пользователя, который на каждый вопрос отвечает «не знаю». Плюс обязанность: журналировать каждое место, где инструкция неоднозначна, невыполнима или потребовала догадки.

Свежий агент дошёл до конца — воркспейс собрался, все 16 файлов каркаса на месте. И принёс **16 задокументированных неоднозначностей**. Примеры, за которые мне до сих пор слегка стыдно:

- **План не совпадал с постройкой.** Дерево, которое мастер показывает пользователю для подтверждения («строим вот это, ок?»), было короче того, что реально создаётся на следующем этапе. Пользователь подтверждал один набор, получал другой.
- **Невыполнимая ветка.** «Если тем для базы знаний нет — создай домен по профессии из блока 2». А в блоке 2 пользователь сказал «работаю и всё». Профессии нет, ветка виснет. Агент выкрутился сам (создал нейтральный домен `work`), но это была его догадка, не моя инструкция.
- **Самопротиворечие.** «Создай пустую папку `_inbox/` (и положи в неё README)». Папка с файлом — не пустая. Мелочь, но свежий исполнитель споткнулся и записал в журнал.
- **Молчание про плейсхолдеры.** Шаблоны копируются в воркспейс «как есть», с `{{PROJECT_NAME}}` внутри — а конвенция «подставляй значения вместо `{{...}}`» нигде не была записана для будущих сессий.
- **Пустые папки и git.** Каркас создаёт пустые `docs/`, `prompts/`, `assets/` — а git пустых папок не хранит. Первый же клон воркспейса потерял бы половину структуры. В инструкции не было ни слова.

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

**Чем хорош метод.** Он дешёвый: один запуск свежего агента с журналом неоднозначностей находит то, чего автор сам не видит, — автор знает замысел и достраивает его поверх текста. Это ровно code review, только ревьюер — та же система, что будет исполнять.

**Чем плох.** Недетерминизм: один прогон — одна траектория. Тот факт, что агент сегодня выкрутился из невыполнимой ветки, не значит, что выкрутится завтра. Тест снижает вероятность отказа, но не даёт гарантий — как и любой тест, впрочем.

## Грабли дистрибуции, собранные лбом

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

| Грабля | Что происходит | Фикс |
|---|---|---|
| `: ` (двоеточие с пробелом) внутри YAML-description | frontmatter не парсится, скилл не подхватывается | переформулировать без двоеточий или закавычить значение |
| GitHub ZIP распаковывается в `<repo>-main` | скилл лежит не по ожидаемому пути, «не работает» | явная инструкция переименования в README |
| `%USERPROFILE%` в команде установки | в PowerShell не раскрывается — создаётся папка с буквальным именем | `$env:USERPROFILE` |
| `~/.claude` скрыта в Finder | пользователь без терминала не может найти папку скиллов | `⇧⌘G` → «Переход к папке» в инструкции |
| Свежеустановленный скилл не виден в текущей сессии | «сказал волшебную фразу — ничего не произошло» | установочная фраза велит агенту выполнить SKILL.md сразу, не дожидаясь перезапуска |
| Агент по голой ссылке строит «по мотивам» | вместо эталонного каркаса — импровизация по README | требование в тексте скилла: шаблоны брать из файлов, по памяти не восстанавливать |

Последняя строка — любимая. Дай агенту ссылку на репозиторий без инструкций — он прочитает README, поймёт идею и уверенно построит нечто похожее, но своё. Для тысячи пользователей это тысяча разных воркспейсов. Лечится одной строкой в скилле, но додуматься до неё надо.

## Где подход не работает

- **Команда.** Всё выше — про одного человека. Совместная память на файлах упирается в merge-конфликты человеческих решений; для команды нужен другой контур согласования, у меня его нет.
- **Поиск по смыслу.** Здесь нет эмбеддингов: агент ходит по картам (main.md) и grep'у. На моих объёмах хватает; если у вас тысячи заметок с перекрёстными смысловыми запросами — RAG вернётся в разговор.
- **Протухание памяти.** memory.md обновляет агент, агент подчиняется правилу вероятностно. Без еженедельной ревизии («разбери inbox, обнови статусы») память дрейфует от реальности. Ритуал занимает минут двадцать, но он обязателен — это цена подхода.
- **Другие агенты.** Структура переносима (markdown есть markdown), но автозапуск навыков — механика Claude Code. В Cursor тот же контракт приходится скармливать через AGENTS.md, триггер слабее.

## Краткие выводы

1. Память агента между сессиями решается файлами: memory.md на проект + карта + правила, записанные там, откуда агент читает их автоматически. Дорогая инфраструктура для этой задачи не нужна.
2. Инструкции для LLM исполняются вероятностно. Контракт стоит дублировать по уровням (CLAUDE.md → правило → навык), а критичные конвенции записывать явно, даже если агент «и так догадался».
3. Инструкция для LLM — это код. Тестируйте её как код: свежий исполнитель без знания замысла + сценарий худшего пользователя + журнал неоднозначностей. 16 находок на «трижды перечитанном» тексте — моя цена этого урока.
4. Дистрибуция текста ломается как софт: YAML, пути, скрытые папки, порядок активации. Таблица граблей выше сэкономит вам вечер.

Каркас воркспейса, скилл-мастер с интервью, шаблоны и обе справки — в репозитории [ai-workspace-starter](https://github.com/evstygney/ai-workspace-starter) (MIT). Ставится за 15 минут, работает без программирования.

А ваш агент завтра утром помнит, почему вы вчера выбрали вариант B, а не A? Если нет — посчитайте, сколько минут в день вы тратите на пересказ контекста, и умножьте на цену своего часа.

Интересно, как эту задачу решаете вы: файлы, встроенная память, RAG, что-то своё? И переживает ли ваш вариант смену сессии без пересказа проекта с нуля?

---
Автор: Егор, маркетинг на языке денег. Telegram: https://t.me/evstygney_ru. Все цифры — модельные прикидки, если не сказано иное.