OpenHands memory: Stop losing context after every task

OpenHands loses all context after every task, forcing users to re-explain architectural decisions daily. Unlike the default "blank slate" behavior where the agent re-suggests rejected dependencies, this setup ensures the system recalls prior conventions automatically.

The integration uses Hindsight's state-of-the-art performance on the LongMemEval benchmark to validate its conversational memory capabilities. Readers will learn how a single initialization command modifies config.toml and injects rules into AGENTS.md, transforming ephemeral interactions into durable knowledge. This approach prevents the agent from forgetting deploy steps or library restrictions between sessions.

While Hindsight operates as a lean organization with only 20 employees, its architecture delivers enterprise-grade retention for OpenHands workflows. The guide details the specific MCP configuration required to enable recall, retain, and reflect tools without external proxies. By isolating memory banks per repository, developers can finally stop re-deriving project structures and let the agent build on established context.

The Role of Persistent Memory in Open-Source Coding Agents

OpenHands Persistent Memory and the Blank Slate Problem

OpenHands, once called OpenDevin, ranks among the most capable open-source coding agents available today. It reads repositories, executes commands, and edits files with impressive speed. Every single task begins from a blank slate regardless of prior work. Architectural decisions made last week vanish the moment a task ends. Conventions corrected yesterday disappear. Libraries marked forbidden reappear in suggestions. This context loss forces developers to re-explain project conventions, rejected dependencies, and deployment steps during each session, effectively resetting the agent's utility to zero between tasks. The system excels at executing commands within a single run yet fails to accumulate long-term project knowledge due to a lack of persistent memory.

Integrating Hindsight as a specialized memory layer via the Model Context Protocol (MCP) solves this issue. This architecture separates facts from opinions across distinct logical networks rather than storing everything as general conversational history. The agent learns to retain durable facts and recall them at the start of new tasks automatically. Modifying the `AGENTS.md` file enforces a workflow where the agent queries its memory bank before acting. Continuity across sessions happens without manual prompting. Hindsight has achieved state-of-the-art performance on the LongMemEval benchmark, a widely used metric for assessing memory system performance across conversations.

Operators face a new dependency on external state management. The system relies on a memory bank to store durable facts such as architectural decisions and user preferences. Maintenance shifts from repetitive instruction to active memory hygiene. Verification of stored architectural decisions becomes necessary to ensure accuracy. Gaining historical context requires managing the recall-retain cycle to preserve valid data across sessions.

Applying the Four Logical Networks in Hindsight Architecture

Hindsight eliminates context loss by organizing data into four logical networks: world, experience, opinion, and observation. Transient task interactions become durable project knowledge through three specific operations: retain, recall, and reflect. World and experience networks capture objective facts and subjective interactions respectively. The opinion network tracks belief evolution over time.

Operators configure this system by installing the package and running a single initialization command that merges the MCP server into `config.toml`. This setup writes a recall/retain rule directly into `AGENTS.md`. The agent retrieves the history before executing code. Unlike standard configurations that reset after every run, this approach forces the model to consult persistent memory as a mandatory first step. Reflection consolidates raw transcripts into deduplicated observations. Redundant transient data does not clutter the memory bank.

Strict dependency on the `AGENTS.md` file remaining intact within the repository context limits this design. Users removing this instruction file cause the agent to revert to default behavior. It operates from a blank slate again. Available memory tools get ignored entirely. Reliability of long-term context retention ties directly to the persistence of this specific configuration file rather than an inherent property of the underlying model. Builders must treat `AGENTS.md` as critical infrastructure instead of mere documentation. Continuity of the observation consolidation pipeline depends on this file staying in place.

Hindsight Versus MemGPT: Separating Facts from Opinions

Hindsight uniquely separates facts from opinions within agent memory. Competitors like MemGPT, LIGHT, and KARMA lack this capability. Tracking opinion evolution over time prevents transient hypotheses from corrupting durable project constraints. Eight compared systems fail to distinguish subjective beliefs from objective data. Hindsight maintains this separation with high consistency across evaluated scenarios.

An entity-aware graph structure manages these distinct knowledge types effectively. Only Zep, A-Mem, and Mem0 share this specific graph topology. They still lack the logical separation required for true opinion tracking. Temporary debugging hypotheses do not become permanent codebase rules because of this design choice.

Maintaining a verifiable audit trail of why specific architectural paths were abandoned becomes possible through this separation. Isolating subjective states helps the system distinguish between established constraints and temporary hypotheses. Manual prompt engineering to enforce context boundaries becomes unnecessary. The memory structure itself enforces the distinction between what is known and what is merely suspected.

Inside the Hindsight MCP Architecture for OpenHands

Streamable-HTTP MCP Protocol in OpenHands

OpenHands uses native Streamable-HTTP support to link the Hindsight endpoint directly, bypassing intermediate bridges entirely. A specific entry inside `config.toml` defines the server URL and authentication token, serving as the sole dependency for this connection. The integration wires the Hindsight MCP server into the configuration, allowing the agent to pull the context the moment a task begins.

Three distinct tools become available: recall, retain, and reflect. This architecture treats memory as a dedicated service decoupled from the core agent execution engine rather than a general conversational log. The protocol grants access to a persistent memory service built specifically for coding workflows.

Network reliability acts as a hard constraint for memory access since the system retrieves stored context to avoid re-transmitting project conventions. By fetching these details, the setup prevents the compounding token waste of re-explaining decisions. This modular design suggests a shift where specialized memory services operate independently from the primary LLM provider.

Deploying Recall and Retain Tools via AGENTS.md

Executing `pip install hindsight-openhands` followed by the `init` command enables persistent memory by wiring the server. This single workflow modifies `config.toml` with a Streamable-HTTP entry, granting the agent access to recall, retain, and reflect tools without external proxies. The initialization script writes a recall/retain rule into `AGENTS.md`, instructing the model to query its memory bank before executing any code generation or file edits. The agent possesses the tools but lacks the behavioral trigger to apply them consistently across sessions without this explicit rule in `AGENTS.md`.

Tool availability differs from tool adoption; the configuration provides the mechanism while the markdown rule enforces the habit. Because `AGENTS.md` is always-on context, the rule reliably steers the agent to recall first and retain durable facts without requiring additional prompting. This overhead ensures the agent retrieves architectural decisions stored in the Hindsight bank rather than hallucinating conventions. A unique bank identifier isolates memory per project, preventing cross-contamination between repositories.

Developers gain a compounding return on investment as the agent retains valid patterns over time, transforming the agent from a stateless executor into a cumulative learner. Refer to the documentation provided by AI Agents News for further technical details on setting up this workflow.

Validating the Three-Tool Memory Workflow

Verification begins by confirming the `init` command injects the Hindsight MCP server into `config.toml` with `recall`, `retain`, and reflect capabilities.

1. Inspect `config.toml` for the Streamable-HTTP entry pointing to the project-specific endpoint.
2. Check `AGENTS.md` for the fenced rule block instructing the agent to prioritize memory retrieval.
3. Execute a test task to observe if the agent queries the memory bank for the decisions before generating code.

The rule lives in a fenced block at the top of the file, so it leads the instructions and can be updated or removed without touching your own content. This structural guardrail prevents the system from reverting to ephemeral processing despite correct server wiring. Operators must place the rule at the start of the instruction set to guarantee consistent behavioral adoption across sessions.

Deploying Hindsight Integration for Per-Project Memory

Defining the Hindsight Init Command and Bank-ID Routing

The `hindsight-openhands init` command parses local configuration files to inject Streamable-HTTP endpoints without overwriting existing user data.

1. Execute `pip install hindsight-openhands` followed by `init` within the target directory.
2. Provide the `--bank-id` flag to establish a unique memory namespace where one bank corresponds strictly to one project.
3. If the parser detects unsafe modifications to `config.toml`, the tool halts and prints the exact snippet required for manual insertion.

This routing key ensures that architectural decisions for an `acme-api` repository never bleed into `acme-frontend` contexts. Server-side residence keeps this isolation intact across local runs, CI pipelines, or different machines. The integration decouples specialized memory services from the core agent execution engine, allowing operators to scale infrastructure independently modular AI architectures. Storage presents a constraint; deploying via Docker requires mapping persistent volumes like `v hindsight-data:/home/hindsight/.pg0` to prevent data loss during container restarts persistent storage. Cloud backends eliminate local maintenance while self-hosting shifts the burden of storage infrastructure costs to the user.

Builders must weigh the convenience of managed cloud storage against the control of on-premises volume mapping.

Executing Cloud and Local Backend Setup Workflows

Connect the agent to Hindsight Cloud by running `hindsight-openhands init --api-token YOUR_HINDSIGHT_API_KEY --bank-id my-project`. This command injects the required Streamable-HTTP endpoint into `config.toml`, enabling the agent to access persistent storage without manual file editing. Developers prioritizing data sovereignty can instead deploy a local Docker environment to keep all memory artifacts on-premises. Point the CLI to this self-hosted instance using the `--api-url` flag rather than an authentication token.

1. Install the package via `pip install hindsight-openhands`.
2. Execute `hindsight-openhands init --api-url localhost --bank-id my-project` for local backends.
3. Verify the `--bank-id` flag creates an isolated namespace per repository to prevent context leakage.

Validating config.toml Entries and Tool Availability

Verify the Streamable-HTTP entry exists in `config.toml` to confirm the agent can access recall, retain, and reflect tools. Without this specific URL structure, the integration fails silently, leaving the model without persistent context.

1. Inspect `config.toml` for the Hindsight MCP server definition pointing to your project bank.
2. Run `hindsight-openhands status` to validate that both the server connection and AGENTS.md rule are active.
3. Execute `hindsight-openhands uninstall` if you need to remove the configuration while preserving your existing codebase.

If the initialization command cannot safely parse your configuration file, it halts modification and prints the required snippet for manual insertion rather than corrupting data. This protective behavior prevents syntax errors from breaking the agent's ability to load tools during runtime. Unlike manual edits, the uninstall command surgically removes only the added blocks, ensuring user content remains intact. For builders managing multiple repositories, failing to validate these entries means distinct projects may inadvertently share memory banks or lose isolation entirely. AI Agents News recommends running the status check after every dependency update to ensure the memory namespace remains correctly bound to the intended project identifier.

Strategic Decisions for Cloud Deployment and Memory Isolation

Defining Per-Bank Memory Isolation and Bank-ID Routing

The `--bank-id` flag acts as the routing key that segregates memory namespaces by project scope. Initializing a system with `acme-api` keeps that context distinct from `acme-frontend`, preventing architectural conventions from bleeding across boundaries. Since the bank resides on a remote server or local Docker environment, this isolation persists regardless of whether the agent runs in CI or on a laptop.

Shared memory accelerates learning, yet unrestricted sharing corrupts project-specific logic with irrelevant history. The surgical editing capability of the `init` command mitigates risk by printing configuration snippets if `config.toml` parsing fails, rather than forcing destructive overwrites. Systems merging all facts into a single stream struggle here. This approach allows organizations to consolidate related facts within a project while maintaining strict boundaries between them. Managing unique identifiers for every repository creates a small administrative overhead. That cost prevents catastrophic context collisions in multi-project agents.

Scenarios for Coding Agent Context Loss and Persistent Recall

Default OpenHands workflows discard architectural context the moment a task completes, forcing agents to re-derive project structure on every invocation. This context loss occurs because standard configurations lack a mechanism to persist decisions across session boundaries, treating each prompt as an isolated event. Without intervention, the agent repeatedly suggests rejected dependencies or ignores established conventions, creating a loop of redundant correction. Placing recall rules directly into AGENTS.md enforces a discipline where the agent must query its history before acting.

The Hindsight integration addresses this by binding memory tools to the agent's primary instruction set via Streamable-HTTP. Unlike general conversational systems, this setup creates a dedicated memory namespace for each repository, ensuring that logic for an API project never contaminates a frontend codebase. Developers can verify this isolation by checking that the `--bank-id` flag correctly segregates data on the Hindsight Cloud backend or a local instance.

Agent autonomy conflicts with strict adherence to historical data when recall rules become too rigid, potentially causing the agent to refuse valid architectural pivots. Balancing reliable recall with the flexibility to overwrite outdated facts when explicit user commands demand change solves this friction. This approach transforms the agent from a transient executor into a cumulative learner that evolves with the codebase.

Hindsight Cloud Versus Self-Hosted Backend Deployment

Operators often select Hindsight Cloud as the recommended backend, requiring an API key, though they may self-host the API locally to retain data sovereignty. Self-hosting works by running the API locally, providing an alternative to the managed cloud service.

Cloud deployment eliminates infrastructure management by offloading storage and compute to managed services. Running the system via a local Docker environment keeps memory artifacts on-premises but demands manual volume mapping and persistence configuration. The choice hinges on whether an organization prioritizes zero-maintenance access or strict control over the memory namespace.

Deploying locally introduces a hidden operational cost: the operator bears full responsibility for backing up the persistent storage volume where recall and retain data resides. Cloud backends abstract this risk. Local instances require explicit `docker volume` definitions to prevent data loss during container restarts. Removal is described as surgical and non-destructive, ensuring that configuration adjustments do not compromise existing data integrity.

Initialization commands differ by target. Cloud users execute `hindsight-openhands init --api-token YOUR_KEY --bank-id my-project`. Local deployments instead point to a specific endpoint: `hindsight-openhands init --api-url localhost --bank-id my-project`. Both configurations inject the Streamable-HTTP server into `config.toml`, providing the same `recall`, retain, and reflect tools regardless of the backend chosen. Infrastructure preference drives the decision: use the cloud option to avoid managing infrastructure, or choose self-hosting to maintain full control over the underlying database engine and data location.

References

• OpenHands - 2026 Company Profile, Team, Funding & Competitors
• Deploy OpenHands on GPU Cloud: Self-Host the Open-Source AI
• OpenCode 2026: Setup Guide for the Top Open-Source AI