构建内存提供商插件

内存提供商插件为 Hermes Agent 提供跨会话的持久化知识，超越内置的 MEMORY.md 和 USER.md。本指南介绍如何构建一个。

:::tip 内存提供商是两种提供商插件类型之一。另一种是上下文引擎插件，用于替换内置的上下文压缩器。两者遵循相同的模式：单选、配置驱动、通过 hermes plugins 管理。 :::

目录结构

每个内存提供商位于 plugins/memory/<name>/：

plugins/memory/my-provider/
├── __init__.py      # MemoryProvider 实现 + register() 入口点
├── plugin.yaml      # 元数据（名称、描述、钩子）
└── README.md        # 安装说明、配置参考、工具

MemoryProvider 抽象基类

您的插件实现 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:
        """检查此提供商是否可以激活。禁止网络调用。"""
        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` (属性)	始终	是
`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)`	将非机密配置写入本地位置	是（除非仅使用环境变量）

可选钩子

方法	调用时机	使用场景
`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 密钥",
            "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()。

:::tip 最小模式 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))

对于仅使用环境变量的提供商，保留默认的空操作。

插件入口点

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

配置文件隔离

所有存储路径必须使用 initialize() 中的 hermes_home 参数，而不是硬编码的 ~/.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_plugin_e2e.py 获取完整的端到端测试模式，使用真实的 SQLite 提供商。

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 文件
定义构建 argparse 树的 register_cli(subparser) 函数
内存插件系统在启动时通过 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("提供商已激活并已连接。")
    elif sub == "config":
        print("正在显示配置...")
    else:
        print("用法: hermes my-provider <status|config>")
 
def register_cli(subparser) -> None:
    """构建 hermes my-provider argparse 树。
 
    在 argparse 设置时由 discover_plugin_cli_commands() 调用。
    """
    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 会拒绝并发出警告。这可以防止工具模式膨胀和后端冲突。

好奇心花园🪴

探索

最近的笔记

note-template

getMoon.js

getWeather.js

内存提供商插件