State schema

The state.json artifact captures cognitive state snapshots during execution and at terminal completion. It provides a complete view of what was planned and what happened.

Schema overview

{
  "version": "1.0",
  "state_schema_version": "1.0.0",
  "episode": { ... },
  "goal": { ... },
  "beliefs": [ ... ],
  "plan": { ... },
  "memory": { ... },
  "outcomes": { ... },
  "links": { ... }
}

Root fields

string

required

Backwards-compatible identifier. Currently "1.0".

string

required

Semantic version for the schema contract. Currently "1.0.0".

object

Relative artifact paths for this run (for example events.jsonl, learn.jsonl, summary.json, manifest.json). Keys vary by lifecycle state.

Episode

Episode metadata and timestamps.

{
  "episode": {
    "id": "ep_2024_abc123_s0",
    "seed": 0,
    "tags": {
      "environment": "staging",
      "team": "platform"
    },
    "using": "baseline",
    "started_at": "2024-01-15T10:30:00Z"
  }
}

string

required

Unique episode identifier.

number

Seed used for reproducibility.

object

User-provided metadata tags.

string

Adapter label used for execution (optional).

string

required

ISO 8601 start timestamp.

string

Intuition posture for the episode (advisory | interventive | hybrid). Runs created with older Noēsis versions may omit this field (default advisory).

Artifact links

links points to run-local artifacts in the episode directory.

{
  "links": {
    "events": "events.jsonl",
    "learn": "learn.jsonl",
    "summary": "summary.json",
    "manifest": "manifest.json"
  }
}

string

Event timeline artifact path.

string

Learning timeline artifact path.

string

Final summary artifact path (terminal runs only).

string

Final manifest artifact path (terminal runs only).

Lifecycle constraint:

non-terminal runs (for example approval pauses) persist links.events and links.learn
terminal runs additionally persist links.summary and links.manifest

Goal

The task the agent is pursuing.

{
  "goal": {
    "task": "Draft release notes for v1.2.0",
    "type": "task"
  }
}

string

required

The original task or goal.

Beliefs

Normalized statements the system inferred during execution.

{
  "beliefs": [
    {
      "statement": "Version 1.2.0 includes 3 new features",
      "confidence": 0.9,
      "provenance": "changelog_analysis",
      "timestamp": "2024-01-15T10:30:02Z"
    },
    {
      "statement": "Breaking changes require migration guide",
      "confidence": 0.85,
      "provenance": "policy_hint"
    }
  ]
}

string

required

The belief statement.

number

required

Confidence in the belief (0-1).

string

required

Source of the belief.

string

When the belief was recorded.

Plan

Ordered steps describing the execution plan.

{
  "plan": {
    "source": "planner.minimal",
    "updated_at": "2024-01-15T10:30:01Z",
    "rationale": "minimal planner",
    "steps": [
      {
        "id": "step_1",
        "kind": "detect",
        "description": "Read changelog entries",
        "status": "done",
        "rationale": "Need to gather raw changelog data",
        "inputs": {
          "file": "CHANGELOG.md"
        },
        "outputs": {
          "entries": 15
        }
      },
      {
        "id": "step_2",
        "kind": "analyze",
        "description": "Categorize changes",
        "status": "done"
      },
      {
        "id": "step_3",
        "kind": "act",
        "description": "Generate release notes",
        "status": "done"
      },
      {
        "id": "step_4",
        "kind": "verify",
        "description": "Validate format",
        "status": "done"
      }
    ]
  }
}

array

required

Ordered list of plan steps.

string

Origin of the plan (for example, "planner.minimal" or "planner.resume"). When projected from events, this comes from the latest plan payload source value (with agent_id as fallback).

string

ISO 8601 timestamp of the last plan update. For event-projected plans, this is the timestamp of the latest plan event.

Step fields

string

required

Unique step identifier.

string

required

Step kind (controlled vocabulary):

Kind	Purpose
`detect`	Gather information
`analyze`	Process or categorize
`plan`	Sub-planning
`act`	Execute action
`verify`	Check results
`review`	Human review point

string

required

Human-readable step description.

string

required

Step status (controlled vocabulary):

Status	Meaning
`pending`	Not yet started
`running`	Currently executing
`done`	Completed successfully
`skipped`	Intentionally skipped
`failed`	Failed with error
`vetoed`	Blocked by policy

string

Explanation for the step.

object

Inputs provided to the step.

object

Outputs produced by the step.

Plan reconstruction contract

The runtime can reconstruct state.plan from events.jsonl:

Locate the latest plan event.
Build steps from payload.step_records when present.
Fall back to parsing legacy payload.steps labels (<kind>:<description>) when step_records is absent.
Apply subsequent act events that include both payload.step_id and payload.step_status.
Keep existing step status when no step_status evidence exists.

This contract is implemented by noesis.runtime.plan_projection.project_plan_state(...).

Memory

Persistent facts and scratchpad captured during the run.

{
  "memory": {
    "facts": [
      {
        "key": "changelog_format",
        "value": "keep-a-changelog",
        "timestamp": "2024-01-15T10:30:02Z",
        "provenance": "detection"
      },
      {
        "key": "breaking_changes_count",
        "value": 3,
        "timestamp": "2024-01-15T10:30:03Z",
        "provenance": "analysis"
      }
    ],
    "scratchpad": "Found 3 breaking changes to highlight in the migration section"
  }
}

array

Normalized facts with timestamps and provenance.

string

required

Fact identifier.

any

required

Fact value (any JSON type).

string

When the fact was recorded.

string

Source of the fact.

string

Free-form notes captured during execution.

Outcomes

Final status, action log, metrics, and artifacts.

{
  "outcomes": {
    "status": "ok",
    "actions": [
      {
        "id": "action_1",
        "tool": "changelog_reader",
        "input": "CHANGELOG.md",
        "output": {"entries": 15},
        "timestamp": "2024-01-15T10:30:01Z",
        "duration_ms": 150
      },
      {
        "id": "action_2",
        "tool": "release_notes_generator",
        "input": {"entries": 15, "format": "markdown"},
        "output": {"file": "release_notes.md"},
        "timestamp": "2024-01-15T10:30:03Z",
        "duration_ms": 2500
      }
    ],
    "metrics": {
      "task_score": 0.95,
      "steps_completed": 4,
      "steps_total": 4
    },
    "artifacts": [
      "release_notes.md"
    ],
    "error": null
  }
}

string

required

Final outcome status (controlled vocabulary):

Status	Meaning
`ok`	Completed successfully
`error`	Failed with error
`vetoed`	Blocked by policy
`aborted`	Manually stopped
`partial`	Partially completed
`pending`	Still running

array

Structured action records (id, kind, tool, input_excerpt, result_status, step_id, provenance, result_artifacts, plus x- extensions). The shape mirrors act event payloads, and runtime emission aligns each action timestamp to the corresponding act event timestamp.

object

Outcome metrics (e.g., total duration).

Traceability guarantees

episode.started_at is aligned to the start event timestamp and remains stable across continuation.
Whenever state.json is persisted, runtime emits phase="runtime", event_type="run.state_projection" with projection evidence for outcomes and links.
For terminal runs, projection outcomes and links mirror the final persisted state.json values.

Complete example

{
  "version": "1.0",
  "state_schema_version": "1.0.0",
  "episode": {
    "id": "ep_2024_abc123_s0",
    "seed": 0,
    "tags": {"team": "platform"},
    "using": "baseline",
    "started_at": "2024-01-15T10:30:00Z"
  },
  "goal": {
    "task": "Draft release notes for v1.2.0",
    "type": "task"
  },
  "beliefs": [
    {
      "statement": "Version 1.2.0 includes 3 new features",
      "confidence": 0.9,
      "provenance": "changelog_analysis"
    }
  ],
  "plan": {
    "source": "direction",
    "updated_at": "2024-01-15T10:30:01Z",
    "steps": [
      {"id": "step_1", "kind": "detect", "description": "Read changelog", "status": "done"},
      {"id": "step_2", "kind": "act", "description": "Generate notes", "status": "done"}
    ]
  },
  "memory": {
    "facts": [
      {"key": "format", "value": "keep-a-changelog", "provenance": "detection"}
    ],
    "scratchpad": "3 breaking changes found"
  },
  "outcomes": {
    "status": "ok",
    "actions": [
      {"id": "action_1", "tool": "reader", "timestamp": "2024-01-15T10:30:01Z"}
    ],
    "metrics": {"task_score": 0.95},
    "artifacts": ["release_notes.md"]
  }
}

Reading state

Python

import noesis as ns

state = ns.state.read("ep_abc123")

print(f"Task: {state['goal']['task']}")
print(f"Status: {state['outcomes']['status']}")
print(f"Steps: {len(state['plan']['steps'])}")

File access

cat .noesis/episodes/ep_abc123/state.json | jq '.outcomes.status'

Policy usage

Policies receive the state snapshot in their advise method:

class MyPolicy(ns.DirectedIntuition):
    def advise(self, state: dict):
        # Access goal
        task = state["goal"]["task"]
        
        # Access plan
        steps = state["plan"]["steps"]
        
        # Access memory
        facts = state["memory"]["facts"]
        
        # Access outcomes
        actions = state["outcomes"]["actions"]
        
        return None

Policies should treat state as read-only. To modify execution, return hints, interventions, or vetoes through the policy API.

API reference

Schema reference

Configuration

Schema overview

Root fields

Episode

Artifact links

Goal

Beliefs

Plan

Step fields

Plan reconstruction contract

Memory

Outcomes

Traceability guarantees

Complete example

Reading state

Python

File access

Policy usage

Next steps

Summary schema

Events schema

​Schema overview

​Root fields

​Episode

​Artifact links

​Goal

​Beliefs

​Plan

​Step fields

​Plan reconstruction contract

​Memory

​Outcomes

​Traceability guarantees

​Complete example

​Reading state

​Python

​File access

​Policy usage

​Next steps

Summary schema

Events schema

Schema overview

Root fields

Episode

Artifact links

Goal

Beliefs

Plan

Step fields

Plan reconstruction contract

Memory

Outcomes

Traceability guarantees

Complete example

Reading state

Python

File access

Policy usage

Next steps