Skip to main content
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

​
version
string
required
Backwards-compatible identifier. Currently "1.0".
​
state_schema_version
string
required
Semantic version for the schema contract. Currently "1.0.0".
​
links
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"
  }
}
​
episode.id
string
required
Unique episode identifier.
​
episode.seed
number
Seed used for reproducibility.
​
episode.tags
object
User-provided metadata tags.
​
episode.using
string
Adapter label used for execution (optional).
​
episode.started_at
string
required
ISO 8601 start timestamp.
​
episode.intuition_mode
string
Intuition posture for the episode (advisory | interventive | hybrid). Runs created with older Noēsis versions may omit this field (default advisory).
links points to run-local artifacts in the episode directory. 
{
  "links": {
    "events": "events.jsonl",
    "learn": "learn.jsonl",
    "summary": "summary.json",
    "manifest": "manifest.json"
  }
}
​
links.events
string
Event timeline artifact path.
​
links.learn
string
Learning timeline artifact path.
​
links.summary
string
Final summary artifact path (terminal runs only).
​
links.manifest
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"
  }
}
​
goal.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"
    }
  ]
}
​
beliefs[].statement
string
required
The belief statement.
​
beliefs[].confidence
number
required
Confidence in the belief (0-1).
​
beliefs[].provenance
string
required
Source of the belief.
​
beliefs[].timestamp
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"
      }
    ]
  }
}
​
plan.steps
array
required
Ordered list of plan steps.
​
plan.source
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).
​
plan.updated_at
string
ISO 8601 timestamp of the last plan update. For event-projected plans, this is the timestamp of the latest plan event.

​
Step fields

​
plan.steps[].id
string
required
Unique step identifier.
​
plan.steps[].kind
string
required
Step kind (controlled vocabulary):
KindPurpose
detectGather information
analyzeProcess or categorize
planSub-planning
actExecute action
verifyCheck results
reviewHuman review point
​
plan.steps[].description
string
required
Human-readable step description.
​
plan.steps[].status
string
required
Step status (controlled vocabulary):
StatusMeaning
pendingNot yet started
runningCurrently executing
doneCompleted successfully
skippedIntentionally skipped
failedFailed with error
vetoedBlocked by policy
​
plan.steps[].rationale
string
Explanation for the step.
​
plan.steps[].inputs
object
Inputs provided to the step.
​
plan.steps[].outputs
object
Outputs produced by the step.

​
Plan reconstruction contract

The runtime can reconstruct state.plan from events.jsonl:
  1. Locate the latest plan event.
  2. Build steps from payload.step_records when present.
  3. Fall back to parsing legacy payload.steps labels (<kind>:<description>) when step_records is absent.
  4. Apply subsequent act events that include both payload.step_id and payload.step_status.
  5. 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"
  }
}
​
memory.facts
array
Normalized facts with timestamps and provenance.
​
memory.facts[].key
string
required
Fact identifier.
​
memory.facts[].value
any
required
Fact value (any JSON type).
​
memory.facts[].timestamp
string
When the fact was recorded.
​
memory.facts[].provenance
string
Source of the fact.
​
memory.scratchpad
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
  }
}
​
outcomes.status
string
required
Final outcome status (controlled vocabulary):
StatusMeaning
okCompleted successfully
errorFailed with error
vetoedBlocked by policy
abortedManually stopped
partialPartially completed
pendingStill running
​
outcomes.actions
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.
​
outcomes.metrics
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.

​
Next steps

Summary schema

Summary artifact reference.

Events schema

Event timeline reference.