docs(hermes): document GitHub and catalog installation

README.md

@@ -96,6 +96,7 @@ Every memory mutation has a snapshot + provenance chain
   <a href="https://openai.com/index/introducing-codex/"><img src="https://img.shields.io/badge/Codex-412991?style=for-the-badge&logo=openai&logoColor=white" alt="Codex"/></a>
   <a href="https://geminicli.com"><img src="https://img.shields.io/badge/Gemini_CLI-4285F4?style=for-the-badge&logo=google&logoColor=white" alt="Gemini CLI"/></a>
   <a href="plugins/openclaw/README.md"><img src="https://img.shields.io/badge/OpenClaw-FF6B6B?style=for-the-badge" alt="OpenClaw"/></a>
+  <a href="plugins/hermes/README.md"><img src="https://img.shields.io/badge/Hermes-8B5CF6?style=for-the-badge" alt="Hermes"/></a>
 </p>
 
 <p align="center"><i>Works with any MCP-compatible agent</i></p>

plugins/hermes/README.md

@@ -4,19 +4,114 @@ Native Hermes memory provider, using the free Memoria Cloud by default. Users do
 need to deploy a database, embedding model, extraction model or local Memoria server.
 Self-hosted users can change the API origin in the same plugin.
 
-**Development preview, version 0.1.1.** Source is ready for local installation and
-testing; this directory has not yet been published or accepted into the Hermes
-catalog. The 0.1.0 Cloud API acceptance passed on October 8, 2026; the new
-deduplicated-capture route requires server deployment and a fresh live check. See
-[CLOUD_ACCEPTANCE.md](CLOUD_ACCEPTANCE.md) for the tested scope and results.
+**Development preview, version 0.1.1.** Source is published on GitHub and can be
+installed directly. The [Hermes catalog submission](https://github.com/NousResearch/hermes-agent/pull/135490)
+is awaiting review; installation by name becomes available after catalog acceptance.
+See [CLOUD_ACCEPTANCE.md](CLOUD_ACCEPTANCE.md) for the recorded Cloud API acceptance
+scope and results. Self-hosted APIs must include the matching deduplicated-capture
+route before using automatic capture with explicit-write exclusions.
 
-## Install the current checkout
+## Installation
 
 Requires Hermes ≥ 0.21.5 and its Python ≥ 3.11. The tested Hermes checkout is
 `0240fa4a84123406a0e5e6e7262e5b772b43f0bd` (0.21.5, September 2026).
 Hermes releases sharing a version number may have different plugin APIs; run
 `hermes plugins validate` on the actual target installation.
 
+Choose one of the following installation methods. The GitHub guide below includes
+configuration and a first conversation; the other methods use the shared
+[setup steps](#configure-memoria).
+
+### 1. Install from GitHub
+
+These steps use the default Hermes profile. For an existing named profile, add
+`-p <profile-name>` to **every** Hermes command below.
+
+**Step 1: Get a Memoria API key.**
+
+Log in at [Memoria](https://thememoria.ai) and create/copy a memory-service API Key.
+Keep it ready for the setup prompt; the website login session token is not the API Key.
+
+**Step 2: Install the plugin.**
+
+Install the commit verified in the October 9, 2026 local CLI acceptance:
+
+```sh
+hermes plugins install 'https://github.com/matrixorigin/memoria#plugins/hermes' \
+  --ref 3a5c5065b2820d56dd3d8ac8bb259a9424b1476e \
+  --yes-deps --enable
+```
+
+The `#plugins/hermes` suffix selects the plugin directory inside the Memoria
+repository. `--yes-deps` authorizes preparation of its declared Python dependencies;
+`--enable` selects Memoria as the memory provider.
+
+**Step 3: Configure the API key and automatic capture.**
+
+Run the interactive setup wizard:
+
+```sh
+hermes memory setup
+```
+
+Select **memoria** in the provider picker, then paste your API key at the
+Memoria API Key prompt. Input is masked. If a key is already configured, press
+Enter to keep it or paste a replacement.
+
+At the automatic capture prompt, enter `true` to upload completed user/assistant
+turns for background fact extraction, or `false` to use recall and explicit
+memory tools without automatic uploads. Tool results are excluded from capture.
+
+Use `hermes memory setup` for this step. In the tested Hermes CLI,
+`hermes memory setup memoria` only activates the provider and does not prompt for
+the key or capture setting.
+
+**Step 4: Check the configuration.**
+
+```sh
+hermes memory status
+```
+
+Check that the provider is `memoria`, the plugin is installed, and its status is
+`available`. If `MEMORIA_API_KEY` is listed as missing, repeat Step 3 in the same
+profile. This checks local readiness; it does not verify a request to Memoria Cloud.
+
+**Step 5: Start a new conversation.**
+
+Exit any existing Hermes conversation and start a new one:
+
+```sh
+hermes
+```
+
+Hermes also needs a configured chat-model provider and its credentials. The
+Memoria API key authenticates memory operations only.
+
+To check a real memory write, say: "Remember that I prefer unsweetened coffee."
+Confirm that `memoria_store` succeeds, then exit and start another conversation
+with `hermes`. Ask: "How do I like my coffee?" Check that the answer recalls the
+saved preference. You can then ask Hermes to forget that test preference.
+
+### 2. Install from the Hermes catalog (after acceptance)
+
+Use this method only after the catalog PR is merged and the Memoria entry is
+available in your Hermes catalog. Check for it with:
+
+```sh
+hermes plugins search memoria
+```
+
+Then install the reviewed catalog version:
+
+```sh
+hermes plugins install memoria --yes-deps --enable
+```
+
+The catalog supplies the reviewed commit automatically. If Memoria is not listed,
+use the GitHub installation above instead.
+
+### 3. Install from a local checkout (development)
+
 Copy this directory into **the active profile's** `$HERMES_HOME/plugins/memoria`.
 For a default profile whose home is `~/.hermes`, from the Memoria repository:
 
@@ -25,33 +120,54 @@ mkdir -p ~/.hermes/plugins
 cp -R plugins/hermes ~/.hermes/plugins/memoria
 hermes plugins validate ~/.hermes/plugins/memoria --install-deps
 hermes plugins enable memoria
+```
+
+Do not overwrite an existing `plugins/memoria` directory without checking its contents.
+
+### Configure Memoria
+
+After installing with any of the methods above:
+
+```sh
 hermes memory setup
+```
+
+In the interactive provider picker, select **memoria**. At the Memoria API Key
+prompt, paste your key; the input is masked. If a key is already configured,
+press Enter to keep it or paste a replacement. Then choose `true` or `false`
+for automatic capture and check the resulting configuration:
+
+```sh
 hermes memory status
 ```
 
-Choose **Memoria** in setup. Log in at [Memoria](https://thememoria.ai), create/copy
-a memory-service API Key, and paste it into setup. The website login session token
+Log in at [Memoria](https://thememoria.ai), create/copy a memory-service API Key,
+and paste it into the interactive setup prompt. The website login session token
 is not the API Key. Hermes stores `MEMORIA_API_KEY` in the active profile's secret
 store; never put it in `memoria.json` or in a shell command.
 
+Use the interactive command above for initial configuration. In the tested Hermes
+CLI, `hermes memory setup memoria` only prepares dependencies and activates the
+provider; it does **not** prompt for the API key or automatic capture.
+
 Setup also asks whether to upload completed user/assistant turns for background
 fact extraction. This is **off until opted in**. Auto recall and explicit memory
 tools work without auto capture. Restart the current Hermes conversation after setup.
 
-If using a named profile, substitute its actual home for every `~/.hermes` above
-and run the commands with that profile selected. Do not overwrite an existing
-`plugins/memoria` directory without checking its contents.
-
-After source is published, the Git distribution form is:
+For an existing named profile, use `-p <profile-name>` on every Hermes command.
+For example, install and configure the plugin in `memoria-acceptance`:
 
 ```sh
-hermes plugins install 'https://github.com/matrixorigin/Memoria#plugins/hermes' --ref <FULL_40_CHARACTER_RELEASE_SHA>
-hermes memory setup
+hermes -p memoria-acceptance plugins install 'https://github.com/matrixorigin/memoria#plugins/hermes' \
+  --ref 3a5c5065b2820d56dd3d8ac8bb259a9424b1476e \
+  --yes-deps --enable
+hermes -p memoria-acceptance memory setup
+hermes -p memoria-acceptance memory status
 ```
 
-Replace the placeholder with the reviewed commit that actually contains this
-directory. `hermes plugins install memoria` becomes valid only after catalog acceptance.
-Enabling the general plugin alone does not select it as the memory provider.
+For a local-copy installation into a named profile, also substitute its actual
+home for every `~/.hermes` path above. Selecting the general plugin is not a
+substitute for configuring the memory provider and its API key.
 
 ## What this preview implements