Retinue — Memory provider plugin for Hermes Agent

Table of Contents

1. Overview

logo.png

Retinue is a Hermes Agent memory provider plugin that adds persistent, semantic memory to every Hermes session. Once installed and configured, it becomes Hermes' external memory backend.

Note: While Hermes already has multiple built-in memory systems, I did not find a solution that:

  • Runs fully locally, and
  • Offers semantic memory retrieval (find memories by meaning, not by the exact keyword used), and
  • Is lightweight (runs fast using CPU-only compute, with no need for a GPU)

It is built on model2vec static embeddings and sqlite-vec, so it runs offline, requires no server, and stores everything in a single SQLite database.

For technical details, read:

2. Installation

Prerequisites:

  • Hermes Agent must be installed. The hermes CLI does not need to be on PATH — the installer also probes the standard locations (~/.local/bin/hermes, ~/bin/hermes, /usr/local/bin, /usr/bin), which matters when installing over a non-login SSH shell where ~/.profile has not run.
  • Nothing else: the installer uses the Python interpreter that Hermes itself runs (~/.hermes/hermes-agent/venv), so it works even on a bare Debian/Ubuntu server without the python3-venv package.

Run the bundled installer from the Retinue source tree: 

cd /path/to/retinue
bash "Install Retinue"

The installer performs four steps:

  1. Detects the active Hermes home from the HERMES_HOME environment variable or falls back to $HOME/.hermes.
  2. Resolves the Python interpreter that Hermes uses and installs sqlite-vec and model2vec there if they are missing.
  3. Copies the Retinue source into $HERMES_HOME/plugins/retinue/, preserving any existing runtime data.
  4. Pre-downloads the embedding model (minishlab/potion-multilingual-128M, ~540 MB — the repo's unused ONNX export is skipped) into $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.

Verify the plugin is active: 

hermes memory status

Important: If Hermes is already running, restart it. Hermes loads plugins at startup, so an active session will not see the newly installed Retinue plugin until it is restarted. On a typical systemd-user setup: 

systemctl --user restart hermes-gateway.service

If the service then stays in activating and the journal says "Gateway already running (PID …)", an older gateway process still holds the lock — stop it once (kill <pid>) and Restart=always brings the new instance up.

For technical details, read: What the installer does.

2.1. Migrating from Holographic memory

If you previously used the Holographic memory provider plugin (the fact_store tool with memory_store.db), you can import your old facts into Retinue with the bundled migration tool.

Run the importer from the Retinue source tree: 

cd /path/to/retinue
"Tools/Import Holographic memories" --source /path/to/memory_store.db

The importer performs three steps:

  1. Reads every fact from the Holographic memory_store.db.
  2. Embeds each fact's content with the Retinue embedding model.
  3. Writes new memories into the active Retinue database, skipping exact duplicates.

The importer needs a Python with sqlite-vec + model2vec. It uses the project-local .venv when available; on a machine without the python3-venv package it automatically falls back to uv (Hermes bundles one at ~/.hermes/bin/uv), and finally to the Hermes runtime venv that Install Retinue already provisioned — so the importer works out of the box right after installation, with no extra packages.

To preview what would be imported without writing anything: 

"Tools/Import Holographic memories" --source /path/to/memory_store.db --dry-run

The importer is idempotent: re-running it skips every fact that is already present in the Retinue database, so it is safe to run again after an interrupted or partial import.

3. Updating

To install an update to Retinue, run the same installer again from the latest source tree: 

cd /path/to/retinue
bash "Install Retinue"

The installer is idempotent: it will replace the deployed plugin code with the current source, install any missing or updated Python dependencies, and leave the existing memory database untouched.

To verify the update after re-running the installer: 

hermes memory status

Important: Restart any running Hermes sessions. Hermes loads plugins at startup, so a running session will continue to use the previous version of Retinue until it is restarted.

For technical details, read: What the installer does.

4. Quick start

After installing the plugin, try storing and recalling a memory through a Hermes session:

  1. Store a fact: 

    Remember that ProjectX is hosted on our primary server.

    Hermes will call retinue_memory_add with the content.

  2. Later, ask a related question: 

    Where is ProjectX hosted?

    Hermes will call retinue_memory_search and retrieve the relevant memory.

5. Source code

This program is free software: released under Creative Commons Zero (CC0) license

Program author:

Getting the source code:

For detailed architecture, integration with Hermes Agent, and the project development workflow, see the dedicated Development page.

Created: 2026-07-18 la 15:26

Validate