The state.json artifact captures the cognitive state at the end of each episode. 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": { ... }
}
Root fields
Backwards-compatible identifier. Currently "1.0".
Semantic version for the schema contract. Currently "1.0.0".
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"
}
}
Unique episode identifier.
Seed used for reproducibility.
User-provided metadata tags.
Adapter label used for execution (optional).
ISO 8601 start timestamp.
Goal
The task the agent is pursuing.
{
"goal": {
"task": "Draft release notes for v1.2.0",
"type": "task"
}
}
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"
}
]
}
Confidence in the belief (0-1).
When the belief was recorded.
Plan
Ordered steps describing the execution plan.
{
"plan": {
"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"
}
]
}
}
Ordered list of plan steps.
Origin of the plan (e.g., "direction", when present).
ISO 8601 timestamp of the last plan update (when present).
Step fields
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 |
Human-readable step description.
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 |
Explanation for the step.
Inputs provided to the step.
Outputs produced by the step.
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"
}
}
Normalized facts with timestamps and provenance.
Fact value (any JSON type).
When the fact was recorded.
memory.facts[].provenance
Source of the fact.
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
}
}
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 |
Structured action records (id, kind, tool, result_status, artifacts, provenance). Shape mirrors the events emitted during execution.
Outcome metrics (e.g., total duration).
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 runs/demo/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
