ShadowGraph

Official

Overview Schema Source Related Servers Discussions Admin

shadowgraph_remember

Destructive

Add or reconcile one scoped memory by identity tuple, or apply a batch ADD/UPDATE/DELETE/NOOP plan; identical content is a no-op, updates preserve history, and deletes invalidate.

Instructions

Add or reconcile one scoped memory, or apply an ADD/UPDATE/DELETE/NOOP plan, by identity tuple. Use shadowgraph_record_decision for a choice, shadowgraph_record_fact for an observation, shadowgraph_recall to read memory back. Identical content is a NOOP, new content supersedes and keeps history, DELETE invalidates; every call commits a revision.

Input Schema

Name	Required	Description
`key`	No	Stable caller-chosen name within this scope and type, such as hotel-style. Reusing it reconciles that memory rather than adding a second one.
`tags`	No	Free-form labels stored with the memory. Part of the compared content, so changing them produces a new version.
`text`	No	The memory content itself. Stored verbatim, searched as content, and compared to decide ADD, UPDATE, or NOOP.
`actor`	No	Who performed this write, such as an agent or person name. Stored for audit; never used to grant trust.
`scope`	No	Scope selector. Omitted or partial fields mean explicit nulls, not "any": identity is the exact (project, userId, agentId, runId, memoryType, key) tuple, so a run-scoped memory never leaks into a user-only read.
`client`	No	Which client software performed this write, such as the host application name.
`project`	No	Owning project; required unless originId is set, else the write is refused.
`validTo`	No	ISO 8601 instant after which it stops being true, or null for open-ended. Must be later than validFrom.
`metadata`	No	Caller-owned JSON object kept with the memory. Part of the compared content, so changing it produces a new version.
`originId`	No	Capture-origin id; with no project the record belongs to it alone.
`embedding`	No	Caller-supplied vector for this text. Omit to use the configured embedding provider; with no provider the record is still stored and recall reports semantic.available=false instead of renaming lexical overlap as semantic.
`sessionId`	No	Caller-owned identifier that groups related writes in the audit trail.
`validFrom`	No	ISO 8601 instant from which this memory is true in the modeled world. Defaults to the write time. Writes for one identity must arrive in non-decreasing validFrom order.
`memoryType`	No	Which kind of memory this is, and part of its identity. preference and profile are durable user facts, goal a desired state, instruction an operating constraint, procedure reusable steps, episode a recallable event, note general knowledge.
`operations`	No	A batch plan. Supply this instead of a single memory, typically from an extraction step. Every operation is validated before the first one is applied, so a malformed late operation cannot leave a half-applied batch.
`sourceClass`	No	Claimed origin, never proof: agent_claimed (the default), tool_observed, human_confirmed, or production_verified. It weights confidence only. An unrecognised label downgrades to agent_claimed, kept verbatim in sourceRaw.
`idempotencyKey`	No	Retry identity within the project or origin and operation (also scope/type/key for memory). Reuse it to recover the original canonical ID; this key is never an entity ID.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedv0.42.1Oct 25, 2026

addedInput schema / description

Added value: +"Every envelope and operation rejects a supplied id, including retries, DELETE and NOOP. Memory is selected by its scoped identity tuple; canonical IDs are generated and returned."

addedInput schema / not

Added value: +{
+  "required": [
+    "id"
+  ]
+}

addedInput schema / properties / idempotencyKey

Added value: +{
+  "description": "Retry identity within the project or origin and operation (also scope/type/key for memory). Reuse it to recover the original canonical ID; this key is never an entity ID.",
+  "maxLength": 200,
+  "type": "string"
+}

addedInput schema / properties / operations / items / not
```
Added value: +{
+  "required": [
+    "id"
+  ]
+}
```

addedInput schema / properties / originId

Added value: +{
+  "description": "Capture-origin id; with no project the record belongs to it alone.",
+  "type": "string"
+}

changedInput schema / properties / project / description

Previous value: -"Project namespace. Defaults to \"default\"; an empty string is rejected."New value: +"Owning project; required unless originId is set, else the write is refused."

changedOutput schema / anyOf

Previous value: -[
-  {
-    "properties": {
-      "indexUpdated": {
-        "description": "Present when identical content arrived with a different embedding: the index was refreshed without minting a new version.",
-        "type": "boolean"
-      },
-      "memory": {
-        "description": "A stored scoped memory version.",
-        "properties": {
-          "actor": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "Who performed the write."
-          },
-          "client": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "Which client performed the write."
-          },
-          "createdAt": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "ISO 8601 creation time."
-          },
-          "embedding": {
-            "anyOf": [
-              {
-                "type": "array"
-              },
-              {
-                "type": "object"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "The stored vector, or null when none was supplied and no provider was configured."
-          },
-          "id": {
-            "description": "Stable entity identifier.",
-            "type": "string"
-          },
-          "key": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "Caller-chosen name within the scope and type."
-          },
-          "kind": {
-            "description": "Entity kind: decision, attempt, memory, fact, relation, review, or alternative.",
-            "type": "string"
-          },
-          "memoryType": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "preference, profile, goal, instruction, procedure, episode, or note."
-          },
-          "metadata": {
-            "description": "Caller-owned JSON stored with the memory.",
-            "type": "object"
-          },
-          "project": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "Project namespace; records imported from a schema that predates projects may carry null."
-          },
-          "schemaVersion": {
-            "description": "Storage schema version this entity was written under. A value above the build’s own version is preserved rather than downgraded.",
-            "type": "integer"
-          },
-          "scope": {
-            "description": "The userId, agentId, and runId this memory is scoped to; each is a string or null.",
-            "type": "object"
-          },
-          "sessionId": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "Session identifier recorded with the write."
-          },
-          "sourceClass": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "Claimed origin class recorded with the write. A claim, never proof."
-          },
-          "sourceRaw": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "The original origin label when it differed from sourceClass. Audit only; never evidence."
-          },
-          "status": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "active, superseded, or invalidated."
-          },
-          "supersededBy": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "Identifier of the version that replaced this one."
-          },
-          "supersedes": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "Identifier of the version this one replaced."
-          },
-          "tags": {
-            "description": "Labels stored with the memory.",
-            "type": "array"
-          },
-          "temporal": {
-            "description": "Bi-temporal window: validFrom, validTo, recordedAt, invalidatedAt.",
-            "type": "object"
-          },
-          "text": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "The memory content."
-          },
-          "updatedAt": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "ISO 8601 time of the last change."
-          },
-          "verificationStatus": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "Always unverified for memories."
-          },
-          "version": {
-            "anyOf": [
-              {
-                "type": "integer"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "Version number within this identity, incrementing on each superseding write."
-          }
-        },
-        "required": [
-          "id",
-          "kind"
-        ],
-        "type": "object"
-      },
-      "operation": {
-        "description": "ADD when no active memory existed, UPDATE when one was superseded, NOOP when content was identical.",
-        "enum": [
-          "ADD",
-          "UPDATE",
-          "NOOP"
-        ],
-        "type": "string"
-      },
-      "previous": {
-        "description": "A stored scoped memory version.",
-        "properties": {
-          "actor": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "Who performed the write."
-          },
-          "client": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "Which client performed the write."
-          },
-          "createdAt": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "ISO 8601 creation time."
-          },
-          "embedding": {
-            "anyOf": [
-              {
-                "type": "array"
-              },
-              {
-                "type": "object"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "The stored vector, or null when none was supplied and no provider was configured."
-          },
-          "id": {
-            "description": "Stable entity identifier.",
-            "type": "string"
-          },
-          "key": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "Caller-chosen name within the scope and type."
-          },
-          "kind": {
-            "description": "Entity kind: decision, attempt, memory, fact, relation, review, or alternative.",
-            "type": "string"
-          },
-          "memoryType": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "preference, profile, goal, instruction, procedure, episode, or note."
-          },
-          "metadata": {
-            "description": "Caller-owned JSON stored with the memory.",
-            "type": "object"
-          },
-          "project": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "Project namespace; records imported from a schema that predates projects may carry null."
-          },
-          "schemaVersion": {
-            "description": "Storage schema version this entity was written under. A value above the build’s own version is preserved rather than downgraded.",
-            "type": "integer"
-          },
-          "scope": {
-            "description": "The userId, agentId, and runId this memory is scoped to; each is a string or null.",
-            "type": "object"
-          },
-          "sessionId": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "Session identifier recorded with the write."
-          },
-          "sourceClass": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "Claimed origin class recorded with the write. A claim, never proof."
-          },
-          "sourceRaw": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "The original origin label when it differed from sourceClass. Audit only; never evidence."
-          },
-          "status": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "active, superseded, or invalidated."
-          },
-          "supersededBy": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "Identifier of the version that replaced this one."
-          },
-          "supersedes": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "Identifier of the version this one replaced."
-          },
-          "tags": {
-            "description": "Labels stored with the memory.",
-            "type": "array"
-          },
-          "temporal": {
-            "description": "Bi-temporal window: validFrom, validTo, recordedAt, invalidatedAt.",
-            "type": "object"
-          },
-          "text": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "The memory content."
-          },
-          "updatedAt": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "ISO 8601 time of the last change."
-          },
-          "verificationStatus": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "Always unverified for memories."
-          },
-          "version": {
-            "anyOf": [
-              {
-                "type": "integer"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "Version number within this identity, incrementing on each superseding write."
-          }
-        },
-        "required": [
-          "id",
-          "kind"
-        ],
-        "type": "object"
-      }
-    },
-    "required": [
-      "operation",
-      "memory"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "completeness": {
-        "description": "Plan accounting. This is not the paginated completeness envelope.",
-        "properties": {
-          "applied": {
-            "description": "Results produced, one per submitted operation.",
-            "minimum": 0,
-            "type": "integer"
-          },
-          "complete": {
-            "description": "Always true: a plan is applied in full or rejected in full.",
-            "type": "boolean"
-          },
-          "requested": {
-            "description": "Operations submitted.",
-            "minimum": 0,
-            "type": "integer"
-          }
-        },
-        "required": [
-          "complete",
-          "requested",
-          "applied"
-        ],
-        "type": "object"
-      },
-      "results": {
-        "description": "One result per submitted operation, in order.",
-        "items": {
-          "properties": {
-            "indexUpdated": {
-              "description": "Present when only the embedding was refreshed.",
-              "type": "boolean"
-            },
-            "memory": {
-              "anyOf": [
-                {
-                  "description": "A stored scoped memory version.",
-                  "properties": {
-                    "actor": {
-                      "anyOf": [
-                        {
-                          "type": "string"
-                        },
-                        {
-                          "type": "null"
-                        }
-                      ],
-                      "description": "Who performed the write."
-                    },
-                    "client": {
-                      "anyOf": [
-                        {
-                          "type": "string"
-                        },
-                        {
-                          "type": "null"
-                        }
-                      ],
-                      "description": "Which client performed the write."
-                    },
-                    "createdAt": {
-                      "anyOf": [
-                        {
-                          "type": "string"
-                        },
-                        {
-                          "type": "null"
-                        }
-                      ],
-                      "description": "ISO 8601 creation time."
-                    },
-                    "embedding": {
-                      "anyOf": [
-                        {
-                          "type": "array"
-                        },
-                        {
-                          "type": "object"
-                        },
-                        {
-                          "type": "null"
-                        }
-                      ],
-                      "description": "The stored vector, or null when none was supplied and no provider was configured."
-                    },
-                    "id": {
-                      "description": "Stable entity identifier.",
-                      "type": "string"
-                    },
-                    "key": {
-                      "anyOf": [
-                        {
-                          "type": "string"
-                        },
-                        {
-                          "type": "null"
-                        }
-                      ],
-                      "description": "Caller-chosen name within the scope and type."
-                    },
-                    "kind": {
-                      "description": "Entity kind: decision, attempt, memory, fact, relation, review, or alternative.",
-                      "type": "string"
-                    },
-                    "memoryType": {
-                      "anyOf": [
-                        {
-                          "type": "string"
-                        },
-                        {
-                          "type": "null"
-                        }
-                      ],
-                      "description": "preference, profile, goal, instruction, procedure, episode, or note."
-                    },
-                    "metadata": {
-                      "description": "Caller-owned JSON stored with the memory.",
-                      "type": "object"
-                    },
-                    "project": {
-                      "anyOf": [
-                        {
-                          "type": "string"
-                        },
-                        {
-                          "type": "null"
-                        }
-                      ],
-                      "description": "Project namespace; records imported from a schema that predates projects may carry null."
-                    },
-                    "schemaVersion": {
-                      "description": "Storage schema version this entity was written under. A value above the build’s own version is preserved rather than downgraded.",
-                      "type": "integer"
-                    },
-                    "scope": {
-                      "description": "The userId, agentId, and runId this memory is scoped to; each is a string or null.",
-                      "type": "object"
-                    },
-                    "sessionId": {
-                      "anyOf": [
-                        {
-                          "type": "string"
-                        },
-                        {
-                          "type": "null"
-                        }
-                      ],
-                      "description": "Session identifier recorded with the write."
-                    },
-                    "sourceClass": {
-                      "anyOf": [
-                        {
-                          "type": "string"
-                        },
-                        {
-                          "type": "null"
-                        }
-                      ],
-                      "description": "Claimed origin class recorded with the write. A claim, never proof."
-                    },
-                    "sourceRaw": {
-                      "anyOf": [
-                        {
-                          "type": "string"
-                        },
-                        {
-                          "type": "null"
-                        }
-                      ],
-                      "description": "The original origin label when it differed from sourceClass. Audit only; never evidence."
-                    },
-                    "status": {
-                      "anyOf": [
-                        {
-                          "type": "string"
-                        },
-                        {
-                          "type": "null"
-                        }
-                      ],
-                      "description": "active, superseded, or invalidated."
-                    },
-                    "supersededBy": {
-                      "anyOf": [
-                        {
-                          "type": "string"
-                        },
-                        {
-                          "type": "null"
-                        }
-                      ],
-                      "description": "Identifier of the version that replaced this one."
-                    },
-                    "supersedes": {
-                      "anyOf": [
-                        {
-                          "type": "string"
-                        },
-                        {
-                          "type": "null"
-                        }
-                      ],
-                      "description": "Identifier of the version this one replaced."
-                    },
-                    "tags": {
-                      "description": "Labels stored with the memory.",
-                      "type": "array"
-                    },
-                    "temporal": {
-                      "description": "Bi-temporal window: validFrom, validTo, recordedAt, invalidatedAt.",
-                      "type": "object"
-                    },
-                    "text": {
-                      "anyOf": [
-                        {
-                          "type": "string"
-                        },
-                        {
-                          "type": "null"
-                        }
-                      ],
-                      "description": "The memory content."
-                    },
-                    "updatedAt": {
-                      "anyOf": [
-                        {
-                          "type": "string"
-                        },
-                        {
-                          "type": "null"
-                        }
-                      ],
-                      "description": "ISO 8601 time of the last change."
-                    },
-                    "verificationStatus": {
-                      "anyOf": [
-                        {
-                          "type": "string"
-                        },
-                        {
-                          "type": "null"
-                        }
-                      ],
-                      "description": "Always unverified for memories."
-                    },
-                    "version": {
-                      "anyOf": [
-                        {
-                          "type": "integer"
-                        },
-                        {
-                          "type": "null"
-                        }
-                      ],
-                      "description": "Version number within this identity, incrementing on each superseding write."
-                    }
-                  },
-                  "required": [
-                    "id",
-                    "kind"
-                  ],
-                  "type": "object"
-                },
-                {
-                  "type": "null"
-                }
-              ],
-              "description": "The resulting memory, or null for a NOOP on an identity that has no memory."
-            },
-            "operation": {
-              "description": "What was actually applied, which may differ from the requested action when content already matched.",
-              "enum": [
-                "ADD",
-                "UPDATE",
-                "DELETE",
-                "NOOP"
-              ],
-              "type": "string"
-            },
-            "previous": {
-              "description": "A stored scoped memory version.",
-              "properties": {
-                "actor": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ],
-                  "description": "Who performed the write."
-                },
-                "client": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ],
-                  "description": "Which client performed the write."
-                },
-                "createdAt": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ],
-                  "description": "ISO 8601 creation time."
-                },
-                "embedding": {
-                  "anyOf": [
-                    {
-                      "type": "array"
-                    },
-                    {
-                      "type": "object"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ],
-                  "description": "The stored vector, or null when none was supplied and no provider was configured."
-                },
-                "id": {
-                  "description": "Stable entity identifier.",
-                  "type": "string"
-                },
-                "key": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ],
-                  "description": "Caller-chosen name within the scope and type."
-                },
-                "kind": {
-                  "description": "Entity kind: decision, attempt, memory, fact, relation, review, or alternative.",
-                  "type": "string"
-                },
-                "memoryType": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ],
-                  "description": "preference, profile, goal, instruction, procedure, episode, or note."
-                },
-                "metadata": {
-                  "description": "Caller-owned JSON stored with the memory.",
-                  "type": "object"
-                },
-                "project": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ],
-                  "description": "Project namespace; records imported from a schema that predates projects may carry null."
-                },
-                "schemaVersion": {
-                  "description": "Storage schema version this entity was written under. A value above the build’s own version is preserved rather than downgraded.",
-                  "type": "integer"
-                },
-                "scope": {
-                  "description": "The userId, agentId, and runId this memory is scoped to; each is a string or null.",
-                  "type": "object"
-                },
-                "sessionId": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ],
-                  "description": "Session identifier recorded with the write."
-                },
-                "sourceClass": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ],
-                  "description": "Claimed origin class recorded with the write. A claim, never proof."
-                },
-                "sourceRaw": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ],
-                  "description": "The original origin label when it differed from sourceClass. Audit only; never evidence."
-                },
-                "status": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ],
-                  "description": "active, superseded, or invalidated."
-                },
-                "supersededBy": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ],
-                  "description": "Identifier of the version that replaced this one."
-                },
-                "supersedes": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ],
-                  "description": "Identifier of the version this one replaced."
-                },
-                "tags": {
-                  "description": "Labels stored with the memory.",
-                  "type": "array"
-                },
-                "temporal": {
-                  "description": "Bi-temporal window: validFrom, validTo, recordedAt, invalidatedAt.",
-                  "type": "object"
-                },
-                "text": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ],
-                  "description": "The memory content."
-                },
-                "updatedAt": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ],
-                  "description": "ISO 8601 time of the last change."
-                },
-                "verificationStatus": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ],
-                  "description": "Always unverified for memories."
-                },
-                "version": {
-                  "anyOf": [
-                    {
-                      "type": "integer"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ],
-                  "description": "Version number within this identity, incrementing on each superseding write."
-                }
-              },
-              "required": [
-                "id",
-                "kind"
-              ],
-              "type": "object"
-            }
-          },
-          "required": [
-            "operation",
-            "memory"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      }
-    },
-    "required": [
-      "results",
-      "completeness"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "properties": {
+      "indexUpdated": {
+        "description": "Present when identical content arrived with a different embedding: the index was refreshed without minting a new version.",
+        "type": "boolean"
+      },
+      "memory": {
+        "description": "A stored scoped memory version.",
+        "properties": {
+          "actor": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Who performed the write."
+          },
+          "client": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Which client performed the write."
+          },
+          "createdAt": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "ISO 8601 creation time."
+          },
+          "embedding": {
+            "anyOf": [
+              {
+                "type": "array"
+              },
+              {
+                "type": "object"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The stored vector, or null when none was supplied and no provider was configured."
+          },
+          "id": {
+            "description": "Stable entity identifier.",
+            "type": "string"
+          },
+          "key": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Caller-chosen name within the scope and type."
+          },
+          "kind": {
+            "description": "Entity kind: decision, attempt, memory, fact, relation, review, or alternative.",
+            "type": "string"
+          },
+          "memoryType": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "preference, profile, goal, instruction, procedure, episode, or note."
+          },
+          "metadata": {
+            "description": "Caller-owned JSON stored with the memory.",
+            "type": "object"
+          },
+          "project": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Project namespace; null for an unattributed record or one imported from before projects."
+          },
+          "schemaVersion": {
+            "description": "Storage schema version this entity was written under. A value above the build’s own version is preserved rather than downgraded.",
+            "type": "integer"
+          },
+          "scope": {
+            "description": "The userId, agentId, and runId this memory is scoped to; each is a string or null.",
+            "type": "object"
+          },
+          "sessionId": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Session identifier recorded with the write."
+          },
+          "sourceClass": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Claimed origin class recorded with the write. A claim, never proof."
+          },
+          "sourceRaw": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The original origin label when it differed from sourceClass. Audit only; never evidence."
+          },
+          "status": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "active, superseded, or invalidated."
+          },
+          "supersededBy": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Identifier of the version that replaced this one."
+          },
+          "supersedes": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Identifier of the version this one replaced."
+          },
+          "tags": {
+            "description": "Labels stored with the memory.",
+            "type": "array"
+          },
+          "temporal": {
+            "description": "Bi-temporal window: validFrom, validTo, recordedAt, invalidatedAt.",
+            "type": "object"
+          },
+          "text": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The memory content."
+          },
+          "updatedAt": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "ISO 8601 time of the last change."
+          },
+          "verificationStatus": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Always unverified for memories."
+          },
+          "version": {
+            "anyOf": [
+              {
+                "type": "integer"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Version number within this identity, incrementing on each superseding write."
+          }
+        },
+        "required": [
+          "id",
+          "kind"
+        ],
+        "type": "object"
+      },
+      "operation": {
+        "description": "ADD when no active memory existed, UPDATE when one was superseded, NOOP when content was identical.",
+        "enum": [
+          "ADD",
+          "UPDATE",
+          "NOOP"
+        ],
+        "type": "string"
+      },
+      "previous": {
+        "description": "A stored scoped memory version.",
+        "properties": {
+          "actor": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Who performed the write."
+          },
+          "client": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Which client performed the write."
+          },
+          "createdAt": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "ISO 8601 creation time."
+          },
+          "embedding": {
+            "anyOf": [
+              {
+                "type": "array"
+              },
+              {
+                "type": "object"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The stored vector, or null when none was supplied and no provider was configured."
+          },
+          "id": {
+            "description": "Stable entity identifier.",
+            "type": "string"
+          },
+          "key": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Caller-chosen name within the scope and type."
+          },
+          "kind": {
+            "description": "Entity kind: decision, attempt, memory, fact, relation, review, or alternative.",
+            "type": "string"
+          },
+          "memoryType": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "preference, profile, goal, instruction, procedure, episode, or note."
+          },
+          "metadata": {
+            "description": "Caller-owned JSON stored with the memory.",
+            "type": "object"
+          },
+          "project": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Project namespace; null for an unattributed record or one imported from before projects."
+          },
+          "schemaVersion": {
+            "description": "Storage schema version this entity was written under. A value above the build’s own version is preserved rather than downgraded.",
+            "type": "integer"
+          },
+          "scope": {
+            "description": "The userId, agentId, and runId this memory is scoped to; each is a string or null.",
+            "type": "object"
+          },
+          "sessionId": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Session identifier recorded with the write."
+          },
+          "sourceClass": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Claimed origin class recorded with the write. A claim, never proof."
+          },
+          "sourceRaw": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The original origin label when it differed from sourceClass. Audit only; never evidence."
+          },
+          "status": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "active, superseded, or invalidated."
+          },
+          "supersededBy": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Identifier of the version that replaced this one."
+          },
+          "supersedes": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Identifier of the version this one replaced."
+          },
+          "tags": {
+            "description": "Labels stored with the memory.",
+            "type": "array"
+          },
+          "temporal": {
+            "description": "Bi-temporal window: validFrom, validTo, recordedAt, invalidatedAt.",
+            "type": "object"
+          },
+          "text": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The memory content."
+          },
+          "updatedAt": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "ISO 8601 time of the last change."
+          },
+          "verificationStatus": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Always unverified for memories."
+          },
+          "version": {
+            "anyOf": [
+              {
+                "type": "integer"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Version number within this identity, incrementing on each superseding write."
+          }
+        },
+        "required": [
+          "id",
+          "kind"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "operation",
+      "memory"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "completeness": {
+        "description": "Plan accounting. This is not the paginated completeness envelope.",
+        "properties": {
+          "applied": {
+            "description": "Results produced, one per submitted operation.",
+            "minimum": 0,
+            "type": "integer"
+          },
+          "complete": {
+            "description": "Always true: a plan is applied in full or rejected in full.",
+            "type": "boolean"
+          },
+          "requested": {
+            "description": "Operations submitted.",
+            "minimum": 0,
+            "type": "integer"
+          }
+        },
+        "required": [
+          "complete",
+          "requested",
+          "applied"
+        ],
+        "type": "object"
+      },
+      "results": {
+        "description": "One result per submitted operation, in order.",
+        "items": {
+          "properties": {
+            "indexUpdated": {
+              "description": "Present when only the embedding was refreshed.",
+              "type": "boolean"
+            },
+            "memory": {
+              "anyOf": [
+                {
+                  "description": "A stored scoped memory version.",
+                  "properties": {
+                    "actor": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "Who performed the write."
+                    },
+                    "client": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "Which client performed the write."
+                    },
+                    "createdAt": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "ISO 8601 creation time."
+                    },
+                    "embedding": {
+                      "anyOf": [
+                        {
+                          "type": "array"
+                        },
+                        {
+                          "type": "object"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "The stored vector, or null when none was supplied and no provider was configured."
+                    },
+                    "id": {
+                      "description": "Stable entity identifier.",
+                      "type": "string"
+                    },
+                    "key": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "Caller-chosen name within the scope and type."
+                    },
+                    "kind": {
+                      "description": "Entity kind: decision, attempt, memory, fact, relation, review, or alternative.",
+                      "type": "string"
+                    },
+                    "memoryType": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "preference, profile, goal, instruction, procedure, episode, or note."
+                    },
+                    "metadata": {
+                      "description": "Caller-owned JSON stored with the memory.",
+                      "type": "object"
+                    },
+                    "project": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "Project namespace; null for an unattributed record or one imported from before projects."
+                    },
+                    "schemaVersion": {
+                      "description": "Storage schema version this entity was written under. A value above the build’s own version is preserved rather than downgraded.",
+                      "type": "integer"
+                    },
+                    "scope": {
+                      "description": "The userId, agentId, and runId this memory is scoped to; each is a string or null.",
+                      "type": "object"
+                    },
+                    "sessionId": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "Session identifier recorded with the write."
+                    },
+                    "sourceClass": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "Claimed origin class recorded with the write. A claim, never proof."
+                    },
+                    "sourceRaw": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "The original origin label when it differed from sourceClass. Audit only; never evidence."
+                    },
+                    "status": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "active, superseded, or invalidated."
+                    },
+                    "supersededBy": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "Identifier of the version that replaced this one."
+                    },
+                    "supersedes": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "Identifier of the version this one replaced."
+                    },
+                    "tags": {
+                      "description": "Labels stored with the memory.",
+                      "type": "array"
+                    },
+                    "temporal": {
+                      "description": "Bi-temporal window: validFrom, validTo, recordedAt, invalidatedAt.",
+                      "type": "object"
+                    },
+                    "text": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "The memory content."
+                    },
+                    "updatedAt": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "ISO 8601 time of the last change."
+                    },
+                    "verificationStatus": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "Always unverified for memories."
+                    },
+                    "version": {
+                      "anyOf": [
+                        {
+                          "type": "integer"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "Version number within this identity, incrementing on each superseding write."
+                    }
+                  },
+                  "required": [
+                    "id",
+                    "kind"
+                  ],
+                  "type": "object"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "The resulting memory, or null for a NOOP on an identity that has no memory."
+            },
+            "operation": {
+              "description": "What was actually applied, which may differ from the requested action when content already matched.",
+              "enum": [
+                "ADD",
+                "UPDATE",
+                "DELETE",
+                "NOOP"
+              ],
+              "type": "string"
+            },
+            "previous": {
+              "description": "A stored scoped memory version.",
+              "properties": {
+                "actor": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "Who performed the write."
+                },
+                "client": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "Which client performed the write."
+                },
+                "createdAt": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "ISO 8601 creation time."
+                },
+                "embedding": {
+                  "anyOf": [
+                    {
+                      "type": "array"
+                    },
+                    {
+                      "type": "object"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "The stored vector, or null when none was supplied and no provider was configured."
+                },
+                "id": {
+                  "description": "Stable entity identifier.",
+                  "type": "string"
+                },
+                "key": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "Caller-chosen name within the scope and type."
+                },
+                "kind": {
+                  "description": "Entity kind: decision, attempt, memory, fact, relation, review, or alternative.",
+                  "type": "string"
+                },
+                "memoryType": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "preference, profile, goal, instruction, procedure, episode, or note."
+                },
+                "metadata": {
+                  "description": "Caller-owned JSON stored with the memory.",
+                  "type": "object"
+                },
+                "project": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "Project namespace; null for an unattributed record or one imported from before projects."
+                },
+                "schemaVersion": {
+                  "description": "Storage schema version this entity was written under. A value above the build’s own version is preserved rather than downgraded.",
+                  "type": "integer"
+                },
+                "scope": {
+                  "description": "The userId, agentId, and runId this memory is scoped to; each is a string or null.",
+                  "type": "object"
+                },
+                "sessionId": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "Session identifier recorded with the write."
+                },
+                "sourceClass": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "Claimed origin class recorded with the write. A claim, never proof."
+                },
+                "sourceRaw": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "The original origin label when it differed from sourceClass. Audit only; never evidence."
+                },
+                "status": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "active, superseded, or invalidated."
+                },
+                "supersededBy": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "Identifier of the version that replaced this one."
+                },
+                "supersedes": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "Identifier of the version this one replaced."
+                },
+                "tags": {
+                  "description": "Labels stored with the memory.",
+                  "type": "array"
+                },
+                "temporal": {
+                  "description": "Bi-temporal window: validFrom, validTo, recordedAt, invalidatedAt.",
+                  "type": "object"
+                },
+                "text": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "The memory content."
+                },
+                "updatedAt": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "ISO 8601 time of the last change."
+                },
+                "verificationStatus": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "Always unverified for memories."
+                },
+                "version": {
+                  "anyOf": [
+                    {
+                      "type": "integer"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "Version number within this identity, incrementing on each superseding write."
+                }
+              },
+              "required": [
+                "id",
+                "kind"
+              ],
+              "type": "object"
+            }
+          },
+          "required": [
+            "operation",
+            "memory"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      }
+    },
+    "required": [
+      "results",
+      "completeness"
+    ],
+    "type": "object"
+  }
+]

Changed32 schema fields changedv0.40.1Sep 3, 2026

changedInput schema / properties / actor / description

Previous value: -"Who performed this write, e.g. an agent name."New value: +"Who performed this write, such as an agent or person name. Stored for audit; never used to grant trust."

changedInput schema / properties / client / description

Previous value: -"Which client performed this write."New value: +"Which client software performed this write, such as the host application name."

changedInput schema / properties / embedding / description

Previous value: -"Optional caller-supplied vector. When omitted, the configured embedding provider is used."New value: +"Caller-supplied vector for this text. Omit to use the configured embedding provider; with no provider the record is still stored and recall reports semantic.available=false instead of renaming lexical overlap as semantic."

addedInput schema / properties / key / description

Added value: +"Stable caller-chosen name within this scope and type, such as hotel-style. Reusing it reconciles that memory rather than adding a second one."

addedInput schema / properties / memoryType / description

Added value: +"Which kind of memory this is, and part of its identity. preference and profile are durable user facts, goal a desired state, instruction an operating constraint, procedure reusable steps, episode a recallable event, note general knowledge."

addedInput schema / properties / metadata / description

Added value: +"Caller-owned JSON object kept with the memory. Part of the compared content, so changing it produces a new version."

addedInput schema / properties / operations / description

Added value: +"A batch plan. Supply this instead of a single memory, typically from an extraction step. Every operation is validated before the first one is applied, so a malformed late operation cannot leave a half-applied batch."

addedInput schema / properties / operations / items / properties / action / description

Added value: +"ADD and UPDATE both reconcile against the current memory and require text; DELETE invalidates the current one, keeping history; NOOP records that nothing should change."

changedInput schema / properties / operations / items / properties / embedding / description

Previous value: -"Optional caller-supplied vector. When omitted, the configured embedding provider is used."New value: +"Caller-supplied vector for this text. Omit to use the configured embedding provider; with no provider the record is still stored and recall reports semantic.available=false instead of renaming lexical overlap as semantic."

addedInput schema / properties / operations / items / properties / key / description

Added value: +"Stable caller-chosen name within this scope and type, such as hotel-style. Reusing it reconciles that memory rather than adding a second one."

addedInput schema / properties / operations / items / properties / memoryType / description

Added value: +"Which kind of memory this is, and part of its identity. preference and profile are durable user facts, goal a desired state, instruction an operating constraint, procedure reusable steps, episode a recallable event, note general knowledge."

addedInput schema / properties / operations / items / properties / metadata / description

Added value: +"Caller-owned JSON object kept with the memory. Part of the compared content, so changing it produces a new version."

addedInput schema / properties / operations / items / properties / scope / description

Added value: +"Scope selector. Omitted or partial fields mean explicit nulls, not \"any\": identity is the exact (project, userId, agentId, runId, memoryType, key) tuple, so a run-scoped memory never leaks into a user-only read."

addedInput schema / properties / operations / items / properties / scope / properties / agentId / description
```
Added value: +"Agent this memory belongs to, or null for none."
```
addedInput schema / properties / operations / items / properties / scope / properties / runId / description
```
Added value: +"Single run or task this memory belongs to, or null for none."
```
addedInput schema / properties / operations / items / properties / scope / properties / userId / description
```
Added value: +"Person this memory belongs to, or null for none."
```

addedInput schema / properties / operations / items / properties / tags / description

Added value: +"Free-form labels stored with the memory. Part of the compared content, so changing them produces a new version."

addedInput schema / properties / operations / items / properties / text / description

Added value: +"The memory content itself. Stored verbatim, searched as content, and compared to decide ADD, UPDATE, or NOOP."

addedInput schema / properties / operations / items / properties / validFrom / description

Added value: +"ISO 8601 instant from which this memory is true in the modeled world. Defaults to the write time. Writes for one identity must arrive in non-decreasing validFrom order."

addedInput schema / properties / operations / items / properties / validTo / description

Added value: +"ISO 8601 instant after which it stops being true, or null for open-ended. Must be later than validFrom."

addedInput schema / properties / project / description

Added value: +"Project namespace. Defaults to \"default\"; an empty string is rejected."

addedInput schema / properties / scope / description

Added value: +"Scope selector. Omitted or partial fields mean explicit nulls, not \"any\": identity is the exact (project, userId, agentId, runId, memoryType, key) tuple, so a run-scoped memory never leaks into a user-only read."

addedInput schema / properties / scope / properties / agentId / description
```
Added value: +"Agent this memory belongs to, or null for none."
```

addedInput schema / properties / scope / properties / runId / description

Added value: +"Single run or task this memory belongs to, or null for none."

addedInput schema / properties / scope / properties / userId / description
```
Added value: +"Person this memory belongs to, or null for none."
```

changedInput schema / properties / sessionId / description

Previous value: -"Session identifier for this write."New value: +"Caller-owned identifier that groups related writes in the audit trail."

changedInput schema / properties / sourceClass / description

Previous value: -"Claimed origin class. A claim, not proof: no value here can make a fact verified."New value: +"Claimed origin, never proof: agent_claimed (the default), tool_observed, human_confirmed, or production_verified. It weights confidence only. An unrecognised label downgrades to agent_claimed, kept verbatim in sourceRaw."

addedInput schema / properties / tags / description

Added value: +"Free-form labels stored with the memory. Part of the compared content, so changing them produces a new version."

addedInput schema / properties / text / description

Added value: +"The memory content itself. Stored verbatim, searched as content, and compared to decide ADD, UPDATE, or NOOP."

addedInput schema / properties / validFrom / description

Added value: +"ISO 8601 instant from which this memory is true in the modeled world. Defaults to the write time. Writes for one identity must arrive in non-decreasing validFrom order."

addedInput schema / properties / validTo / description

Added value: +"ISO 8601 instant after which it stops being true, or null for open-ended. Must be later than validFrom."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "anyOf": [
+    {
+      "properties": {
+        "indexUpdated": {
+          "description": "Present when identical content arrived with a different embedding: the index was refreshed without minting a new version.",
+          "type": "boolean"
+        },
+        "memory": {
+          "description": "A stored scoped memory version.",
+          "properties": {
+            "actor": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Who performed the write."
+            },
+            "client": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Which client performed the write."
+            },
+            "createdAt": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "ISO 8601 creation time."
+            },
+            "embedding": {
+              "anyOf": [
+                {
+                  "type": "array"
+                },
+                {
+                  "type": "object"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "The stored vector, or null when none was supplied and no provider was configured."
+            },
+            "id": {
+              "description": "Stable entity identifier.",
+              "type": "string"
+            },
+            "key": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Caller-chosen name within the scope and type."
+            },
+            "kind": {
+              "description": "Entity kind: decision, attempt, memory, fact, relation, review, or alternative.",
+              "type": "string"
+            },
+            "memoryType": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "preference, profile, goal, instruction, procedure, episode, or note."
+            },
+            "metadata": {
+              "description": "Caller-owned JSON stored with the memory.",
+              "type": "object"
+            },
+            "project": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Project namespace; records imported from a schema that predates projects may carry null."
+            },
+            "schemaVersion": {
+              "description": "Storage schema version this entity was written under. A value above the build’s own version is preserved rather than downgraded.",
+              "type": "integer"
+            },
+            "scope": {
+              "description": "The userId, agentId, and runId this memory is scoped to; each is a string or null.",
+              "type": "object"
+            },
+            "sessionId": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Session identifier recorded with the write."
+            },
+            "sourceClass": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Claimed origin class recorded with the write. A claim, never proof."
+            },
+            "sourceRaw": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "The original origin label when it differed from sourceClass. Audit only; never evidence."
+            },
+            "status": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "active, superseded, or invalidated."
+            },
+            "supersededBy": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Identifier of the version that replaced this one."
+            },
+            "supersedes": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Identifier of the version this one replaced."
+            },
+            "tags": {
+              "description": "Labels stored with the memory.",
+              "type": "array"
+            },
+            "temporal": {
+              "description": "Bi-temporal window: validFrom, validTo, recordedAt, invalidatedAt.",
+              "type": "object"
+            },
+            "text": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "The memory content."
+            },
+            "updatedAt": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "ISO 8601 time of the last change."
+            },
+            "verificationStatus": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Always unverified for memories."
+            },
+            "version": {
+              "anyOf": [
+                {
+                  "type": "integer"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Version number within this identity, incrementing on each superseding write."
+            }
+          },
+          "required": [
+            "id",
+            "kind"
+          ],
+          "type": "object"
+        },
+        "operation": {
+          "description": "ADD when no active memory existed, UPDATE when one was superseded, NOOP when content was identical.",
+          "enum": [
+            "ADD",
+            "UPDATE",
+            "NOOP"
+          ],
+          "type": "string"
+        },
+        "previous": {
+          "description": "A stored scoped memory version.",
+          "properties": {
+            "actor": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Who performed the write."
+            },
+            "client": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Which client performed the write."
+            },
+            "createdAt": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "ISO 8601 creation time."
+            },
+            "embedding": {
+              "anyOf": [
+                {
+                  "type": "array"
+                },
+                {
+                  "type": "object"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "The stored vector, or null when none was supplied and no provider was configured."
+            },
+            "id": {
+              "description": "Stable entity identifier.",
+              "type": "string"
+            },
+            "key": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Caller-chosen name within the scope and type."
+            },
+            "kind": {
+              "description": "Entity kind: decision, attempt, memory, fact, relation, review, or alternative.",
+              "type": "string"
+            },
+            "memoryType": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "preference, profile, goal, instruction, procedure, episode, or note."
+            },
+            "metadata": {
+              "description": "Caller-owned JSON stored with the memory.",
+              "type": "object"
+            },
+            "project": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Project namespace; records imported from a schema that predates projects may carry null."
+            },
+            "schemaVersion": {
+              "description": "Storage schema version this entity was written under. A value above the build’s own version is preserved rather than downgraded.",
+              "type": "integer"
+            },
+            "scope": {
+              "description": "The userId, agentId, and runId this memory is scoped to; each is a string or null.",
+              "type": "object"
+            },
+            "sessionId": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Session identifier recorded with the write."
+            },
+            "sourceClass": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Claimed origin class recorded with the write. A claim, never proof."
+            },
+            "sourceRaw": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "The original origin label when it differed from sourceClass. Audit only; never evidence."
+            },
+            "status": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "active, superseded, or invalidated."
+            },
+            "supersededBy": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Identifier of the version that replaced this one."
+            },
+            "supersedes": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Identifier of the version this one replaced."
+            },
+            "tags": {
+              "description": "Labels stored with the memory.",
+              "type": "array"
+            },
+            "temporal": {
+              "description": "Bi-temporal window: validFrom, validTo, recordedAt, invalidatedAt.",
+              "type": "object"
+            },
+            "text": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "The memory content."
+            },
+            "updatedAt": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "ISO 8601 time of the last change."
+            },
+            "verificationStatus": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Always unverified for memories."
+            },
+            "version": {
+              "anyOf": [
+                {
+                  "type": "integer"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Version number within this identity, incrementing on each superseding write."
+            }
+          },
+          "required": [
+            "id",
+            "kind"
+          ],
+          "type": "object"
+        }
+      },
+      "required": [
+        "operation",
+        "memory"
+      ],
+      "type": "object"
+    },
+    {
+      "properties": {
+        "completeness": {
+          "description": "Plan accounting. This is not the paginated completeness envelope.",
+          "properties": {
+            "applied": {
+              "description": "Results produced, one per submitted operation.",
+              "minimum": 0,
+              "type": "integer"
+            },
+            "complete": {
+              "description": "Always true: a plan is applied in full or rejected in full.",
+              "type": "boolean"
+            },
+            "requested": {
+              "description": "Operations submitted.",
+              "minimum": 0,
+              "type": "integer"
+            }
+          },
+          "required": [
+            "complete",
+            "requested",
+            "applied"
+          ],
+          "type": "object"
+        },
+        "results": {
+          "description": "One result per submitted operation, in order.",
+          "items": {
+            "properties": {
+              "indexUpdated": {
+                "description": "Present when only the embedding was refreshed.",
+                "type": "boolean"
+              },
+              "memory": {
+                "anyOf": [
+                  {
+                    "description": "A stored scoped memory version.",
+                    "properties": {
+                      "actor": {
+                        "anyOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ],
+                        "description": "Who performed the write."
+                      },
+                      "client": {
+                        "anyOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ],
+                        "description": "Which client performed the write."
+                      },
+                      "createdAt": {
+                        "anyOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ],
+                        "description": "ISO 8601 creation time."
+                      },
+                      "embedding": {
+                        "anyOf": [
+                          {
+                            "type": "array"
+                          },
+                          {
+                            "type": "object"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ],
+                        "description": "The stored vector, or null when none was supplied and no provider was configured."
+                      },
+                      "id": {
+                        "description": "Stable entity identifier.",
+                        "type": "string"
+                      },
+                      "key": {
+                        "anyOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ],
+                        "description": "Caller-chosen name within the scope and type."
+                      },
+                      "kind": {
+                        "description": "Entity kind: decision, attempt, memory, fact, relation, review, or alternative.",
+                        "type": "string"
+                      },
+                      "memoryType": {
+                        "anyOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ],
+                        "description": "preference, profile, goal, instruction, procedure, episode, or note."
+                      },
+                      "metadata": {
+                        "description": "Caller-owned JSON stored with the memory.",
+                        "type": "object"
+                      },
+                      "project": {
+                        "anyOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ],
+                        "description": "Project namespace; records imported from a schema that predates projects may carry null."
+                      },
+                      "schemaVersion": {
+                        "description": "Storage schema version this entity was written under. A value above the build’s own version is preserved rather than downgraded.",
+                        "type": "integer"
+                      },
+                      "scope": {
+                        "description": "The userId, agentId, and runId this memory is scoped to; each is a string or null.",
+                        "type": "object"
+                      },
+                      "sessionId": {
+                        "anyOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ],
+                        "description": "Session identifier recorded with the write."
+                      },
+                      "sourceClass": {
+                        "anyOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ],
+                        "description": "Claimed origin class recorded with the write. A claim, never proof."
+                      },
+                      "sourceRaw": {
+                        "anyOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ],
+                        "description": "The original origin label when it differed from sourceClass. Audit only; never evidence."
+                      },
+                      "status": {
+                        "anyOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ],
+                        "description": "active, superseded, or invalidated."
+                      },
+                      "supersededBy": {
+                        "anyOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ],
+                        "description": "Identifier of the version that replaced this one."
+                      },
+                      "supersedes": {
+                        "anyOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ],
+                        "description": "Identifier of the version this one replaced."
+                      },
+                      "tags": {
+                        "description": "Labels stored with the memory.",
+                        "type": "array"
+                      },
+                      "temporal": {
+                        "description": "Bi-temporal window: validFrom, validTo, recordedAt, invalidatedAt.",
+                        "type": "object"
+                      },
+                      "text": {
+                        "anyOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ],
+                        "description": "The memory content."
+                      },
+                      "updatedAt": {
+                        "anyOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ],
+                        "description": "ISO 8601 time of the last change."
+                      },
+                      "verificationStatus": {
+                        "anyOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ],
+                        "description": "Always unverified for memories."
+                      },
+                      "version": {
+                        "anyOf": [
+                          {
+                            "type": "integer"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ],
+                        "description": "Version number within this identity, incrementing on each superseding write."
+                      }
+                    },
+                    "required": [
+                      "id",
+                      "kind"
+                    ],
+                    "type": "object"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "The resulting memory, or null for a NOOP on an identity that has no memory."
+              },
+              "operation": {
+                "description": "What was actually applied, which may differ from the requested action when content already matched.",
+                "enum": [
+                  "ADD",
+                  "UPDATE",
+                  "DELETE",
+                  "NOOP"
+                ],
+                "type": "string"
+              },
+              "previous": {
+                "description": "A stored scoped memory version.",
+                "properties": {
+                  "actor": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "Who performed the write."
+                  },
+                  "client": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "Which client performed the write."
+                  },
+                  "createdAt": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "ISO 8601 creation time."
+                  },
+                  "embedding": {
+                    "anyOf": [
+                      {
+                        "type": "array"
+                      },
+                      {
+                        "type": "object"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "The stored vector, or null when none was supplied and no provider was configured."
+                  },
+                  "id": {
+                    "description": "Stable entity identifier.",
+                    "type": "string"
+                  },
+                  "key": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "Caller-chosen name within the scope and type."
+                  },
+                  "kind": {
+                    "description": "Entity kind: decision, attempt, memory, fact, relation, review, or alternative.",
+                    "type": "string"
+                  },
+                  "memoryType": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "preference, profile, goal, instruction, procedure, episode, or note."
+                  },
+                  "metadata": {
+                    "description": "Caller-owned JSON stored with the memory.",
+                    "type": "object"
+                  },
+                  "project": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "Project namespace; records imported from a schema that predates projects may carry null."
+                  },
+                  "schemaVersion": {
+                    "description": "Storage schema version this entity was written under. A value above the build’s own version is preserved rather than downgraded.",
+                    "type": "integer"
+                  },
+                  "scope": {
+                    "description": "The userId, agentId, and runId this memory is scoped to; each is a string or null.",
+                    "type": "object"
+                  },
+                  "sessionId": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "Session identifier recorded with the write."
+                  },
+                  "sourceClass": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "Claimed origin class recorded with the write. A claim, never proof."
+                  },
+                  "sourceRaw": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "The original origin label when it differed from sourceClass. Audit only; never evidence."
+                  },
+                  "status": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "active, superseded, or invalidated."
+                  },
+                  "supersededBy": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "Identifier of the version that replaced this one."
+                  },
+                  "supersedes": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "Identifier of the version this one replaced."
+                  },
+                  "tags": {
+                    "description": "Labels stored with the memory.",
+                    "type": "array"
+                  },
+                  "temporal": {
+                    "description": "Bi-temporal window: validFrom, validTo, recordedAt, invalidatedAt.",
+                    "type": "object"
+                  },
+                  "text": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "The memory content."
+                  },
+                  "updatedAt": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "ISO 8601 time of the last change."
+                  },
+                  "verificationStatus": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "Always unverified for memories."
+                  },
+                  "version": {
+                    "anyOf": [
+                      {
+                        "type": "integer"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "Version number within this identity, incrementing on each superseding write."
+                  }
+                },
+                "required": [
+                  "id",
+                  "kind"
+                ],
+                "type": "object"
+              }
+            },
+            "required": [
+              "operation",
+              "memory"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "results",
+        "completeness"
+      ],
+      "type": "object"
+    }
+  ],
+  "description": "Either the outcome of one reconciliation, or the outcome of a plan.",
+  "type": "object"
+}

First observedv0.40.0Sep 2, 2026

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false; the description adds the important nuance that 'destructive' here means invalidation with history retained and that every call commits a revision. That reframes the risk profile in a way annotations alone cannot. It does not cover auth/permission requirements or failure modes, keeping it a 4.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with purpose then alternatives then semantics, with zero filler. The final sentence is a dense run-on of three behaviors that could be split for readability, but every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 17-parameter, nested, mutation tool with an output schema, the description supplies the essential mental model (identity tuple, reconciliation outcomes, revision commit) and sibling routing. Batch atomicity and ID-rejection rules live in the schema, which is legitimate, but the description does not mention the single-vs-operations mutual exclusivity that an agent must satisfy.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3; the description adds the governing concept that memory is keyed by an exact scoped identity tuple and that identical content is a NOOP, which explains why no id is accepted. That conceptual framing helps the agent choose between single-memory and operations form, though individual parameter meanings still come from the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb-and-resource statement ('Add or reconcile one scoped memory') and covers the batch form ('apply an ADD/UPDATE/DELETE/NOOP plan, by identity tuple'). It explicitly differentiates itself from siblings by naming shadowgraph_record_decision, shadowgraph_record_fact and shadowgraph_recall with their respective purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives direct routing rules: use record_decision for a choice, record_fact for an observation, recall to read back. The reconciliation semantics (identical content = NOOP, new content supersedes, DELETE invalidates) tell the agent when an ADD collapses into a no-op or an update. The only minor gap is no explicit guidance versus shadowgraph_supersede or shadowgraph_maintain.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.