Contexto: a retrieval plugin for OpenClaw and Hermes agents that compact their context

The failure mode Contexto is built around

Long agent sessions do not fail loudly. They fail at turn 35, when the agent deletes twelve flagged emails because the instruction at turn 2 said flag only, never delete, and that instruction was compacted into a summary somewhere around turn 20. The README frames this as the core problem: early instructions get compacted away, summaries turn into summaries of summaries, unrelated topics blur together, and the agent becomes less reliable the longer you use it. Contexto is aimed at that specific degradation, not at general agent quality. The audience is narrow and stated plainly. OpenClaw or Hermes users whose sessions run long enough to compact, and agents where a forgotten constraint is expensive. The README also states the inverse: not for one-shot chats or very short sessions. If your sessions never reach the compaction threshold, the plugin has nothing to ingest and nothing to retrieve, so the install cost buys you nothing.

Episodes, AGNES clustering and beam search retrieval

The mechanism has four stages, and the README is specific about each. OpenClaw buffers conversation turns as full episodes, where an episode is a complete turn including tool output rather than a condensed representation. When the prompt budget crosses the compaction threshold, the oldest episodes are ingested instead of being discarded into a summary entry. Ingested episodes are then clustered with hierarchical similarity, which the README names as AGNES, so related work lands in the same branch without predefined categories. Retrieval at prompt time uses multi-branch beam search, which can pull from several relevant branches in a single pass. The stated storage unit matters here. Because the raw turn and its tool output survive, retrieval returns the original constraint rather than a paraphrase of it, which is the difference between the agent reading flag only, never delete and the agent reading a summary that mentioned email handling. The README also describes a hybrid rebuild strategy: periodic full rebuilds plus cheaper incremental inserts between them. That is a maintenance-shaped design decision, and the documentation does not quantify when a full rebuild triggers or what it costs.

Installing it into OpenClaw and Hermes

OpenClaw installation is five commands. The plugin is installed from npm as @ekai/contexto, enabled, then wired into the context engine slot with openclaw config set plugins.slots.contextEngine contexto. The API key goes in at plugins.entries.contexto.config.apiKey, and the gateway restarts. Hermes takes a different path: pip install contexto-hermes, then contexto-hermes-install, which the README says symlinks the plugin into hermes-agent. You then enable it by editing ~/.hermes/config.yaml so that context.engine is set to contexto, export CONTEXTO_API_KEY, and run hermes gateway run. The configuration table lists exactly one property, apiKey, marked required. That is the whole config surface for the hosted path. The README points to docs/contexto-hermes-quickstart.md for a fully local setup that runs embeddings and summarization against your own OpenAI or OpenRouter key with the mindmap on disk. That document is the one to read if you cannot send conversation content to a remote service, because the default path does.

The hosted backend is the default, and that is the main constraint

The engine talks to storage through an interface called ContextoBackend, and the default remote backend calls api.getcontexto.com. The README shows the interface with an ingest method taking a WebhookPayload or an array of them, and a search method taking a query string, a maxResults number, and an optional filter object. The listing is truncated mid-signature, so the full contract is not visible in the README; you would need the source. Two consequences follow. First, the out-of-the-box deployment sends episode content, including tool output, to a third-party endpoint, which is a data-handling decision your team has to make before the first install rather than after. Second, the custom backend path exists but is an interface you implement yourself, not a configuration flag. The README does not describe a reference implementation or a local backend that ships in the package. The local Hermes quickstart is the documented alternative, and it is Hermes-specific. OpenClaw users who need local retrieval have no equivalent path described in the material.

Where the documentation stops short

Several things a buyer would want are absent. There are no numbers for retrieval latency, ingestion cost, or the token overhead that retrieved episodes add back to the prompt. There is no description of what happens when the Contexto API is unreachable mid-session: whether the agent falls back to default OpenClaw compaction, blocks, or errors. The compaction threshold is referenced but never given a value or a config key, so you cannot tune when ingestion starts. The clustering parameters for AGNES are not exposed in the configuration table, which lists only apiKey. The comparison table in the README contrasts Contexto against default OpenClaw behaviour on four axes, and it is a fair summary of the design intent, but it is the project's own framing and contains no measurements. The explainable retrieval paths shown as travel -> Japan -> visa docs are a genuine diagnostic feature, and they are the thing I would check first on a real workload, because a path that looks wrong tells you the clustering put unrelated episodes in the same branch.

How it differs from a memory layer bolted onto the prompt

The obvious alternative is a vector store plus a retrieval step you write yourself, or a memory plugin that appends recalled facts to the system prompt. The difference is structural. A flat vector index retrieves by embedding similarity alone, so an episode about travel insurance can surface during a task about email triage if the surface wording is close. Contexto clusters episodes hierarchically first and then runs beam search across branches, which the README describes as keeping topics separated so retrieval stays clean. Whether that beats a well-tuned flat index depends on how topically tangled your sessions are, and the material offers no benchmark either way. The second difference is what gets stored. A summarization-based memory layer stores derived text and inherits its losses. Contexto stores the full episode including tool output and retrieves the original, which is why the flag only, never delete constraint can come back verbatim. The trade is storage volume and retrieval cost against fidelity, and the README does not say how large episodes get or how many are retained.

Licence, maintenance and what upgrades cost you

Contexto is Apache-2.0, which permits commercial use, modification and redistribution provided you keep the licence and notice files and state significant changes. That covers the plugin code. It does not cover the hosted service at api.getcontexto.com, which is a separate commercial relationship governed by your API key and whatever terms getcontexto.com sets; the repository licence tells you nothing about the service's availability, pricing or data retention. Do not read Apache-2.0 as a guarantee about the backend. On maintenance, the release history shows v0.1.11 in April 2026 and a legacy snapshot tag from February 2026, so the project is pre-1.0 and versioned accordingly. The README documents one config key, which means upgrades are unlikely to break your configuration, but a pre-1.0 plugin that occupies the contextEngine slot sits directly in the path between your agent and the model. If a release changes the ContextoBackend interface, any custom backend you wrote has to be updated in step, and the truncated interface listing in the README means you should read the TypeScript source rather than the README before implementing one.

Editorial conclusion

Adopt Contexto if you run OpenClaw or hermes-agent sessions long enough to hit compaction and you can accept a hosted retrieval service behind an API key. Do not adopt it for one-shot chats, short sessions, or any deployment where an external endpoint at api.getcontexto.com is not acceptable. Before installing, verify three things: that the plugin slot name plugins.slots.contextEngine matches your OpenClaw build, that your Hermes version reads context.engine from ~/.hermes/config.yaml, and that the local backend path in docs/contexto-hermes-quickstart.md actually points embeddings and summarization at your own OpenAI or OpenRouter key rather than the hosted service.

Official sources

1. ekailabs/contexto on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases