State Persistence
Relevant source files
The following files were used as context for generating this wiki page:
State Persistence in Nexus Orchestrator represents the "Context Layer" of the system, acting as a persistent memory and tracking mechanism for the autonomous infrastructure daemon. Its primary role is to bridge the "infrastructure gap" by maintaining a consistent view of environments, connectivity, and agent interactions across restarts and asynchronous workflows.
The persistence system is local-first, ensuring that all data regarding SSH connectivity, environment configurations, and agent identities is stored securely within the local infrastructure. This layer integrates closely with LangGraph-powered workflows to manage long-running orchestration tasks and with Open Policy Agent (OPA) for maintaining governance states.
Sources: README.md:5-15
Core Pillars of Persistence
State persistence is organized into four primary functional areas that define how the orchestrator retains information about its operating environment and the agents it serves.
| Pillar | Description | Role in Persistence |
|---|---|---|
| Connectivity | MCP-based protocol state | Manages active SSH tunnels and protocol handshakes. |
| Orchestration | LangGraph workflow state | Tracks the progress and state transitions of background tasks. |
| Context | AGENTS.md and context files | Maintains a record of known agents and their operational context. |
| Governance | OPA + Zero Trust state | Persists trust levels and security policies for non-human identities. |
Sources: README.md:10-15
Agent Tracking and Registry
A key component of the persistence layer is the AGENTS.md file, which serves as a human-readable and machine-parseable registry of all AI agents interacting with the system.
This diagram illustrates the flow of agent identity information into the persistent storage layer.
The registry tracks specific metadata for every agent to ensure secure and consistent orchestration:
- Agent ID: Unique identifier for the non-human identity.
- Description: Metadata regarding the agent's purpose or origin.
- Trust Level: Security tier used by the Governance Layer (OPA) to restrict or allow infrastructure access.
Sources: context/AGENTS.md:1-8, README.md:15
Data Flow and Infrastructure Synchronization
The Nexus Orchestrator functions as a "nervous system" where state persistence ensures that the infrastructure remains synchronized with agent requests. When an agent initiates a request via the connectivity layer, the orchestrator updates its internal state to reflect environment changes.
The sequence diagram shows how persistent state updates are interleaved with infrastructure execution to prevent state drift.
Sources: README.md:3-12, context/AGENTS.md:3-8
Summary
State Persistence in Nexus Orchestrator provides the necessary "memory" for autonomous infrastructure management. By combining local-first context files like AGENTS.md with structured workflow management via LangGraph, the system ensures that AI agents can interact with complex environments without losing track of their operational status or security context. This persistent layer is fundamental to achieving Zero Trust security for non-human identities within the orchestrator.
Sources: README.md:4-15, context/AGENTS.md:1-5