# Portability: UNIVERSAL
# Last validated: 2026-05-17
# Next review: 2027-05-17
# Ресурсы: [hub/shared_memory.py,shared_memory_*,shared_context_triggers]

ОБЩАЯ ПАМЯТЬ — многоагентное управление памятью
-----------------------------------------------

ДАТА: 28 февраля 2026 г.

Система общей памяти обеспечивает доступ к общей памяти
несколько агентов (Клод, Близнецы и т. д.). В отличие от обычного
Система памяти позволяет нескольким партнерам читать и читать одновременно
запись.

Ссылка: SQ043 Уровень A-2

АРХИТЕКТУРА
-----------

  Агент А ─┐
  Агент B ─┤─>shared_memory_* (bach.db) <─┬─> блок контекста
  Агент C ─┘ └─> Лента изменений

Особенности:
  - Поддержка нескольких агентов (agent_id, пространство имен)
  - Уровни видимости (частный, командный, глобальный)
  - Отслеживание распада для автоматической очистки
  - Разрешение конфликтов с помощью значений доверия
  - dist_type для системы распределения

КОМАНДЫ CLI (общая память bach)
------------------------------

ФАКТЫ (общие факты):
  список фактов Показать все общие факты
  факты add <ключ> <значение> Добавить новый факт
  факты get <id> Показать конкретный факт
  факты delete <id> delete fact

УРОКИ (общие уроки):
  список уроков Показать все общие уроки
  уроки add <title> Добавить новый урок
  уроки активировать <id> Активировать урок
  уроки деактивировать <id> деактивировать урок

РАБОЧАЯ ПАМЯТЬ (краткосрочная память):
  рабочий список Показать активные записи
  работаю добавить <контент> Добавить запись
  рабочая очистка Удаление просроченных записей
  рабочая текущая задача <текст> Установить текущую задачу (максимум 1 на агента)

СЕССИИ:
  список сеансов [N] Показать сеансы (по умолчанию: 20)
  текущие сеансы Показать активные сеансы
  архив сеансов <tage> Архивировать старые сеансы

КОНСОЛИДАЦИЯ (взвешивание памяти):
  список консолидаций Показать записи консолидации
  статистика консолидации Посмотреть статистику
  консолидация add <t> <id> Добавить запись вручную
  консолидация Консолидация слабых позиций
  прогон консолидации. Выполнение логики распада (B57)

КОНТЕКСТ И ИЗМЕНЕНИЯ:
  context Создать блок контекста (B55)
  изменения <метка времени> Изменения с момента отметки времени (B58)

ПРИМЕРЫ
---------

  # Добавить факт
  bach shared-mem facts add "api.endpoint" "https://api.example.com"
  bach shared-mem facts add "server.ip" "192.168.1.1" --agent CLAUDE --confidence 0.9

  # поделиться уроком
  bach shared-mem lessons add "Windows: UTF-8 mit PYTHONIOENCODING setzen" --severity high

  # Установить текущую задачу (привязку сеанса)
  bach shared-mem working current-task "Migration von PyMuPDF auf pypdf"
  bach shared-mem working current-task "BACH Release vorbereiten" --agent GEMINI

  # Генерируем контекстный блок (для инициализации агента)
  bach shared-mem context

  # Запрос изменился со вчерашнего дня
  bach shared-mem changes 2026-02-27T00:00:00

  # Выполнить логику распада (очистка памяти)
  bach shared-mem consolidation run
  bach shared-mem consolidation run --dry-run

РАЗРЕШЕНИЕ КОНФЛИКТА (B56)
--------------------------

Когда `факты добавляются` с существующим ключом:
  - Новая уверенность >= существующая уверенность → запись обновляется
  - Новая уверенность <существующая уверенность → запись остается неизменной

  Пример:
    bach shared-mem facts add "version" "2.5" --confidence 0.9
    # Перезаписывает существующую запись, если ее достоверность < 0,9

DECAY-SYSTEM (B57)
------------------

`consolidation run` выполняет логику распада:
  - Каждая запись: вес *= Decay_rate (по умолчанию: удержание 95%).
  - Если вес падает ниже порога (по умолчанию: 0,1) → Архивация
  - Часто используемые записи получают повышение и реже архивируются

CONTEXT-BLOCK (B55)
--------------------

`bachshared-mem context` генерирует блок Markdown:

  ## Контекст общей памяти

  ### Текущие задачи
  - **КЛОД**: миграция выполняется (с...)

  ### Главные факты
  - **api.endpoint** [0.9]: https://api.example.com

  ### Активные уроки
  - [высокий] Windows: установите UTF-8 с PYTHONIOENCODING

Используется для инициализации агента.

CHANGES-FEED (B58)
-------------------

`bach Shared-Mem Changes <timestamp>` возвращает все изменения
поскольку указана временная метка ISO:

  bach shared-mem changes 2026-02-28T10:00:00

Полезно для синхронизации агента: агент регулярно проверяет
добавили ли другие агенты факты или уроки.

ВАРИАНТЫ ДОБАВЛЕНИЯ ФАКТОВ
-----------------------

  --agent <id> идентификатор агента (по умолчанию: ГЛОБАЛЬНЫЙ)
  --namespace <ns> пространство имен (по умолчанию: по умолчанию)
  --visibility <уровень> частный|команда|глобальный (по умолчанию: глобальный)
  --confidence <0,0-1,0> Значение достоверности (по умолчанию: 0,5)

ВАРИАНТЫ ДОБАВЛЕНИЯ УРОКОВ
--------------------------

  --severity info|warn|high|critical Severity (по умолчанию: информация)
  --agent <id> идентификатор агента (по умолчанию: ГЛОБАЛЬНЫЙ)
  --namespace <ns> пространство имен (по умолчанию: по умолчанию)

ТАБЛИЦЫ БАЗ ДАННЫХ
------------------

shared_memory_facts Общие факты (ключ-значение)
  Shared_memory_lessons Общие уроки
  Shared_memory_sessions История общих сеансов
  Shared_memory_working кратковременная память (is_active, expires_at)
  Shared_memory_consolidation Отслеживание затухания (вес, скорость распада, порог)
  Shared_context_triggers Триггеры общего контекста

ОТЛИЧАЮТСЯ ОТ НОРМАЛЬНОЙ ПАМЯТИ
---------------------------------

  Нормальная память (bach mem, bach --memory):
    - Для ОДНОГО агента/партнера
    - работа с памятью, память_факты, уроки_памяти

  Общая память (bachshared-mem):
    - Для НЕСКОЛЬКИХ агентов одновременно
    - Контроль видимости (частный/командный/глобальный)
    - Разрешение конфликтов через доверие.
    - Система распада для очистки

ФАЙЛОВ
-------
  hub/shared_memory.py Реализация обработчика

СМ. ТАКЖЕ
----------
  bach --help memory        Обычная система памяти (один агент)
  bach --help consolidation Konsolidierungs-Engine
  bach --help connector     Система коннекторов (многопартнерская)
