Agent State Model (ASM) defines a unified framework for describing, merging, querying, and managing the lifecycle of persistent states in AI agents. It serves as the standard for state definition within Agent Capability Packages (ACPs) as specified in NIP-7.
It extends JSON-Schema 2020-12 with a minimal set of x-asm annotations:
| Area | Annotation | Purpose |
|---|---|---|
| Container kind | container |
object, map, list, log |
| CRDT policy | crdt or per-field x-crdt |
lww_register, rga_text, or_map, … |
| Lifecycle | x-ttl, x-retention, x-compression |
automated ageing, summarisation, compression |
| Visibility | x-visibility |
private, shared, public |
Together with a small JSON-AST query language (ASM-QL) and the standard state.* tool family, ASM allows routers and runtimes to treat conversation history, long-term memory, settings, and arbitrary application data in a unified, verifiable way.
| Need | Current pain | ASM solution |
|---|---|---|
| Multiple data shapes | Only record-like objects in NIP-7 | Adds map, list, log containers |
| Conflict-free merging | Each plugin hand-picks a CRDT | Policy is declared in schema → runtime acts uniformly |
| Unified querying | Ad-hoc filters per capability | ASM-QL: portable, verifiable query AST |
| Memory & chat history | Not standardised | Built-in ConversationLog & MemoryStore models |
| Data isolation | Name clashes across ACPs | Namespace rules under DID hierarchy |
This NIP addresses the need for a standardized and comprehensive state management framework for AI agents. Existing mechanisms (like NIP-7 for record-like objects) are insufficient for handling diverse data shapes, ensuring conflict-free data merging across different agent capabilities (ACPs), providing a unified query language, standardizing common state types like conversation history and memory, and enforcing data isolation. ASM provides these capabilities, leading to more robust, interoperable, and manageable agent states.
| Term | Meaning |
|---|---|
| Container | Top-level state shape (object, map, list, log). |
| CRDT policy | Conflict-resolution algorithm bound to container / field. |
| Memory Scope | Named partition (e.g. sc:note, sc:chat) governed by ASM rules. |
| ASM-QL | JSON serialisable query language evaluated by runtime and optionally verified on-chain. |
Nuwa runtimes MUST create exactly one instance of each core model for every user on first run.
did:nuwa:core:ConversationLog#v1{
"$id": "did:nuwa:core:ConversationLog#v1",
"type": "object",
"x-asm": {
"container": "log",
"crdt": "append_only",
"x-ttl": "P14D",
"x-compression": "br",
"x-visibility": "private"
},
"properties": {
"entries": {
"type": "array",
"x-crdt": "log_rga",
"items": {
"type": "object",
"properties": {
"id": {"type":"string","format":"uuid"},
"role": {"type":"string","enum":["user","assistant"]},
"content": {"type":"string"},
"timestamp": {"type":"string","format":"date-time"}
},
"required":["id","role","content","timestamp"]
}
}
},
"required": ["entries"]
}
Note:
"container": "log": Specifies that this is an append-only event stream."crdt": "append_only": Conflict-free replicated data type for appending entries."x-ttl": "P14D": Entries older than 14 days may be deleted. This value can be configured."x-compression": "br": Data may be stored using Brotli compression, chosen for its balance of compression ratio and speed."x-visibility": "private": Access is restricted to the owner.did:nuwa:core:MemoryStore#v1{
"$id": "did:nuwa:core:MemoryStore#v1",
"type": "object",
"x-asm": {
"container": "map",
"keyType": "string",
"valueRef": "#/definitions/MemoryItem",
"x-retention": {
"window": "P90D",
"strategy": "evict_low_importance"
},
"x-visibility": "private"
},
"properties": {
"items": {
"type": "object",
"additionalProperties": { "$ref": "#/definitions/MemoryItem" }
}
},
"definitions": {
"MemoryItem": {
"type": "object",
"properties": {
"value": {"type":"string"},
"importance":{"type":"number"},
"createdAt": {"type":"string","format":"date-time"}
},
"required":["value","importance","createdAt"]
}
}
}
Note:
"container": "map": Specifies that this is a key-value map."x-retention": {"window": "P90D", "strategy": "evict_low_importance"}: Retains data for 90 days and evicts low-importance items. “Low importance” is determined by the importance field."x-visibility": "private": Access is restricted to the owner.did:nuwa:core:AgentSettings#v1{
"$id": "did:nuwa:core:AgentSettings#v1",
"type": "object",
"x-asm": {
"container": "object",
"x-visibility": "private"
},
"properties": {
"language": {"type":"string","enum":["zh","en","ja","es"]},
"tone": {"type":"string","enum":["casual","formal","kids"]},
"theme": {"type":"string","enum":["light","dark"]},
"notifOpt": {"type":"boolean"}
},
"required": ["language"]
}
Note:
"container": "object": Specifies that this is a structured object."x-visibility": "private": Access is restricted to the owner."required": ["language"]: Language is mandatory to ensure proper localization.| Kind | Typical usage | Default CRDT |
|---|---|---|
object |
Fixed structured record | per-field mix |
map |
Arbitrary key → value | OR-Map |
list |
Ordered sequence | RGA / Y-list |
log |
Append-only event stream | Monotonic vector |
The canonical x-crdt keywords are:
lww_register • mv_register • rga_text • grow_only_set • or_map • counter • flag • log_rga
| Annotation | Format | Semantics |
|---|---|---|
x-ttl |
ISO-8601 duration | Hard expiry; entries beyond TTL MAY be deleted. |
x-retention |
{window,strategy} |
Sliding window & summarisation rules. |
x-compression |
"br" / "zstd" / "gzip" |
Runtime MAY store snapshots compressed. |
x-visibility |
private / shared / public |
Router MUST enforce access control. |
Example AST:
{
"select": ["id","title"],
"from": "did:nuwa:state:note#v1",
"where": {"tags":{"$contains":"meeting"}},
"order": [{"field":"updatedAt","direction":"desc"}],
"limit": 20,
"cursor": "opaque-base64"
}
Runtimes MAY translate to SQL, RocksDB iterators, or CR-SQLite views. Provers MAY embed the same AST in a Merkle proof for verifiable reads.
state.* Tool Semantics| Tool | Required params | Behaviour |
|---|---|---|
state.create |
schema_uri, object |
Validate via ASM, emit create-op |
state.update |
schema_uri, id, patch |
JSON-Patch / $inc, $push diff |
state.query |
query (ASM-QL) |
Stream results or single shot |
state.delete |
schema_uri, id, mode |
Tombstone or hard delete |
All ops are persisted into the NIP-4 CRDT Event Log; snapshots anchored on-chain by NIP-13.
| Namespace | Pattern | Purpose |
|---|---|---|
| core | did:nuwa:core:<Model>#<ver> |
Platform-built-in |
| cap | did:nuwa:cap:<cap_id>:state:<Name>#<ver> |
Each ACP’s private data |
| app | did:nuwa:app:<app_name>:state:<Name>#<ver> |
Multi-capability application |
| user | did:nuwa:user:<did_suffix>:state:<Name>#<ver> |
Experimental / ad-hoc |
$id MUST resolve via local cache → Registry → DID resolver.memory_scope ↔ distinct CRDT log.x-compression set, runtime MAY store chunks compressed and anchor CAR hash.The Agent State Model (ASM) defined in this NIP is the designated framework for specifying the schema section within an Agent Capability Package (.acp.yaml file) as detailed in NIP-7. Capabilities should define their state objects using ASM-compliant JSON Schemas, leveraging the x-asm annotations for CRDT policies, lifecycle management, and visibility controls. The schema_uri used in state.* tool calls within an ACP context will refer to the $id of such an ASM-compliant schema.
The design choices for ASM prioritize extending familiar standards like JSON-Schema with minimal, targeted annotations (x-asm) to reduce the learning curve and promote adoption.
x-asm annotations provide the necessary extensions for state-specific concerns like CRDT policies, lifecycle, and visibility without reinventing core schema definition.object, map, list, log) cover the most common data structures needed for agent state, offering a balance between flexibility and specialized handling (e.g., log for append-only streams).ConversationLog, MemoryStore, and AgentSettings address common agent needs out-of-the-box, promoting consistency across the ecosystem.Test cases are mandatory for this NIP and will be provided in a separate document or repository. They will cover:
x-asm annotations.state.* tool semantics and their interaction with the CRDT event log.A reference implementation of an ASM-compliant runtime module is planned. This will include:
state.* tool family.storage.large permission. Runtimes must enforce configured size limits for individual state entries and overall state storage per agent/user to prevent denial-of-service attacks.x-visibility enforced via capability tokens (ZCAP-LD). Runtimes must rigorously enforce these visibility rules to prevent unauthorized data access or leakage between private, shared, and public scopes.Copyright and related rights waived via CC0.