mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-07-01 12:02:05 +00:00

Mahesh Sanikommu 1b75b3fd90 feat(memory): add Supermemory setup connection summary

Add post_setup() and get_status_config() to the Supermemory memory
provider so `hermes memory setup` and `hermes memory status` print a
one-line connection summary (container, profile fact count,
auto_recall/auto_capture). Point API-key onboarding at the Hermes
connect URL (app.supermemory.ai/integrations?connect=hermes).

Salvage of #52988. Two fixes folded in:

- Test isolation: the new probe/status tests mocked _SupermemoryClient
  but not the __import__("supermemory") guard inside
  _probe_supermemory_connection, so they passed only where the optional
  supermemory package was installed and failed on a clean checkout / CI
  (the PR shipped with red CI). Added _stub_supermemory_importable()
  mirroring the existing test_is_available_false_when_import_missing
  pattern; the suite now passes with supermemory absent.

- post_setup: `if api_key and api_key not in os.environ` checked whether
  the key's *value* named an env var (always false in practice). Fixed to
  compare the value: `os.environ.get("SUPERMEMORY_API_KEY") != api_key`.

Verified: 38/38 in test_supermemory_provider.py and the full
tests/plugins/memory/ suite green with supermemory not installed.

Closes #52988

2026-06-27 15:07:34 +05:30

4.5 KiB

Raw Blame History

Supermemory Memory Provider

Semantic long-term memory with profile recall, semantic search, explicit memory tools, and full-session conversation ingest (one ingest per session) for richer profiles.

Requirements

pip install supermemory
Supermemory API key from app.supermemory.ai/integrations?connect=hermes

Setup

hermes memory setup    # select "supermemory"

Or manually:

hermes config set memory.provider supermemory
echo 'SUPERMEMORY_API_KEY=***' >> ~/.hermes/.env

Config

Config file: $HERMES_HOME/supermemory.json

Key	Default	Description
`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 and ingest requests

Environment Variables

Variable	Description
`SUPERMEMORY_API_KEY`	API key (required)
`SUPERMEMORY_CONTAINER_TAG`	Override container tag (takes priority over config file)

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
buffer the full conversation and ingest it as one session at session end (or on /reset, branch, compression, or shutdown)
ingest the full session to the conversations endpoint for richer profile/graph updates
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, and supermemory-profile accept an optional container_tag parameter
The tag must be in the whitelist: primary container + custom_containers
Automatic operations (turn sync, prefetch, memory write mirroring, session ingest) always use the primary container only
Custom container instructions are injected into the system prompt

4.5 KiB Raw Blame History