KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #developer-tools #claude-code #ai-agent #codex #deepseek-harness #ai-agents #cli #react #mcp

contexto

★ 623 Open GitHub ↗

Context Engine for your long-running AI agents

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">Contexto</h1>
<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;
  <a href="#why-contexto">Why Contexto</a>&nbsp;&nbsp;&bull;&nbsp;&nbsp;
  <a href="#how-it-works">How It Works</a>&nbsp;&nbsp;&bull;&nbsp;&nbsp;
  <a href="https://getcontexto.com/">Website</a>&nbsp;&nbsp;&bull;&nbsp;&nbsp;
  <a href="https://discord.gg/4QTRS5ew">Discord</a>
</p>

<p align="center">
  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>

## The Problem in 15 Seconds

```text
Turn 2:
"Flag suspicious emails.
Do NOT delete anything."

[... 30 more turns:
tools, retries, compaction ...]
```

**Without Contexto**

```text
Turn 35: Agent deletes 12 flagged emails.
The constraint was lost in compaction.
```

</td>
<td width="50%">

**With Contexto**

```text
Turn 35: Agent flags 4 new suspicious emails.

Retrieved context:
  -> user constraint: flag only, never delete

The instruction survives compaction.
```

</td>
</tr>
</table>

## Why Contexto

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
- unrelated topics blur together
- the agent becomes less reliable the longer you use it

Contexto fixes that by storing full episodes and retrieving only the context that is relevant right now.

## What You Get

- Keeps important constraints retrievable even after long sessions and compaction
- 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 or Hermes as one plugin with one config key

## Quick Start

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
openclaw plugins enable contexto
openclaw config set plugins.slots.contextEngine contexto
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 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

## How Contexto Compares

If you are deciding whether this is worth installing, this is the short version.

| | Default OpenClaw | **Contexto** |
|---|---|---|
| **When the context window fills** | Older turns get compacted into a summary entry; recent messages stay intact | Full episodes get ingested and indexed |
| **Keeps earlier instructions?** | Degrades over time | Yes, original episodes remain retrievable |
| **Keeps topics separated?** | No, unrelated topics get blurred together | Yes, semantic clustering keeps branches distinct |
| **Can you explain what was retrieved?** | No | Yes, full path tracing (`travel -> Japan -> visa docs`) |
| **Setup time** | Built-in | One plugin install, one config key |

## How It Works

Contexto turns aging conversation history into a searchable context tree instead of a lossy summary blob.

1. OpenClaw buffers conversation turns as full episodes.
2. When the prompt budget crosses the compaction threshold, the oldest episodes are ingested.
3. Episodes are clustered with hierarchical similarity, so related work lands in the same branch.
4. Retrieval uses beam search to pull back the most relevant episodes for the current prompt.

That means old context is not gone. It is organized.

### Under the Hood

- **Episodes and sliding window**: the storage unit is a full turn, including tool output.
- **Hierarchical clustering (AGNES)**: related episodes are grouped without predefined categories.
- **Multi-branch beam search**: retrieval can pull from several relevant branches in one pass.
- **Hybrid rebuild strategy**: periodic full rebuilds plus cheaper incremental inserts between them.

For the deeper technical reasoning:

- [Fixing Context Collapse in Long-Running Agents](https://getcontexto.com/blogs/contexto-mindmap)
- [Your AI Agent Isn't Broken. It's Missing the Context Engine](https://getcontexto.com/blogs/context-engine)
- [Why We Chose Hierarchical Clustering](https://github.com/ekailabs/contexto/discussions/114)

## Configuration

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `apiKey` | string | Yes | Your Contexto API key |

## Custom Backends

The engine talks to storage through `ContextoBackend`. The default remote backend calls `api.getcontexto.com`, but you can implement your own.

```ts
interface ContextoBackend {
  ingest(payload: WebhookPayload | WebhookPayload[]): Promise<void>;
  search(
    query: string,
    maxResults: number,
    filter?: Record<string, unknown>,
    minScore?: number
  ): Promise<SearchResult | null>;
}
```

## Roadmap

- [ ] Horizontal scaling with sub-agent context delegation
- [ ] Scoped context with access boundaries
- [ ] Knowledge from external documents
- [ ] Context sharing across agents

## Community

- [Discord](https://discord.gg/4QTRS5ew)
- [Discussions](https://github.com/ekailabs/contexto/discussions)
- [Issues](https://github.com/ekailabs/contexto/issues)
- [Contributing guide](CONTRIBUTING.md)

## License

Apache 2.0. See [LICENSE](LICENSE).

---

<p align="center">
  If long-session reliability matters to you, star the repo and help other OpenClaw users discover it.
</p>

contexto

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README