Инженерные документы

Knowledge Extraction из агентских траекторий

#1. Цель

Реализовать механизм автоматического выделения кандидатов в знания из реальной работы агентов в Temporality.

Сейчас Temporality умеет:

фиксировать события агентской деятельности;
формировать knowledge.* события;
проектировать знания;
подтверждать, использовать, оспаривать и инвалидировать знания;
выдавать знания в виде hints.

При этом большая часть содержательной работы агента — исследование, обсуждение, принятие решений, обнаружение причин, формирование выводов — не приводит к появлению knowledge.

В результате реальный агентский run может содержать большое количество полезной информации, но после его завершения в Knowledge Layer не появляется ни одного кандидата.

Необходимо добавить отдельный механизм:

Agent trajectory
       ↓
Knowledge Extraction
       ↓
0..N knowledge candidates
       ↓
knowledge.proposed
       ↓
confirmation / rejection / correction
       ↓
persistent knowledge

#Основной принцип

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

#2. Что не является целью

В рамках задачи не требуется:

превращать каждый tool.completed в knowledge;
автоматически сохранять весь текст переписки;
делать из Temporality очередной RAG-контур;
заставлять агента вручную вызывать remember после каждого значимого вывода;
требовать от модели заполнения сложной структуры topics/entities/...;
автоматически считать любое утверждение истинным;
менять event log как source of truth;
заменять существующий lifecycle proposed → confirmed → used → challenged/corrected → invalidated.

Knowledge Extraction должен порождать кандидатов, а не самостоятельно объявлять их истиной.

#3. Целевая модель

Источником данных остаётся event stream.

Knowledge является производным представлением, построенным на основании событий.

                         Event Stream
                              │
             ┌────────────────┴────────────────┐
             │                                 │
        Runtime events                  Knowledge events
             │                                 │
             │                         ProjectKnowledge
             │
             ▼
       Agent trajectory
             │
             ▼
    Knowledge Extraction
             │
             ▼
    knowledge.proposed
             │
      ┌──────┼────────┐
      ▼      ▼        ▼
 confirmed rejected challenged
      │
      ▼
   Knowledge

Extraction не должен становиться вторым source of truth.

Все результаты extraction должны выражаться через существующую событийную модель Temporality.

#4. Основной сценарий

После завершения содержательной работы агента система должна иметь возможность проанализировать trajectory и определить:

что было установлено;
какие гипотезы были подтверждены или опровергнуты;
какие решения были приняты;
какие причины проблем были обнаружены;
какие ограничения или закономерности были выявлены;
какие результаты могут быть полезны будущему агенту.

Пример.

Агент исследовал проблему:

Почему WebAuthn не работает в Tauri WebView на macOS?

В ходе run:

исследование
→ проверка Safari
→ проверка Firefox
→ проверка Tauri WebView
→ эксперимент
→ анализ результата
→ вывод

После завершения extraction может предложить:

knowledge.proposed

kind: claim

proposition:
"WebAuthn работает в Safari/Firefox, но не работает
в текущем macOS WebView runtime Tauri."

evidence:
[
  event-123,
  event-127,
  event-131
]

Это не означает автоматического подтверждения знания.

Оно становится кандидатом:

proposed

и далее проходит существующий lifecycle.

#5. Два типа знания

Extraction должен различать как минимум два типа.

#5.1 Observation

Объективный результат действия.

Примеры:

pytest завершился с exit code 0

HTTP endpoint вернул status 200

файл X существует

конфигурация содержит параметр Y

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

#5.2 Claim

Вывод, сделанный на основании нескольких событий.

Примеры:

Проблема возникает только в WebView.

Причиной ошибки является несовместимость X и Y.

Для этого проекта нельзя использовать механизм Z.

Изменение A необходимо делать до B.

Claim обязательно должен иметь evidence, на основании которого он был сформирован.

#6. Источники extraction

На первом этапе extraction должен работать с завершёнными run.

run.completed
      ↓
Knowledge Extraction

Это является обязательным MVP.

В будущем extraction может запускаться и на промежуточных этапах содержательной работы, но это не является обязательным требованием первой реализации.

#7. Extraction должен анализировать trajectory, а не только chat

В extraction необходимо передавать релевантный контекст run:

пользовательскую задачу;
сообщения агента;
сообщения пользователя, если они являются частью run;
tool calls;
результаты инструментов;
MCP calls/results;
результаты команд;
изменения состояния, если они представлены событиями;
результаты проверок;
ошибки и последующие действия;
финальный результат run.

Необходимо избегать передачи модели полного необработанного event log без необходимости.

Должен существовать механизм формирования компактного extraction context.

#8. Контракт extractor

Extractor должен возвращать 0..N кандидатов.

Минимальная структура кандидата:

kind: observation | claim
proposition: "..."
evidence:
  - event_id

Дополнительно extractor может возвращать:

confidence: ...

если такое поле поддерживается моделью knowledge.

#Важное требование

Не делать обязательным заполнение:

topics
entities
tags
categories

агентом или extractor-моделью. В текущей реализации extractor заполняет topics/entities (0–3 нормализованных значений) — это контекст для retrieval, не обязательная часть knowledge creation.

Если они необходимы для retrieval, они вычисляются из самого knowledge и нормализуются судейским проходом (карта областей).

#9. Evidence

Каждый автоматически созданный claim должен иметь ссылки на исходные события.

Например:

knowledge.proposed
    proposition:
      "X вызывает Y"
    evidence:
      - event-123
      - event-127
      - event-131

Evidence должен позволять:

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

Knowledge без понятного происхождения не должен считаться полноценным результатом extraction.

#10. Не создавать knowledge из каждого run

Extractor должен уметь вернуть:

[]

если в run не было знаний, которые имеют ценность за пределами текущей задачи.

Это нормальный результат.

Например:

прочитал файл
→ поменял переменную
→ запустил тест
→ всё прошло

не обязательно должно создавать отдельный claim.

В то же время:

исследовал проблему
→ проверил несколько гипотез
→ обнаружил систематическую причину
→ сформировал решение

должно иметь возможность породить knowledge candidate.

#11. Критерий полезности

Extractor должен ориентироваться не на вопрос:

Что произошло в этом run?

а на вопрос:

Что из произошедшего может быть полезно будущему агенту при похожей работе?

Особенно ценны:

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

#12. Связь с `remember`

Существующий remember сохранить.

Он должен рассматриваться как явный канал утверждения знания агентом:

Agent
  ↓
remember
  ↓
knowledge.proposed

Но remember не должен быть единственным способом создания knowledge.

Целевая модель:

             ┌── remember ───────────────┐
             │                           │
Agent work ──┼── successful observations ┤
             │                           │
             └── Knowledge Extraction ──┘
                                         ↓
                                knowledge.proposed

При этом существующее правило:

успешные тесты не нужно повторно записывать через remember

сохранить.

#13. Автоматические observations

Существующую эвристику успешных test/build/lint команд сохранить.

Она является специализированным быстрым producer'ом:

successful verification
        ↓
knowledge.proposed
kind: observation

Knowledge Extraction не должен дублировать уже существующие observations.

Extractor должен видеть их как evidence/контекст и избегать создания второго knowledge с тем же смыслом.

#14. Deduplication

Необходимо предусмотреть защиту от повторного создания одного и того же знания.

Например:

Run 1:
"pytest tests/foo passes"

Run 2:
"pytest tests/foo passes"

Run 3:
"pytest tests/foo passes"

не должны создавать бесконечное количество одинаковых knowledge nodes.

Для этого необходимо использовать существующий механизм identity/deduplication knowledge либо добавить минимальный deterministic fingerprint.

Особенно важно различать:

новое знание

и:

повторное подтверждение существующего знания

Повторное подтверждение должно по возможности усиливать evidence существующего knowledge, а не создавать новый узел.

#15. Связывание знаний

Если extraction выявляет несколько связанных выводов, необходимо иметь возможность создавать связи:

knowledge.linked

Например:

knowledge A:
"WebAuthn не работает в текущем WebView"

knowledge B:
"Safari использует другой browser runtime"

knowledge A
    └── related_to ──> knowledge B

При этом создание связей не должно быть обязательным для каждого knowledge candidate.

Минимальный MVP мог начать только с:

knowledge.proposed
    + evidence

а linking — отдельным этапом. Сейчас linking реализован: contradicts создаёт вызов опровержения, куратор отношений подтверждает/отклоняет связи (knowledge.relation_confirmed/dismissed).

#16. Confirmation

Extraction не подтверждает knowledge автоматически только потому, что его предложила LLM. Исключение — ре-деривация: повторное извлечение уже известного утверждения подтверждает его (execution-reverification/extraction-reverification), а последующие — фиксируют использование (knowledge.used). И отдельно: judged-подсказка hint.outcome: helpful подтверждает proposal прямо из проекции.

После:

knowledge.proposed

должен использоваться существующий механизм подтверждения.

Подтверждение может происходить:

повторной проверкой;
новым агентским run;
явным human approval;
существующими verification-механизмами Temporality.

#17. Human-in-the-loop

Для MVP желательно предусмотреть возможность просмотра кандидатов человеком.

Интерфейс должен позволять:

┌──────────────────────────────────────────┐
│ Новый кандидат в знания                  │
│                                          │
│ WebView macOS не поддерживает ...        │
│                                          │
│ Evidence: 3 события                      │
│                                          │
│ [ Подтвердить ] [ Отклонить ] [ Изменить ]│
└──────────────────────────────────────────┘

При этом пользователь не должен редактировать YAML/JSON.

Редактирование knowledge должно происходить через обычный UI.

#18. Extraction prompt

Для extractor должен быть отдельный системный prompt.

Он должен явно задавать:

#Нужно

искать знания, полезные за пределами текущего run;
отличать факт/наблюдение от вывода;
опираться только на evidence;
возвращать несколько кандидатов, если они независимы;
возвращать пустой результат, если полезного знания нет;
избегать дублирования существующих knowledge;
фиксировать отрицательные результаты, если они полезны для будущих задач.

#Нельзя

превращать каждое действие в knowledge;
придумывать факты;
делать вывод без evidence;
сохранять обычный ход рассуждений;
сохранять временные детали run;
дублировать результаты существующих observations;
считать собственную уверенность доказательством.

#19. Контекст существующих знаний

Extractor желательно должен видеть релевантные существующие knowledge.

Это необходимо для определения:

новое знание

против:

подтверждение существующего знания

против:

Например:

Existing:
"X работает через Y"

Current run:
"X работает через Z"

Это должно потенциально приводить не к новому независимому knowledge, а к:

knowledge.challenged

или соответствующему механизму correction.

#20. Retrieval для extractor

Не нужно передавать extractor всю базу знаний.

Передавать следует только релевантные существующие knowledge:

trajectory
    ↓
candidate concepts / terms
    ↓
existing relevant knowledge
    ↓
extractor

Это одновременно:

уменьшает context;
помогает deduplication;
позволяет обнаруживать противоречия;
повышает качество extraction.

#21. Пилот на реальных задачах

Статус: проведён — extractor v4 работает в проде (topics/entities, contradicts, hint_outcomes, ре-деривация).

До реализации сложной схемы необходимо проверить гипотезу на уже выполненных реальных run.

Взять несколько существующих задач Temporality, в которых:

была содержательная работа;
были обсуждения;
были исследования;
принимались решения;
knowledge в текущей реализации не сформировалось.

Для каждого run:

existing trajectory
        ↓
prototype extractor
        ↓
candidate knowledge
        ↓
human review

Необходимо оценить:

сколько кандидатов создаётся на run;
сколько кандидатов действительно полезны;
сколько являются дубликатами;
сколько являются обычным шумом;
достаточно ли evidence;
какие типы knowledge реально встречаются;
какие знания стоит сохранять;
какие знания следует отклонять.

#22. Критерии успешности пилота

Пилот считается успешным, если на реальных задачах extractor способен:

находить содержательные выводы, которые сейчас теряются;
привязывать их к конкретным evidence;
не превращать каждый run в поток мусора;
отличать observations от claims;
находить знания, полезные за пределами текущего run;
обнаруживать повторение уже существующих knowledge;
возвращать 0 кандидатов там, где сохранять нечего.

Количественные пороги определить после первого пилота, а не задавать заранее.

#23. Что делать с `topics` и `entities`

Не делать их обязательными входными параметрами remember или extractor на первом этапе.

После пилота определить:

нужны ли они вообще в текущем виде;
какие поля действительно помогают retrieval;
можно ли получать их автоматически;
достаточно ли term/phrase matching;
какие сущности реально встречаются в knowledge.

Если они нужны, предпочтительный вариант:

knowledge
    ↓
enrichment
    ↓
topics/entities

а не:

agent
    ↓
обязательное заполнение topics/entities

#24. Наблюдаемость extraction

Сам extraction должен быть наблюдаемым через Temporality.

Необходимо фиксировать как минимум:

knowledge.extraction.started
knowledge.extraction.completed

и результат:

candidates_count
proposed
strengthened
challenged
aged
duplicates_skipped
invalid_skipped
duration_ms
model

(фактические поля knowledge.extraction.completed; knowledge.extraction.failed — отдельное событие сбоя.)

Extraction не должен быть «магией», которую невозможно диагностировать.

#25. Failure handling

Ошибка extraction не должна ломать основной run.

agent run
    │
    ├── completed
    │
    └── extraction failed
             │
             └── logged / observable

Run считается завершённым независимо от результата extraction.

Повторный extraction должен быть возможен.

#26. Idempotency

Повторный запуск extraction для одной и той же trajectory не должен порождать бесконечные дубликаты.

Необходимо определить стабильный идентификатор extraction:

extraction_id =
hash(
    trajectory_id,
    extraction_version
)

При изменении prompt/schema допускается новая версия extraction.

Например:

trajectory-123 / extraction-v1
trajectory-123 / extraction-v2

Это позволит эволюционировать extractor без потери истории.

#27. Версионирование

Extractor должен иметь версию.

Например:

knowledge-extractor.v1

В knowledge event желательно сохранять информацию о producer/version.

Это необходимо для последующего анализа:

какие знания были созданы какой версией;
как менялось качество extraction;
можно ли безопасно переобработать старые trajectories.

#28. Минимальный MVP

В первый этап включить только:

#Producer

run.completed
    ↓
Knowledge Extraction

#Output

knowledge.proposed

с:

kind
proposition
evidence

#Поддержать

observation;
claim;
0..N candidates;
deduplication;
idempotency;
extraction version;
наблюдаемость extraction;
ошибки без влияния на run.

#Не включать в MVP

сложную автоматическую taxonomy;
обязательные topics/entities;
сложный graph linking;
автоматическое подтверждение claims;
extraction после каждого turn;
сложный human-review workflow, если существующий UI пока не готов.

#29. Что сделано из «следующего этапа»

enrichment topics/entities — ✅ (плюс судейская нормализация областей);
automatic linking — ✅ (contradicts, куратор отношений);
challenge/correction существующих знаний — ✅ (opровержения, aging sweep, переходы состояний от hint.outcome);
human review — ✅ через supervisor-кейсы (knowledge_hygiene, knowledge_contradiction) и ручные действия в Explorer;
автоматическое подтверждение observations — ✅ (ре-деривация);
промежуточный extraction после содержательных блоков и quality metrics — остаётся будущим.

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

После реализации реальный run должен выглядеть примерно так:

User task
   ↓
Agent work
   │
   ├── tool events
   ├── observations
   ├── decisions
   ├── experiments
   └── conclusions
          │
          ▼
      run.completed
          │
          ▼
   Knowledge Extraction
          │
          ├── candidate A
          ├── candidate B
          └── candidate C
                  │
                  ▼
        knowledge.proposed
                  │
          ┌───────┴────────┐
          ▼                ▼
     verification       rejection
          │
          ▼
   knowledge.confirmed
          │
          ▼
      future run
          │
          ▼
      knowledge.used

Главный результат задачи:

Temporality начинает фиксировать не только то, что делал агент, но и то, что агентская работа позволила узнать.

При этом event stream остаётся источником истины, а knowledge остаётся производным, проверяемым и эволюционирующим представлением.

Knowledge Extraction из агентских траекторий

#1. Цель

#Основной принцип

#2. Что не является целью

#3. Целевая модель

#4. Основной сценарий

#5. Два типа знания

#5.1 Observation

#5.2 Claim

#6. Источники extraction

#7. Extraction должен анализировать trajectory, а не только chat

#8. Контракт extractor

#Важное требование

#9. Evidence

#10. Не создавать knowledge из каждого run

#11. Критерий полезности

#12. Связь с remember

#13. Автоматические observations

#14. Deduplication

#15. Связывание знаний

#16. Confirmation

#17. Human-in-the-loop

#18. Extraction prompt

#Нужно

#Нельзя

#19. Контекст существующих знаний

#20. Retrieval для extractor

#21. Пилот на реальных задачах

#22. Критерии успешности пилота

#23. Что делать с topics и entities

#24. Наблюдаемость extraction

#25. Failure handling

#26. Idempotency

#27. Версионирование

#28. Минимальный MVP

#Producer

#Output

#Поддержать

#Не включать в MVP

#29. Что сделано из «следующего этапа»

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

#12. Связь с `remember`

#23. Что делать с `topics` и `entities`