hermes-hy-memory 0.1.4

HY Memory provider plugin for Hermes Agent (native, 100% passive injection)

HY Memory Provider for Hermes

A native Memory Provider plugin for Hermes Agent — first-class, 100% passive injection.

How it works

Hermes calls prefetch(query) before every LLM turn. This provider:

1. searches HY Memory with the query (chat path, three-channel recall),
2. formats the hits by layer (§ [profile] / § [intent] / §),
3. lets Hermes inject that block into the system prompt.

No user action required — memory works automatically.

At the end of each turn Hermes calls sync_turn(user, assistant); the provider submits the write to an internal thread pool asynchronously, so the main loop is never blocked.

Install

The SDK package hy-memory is on public PyPI — a plain pip install works, no extra index or credentials needed.

The chroma backend needs sqlite3 >= 3.35 (default MEMORY_VECTOR_STORE=chroma). On systems with an older sqlite (some CentOS/Linux report unsupported version of sqlite3): pip install pysqlite3-binary and swap it in at process entry (import sys; sys.modules["sqlite3"] = __import__("pysqlite3")), or switch to MEMORY_VECTOR_STORE=qdrant / faiss.

Option A: hermes memory setup (recommended)

hermes memory setup hy-memory

Hermes installs hy-memory per the plugin's pip_dependencies and runs a config wizard asking for HY_MEMORY_USER_ID / HY_MEMORY_AGENT_ID / mode.

Option B: manual pip install

# install this plugin (pulls hy-memory as a dependency)
pip install hermes-hy-memory

# enable it in Hermes
hermes config set memory.provider hy-memory

Option C: folder-drop (development)

cp -r plugins/native/hermes ~/.hermes/plugins/memory/hy-memory
pip install "hy-memory>=1.2.17"

Configuration

Quick start: interactive wizard (recommended)

hermes hy-memory init          # via the Hermes main CLI
# or standalone: hermes-hy-memory hy-memory init

A 4-step wizard (LLM → embedding → vector store → mode/userId) writes the configuration to ~/.hermes/.env. Requires questionary (pip install "hermes-hy-memory[init]" or pip install questionary).

Verify with doctor:

hermes hy-memory doctor

Environment variables

Variable	Required	Default	Description
HY_MEMORY_USER_ID	✅	—	First-level isolation key (your memory namespace)
HY_MEMORY_AGENT_ID	❌	hermes	Second-level isolation key
HY_MEMORY_MODE	❌	pro	Processing mode: lite / pro / ultra
HY_MEMORY_PREFETCH_MAX_CHARS	❌	2000	Max chars of injected prefetch text
HY_MEMORY_SYNC_WORKERS	❌	2	sync_turn background thread-pool size
HY_MEMORY_SHUTDOWN_GRACE_SEC	❌	10	Max seconds to wait for in-flight writes on shutdown
OPENAI_API_KEY (or matching LLM/embedder key)	✅*	—	Required for pro/ultra; lite only needs the embedder

*The HY Memory SDK's own LLM/Embedder configuration (see the hy-memory docs).

~/.hermes/config.yaml

memory:
  provider: hy-memory

Environment variables take precedence and can be persisted in ~/.hermes/.env (written automatically by hermes memory setup / the init wizard).

Processing modes (HY_MEMORY_MODE)

Mode	Write pipeline	Speed	Recall quality
lite	pure embedding (no LLM)	fastest	vector similarity only
pro (default)	LLM fact/identity extraction + reconcile/evolution	medium	profile + fact layers
ultra	pro + System2 async cognition (Schema/Intention)	fullest	+ cross-domain induction + proactive intent

⚠️ lite mode is not suitable for Hermes passive injection / recall. lite only embeds and skips LLM extraction, so memories stay at the L1_RAW layer; the SDK's list / search filter out L1_RAW, meaning lite-written memories cannot be recalled by prefetch (writes succeed but search is always empty). Use pro (default) or ultra for Hermes; lite only fits write-only / no-semantic-recall scenarios.

CLI

After pip install, the hermes-hy-memory subcommands let you run diagnostics and manual operations (outside the Hermes main process):

# health check: env present / client constructs / list works (read-only)
hermes-hy-memory doctor

# manual write
hermes-hy-memory add "I like K-Pop but prefer Jazz"

# manual search
hermes-hy-memory search "music taste" --limit 5

# list recent 20
hermes-hy-memory list

# cross-user test (override env)
hermes-hy-memory search "x" --user-id other_user --agent-id test

When loaded by the Hermes main CLI:

hermes hy-memory doctor

Hooks

Hook	When	Behavior
prefetch(query)	before each LLM call	search memory → inject into system prompt
sync_turn(user, ast)	end of each turn	submit async write to thread pool
on_session_end(msgs)	session end	wait for in-flight + tail extraction
on_pre_compress(msgs)	before context compression	same as on_session_end, preserves about-to-be-trimmed content
on_memory_write(action, target, content)	Hermes built-in memory commands	add syncs to HY Memory; delete is skipped (target IDs are not interchangeable)

Tools (LLM-invoked, optional)

Tool	Purpose
memory_search(query, limit)	search memories
memory_add(content)	write a memory
memory_delete(memory_id)	delete a memory
memory_list(limit)	list memories for the current user/agent

Even with tools disabled, the passive prefetch injection guarantees relevant memories reach every LLM call.

Troubleshooting

provider not initialized or all hooks silently no-op

Run the health check:

hermes-hy-memory doctor

Common causes:

1. HY_MEMORY_USER_ID not set
2. embed/LLM key not set (OPENAI_API_KEY, etc.) → HyMemoryClient(mode="pro") fails to construct
3. SDK not installed: pip install hy-memory

prefetch injects nothing

• There really is no relevant memory — confirm with hermes-hy-memory list
• Query too short (< 3 chars) or in the skip list (ok / thanks, etc.) — by design
• Using lite mode? lite memories stay at L1_RAW and are never recalled — use pro/ultra

sync_turn doesn't seem to write

• Default daemon threads are killed when the main process exits. Use Hermes daemon mode in production
• Raise HY_MEMORY_SHUTDOWN_GRACE_SEC to let shutdown wait a few more seconds
• Check the log for [hermes] sync_turn failed: ...

cross-loop errors (multi-client deployments)

If your Hermes deployment runs multiple HyMemoryClient instances (e.g. a multi-tenant server), use SharedRuntime:

from hy_memory import HyMemoryClient, SharedRuntime
runtime = await SharedRuntime.create(base_config)
client = HyMemoryClient(cfg, runtime=runtime)

A single-process Hermes deployment uses a solo-mode client by default and does not need this.

Comparison with Mem0-style integrations

Mem0's Hermes integration relies on a TypeScript SDK; this plugin uses the Python SDK. HY Memory offers three processing depths — lite/pro/ultra (lite skips the LLM, pro does standard extraction, ultra adds System2 cognition) — whereas Mem0 is single-tier LLM extraction.

Development

cd plugins/native/hermes
python -m pytest tests/ -v

Tests mock HyMemoryClient and need no external dependencies (no OPENAI_API_KEY, no running Qdrant).

Versions

Plugin	SDK dependency	Notes
0.1.4	hy-memory>=1.2.17	English README; init wizard (questionary)
0.1.3	hy-memory>=1.2.17	init interactive setup wizard
0.1.2	hy-memory>=1.2.17	Published to public PyPI; channel-dict flatten fix