sidebar_position: 8 title: "Memory Provider Plugins" description: "How to build a memory provider plugin for Hermes Agent" lang: ru

Создание плагина поставщика памяти

Плагины поставщика памяти предоставляют агенту Hermes постоянные межсессионные знания, выходящие за рамки встроенных MEMORY.md и USER.md. В этом руководстве рассказывается, как его создать.

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

Структура каталогов

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

plugins/memory/my-provider/
├── __init__.py      # MemoryProvider implementation + register() entry point
├── plugin.yaml      # Metadata (name, description, hooks)
└── README.md        # Setup instructions, config reference, tools

Азбука поставщика памяти

Ваш плагин реализует абстрактный базовый класс 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:
        """Check if this provider can activate. NO network calls."""
        return bool(os.environ.get("MY_API_KEY"))

    def initialize(self, session_id: str, **kwargs) -> None:
        """Called once at agent startup.

        kwargs always includes:
          hermes_home (str): Active HERMES_HOME path. Use for storage.
        """
        self._api_key = os.environ.get("MY_API_KEY", "")
        self._session_id = session_id

    # ... implement remaining methods

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

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

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

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

Метод	Цель	Должен реализовать?
`get_config_schema()`	Объявите поля конфигурации для `hermes memory setup`	Да
`save_config(values, hermes_home)`	Записать несекретную конфигурацию в исходное расположение	Да (если только env-var)

Дополнительные крючки

Метод	При вызове	Вариант использования
`system_prompt_block()`	Система оперативной сборки	Статическая информация о провайдере
`prefetch(query)`	Перед каждым вызовом API	Вернуть вызванный контекст
`queue_prefetch(query)`	После каждого хода	Предварительный разогрев для следующего поворота
`sync_turn(user, assistant)`	После каждого завершенного хода	Продолжать разговор
`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": "My Provider API key",
            "secret": True,           # → written to .env
            "required": True,
            "env_var": "MY_API_KEY",   # explicit env var name
            "url": "https://my-provider.com/keys",  # where to get it
        },
        {
            "key": "region",
            "description": "Server region",
            "default": "us-east",
            "choices": ["us-east", "eu-west", "ap-south"],
        },
        {
            "key": "project",
            "description": "Project identifier",
            "default": "hermes",
        },
    ]

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

💡 Tip

Минимальная и полная схема Каждое поле в `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:
    """Write non-secret config to your native location."""
    import json
    from pathlib import Path
    config_path = Path(hermes_home) / "my-provider.json"
    config_path.write_text(json.dumps(values, indent=2))

Для поставщиков только env-var оставьте значение по умолчанию no-op.

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

def register(ctx) -> None:
    """Called by the memory plugin discovery system."""
    ctx.register_memory_provider(MyMemoryProvider())

плагин.yaml

name: my-provider
version: 1.0.0
description: "Short description of what this provider does."
hooks:
  - on_session_end    # list hooks you implement

Потоковый контракт

sync_turn() ДОЛЖЕН быть неблокирующим. Если ваш сервер имеет задержку (вызовы API, обработка LLM), запустите работу в потоке демона:

def sync_turn(self, user_content, assistant_content):
    def _sync():
        try:
            self._api.ingest(user_content, assistant_content)
        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()

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

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

# CORRECT — profile-scoped
from hermes_constants import get_hermes_home
data_dir = get_hermes_home() / "my-provider"

# WRONG — shared across all profiles
data_dir = Path("~/.hermes/my-provider").expanduser()

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

См. tests/agent/test_memory_plugin_e2e.py для получения полного шаблона тестирования E2E с использованием реального поставщика SQLite.

from agent.memory_manager import MemoryManager

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

# Test tool routing
result = mgr.handle_tool_call("my_tool", {"action": "add", "content": "test"})

# Test lifecycle
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):
    """Handler dispatched by 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:
    """Build the hermes my-provider argparse tree.

    Called by discover_plugin_cli_commands() at argparse setup time.
    """
    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)

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

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

Структура каталогов с помощью CLI

plugins/memory/my-provider/
├── __init__.py      # MemoryProvider implementation + register()
├── plugin.yaml      # Metadata
├── cli.py           # register_cli(subparser) — CLI commands
└── README.md        # Setup instructions

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

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