claude-code/docs/state-schemas.md

State File Schemas

This document defines the JSON schemas for all state files in ~/.claude/state/.

Personal Assistant State

session-context.json

Path: ~/.claude/state/personal-assistant/session-context.json Writer: user/CLI Purpose: Session-level context override (ephemeral)

{
  "version": "1.0",
  "current_context_level": "minimal" | "moderate" | "comprehensive" | "none" | null,
  "set_at": "ISO8601 timestamp" | null,
  "set_by": "user" | null
}

Field	Type	Description
version	string	Schema version
current_context_level	string|null	Active context level, null if unset
set_at	string|null	When the override was set
set_by	string|null	Who set it (always "user")

general-instructions.json

Path: ~/.claude/state/personal-assistant/general-instructions.json Writer: personal-assistant Purpose: User memory/instructions optimized for agent consumption

{
  "version": "1.0",
  "description": "User instructions optimized for agent consumption",
  "items": [
    {
      "id": "uuid",
      "text": "Instruction text",
      "scope": "global",
      "tags": ["tag1", "tag2"],
      "created": "ISO8601 timestamp",
      "status": "active" | "deprecated"
    }
  ]
}

Field	Type	Description
version	string	Schema version
description	string	File description
items	array	List of instruction items
items[].id	string	UUID for the item
items[].text	string	The instruction text
items[].scope	string	Scope of instruction (e.g., "global")
items[].tags	array	Optional categorization tags
items[].created	string	ISO8601 creation timestamp
items[].status	string	"active" or "deprecated" (soft delete)

Notes:

• Items are append-only; use status: "deprecated" for soft delete
• PA generates UUIDs for new items
• Never remove items from the array

personal-assistant-preferences.json

Path: ~/.claude/state/personal-assistant-preferences.json Writer: master-orchestrator Purpose: Persistent PA configuration

{
  "version": "1.0",
  "description": "Persistent PA configuration",
  "context_gathering": {
    "default_level": "moderate"
  }
}

Field	Type	Description
version	string	Schema version
description	string	File description
context_gathering.default_level	string	Default context level

Valid context levels: none, minimal, moderate, comprehensive

Knowledge Base State

kb.json (Shared)

Path: ~/.claude/state/kb.json Writer: personal-assistant Purpose: Shared knowledge base for infrastructure facts (all agents can read)

{"infra":{},"svc":{},"net":{},"hw":{}}

Category	Purpose	Example facts
infra	Cluster/platform	cluster type, node count, architecture
svc	Services/tools	gitops, monitoring, alerting
net	Network	domain, ingress controller, DNS
hw	Hardware	device models, RAM, storage

Notes:

• Values should be primitives (string, number, boolean) or flat arrays
• Avoid nested objects beyond category level
• All state JSON files use minified format (single-line)

kb.json (PA-Private)

Path: ~/.claude/state/personal-assistant/kb.json Writer: personal-assistant Purpose: PA-private knowledge base for personal/non-tech facts

Same format as shared KB. Categories TBD based on use cases.

System State

system-instructions.json

Path: ~/.claude/state/system-instructions.json Writer: master-orchestrator Purpose: Central process definitions

See system-instructions.json for current schema.

future-considerations.json

Path: ~/.claude/state/future-considerations.json Writer: master-orchestrator Purpose: Deferred features and decisions

See future-considerations.json for current schema.

model-policy.json

Path: ~/.claude/state/model-policy.json Writer: master-orchestrator Purpose: Model selection rules

See model-policy.json for current schema.

autonomy-levels.json

Path: ~/.claude/state/autonomy-levels.json Writer: master-orchestrator Purpose: Autonomy level definitions

See autonomy-levels.json for current schema.

Sysadmin State

session-autonomy.json

Path: ~/.claude/state/sysadmin/session-autonomy.json Writer: user/CLI Purpose: Per-session autonomy overrides

See session-autonomy.json for current schema.