install.ps1 -Targets hermes rejects the target. Use the Bash installer.
The Hermes plugin version is 0.10.3. The main Memory Crystal release, including both MCP servers, is 0.10.1.
Recommended: universal installer
Agent Instructions
Paste this into Hermes Agent:/dev/tty. The installer can complete browser device authorization without one. Set MEMORY_CRYSTAL_ALLOW_STDIN_PROMPTS=1 when you want prompt fallback through stdin. If an agent-run install still cannot accept prompts, run it under a pseudo-terminal:
On macOS:
--backend local. See Local-First Setup.
What you get
Two surfaces:- A native plugin for completed-turn capture, optional recall injection, and pre-tool guardrail checks.
- Hermes MCP configuration for the hosted tool surface.
crystal_update and crystal_supersede. It does not expose crystal_edit or the six crystal_research_* tools. Those seven tools exist only on the stdio package. See MCP Server.
The plugin runs in auto mode by default. If Hermes exposes a native memory-provider registration surface, Memory Crystal registers as a provider. Otherwise it uses lifecycle hooks. Capture stays automatic either way.
Automatic recall injection is off. The installer does not write MEMORY_CRYSTAL_INJECT_RECALL unless that line already exists in ~/.hermes/.env, in which case it keeps the existing value. Set MEMORY_CRYSTAL_INJECT_RECALL=true in ~/.hermes/.env to opt in.
From plugin 0.10.3, every recall request that carries an agent identity also sends agentPool: "layer". The backend applies a per-agent recall layer only when that agent has a recall policy. Set MEMORY_CRYSTAL_AGENT_POOL=account to opt out, or agent to drop the shared overlay. Unset or any other value means layer. Wake, capture, preflight, topic-scan, and decision-archaeology requests never send it. The installer does not write it and keeps an existing value.
The plugin uses an explicit agent identity from the call context first, then MEMORY_CRYSTAL_AGENT_ID, then the Hermes profile name. Set MEMORY_CRYSTAL_AGENT_SCOPE, MEMORY_CRYSTAL_PROJECT_ID, or MEMORY_CRYSTAL_REPO_SLUG when a profile should map to a stable scope. These values partition one account. They are not a separate-account privacy boundary. See Scoping.
Files the installer writes
~/.hermes/plugins/crystal-memory/plugin.yaml~/.hermes/plugins/crystal-memory/__init__.py~/.hermes/.env~/.hermes/config.yaml
HERMES_HOME overrides ~/.hermes when set. The installer also updates an existing crystal-memory directory under ~/.hermes/profiles/<profile>/plugins/, and creates the active HERMES_PROFILE copy when that profile is set. It does not create plugin directories in unrelated profiles.
It enables crystal-memory under plugins.enabled, sets memory.provider: crystal-memory, and adds mcp_servers.memory_crystal with the selected backend URL and bearer token.
Verify
Restart Hermes, or reload MCP from a running session:mcp_memory_crystal_crystal_stats. Hermes can still select it during normal reasoning.
Environment
A fresh install writes these values. A rerun keeps an existingMEMORY_CRYSTAL_INJECT_RECALL line and an existing MEMORY_CRYSTAL_ALLOW_GROUP_WRITES value.
MEMORY_CRYSTAL_INJECT_RECALL is absent until you set it. Add =true only when you want automatic pre-response recall.
Optional scope settings:
Turn capture posts completed user and assistant turns to
/api/mcp/turn. If that route is missing, the plugin falls back to the older two-message /api/mcp/log path and reports the fallback in crystal_status. Capture is queued. crystal_status and crystal_doctor report queue depth, drops, and the last flush.
Automatic session lifecycle events write Conversation Snapshots through /api/mcp/snapshot. A snapshot keeps the newest usable messages within 750,000 bytes of UTF-8 JSON and 10,000 messages. Empty content and unknown roles are skipped. A single oversized newest message is shortened with a \n[truncated] suffix. When anything is skipped, dropped, or shortened, the response adds truncated: true, droppedMessageCount, skippedMessageCount, and truncatedContentCount. Invalid metadata, or an array with no usable messages, returns 400. Automatic snapshots are not Memory Checkpoints. crystal_checkpoint remains the checkpoint path.
crystal_status reports the lifecycle mode (provider, hooks, disabled, or degraded), backend auth, recent hook and provider counts, capture mode, effective agent scope, provider-tool policy, recall freshness, skip reasons, and circuit-breaker state.
Uninstall
--purge to remove ~/.hermes/plugins/crystal-memory. Uninstall removes Memory Crystal keys from ~/.hermes/.env and removes the crystal-memory plugin and mcp_servers.memory_crystal entries. Unrelated Hermes config stays.
Troubleshooting
If the plugin is installed but inactive, check the enabled list in~/.hermes/config.yaml (under HERMES_HOME when set):
mcp_servers.memory_crystal and run /reload-mcp. If capture or recall fails, check the API key and backend URL in .env, then run /crystal_doctor.
Use crystal_recall for durable context, crystal_query_knowledge_base for named references, and crystal_search_messages for exact retained wording. The provider’s fallback tools are exposed only when MCP is not detected unless you select always. If an automatic refresh fails, the provider can reuse cached context for the active scope; check recall freshness in /crystal_status.
Snapshot responses normally include id, messageCount, and totalTokens. Counts and tokens describe stored messages. When truncated, the stored record also retains original counts and tokens and the byte limit.
From a source checkout, you can run the optional live smoke test with your key already exported:
MEMORY_CRYSTAL_LIVE_WRITE_TEST=1 only if you want it to create a tagged test memory.