构建记忆提供商插件
记忆提供商插件为 Hermes Agent 提供超越内置 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 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() | Agent 初始化，激活前 | 是 — 无网络调用 |
initialize(session_id, **kwargs) | Agent 启动 | 是 |
get_tool_schemas() | 初始化后，用于工具注入 | 是 |
handle_tool_call(name, args) | Agent 使用您的工具时 | 是（如果您有工具） |
配置
| 方法 | 用途 | 是否必需 |
|---|---|---|
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() | 进程退出 | 清理连接 |
配置 Schema
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 期间提示用户。拥有许多选项的提供商应保持 schema 最小化——只包含用户必须配置的字段（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))
对于仅使用环境变量的提供商，保留默认的空操作即可。
插件入口点
def register(ctx) -> None:
"""Called by the memory plugin discovery system."""
ctx.register_memory_provider(MyMemoryProvider())
plugin.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 关键字参数，而非硬编码的 ~/.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 提供商的完整端到端测试模式。
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文件 - 定义构建 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):
"""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 会以警告拒绝。这防止了工具 schema 膨胀和后端冲突。