Skip to content

Commit ee81c65

Browse files
benfrank241benfrank241
authored
blog(openhands): OpenHands persistent memory via native MCP (#2316)
* blog(openhands): add OpenHands persistent memory post Walkthrough of the Hindsight OpenHands integration: native Streamable-HTTP MCP server wired into config.toml (recall/retain/reflect tools) plus a recall/retain rule written into AGENTS.md so the agent recalls at task start and retains durable facts. Covers Cloud + self-host setup, the CLI commands (init/status/uninstall), and per-project banks via --bank-id. Co-branded cover image.
1 parent ccd3eb2 commit ee81c65

2 files changed

Lines changed: 125 additions & 0 deletions

File tree

‎hindsight-docs/blog/2026-06-19-openhands-persistent-memory.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
title: "OpenHands (formerly OpenDevin) Forgets Every Task. Here's the One-Command Fix."
3+
authors: [benfrank241]
4+
slug: "2026/06/19/openhands-persistent-memory"
5+
date: 2026-06-19T12:00
6+
tags: [openhands, opendevin, mcp, memory, persistent-memory, hindsight, agents, tutorial]
7+
description: "Add persistent long-term memory to OpenHands (formerly OpenDevin) with Hindsight. One command wires the Hindsight MCP server into config.toml and drops a recall/retain rule into AGENTS.md, so the agent recalls relevant context at the start of every task and retains durable facts as it works."
8+
image: /img/blog/openhands-persistent-memory.png
9+
hide_table_of_contents: true
10+
---
11+
12+
![OpenHands persistent memory with Hindsight](/img/blog/openhands-persistent-memory.png)
13+
14+
[OpenHands](https://github.com/OpenHands/OpenHands) (formerly OpenDevin) is one of the most capable open-source coding agents — it reads your repo, runs commands, edits files, and ships changes. But every task starts from a blank slate. The architectural decision you explained last week, the convention you corrected it on yesterday, the library you told it to never use — all gone the moment the task ends.
15+
16+
This post is a walkthrough of the Hindsight integration for OpenHands. One command wires Hindsight's **MCP server** into your config and drops a recall/retain rule into `AGENTS.md`, so the agent pulls relevant context at the start of every task and saves durable facts as it works.
17+
18+
## TL;DR
19+
20+
<!-- truncate -->
21+
22+
- OpenHands agents start every task cold — no memory of past decisions, preferences, or conventions.
23+
- The Hindsight integration uses OpenHands' **native MCP support**. `pip install hindsight-openhands`, run `init`, done.
24+
- `init` adds the Hindsight **MCP server** to `config.toml` (giving the agent `recall` / `retain` / `reflect` tools) and writes a recall/retain **rule** into `AGENTS.md`.
25+
- Because `AGENTS.md` is always-on context, the rule reliably steers the agent: recall first, retain durable facts — no prompting required.
26+
- Memory lives in a Hindsight **bank** you choose per project, so each repo gets its own isolated memory.
27+
- Hindsight Cloud means no infrastructure. [Sign up free.](https://ui.hindsight.vectorize.io/signup)
28+
29+
## Why OpenHands Needs Persistent Memory
30+
31+
OpenHands is great at the _doing_: give it a task and it plans, runs tools, and iterates until the work is done. Within a task it has full working context. But that context is scoped to the task. Close it, start the next one, and the agent is back to zero.
32+
33+
For a coding agent you run against the same repo day after day, that's the limitation you hit first. It re-derives the project's structure on every task. It re-suggests the dependency you already rejected. It forgets the deploy step you walked it through last time. You end up re-explaining the same context until it feels easier to just do the work yourself.
34+
35+
Hindsight gives OpenHands a memory that persists across tasks and sessions — and because OpenHands speaks MCP natively, wiring it in takes one command.
36+
37+
## How It Works
38+
39+
OpenHands has **native Streamable-HTTP MCP support**, so the Hindsight MCP endpoint connects directly — no bridge, no proxy:
40+
41+
```toml
42+
[mcp]
43+
shttp_servers = [
44+
{url = "https://api.hindsight.vectorize.io/mcp/my-project/", api_key = "hsk_..."}
45+
]
46+
```
47+
48+
That alone gives the agent three tools: `recall`, `retain`, and `reflect`. But tools the model _can_ call aren't tools it _will_ call. The second half of the integration makes memory a habit, not an option.
49+
50+
OpenHands loads `AGENTS.md` into the agent's context on **every task**. So the integration writes a recall/retain rule there:
51+
52+
> You have persistent long-term memory through the Hindsight MCP server (`recall`, `retain`, and `reflect` tools).
53+
>
54+
> - At the start of each task, call `recall` with the user's request to load relevant decisions, preferences, and project context before you act. Use what's relevant and ignore the rest.
55+
> - When you learn a durable fact — an architectural decision, a user preference, a convention, or anything worth remembering across sessions — call `retain` to store it.
56+
> - Do not mention these memory operations unless the user asks about them.
57+
58+
The rule lives in a fenced `<!-- HINDSIGHT:BEGIN -->` … `<!-- HINDSIGHT:END -->` block at the top of the file, so it leads the instructions and can be updated or removed without touching your own content.
59+
60+
## Setup
61+
62+
Install the package and run `init` in your project:
63+
64+
```bash
65+
pip install hindsight-openhands
66+
cd your-project
67+
hindsight-openhands init --api-token YOUR_HINDSIGHT_API_KEY --bank-id my-project
68+
```
69+
70+
`init` merges the `[mcp]` entry into `./config.toml` and writes the rule into `./AGENTS.md`. The recommended backend is **Hindsight Cloud** — [sign up free](https://ui.hindsight.vectorize.io/signup) and create an API key.
71+
72+
Self-hosting works the same way; run the API locally and point `init` at it (no token needed for an open local server):
73+
74+
```bash
75+
hindsight-openhands init --api-url http://localhost:8888 --bank-id my-project
76+
```
77+
78+
If `config.toml` can't be parsed safely, `init` never touches it — it prints the exact snippet to paste instead. You can also preview everything without writing anything:
79+
80+
```bash
81+
hindsight-openhands init --print-only
82+
```
83+
84+
## Per-Project Memory
85+
86+
The `--bank-id` is the routing key for memory. A Hindsight bank is just a namespace, and the natural granularity for a coding agent is one bank per project:
87+
88+
```bash
89+
hindsight-openhands init --bank-id acme-api
90+
```
91+
92+
Each repo gets its own isolated memory — decisions and conventions for `acme-api` never bleed into `acme-frontend`. Because the bank lives server-side (on Cloud or your own instance), the same memory is there whether you run OpenHands locally, in CI, or from another machine. The bank id defaults to `openhands` if you don't set one.
93+
94+
## Commands
95+
96+
| Command | What it does |
97+
| ------------------------------- | --------------------------------------------------------- |
98+
| `hindsight-openhands init` | Add the MCP server + recall/retain rule |
99+
| `hindsight-openhands status` | Show whether the server + rule are configured |
100+
| `hindsight-openhands uninstall` | Remove the server + rule (leaves your own content intact) |
101+
102+
## Three Things It Gets Right
103+
104+
**Native MCP, no bridge.** OpenHands speaks Streamable-HTTP MCP, and Hindsight serves it directly. There's no local proxy process to babysit and nothing to keep running alongside the agent — just a URL in `config.toml`.
105+
106+
**The rule makes recall reliable.** Exposing memory tools isn't enough; the model has to actually use them. Putting the rule in always-on `AGENTS.md` context means the agent is reminded to recall and retain on every single task, so memory isn't left to chance.
107+
108+
**It edits your files surgically.** `init` merges into existing `config.toml` and `AGENTS.md` rather than overwriting them, and the rule sits in a fenced block. `uninstall` removes exactly that block and nothing else. Your config and your agent instructions stay yours.
109+
110+
## Recap
111+
112+
| | OpenHands default | With Hindsight |
113+
| --------------------- | ----------------- | -------------------------------------------------- |
114+
| Memory across tasks | None | Persistent, per bank |
115+
| Setup | n/a | One command (`init`) |
116+
| Transport | n/a | Native MCP (no bridge) |
117+
| Recall/retain | n/a | `recall` / `retain` / `reflect` tools, rule-guided |
118+
| Per-project isolation | n/a | Set `--bank-id` |
119+
| Removal | n/a | `uninstall` — surgical, non-destructive |
120+
121+
## Next Steps
122+
123+
- **Hindsight Cloud:** [ui.hindsight.vectorize.io](https://ui.hindsight.vectorize.io/signup)
124+
- **Integration docs:** [OpenHands + Hindsight](/sdks/integrations/openhands)
125+
- **Source:** [vectorize-io/hindsight/hindsight-integrations/openhands](https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/openhands)

‎hindsight-docs/static/img/blog/openhands-persistent-memory.png‎

61 KB
Loading

0 commit comments

Comments
 (0)