hermes - 💡(How to fix) Fix [Bug/UX]: Hindsight local_embedded setup failure — compound root causes + hermes memory setup wizard gaps [1 participants]

[Bug/UX]: Hindsight local_embedded setup failure — compound root causes + hermes memory setup wizard gaps

Summary

After following the documented setup flow for Hindsight local_embedded mode on macOS Apple Silicon, the daemon repeatedly failed to start (timeout after 180s), with logs showing:

• [Errno 48] address already in use
• HTTP 401 Missing Authentication header
• Hindsight sync failed: Failed to start daemon for profile 'hermes'

This issue documents the compound root causes discovered through debugging, and proposes improvements to hermes memory setup to prevent them.

Environment

• macOS Apple Silicon (M-series)
• Hermes Agent v2.x (local_embedded mode)
• hindsight-all installed via hermes venv Python

Root Causes (compound — all three must be resolved)

1. llm_api_key not written to config.json (most critical)

The Hermes plugin reads the key from config.json and injects it into the daemon subprocess env. If the key is missing from config.json, the daemon receives an empty key and returns 401 on every LLM call, preventing startup.

The hermes memory setup wizard does NOT prompt the user to write llm_api_key into config.json. Users naturally assume environment variables are sufficient, but:

• Hermes Agent process reads: HINDSIGHT_LLM_API_KEY (from $HERMES_HOME/.env)
• daemon process reads: HINDSIGHT_API_LLM_API_KEY (from ~/.hindsight/profiles/hermes.env)

These are two different env var names for two different processes by design. The only reliable single source of truth is config.json:

{
  "mode": "local",
  "llm_provider": "openai_compatible",
  "llm_api_key": "sk-or-...",
  "llm_model": "deepseek/deepseek-v4-flash",
  "llm_base_url": "https://openrouter.ai/api/v1",
  "idle_timeout": 0
}

2. LaunchAgent ghost process (macOS-specific)

Any previous installation of hindsight local_embedded (a prior Hermes session, another agent that embeds hindsight, or any other program using hindsight-embed) may have created ~/Library/LaunchAgents/io.hindsight.*.plist with KeepAlive: true.

This causes:

• Manually killing the daemon → it auto-revives with the old plist config
• The revived daemon uses stale/wrong configuration
• Port conflict with Hermes-managed daemon → [Errno 48] dead loop

Hermes kills the "unhealthy" daemon and starts a new one, which immediately hits port conflict, loops forever, never stabilizes.

3. idle_timeout defaults to 300s — daemon silently dies

Default idle timeout causes the daemon to shut down after 5 minutes of inactivity. Hermes does not reliably detect and restart it (related: #7149). Setting idle_timeout: 0 prevents this entirely.

Fix that worked (verified on macOS Apple Silicon, 2026-04-29)

1. Check and remove LaunchAgent:

launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/io.hindsight.*.plist
rm ~/Library/LaunchAgents/io.hindsight.*.plist

1. Kill all daemon processes:

pkill -9 -f "hindsight-api --daemon"

1. Write llm_api_key directly into ~/.hermes/hindsight/config.json (see above)

2. Remove conflicting HINDSIGHT_* vars from ~/.zshenv if any

3. Restart Hermes session

hermes memory setup Wizard Gaps

The wizard currently:

• Does NOT prompt for llm_api_key → users leave config.json without a key → 401 on every run
• Clears memory.provider after completing setup → user must manually re-run hermes config set memory.provider hindsight
• Does NOT run a post-setup daemon health check → user has no confirmation setup succeeded
• Does NOT detect existing LaunchAgent conflicts on macOS

Suggested Improvements to hermes memory setup

1. Prompt for llm_api_key and write it directly to config.json
2. Do not clear memory.provider after wizard completion
3. Run daemon health check at end of wizard (curl /health), show success/failure clearly
4. On macOS, detect ~/Library/LaunchAgents/io.hindsight.*.plist and warn user

Related Issues

• #7149 — daemon shuts down after idle timeout and isn't brought back
• #12990 — memory setup picker always defaults to Built-in only
• #7718 — plugin.yaml missing hindsight-all dependency