ee2b165e78
- 15 `MERGE-CHECK:` conflict-resolution comments removed from prod code (two were TODOs already done: the utf-8-sig sessions.json read lives in session_persistence, the pm-aware cron script helpers in scheduler_script). - 49 imports the branch left unused (ruff F401, none present at the merge base, none inside PLUGIN-COMPAT blocks). update_cmd's frozen-surface re-exports are trimmed to the names tests/compat/old_updater_surface.json actually lists under hermes_cli.update_cmd; the rest resolve through hermes_cli.main.__getattr__. - tools/environments/local_gitbash_probe.py: nothing imported it once _find_bash delegated to pm.shell(). - Three try/except wrappers around calls that cannot raise (install_truststore, get_hermes_home, and a duplicated except clause in supermemory).
Supermemory Memory Provider
Semantic long-term memory with profile recall, semantic search, explicit memory tools, and per-turn conversation capture into one document per session per 4-hour window for richer profiles.
Requirements
- The
supermemorySDK, prepared through PM byhermes memory setupwhen you select Supermemory. Restart Hermes after preparation; do not install into its selected environment with pip. - Hosted: API key from app.supermemory.ai/integrations?connect=hermes
- Self-hosted: a running Supermemory local server and the API key it prints on first boot
Setup
hermes memory setup # select "supermemory"
Or manually:
hermes config set memory.provider supermemory
echo 'SUPERMEMORY_API_KEY=***' >> ~/.hermes/.env
For a fully self-hosted setup, start Supermemory local and note the API key it prints on first boot:
npx supermemory local
Before running hermes memory setup, add the local endpoint to
$HERMES_HOME/supermemory.json:
{
"base_url": "http://localhost:6767"
}
Then run hermes memory setup and enter the local server's API key. Configuring
the endpoint first ensures the setup connection probe also stays local.
Config
Config file: $HERMES_HOME/supermemory.json
| Key | Default | Description |
|---|---|---|
base_url |
https://api.supermemory.ai |
API endpoint for hosted or self-hosted Supermemory. Takes priority over SUPERMEMORY_BASE_URL. |
container_tag |
hermes |
Container tag used for search and writes. Supports {identity} template for profile-scoped tags (e.g. hermes-{identity} → hermes-coder). |
auto_recall |
true |
Inject relevant memory context before turns |
auto_capture |
true |
Store cleaned user-assistant turns after each response |
max_recall_results |
10 |
Max recalled items to format into context |
profile_frequency |
50 |
Include profile facts on first turn and every N turns |
capture_mode |
all |
Skip tiny or trivial turns by default |
search_mode |
hybrid |
Search mode: hybrid (profile + memories), memories (memories only), documents (documents only) |
entity_context |
built-in default | Extraction guidance passed to Supermemory |
api_timeout |
5.0 |
Timeout for SDK requests |
Environment Variables
| Variable | Description |
|---|---|
SUPERMEMORY_API_KEY |
API key (required) |
SUPERMEMORY_BASE_URL |
Compatibility fallback for the API endpoint when base_url is not configured |
SUPERMEMORY_CONTAINER_TAG |
Override container tag (takes priority over config file) |
Base URL precedence is supermemory.json → SUPERMEMORY_BASE_URL →
https://api.supermemory.ai. Hermes resolves it once and uses the same endpoint
for SDK operations and setup/status probes.
Tools
Kebab-case names are registered for the agent; snake_case aliases remain supported.
| Tool | Alias | Description |
|---|---|---|
supermemory-save |
supermemory_store |
Store an explicit memory |
supermemory-search |
supermemory_search |
Search memories by semantic similarity |
supermemory-forget |
supermemory_forget |
Forget a memory by ID or best-match query |
supermemory-profile |
supermemory_profile |
Retrieve persistent profile and recent context |
Source attribution
All Supermemory API calls send x-sm-source: hermes, and document writes stamp
metadata.sm_source: hermes. This is a functional routing key, not telemetry:
it groups Hermes-written memories into a dedicated "Hermes" Space in the
Supermemory app, so you can filter, browse, and bulk-manage them per source agent
(alongside Codex, Claude Code, etc.) from the Supermemory UI.
Behavior
When enabled, Hermes can:
- prefetch relevant memory context before each turn
- write each completed user/assistant turn to one document per session per 4-hour window (
customId=<session>_<date>_b<0-5>, so the API appends deltas), matching the capture shape of the other Supermemory agent integrations - retry failed turn writes on the next turn, session end,
/reset, or shutdown (at-least-once: if the API accepted a write but the response was lost, the same turn is appended again) - route every SDK and probe request through the configured hosted or self-hosted endpoint
- expose explicit tools for search, store, forget, and profile access
Profile-Scoped Containers
Use {identity} in the container_tag to scope memories per Hermes profile:
{
"container_tag": "hermes-{identity}"
}
For a profile named coder, this resolves to hermes-coder. The default profile resolves to hermes-default. Without {identity}, all profiles share the same container.
Multi-Container Mode
For advanced setups (e.g. OpenClaw-style multi-workspace), you can enable custom container tags so the agent can read/write across multiple named containers:
{
"container_tag": "hermes",
"enable_custom_container_tags": true,
"custom_containers": ["project-alpha", "project-beta", "shared-knowledge"],
"custom_container_instructions": "Use project-alpha for coding tasks, project-beta for research, and shared-knowledge for team-wide facts."
}
When enabled:
supermemory-search,supermemory-save,supermemory-forget, andsupermemory-profileaccept an optionalcontainer_tagparameter- The tag must be in the whitelist: primary container +
custom_containers - Automatic operations (turn capture, prefetch, memory write mirroring) always use the primary container only
- Custom container instructions are injected into the system prompt