Skip to content

MEMORY_STRATEGY.uk.md

Latest commit

 

History

History
214 lines (153 loc) · 12.1 KB

MEMORY_STRATEGY.uk.md

File metadata and controls

214 lines (153 loc) · 12.1 KB
Raw

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

Інші мови: 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

Секрети vs. Нотатки (Phase 9)

Секретний vault — це ОКРЕМА підсистема з іншою семантикою, відмінною від нотаток. Тримайте їх ментально та операційно роздільно:

Нотатки Секрети
Зберігання plaintext JSON, індексується AES-256-GCM blob, ніколи не індексується
Шлях retrieval semantic_search / hydrate (нечіткий пошук) тільки get_secret(name) (точне ім'я)
Scope project + global тільки project (без параметра scope)
Promotion promote_note у global не підтримується (завжди per-project)
Передача ніколи не залишає машину (нуль outbound HTTP) ніколи не залишає машину (та сама гарантія)

Поведінка агента для vault'а:

  1. Спочатку рецепти. Шукай правильний виклик get_secret(name) через semantic_search за pattern-нотаткою-рецептом, що документує credential. Ніколи не виловлюй імена з історії чату.
  2. Читай через secret_value. Викликай get_secret(name) лише коли значення дійсно потрібне; передавай secret_value програмно (env injection, аргумент підпроцесу); не дублюй у summary, логи, remember_note.
  3. Пиши реактивно для чат-видимих значень. Якщо користувач щойно вставив credential, або ти сам згенерував його у розмові — викликай set_secret(name, value) напряму. У тебе авторитетний активний project_id через cwd resolution; користувач, що запускає CLI з терміналу, не завжди. Відсилати користувача знову у CLI переробляти значення, яке вже у транскрипті — це фрикція без захисту.
  4. CLI рекомендуй профілактично. Поки значення ще НЕ у чаті — наприклад, користувач питає "куди мені покласти SSH-ключ?" — направ його на turbo-memory-mcp secret-set NAME з терміналу (getpass зі прихованим вводом). Прямий keyring set — low-level еквівалент. Після того як значення вже у чаті, CLI не дає додаткової секретності.

Запобіжники

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

Підсумок

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

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