From 8c9ee6477e79a6ab7194b74ca4b05a5e57bf9b5e Mon Sep 17 00:00:00 2001 From: lr90 Date: Fri, 9 Oct 2026 15:45:11 +0800 Subject: [PATCH 1/3] docs(hermes): document GitHub and catalog installation --- README.md | 1 + plugins/hermes/README.md | 85 +++++++++++++++++++++++++++++++--------- 2 files changed, 67 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 3c95dc8e..23cdebd3 100644 --- a/README.md +++ b/README.md @@ -96,6 +96,7 @@ Every memory mutation has a snapshot + provenance chain Codex Gemini CLI OpenClaw + Hermes

Works with any MCP-compatible agent

diff --git a/plugins/hermes/README.md b/plugins/hermes/README.md index c0986cd9..e3f737f8 100644 --- a/plugins/hermes/README.md +++ b/plugins/hermes/README.md @@ -4,19 +4,57 @@ 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, then complete the shared +[setup steps](#configure-memoria). + +### 1. Install from GitHub + +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. Configure your API key next. + +### 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,12 +63,21 @@ mkdir -p ~/.hermes/plugins cp -R plugins/hermes ~/.hermes/plugins/memoria hermes plugins validate ~/.hermes/plugins/memoria --install-deps hermes plugins enable memoria -hermes memory setup +``` + +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 memoria 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 setup. 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. @@ -38,20 +85,20 @@ 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 ` 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 -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 memoria +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 From 1dab1179fe8b0230fc03e3475f23a6492f314b3e Mon Sep 17 00:00:00 2001 From: lr90 Date: Fri, 9 Oct 2026 15:53:53 +0800 Subject: [PATCH 2/3] docs(hermes): use interactive setup for API key configuration --- plugins/hermes/README.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/plugins/hermes/README.md b/plugins/hermes/README.md index e3f737f8..c11fdbdd 100644 --- a/plugins/hermes/README.md +++ b/plugins/hermes/README.md @@ -72,15 +72,27 @@ Do not overwrite an existing `plugins/memoria` directory without checking its co After installing with any of the methods above: ```sh -hermes memory setup memoria +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 ``` Log in at [Memoria](https://thememoria.ai), create/copy a memory-service API Key, -and paste it into setup. The website login session token +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. @@ -92,7 +104,7 @@ For example, install and configure the plugin in `memoria-acceptance`: hermes -p memoria-acceptance plugins install 'https://github.com/matrixorigin/memoria#plugins/hermes' \ --ref 3a5c5065b2820d56dd3d8ac8bb259a9424b1476e \ --yes-deps --enable -hermes -p memoria-acceptance memory setup memoria +hermes -p memoria-acceptance memory setup hermes -p memoria-acceptance memory status ``` From 4a8c73f09e9672f86f8b817b00b2f70951283fd4 Mon Sep 17 00:00:00 2001 From: lr90 Date: Fri, 9 Oct 2026 15:56:22 +0800 Subject: [PATCH 3/3] docs(hermes): include complete GitHub setup and first conversation --- plugins/hermes/README.md | 61 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 59 insertions(+), 2 deletions(-) diff --git a/plugins/hermes/README.md b/plugins/hermes/README.md index c11fdbdd..8a3409ae 100644 --- a/plugins/hermes/README.md +++ b/plugins/hermes/README.md @@ -18,11 +18,22 @@ Requires Hermes ≥ 0.21.5 and its Python ≥ 3.11. The tested Hermes checkout i 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, then complete the shared +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 ` 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 @@ -33,7 +44,53 @@ hermes plugins install 'https://github.com/matrixorigin/memoria#plugins/hermes' 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. Configure your API key next. +`--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)