跳到主要内容

记忆提供商插件

内存大模型提供商（provider）插件为 Hermes Agent 提供了超出内置 MEMORY.md 和 USER.md 的持久跨会话知识。本指南介绍了如何构建一个。

:::提示 内存大模型提供商（provider）是两种大模型提供商（provider）插件类型之一。另一个是Context Engine Plugins，它取代了内置的上下文压缩器。两者都遵循相同的模式：单选、配置驱动、通过 hermes plugins 管理。 :::

目录结构​

每个内存大模型提供商（provider）都位于 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 ABC​

您的插件实现了 agent/memory_provider.py 中的 MemoryProvider 抽象基类：

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()is_available()代理初始化，激活前是 — 没有网络调用
initialize(session_id, **kwargs)initialize(session_id, **kwargs)代理启动是
get_tool_schemas()get_tool_schemas() init之后，用于工具注入是
handle_tool_call(name, args)handle_tool_call(name, args)当代理使用您的工具时是（如果您有工具）

配置​

方法目的必须实施吗？
get_config_schema()get_config_schema()声明 hermes memory setup 的配置字段是
save_config(values, hermes_home)save_config(values, hermes_home)将非秘密配置写入本机位置是（除非仅限 env-var）

可选挂钩​

方法当被呼叫时使用案例
system_prompt_block()system_prompt_block()系统提示组装静态提供商信息
prefetch(query)prefetch(query)每次 API 调用之前返回回忆上下文
queue_prefetch(query)queue_prefetch(query)每次转弯后为下一轮预热
sync_turn(user, assistant)sync_turn(user, assistant)每次完成转弯后持续对话
on_session_end(messages)on_session_end(messages)对话结束最终萃取/冲洗
on_pre_compress(messages)on_pre_compress(messages)上下文压缩之前在丢弃之前保存见解
on_memory_write(action, target, content)on_memory_write(action, target, content)内置内存写入镜像到您的后端
shutdown()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()。

:::提示最小模式与完整模式 get_config_schema() 中的每个字段都会在 hermes memory setup 期间得到提示。具有多种选项的提供商应保持架构最小化——仅包含用户必须配置的字段（API 密钥、所需的凭据）。在配置文件引用中记录可选设置（例如 $HERMES_HOME/myprovider.json），而不是在安装过程中提示所有设置。这使设置向导保持快速，同时仍然支持高级配置。请参阅超级内存大模型提供商（provider）的示例 - 它仅提示输入 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 的大模型提供商（provider），保留默认的无操作。

插件入口点​

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()

配置文件隔离​

所有存储路径必须使用来自 initialize() 的 hermes_home kwarg，而不是硬编码 ~/.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 了解使用真实 SQLite 大模型提供商（provider）的完整 E2E 测试模式。

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 命令​

内存大模型提供商（provider）插件可以注册自己的 CLI 子命令树（例如 hermes my-provider status、hermes my-provider config）。这使用基于约定的发现系统 - 无需更改核心文件。

它是如何工作的​

  1. 将 cli.py 文件添加到您的插件目录中 2.定义一个构建argparse树的register_cli(subparser)函数 3.内存插件系统在启动时通过discover_plugin_cli_commands()发现它
  2. 您的命令出现在 hermes <provider-name> <subcommand> 下

活动大模型提供商（provider）门控： 仅当您的大模型提供商（provider）是配置中的活动 memory.provider 时，您的 CLI 命令才会出现。如果用户尚未配置您的大模型提供商（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)

参考实现​

有关包含 13 个子命令、跨配置文件管理 (--target-profile) 和配置读/写的完整示例，请参阅 plugins/memory/honcho/cli.py。

使用 CLI 的目录结构​

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

单一提供商规则​

一次只能有一个外部内存大模型提供商（provider）处于活动状态。如果用户尝试注册第二个，MemoryManager 将拒绝它并发出警告。这可以防止工具架构膨胀和后端冲突。