system-analysis.md

Аналіз концепції memory-system

1. Короткий опис ідеї

Поточна ідея полягає у створенні універсальної системи довгострокової пам'яті для нейронок та агентів, яка базується на Markdown-документах, пов'язаних між собою посиланнями та організованих у граф. Візуально це нагадує knowledge graph або "нейронні зв'язки", де окремі документи виступають вузлами, а зв'язки між ними формують контекстну карту проєкту.

Базовий робочий цикл такої системи виглядає так:

1. Агент отримує промпт або задачу.
2. Перед виконанням агент переглядає релевантну базу знань.
3. На основі знайдених документів агент формує контекст проєкту.
4. Після виконання задачі агент оновлює пам'ять: додає нові знання, пов'язує їх із наявними або оновлює вже існуючі вузли.

Додатково система має містити шар задач: TODO-список із посиланнями на пояснення, рішення та пов'язані документи. Ключова вимога до системи: вона має бути переносимою між проєктами, щоб розробник міг просто перенести папку пам'яті та папку skill-ів у новий репозиторій і відразу отримати робочий механізм довгострокового контексту для агентів.

2. Що в цій концепції сильне

2.1. Людино-читабельний формат

Markdown є дуже вдалим вибором як формат джерела істини:

• документи легко читати людині без додаткових інструментів;
• їх зручно редагувати вручну;
• вони добре працюють із Git;
• їх можна відкривати як у редакторі, так і у wiki-like інтерфейсах;
• вони не прив'язують систему до окремої СУБД, сервісу чи конкретної платформи.

Це критично, бо довгострокова пам'ять для агентів повинна бути не лише машино-доступною, а й зрозумілою для людини-розробника.

2.2. Природна модель у вигляді графа знань

Ідея зв'язувати Markdown-документи посиланнями природно веде до knowledge graph-підходу:

• документ може посилатися на рішення, задачі, контексти, сутності, технічні обмеження;
• окремі кластери знань можна візуалізувати як підграфи;
• зростання бази знань відбувається еволюційно, без жорсткого централізованого дерева.

Це добре відповідає реальному розвитку проєктів, де знання часто не вкладаються в ієрархію, але чудово живуть у мережі пов'язаних вузлів.

2.3. Портативність між проєктами

Одна з найсильніших властивостей ідеї: її можна мислити як portable memory engine. Якщо правильно розділити ядро системи і дані конкретного проєкту, то розробник зможе переносити механіку пам'яті між різними кодовими базами без глибокої інтеграції.

2.4. Сумісність з агентним workflow

Сам підхід добре стикується з реальним циклом роботи агентів:

• до виконання потрібно зібрати контекст;
• під час виконання потрібно не втратити нові спостереження;
• після виконання потрібно зафіксувати здобуті знання.

Тобто концепція не просто про "зберігати файли", а про вбудовування пам'яті у життєвий цикл агентної роботи.

3. Головні проблеми та слабкі місця поточної ідеї

У нинішньому формулюванні ідея сильна як напрям, але ще занадто абстрактна. Нижче наведені головні проблеми, які потрібно закрити, інакше система швидко деградує.

3.1. Нечітка модель сутностей

Зараз у концепції змішані кілька різних речей:

• спогад;
• документація;
• нова ідея;
• технічна нотатка;
• рішення;
• TODO;
• контекст проєкту.

Поки ці типи інформації не розділені, агент не зможе стабільно працювати з пам'яттю. У результаті буде або надмірне дроблення знань, або змішування фактів, задач і гіпотез в одному файлі.

3.2. Немає правила "створити новий файл чи оновити існуючий"

Це одна з центральних проблем. Якщо не визначити формальне правило merge vs create, система почне розростатися дублями:

• той самий факт буде записаний у кількох місцях;
• одна й та сама сутність матиме кілька напівканонічних документів;
• нові агенти не знатимуть, який документ вважати головним.

У довгостроковій пам'яті це критично, бо retrieval на брудній базі працює погано навіть за наявності хорошого пошуку.

3.3. Markdown-граф сам по собі не вирішує retrieval

Граф із Markdown-файлів корисний як форма зберігання і навігації, але сам по собі не гарантує, що агент:

• знайде потрібну інформацію швидко;
• прочитає саме релевантні документи;
• не втратить важливий контекст;
• не перевантажить себе шумом.

Потрібно окремо визначити retrieval policy: за якими сигналами агент обирає документи, скільки читає, як формує локальний підграф, як стискає його до робочого контексту.

3.4. Немає політики життєвого циклу знань

Будь-яка реальна база пам'яті стикається з такими процесами:

• старіння знань;
• застарілі рішення;
• конфлікт між старим і новим;
• потреба в архівації;
• потреба позначити документ як canonical, deprecated або superseded.

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

3.5. TODO-шар змішується з knowledge-шаром

Ідея додати TODO-документ правильна, але в поточному формулюванні є ризик, що TODO стане просто великим списком задач без структури і без зрозумілого зв'язку з документацією.

Потрібно жорстко розвести:

• knowledge layer: факти, рішення, контекст, пояснення;
• execution layer: задачі, статуси, пріоритети, next actions.

Інакше пам'ять про знання і пам'ять про виконання будуть заважати одна одній.

3.6. Універсальність конфліктує з model-specific behavior

Ідея "універсальної" системи правильна, але не можна припускати, що однаковий prompt/skill буде однаково працювати для Codex, Claude чи інших моделей.

Реалістичний дизайн має розділяти:

• універсальне ядро пам'яті;
• модельно-специфічні адаптери;
• проєктно-специфічний контент.

Універсальність має досягатися спільним контрактом, а не ідентичністю реалізації для всіх моделей.

3.7. Немає моделі конкурентної роботи кількох агентів

Якщо кілька агентів одночасно:

• читають ті самі документи;
• створюють нові пов'язані записи;
• оновлюють один canonical file;

то без правил конкуренції виникатимуть конфлікти, дублікати або втрата змін.

3.8. Немає метрик якості системи

Поки не визначено, як зрозуміти, чи система реально допомагає. Потрібні хоча б базові метрики:

• наскільки часто агент знаходить релевантний контекст;
• скільки дубльованих документів створюється;
• наскільки швидко росте noise;
• скільки ручних виправлень пам'яті потрібно після агентів;
• чи скорочується час на повторне входження в контекст.

4. Рекомендована архітектурна модель

Щоб система була масштабованою і переносимою, її варто будувати не просто як "папку з Markdown", а як керований memory vault із чіткими шарами.

4.1. Три основні шари

1. Memory Core

Це ядро системи. Воно визначає:

• формат документів;
• типи вузлів;
• метадані;
• правила зв'язування;
• правила запису;
• індексацію;
• перевірки якості.

Memory Core повинен бути універсальним для всіх моделей.

2. Agent Adapters

Це skill-и або інтеграційні шари для конкретних моделей та агентних середовищ:

• Codex adapter;
• Claude adapter;
• інші адаптери в майбутньому.

Їх задача не визначати формат пам'яті, а реалізовувати однаковий memory contract у межах конкретної моделі.

3. Project Overlay

Це контент конкретного проєкту:

• доменна пам'ять;
• рішення;
• задачі;
• сутності;
• поточний робочий контекст;
• історія змін і пояснень.

Саме цей шар переноситься разом із проєктом і еволюціонує разом із ним.

4.2. Рекомендовані типи документів

Щоб розвести різні види знань, варто ввести типізацію вузлів.

concept

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

Створюється, коли:

• формується новий напрям;
• описується нова концепція;
• потрібно зафіксувати high-level ідею до її деталізації.

Оновлюється, коли ідея розвивається, але лишається тією самою концепцією.

decision

Для архітектурних або процесних рішень.

Створюється, коли:

• вибрано конкретний підхід;
• відхилено альтернативу;
• потрібно зберегти мотивацію рішення.

Оновлюється рідко. Якщо рішення суттєво змінюється, краще створювати новий запис із supersedes.

context

Для робочого контексту проєкту, підсистем, потоків даних, доменних обмежень.

Створюється, коли потрібно пояснити "як тут усе влаштовано".

task

Для execution-layer задач.

Створюється як операційна одиниця виконання, але не повинна замінювати знання чи пояснення.

note

Для локальних спостережень, проміжних нотаток, ідей нижчого рівня, коротких висновків.

Це найнебезпечніший тип, бо саме він найшвидше створює шум. Для нього потрібні найжорсткіші правила ревізії й консолідації.

index

Для навігаційних документів, summary-вузлів, оглядів підграфів.

Це важливо для масштабування: великий кластер знань не можна змушувати агента перечитувати повністю щоразу.

entity

Для головних сутностей системи:

• модуль;
• сервіс;
• процес;
• доменний об'єкт;
• інструмент;
• людина;
• зовнішня залежність.

У кожної важливої сутності бажано мати один canonical entity-doc.

5. Формат і правила даних

5.1. Чому plain Markdown недостатньо

Посилання у Markdown добрі для людини, але для стабільної роботи агентів потрібно мати структуровані поля. Тобто Markdown повинен лишатися джерелом істини, але всередині документа мають бути дані, з якими легко працювати машинно.

5.2. Рекомендований frontmatter

Для кожного документа варто ввести мінімальний frontmatter:

---
id: mem-entity-agent-adapter
type: entity
title: Agent Adapter
status: active
created_at: 2026-04-21
updated_at: 2026-04-21
project: memory-system
tags:
  - agents
  - adapters
  - architecture
links:
  - type: related_to
    target: mem-concept-memory-system
  - type: implements
    target: mem-decision-adapter-contract
supersedes: []
superseded_by: []
provenance:
  source: manual-analysis
  confidence: high
---

5.3. Обов'язкові правила для документів

Правило 1. У кожної ключової сутності має бути canonical document

Якщо з'являється важлива сутність, для неї має існувати один основний документ, який вважається головним джерелом правди.

Правило 2. Новий файл створюється не завжди

Рекомендована політика merge vs create:

• якщо нова інформація розширює вже описану сутність, оновлюється canonical doc;
• якщо це окремий факт, нова гіпотеза, нове рішення або окремий execution item, створюється новий файл;
• якщо є сумнів, агент має спочатку виконати write gate перевірку: знайти потенційний canonical node і лише після цього вирішувати, чи потрібен новий документ.

Правило 3. У кожного документа має бути статус

Мінімальний набір:

• active
• draft
• archived
• deprecated
• superseded

Правило 4. Документ має містити provenance

Потрібно знати:

• звідки взявся факт;
• наскільки він перевірений;
• ким або чим був створений документ;
• коли востаннє він оновлювався.

5.4. Семантика зв'язків

Посилання повинні бути не просто raw markdown-links, а логічними зв'язками з типами:

• related_to
• depends_on
• implements
• supersedes
• derived_from
• explains
• blocked_by

Це дозволить агенту працювати не просто з мережею лінків, а зі змістовним графом.

6. Retrieval та update workflow агентів

Центральна цінність системи не у зберіганні документів, а в тому, як агент читає і оновлює пам'ять.

6.1. Рекомендований pipeline

Крок 1. Parse intent

Агент має виділити:

• тему задачі;
• сутності;
• тип запиту;
• область змін;
• очікуваний результат.

Крок 2. Знайти стартові вузли

Вузли мають шукатися не лише за ключовими словами, а також за:

• типами документів;
• тегами;
• canonical entity docs;
• зв'язками;
• останніми релевантними рішеннями;
• task references.

Крок 3. Побудувати локальний підграф

Агент не повинен читати всю пам'ять. Він повинен:

• взяти стартові вузли;
• розширити їх на 1-2 переходи по важливих links;
• зібрати мінімальний підграф, релевантний задачі.

Крок 4. Стиснути підграф у робочий контекст

Навіть 10-20 документів часто забагато для прямого включення в prompt. Тому потрібен шар стискання:

• summary nodes;
• extractive summaries;
• короткий operational context;
• явно виділені constraints, open questions і latest decisions.

Крок 5. Виконати задачу

Тільки після цього агент переходить до виконання основної роботи.

Крок 6. Оновити пам'ять

Після завершення роботи агент повинен:

• оновити релевантні canonical docs;
• створити нові документи, якщо з'явилися нові вузли знань;
• оновити задачі;
• пов'язати нові записи з існуючими документами.

Крок 7. Провести post-write linking

Після запису система має перевірити:

• чи є документ сиротою;
• чи вистачає в нього зв'язків;
• чи не дублює він уже наявний вузол;
• чи потрібно оновити index або summary docs.

6.2. Потрібен lightweight indexing layer

Markdown лишається джерелом істини, але для швидкого retrieval потрібен легкий індекс:

• карта id -> file;
• зворотні зв'язки;
• індекс за типами;
• індекс за тегами;
• можливо, індекс ключових фраз або embeddings у майбутньому.

Без цього масштабована система буде або повільною, або неточною.

7. TODO-система як окремий шар

7.1. Не робити один плоский todo.md

Один великий TODO-файл з часом стане шумом. Краще одна з двох моделей:

Варіант A. tasks/index.md + окремі task-файли

Підходить для серйозного використання і масштабування.

Переваги:

• у кожної задачі є своя історія;
• задачу легко пов'язувати з knowledge docs;
• простіше оновлювати статуси;
• менше конфліктів при паралельній роботі.

Варіант B. Task-розділи з унікальними ID

Підходить для lightweight setup, якщо проєкт невеликий.

Але навіть тут у кожної задачі повинні бути мінімальні структуровані поля.

7.2. Мінімальний контракт задачі

Кожна задача повинна мати:

• id
• title
• status
• priority
• related_docs
• owner за потреби
• next_action
• updated_at

7.3. TODO не повинен підміняти документацію

Задача має відповідати на питання "що робити далі", але не "чому система влаштована саме так". Всі пояснення повинні жити в decision, context, concept або entity документах, а TODO лише посилатися на них.

8. Універсальність і переносимість

8.1. Що означає реальна універсальність

Система не стане універсальною, якщо один і той самий prompt копіювати між усіма моделями. Реальна універсальність означає інше:

• формат пам'яті є стабільним;
• контракти читання й запису є стабільними;
• моделі мають власні адаптери;
• проєкт може переносити vault без переписування концепції.

8.2. Базова структура директорій

Рекомендована стартова структура:

memory/
  indexes/
  concepts/
  entities/
  decisions/
  contexts/
  notes/
  tasks/
  summaries/
skills/
  codex/
  claude/

За потреби можна додати:

• templates/
• schemas/
• scripts/

8.3. Що має переноситися між проєктами

Окремо слід відділити:

• portable engine: правила, шаблони, contract-и, scripts;
• project memory: фактичні знання конкретного проєкту;
• model adapters: skill-и для конкретних середовищ.

Це дає нормальний баланс між перевикористанням і специфікою конкретного репозиторію.

9. Основні ризики і як їх гасити

9.1. Дублікати знань

Ризик:

• кілька документів про ту саму сутність або те саме рішення.

Що робити:

• canonical docs;
• write gate перед записом;
• periodic consolidation;
• явний supersedes.

9.2. Noise growth

Ризик:

• система швидко обростає дрібними нотатками, що не несуть довгострокової цінності.

Що робити:

• статуси;
• архівація;
• summary nodes;
• регулярний review/cleanup;
• чіткий бар'єр на створення note.

9.3. Hallucinated updates

Ризик:

• агент записує вигаданий, неперевірений або неточно інтерпретований факт.

Що робити:

• provenance;
• confidence level;
• шаблонізація запису;
• правило: не піднімати факт до canonical source без перевірки.

9.4. Context bloat

Ризик:

• перед виконанням задачі агент читає надто багато документів і губиться в них.

Що робити:

• retrieval budget;
• локальний підграф замість повного читання;
• summary docs;
• пріоритет canonical nodes.

9.5. Knowledge drift

Ризик:

• база знань більше не відповідає фактичному стану проєкту.

Що робити:

• decision records;
• updated_at;
• ревізія stale docs;
• явне позначення deprecated/superseded станів.

9.6. Паралельна робота агентів

Ризик:

• конфлікти при одночасному оновленні документів.

Що робити:

• append-only write model для нових нотаток;
• окремий merge/consolidation step;
• lock strategy для canonical docs, якщо система стане автоматизованою;
• мінімізація запису в одні й ті самі файли.

9.7. Втрата довіри до пам'яті

Найгірший сценарій: розробник перестає вірити системі і перестає її читати.

Що робити:

• provenance;
• last updated дата;
• visible status;
• індикатор рівня впевненості;
• обмеження на автостворення "важливих" документів без явної верифікації.

10. Практичні покращення, які варто закласти відразу

Нижче список покращень, які суттєво піднімуть шанс, що система буде реально працювати, а не просто красиво виглядати.

10.1. Ввести schema і шаблони документів

Потрібні шаблони для:

• concept;
• decision;
• entity;
• context;
• task;
• summary;
• note.

Без шаблонів агенти будуть писати вільним стилем, і база стане неоднорідною.

10.2. Додати linker/indexer

Потрібен інструмент, який:

• парсить frontmatter;
• будує карту вузлів і зв'язків;
• шукає сирітські документи;
• допомагає формувати локальний підграф.

10.3. Додати summary docs для великих кластерів

Коли знань стане багато, агентам не можна буде кожного разу читати десятки дрібних документів. Потрібні summary nodes, які збирають:

• головні факти;
• чинні рішення;
• відкриті питання;
• навігацію по кластеру.

10.4. Додати review/cleanup routine

Потрібен регулярний цикл прибирання:

• виявлення дублікатів;
• архівація застарілих документів;
• консолідація дрібних notes;
• перевірка broken links;
• оновлення summary docs.

10.5. Додати policy для stale knowledge

Якщо документ давно не оновлювався, система має:

• позначити його як можливо застарілий;
• знизити його retrieval priority;
• запропонувати ревізію.

10.6. Додати write gate

Перед створенням нового документа агент має пройти короткий фільтр:

1. Чи існує canonical doc цієї сутності?
2. Чи це справді новий вузол знань?
3. Чи достатньо даних для нового документа?
4. Чи потрібно спочатку оновити summary/index?

10.7. Додати minimal quality checks

Мінімальні перевірки перед або після запису:

• документ має id;
• документ має type;
• документ має хоча б один змістовний link або обґрунтовану причину бути root node;
• документ не дублює існуючий title/id;
• є updated_at;
• для важливих фактів є provenance.

11. Публічні контракти системи

Щоб систему можна було підключати до різних моделей і проєктів, потрібно явно зафіксувати інтерфейси.

11.1. Контракт memory document

Кожен memory document повинен:

• мати стабільний id;
• мати один із дозволених type;
• мати title;
• мати status;
• мати updated_at;
• мати список links;
• допускати ручне читання і машинний парсинг.

11.2. Контракт agent adapter

Кожен adapter повинен вміти:

1. Прийняти новий user/task intent.
2. Виконати retrieval релевантної пам'яті.
3. Сформувати короткий робочий контекст.
4. Виконати основну задачу.
5. Оновити знання за правилами merge vs create.
6. Оновити task layer, якщо задача змінилася.

Тобто adapter не повинен сам вигадувати структуру пам'яті, а має працювати поверх фіксованого контракту.

11.3. Контракт task item

Кожна task-одиниця повинна:

• бути посилальною через id;
• мати зв'язок із knowledge docs;
• зберігати статус і пріоритет;
• зберігати next action;
• не містити всю документацію всередині себе.

11.4. Контракт link semantics

Мінімальний набір типів зв'язків:

• related_to
• depends_on
• implements
• supersedes
• derived_from

Розширення можливе, але цей базовий набір уже дає корисну структуру для retrieval і навігації.

12. Перевірка концепції: тестові сценарії

Щоб зрозуміти, чи система життєздатна, потрібно перевіряти її не лише теоретично, а й на сценаріях використання.

12.1. Retrieval only relevant subgraph

Сценарій:

• агент отримує нову задачу;
• у пам'яті вже є десятки документів;
• агент знаходить лише релевантний підграф, а не читає всю базу.

Критерій успіху:

• контекст короткий;
• рішення не пропускають критичні залежності;
• шум мінімальний.

12.2. No duplicate creation

Сценарій:

• агент отримує нову ідею або спостереження;
• у базі вже є пов'язаний canonical doc;
• агент дописує його, а не створює нову копію.

12.3. Correct new-node creation

Сценарій:

• агент стикається зі справді новою сутністю, рішенням або задачею;
• створюється новий документ;
• він правильно лінкується до графа.

12.4. TODO linked to knowledge

Сценарій:

• задача містить посилання на explanation docs і decision docs;
• по задачі можна зрозуміти не лише що робити, а й звідки ця робота взялася.

12.5. Superseded knowledge preserved

Сценарій:

• старе рішення втратило актуальність;
• документ не видаляється, а позначається як superseded або deprecated;
• історія рішень зберігається.

12.6. Multi-agent safety

Сценарій:

• два агенти працюють паралельно;
• система не руйнує структуру пам'яті;
• конфлікти або мінімізуються, або добре виявляються.

12.7. Portability

Сценарій:

• memory vault і skills переносяться в інший проєкт;
• ядро системи не потрібно переписувати;
• адаптація відбувається через контент, а не через зміну базових правил.

13. Roadmap реалізації

Етап 1. Зафіксувати schema

Потрібно визначити:

• типи документів;
• мінімальний frontmatter;
• naming rules;
• link semantics;
• статуси.

Етап 2. Побудувати базову структуру vault

Створити директорії, шаблони і базові index docs.

Етап 3. Описати adapter contract

Окремо визначити, як різні моделі:

• читають пам'ять;
• збирають підграф;
• оновлюють знання;
• працюють із task layer.

Етап 4. Реалізувати retrieval/update workflow

Потрібен базовий pipeline, який вже може:

• знайти релевантні вузли;
• сформувати контекст;
• записати оновлення.

Етап 5. Додати task layer

Інтегрувати задачі як окремий execution layer, а не як довільні нотатки.

Етап 6. Додати indexing, cleanup і quality checks

Це критичний етап для переходу від красивої концепції до стабільної системи.

Етап 7. Перевірити систему на реальних проєктах

Справжня перевірка відбудеться лише на 1-2 реальних кодових базах, де:

• багато контексту;
• є повторювані задачі;
• є шанс накопичення знань;
• є кілька агентних сесій.

14. Підсумковий висновок

Ідея дуже сильна як основа для human-readable long-term memory системи для агентів. Вона добре поєднує:

• простоту Markdown;
• прозорість для людини;
• сумісність із knowledge graph-підходом;
• придатність для агентного workflow;
• переносимість між проєктами.

Але в поточному вигляді це ще не система, а напрям. Найбільша слабкість не в самому виборі Markdown чи графа, а в нестачі жорстких правил:

• які існують типи знань;
• як агент обирає, що читати;
• як агент вирішує, що оновлювати;
• як запобігати шуму і дублям;
• як працювати з застаріванням знань;
• як відокремити пам'ять про знання від пам'яті про виконання.

Головний висновок: успіх цієї системи визначатиметься не самим фактом існування Markdown-графа, а якістю контрактів навколо нього. Якщо закласти чіткі типи вузлів, правила retrieval, політику оновлення, task layer, provenance та cleanup-процеси, із цієї ідеї може вийти справді сильна універсальна система довгострокової пам'яті для агентів.