Skip to content

development-plan.md

Latest commit

 

History

History
393 lines (271 loc) · 13.2 KB

development-plan.md

File metadata and controls

393 lines (271 loc) · 13.2 KB

План розробки memory-system

Purpose

Цей документ є практичним планом розробки системи memory-system.

  • idea.md фіксує сирий задум.
  • system-analysis.md містить критичний аналіз і архітектурні висновки.
  • development-plan.md фіксує затверджений execution-roadmap: що саме будувати, у якій послідовності, які правила приймаються у v1 і як підготувати репозиторій до розробки.

Документ навмисно коротший і операційніший за system-analysis.md. Тут не повторюється весь аналіз, а фіксуються рішення, які повинні лягти в основу реалізації.

Foundation Decisions

Цей блок закриває основні слабкі місця ідеї і є обов'язковим набором правил для v1.

1. Типи документів

У v1 підтримуються лише такі типи memory-документів:

  • concept
  • decision
  • context
  • entity
  • task
  • note
  • index

Документи без типу не вважаються валідними вузлами пам'яті.

2. Політика merge vs create

Агент перед створенням нового документа завжди проходить write gate:

  1. Знаходить 1-3 найближчі canonical-кандидати.
  2. Перевіряє, чи нова інформація стосується вже існуючої сутності, рішення або контексту.
  3. Якщо так, оновлює наявний canonical doc.
  4. Якщо ні, створює новий вузол і одразу лінкує його до графа.

Новий документ дозволений лише тоді, коли інформація не може бути коректно влита в уже існуючий canonical node.

3. Canonical policy

У кожної ключової сутності, теми або стабільного знання має бути один головний документ.

Правила:

  • entity, context і довгоживучі concept за замовчуванням мають canonical docs.
  • decision є окремим записом, але не дублюється у кількох файлах з однаковим змістом.
  • note не є canonical-джерелом, якщо спеціально не піднятий до такого статусу через консолідацію.

4. Lifecycle і статуси

У кожного memory-документа повинен бути статус:

  • draft
  • active
  • deprecated
  • superseded
  • archived

Додаткові правила:

  • важливі зміни рішення краще оформлювати новим decision із supersedes, а не переписувати історію;
  • старі знання не видаляються, а виводяться з активного використання через статус;
  • retrieval має надавати пріоритет active документам.

5. Розділення knowledge і task layer

task не зберігає пояснення системи, архітектурні аргументи або доменний опис.

task зберігає лише:

  • execution-state;
  • пріоритет;
  • next action;
  • посилання на пов'язані knowledge docs.

Уся аргументація і пояснення живуть у concept, decision, context або entity.

6. Retrieval policy

Агент не читає весь vault перед кожним промптом. У v1 retrieval працює так:

  1. Парситься intent задачі.
  2. Визначаються стартові вузли через entity, task, decision, context, теги і link semantics.
  3. Будується локальний підграф із лімітом переходів і читання.
  4. Підграф стискається в короткий робочий контекст.

Пріоритет читання:

  1. entity
  2. task
  3. decision
  4. context
  5. index
  6. note

7. Multi-agent policy v1

У v1 система не покладається на складний locking.

Базове правило:

  • нові спостереження й локальні оновлення спочатку пишуться як append-first записи;
  • злиття у canonical docs виконується окремим consolidation step;
  • пряме одночасне редагування одного й того самого canonical file треба мінімізувати.

8. Quality policy

Документ не вважається валідним memory node, якщо в ньому відсутні:

  • id
  • type
  • title
  • status
  • created_at
  • updated_at
  • project
  • links
  • provenance

tags, supersedes, superseded_by і confidence підтримуються як частина v1-контракту, але не всі з них обов'язкові для кожного документа.

v1 Architecture

1. Memory Core

Ядро системи визначає:

  • schema документів;
  • frontmatter;
  • link semantics;
  • правила запису;
  • правила retrieval;
  • індексацію;
  • quality checks.

Memory Core є стабільним і не залежить від конкретної моделі.

2. Agent Adapters

Адаптери реалізують один і той самий memory contract у різних агентних середовищах.

Перші цільові адаптери:

  • Codex
  • Claude

Обов'язкове правило: адаптери не змінюють Memory Core, а лише працюють поверх нього.

3. Project Overlay

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

  • фактичні memory-документи;
  • задачі;
  • summary-вузли;
  • індекси;
  • історія рішень;
  • локальний контекст конкретної кодової бази.

4. Цільова структура директорій v1

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

Це цільова структура для реалізації. На цьому етапі вона фіксується як стандарт, навіть якщо ще не створена фізично.

Public Contracts

1. MemoryDocument

Мінімальний контракт memory-документа:

  • обов'язкові поля:
    • id
    • type
    • title
    • status
    • created_at
    • updated_at
    • project
    • tags
    • links
  • опціональні поля:
    • supersedes
    • superseded_by
    • provenance
    • confidence

Призначення контракту:

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

2. TaskItem

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

  • id
  • title
  • status
  • priority
  • related_docs
  • next_action
  • updated_at

task завжди посилається на knowledge docs і не дублює архітектурні пояснення всередині себе.

3. AgentAdapter

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

  1. Прийняти intent задачі.
  2. Знайти стартові вузли.
  3. Побудувати локальний підграф.
  4. Стиснути його в робочий контекст.
  5. Виконати задачу.
  6. Оновити пам'ять за правилами merge vs create.

4. LinkSemantics

Базовий набір типів зв'язків для v1:

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

Execution Phases

Phase 1. Foundation

Зафіксувати:

  • schema документа;
  • типи документів;
  • статуси;
  • link semantics;
  • write gate;
  • canonical rules.

Результат фази: система має формальні правила, які агент не може трактувати довільно.

Phase 2. Vault Layout

Визначити:

  • структуру директорій;
  • naming convention;
  • правила для canonical docs;
  • правила для index і summary вузлів.

Результат фази: memory vault має стабільну фізичну організацію.

Phase 3. Templates and Standards

Підготувати шаблони для:

  • concept
  • decision
  • entity
  • context
  • task
  • note
  • index

Додатково зафіксувати:

  • приклади валідних документів;
  • anti-patterns;
  • приклади поганого merge/create рішення.

Результат фази: агент і людина пишуть у єдиному форматі.

Phase 4. Retrieval Layer

Описати:

  • стартові сигнали пошуку;
  • правила побудови локального підграфа;
  • retrieval budget;
  • роль index і summary документів.

Результат фази: агент читає релевантний мінімум, а не весь vault.

Phase 5. Write and Consolidation Layer

Описати:

  • post-task update flow;
  • merge vs create;
  • append-first strategy;
  • consolidation pass для злиття note у canonical docs.

Результат фази: система може накопичувати знання без лавини дублікатів.

Phase 6. Validation and Indexing

Визначити:

  • lightweight index;
  • quality checks;
  • orphan detection;
  • duplicate detection.

Результат фази: пам'ять стає перевірюваною, а не лише зручною для читання.

Phase 7. Adapter Layer

Описати:

  • спільний adapter contract;
  • обмеження адаптерів;
  • порядок підготовки референсних адаптерів.

Послідовність:

  1. Codex adapter
  2. Claude adapter

Результат фази: модельні інтеграції працюють поверх єдиного Memory Core.

Phase 8. Pilot Usage

Провести перевірку на 1-2 реальних проєктах.

Зафіксувати:

  • сигнали успіху;
  • сигнали провалу;
  • зони шуму;
  • дублікати;
  • точність retrieval;
  • складність ручної підтримки.

Результат фази: можна оцінити, чи система реально працює в живому середовищі.

Validation Criteria

v1 вважається придатним, якщо виконуються такі сценарії:

  1. Агент може відрізнити task від decision, entity і context.
  2. Агент перед створенням нового документа виконує write gate.
  3. Retrieval збирає локальний підграф, а не всю базу знань.
  4. Старі рішення можуть бути позначені як superseded без втрати історії.
  5. task посилається на knowledge docs, а не дублює їхній зміст.
  6. Multi-agent flow не вимагає прямого одночасного редагування тих самих canonical docs.
  7. Якість memory-документів можна перевірити через формальні поля, а не лише вручну.
  8. Репозиторій може бути підготовлений до роботи через базовий Git bootstrap без коміту і push.

Repository Bootstrap

Поточний стан:

  • папка /home/forg/github/memory-system ще не є Git-репозиторієм;
  • цільовий remote: git@github.com:Long-as-Python/Agent_memory_system.git;
  • цільова основна гілка: main.

Потрібні дії:

  1. Виконати git init.
  2. Встановити основну гілку main.
  3. Додати remote:
    • git remote add origin git@github.com:Long-as-Python/Agent_memory_system.git
  4. Перевірити git remote -v.
  5. Не робити commit.
  6. Не робити push.

Open v2 Items

Після стабілізації v1 свідомо відкладаються:

  • embeddings або semantic retrieval;
  • автоматичне резюмування великих кластерів;
  • складний locking або concurrency control;
  • metrics dashboard;
  • advanced model-specific optimizations.