Sessions & State Persistence

Hive is designed for production environments where agent executions must be durable, resumable, and observable. The framework manages state through a combination of filesystem-based storage, session identifiers, and structured runtime logs.

The Agent Runtime and Storage

State persistence is managed by the AgentRuntime. When initializing a runtime, you provide a storage_path. This directory serves as the root for all persistent data, including graph checkpoints, tool execution logs, and sandbox artifacts.

from pathlib import Path
from framework.runtime.agent_runtime import create_agent_runtime

storage_path = Path.home() / ".hive" / "sessions" / "research_task_01"
storage_path.mkdir(parents=True, exist_ok=True)

runtime = create_agent_runtime(
    graph=my_graph,
    storage_path=storage_path,
    # ... other configuration
)

Session Identifiers

Hive uses a hierarchical identification system to isolate data and maintain context across different levels of execution:

| Identifier | Description | | :--- | :--- | | workspace_id | The highest level of isolation, typically representing a project or a specific user environment. | | agent_id | Identifies the specific agent configuration/template being executed. | | session_id | A unique string for a specific long-running conversation or task. Used by tools to identify the correct sandbox. | | run_id | A unique identifier for a single execution pass through the graph. |

These IDs are automatically propagated to tools (via MCP) to ensure that file operations and state changes occur within the correct boundaries.

Three-Level Runtime Logging

Persistence is not just about state recovery; it is also about auditability. Hive implements a three-level logging system that serializes execution data to the storage_path:

1. Level 1: Summary (RunSummaryLog)
   • Contains high-level outcomes (success/failure), token usage, and total latency.
   • Used for dashboards and cost tracking.
2. Level 2: Node Details (NodeDetail)
   • Records the input, output, and success status of every node in the graph.
   • Tracks retry attempts and "attention flags" for Human-in-the-Loop (HITL) interventions.
3. Level 3: Tool Logs (NodeStepLog)
   • The most granular level, recording every individual tool call, LLM prompt, and raw response.
   • Critical for debugging and the "self-improving" feedback loop.

Human-in-the-Loop (HITL) and Resumption

One of Hive's core strengths is the ability to pause execution for human approval and resume exactly where it left off.

Approval Workflow

When an agent generates a proposal (e.g., a test case or a code change), the state is persisted as a "pending" object. The ApprovalCLI or the TUI can then be used to review these objects.

# Example: Reviewing persisted test cases
from framework.testing.test_storage import TestStorage
from framework.testing.approval_cli import interactive_approval

storage = TestStorage(path="./data/tests")
pending_tests = storage.load_pending(goal_id="research_goal")

# This flow updates the persisted state based on user input
results = interactive_approval(pending_tests, storage)

State Checkpoints

The AgentRuntime tracks the execution_path. If an agent reaches an EventLoopNode that requires external validation or hits a terminal node that allows for follow-up, the session remains "warm" in the storage_path. You can restart the runtime pointing to the same directory to continue the conversation with the full history and tool context intact.

Credential Persistence

Credentials (API keys, OAuth tokens) are managed via a dedicated CredentialStore. Unlike transient session state, credentials are encrypted and persisted with their own lifecycle metadata:

• Auto-refresh: OAuth2 credentials track expires_at and can trigger refresh flows automatically.
• Usage Tracking: Each CredentialObject tracks its use_count and last_used timestamp across sessions.

# Internal structure of a persisted credential
credential = CredentialObject(
    id="github_oauth",
    credential_type=CredentialType.OAUTH2,
    auto_refresh=True,
    keys={
        "access_token": CredentialKey(name="access_token", value=SecretStr("...")),
    }
)

Sandbox Isolation

When using file system tools (like view_file or edit_file), Hive enforces path security by combining the workspace_id, agent_id, and session_id. This ensures that an agent in session_A cannot accidentally read or modify files belonging to session_B, providing a persistent but secure working directory for every task.