Development - Retinue

Retinue uses:

model2vec

Static embedding model (minishlab/potion-multilingual-128M, ~540 MB download on first use, then offline; the repo's unused ~512 MB ONNX export is skipped). Understands meaning across languages.

sqlite-vec

SQLite extension for vector similarity search. No server, no daemon, no port.

Unified store

All memories share one table. Each memory has a content string, a timestamp, and an auto-generated embedding.

Install Retinue is the deployment bridge between the Retinue workspace and the active Hermes home. It is intended for iterative development: edit the source tree, run the script, and test inside Hermes immediately.

The script is idempotent, so you can run it after every code change. It preserves runtime artifacts (the database, virtual environments, and caches) while replacing the plugin source code.

What it does, in order:

1. Detects the active Hermes home from the HERMES_HOME environment variable, or falls back to $HOME/.hermes.
2. Creates $HERMES_HOME/plugins/retinue/ and its .hf-cache/ subdirectory if they do not exist.
3. Removes every previously deployed item in the plugin directory except the PRESERVE list (.venv, .hf-cache), so stale code cannot linger.
4. Copies the whitelist (plugin.yaml __init__.py src) from the workspace into the plugin directory with cp.
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).
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 unused ~512 MB ONNX export (ignore_patterns["onnx/*"]=) and loads from the returned local path, so the cache is ~540 MB and the first Hermes session does not stall. Failure here is non-fatal: a warning is printed 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.

To target a specific Hermes profile or home directory:

HERMES_HOME="$HOME/.hermes/profiles/coder" bash "Install Retinue"

When Retinue is the active memory provider, Hermes can call these tools natively. The exact names and schemas are defined in get_tool_schemas() and dispatched through handle_tool_call().

1. LLM decides something is worth remembering it issues the call:

   retinue_memory_add({"content": "ProjectX is hosted on our primary server"})
   

   Alternative trigger: LLM instead calls Hermes' built-in memory tool. Hermes then calls Retinue's on_memory_write hook, which feeds the same text into the same chain at step 2. Both triggers produce one identical memory in the same single store — one memory system, two ways to trigger a save.

2. Hermes routes it to handle_tool_call("retinue_memory_add", args).
3. Text is embedded with model2vec into a float32 vector packed as bytes. On the first call in a process, memory.py resolves the model snapshot with snapshot_download(MODEL, ignore_patterns["onnx/*"])= (skipping the repo's unused ~512 MB ONNX export) and loads StaticModel from the returned local path — loading from a local path is what prevents re-fetching the skipped files on every load;

4. Resulting vector with original text is written into database

   INSERT INTO memories (embedding, content, created)
   

5. JSON string is then returned back to the LLM:

   {"success": true, "result": {"id": 1, "content": "ProjectX is hosted on our primary server"}}
   

Retrieval happens through exactly one concrete path: the retinue_memory_search tool. The prefetch hook is a no-op, so nothing is injected automatically — every retrieval is an explicit tool call visible in the conversation transcript.

The step-by-step mechanics:

1. The LLM is notified the tool exists. At session start Hermes calls get_tool_schemas() and places all four retinue_memory_* schemas into the LLM's tool list next to the built-in tools. The retinue_memory_search schema declares two parameters: query (required string) and limit (optional integer, default 50). Separately, the text of src/retinue/system_prompt_block.txt is injected into the system prompt, instructing the LLM to run retinue_memory_search before acting on a task.
2. The LLM invokes it with a natural-language query. Example call: retinue_memory_search({"query": "coworker", "limit": 2}).
3. Retinue embeds the query and runs a vector query. The query text is embedded with the same model2vec model used at write time, then MemoryStore.search() executes a sqlite-vec KNN query: WHERE embedding MATCH ? AND k = <limit> against the memories virtual table.
4. Result count is limited by count only. The k parameter is a hard top-N cap: sqlite-vec returns at most limit nearest rows, with no similarity threshold. Even a nonsense query ("zzzzqqq nonexistent") returns exactly limit rows. Filtering weak matches is left to the LLM reading the scores.
5. Results are sorted best-first. sqlite-vec orders KNN results by ascending distance, so the most similar memory is always results[0]. Ordering is deterministic; ties can occur (two different memories scored 0.458 on the same query).

6. The tool returns a JSON string — the result of json.dumps({"success": True, "result": [...]}). Each element has four fields: id (the rowid, for retinue_memory_delete), content (full stored text), created (ISO 8601 UTC timestamp), and similarity. The similarity is computed in provider.py from the raw sqlite-vec distance as 1 / (1 + distance) — higher is better, 1.0 means identical vectors. (Raw distance in the database is unbounded L2 on the model's non-normalized embeddings, so typical real-world matches land in the 0.4–0.6 range; treat the score as a relative ranking signal, not an absolute confidence.)

   {"success": true, "result": [
     {"id": 2, "content": "Coworker John reads Spanish",
      "created": "2026-07-17T20:33:43.081952+00:00", "similarity": 0.4626},
     {"id": 1, "content": "ProjectX is hosted on our serverY",
      "created": "2026-07-17T20:33:40.987271+00:00", "similarity": 0.4357}
   ]}
   

   (Captured verbatim from handle_tool_call("retinue_memory_search", {"query": "coworker", "limit": 2}) against a store holding exactly those two memories; similarity values shortened for print.)

1. The LLM reads the JSON and decides. Weak-looking results (all scores near the noise floor) mean the store has nothing relevant; the LLM proceeds without memory context.

Retinue is developed in its own source tree and deployed into the active Hermes home with Install Retinue. This makes iteration fast and safe: the runtime data/ directory lives in Hermes, while the source code lives in the workspace.