ShadowGraph

Official

Overview Schema Related Servers Score Discussions

shadowgraph_remember

Add or reconcile scoped memories by identity tuple, applying ADD, UPDATE, DELETE, or NOOP with full revision history. Solves duplicate and stale memory writes while keeping changes auditable.

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

TableJSON 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	Project namespace. Defaults to "default"; an empty string is rejected.
`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.
`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.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

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.7/5.0

Behavior5/5

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

Beyond the annotations (readOnly=false, destructive=false, idempotent=false), the description adds meaningful behavior: identical content is a NOOP, new content supersedes while keeping history, DELETE invalidates, and every call commits a revision. This clarifies the mutation model and confirms why the operation is neither idempotent nor genuinely destructive.

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

Conciseness5/5

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

Three dense sentences carry distinct value: what the tool does, which siblings to use instead, and core behavioral semantics. The most important action is front-loaded, and no sentence is filler.

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

Completeness5/5

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

For a complex 15-parameter tool with a rich output schema and fully commented input schema, the description covers the essential selection and invocation information: single-memory vs batch plan, identity-tuple reconciliation, history preservation, and sibling routing. Remaining operational details live appropriately in the schema definitions.

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

Parameters3/5

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

The input schema is exhaustively self-documenting with 100% description coverage, so the description does not need to repeat parameter details. It adds useful framing like 'by identity tuple' and the reconcile/supersede/NOOP behavior, but does not independently clarify individual parameters beyond 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?

The description opens with a specific verb and resource: 'Add or reconcile one scoped memory, or apply an ADD/UPDATE/DELETE/NOOP plan.' It clearly distinguishes itself from sibling tools by directing decision memories to shadowgraph_record_decision, factual observations to shadowgraph_record_fact, and reads to shadowgraph_recall.

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?

The description explicitly states when to use sibling alternatives ('Use shadowgraph_record_decision for a choice, shadowgraph_record_fact for an observation, shadowgraph_recall to read memory back'), giving an agent clear routing signals. It also clarifies the batch-plan mode versus single-memory mode as two valid ways to invoke this tool.

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

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/LiLara-AI/shadowgraph'

If you have feedback or need assistance with the MCP directory API, please join our Discord server