Contents

KV Store
- Concepts
  - Data types
  - Schema files
  - Schema format
  - Auto-creating keys
  - Agent keying
  - Exit codes
- Basic operations
- mx kv get <key>
  - Flags
  - Examples
- mx kv set <key> [args...] [--json <value>]
  - Flags
  - Examples
- mx kv keys
  - Examples
- Counters
- mx kv inc <key>
  - Flags
  - Examples
- mx kv dec <key>
  - Flags
  - Examples
- Lists & History
  - push
- mx kv push <key> <value>
  - Flags
  - Examples
  - pop
- mx kv pop <key>
  - Examples
  - last
- mx kv last <key>
  - Flags
  - Examples
  - since
- mx kv since <key> <timeref>
  - Flags
  - Examples
  - search
- mx kv search <key> [query]
  - Flags
  - Examples
  - count
- mx kv count <key> [value]
  - Flags
  - Examples
  - random
- mx kv random <key>
  - Flags
  - Examples
  - remove
- mx kv remove <key> [value]
  - Flags
  - Examples
  - update
- mx kv update <key> [value] --id <spec>
  - Flags
  - Examples
  - migrate
- mx kv migrate <key>
  - Flags
  - Examples
- Time-range queries
  - Available flags
  - Interaction with --count
  - Examples
  - Relationship to since subcommand
- Structured data
  - Pushing data
  - Output format
  - Filtering with --where
  - Matching semantics
  - Combining with other filters
  - Backward compatibility
- Entry IDs
  - Generation
  - Push output
  - Dual addressing
  - Prefix matching
  - Backward compatibility
- Management
- mx kv dump
  - Flags
  - Examples
- mx kv reset <key>
  - Examples
- mx kv rename <old-key> <new-key>
  - Examples
- Memory linking
  - Key-level memory links
  - Per-entry memory links
  - Resolution hierarchy
  - Resolving memory links
- JSON output
  - Entry format
  - Special output shapes
  - Piping to jq

KV Store

Fast local key-value state per agent.

The KV subsystem gives each agent a lightweight, schema-driven key-value store for operational state that needs to be fast and local. Counters, strings, lists, timestamped history, and structured state fields – all backed by a TOML schema file and a JSON data file. No networking, no database. Reads and writes are direct file operations with atomic saves (serialize to tmp, fsync, rename). History and list entries can carry structured JSON data for queryable metadata.

Use KV for state that lives within a single agent session or across sessions: build counters, track decisions as a history log, maintain a todo list, or store the current goal as a string. For cross-agent knowledge that needs search, tagging, and relationships, use Memory instead.

Concepts

Data types

Every key has a type declared in the schema. Five types are supported:

string: A single text value. Has an optional default.
counter: An integer with optional min, max, and default. Clamped on every write.
history: A timestamped append-only log. Newest entries first. Has an optional max_entries cap that drops the oldest entries on overflow. Each entry gets a numeric index and a stable ID. Entries can carry optional structured JSON data.
list: An ordered collection with timestamps. Supports push and pop. Also has an optional max_entries cap. Each entry gets a numeric index and a stable ID. Entries can carry optional structured JSON data.
state: A structured record with named fields. Fields are declared in the schema and validated on write.

Schema files

Each agent has a TOML schema file that declares every valid key, its type, and any constraints. The schema lives at:

$MX_HOME/kv/schema/{agent}.toml

The data file (JSON, auto-created on first write) lives at:

$MX_HOME/kv/data/{agent}.json

The active agent is determined by the MX_CURRENT_AGENT environment variable.

You can override the paths with MX_KV_SCHEMA and MX_KV_DATA environment variables. Both support an {agent} placeholder that expands to the current agent name.

Schema format

A schema file is TOML with a [keys.<name>] section per key:

[keys.builds]
type = "counter"
min = 0
default = "0"

[keys.session_goal]
type = "string"
default = ""

[keys.decisions]
type = "history"
max_entries = 50

[keys.ideas]
type = "list"

[keys.todos]
type = "list"
max_entries = 20
description = "Pending work items"

[keys.context]
type = "state"
fields = ["goal", "phase", "blocker"]

Schema fields:

type: Required. One of string, counter, history, list, state.
default: Optional. Initial value for string and counter types.
min: Optional. Minimum value for counters (clamped, never errors).
max: Optional. Maximum value for counters (clamped, never errors).
max_entries: Optional. Maximum entries for history and list types. Oldest entries are dropped when exceeded. Omit to allow unbounded growth.
description: Optional. Human-readable description of the key’s purpose. Displayed as a third column by mx kv keys.
fields: Optional. List of valid field names for state types. Writes to unlisted fields are rejected.

Auto-creating keys

Keys can be added to the schema on the fly with mx kv push --create. When a key does not exist in the schema, --create history or --create list appends a new [keys.<name>] block to the TOML file and reloads the in-memory schema. This avoids manual schema editing for simple cases. See push for details and validation rules.

Agent keying

All KV operations require MX_CURRENT_AGENT to be set. Each agent gets its own schema and data file – there is no cross-agent state leakage. Two agents can define entirely different schemas with different keys.

Exit codes

KV commands use structured exit codes for scripting:

0: Success.
1: Key not found (or no data yet for that key).
2: Type mismatch (e.g., inc on a string key, or get --id on a non-history/list key).
3: Schema file not found.
4: Invalid input (e.g., reversed range, empty spec, empty ID after kv- prefix, entry not found by ID, ambiguous ID prefix).

Basic operations

`mx kv get <key>`

Get the current value of a key, or look up specific entries by ID.

Without --id, prints the full current value: raw text for strings and counters, all entries with indexes and timestamps for history and list types, and fields as JSON for state types.

With --id, retrieves specific entries from a history or list by numeric index or entry ID. Four formats are supported:

Single numeric index: --id 35 – returns exactly one entry.
Single entry ID: --id kv-A3fB – returns the entry matching that ID. ID matching is prefix-based: kv-A3f will match if the prefix is unambiguous.
Numeric range: --id 35-64 – returns all entries with indexes 35 through 64 inclusive. Maximum range size is 10,000 entries. Ranges are numeric only.
Comma-separated: --id 1,kv-A3fB,12 – returns the listed entries. Numeric indexes and entry IDs can be mixed freely in comma lists.

If any requested IDs are not found, a note listing the missing IDs is printed to stderr. The found entries are still printed to stdout.

The --id flag only works on history and list types. Using it on a string, counter, or state key returns exit code 2 (type mismatch). Parse failures (reversed ranges, empty specs) return exit code 4 (invalid input).

Flags

Flag	Type	Description
`--id <spec>`	string	Entry identifier: numeric index (`35`), entry ID (`kv-A3fB`), range (`35-64`), or comma-separated (`1,kv-A3fB,12`)
`--memory`	flag	Resolve and display any linked memory entry
`--json`	flag	Output as JSON. Collections emit a JSON array of entry objects. Scalars emit `{"value": "..."}`. Memory resolution is skipped in JSON mode; the raw `kn-` ID is included in each entry’s `memory` field.

Examples

mx kv get session_goal

mx kv get builds

mx kv get decisions

mx kv get context --memory

mx kv get shipped --id 35

mx kv get shipped --id kv-A3fB

mx kv get shipped --id 35-64

mx kv get shipped --id 1,kv-A3fB,12

mx kv get shipped --id 35 --memory

mx kv get shipped --id 42 --json

mx kv get shipped --json

`mx kv set <key> [args...] [--json <value>]`

Set a value for a string, counter, or state key, or link a specific entry to a memory node. Supports four input modes for state keys: single-field, inline batch, JSON object, and JSON array (tensor).

For string keys: mx kv set <key> <value> sets the value directly.

For counter keys: mx kv set <key> <value> parses the value as an integer and clamps to min/max.

For state keys, four input modes are available:

Single field (legacy): mx kv set <key> <field> <value> – sets one field. Backward compatible with pre-batch syntax.
Inline batch: mx kv set <key> field1=value1 field2=value2 ... – sets multiple fields atomically. All field names are validated against the schema before any writes. Unmentioned fields are preserved (partial update).
JSON object: mx kv set <key> --json '{"field1":"value1","field2":"value2"}' – sets multiple fields from a JSON object. Non-string values (numbers, booleans, null) are coerced to strings. Same atomic validation as inline batch.
JSON array (tensor): mx kv set <key> --json '[0.4, 0.6, 0.5]' – sets all fields by position. The number of array elements must exactly match the number of fields declared in the schema. Values are mapped to schema fields in declaration order.

The --json flag accepts "-" to read JSON from stdin: echo '{"goal":"done"}' | mx kv set context --json -

The --json flag and positional arguments cannot be combined – use one or the other.

Batch operations (inline and JSON) are all-or-nothing: if any field name is invalid, no fields are written. Duplicate field names in a single batch are rejected. All validation errors are reported, not just the first.

With --id and --memory, links an existing history or list entry to a memory knowledge node. The --id flag accepts a numeric index (17) or an entry ID (kv-A3fB). ID matching is prefix-based – an ambiguous prefix returns an error asking for more characters. --id requires --memory; it cannot be used alone. Pass an empty string (--memory "") to clear a per-entry link.

Flags

Flag	Type	Description
`--json <value>`	string	JSON input: object for state batch set, array for tensor positional set. Use `"-"` to read from stdin.
`--memory <kn-id>`	string	Link a memory entry (kn- ID) to this key or entry, or `""` to clear
`--id <spec>`	string	Target a specific entry by numeric index or entry ID (requires `--memory`)

Examples

mx kv set session_goal "ship the docs"

mx kv set builds 0

mx kv set context goal "finish KV docs"

mx kv set context phase "writing"

mx kv set context goal="done" phase="writing"

mx kv set context goal="done" phase="writing" blocker="none"

mx kv set context --json '{"goal":"done","phase":"writing"}'

mx kv set mytensor --json '[0.4, 0.6, 0.5]'

echo '{"goal":"done"}' | mx kv set context --json -

mx kv set decisions --memory kn-abc123

mx kv set decisions --memory ""

mx kv set decisions --id 17 --memory kn-abc123

mx kv set decisions --id kv-A3fB --memory kn-def456

mx kv set decisions --id 17 --memory ""

`mx kv keys`

List all keys defined in the schema with their types. Output is two columns: key name (left-aligned, 30 chars) and type. When a key has a description in the schema, it is shown as a third column.

Examples

mx kv keys

Counters

`mx kv inc <key>`

Increment a counter key. Returns the new value after incrementing. The result is clamped to the schema’s min/max bounds – it never errors on overflow, it just stops at the limit.

Flags

Flag	Type	Description
`--by <n>`	integer	Amount to increment by (default: 1)

Examples

mx kv inc builds

mx kv inc builds --by 5

`mx kv dec <key>`

Decrement a counter key. Returns the new value after decrementing. Like inc, the result is clamped to schema bounds.

Flags

Flag	Type	Description
`--by <n>`	integer	Amount to decrement by (default: 1)

Examples

mx kv dec retries

mx kv dec retries --by 3

Lists & History

History and list types both store timestamped entries with auto-assigned IDs. The difference is semantic: history is append-only (newest first, no pop), while lists support push/pop and maintain insertion order.

Every entry gets two identifiers: a numeric index (sequential, per-key) and a stable entry ID (a base58 string prefixed with kv-, e.g. kv-A3fB). Both can be used anywhere an ID is accepted. See Entry IDs for details.

Both types support push, last, search, count, random, remove, update, migrate, and entry lookup by ID via get --id. Both support structured data on entries (--data on push/update) and structured data filtering (--where on queries). Only lists support pop. Only history supports since (time-based queries).

push

`mx kv push <key> <value>`

Push a value onto a history or list key. The entry is automatically timestamped and assigned both a numeric index and a stable entry ID.

On success, prints the new entry’s identifiers:

kv-A3fB (42)

Entry ID first (the primary stable identifier), numeric index in parentheses.

For history keys, new entries are inserted at the front (newest first). If the key has a max_entries schema constraint, the oldest entries are truncated after the push.

For list keys, new entries are appended to the end. The same max_entries truncation applies, dropping from the front.

Use --data to attach a JSON object to the entry. The data is stored alongside the value and timestamp, and is displayed inline in output. See Structured data for details and query examples.

Use --memory to link the new entry to a knowledge node in the memory graph. This sets a per-entry memory pointer (a kn- ID) that is resolved when --memory is passed to read commands. See Per-entry memory links for the full resolution hierarchy.

Use --create to auto-add the key to the schema if it does not already exist. Pass the type as the value: --create history or --create list. Only history and list types are accepted (those are the types that support push). If the key already exists in the schema, --create is silently ignored – this makes it safe to use unconditionally in scripts without checking whether the key has been defined yet.

The optional --max-entries flag sets the entry cap for the new key. It requires --create and has no effect if the key already exists.

Key names are validated on creation: alphanumeric characters, underscores, and hyphens only, maximum 128 characters. Dots are rejected because they conflict with TOML key quoting. The new key block is appended to the schema file without reformatting existing content.

Flags

Flag	Type	Description
`--data <json>`	string	Attach a JSON object to the entry. Must be a valid JSON object (not an array, string, or other type).
`--memory <kn-id>`	string	Link this entry to a memory knowledge node (e.g. `kn-abc123`). Resolved when `--memory` is passed on read commands.
`--create <type>`	enum	Auto-create the key in the schema if missing. Accepted types: `history`, `list`. Silently ignored if the key already exists.
`--max-entries <n>`	integer	Maximum entries for the new key (only valid with `--create`). Oldest entries are dropped when exceeded.

Examples

mx kv push decisions "chose Typst for docs"

mx kv push todos "write tests for kv handler"

mx kv push projects "palmtop DSI fix" --data '{"tags":["palmtop","i915"],"status":"active"}'

mx kv push shipped "v0.1.156" --data '{"pr":305,"scope":"kv"}'

mx kv push decisions "adopted per-entry memory links" --memory kn-abc123

mx kv push puns "the joke" --create history

mx kv push ideas "wild thought" --create list --max-entries 500

pop

`mx kv pop <key>`

Pop the last item from a list key. Prints the removed entry with its numeric index, entry ID, value, and timestamp. Returns silently if the list is empty.

Only works on list types. History keys are append-only and do not support pop.

Examples

mx kv pop todos

last

`mx kv last <key>`

Get the last N entries from a history or list key. Entries are printed with their numeric index, entry ID, value, and timestamp.

For history keys, “last” means the most recent (entries are stored newest first). For list keys, “last” means the tail of the list.

Time-range flags narrow the result set before --count is applied. See Time-range queries for details and examples.

The --where flag filters entries by structured data fields. Multiple --where flags are ANDed. See Structured data for filtering semantics.

Flags

Flag	Type	Description
`--count <n>`	integer	Number of entries to return (default: 1)
`--memory`	flag	Resolve and display any linked memory entry
`--json`	flag	Output as a JSON array of entry objects
`--where <key=value>`	string	Filter by structured data field (repeatable, ANDed). Top-level fields only.
`--day <YYYY-MM-DD>`	string	Entries from a specific day (UTC)
`--month <YYYY-MM>`	string	Entries from a specific month (UTC)
`--week <YYYY-Www>`	string	Entries from an ISO week, Monday to Sunday
`--from <YYYY-MM-DD>`	string	Start of date range, inclusive (UTC)
`--to <YYYY-MM-DD>`	string	End of date range, inclusive (UTC)
`--since <relative-or-iso>`	string	Filter entries since a relative time (`30d`, `1w`, `2h`, `30m`) or ISO-8601 timestamp

Examples

mx kv last decisions

mx kv last decisions --count 5

mx kv last todos --count 3 --memory

mx kv last shipped --day 2026-04-25

mx kv last shipped --month 2026-04

mx kv last shipped --month 2026-04 --count 5

mx kv last shipped --since 1w

mx kv last projects --where status=active

mx kv last projects --where status=active --count 3

mx kv last projects --count 5 --json

since

`mx kv since <key> <timeref>`

Get history entries since a time reference. Only works on history keys.

The time reference can be relative or absolute:

Relative: 30m (minutes), 1h (hours), 7d (days), 2w (weeks)
Absolute: ISO-8601 format (e.g., 2025-01-15T10:00:00Z)

Entries are printed with their numeric index, entry ID, value, and timestamp.

Flags

Flag	Type	Description
`--memory`	flag	Resolve and display any linked memory entry
`--json`	flag	Output as a JSON array of entry objects

Examples

mx kv since decisions 1h

mx kv since decisions 7d

mx kv since decisions 2w --memory

mx kv since decisions 2025-01-15T10:00:00Z

mx kv since shipped 1w --json

search

`mx kv search <key> [query]`

Search entries in a list or history by case-insensitive substring match and/or structured data filters. Prints matching entries with their numeric index, entry ID, value, timestamp, and any attached data.

The text query is optional when --where filters are provided. You can search by text alone, by structured data alone, or by both. At least one of a text query or --where filter must be given.

Multiple --where flags are ANDed. See Structured data for filtering semantics.

Time-range flags narrow the search to entries within the specified period. See Time-range queries for details.

Flags

Flag	Type	Description
`--memory`	flag	Resolve and display any linked memory entry
`--json`	flag	Output as a JSON array of entry objects
`--where <key=value>`	string	Filter by structured data field (repeatable, ANDed). Top-level fields only.
`--day <YYYY-MM-DD>`	string	Search within a specific day (UTC)
`--month <YYYY-MM>`	string	Search within a specific month (UTC)
`--week <YYYY-Www>`	string	Search within an ISO week, Monday to Sunday
`--from <YYYY-MM-DD>`	string	Start of date range, inclusive (UTC)
`--to <YYYY-MM-DD>`	string	End of date range, inclusive (UTC)
`--since <relative-or-iso>`	string	Search since a relative time (`30d`, `1w`, `2h`, `30m`) or ISO-8601 timestamp

Examples

mx kv search decisions "typst"

mx kv search todos "test"

mx kv search shipped "feature" --month 2026-04

mx kv search shipped "feature" --since 30d

mx kv search projects --where status=active

mx kv search projects "DSI" --where status=active

mx kv search projects --where tags=palmtop --where status=active

mx kv search projects --where status=active --json

count

`mx kv count <key> [value]`

Count entries in a list or history. Without a value filter or --where, prints the total count. With a value filter, --where, or both, prints the matched count, total, and percentage.

Unfiltered output: <count> or <count> (latest: <timestamp>).

Filtered output: <matched>/<total> (<pct>%) --- latest: <timestamp>.

The percentage display makes it easy to gauge ratios at a glance – for example, what fraction of your decisions mentioned a particular topic, or how many entries have status=active in their structured data.

Multiple --where flags are ANDed. See Structured data for filtering semantics.

Time-range flags restrict the count to entries within the specified period. See Time-range queries for details.

Flags

Flag	Type	Description
`--json`	flag	Output as JSON: `{"count": N}` with optional `total` and `latest_ts` fields when filtering is active
`--where <key=value>`	string	Filter by structured data field (repeatable, ANDed). Top-level fields only.
`--day <YYYY-MM-DD>`	string	Count within a specific day (UTC)
`--month <YYYY-MM>`	string	Count within a specific month (UTC)
`--week <YYYY-Www>`	string	Count within an ISO week, Monday to Sunday
`--from <YYYY-MM-DD>`	string	Start of date range, inclusive (UTC)
`--to <YYYY-MM-DD>`	string	End of date range, inclusive (UTC)
`--since <relative-or-iso>`	string	Count since a relative time (`30d`, `1w`, `2h`, `30m`) or ISO-8601 timestamp

Examples

mx kv count decisions

mx kv count decisions "typst"

mx kv count todos "blocked"

mx kv count shipped --day 2026-05-07

mx kv count shipped --from 2026-04-01 --to 2026-04-15

mx kv count shipped --since 1w

mx kv count projects --where status=active

mx kv count projects --where status=active --since 30d

mx kv count shipped --json

random

`mx kv random <key>`

Get N random entries from a history or list key. Entries are printed with their numeric index, entry ID, value, and timestamp.

Useful for inspiration (pick a random idea), spot-checking (sample from a large history), or building variety into automated workflows.

When fewer entries are available than requested, all matching entries are returned and a note is printed to stderr. If a time range or --where filter is specified, entries are filtered first, then random sampling is applied to the filtered set.

Multiple --where flags are ANDed. See Structured data for filtering semantics.

Flags

Flag	Type	Description
`--count <n>`	integer	Number of random entries to return (default: 1, must be >= 1)
`--memory`	flag	Resolve and display any linked memory entry
`--json`	flag	Output as a JSON array of entry objects
`--where <key=value>`	string	Filter by structured data field (repeatable, ANDed). Top-level fields only.
`--day <YYYY-MM-DD>`	string	Sample from entries on a specific day (UTC)
`--month <YYYY-MM>`	string	Sample from entries in a specific month (UTC)
`--week <YYYY-Www>`	string	Sample from entries in an ISO week, Monday to Sunday
`--from <YYYY-MM-DD>`	string	Start of date range, inclusive (UTC)
`--to <YYYY-MM-DD>`	string	End of date range, inclusive (UTC)
`--since <relative-or-iso>`	string	Sample from entries since a relative time (`30d`, `1w`, `2h`, `30m`) or ISO-8601 timestamp

Examples

mx kv random shipped

mx kv random shipped --count 5

mx kv random ideas --count 1

mx kv random shipped --count 3 --since 30d

mx kv random decisions --month 2026-04 --count 3

mx kv random projects --where status=active --count 3

mx kv random ideas --count 3 --json

remove

`mx kv remove <key> [value]`

Remove entries from a list or history by value substring or by ID. You must provide either a value substring or --id.

The --id flag accepts a numeric index (7) or an entry ID (kv-A3fB). ID matching is prefix-based – if the prefix is ambiguous (matches multiple entries), an error is returned asking for more characters.

By default, only the first match is removed. Use --all to remove every matching entry.

Flags

Flag	Type	Description
`--id <spec>`	string	Remove the entry with this numeric index or entry ID (`kv-XXXX`)
`--all`	flag	Remove all matching entries (default: first match only)

Examples

mx kv remove todos "write tests"

mx kv remove todos --id 7

mx kv remove todos --id kv-A3fB

mx kv remove decisions "typo" --all

update

`mx kv update <key> [value] --id <spec>`

Update an existing entry’s value and/or structured data in-place. Preserves the entry’s ID, position, and timestamp.

Requires --id to target a specific entry by numeric index or entry ID. ID matching is prefix-based – if the prefix is ambiguous (matches multiple entries), an error is returned asking for more characters. The value argument is optional – you can update only --data, only the value, or both.

When --data is provided, the JSON object is shallow-merged into the entry’s existing structured data. Fields in the patch overwrite existing fields. Null values in the patch delete that field from the merged result (they do not set it to null). If the key has a [data] schema section, validation runs on the merged result before the write commits.

At least one of a value argument or --data must be provided – calling update with neither is rejected.

On success, prints the updated entry’s identifiers:

Updated entry 42 (kv-A3fB)

Works on both history and list types.

Flags

Flag	Type	Description
`--id <spec>`	string	Target entry by numeric index (`42`) or entry ID (`kv-A3fB`). Required.
`--data <json>`	string	JSON object to merge into the entry’s structured data. Null field values delete that field from the merged result.

Examples

mx kv update projects "palmtop DSI fix (v2)" --id kv-A3fB

mx kv update projects --id 42 --data '{"status":"done"}'

mx kv update projects "renamed" --id kv-A3fB --data '{"status":"closed"}'

mx kv update projects --id 42 --data '{"obsolete_field":null}'

migrate

`mx kv migrate <key>`

Migrate existing entries to match current schema data definitions. Operates on all entries in a key.

Compares each entry’s structured data against the [data] section in the key’s schema. Missing fields that have a default value in the schema are added. Required fields without defaults produce a warning. Type mismatches between existing data and schema declarations are reported as warnings.

Entries without any structured data get a new data object populated from schema defaults.

With --prune, fields present in entries but not declared in the schema are removed. Without --prune, undeclared fields are left untouched.

With --dry-run, reports what would change without modifying any data. The output lists each affected entry with its added and pruned fields.

If the key has no [data] section in the schema, nothing is migrated and a warning is printed.

Works on both history and list types.

Flags

Flag	Type	Description
`--prune`	flag	Remove fields not declared in the current schema
`--dry-run`	flag	Show what would change without modifying data

Examples

mx kv migrate projects

mx kv migrate projects --dry-run

mx kv migrate projects --prune

mx kv migrate projects --prune --dry-run

Time-range queries

The last, search, count, and random subcommands accept time-range flags that filter entries by their timestamp before any other processing. This lets you answer questions like “what did I ship last Tuesday?” or “how many decisions were recorded in April?” without scanning the full history.

Available flags

All time-range flags are mutually exclusive – you can use one shorthand (--day, --month, --week, --since) or one explicit range (--from/--to), but not both.

Flag	Format	Selects
`--day`	`YYYY-MM-DD`	All entries from that calendar day (00:00 to 23:59 UTC)
`--month`	`YYYY-MM`	All entries from that calendar month (first day to last day, UTC)
`--week`	`YYYY-Www`	All entries from that ISO week (Monday 00:00 to Sunday 23:59 UTC)
`--since`	relative or ISO-8601	All entries from the given point in time until now. Relative formats: `30d` (days), `1w` (weeks), `2h` (hours), `30m` (minutes). Also accepts full ISO-8601 timestamps.
`--from`	`YYYY-MM-DD`	Start of range, inclusive (midnight UTC). Can be used alone (implies “to now”)
`--to`	`YYYY-MM-DD`	End of range, inclusive (end of day UTC). Can be used alone (implies “from the beginning”)

All dates are interpreted as UTC. The --to date is inclusive – entries from any time on that day are included.

Interaction with `--count`

When both a time range and --count are specified, the time range is applied first, then --count limits the result. This applies to both last (which takes the N most recent from the filtered set) and random (which samples N entries from the filtered set).

# The 5 most recent entries from April 2026
mx kv last shipped --month 2026-04 --count 5

# 3 random entries from the last 30 days
mx kv random shipped --since 30d --count 3

Examples

# Everything shipped on a specific day
mx kv last shipped --day 2026-04-25

# Everything shipped in April
mx kv last shipped --month 2026-04

# Everything shipped in ISO week 17
mx kv last shipped --week 2026-W17

# Everything shipped in the first half of April
mx kv last shipped --from 2026-04-01 --to 2026-04-15

# Everything shipped in the last week
mx kv last shipped --since 1w

# Search within a time window
mx kv search shipped "feature" --month 2026-04

# Count entries on a specific day
mx kv count shipped --day 2026-05-07

# Count entries from the last 30 days
mx kv count shipped --since 30d

# Random entry from the last 2 hours
mx kv random shipped --since 2h

Relationship to `since` subcommand

The since subcommand (mx kv since <key> <timeref>) is a standalone command that returns all history entries since a time reference. It only works on history keys and predates the time-range flag system.

The --since flag brings relative time filtering to all time-range-aware subcommands (last, search, count, random) and works on both history and list types. It accepts the same relative formats (30d, 1w, 2h, 30m) and ISO-8601 timestamps.

Use the since subcommand when you want a quick “everything since X” dump from a history key. Use the --since flag when you want to combine relative time filtering with other operations like counting, searching, or random sampling, or when you need it on a list key.

NOTE: Time-range flags (--day, --month, --week, --since, --from/--to) are available on last, search, count, and random. The since subcommand is unchanged and continues to work for history keys.

Structured data

History and list entries can carry structured JSON data alongside their text value. This turns each entry from a plain string into a string with queryable metadata – tags, status, priority, or any key-value pairs relevant to the domain.

Pushing data

Use --data on push to attach a JSON object to the entry:

mx kv push projects "palmtop DSI fix" \
  --data '{"tags":["palmtop","i915"],"status":"active"}'

mx kv push shipped "v0.1.156" \
  --data '{"pr":305,"scope":"kv"}'

The data must be a valid JSON object. Arrays, strings, numbers, and other non-object JSON types are rejected. If --data is omitted, the entry has no structured data (backward compatible with all existing entries).

Output format

Entries display the numeric index, entry ID in brackets, value, timestamp, and any structured data:

42 [kv-A3fB]: palmtop DSI fix (2026-05-08T14:30:00Z) {"tags":["palmtop","i915"],"status":"active"}
43 [kv-B7xQ]: display rotation patch (2026-05-08T15:00:00Z)

Entries without data omit the trailing JSON. This format appears on all commands that display entries: get, last, search, since, pop, random, and dump.

Filtering with `--where`

The --where flag queries entries by their structured data fields. It is available on search, last, random, and count.

# Exact match on a string field
mx kv search projects --where status=active

# Array-contains: matches if the array includes the value
mx kv search projects --where tags=palmtop

# Combine text search with structured data filter
mx kv search projects "DSI" --where status=active

# Multiple --where flags are ANDed
mx kv search projects --where tags=palmtop --where status=active

# Works on last, random, and count too
mx kv last projects --where status=active --count 5
mx kv random projects --where status=active --count 3
mx kv count projects --where status=active

Matching semantics

Each --where clause has the form key=value (split on the first =). The match is evaluated against the top-level fields of the entry’s JSON data:

String field: The field value must equal the clause value exactly.
Array field: The array must contain a string element equal to the clause value.
Number field: The field’s string representation must equal the clause value (e.g., --where pr=305).
Boolean field: Matches against true or false as strings.
Missing field: Does not match. Entries without data never match any --where clause.

Only top-level fields are supported. Dot-path traversal (e.g., --where nested.field=value) is not available.

When multiple --where clauses are given, ALL must match (AND logic). There is no OR operator – use separate queries if you need union semantics.

Combining with other filters

The --where flag composes with both text queries and time-range flags. All filters are applied together:

# Text + where + time range: all three must match
mx kv search projects "DSI" --where status=active --since 30d

Filter application order: time range first, then --where, then text query. The --count limit is applied last.

Backward compatibility

Structured data is fully backward compatible. Existing data files written before this feature was added continue to work without migration. Entries without data are simply treated as having no structured fields – they will not match any --where clause, but they are otherwise unaffected.

Entry IDs

Every history and list entry has a stable entry ID in addition to its numeric index. Entry IDs are short base58 strings (4–6 characters) prefixed with kv- for visual identification, e.g. kv-A3fB.

Generation

The ID is generated from blake3(key + timestamp + index), with the first 4 bytes encoded as base58 via base-d. This produces 11 million unique addresses per key – sufficient for typical KV usage. The ID is deterministic: the same key, timestamp, and numeric index always produce the same ID.

Push output

mx kv push prints the new entry’s identifiers on success:

kv-A3fB (42)

Entry ID first (the primary stable identifier), numeric index in parentheses. This makes it easy to capture the ID for later use in scripts or follow-up commands.

Dual addressing

Anywhere a numeric index is accepted, an entry ID also works:

# Get by entry ID
mx kv get shipped --id kv-A3fB

# Get by numeric index (still works)
mx kv get shipped --id 42

# Mix in comma lists
mx kv get shipped --id 42,kv-A3fB,15

# Remove by entry ID
mx kv remove shipped --id kv-A3fB

Numeric ranges remain numeric only (35-64). Entry IDs cannot be used in ranges because they are not ordered.

Prefix matching

ID lookups are prefix-based: kv-A3f will match an entry with ID A3fBx2 as long as the prefix uniquely identifies one entry. If the prefix is ambiguous (matches multiple entries), an error is returned:

Error: ID prefix 'kv-A3' is ambiguous: matches 3 entries, provide more characters

Backward compatibility

Old data files written before entry IDs existed are back-filled automatically on first load. The store generates IDs for all entries that lack one, saves the file, and continues normally. This is a one-time migration – no manual action is needed.

Management

`mx kv dump`

Dump all KV state. Defaults to JSON output (the full data file, pretty- printed). Compact format shows one line per key in key=value notation, designed for embedding in wake prompts or status lines.

Compact format examples:

Counters: builds=42
Strings: session_goal=ship the docs
History: decisions=[chose Typst\@14:30,fixed bug\@13:15]
Lists: todos=[write tests\@14:30,review PR\@13:15]
State: context={finish KV docs,writing,}
Memory links appended: decisions=[...](kn-abc123)

Flags

Flag	Type	Description
`--format <fmt>`	enum	Output format: `json` (default) or `compact`
`--memory`	flag	Resolve and display all linked memory entries

Examples

mx kv dump

mx kv dump --format compact

mx kv dump --memory

`mx kv reset <key>`

Reset a key to its schema default value. Counters return to their default (or 0). Strings return to their default (or empty). History and list keys are cleared to empty. State keys reset all fields to empty strings.

Examples

mx kv reset builds

mx kv reset decisions

mx kv reset context

`mx kv rename <old-key> <new-key>`

Rename a key, preserving all entries and data. The old key is removed from both the schema (TOML) and data (JSON) files, and all its content – type definition, constraints, entries, timestamps, structured data, memory links – is moved to the new key name. Entry IDs are stable and do not change.

The new key name is validated with the same rules as push --create: alphanumeric characters, underscores, and hyphens only, maximum 128 characters, no dots.

Persistence order: the data file is written first (higher-value file), then the schema file. If the data write fails, in-memory state is rolled back and no files are modified.

Examples

mx kv rename session_goal current_goal

mx kv rename old_decisions archived_decisions

Memory linking

History, list, and state keys can be linked to a memory graph entry via the --memory flag. This creates a pointer from the KV key to a knowledge entry (a kn- ID), bridging fast local state with the persistent knowledge graph.

When a memory link is set, commands that read the key (get, last, since, search, random, dump) can resolve the link with --memory, which fetches the linked entry from SurrealDB and prints its title, category, and body.

Key-level memory links

# Link a key to a memory entry
mx kv set decisions --memory kn-abc123

# Clear a memory link (pass empty string)
mx kv set decisions --memory ""

Key-level memory links are stored in the JSON data file alongside the key’s entries. They survive resets – mx kv reset clears the data but preserves the memory pointer.

Per-entry memory links

Individual history and list entries can carry their own memory link. This allows different entries within the same key to reference different knowledge nodes.

Set at creation time:

# Link a new entry to a knowledge node on push
mx kv push decisions "adopted per-entry memory links" --memory kn-abc123

Set on an existing entry:

# Link by numeric index
mx kv set decisions --id 17 --memory kn-abc123

# Link by entry ID
mx kv set decisions --id kv-A3fB --memory kn-def456

# Clear a per-entry link
mx kv set decisions --id 17 --memory ""

The --id flag on set requires --memory – it cannot be used alone. ID matching is prefix-based: kv-A3f matches if the prefix uniquely identifies one entry. If the prefix is ambiguous, an error is returned. If the entry is not found, exit code 4 (invalid input) is returned.

Resolution hierarchy

When --memory is passed on a read command, memory links are resolved in priority order:

Per-entry memory field – if the entry has its own memory link, that link is resolved and displayed. This is the highest priority.
Legacy kn- value – if the entry’s value string starts with kn-, it is treated as a memory reference and resolved. This provides backward compatibility with entries that stored knowledge node IDs as their value.
Key-level memory – after all entries are printed, the key-level memory pointer (if any) is resolved once at the end.

Per-entry memory wins. An entry with a memory field set will use that link regardless of whether the key itself also has a memory pointer. The key-level link serves as a fallback that applies to the key as a whole.

Resolving memory links

# Read a key and show its linked memory entry
mx kv get decisions --memory

# Show the last 5 entries plus linked memory
mx kv last decisions --count 5 --memory

# Look up a specific entry and resolve its memory link
mx kv get decisions --id 17 --memory

# Dump everything with all memory links resolved
mx kv dump --memory

Resolution connects to the memory store (SurrealDB). If the store is unavailable or the linked entry has been deleted, a warning is printed to stderr but the KV data is still shown. KV data is always primary – memory links are supplementary context.

NOTE: Memory links are only available on history, list, and state types. String and counter keys do not support --memory.

JSON output

The --json flag outputs results as pretty-printed JSON instead of the human-readable format. It is available on six commands: get, last, search, random, since, and count.

JSON output is designed for scripting and piping to tools like jq. When --json is active, human formatting is skipped and --memory resolution is not performed – the raw kn- ID is included in each entry’s memory field for the caller to resolve if needed.

Entry format

Commands that return entries (get, last, search, random, since) emit a JSON array of entry objects. Each object has this shape:

{
  "index": 42,
  "id": "A3fB",
  "value": "palmtop DSI fix",
  "ts": "2026-05-08T14:30:00+00:00",
  "data": {"status": "active", "tags": ["palmtop", "i915"]},
  "memory": "kn-e1f646aa"
}

index: Numeric sequence index (integer).
id: Stable entry ID (base58 string, without the kv- prefix).
value: The entry’s text value.
ts: Timestamp in ISO-8601 format.
data: Structured data object, omitted when the entry has no data.
memory: Per-entry memory link (kn- ID), omitted when not set.

The data and memory fields are omitted entirely (not null) when they have no value. This keeps the output clean and avoids forcing callers to handle nulls.

Special output shapes

get --json without --id adapts to the key type:

History and list keys: JSON array of all entries (same format as above).
Scalar keys (string, counter, state): {"value": "..."} – the formatted value as a string.

count --json emits a count object:

{"count": 12}

When filtering is active (value substring, --where, or time range), the object includes additional context:

{"count": 5, "total": 12, "latest_ts": "2026-05-08T14:30:00+00:00"}

count: Number of matched entries (always present).
total: Total entries before filtering (present when filtering).
latest_ts: Timestamp of the most recent matched entry (present when filtering).

Piping to `jq`

The primary use case for --json is piping to jq for complex queries that go beyond what --where provides:

# Extract all status values
mx kv last projects --json | jq '.[].data.status'

# Filter by a nested condition
mx kv search projects --where status=active --json \
  | jq 'map(select(.data.tags | contains(["rust"])))'

# Get the count as a bare number
mx kv count shipped --json | jq '.count'

# Build a CSV of shipped items
mx kv last shipped --count 100 --json \
  | jq -r '.[] | [.index, .id, .value, .ts] | @csv'

NOTE: --json is available on get, last, search, random, since, and count. It is not available on push, pop, set, inc, dec, remove, reset, keys, or dump (which already has --format json).

KV Store

Concepts

Data types

Schema files

Schema format

Auto-creating keys

Agent keying

Exit codes

Basic operations

mx kv get <key>

Flags

Examples

mx kv set <key> [args...] [--json <value>]

Flags

Examples

mx kv keys

Examples

Counters

mx kv inc <key>

Flags

Examples

mx kv dec <key>

Flags

Examples

Lists & History

push

mx kv push <key> <value>

Flags

Examples

pop

mx kv pop <key>

Examples

last

mx kv last <key>

Flags

Examples

since

mx kv since <key> <timeref>

Flags

Examples

search

mx kv search <key> [query]

Flags

Examples

count

mx kv count <key> [value]

Flags

Examples

random

mx kv random <key>

Flags

Examples

remove

mx kv remove <key> [value]

Flags

Examples

update

mx kv update <key> [value] --id <spec>

Flags

Examples

migrate

mx kv migrate <key>

Flags

Examples

Time-range queries

Available flags

Interaction with --count

Examples

Relationship to since subcommand

Structured data

Pushing data

Output format

Filtering with --where

Matching semantics

Combining with other filters

Backward compatibility

Entry IDs

Generation

Push output

Dual addressing

`mx kv get <key>`

`mx kv set <key> [args...] [--json <value>]`

`mx kv keys`

`mx kv inc <key>`

`mx kv dec <key>`

`mx kv push <key> <value>`

`mx kv pop <key>`

`mx kv last <key>`

`mx kv since <key> <timeref>`

`mx kv search <key> [query]`

`mx kv count <key> [value]`

`mx kv random <key>`

`mx kv remove <key> [value]`

`mx kv update <key> [value] --id <spec>`

`mx kv migrate <key>`

Interaction with `--count`

Relationship to `since` subcommand

Filtering with `--where`

`mx kv dump`

`mx kv reset <key>`

`mx kv rename <old-key> <new-key>`

Piping to `jq`