Troubleshooting

Start with the built-in checks. They tell you which area to look at.

  # Linux / macOS
./_System/Scripts/Installers/verify_install.sh
python3 _System/Scripts/hermes_brain_mcp.py --test

# Windows PowerShell
.\_System\Scripts\Installers\verify_install.ps1
python _System\Scripts\hermes_brain_mcp.py --test
  

Installer verification checks link

verify_install runs six checks. Here is what each one means and how to fix it.

The MCP server cannot find my vault link

The server looks for the vault in this order:

1. The --vault <path> argument.
2. The HERMES_VAULT_PATH environment variable.
3. A search upward from the script’s own location.

Fix it by passing the path explicitly, or set the variable once:

  export HERMES_VAULT_PATH="$HOME/Hermes Brain"      # Linux / macOS
setx HERMES_VAULT_PATH "C:\Users\you\Hermes Brain"  # Windows
python _System/Scripts/hermes_brain_mcp.py --test --vault "/path/to/vault"
  

No sessions are being archived link

1. Check how archiving is wired. You need one of: real-time hooks in ~/.hermes/config.yaml (on_session_start, post_llm_call, on_session_end), or an hourly cron job (0 * * * *) running hourly_archive.py. See Install Prompts.
2. Trigger an export by hand to separate a wiring problem from a script problem:

     python3 _System/Scripts/archive_now.py
   python3 _System/Scripts/hourly_archive.py --since 2h
     

3. Look in the right folder. Sessions go to 04-Archives/Daily/YYYY/MM/DD/. Cron-run notes are kept separately in 04-Archives/Cron/ so Daily/ only holds real chats.

Duplicate or garbled archive entries link

Run only one session-archiving job per vault. Two concurrent writers to 04-Archives/Daily/manifest.jsonl race and can corrupt the index. Remove the extra cron job or hook, then run vault_audit.py to check the vault:

  python3 _System/Scripts/vault_audit.py
  

The review queue is empty link

• Candidates only appear after staging. Run python3 _System/Scripts/consolidate_memory.py, then python _System/Scripts/promote_memory.py --list.
• A fresh vault correctly prints [].
• If your agent stages facts through MCP, check that its client is pointed at the right vault (see above).

A promoted fact is not showing up in Hermes link

Promoting writes to the vault side. Copy it to Hermes’s own memory with the sync script, and preview first:

  python _System/Scripts/sync_to_hermes.py --dry-run
python _System/Scripts/sync_to_hermes.py
  

Then start a new chat. Memory is injected at the start of a turn, so an already-open conversation may not see it.

The Obsidian Local REST API key link

The plugin generates its own key the first time you enable it. The template ships without one. Store it in Hermes’s protected environment, never as a note in the vault:

  hermes config set env.OBSIDIAN_REST_API_KEY "<your-key>"
  

Updating without losing my notes link

Run the update script from inside your vault. It refreshes scripts, templates, and configs, and leaves Daily/, Memory-Review/ and your profile alone:

  ./_System/Scripts/Installers/update.sh        # Linux / macOS
.\_System\Scripts\Installers\update.ps1       # Windows
  

To see what an update would touch before running it, use the drift checker, which sorts each file into safe, customised, outdated, or missing:

  python3 _System/Scripts/template_drift.py
  

This documentation site link

Problems with the docs site itself, such as a 502 error or a page that will not update, are covered on the Deployment page.

Still stuck? link

Open a Discussion to ask a question, or file an issue for a bug. Include the output of verify_install and the --test run.