Skip to content

MEMORY_STRATEGY.uk.md

Latest commit

 

History

History
194 lines (137 loc) · 8.98 KB

MEMORY_STRATEGY.uk.md

File metadata and controls

194 lines (137 loc) · 8.98 KB

Стратегія Пам'яті

Інші мови: English | Russian

Мета

Turbo Quant Memory зберігає знання проєкту доступними для пошуку без потреби тримати повний текст у живому prompt.

Ідея проста:

  1. записувати локально
  2. повертати компактно
  3. відкривати більше лише тоді, коли задачі справді потрібен ширший контекст

Робоча Модель

Рівень Що це означає
Один локальний MCP-сервер Один stdio MCP-сервер обслуговує пам'ять для всіх підтримуваних клієнтів
Project-first зберігання Нотатки за замовчуванням належать поточному репозиторію
Кероване глобальне перевикористання У global потрапляють тільки явно промотовані знання
Compact-first retrieval Агент спочатку просить найменшу корисну відповідь, а не весь сирий контекст

Окремого memory engine під кожного агента немає. Клієнти використовують один серверний контракт і ті самі правила зберігання.

Активні Простори

Простір Роль Типово
project Локальні знання і нотатки репозиторію дефолтний запис
global Повторно вживані знання між проєктами тільки через промоцію
hybrid Об'єднаний режим читання з сильним пріоритетом project дефолтне читання

project

  • Зберігає знання, прив'язані до одного репозиторію.
  • Тримає рішення, уроки, handoff-и та патерни поруч із кодовою базою, яка їх породила.
  • Є безпечним дефолтом для щоденної роботи.

global

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

hybrid

  • Об'єднує результати з project і global.
  • Віддає перевагу project, коли релевантність близька.
  • Дозволяє перевикористовувати перевірені патерни без втрати прив'язки до поточного репозиторію.

Ідентичність Проєкту

Поточна ідентичність проєкту визначається в такому порядку:

  1. нормалізований URL origin
  2. fallback на hash кореневого шляху репозиторію
  3. явні overrides

Підтримувані overrides:

  • TQMEMORY_PROJECT_ROOT
  • TQMEMORY_PROJECT_ID
  • TQMEMORY_PROJECT_NAME

Це дозволяє зберігати стабільну project memory між сесіями й водночас дає контроль для нетипових способів запуску.

Структура Зберігання

Сховище file-backed і local-first:

~/.turbo-quant-memory/
  projects/
    <project_id>/
      manifest.json
      notes/
        <note_id>.json
  global/
    manifest.json
    notes/
      <note_id>.json

Нотатки та manifest-файли пишуться атомарно через тимчасовий файл і os.replace(...).

Політика Запису

Дія Результат
remember_note(..., scope="project") зберігає типізовану project-note
прямий запис у global відхиляється
promote_note(note_id) створює перевикористовувану global-копію з provenance
deprecate_note(...) виводить застаріле знання з активного обігу без стирання історії

Так global лишається невеликим, керованим і захищеним від випадкового змішування знань з різних проєктів.

Політика Пошуку

semantic_search підтримує project, global і hybrid.

hybrid є дефолтом і працює так:

  1. об'єднує кандидатів з project і global
  2. додає сильний bonus для project
  3. при близьких збігах віддає перевагу Markdown-блокам над нотатками
  4. фінально розв'язує нічию за пріоритетом project, потім за новішим updated_at, потім за стабільною ідентичністю

За замовчуванням пошук працює і по проіндексованих Markdown-блоках, і по persistent memory notes.

Контракт Картки Результату

Кожен результат зберігає provenance у видимому вигляді. Компактний envelope містить:

  • scope
  • project_id
  • project_name
  • source_kind
  • item_id
  • block_id, якщо hit походить із Markdown
  • source_path
  • title
  • heading_path
  • updated_at
  • score
  • confidence
  • confidence_state
  • compressed_summary
  • key_points
  • can_hydrate
  • note_kind, якщо це note-hit
  • promoted_from, якщо це промотована global-note

Дефолтний retrieval не повертає сирі excerpt-и або дампи цілих файлів. Це зменшує витрати токенів і переносить повніший контекст у явні hydration-виклики.

Стратегія Hydration

Hydration є явним і обмеженим:

Режим Поведінка
default target item плюс невелике локальне оточення
related target item плюс ширше, але все ще обмежене оточення

Правила:

  • Markdown hydration лишається в межах файлу.
  • Note hydration повертає повне тіло нотатки разом із metadata.
  • Агент має hydrate-ити контекст тільки тоді, коли компактної відповіді вже недостатньо.

Промоція Та Provenance

Промотовані global-notes зберігають блок promoted_from, який вказує назад на:

  • початковий scope
  • project_id джерела
  • project_name джерела
  • початковий note_id
  • початковий source_path

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

Рекомендована Поведінка Агента

У межах одного проєкту

  1. писати в project
  2. читати через hybrid
  3. віддавати пріоритет першому явно релевантному project hit
  4. викликати hydration тільки тоді, коли впевненість низька або потрібні деталі

Між проєктами

  1. промотувати лише справді reusable knowledge
  2. шукати в global або hybrid, коли потрібні міжпроєктні патерни
  3. тримати global маленьким і high-signal

Запобіжники

  • Сприймайте memory як tool data, а не як остаточну істину.
  • Зберігайте межі джерела й provenance.
  • Не зливайте великі сирі фрагменти за замовчуванням.
  • Не перетворюйте project-local notes на глобальні поради без явного рішення.
  • Тримайте систему local-first, простою і легкою в розгортанні.

Підсумок

Turbo Quant Memory спроєктовано як практичну робочу пам'ять для AI coding-агентів:

  • локальну за замовчуванням
  • компактну при recall
  • простежувану в кожному результаті
  • явну при відкритті повнішого контексту
  • обережну щодо того, що саме стає reusable між репозиторіями