State

Flags

Examples

# Pipe-separated positional values (six dimensions for default tensor schema)
mx state encode "0.4|0.6|0.5|0.3|0.7|0.2"

# Named dimensions with prefix abbreviation
mx state encode -d "entropy=0.4 agency=0.6 temp=0.5 verb=0.3 skep=0.7 humor=0.2"

# Default values from schema
mx state encode

# Human-readable output with nearest mood
mx state encode "0.4|0.6|0.5|0.3|0.7|0.2" -F human

# Bootstrap format (self-documenting, with rune legend)
mx state encode "0.4|0.6|0.5|0.3|0.7|0.2" -F bootstrap

# With rune decoration
mx state encode "0.4|0.6|0.5|0.3|0.7|0.2" --runes

# Read from file
mx state encode -f state-values.txt

# Interactive guided mode
mx state encode --guided

# Use a custom schema
mx state encode -s crewu "0.3|0.2|0.7|0.8|0.4"

Output formats

tensor

The default. Prints the encoded tensor string: @state:tensor|0.40|0.60|.... With --runes, each value is prefixed by its dimension’s rune character.

json

Structured JSON with schema_id and values fields.

human

Each dimension printed as Name: value (anchor description), followed by the nearest mood if one falls within tolerance.

bootstrap

Self-documenting multiline output designed for session bootstrap. Line 1 is the rune-encoded tensor, line 2 is a rune legend mapping runes to dimension IDs, then a blank line, then interpolated anchor descriptions with values.

Named dimensions

The -d / --dimensions flag accepts space-separated key=value pairs. Keys are matched against dimension IDs case-insensitively, with prefix abbreviation: temp=0.5 matches temperature, ent=0.4 matches entropy. Every dimension in the schema must be covered – missing dimensions produce an error listing the expected set.

Value clamping

All values are clamped to the 0.0–1.0 range. Out-of-bounds values are silently clamped, never rejected.

Flags

Examples

mx state decode "@state:tensor|0.40|0.60|0.50|0.30|0.70|0.20"

# Pipe from another command
echo "@state:tensor|0.40|0.60|0.50|0.30|0.70|0.20" | mx state decode

# JSON output
mx state decode "@state:tensor|0.40|0.60|0.50|0.30|0.70|0.20" -F json

# Show only the nearest mood
mx state decode "@state:tensor|0.40|0.60|0.50|0.30|0.70|0.20" -F mood

# Re-encode (roundtrip)
mx state decode "@state:tensor|0.40|0.60|0.50|0.30|0.70|0.20" -F tensor

Output formats

human

The default. Prints each dimension as Name: value (anchor description), followed by the nearest mood if one falls within tolerance.

json

Structured JSON with schema_id and values fields.

tensor

Re-encodes the tensor. Useful for normalizing or roundtripping.

mood

Prints only the nearest mood name, its description, and distance. If no mood is within tolerance, prints (unnamed region).

Rune stripping

Tensor strings may contain rune prefixes on values (e.g., @state:tensor|ᚣ0.30|ᚤ0.20|...). The decoder strips any non-digit, non-dot, non-minus prefix characters before parsing, so rune-encoded and plain tensors decode identically.

Flags

Examples

mx state schemas

mx state schemas --json

Flags

Examples

# List all moods for the default schema
mx state moods

# List moods for a specific schema
mx state moods -s crewu

# Show details for a specific mood
mx state moods calm

# JSON output
mx state moods --json

Mood matching

When encoding or decoding, the nearest mood is found by weighted Euclidean distance. Each mood defines a canonical tensor (the center point), optional per-dimension weights (default 1.0), and a tolerance radius (default 0.30). A mood matches when the distance is within tolerance. If multiple moods match, the closest one wins.

The distance formula:

$$d = \sqrt{\sum_{i = 0}^{n - 1}w_{i}\left( v_{i} - c_{i} \right)^{2}}$$

where $v_{i}$ is the tensor value, $c_{i}$ is the mood’s canonical value, and $w_{i}$ is the per-dimension weight.

Flags

Examples

mx state info

mx state info -s crewu

mx state info --json

Top-level fields

id

Required. Schema identifier. Must match the file stem.

name

Required. Human-readable name.

version

Optional. Integer version number. Default: 1.

dimensions

Required. Ordered list of dimension definitions.

moods

Optional. Map of mood name to mood definition. Default: empty.

Dimension definition

Each dimension in the dimensions list has these fields:

id

Required. Unique identifier (e.g., entropy, temperature).

name

Required. Human-readable display name.

rune

Optional. Decorative Unicode character used when --runes is enabled.

default

Optional. Default value (0.0–1.0). Default: 0.5.

anchors

Required. Object with anchor descriptions:

• low: Required. Description for values near 0.0.

• mid: Optional. Description for values near 0.5.

• high: Required. Description for values near 1.0.

Mood definition

Each entry in the moods map has these fields:

description

Required. Human-readable description of the mood.

tensor

Required. List of canonical float values, one per dimension, in the dimension order declared by the schema.

weights

Optional. List of per-dimension weights for distance calculation. Default: 1.0 for all dimensions.

tolerance

Optional. Maximum weighted Euclidean distance for a tensor to be considered “in” this mood. Default: 0.30.

Example schema

id: example
name: Example Schema
version: 1

dimensions:
  - id: entropy
    name: Entropy
    rune: "ᙣ"
    anchors:
      low: ordered / focused / coherent
      mid: structured but breathing
      high: chaotic / associative / wild
    default: 0.4

  - id: agency
    name: Agency
    anchors:
      low: receptive / yielding
      mid: collaborative
      high: active / driving / proactive
    default: 0.5

moods:
  calm:
    description: Settled, receptive, low entropy
    tensor: [0.2, 0.3]
    weights: [1.0, 0.8]
    tolerance: 0.3

  driven:
    description: High agency, moderate entropy
    tensor: [0.5, 0.9]
    tolerance: 0.25

Default tensor schema

The built-in tensor schema ships with six dimensions in this order:

1. Entropy – ordered/focused (0.0) to chaotic/wild (1.0). Default: 0.4.

2. Agency – receptive/yielding (0.0) to active/driving (1.0). Default: 0.5.

3. Temperature – cold/precise (0.0) to warm/casual (1.0). Default: 0.5.

4. Verbosity – terse/minimal (0.0) to expansive/elaborate (1.0). Default: 0.4.

5. Skepticism – agreeable/affirming (0.0) to challenging/pushback (1.0). Default: 0.55.

6. Humor – serious/matter-of-fact (0.0) to playful/quippy (1.0). Default: 0.3.

The default schema has no moods defined. Add moods to your local copy at $MX_HOME/state/schemas/tensor.yaml to enable mood matching.

Schema resolution

The --schema flag on all commands accepts either a schema ID or a direct file path. The heuristic: if the argument contains a slash or ends with .yaml, .yml, or .json, it is treated as a path and loaded directly. Otherwise it is treated as an ID and resolved from $MX_HOME/state/schemas/ with an extension fallback chain of .yaml, .yml, .json.