Создание плагина провайдера памяти

Провайдеры памяти дают VibeOS постоянное, межсессионное знание, выходящее за рамки встроенных MEMORY.md и USER.md. Это руководство объясняет, как создать такой плагин.

подсказка

Провайдеры памяти — один из двух типов провайдерских плагинов. Второй — Плагины контекстного движка, которые заменяют встроенный компрессор контекста. Оба следуют одному шаблону: одиночный выбор, управление через конфиг, администрирование через vibeos plugins.

Структура директории

Каждый провайдер памяти находится в plugins/memory/<name>/:

plugins/memory/my-provider/
├── __init__.py      # Реализация MemoryProvider + точка входа register()
├── plugin.yaml      # Метаданные (имя, описание, хуки)
└── README.md        # Инструкции по настройке, справка по конфигу, инструменты

Абстрактный базовый класс MemoryProvider

Ваш плагин реализует абстрактный базовый класс MemoryProvider из agent/memory_provider.py:

from agent.memory_provider import MemoryProvider

class MyMemoryProvider(MemoryProvider):
    @property
    def name(self) -> str:
        return "my-provider"

    def is_available(self) -> bool:
        """Проверяет, может ли этот провайдер активироваться. Без сетевых вызовов."""
        return bool(os.environ.get("MY_API_KEY"))

    def initialize(self, session_id: str, **kwargs) -> None:
        """Вызывается один раз при запуске агента.

        kwargs всегда включает:
          vibeos_home (str): Путь к активному VIBEOS_HOME. Используйте для хранения.
        """
        self._api_key = os.environ.get("MY_API_KEY", "")
        self._session_id = session_id

    # ... реализация остальных методов

Обязательные методы

Основной жизненный цикл

Метод	Когда вызывается	Обязателен?
name (свойство)	Всегда	Да
is_available()	Инициализация агента, до активации	Да — без сетевых вызовов
initialize(session_id, **kwargs)	Запуск агента	Да
get_tool_schemas()	После инициализации, для внедрения инструментов	Да
handle_tool_call(tool_name, args, **kwargs)	Когда агент использует ваши инструменты	Да (если есть инструменты)

Конфигурация

Метод	Назначение	Обязателен?
get_config_schema()	Объявляет поля конфигурации для vibeos memory setup	Да
save_config(values, vibeos_home)	Записывает несекретную конфигурацию в собственное расположение	Да (если не только через переменные окружения)

Опциональные хуки

Метод	Когда вызывается	Сценарий использования
system_prompt_block()	Сборка системного промпта	Статическая информация о провайдере
prefetch(query, *, session_id="")	Перед каждым вызовом API	Возврат извлечённого контекста
queue_prefetch(query)	После каждого шага	Предварительная загрузка для следующего шага
sync_turn(user, assistant, *, session_id="")	После каждого завершённого шага	Сохранение диалога
on_session_end(messages)	Завершение диалога	Финальное извлечение/сброс
on_pre_compress(messages)	Перед сжатием контекста	Сохранение инсайтов до удаления
on_memory_write(action, target, content)	Встроенные записи в память	Зеркалирование в ваш бэкенд
shutdown()	Завершение процесса	Очистка соединений

Схема конфигурации

get_config_schema() возвращает список описаний полей, используемых vibeos memory setup:

def get_config_schema(self):
    return [
        {
            "key": "api_key",
            "description": "API-ключ My Provider",
            "secret": True,           # → записывается в .env
            "required": True,
            "env_var": "MY_API_KEY",   # явное имя переменной окружения
            "url": "https://my-provider.com/keys",  # где получить
        },
        {
            "key": "region",
            "description": "Регион сервера",
            "default": "us-east",
            "choices": ["us-east", "eu-west", "ap-south"],
        },
        {
            "key": "project",
            "description": "Идентификатор проекта",
            "default": "vibeos",
        },
    ]

Поля с secret: True и env_var попадают в .env. Несекретные поля передаются в save_config().

Минимальная vs Полная схема

Каждое поле из get_config_schema() запрашивается во время vibeos memory setup. Провайдерам с множеством опций следует делать схему минимальной — включать только поля, которые пользователь обязан настроить (API-ключ, обязательные учётные данные). Документируйте опциональные настройки в справке по конфигурационному файлу (например, $VIBEOS_HOME/myprovider.json), а не запрашивайте их все во время настройки. Это сохраняет скорость мастера установки, но поддерживает расширенную конфигурацию. Пример — провайдер Supermemory: он запрашивает только API-ключ; все остальные опции хранятся в supermemory.json.

Сохранение конфигурации

def save_config(self, values: dict, vibeos_home: str) -> None:
    """Записывает несекретную конфигурацию в собственное расположение."""
    import json
    from pathlib import Path
    config_path = Path(vibeos_home) / "my-provider.json"
    config_path.write_text(json.dumps(values, indent=2))

Для провайдеров, использующих только переменные окружения, оставьте реализацию по умолчанию (пустую).

Точка входа плагина

def register(ctx) -> None:
    """Вызывается системой обнаружения плагинов памяти."""
    ctx.register_memory_provider(MyMemoryProvider())

plugin.yaml

name: my-provider
version: 1.0.0
description: "Краткое описание того, что делает этот провайдер."
hooks:
  - on_session_end    # перечислите реализованные хуки

Контракт потоков

sync_turn() НЕ должен блокировать выполнение. Если ваш бэкенд имеет задержки (API-вызовы, обработка LLM), выполняйте работу в фоновом потоке-демоне:

def sync_turn(self, user_content, assistant_content, *, session_id="", messages=None):
    def _sync():
        try:
            self._api.ingest(user_content, assistant_content, session_id=session_id, messages=messages)
        except Exception as e:
            logger.warning("Синхронизация не удалась: %s", e)

    if self._sync_thread and self._sync_thread.is_alive():
        self._sync_thread.join(timeout=5.0)
    self._sync_thread = threading.Thread(target=_sync, daemon=True)
    self._sync_thread.start()

messages — это опциональный контекст диалога в стиле OpenAI по состоянию на завершённый шаг. Если он присутствует, то включает сообщения пользователя/ассистента, вызовы инструментов ассистента и результаты вызовов инструментов. Провайдеры, которым не нужен сырой контекст шага, могут опустить параметр messages; VibeOS продолжит вызывать их с устаревшей сигнатурой.

Облачные провайдеры должны документировать, какие части messages отправляются за пределы устройства. Вызовы инструментов и их результаты могут содержать пути к файлам, вывод команд или другие данные рабочей области.

Изоляция профилей

Все пути хранения обязаны использовать аргумент vibeos_home из initialize(), а не жёстко заданный ~/.vibeos:

# ПРАВИЛЬНО — привязано к профилю
from vibeos_constants import get_vibeos_home
data_dir = get_vibeos_home() / "my-provider"

# НЕПРАВИЛЬНО — общее для всех профилей
data_dir = Path("~/.vibeos/my-provider").expanduser()

Тестирование

Смотрите tests/agent/test_memory_provider.py и соседние тесты памяти (tests/agent/test_memory_session_switch.py, tests/agent/test_memory_user_id.py, tests/run_agent/test_memory_provider_init.py) для сквозных шаблонов.

from agent.memory_manager import MemoryManager

mgr = MemoryManager()
mgr.add_provider(my_provider)
mgr.initialize_all(session_id="test-1", platform="cli")

# Тестирование маршрутизации инструментов
result = mgr.handle_tool_call("my_tool", {"action": "add", "content": "test"})

# Тестирование жизненного цикла
mgr.sync_all("user msg", "assistant msg")
mgr.on_session_end([])
mgr.shutdown_all()

Добавление CLI-команд

Плагины провайдеров памяти могут регистрировать собственное дерево подкоманд CLI (например, vibeos my-provider status, vibeos my-provider config). Для этого используется система обнаружения на основе соглашений — изменения в основных файлах не требуются.

Как это работает

1. Добавьте файл cli.py в директорию вашего плагина
2. Определите функцию register_cli(subparser), которая строит дерево argparse
3. Система плагинов памяти обнаруживает его при запуске через discover_plugin_cli_commands()
4. Ваши команды появляются в vibeos <имя-провайдера> <подкоманда>`

Ограничение активным провайдером: Ваши CLI-команды отображаются только тогда, когда ваш провайдер является активным memory.provider в конфиге. Если пользователь не настроил ваш провайдер, ваши команды не будут показаны в vibeos --help.

Пример

# plugins/memory/my-provider/cli.py

def my_command(args):
    """Обработчик, вызываемый argparse."""
    sub = getattr(args, "my_command", None)
    if sub == "status":
        print("Провайдер активен и подключён.")
    elif sub == "config":
        print("Показываю конфигурацию...")
    else:
        print("Использование: vibeos my-provider <status|config>")

def register_cli(subparser) -> None:
    """Строит дерево argparse для vibeos my-provider.

    Вызывается discover_plugin_cli_commands() во время настройки argparse.
    """
    subs = subparser.add_subparsers(dest="my_command")
    subs.add_parser("status", help="Показать статус провайдера")
    subs.add_parser("config", help="Показать конфигурацию провайдера")
    subparser.set_defaults(func=my_command)

Эталонная реализация

Смотрите plugins/memory/honcho/cli.py для полного примера с 13 подкомандами, управлением между профилями (--target-profile) и чтением/записью конфигурации.

Структура директории с CLI

plugins/memory/my-provider/
├── __init__.py      # Реализация MemoryProvider + register()
├── plugin.yaml      # Метаданные
├── cli.py           # register_cli(subparser) — CLI-команды
└── README.md        # Инструкции по настройке

Правило одного провайдера

Одновременно может быть активен только один внешний провайдер памяти. Если пользователь попытается зарегистрировать второй, MemoryManager отклонит его с предупреждением. Это предотвращает раздувание схем инструментов и конфликты бэкендов.