memory-provider-plugin.md
1 --- 2 sidebar_position: 8 3 title: "Memory Provider Plugins" 4 description: "How to build a memory provider plugin for Hermes Agent" 5 --- 6 7 # Building a Memory Provider Plugin 8 9 Memory provider plugins give Hermes Agent persistent, cross-session knowledge beyond the built-in MEMORY.md and USER.md. This guide covers how to build one. 10 11 :::tip 12 Memory providers are one of two **provider plugin** types. The other is [Context Engine Plugins](/docs/developer-guide/context-engine-plugin), which replace the built-in context compressor. Both follow the same pattern: single-select, config-driven, managed via `hermes plugins`. 13 ::: 14 15 ## Directory Structure 16 17 Each memory provider lives in `plugins/memory/<name>/`: 18 19 ``` 20 plugins/memory/my-provider/ 21 ├── __init__.py # MemoryProvider implementation + register() entry point 22 ├── plugin.yaml # Metadata (name, description, hooks) 23 └── README.md # Setup instructions, config reference, tools 24 ``` 25 26 ## The MemoryProvider ABC 27 28 Your plugin implements the `MemoryProvider` abstract base class from `agent/memory_provider.py`: 29 30 ```python 31 from agent.memory_provider import MemoryProvider 32 33 class MyMemoryProvider(MemoryProvider): 34 @property 35 def name(self) -> str: 36 return "my-provider" 37 38 def is_available(self) -> bool: 39 """Check if this provider can activate. NO network calls.""" 40 return bool(os.environ.get("MY_API_KEY")) 41 42 def initialize(self, session_id: str, **kwargs) -> None: 43 """Called once at agent startup. 44 45 kwargs always includes: 46 hermes_home (str): Active HERMES_HOME path. Use for storage. 47 """ 48 self._api_key = os.environ.get("MY_API_KEY", "") 49 self._session_id = session_id 50 51 # ... implement remaining methods 52 ``` 53 54 ## Required Methods 55 56 ### Core Lifecycle 57 58 | Method | When Called | Must Implement? | 59 |--------|-----------|-----------------| 60 | `name` (property) | Always | **Yes** | 61 | `is_available()` | Agent init, before activation | **Yes** — no network calls | 62 | `initialize(session_id, **kwargs)` | Agent startup | **Yes** | 63 | `get_tool_schemas()` | After init, for tool injection | **Yes** | 64 | `handle_tool_call(name, args)` | When agent uses your tools | **Yes** (if you have tools) | 65 66 ### Config 67 68 | Method | Purpose | Must Implement? | 69 |--------|---------|-----------------| 70 | `get_config_schema()` | Declare config fields for `hermes memory setup` | **Yes** | 71 | `save_config(values, hermes_home)` | Write non-secret config to native location | **Yes** (unless env-var-only) | 72 73 ### Optional Hooks 74 75 | Method | When Called | Use Case | 76 |--------|-----------|----------| 77 | `system_prompt_block()` | System prompt assembly | Static provider info | 78 | `prefetch(query)` | Before each API call | Return recalled context | 79 | `queue_prefetch(query)` | After each turn | Pre-warm for next turn | 80 | `sync_turn(user, assistant)` | After each completed turn | Persist conversation | 81 | `on_session_end(messages)` | Conversation ends | Final extraction/flush | 82 | `on_pre_compress(messages)` | Before context compression | Save insights before discard | 83 | `on_memory_write(action, target, content)` | Built-in memory writes | Mirror to your backend | 84 | `shutdown()` | Process exit | Clean up connections | 85 86 ## Config Schema 87 88 `get_config_schema()` returns a list of field descriptors used by `hermes memory setup`: 89 90 ```python 91 def get_config_schema(self): 92 return [ 93 { 94 "key": "api_key", 95 "description": "My Provider API key", 96 "secret": True, # → written to .env 97 "required": True, 98 "env_var": "MY_API_KEY", # explicit env var name 99 "url": "https://my-provider.com/keys", # where to get it 100 }, 101 { 102 "key": "region", 103 "description": "Server region", 104 "default": "us-east", 105 "choices": ["us-east", "eu-west", "ap-south"], 106 }, 107 { 108 "key": "project", 109 "description": "Project identifier", 110 "default": "hermes", 111 }, 112 ] 113 ``` 114 115 Fields with `secret: True` and `env_var` go to `.env`. Non-secret fields are passed to `save_config()`. 116 117 :::tip Minimal vs Full Schema 118 Every field in `get_config_schema()` is prompted during `hermes memory setup`. Providers with many options should keep the schema minimal — only include fields the user **must** configure (API key, required credentials). Document optional settings in a config file reference (e.g. `$HERMES_HOME/myprovider.json`) rather than prompting for them all during setup. This keeps the setup wizard fast while still supporting advanced configuration. See the Supermemory provider for an example — it only prompts for the API key; all other options live in `supermemory.json`. 119 ::: 120 121 ## Save Config 122 123 ```python 124 def save_config(self, values: dict, hermes_home: str) -> None: 125 """Write non-secret config to your native location.""" 126 import json 127 from pathlib import Path 128 config_path = Path(hermes_home) / "my-provider.json" 129 config_path.write_text(json.dumps(values, indent=2)) 130 ``` 131 132 For env-var-only providers, leave the default no-op. 133 134 ## Plugin Entry Point 135 136 ```python 137 def register(ctx) -> None: 138 """Called by the memory plugin discovery system.""" 139 ctx.register_memory_provider(MyMemoryProvider()) 140 ``` 141 142 ## plugin.yaml 143 144 ```yaml 145 name: my-provider 146 version: 1.0.0 147 description: "Short description of what this provider does." 148 hooks: 149 - on_session_end # list hooks you implement 150 ``` 151 152 ## Threading Contract 153 154 **`sync_turn()` MUST be non-blocking.** If your backend has latency (API calls, LLM processing), run the work in a daemon thread: 155 156 ```python 157 def sync_turn(self, user_content, assistant_content): 158 def _sync(): 159 try: 160 self._api.ingest(user_content, assistant_content) 161 except Exception as e: 162 logger.warning("Sync failed: %s", e) 163 164 if self._sync_thread and self._sync_thread.is_alive(): 165 self._sync_thread.join(timeout=5.0) 166 self._sync_thread = threading.Thread(target=_sync, daemon=True) 167 self._sync_thread.start() 168 ``` 169 170 ## Profile Isolation 171 172 All storage paths **must** use the `hermes_home` kwarg from `initialize()`, not hardcoded `~/.hermes`: 173 174 ```python 175 # CORRECT — profile-scoped 176 from hermes_constants import get_hermes_home 177 data_dir = get_hermes_home() / "my-provider" 178 179 # WRONG — shared across all profiles 180 data_dir = Path("~/.hermes/my-provider").expanduser() 181 ``` 182 183 ## Testing 184 185 See `tests/agent/test_memory_plugin_e2e.py` for the complete E2E testing pattern using a real SQLite provider. 186 187 ```python 188 from agent.memory_manager import MemoryManager 189 190 mgr = MemoryManager() 191 mgr.add_provider(my_provider) 192 mgr.initialize_all(session_id="test-1", platform="cli") 193 194 # Test tool routing 195 result = mgr.handle_tool_call("my_tool", {"action": "add", "content": "test"}) 196 197 # Test lifecycle 198 mgr.sync_all("user msg", "assistant msg") 199 mgr.on_session_end([]) 200 mgr.shutdown_all() 201 ``` 202 203 ## Adding CLI Commands 204 205 Memory provider plugins can register their own CLI subcommand tree (e.g. `hermes my-provider status`, `hermes my-provider config`). This uses a convention-based discovery system — no changes to core files needed. 206 207 ### How it works 208 209 1. Add a `cli.py` file to your plugin directory 210 2. Define a `register_cli(subparser)` function that builds the argparse tree 211 3. The memory plugin system discovers it at startup via `discover_plugin_cli_commands()` 212 4. Your commands appear under `hermes <provider-name> <subcommand>` 213 214 **Active-provider gating:** Your CLI commands only appear when your provider is the active `memory.provider` in config. If a user hasn't configured your provider, your commands won't show in `hermes --help`. 215 216 ### Example 217 218 ```python 219 # plugins/memory/my-provider/cli.py 220 221 def my_command(args): 222 """Handler dispatched by argparse.""" 223 sub = getattr(args, "my_command", None) 224 if sub == "status": 225 print("Provider is active and connected.") 226 elif sub == "config": 227 print("Showing config...") 228 else: 229 print("Usage: hermes my-provider <status|config>") 230 231 def register_cli(subparser) -> None: 232 """Build the hermes my-provider argparse tree. 233 234 Called by discover_plugin_cli_commands() at argparse setup time. 235 """ 236 subs = subparser.add_subparsers(dest="my_command") 237 subs.add_parser("status", help="Show provider status") 238 subs.add_parser("config", help="Show provider config") 239 subparser.set_defaults(func=my_command) 240 ``` 241 242 ### Reference implementation 243 244 See `plugins/memory/honcho/cli.py` for a full example with 13 subcommands, cross-profile management (`--target-profile`), and config read/write. 245 246 ### Directory structure with CLI 247 248 ``` 249 plugins/memory/my-provider/ 250 ├── __init__.py # MemoryProvider implementation + register() 251 ├── plugin.yaml # Metadata 252 ├── cli.py # register_cli(subparser) — CLI commands 253 └── README.md # Setup instructions 254 ``` 255 256 ## Single Provider Rule 257 258 Only **one** external memory provider can be active at a time. If a user tries to register a second, the MemoryManager rejects it with a warning. This prevents tool schema bloat and conflicting backends.