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

Плагины провайдера памяти дают Hermes Agent постоянные знания, которые сохраняются между сессиями, — поверх встроенных MEMORY.md и USER.md. Ниже разберём, как собрать такой плагин.

совет

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

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

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

plugins/memory/my-provider/
├── __init__.py      # Реализация MemoryProvider + точка входа register()
├── plugin.yaml      # Метаданные (name, description, hooks)
└── 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 всегда содержит:
          hermes_home (str): Активный путь HERMES_HOME. Используй для хранения данных.
        """
        self._api_key = os.environ.get("MY_API_KEY", "")
        self._session_id = session_id

    # ... реализуй оставшиеся методы

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

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

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

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

Метод	Назначение	Обязателен?
`get_config_schema()`	Объявить поля конфига для `hermes memory setup`	Да
`save_config(values, hermes_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() возвращает список дескрипторов полей, которые использует hermes memory setup:

def get_config_schema(self):
    return [
        {
            "key": "api_key",
            "description": "API-ключ провайдера",
            "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": "hermes",
        },
    ]

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

совет

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

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

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

def save_config(self, values: dict, hermes_home: str) -> None:
    """Записать несекретный конфиг в собственное место хранения."""
    import json
    from pathlib import Path
    config_path = Path(hermes_home) / "my-provider.json"
    config_path.write_text(json.dumps(values, indent=2))

Если провайдер работает только через переменные окружения, оставьте реализацию по умолчанию (no-op).

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

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("Sync failed: %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 — Hermes продолжит вызывать их со старой сигнатурой.

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

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

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

# ПРАВИЛЬНО — путь в рамках профиля
from hermes_constants import get_hermes_home
data_dir = get_hermes_home() / "my-provider"

# НЕПРАВИЛЬНО — общий путь для всех профилей
data_dir = Path("~/.hermes/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-подкоманд (например, hermes my-provider status, hermes my-provider config). Работает это через систему обнаружения по соглашению — править файлы ядра не нужно.

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

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

Привязка к активному провайдеру: CLI-команды видны только когда ваш провайдер выбран как активный memory.provider в конфиге. Пока пользователь не настроил провайдер, его команды в hermes --help не появятся.

Пример

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

def my_command(args):
    """Обработчик, вызываемый argparse."""
    sub = getattr(args, "my_command", None)
    if sub == "status":
        print("Provider is active and connected.")
    elif sub == "config":
        print("Showing config...")
    else:
        print("Usage: hermes my-provider <status|config>")

def register_cli(subparser) -> None:
    """Построить дерево argparse для hermes my-provider.

    Вызывается discover_plugin_cli_commands() во время настройки argparse.
    """
    subs = subparser.add_subparsers(dest="my_command")
    subs.add_parser("status", help="Show provider status")
    subs.add_parser("config", help="Show provider config")
    subparser.set_defaults(func=my_command)

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

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

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

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

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

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