Урок 5.6. Declarative Memory: память через файлы и спецификации

Цель лекции

Показать, что часть памяти агента может жить в декларативных файлах, а не только в базах данных.

Ожидаемый результат

Читатель понимает, как проектные документы становятся частью memory layer: AGENTS.md, CLAUDE.md, README, specifications, policies, conventions, architecture notes и review process могут быть более надежной процедурной и проектной памятью, чем автоматически извлеченные записи.

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

Когда говорят о памяти агента, часто представляют database, embeddings или vector search. Но в coding agents и командных workflow огромная часть полезной памяти уже существует в файлах:

• AGENTS.md;
• CLAUDE.md;
• README.md;
• CONTRIBUTING.md;
• architecture notes;
• ADR;
• specs;
• TODO;
• style guides;
• policy documents;
• test plans;
• release checklists.

Эти файлы не просто "документация". Для агента они являются памятью проекта:

• как работать;
• что считать source of truth;
• какие команды запускать;
• какие файлы не трогать;
• какой стиль соблюдать;
• какие constraints важны;
• какие decisions уже приняты.

Declarative Memory показывает, что иногда лучший memory store - это не база данных, а явный, reviewable файл в репозитории.

Основная идея

В coding agents и командных workflow файлы спецификаций, инструкций и conventions часто являются самым надежным видом процедурной памяти.

Декларативная память отличается тем, что человек или команда явно записывает правила и контекст в устойчивом артефакте. Агент не выводит их неявно из поведения. Он читает их как авторитетный источник.

Пример:

AGENTS.md:
- Do not overwrite user-authored drafts in intro/.
- guide/content_plan.md is source of truth for course structure.
- New lesson files live under modules/.

Для агента это procedural/project memory. Она управляет действиями: где писать, чего не трогать, какой документ считать главным.

Ключевые термины

Декларативная память против извлеченной

Обе формы нужны.

Declarative memory задает стабильные правила.

Extracted memory помогает агенту учиться из опыта.

AGENTS.md, CLAUDE.md и похожие файлы

Project instruction files часто являются первой точкой входа для coding agent.

Они могут содержать:

• структуру проекта;
• build/test commands;
• style conventions;
• forbidden actions;
• safety rules;
• review expectations;
• naming conventions;
• ownership boundaries;
• workflow notes;
• preferred tools;
• files not to edit.

Пример:

AGENTS.md:
- Use Markdown for all course content.
- Keep new course content under modules/.
- Do not overwrite user-authored drafts in intro/.
- Treat guide/content_plan.md as source of truth.

Это не просто helpful docs. Это procedural memory с project scope.

README и architecture notes

README.md часто хранит public-facing или developer-facing memory:

• что делает проект;
• как запустить;
• какие зависимости;
• basic architecture;
• commands;
• examples.

Architecture notes и ADR хранят:

• почему выбрано решение;
• какие alternatives рассматривались;
• какие constraints важны;
• что не менять без review;
• какие trade-offs приняты.

Для агента ADR - это не только world memory. Это project semantic/procedural memory:

Decision:
- Discount rounding happens before tax.

Implication:
- Do not change tax order without reviewing ADR.

Specifications как устойчивый контекст

Specification задает ожидаемое поведение до реализации.

Примеры:

• product requirements;
• API contract;
• acceptance criteria;
• test plan;
• design spec;
• migration plan;
• course content plan;
• release checklist.

Spec-driven workflow:

Read spec -> implement or write content -> verify against spec -> update artifacts

Для агента спецификация является procedural memory: она направляет future actions.

Пример из курса:

guide/content_plan.md defines high-level structure.
modules/writing_todo.md describes writing workflow.
lesson plan defines local scope.

Если агент пишет лекцию, spec говорит, что должно быть раскрыто.

Policies и conventions в репозитории

Policies и conventions лучше хранить декларативно, если они должны быть видимы команде.

Примеры:

Policy:
- Do not store secrets in memory.

Convention:
- Lesson filenames use lowercase ASCII aliases with underscores.

Workflow:
- Update content plan before structural changes.

Преимущества:

• люди могут review;
• изменения проходят через git;
• агент видит актуальные правила;
• легко ссылаться на source;
• можно обсуждать в PR.

Если policy живет только в скрытой extracted memory агента, команда может не знать, почему он действует так или иначе.

Когда файл лучше базы данных

Файл лучше, если:

• правило должно быть reviewable человеком;
• memory относится к проекту;
• изменения должны версионироваться в git;
• данные небольшие;
• команда должна видеть source of truth;
• нужно offline/local поведение;
• memory является инструкцией или spec;
• update должен проходить code review.

Примеры:

• AGENTS.md для agent instructions;
• CONTRIBUTING.md для workflow;
• ADR для architecture decisions;
• content_plan.md для структуры курса;
• style_guide.md для writing conventions.

Файл хорош тем, что он явный. Агент и человек смотрят на один артефакт.

Когда файл становится недостаточным

Файл перестает справляться, если:

• записей слишком много;
• нужна fine-grained permission model;
• много пользователей или tenants;
• нужны structured queries;
• требуется automatic TTL;
• нужен semantic retrieval по большому corpus;
• данные часто меняются;
• нужна concurrent запись;
• требуется deletion на уровне отдельных records;
• нужен audit по каждому read/write;
• нужно связывать records в graph.

Пример:

User preferences for 100,000 users

Это не стоит хранить в одном Markdown-файле.

Но даже в сложной системе declarative files могут оставаться source of truth для policies и project conventions.

Риск устаревших инструкций

Declarative memory может устаревать.

Примеры:

• README говорит запускать Jest, а проект перешел на Vitest;
• AGENTS.md запрещает трогать папку, которой больше нет;
• spec не соответствует реализации;
• ADR устарел, но не помечен deprecated;
• TODO говорит "planned", хотя задача уже сделана;
• policy file не отражает новую legal requirement.

Агент должен учитывать staleness:

• смотреть даты и source;
• проверять canonical status;
• сравнивать files с текущим code state;
• замечать contradictions;
• спрашивать пользователя при high-risk conflict;
• не считать любой файл вечной истиной.

Декларативная память сильна, но требует governance.

Human governance

Human governance делает declarative memory надежной.

Механизмы:

• code review;
• PR approvals;
• ownership;
• version history;
• deprecation markers;
• changelog;
• style guide updates;
• issue links;
• periodic docs review;
• tests that check docs assumptions.

Роль агента:

• читать declarative memory перед действием;
• ссылаться на source;
• замечать противоречия;
• предлагать обновления;
• не менять policies без явного запроса;
• не считать extracted habit важнее reviewed instruction.

Схема declarative memory

Обновление declarative memory часто проходит через human loop. Агент может предложить изменение, но source of truth меняется через review.

Мини-кейс: курс как declarative memory

В этом репозитории declarative memory включает:

AGENTS.md:
- Writing style and repository rules.

guide/content_plan.md:
- Canonical high-level structure.

modules/todo.md:
- Lesson hierarchy.

modules/writing_todo.md:
- Writing workflow.

lesson_XX.md:
- Local lesson plan before expansion.

Когда агент пишет лекцию, он не должен полагаться только на extracted memory вроде "кажется, лекции обычно длинные". Он должен читать declarative sources.

Правильный workflow:

1. Read target lesson plan.
2. Read content_plan.md section.
3. Read neighboring lesson for continuity.
4. Apply writing skill.
5. Preserve structure and scope.

Мини-кейс: coding repo

Coding repo может иметь:

AGENTS.md:
- Use pnpm.
- Do not edit generated files.
- Run targeted tests before final response.

CONTRIBUTING.md:
- Branch naming and PR process.

ADR-007.md:
- Use event sourcing for task state.

README.md:
- Local setup and commands.

Для агента это project memory. Если user request конфликтует с policy, агент должен учитывать priority.

Пример:

User:
"Просто поправь generated file напрямую."

AGENTS.md:
"Do not edit generated files; update source schema."

Агент должен объяснить constraint и работать с source schema, если задача действительно требует изменения generated output.

Declarative + extracted memory

Лучший подход часто комбинированный.

Declarative memory:

Project rule:
- Run targeted tests for code changes.

Extracted reflection:

Previous failure:
- Shared helper changes also require dependent module tests.

Together:

For code changes, run targeted tests.
For shared helpers, include dependent module tests.

Declarative memory задает base rules. Extracted memory добавляет lessons learned.

Но extracted memory не должна молча изменять declarative policy. Если learned lesson должен стать rule, его лучше предложить как update to spec.

Типичные ошибки

Ошибка 1: игнорировать файлы инструкций.

Агент без чтения AGENTS.md часто нарушает локальные правила проекта.

Ошибка 2: считать declarative memory обычной документацией.

Для агента она может быть active procedural memory.

Ошибка 3: доверять устаревшему README больше текущего source.

Документы тоже имеют staleness.

Ошибка 4: менять policy files без явного запроса.

Policy updates требуют human governance.

Ошибка 5: хранить персональную память многих пользователей в project file.

Для user memory с privacy и deletion нужен другой storage.

Ошибка 6: не отличать spec от implementation.

Spec говорит, что должно быть. Code/tool results показывают, что сейчас есть.

Ошибка 7: не связывать extracted lessons с declarative updates.

Полезный lesson learned может остаться hidden habit вместо reviewed convention.

Краткое резюме

Declarative Memory - это память, явно записанная в файлах, спецификациях, policies, conventions и architecture notes. Для coding agents и командных workflows она часто является самым надежным источником процедурной и проектной памяти.

Файлы хороши, когда правила должны быть human-reviewable, versioned, local to project и visible to team. Они хуже подходят для large-scale user memory, high-frequency events, fine-grained permissions и semantic retrieval по большим корпусам.

Зрелая система сочетает declarative memory с extracted memory: правила живут в reviewed specs, а опыт агента предлагает updates через human governance.

Вопросы для самопроверки

1. Чем declarative memory отличается от extracted memory?
2. Почему AGENTS.md можно считать procedural memory?
3. Когда файл лучше базы данных?
4. Какие риски создает устаревшая инструкция?
5. Почему learned lesson не должен молча становиться project policy?

Что дальше

Module 05 показал основные архитектурные паттерны памяти: простые MVP-подходы, tiered memory, OS-style virtual context, hybrid vector-graph retrieval, event-sourced agents и declarative memory. В следующем модуле мы соберем эти идеи в системный дизайн memory layer: router, extractor, policy engine, store adapters, indexer, retriever, reranker, context assembler, consolidator и user controls.