Integration

Long-term memory for OpenHands

OpenHands is the autonomous coding agent (formerly OpenDevin), and OpenHands 1.x reads MCP settings from `settings.json` at runtime — NOT from `config.toml`. The toml shape still works because the UI merges it into `settings.json` on first save, but a fresh container with a mounted `config.toml` and no UI click silently ignores the file. The recipe ships two install paths: UI (mount `config.toml`, click once to trigger the merge) and headless (POST the diff to `/api/v1/settings`).

Get an API key (free) All integrations →

Install

Three steps: sign up for an Engram API key, paste a BYOK LLM-provider key on /models, then drop the snippet below into OpenHands.

Three steps to memory in your agent

Sign up. Free, no card. You'll land on a Getting Started page that walks the next two steps.
Add your LLM key. Engram is BYOK. Paste an OpenAI / Anthropic / Groq / Together / Fireworks key and we'll route every extraction and query call through your provider. You pay your provider directly. We never see your inference.
Paste the snippet below into your agent and restart it. Use Authorization: Bearer <api-key>with the API key from your portal.

OpenHands 1.x: settings.json is the source of truth

OpenHands reads MCP from settings.json at runtime, NOT from config.toml. The UI merges toml into settings on first save, so headless / CI installs need a direct POST to /api/v1/settings.

Path A (interactive): mount config.toml, launch the container, then click once in Settings → MCP to trigger the merge into settings.json.

~/.openhands/config.toml

[mcp]

[[mcp.sse_servers]]
url = "https://mcp.lumetra.io/mcp/sse"
api_key = "<api-key>"

Path B (headless / CI): skip config.toml entirely and POST the diff directly. The only path that works without a human click.

Terminal

curl -X POST http://localhost:3000/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{
    "agent_settings_diff": {
      "mcp_config": {
        "mcpServers": {
          "engram": {
            "url": "https://mcp.lumetra.io/mcp/sse",
            "auth": "<api-key>"
          }
        }
      }
    }
  }'

Verified against docker.openhands.dev/openhands/openhands:1.7. Drop a microagent at .agents/skills/engram-memory/SKILL.md in any project so OpenHands reaches for memory tools when the user says "remember this".

What you can do once memory's wired in

Path A (interactive): mount `~/.openhands/config.toml`, launch the Docker image, open **Settings → MCP** once to trigger the toml→settings.json merge, then ask the agent `List the available Engram buckets`
Path B (headless / CI): skip `config.toml` entirely and `POST /api/v1/settings` with the `agent_settings_diff` payload — the only path that works without a human click
Drop the keyword-triggered microagent / skill (`.agents/skills/engram-memory/SKILL.md` or legacy `microagents/engram-memory.md`) into a project so the agent reaches for memory tools when the user says 'remember this'
Watch `tool_name: engram_*` calls fly past in the event stream while OpenHands plans a multi-step refactor

FAQ

Why doesn't my `config.toml` take effect on a fresh container?

OpenHands 1.x reads MCP settings from `settings.json` at runtime, not `config.toml`. The UI merges your toml into `settings.json` on first save — so headless installs (no human click) silently ignore the file. Use Path B (POST `/api/v1/settings` with `agent_settings_diff`) for any CI / scripted setup. Verified end-to-end against `docker.openhands.dev/openhands/openhands:1.7`.

Why does the settings POST use `auth: "eng_live_..."` instead of `{Authorization: Bearer ...}`?

`mcp_config.mcpServers.engram.auth` is a fastmcp `RemoteMCPServer.auth` field — it takes the bearer token as a bare string. The legacy `sse_servers = [{ url, api_key }]` toml shape uses `api_key`; the newer settings.json shape uses `auth`. Same string value, different field names.

Does the microagent go in `.agents/skills/` or `microagents/`?

Both work. `.agents/skills/engram-memory/SKILL.md` is the current recommendation; `microagents/engram-memory.md` is the legacy path and still supported. Drop one or the other into your project root and OpenHands will pick it up on the next conversation start.

Related integrations

Ship durable memory in OpenHands today

Free tier: 10K memories and 50K retrievals per month. No credit card. Same Engram backend powers all 41 integrations, so memories you write from one client are immediately queryable from the rest.

Start free See pricing