fix(install): enable memory toolset so clean Hermes installs expose Retinue

Found on a fresh Hermes "Blank Slate" install (valeriapc, 2026-08-30):
Retinue installed and selected via memory.provider, hermes memory status
reported the plugin available — yet the session had no retinue_memory_*
tools and no Retinue system-prompt block. Blank Slate setup writes
platform_toolsets.cli = [file, skills, terminal, vision] and lists memory
in agent.disabled_toolsets; with that gate closed Hermes initializes the
provider but withholds its entire model-facing surface.

- Install Retinue now runs `hermes tools enable --platform cli memory`
  after setting memory.provider. Verified in Hermes source
  (tools_config.py _save_platform_tools) that this both adds the toolset
  to platform_toolsets.cli and removes it from agent.disabled_toolsets.
- Failure of that step is non-fatal but fully visible: captured output
  and the manual command are printed (no silent 2>/dev/null), plus a note
  that other platforms (telegram, discord, ...) each need their own
  --platform <name> enable.
- Docs: Documentation/index.org (five installer steps),
  Documentation/Development/index.org (full step list incl. the
  pip -> ensurepip -> uv dependency chain), AGENTS.org (deploy section +
  new Blank Slate memory-toolset pitfall).

Verified with a stubbed-environment ad-hoc harness (10/10): the stub
hermes CLI receives `tools enable --platform cli memory`; a CLI that
rejects it produces a warning with the captured error and manual command
while the install still completes. Live fix applied on valeriapc:
memory now in platform_toolsets.cli and gone from agent.disabled_toolsets.

diff --git a/AGENTS.org b/AGENTS.org
index 3d286a1..06d5147 100644 (file)
--- a/AGENTS.org
+++ b/AGENTS.org
@@ -143,7 +143,9 @@ The installer is idempotent: it wipes everything under
 whitelist =(plugin.yaml __init__.py src)=, installs missing Python deps
 into the interpreter Hermes actually runs, pre-downloads the embedding
 model into =.hf-cache/= (no first-use stall), sets =memory.provider:
 whitelist =(plugin.yaml __init__.py src)=, installs missing Python deps
 into the interpreter Hermes actually runs, pre-downloads the embedding
 model into =.hf-cache/= (no first-use stall), sets =memory.provider:

-retinue=, and validates the plugin imports.
+retinue=, enables the =memory= toolset for the CLI platform (clean
+"Blank Slate" installs disable it — see pitfalls), and validates the
+plugin imports.

 
 To target a non-default Hermes home:
 
 
 To target a non-default Hermes home:
 


@@ -283,6 +285,17 @@ Never commit the generated =*.html= — they are gitignored.
   validation) now captures combined output into a temp dir (=DIAG_DIR=,
   cleaned by an EXIT trap) and prints a =show_log_tail= excerpt on
   failure. Never reintroduce bare =2>/dev/null= on a step that can fail.
   validation) now captures combined output into a temp dir (=DIAG_DIR=,
   cleaned by an EXIT trap) and prints a =show_log_tail= excerpt on
   failure. Never reintroduce bare =2>/dev/null= on a step that can fail.

+- *Pitfall: clean Hermes installs disable the =memory= toolset.* A "Blank
+  Slate" Hermes setup writes =platform_toolsets.cli: [file, skills,
+  terminal, vision]= and lists =memory= in =agent.disabled_toolsets=. With
+  that gate closed, =hermes memory status= still reports Retinue installed
+  and available, but the session never sees the =retinue_memory_*= tools or
+  the system-prompt block — the provider is active yet unusable (found
+  2026-08-30 on valeriapc: fresh Hermes + Retinue install, agent had no
+  memory tools). The installer now runs =hermes tools enable --platform cli
+  memory=, which adds the toolset and reconciles =agent.disabled_toolsets=.
+  If Retinue tools are missing in a session, check those two config keys
+  first; other platforms each need their own =--platform <name>= enable.

 - *Pitfall: gateway restart on the remote.* =systemctl --user restart
   hermes-gateway.service= can leave the unit in =activating= when an old
   gateway process (started with =gateway run --replace= outside systemd)
 - *Pitfall: gateway restart on the remote.* =systemctl --user restart
   hermes-gateway.service= can leave the unit in =activating= when an old
   gateway process (started with =gateway run --replace= outside systemd)

diff --git a/Documentation/Development/index.org b/Documentation/Development/index.org
index 09863e3..d2e1b08 100644 (file)
--- a/Documentation/Development/index.org
+++ b/Documentation/Development/index.org
@@ -114,8 +114,11 @@ What it does, in order:
 5. Resolves the Python interpreter that Hermes actually runs under (via the
    =PYTHON= environment variable, common venv layouts, or the =hermes=
    launcher shebang) and installs any missing =sqlite-vec= / =model2vec=
 5. Resolves the Python interpreter that Hermes actually runs under (via the
    =PYTHON= environment variable, common venv layouts, or the =hermes=
    launcher shebang) and installs any missing =sqlite-vec= / =model2vec=

-   dependencies into it with =pip= (falling back to
-   =--break-system-packages= inside that interpreter on PEP 668 systems).
+   dependencies into it, trying in order: =pip=, =ensurepip=-bootstrapped
+   =pip=, then =uv pip install --python= (uv is probed on =PATH= and at
+   =$HERMES_HOME/bin/uv= — Hermes bundles it there). The chain exists
+   because the Hermes runtime venv is created by =uv venv= and ships
+   without pip.

 6. Pre-downloads the embedding model into =.hf-cache/= by calling
    =retinue.memory.get_model()= with the Hermes Python — the same code path
    the plugin uses at runtime. The snapshot download skips the repo's
 6. Pre-downloads the embedding model into =.hf-cache/= by calling
    =retinue.memory.get_model()= with the Hermes Python — the same code path
    the plugin uses at runtime. The snapshot download skips the repo's


@@ -125,7 +128,18 @@ What it does, in order:
    and the model simply downloads on first use instead.
 7. Sets =memory.provider: retinue= with =hermes config set= if the CLI is
    available.
    and the model simply downloads on first use instead.
 7. Sets =memory.provider: retinue= with =hermes config set= if the CLI is
    available.

-8. Runs a lightweight import check to confirm the plugin loads.
+8. Enables the =memory= toolset for the CLI platform with =hermes tools
+   enable --platform cli memory=. Clean "Blank Slate" Hermes installs list
+   =memory= in =agent.disabled_toolsets= and exclude it from
+   =platform_toolsets.cli=, which makes Hermes withhold the
+   =retinue_memory_*= tools and the system-prompt block from the model even
+   with the provider selected; this step lifts both gates. Other platforms
+   need their own =--platform <name>= run.
+9. Runs a lightweight import check to confirm the plugin loads.
+
+Every fallible step captures its combined output into a temp directory
+(cleaned by an EXIT trap) and prints an excerpt on failure — stderr is
+never discarded silently.

 
 To target a specific Hermes profile or home directory:
 
 
 To target a specific Hermes profile or home directory:
 

diff --git a/Documentation/index.org b/Documentation/index.org
index c1c1ace..9136657 100644 (file)
--- a/Documentation/index.org
+++ b/Documentation/index.org
@@ -64,7 +64,7 @@ cd /path/to/retinue
 bash "Install Retinue"
 #+end_src
 
 bash "Install Retinue"
 #+end_src
 

-The installer performs four steps:
+The installer performs five steps:

 
 1. Detects the active Hermes home from the =HERMES_HOME= environment variable
    or falls back to =$HOME/.hermes=.
 
 1. Detects the active Hermes home from the =HERMES_HOME= environment variable
    or falls back to =$HOME/.hermes=.


@@ -81,7 +81,12 @@ The installer performs four steps:
    =$HERMES_HOME/plugins/retinue/.hf-cache/= so the first Hermes session
    does not stall on the download. The cache is preserved across
    re-installs, so this step is a no-op after the first successful run.
    =$HERMES_HOME/plugins/retinue/.hf-cache/= so the first Hermes session
    does not stall on the download. The cache is preserved across
    re-installs, so this step is a no-op after the first successful run.

-5. Sets =memory.provider: retinue=.
+5. Sets =memory.provider: retinue= and enables the =memory= toolset for the
+   CLI platform (=hermes tools enable --platform cli memory=). A clean
+   "Blank Slate" Hermes install disables the memory toolset, which would
+   withhold the =retinue_memory_*= tools from the agent even with the
+   provider selected. Other platforms (telegram, discord, ...) each need
+   their own =hermes tools enable --platform <name> memory=.

 
 Verify the plugin is active:
 
 
 Verify the plugin is active:
 

diff --git a/Install Retinue b/Install Retinue
index c0db46a..069661d 100755 (executable)
--- a/Install Retinue
+++ b/Install Retinue
@@ -290,6 +290,29 @@ else
     echo "  $HERMES_HOME/config.yaml"
 fi
 
     echo "  $HERMES_HOME/config.yaml"
 fi
 

+# Enable the memory toolset for the CLI platform. Clean "Blank Slate" Hermes
+# installs ship with memory in agent.disabled_toolsets and a
+# platform_toolsets.cli that excludes it — with that gate closed, Hermes
+# initializes the provider but withholds the retinue_memory_* tools and the
+# system-prompt block from the model, so the install looks green while the
+# agent can never call the tools (found 2026-08-30 on a fresh install).
+# `hermes tools enable` both adds the toolset to platform_toolsets.cli and
+# removes it from agent.disabled_toolsets.
+if [[ -n "$HERMES_CLI" ]]; then
+    echo "Enabling the memory toolset for cli (via $HERMES_CLI)..."
+    if "$HERMES_CLI" tools enable --platform cli memory >"$DIAG_DIR/tools-enable.log" 2>&1; then
+        echo "  memory toolset enabled for cli."
+    else
+        echo "  Warning: could not enable the memory toolset automatically."
+        echo "  --- hermes tools enable output:"
+        show_log_tail "$DIAG_DIR/tools-enable.log"
+        echo "           Run it manually:"
+        echo "             $HERMES_CLI tools enable --platform cli memory"
+    fi
+    echo "  Note: other platforms (telegram, discord, ...) each need their own:"
+    echo "        $HERMES_CLI tools enable --platform <name> memory"
+fi
+

 # Validate that the plugin imports.
 echo "Validating plugin import with: $PYTHON"
 if "$PYTHON" -c "
 # Validate that the plugin imports.
 echo "Validating plugin import with: $PYTHON"
 if "$PYTHON" -c "