Metadata-Version: 2.4
Name: hindsight-openhands
Version: 0.1.0
Summary: OpenHands integration for Hindsight - persistent long-term memory via MCP
Project-URL: Homepage, https://github.com/vectorize-io/hindsight
Project-URL: Documentation, https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/openhands
Project-URL: Repository, https://github.com/vectorize-io/hindsight
Author-email: Vectorize <support@vectorize.io>
License: MIT
Keywords: agents,ai,hindsight,mcp,memory,opendevin,openhands
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: tomlkit>=0.12
Description-Content-Type: text/markdown

# hindsight-openhands

Long-term memory for [OpenHands](https://github.com/OpenHands/OpenHands) (formerly OpenDevin), powered by [Hindsight](https://github.com/vectorize-io/hindsight).

`hindsight-openhands init` wires the Hindsight **MCP server** into OpenHands'
`config.toml` and adds a recall/retain rule to your project's `AGENTS.md`. The
agent then has `recall` / `retain` / `reflect` tools and — guided by the rule —
recalls relevant memory at the start of a task and retains durable facts as it
works.

## How it works

OpenHands has **native Streamable-HTTP MCP support**, so the Hindsight MCP
endpoint connects directly (no bridge):

```toml
[mcp]
shttp_servers = [
    {url = "https://api.hindsight.vectorize.io/mcp/my-project/", api_key = "hsk_..."}
]
```

OpenHands also loads `AGENTS.md` (and repo microagents) into the agent's context
on every task — that's where the recall/retain rule lives.

## Install

```bash
pip install hindsight-openhands
cd your-project
hindsight-openhands init --api-token YOUR_HINDSIGHT_API_KEY --bank-id my-project
```

`init` merges the `[mcp]` entry into `./config.toml` and writes the rule into
`./AGENTS.md`. Use [Hindsight Cloud](https://hindsight.vectorize.io), or a
self-hosted server with `--api-url http://localhost:8888` (no token needed for an
open local server).

> If `config.toml` can't be parsed safely, `init` prints the exact `[mcp]`
> snippet to paste instead of touching the file. `hindsight-openhands init
> --print-only` shows the snippet + rule anytime.

## Commands

| Command | Description |
| --- | --- |
| `hindsight-openhands init` | Add the MCP server + recall/retain rule |
| `hindsight-openhands status` | Show whether the server + rule are configured |
| `hindsight-openhands uninstall` | Remove the server + rule |

## Configuration

| Setting | Env var | Default |
| --- | --- | --- |
| API URL | `HINDSIGHT_API_URL` | `https://api.hindsight.vectorize.io` |
| API token | `HINDSIGHT_API_TOKEN` | _(none; required for Cloud)_ |
| Bank id | `HINDSIGHT_OPENHANDS_BANK_ID` | `openhands` |

## Development

```bash
uv sync
uv run pytest tests -v -m 'not requires_real_llm'   # deterministic suite
uv run pytest tests -v -m requires_real_llm          # gated MCP-endpoint check
```

## License

MIT
