Память проекта: что агенту знать заранее и как это хранить

Внешняя память — это папка с текстом и правило, как её читать

Из урока 1 вы знаете: модель не хранит состояние. Закрыли сессию — всё забыто. Окно контекста ограничено. Значит, знания о проекте надо держать снаружи, в обычных файлах. Это и называют Second Brain (второй мозг).

Схема простая. Перед задачей harness читает оглавление, выбирает подходящие заметки и кладёт их в контекст. После задачи агент дописывает новое знание.

// Перед задачей
const index = read("memory/INDEX.md");            // 40 строк: имя + описание
const picked = choose(index, task);              // 2–3 заметки по теме задачи
context.push(...picked.map(name => read(`memory/${name}.md`)));

// После задачи
if (learnedSomethingNew) write("memory/new-fact.md", note);

Что хранить и как раскладывать

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

• Правила проекта. «Деньги храним в копейках, целым числом». «Миграции только через Doctrine».
• Архитектурные решения. Формат ADR: контекст, решение, последствия. Объясняет «почему так», чтобы агент не «улучшил» обратно.
• Справка. Как запустить проект, тесты, деплой. Команды, которые агент выполнит сам.
• Продуктовый контекст. Кто пользователи, что для бизнеса важно, какие слова нельзя писать клиентам.
• Грабли. Инциденты и их причины: «перезапуск воркера руками обрывает очередь».

Как раскладывать. Одна мысль — один маленький файл. В начале файла — frontmatter: имя, однострочное описание, тип. Отдельный файл-оглавление собирает по строке на каждую заметку. Заметки ссылаются друг на друга через [[имя]].

---
name: money-in-kopecks
description: Деньги храним целым числом в копейках, никогда не float
type: rule
updated: 2026-09-14
---
Все суммы в БД и коде — integer в копейках (1 BYN = 100).
Float теряет точность: 0.1 + 0.2 != 0.3.
Связано: [[adr-003-money-type]], [[incident-refund-rounding]]

Три способа выдачи знаний агенту:

• Всё сразу. Склеить все заметки в системный промпт. Просто, но дорого. При росте базы важное тонет в шуме.
• Оглавление и подгрузка. Агент видит только индекс и сам открывает нужные файлы. Дёшево, точно, но требует хороших описаний.
• Поиск. Программа находит заметки по тексту задачи и подкладывает их. Работает на больших базах. Может промахнуться.

memory/
├── INDEX.md                      ← оглавление: по строке на заметку
├── rules/
│   ├── money-in-kopecks.md
│   └── migrations-only-doctrine.md
├── decisions/
│   ├── adr-001-symfony-messenger.md
│   └── adr-003-money-type.md
├── howto/
│   ├── run-tests.md
│   └── deploy-backend.md
├── product/
│   └── never-mention-fees.md
└── incidents/
    └── 2026-08-worker-restart.md

# INDEX.md
- [money-in-kopecks](rules/money-in-kopecks.md) — деньги целым числом в копейках
- [deploy-backend](howto/deploy-backend.md) — выкатка только через make up
- [adr-001-symfony-messenger](decisions/adr-001-symfony-messenger.md) — очереди на Messenger, не на cron
- [2026-08-worker-restart](incidents/2026-08-worker-restart.md) — ручной рестарт воркера обрывает очередь

# ADR-003. Тип для денежных сумм

Статус: принято, 2026-03-02

## Контекст
Суммы хранились во float. При возвратах накопились расхождения в 1 копейку.

## Решение
Храним суммы целым числом в копейках (BIGINT). В коде — value object Money.

## Последствия
+ Нет ошибок округления.
- При выводе нужно делить на 100. Все старые колонки переводим миграцией.
- Внешние API, которые отдают float, переводим в копейки на входе.

# Правила для агента

- Перед задачей прочитай memory/INDEX.md и открой заметки по теме.
- Заметка — подсказка, а не правда. Перед действием сверь её с кодом.
- Если заметка разошлась с кодом — прав код. Исправь заметку и обнови дату.
- Новое знание (решение, грабли) — отдельной заметкой и строкой в INDEX.md.
- Как запускать тесты и деплой — docs/howto/*.md, не выдумывай команды.

Поиск по смыслу, устаревание и иерархия правды

Поиск по словам находит заметки, где есть слова из запроса. Простой подсчёт совпадений работает плохо: частые слова вроде «код» есть везде. Алгоритм BM25 даёт больший вес редким словам и не любит слишком длинные документы.

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

Устаревание — главная беда любой базы знаний. Код меняют каждый день, а заметки — редко. Правила гигиены:

• в заметке есть дата обновления;
• перед действием агент сверяет заметку с кодом;
• нашёл расхождение — исправил заметку сразу, а не завёл вторую рядом;
• противоречивые заметки — это баг, его чинят.

score(док, запрос) = Σ IDF(слово) · tf·(k+1) / (tf + k·(1 − b + b·длина/средняя_длина))
обычно k ≈ 1.2, b ≈ 0.75

близость(a, b) = (a · b) / (|a| · |b|)   ← косинус угла между векторами смысла, от −1 до 1

import { readdirSync, readFileSync } from "node:fs";

const STOP = new Set(["и", "в", "на", "как", "что", "по", "с", "для", "не"]);
const words = s => s.toLowerCase().match(/[a-zа-яё0-9]+/g)?.filter(w => !STOP.has(w)) ?? [];

function search(dir, query, limit = 3) {
  const q = new Set(words(query));
  return readdirSync(dir)
    .filter(f => f.endsWith(".md"))
    .map(f => {
      const text = readFileSync(`${dir}/${f}`, "utf8");
      const score = new Set(words(text).filter(w => q.has(w))).size;
      return { file: f, score };
    })
    .filter(r => r.score > 0)
    .sort((a, b) => b.score - a.score)
    .slice(0, limit);
}

console.log(search("memory", "как выкатить бэкенд на прод"));

import { readdirSync, readFileSync } from "node:fs";

interface Hit { file: string; score: number }

const STOP = new Set(["и", "в", "на", "как", "что", "по", "с", "для", "не"]);
const words = (s: string): string[] =>
  (s.toLowerCase().match(/[a-zа-яё0-9]+/g) ?? []).filter(w => !STOP.has(w));

export function search(dir: string, query: string, limit = 3): Hit[] {
  const q = new Set(words(query));
  return readdirSync(dir)
    .filter(f => f.endsWith(".md"))
    .map((file): Hit => {
      const text = readFileSync(`${dir}/${file}`, "utf8");
      return { file, score: new Set(words(text).filter(w => q.has(w))).size };
    })
    .filter(h => h.score > 0)
    .sort((a, b) => b.score - a.score)
    .slice(0, limit);
}

<?php
const STOP = ['и', 'в', 'на', 'как', 'что', 'по', 'с', 'для', 'не'];

function words(string $s): array
{
    preg_match_all('/[a-zа-яё0-9]+/u', mb_strtolower($s), $m);
    return array_values(array_diff($m[0], STOP));
}

function search(string $dir, string $query, int $limit = 3): array
{
    $q = array_unique(words($query));
    $hits = [];
    foreach (glob($dir . '/*.md') as $file) {
        $score = count(array_intersect($q, array_unique(words(file_get_contents($file)))));
        if ($score > 0) {
            $hits[] = ['file' => basename($file), 'score' => $score];
        }
    }
    usort($hits, fn ($a, $b) => $b['score'] <=> $a['score']);
    return array_slice($hits, 0, $limit);
}

print_r(search(__DIR__ . '/memory', 'как выкатить бэкенд на прод'));

import re
from pathlib import Path

STOP = {"и", "в", "на", "как", "что", "по", "с", "для", "не"}

def words(s: str) -> list[str]:
    return [w for w in re.findall(r"[a-zа-яё0-9]+", s.lower()) if w not in STOP]

def search(folder: str, query: str, limit: int = 3) -> list[tuple[str, int]]:
    q = set(words(query))
    hits = []
    for path in Path(folder).glob("*.md"):
        score = len(q & set(words(path.read_text(encoding="utf-8"))))
        if score:
            hits.append((path.name, score))
    return sorted(hits, key=lambda h: -h[1])[:limit]

print(search("memory", "как выкатить бэкенд на прод"))