ekailabs · sm86 · Jun 10, 2026 · May 26, 2026 · May 28, 2026 · May 28, 2026
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 <h1 align="center">Contexto</h1>
-<h2 align="center">Keep long-running OpenClaw agents reliable after the context window fills.</h2>
-<p align="center">A drop-in OpenClaw context engine that retrieves old constraints instead of losing them to summaries.</p>
+<h2 align="center">Keep long-running OpenClaw and Hermes agents reliable after the context window fills.</h2>
+<p align="center">A drop-in context engine for OpenClaw and hermes-agent that retrieves old constraints instead of losing them to summaries.</p>
 
 <p align="center">
   <a href="#quick-start">Quick Start</a>&nbsp;&nbsp;&bull;&nbsp;&nbsp;
@@ -18,7 +18,7 @@
 </p>
 
 <p align="center">
-  OpenClaw works well until long sessions start compacting away the exact instruction that mattered.<br />
+  OpenClaw and hermes-agent work well until long sessions start compacting away the exact instruction that mattered.<br />
   Contexto is the context engine built for that failure mode.
 </p>
 
@@ -64,7 +64,7 @@ The instruction survives compaction.
 
 ## Why Contexto
 
-Contexto is a context engine for OpenClaw. It is built for the exact moment OpenClaw starts dropping or blurring the context your agent still needs:
+Contexto is a context engine plugin. It runs inside OpenClaw and hermes-agent today, and is built for the exact moment your agent starts dropping or blurring the context it still needs:
 
 - early instructions get compacted away
 - summaries turn into summaries of summaries
@@ -79,11 +79,13 @@ Contexto fixes that by storing full episodes and retrieving only the context tha
 - Stores full episodes instead of collapsing everything into lossy summaries
 - Separates topics with semantic clustering so retrieval stays clean
 - Surfaces explainable paths such as `travel -> Japan -> visa docs`
-- Drops into OpenClaw as one plugin with one config key
+- Drops into OpenClaw or Hermes as one plugin with one config key
 
 ## Quick Start
 
-Built for OpenClaw today. Managed hosting is available, so you do not need to run retrieval infrastructure yourself.
+Built for OpenClaw and Hermes today. Managed hosting is available, so you do not need to run retrieval infrastructure yourself.
+
+### OpenClaw
 
 ```bash
 openclaw plugins install @ekai/contexto
@@ -93,13 +95,36 @@ openclaw config set plugins.entries.contexto.config.apiKey YOUR_KEY
 openclaw gateway restart
 ```
 
+### Hermes
+
+```bash
+pip install contexto-hermes
+contexto-hermes-install            # symlinks the plugin into hermes-agent
+```
+
+Enable it in `~/.hermes/config.yaml`:
+
+```yaml
+context:
+  engine: contexto
+```
+
+Then set the key and run:
+
+```bash
+export CONTEXTO_API_KEY=YOUR_KEY
+hermes gateway run
+```
+
+For a fully local setup — embeddings + summarization against your own OpenAI or OpenRouter key, mindmap on disk — see [docs/contexto-hermes-quickstart.md](docs/contexto-hermes-quickstart.md).
+
 Get an API key at [getcontexto.com](https://getcontexto.com/).
 
 If your agent ever forgets a rule, preference, or prior decision after a long run, this is the switch to try first.
 
 ## Who Should Use This
 
-- OpenClaw users whose sessions run long enough to compact
+- OpenClaw or Hermes users whose sessions run long enough to compact
 - Agents where forgotten constraints are costly
 - Teams that want better reliability without prompt hacks
 - Not for one-shot chats or very short sessions
@@ -171,7 +196,6 @@ interface ContextoBackend {
 - [ ] Horizontal scaling with sub-agent context delegation
 - [ ] Scoped context with access boundaries
 - [ ] Knowledge from external documents
-- [ ] Local backend
 - [ ] Context sharing across agents
 
 ## Community

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -4,6 +4,7 @@
 * [Architecture Overview](architecture-overview.md)
 * [Getting Started](getting-started.md)
 * [Contexto Plugin](contexto.md)
+* [Contexto-Hermes Quickstart](contexto-hermes-quickstart.md)
 * [Memory](memory-plugin.md)
 * [Supported Providers and Models](providers-and-models.md)
 * [OpenRouter Integration Quickstart](openrouter-quickstart.md)

diff --git a/docs/contexto-hermes-quickstart.md b/docs/contexto-hermes-quickstart.md
@@ -0,0 +1,106 @@
+# Contexto-Hermes Quickstart
+
+Install Contexto as a context engine in [hermes-agent](https://hermes-agent.nousresearch.com) in a few minutes. Two backends to choose from — they install the same way and differ only in env vars.
+
+| | **Remote** *(default)* | **Local** |
+|---|---|---|
+| Storage | Contexto cloud | On-disk JSON (`$HERMES_HOME/data/contexto/mindmap.json`) |
+| Embeddings + summarization | Contexto-hosted | Your OpenAI **or** OpenRouter key |
+| Required key | `CONTEXTO_API_KEY` from [getcontexto.com](https://getcontexto.com) | `OPENAI_API_KEY` *or* `OPENROUTER_API_KEY` |
+| Extra deps | none beyond `httpx` | `numpy`, `scipy` (installed automatically) |
+| Best for | Zero local setup, managed retrieval | Air-gapped / BYOK / "no third-party context store" |
+
+## 0. Prereqs
+
+- Python 3.10 or newer.
+- `hermes-agent` installed and importable (i.e. `python -c "import plugins.context_engine"` resolves). If you don't have it yet, follow the hermes-agent install instructions first, then come back.
+
+## 1. Install the plugin (both backends)
+
+```bash
+pip install contexto-hermes
+contexto-hermes-install        # symlinks the plugin into hermes-agent's tree
+```
+
+`contexto-hermes-install` finds hermes via the same import path Hermes uses. To point at a non-default checkout: `HERMES_AGENT_ROOT=/path/to/hermes-agent contexto-hermes-install`.
+
+Then enable the engine in `~/.hermes/config.yaml`:
+
+```yaml
+context:
+  engine: contexto
+```
+
+That's it for installation. The remaining step is one or two env vars to pick a backend.
+
+## 2a. Remote backend (default)
+
+```bash
+export CONTEXTO_API_KEY=ckai_xxx          # from https://getcontexto.com
+hermes chat                                # or `hermes gateway run`
+```
+
+Nothing else to configure. `CONTEXTO_BACKEND` defaults to `remote`.
+
+## 2b. Local backend
+
+```bash
+export CONTEXTO_BACKEND=local
+export OPENROUTER_API_KEY=sk-or-xxx        # or: export OPENAI_API_KEY=sk-xxx
+hermes chat                                # or `hermes gateway run`
+```
+
+Provider is auto-detected from the key you set. If both keys are exported, OpenRouter wins; pin explicitly with `CONTEXTO_LOCAL_PROVIDER=openai|openrouter`. The mindmap lands at `~/.hermes/data/contexto/mindmap.json` after the first `compress()`.
+
+## 3. Verify it's wired up
+
+After enough chat turns to trigger compaction:
+
+```bash
+# Hermes logs — confirm no registration error.
+# If anything is wrong you'll see one of these and Hermes falls back silently:
+#   "Contexto plugin not registered: CONTEXTO_API_KEY is not set"
+#   "Contexto plugin (local) not registered: local config invalid"
+grep -i "contexto plugin" ~/.hermes/logs/hermes.log
+
+# Local backend only — inspect the on-disk mindmap.
+jq '.version, .stats' ~/.hermes/data/contexto/mindmap.json
+```
+
+A healthy local backend prints `1` and `{"total_items": N, "total_clusters": M, ...}`.
+
+## Running inside Docker
+
+The hermes-agent base image needs two adjustments when using the local backend:
+
+1. **Plugin source.** The bundled `plugins/context_engine/contexto/` is an absolute symlink that `docker build` resolves to a host path. Bind-mount the source at runtime instead:
+   ```yaml
+   volumes:
+     - /path/to/contexto/packages/contexto-py/src/contexto_hermes:/opt/hermes/plugins/context_engine/contexto:ro
+   ```
+2. **Runtime deps.** Install `numpy` + `scipy` into the image's venv before launching:
+   ```yaml
+   command:
+     - sh
+     - -c
+     - |
+       uv pip install --python /opt/hermes/.venv/bin/python numpy scipy \
+         && exec hermes gateway run
+   ```
+
+A ready-to-use compose file is at [`packages/contexto-py/e2e/docker-compose.hermes-local.yml`](../packages/contexto-py/e2e/docker-compose.hermes-local.yml).
+
+The remote backend has no extra Docker requirements — just `CONTEXTO_API_KEY` in the environment.
+
+## Full config reference
+
+The most common knobs are above. For everything else — `CONTEXTO_MAX_RESULTS`, `CONTEXTO_MIN_SCORE`, `CONTEXTO_LOCAL_SIMILARITY_THRESHOLD`, model overrides, timeouts, status fields — see the package README at [`packages/contexto-py/README.md`](../packages/contexto-py/README.md).
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+|---|---|
+| `Contexto plugin not registered: CONTEXTO_API_KEY is not set` | Remote backend selected (default) but no API key in env. |
+| `Contexto plugin (local) not registered: local config invalid` | Local backend selected but neither `OPENAI_API_KEY` nor `OPENROUTER_API_KEY` is set, or `CONTEXTO_LOCAL_PROVIDER` is unknown. Check the line above this in the log for the specific reason. |
+| `ModuleNotFoundError: No module named 'numpy'` (Docker) | The image doesn't ship numpy/scipy — install them into the venv as shown above. |
+| `Could not locate hermes-agent's plugins/context_engine directory` from `contexto-hermes-install` | hermes-agent isn't installed in the same Python environment. Activate the venv first, or set `HERMES_AGENT_ROOT`. |