Mahesh Sanikommu
1b76cfff83
A failed flush at on_session_switch() restored the pending buffer and then cleared it on the next line, so an unavailable service at the switch boundary still lost every pending turn. Pending turns now carry their own session_id; _write_turns() batches per session, so a later retry (next turn, session end, shutdown) writes old-session turns under the old session's custom_id even after the switch. Addresses review on #109359.
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
pip install supermemory- 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), like the Codex and OpenClaw plugins - retry failed turn writes on the next turn, session end,
/reset, or shutdown - route every SDK and probe request through the configured hosted or self-hosted endpoint
- expose explicit tools for search, store, forget, and profile access
The session is written once via the conversations endpoint, which drives Supermemory's entity extraction and profile building while keeping a clean, retrievable full transcript.
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