CLI Reference: Memory
Commands for persistent agent memory (key-value store with versioning).
Each agent has its own persistent memory namespace. Unlike the blackboard (which is daemon-global and shared), memory is private to an agent and survives across restarts. See Persistent Memory for background.
ash memory read
Read a key from an agent's persistent memory.
ash memory read <agent-id> <key>
Returns the current value, version number, and optional expiry. Returns an error if the key does not exist.
Example:
ash memory read <agent-id> state/current-phase
ash memory write
Write a key to persistent memory.
ash memory write <agent-id> <key> <value-json> [--ttl <seconds>]
| Argument/Flag | Description |
|---|---|
agent-id | Agent ID (must have memory.write) |
key | Arbitrary string key |
value-json | JSON value to store |
--ttl | Optional time-to-live in seconds |
Example:
ash memory write <agent-id> progress/items-processed 42
ash memory write <agent-id> cache/result '"done"' --ttl 86400
ash memory cas
Compare-and-swap: update a key atomically only if it is at the expected version.
ash memory cas <agent-id> <key> <expected-version> <value-json> [--ttl <seconds>]
| Argument | Description |
|---|---|
expected-version | Integer version number; the write is applied only if the current version matches |
value-json | New JSON value |
Use version 0 to create a key only if it does not exist.
Example:
# Increment safely: read version first, then CAS
ash memory read <agent-id> counter # → value: 5, version: 3
ash memory cas <agent-id> counter 3 6 # → succeeds if still at version 3
ash memory delete
Delete a key from persistent memory.
ash memory delete <agent-id> <key>
ash memory list
List keys in an agent's persistent memory matching an optional glob pattern.
ash memory list <agent-id> [--pattern <glob>]
Examples:
ash memory list <agent-id>
ash memory list <agent-id> --pattern "progress/*"