hermes - 💡(How to fix) Fix [Bug]: nixosModule `documents` option installs files to wrong paths [1 pull requests]

Bug Description

The documents option in nix/nixosModules.nix installs all files into workingDirectory (default /var/lib/hermes/workspace), but hermes-agent reads personality/memory files from $HERMES_HOME and $HERMES_HOME/memories/, not from the working directory. This means SOUL.md, USER.md, and MEMORY.md placed via the documents option are silently ignored.

Steps to Reproduce

1. Configure services.hermes-agent.documents."SOUL.md" with some content in your NixOS config
2. Deploy / rebuild
3. Observe that the file appears at /var/lib/hermes/workspace/SOUL.md
4. Start hermes gateway — the agent does NOT pick up the SOUL.md personality

Expected Behavior

• SOUL.md should be installed to $HERMES_HOME/SOUL.md (i.e. ${cfg.stateDir}/.hermes/SOUL.md)
• USER.md / MEMORY.md should be installed to $HERMES_HOME/memories/ (i.e. ${cfg.stateDir}/.hermes/memories/)
• Project context files (AGENTS.md, .cursorrules, etc.) should remain in workingDirectory ✅ (already correct)

Actual Behavior

All documents entries are installed to workingDirectory:

install -o ${cfg.user} -g ${cfg.group} -m 0640 ${documentDerivation}/${name} ${cfg.workingDirectory}/${name}

With default paths:

• SOUL.md → /var/lib/hermes/workspace/SOUL.md ❌ (should be /var/lib/hermes/.hermes/SOUL.md)
• USER.md → /var/lib/hermes/workspace/USER.md ❌ (should be /var/lib/hermes/.hermes/memories/USER.md)

Where hermes-agent actually reads files

Secondary issue: nested keys not supported

The documents attrset does not support nested paths like "memories/USER.md" as keys:

1. documentDerivation only does mkdir -p $out, so $out/memories/ is never created → cp/cat fails at build time
2. install command does not use -D flag, so parent directories are not created at activation time

Affected Component

• Configuration (config.yaml, .env, hermes setup)
• Setup / Installation

Debug Report

N/A — this is a NixOS module configuration issue, not a runtime bug. The code analysis is provided above.

Operating System

NixOS (any version using the flake nixosModule)

Hermes Version

main branch (755b74fc2)

Root Cause Analysis

File: nix/nixosModules.nix

1. Line 821: Activation script hardcodes workingDirectory as install target for all documents, but hermes-agent reads SOUL.md from HERMES_HOME and USER.md/MEMORY.md from HERMES_HOME/memories/
2. Lines 55-65: documentDerivation does not mkdir -p for subdirectory components of the key name, breaking nested attr keys like "memories/USER.md"

Proposed Fix

Route files to the correct target path based on filename:

${lib.concatStringsSep "\n" (lib.mapAttrsToList (name: _value: let
  target = if name == "SOUL.md" then "${cfg.stateDir}/.hermes/SOUL.md"
    else if lib.elem name ["USER.md" "MEMORY.md"] then "${cfg.stateDir}/.hermes/memories/${name}"
    else "${cfg.workingDirectory}/${name}";
in ''
  install -D -o ${cfg.user} -g ${cfg.group} -m 0640 ${documentDerivation}/${name} ${target}
'') cfg.documents)}

And fix documentDerivation to handle nested keys:

lib.mapAttrsToList (name: value: let
  dir = dirOf name;
in ''
  mkdir -p $out/${dir}
  ${if builtins.isPath value || lib.isStorePath value
    then "cp ${value} $out/${name}"
    else "cat > $out/${name} <<'HERMES_DOC_EOF'\n${value}\nHERMES_DOC_EOF"}
'')

Are you willing to submit a PR for this?

• I'd like to fix this myself and submit a PR