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. 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. Tool availability differs from tool adoption: config.toml supplies the mechanism, and because AGENTS.md is always-on context, the rule written there enforces the habit. 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. These competing 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

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 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. 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. 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 with hindsight-openhands init --api-url localhost:8888 --bank-id my-project, which supplies the --api-url flag in place of an authentication token.

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. 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; the uninstall command surgically removes only those added blocks. 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.

Where the Memory Bank Runs: Cloud or Self-Hosted

Two decisions outlive the install: how many banks you run, and where they live. A unique bank identifier per repository costs a little administrative overhead and keeps one project's history out of another's context; the backend choice decides only who carries the storage risk.

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.

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.

Both backends inject the same Streamable-HTTP server entry into config.toml, so recall, retain, and reflect behave identically whichever one you pick. Infrastructure preference drives the decision: take the cloud option to avoid managing infrastructure, or self-host to keep 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