Цель лекции
Показать, какие виды памяти особенно важны для агента, работающего с кодовой базой.
Ожидаемый результат
Читатель понимает, как память делает coding agent более устойчивым и полезным: помогает соблюдать стиль проекта, не повторять ошибки, использовать прошлые решения и при этом проверять актуальное состояние репозитория.
Зачем это нужно
Coding agent отличается от обычного chatbot тем, что работает в живой среде:
- читает файлы;
- меняет код;
- запускает команды;
- видит ошибки;
- учитывает инструкции проекта;
- продолжает работу после неудачных попыток;
- должен уважать существующую архитектуру.
Память здесь нужна не для "личности" агента, а для инженерной непрерывности. Агент должен понимать, что это за проект, как в нем принято работать, какие команды уже запускались, какие ошибки возникали и какие решения были приняты.
Но есть важное правило:
Текущее состояние репозитория важнее старой памяти.
Если memory говорит "тесты запускаются через Jest", а package.json показывает Vitest, агент должен доверять источнику истины в кодовой базе.
Основная идея
Coding agent нуждается в проектной, процедурной и эпизодической памяти: что за проект, как в нем принято работать и какие ошибки уже встречались.
Для coding agent особенно важны четыре слоя:
- project memory: архитектура, соглашения, инструкции;
- episodic memory: прошлые задачи, tool calls, ошибки и решения;
- procedural memory: workflow, команды, checklist;
- retrieval over code/docs: актуальный контекст из файлов и документации.
Эти слои должны работать вместе, но не заменять чтение текущего кода.
Ключевые термины
| Термин | Короткое определение |
|---|---|
Project memory |
Устойчивый контекст конкретного репозитория: архитектура, conventions, команды, ownership. |
Declarative memory |
Память, записанная в файлах: README, AGENTS.md, specs, architecture notes. |
Episodic coding memory |
История конкретных задач: что меняли, какие команды запускали, какие ошибки получили. |
Procedural coding memory |
Повторяемые workflows: как тестировать, как править, как оформлять финальный отчет. |
Source of truth |
Текущий авторитетный источник фактов: файлы, git state, package metadata, docs. |
Tool trace |
Журнал действий агента: read, edit, command, test, error, result. |
Secret leakage |
Попадание секретов из кода, логов или env в память или ответ. |
Архитектура памяти coding agent
Ключевая особенность: files and git state находятся рядом с памятью, но имеют более высокий приоритет для фактов о текущем проекте.
Что стоит помнить
Coding agent может помнить:
- архитектурные решения;
- стиль кода;
- naming conventions;
- тестовый стек;
- команды сборки и проверки;
- ограничения окружения;
- прошлые ошибки;
- найденные обходные пути;
- user preferences по отчетам;
- паттерны изменения файлов;
- связанные документы и спецификации.
Пример useful memory:
scope: repository
type: procedural
content: "Before final response, check edited modules for unfinished-work markers and report whether any remain."
source: repeated successful workflow
Пример опасной memory:
content: "Use token sk-..."
source: tool log
Такая запись должна быть заблокирована policy.
Project memory через файлы и спецификации
В coding scenarios часть памяти лучше хранить декларативно.
Примеры:
README.md;AGENTS.md;- architecture notes;
- ADR documents;
- module plans;
- coding standards;
- contribution guide;
- test instructions;
- design specs.
Преимущество файлов:
- они видны людям;
- проходят code review;
- версионируются git;
- легко цитируются;
- могут быть source of truth;
- не зависят от скрытого профиля агента.
Пример:
AGENTS.md:
"Use apply_patch for manual edits. Do not overwrite intro drafts."
Это procedural/project memory, но она живет в репозитории, а не в vector DB.
Episodic memory через логи задач и tool calls
Episodic memory отвечает на вопрос:
Что происходило в прошлый раз?
Для coding agent это:
- какие файлы читались;
- какие файлы изменялись;
- какие команды запускались;
- какие ошибки возникали;
- какие test failures были исправлены;
- какие решения принял агент;
- где пользователь остановил или изменил задачу.
Пример эпизода:
Task:
"Написать лекцию 8.3."
Events:
- read lesson plan
- read previous lesson ending
- expanded outline
- checked headings
- removed unfinished-marker-like text from example
Learned:
- Module lectures should end with transition to next module.
Episodic memory полезна для восстановления контекста после long task или interruption.
Procedural memory через workflow
Procedural memory хранит то, как агент должен работать.
Пример workflow:
For Markdown lecture task:
1. Read skill instructions.
2. Read target lesson plan.
3. Read adjacent lessons.
4. Expand into full lecture.
5. Include terms, diagram/table, mistakes, summary, questions.
6. Check headings and unfinished-work markers.
7. Report concise final summary.
Для coding agent procedural memory может включать:
- как запускать tests;
- как проверять formatting;
- как читать logs;
- как минимально редактировать файлы;
- как не трогать unrelated changes;
- как оформлять финальный ответ;
- как обращаться с approvals.
Хорошая procedural memory уменьшает повторяемость ошибок.
Retrieval по кодовой базе и документации
Coding agent должен уметь доставать relevant context из:
- source files;
- configs;
- tests;
- docs;
- issues;
- previous diffs;
- logs;
- local instructions;
- package metadata.
Retrieval может быть:
- lexical:
rg, exact symbol search, filename search; - structural: language server, AST, imports, call graph;
- semantic: embeddings over docs/code;
- historical: git history, previous tasks;
- hybrid: сочетание нескольких signals.
Правильная стратегия зависит от вопроса.
| Вопрос | Лучший первый retrieval |
|---|---|
| "Где объявлена функция?" | Symbol/file search |
| "Почему тест падает?" | Test output + related code |
| "Как в проекте оформляют лекции?" | Adjacent files + instructions |
| "Была ли похожая ошибка?" | Episodic logs + semantic search |
| "Какая команда запускает тесты?" | README/package config + previous successful commands |
Приоритет источников
Для coding agent нужен порядок доверия.
| Источник | Обычно приоритет |
|---|---|
| Current user instruction | Очень высокий |
| System/developer/repo instructions | Очень высокий |
| Current files | Высокий для фактов о коде |
| Tests/output | Высокий для поведения |
| Project docs | Высокий, если актуальны |
| Old memory | Средний, требует проверки |
| Past episode | Средний, зависит от сходства |
| Model recall | Низкий без проверки |
Пример:
Old memory:
"Project uses npm."
Current files:
package-lock absent, pnpm-lock present, package scripts use pnpm.
Expected:
Agent trusts current files and updates old memory if appropriate.
Риски
| Риск | Пример | Защита |
|---|---|---|
| Устаревшая архитектура | Агент применяет старый module layout. | Read current files, verify with search. |
| Wrong workflow | Агент запускает не те tests. | Source-of-truth commands, successful-command memory. |
| Repeated mistakes | Агент снова делает уже исправленную ошибку. | Episodic memory + regression checklist. |
| Secret leakage | Env token попадает в memory/log/final answer. | Redaction, policy, never store secrets. |
| Overfitting to past episode | Похожая, но не та ошибка ведет к неправильному fix. | Compare current evidence. |
| Unrelated changes | Агент затирает пользовательские правки. | Git status, scoped diffs, no destructive commands. |
Метрики
Для coding agent полезны:
| Метрика | Что показывает |
|---|---|
| Task success rate | Задача решена без ручной доработки. |
| Test pass rate | Изменения проходят релевантные проверки. |
| Repeated error rate | Агент не повторяет прошлые ошибки. |
| Context relevance | Прочитаны ли нужные файлы, а не случайный контекст. |
| Diff quality | Изменения точные и не трогают лишнее. |
| Command selection accuracy | Агент выбирает правильные команды проекта. |
| Secret handling incidents | Нет ли утечек из logs/env/files. |
| User correction rate | Как часто пользователь поправляет направление. |
Метрики должны связывать memory с реальным качеством engineering output.
Мини-кейс: повторное использование прошлого решения
Episode:
Agent tried npm test.
Command failed: project uses pnpm.
Agent read package manager lockfile.
Agent used pnpm test successfully.
Future task:
User:
"Проверь изменения."
Good behavior:
- agent checks current repo files;
- sees pnpm lockfile still present;
- uses pnpm command;
- records result;
- does not assume forever for other repositories.
Bad behavior:
- agent globally remembers "always use pnpm";
- applies it in unrelated repo;
- ignores current package metadata.
Scope is the difference between helpful procedural memory and harmful habit.
Мини-кейс: написание лекций в этом курсе
For this repository, useful coding-agent memory:
Project:
AI Agent Memory Guide 101
Conventions:
- Markdown lectures in Russian
- preserve lesson numbering
- use conceptual explanations
- include diagrams/tables and self-check questions
- do not modify intro drafts
- check unfinished-work markers before final response
When user says:
"Напиши последовательно лекции в модуле 10"
Agent should:
- read module files;
- read neighboring transitions;
- expand plans;
- preserve structure;
- check module files;
- summarize changed paths.
Это пример procedural + project memory in action.
Типичные ошибки
Ошибка 1: полагаться на старую память вместо чтения файлов.
В коде текущий source of truth почти всегда важнее remembered fact.
Ошибка 2: сохранять tool logs без фильтрации.
Логи могут содержать secrets, tokens, paths, customer data.
Ошибка 3: делать memory глобальной.
Project convention из одного repo не должен автоматически применяться в другом.
Ошибка 4: не хранить failed attempts.
Иногда самая полезная память - что уже не сработало.
Ошибка 5: не различать episodic и procedural memory.
Один прошлый эпизод не всегда должен становиться workflow.
Ошибка 6: не проверять результат.
Память помогает выбрать действие, но tests и diffs подтверждают качество.
Краткое резюме
Coding agent использует память для инженерной непрерывности: project memory, episodic logs, procedural conventions и retrieval по кодовой базе. Но эта память должна быть scoped, проверяемой и подчиненной текущему состоянию файлов.
Главная мысль: хорошая память делает coding agent менее забывчивым, но не должна делать его самоуверенным.
Вопросы для самопроверки
- Почему current repository state должен иметь более высокий приоритет, чем old memory?
- Чем project memory отличается от episodic coding memory?
- Какие данные из tool logs нельзя сохранять без фильтрации?
- Как procedural memory помогает coding agent не повторять ошибки?
- Какие метрики показывают, что память улучшает качество изменений?
Что дальше
В следующей лекции мы перейдем к enterprise knowledge agent: там memory layer становится не только вопросом retrieval quality, но и вопросом permissions, audit, tenant isolation и compliance.