From: Svjatoslav Agejenko Date: Sun, 30 Aug 2026 02:08:33 +0000 (+0300) Subject: fix(install): enable memory toolset so clean Hermes installs expose Retinue X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=commitdiff_plain;h=HEAD;p=retinue.git 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 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 --- 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: -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: @@ -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. +- *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 = 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) diff --git a/Documentation/Development/index.org b/Documentation/Development/index.org index 09863e3..d2e1b08 100644 --- 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= - 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 @@ -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. -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 = 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: diff --git a/Documentation/index.org b/Documentation/index.org index c1c1ace..9136657 100644 --- a/Documentation/index.org +++ b/Documentation/index.org @@ -64,7 +64,7 @@ cd /path/to/retinue 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=. @@ -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. -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 memory=. Verify the plugin is active: diff --git a/Install Retinue b/Install Retinue index c0db46a..069661d 100755 --- a/Install Retinue +++ b/Install Retinue @@ -290,6 +290,29 @@ else 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 memory" +fi + # Validate that the plugin imports. echo "Validating plugin import with: $PYTHON" if "$PYTHON" -c "