Источник и свежесть

К концу этой страницы вы сможете:

1. сохранять факты из документа так, чтобы было видно, откуда они взялись;
2. проверять, не изменился ли документ, через validate_memory и search;
3. обновлять устаревшие факты, ничего не теряя по пути.

Пример на всю страницу: в репозитории есть docs/deploy.md. Сегодня в нём написано, что staging выкатывается через systemd-юнит app-staging. Через неделю команда переходит на Docker Compose и правит документ.

Три поля происхождения

Поле	Пример	Что значит
source_id	docs/deploy.md	Какой документ, файл или страница. Любая устойчивая строка.
source_hash	sha256:9f2c…	Хеш содержимого источника в момент чтения. Только вместе с source_id.
source_revision	a1b2c3d	Версия источника: коммит, номер редакции, дата. Для человека и аудита.

Это сведения о происхождении, а не доказательство. Сервер не читает ваш документ и не проверяет, что хеш настоящий. Поэтому запись с хешем, как и любая новая, получает статус unverified. Зато хеш позволяет потом спросить: «документ всё ещё тот же?»

Осторожно

source_hash без source_id сервер отклоняет: source_id is required when source_hash is provided. Хеш без указания, чего он хеш, бесполезен.

Как получить хеш

Подойдёт любой способ, если он каждый раз одинаковый: сервер просто сравнивает строки.

# хеш содержимого файла
sha256sum docs/deploy.md

# или хеш файла в Git и коммит как ревизия
git rev-parse HEAD:docs/deploy.md
git rev-parse --short HEAD

Пример: документ изменился

1. Агент читает документ и сохраняет факты. Хеш файла сегодня — sha256:aaa….

   remember

   {
     "content": "staging выкатывается через systemd-юнит app-staging",
     "workspace": "docs",
     "source": "agent",
     "source_id": "docs/deploy.md",
     "source_hash": "sha256:aaa…",
     "source_revision": "a1b2c3d",
     "fact_key": "deploy.staging.method",
     "confidence": 0.9
   }

   Второй факт из того же файла — «перед выкаткой staging запускается make migrate» — сохраняется с тем же source_id и хешем.

2. Документ поменяли. Теперь в нём Docker Compose, и хеш стал sha256:bbb….

3. Агент проверяет свежесть — например, в начале сессии или после git pull:

   validate_memory

   {
     "workspace": "docs",
     "source_id": "docs/deploy.md",
     "current_source_hash": "sha256:bbb…"
   }

   Ответ:

   {
     "workspace": "docs",
     "source_id": "docs/deploy.md",
     "current_source_hash": "sha256:bbb…",
     "checked": 2,
     "stale_ids": ["4d428a41-…", "7c1f09e2-…"],
     "conflict_ids": [],
     "stale_count": 2,
     "conflict_count": 0
   }

   Обе записи сохранены с другим хешем — значит, они могли устареть.

4. Агент убирает устаревшее и сохраняет новое. Удалить все записи источника одним вызовом:

   forget

   { "workspace": "docs", "source_id": "docs/deploy.md" }

   Ответ содержит forgotten_count: 2. Затем агент перечитывает документ и сохраняет актуальные факты с source_hash: "sha256:bbb…". Если изменился только один факт, можно удалить конкретную запись по memory_id, а остальные пересохранить с новым хешем.

Совет

Порядок важен: сначала forget по source_id, потом новые remember. Иначе forget по источнику удалит и только что сохранённые свежие записи.

stale не хранится — он вычисляется

Сравнение с хешем происходит в момент запроса. Если вызвать search без current_source_hash, старые записи снова будут выглядеть как unverified. Поэтому, увидев stale, агент должен что-то сделать — обновить или удалить запись, а не просто «запомнить, что она устарела».

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

Свежесть в search

search тоже принимает current_source_hash и exclude_stale:

search

{
  "query": "staging выкатка",
  "workspace": "docs",
  "current_source_hash": "sha256:bbb…",
  "exclude_stale": true
}

• current_source_hash — записи, у которых сохранён другой хеш, получат статус stale;
• exclude_stale: true — такие записи не попадут в ответ.

Осторожно

В search хеш сравнивается со всеми найденными записями, у которых есть source_hash, — фильтра по source_id там нет. Если в области лежат факты из разных документов, проверяйте свежесть через validate_memory с конкретным source_id, а current_source_hash в search используйте, когда область отведена под один источник.

Когда проверять

• в начале сессии — для ключевых документов проекта (README, правила деплоя, API-контракт);
• после git pull или слияния веток, если менялась документация;
• перед тем как действовать по факту с высоким риском (выкатка, миграция, удаление данных).

Что дальше

Конфликты и сводки Что происходит, когда версии факта расходятся.

Справочник validate_memory Параметры и поля ответа.

Справочник forget Удаление записи или всего источника.