ShadowGraph

Official

Overview Schema Source Related Servers Discussions Admin

shadowgraph_record_fact

Destructive

Record an observed fact by project and key with claimed provenance and optional validity, replacing the prior active fact while preserving it as history.

Instructions

Record one observed fact as a project and key, with a claimed provenance class and optional validity window. Use for the fact keys reopenWhen rules name; shadowgraph_remember stores durable memory that is not an observation. Supersedes the previous active fact, keeping it as history. No input can make a fact verified. Each call commits a revision.

Input Schema

Name	Required	Description
`key`	Yes	Fact name, unique per project among active facts. Required and non-empty. Use the same key that a decision’s reopenWhen rules refer to.
`actor`	No	Who performed this write, such as an agent or person name. Stored for audit; never used to grant trust.
`value`	No	Any lossless JSON value: string, finite number, boolean, null, array, or object.
`client`	No	Which client software performed this write, such as the host application name.
`source`	No	Legacy alias for sourceClass. An unknown label downgrades to agent_claimed with the raw label kept in sourceRaw.
`project`	No	Owning project; required unless originId is set, else the write is refused.
`originId`	No	Capture-origin id; with no project the record belongs to it alone.
`expiresAt`	No	ISO 8601 instant after which shadowgraph_maintain expires this fact. Combined with validTo, the earlier boundary wins.
`sessionId`	No	Caller-owned identifier that groups related writes in the audit trail.
`confidence`	No	How much the caller trusts this observation, 0-1. Defaults to 0.5. It does not verify anything.
`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.
`verificationStatus`	No	Only "contradicted" may be set by a caller, because it lowers trust. "verified" and "expired" are rejected: verification is not self-assertable and expiry is owned by shadowgraph_maintain.

Output Schema

Name	Required	Description
`id`	No	Stable entity identifier.
`key`	Yes	Fact name, unique per project among active facts.
`kind`	No	Entity kind: decision, attempt, memory, fact, relation, review, or alternative.
`actor`	No	Who performed the write.
`value`	No	The observed value, any lossless JSON value.
`client`	No	Which client performed the write.
`source`	No	Legacy alias of sourceClass, retained for compatibility.
`status`	No	active, superseded, or expired.
`project`	No	Project namespace; null for an unattributed record or one imported from before projects.
`temporal`	No	Bi-temporal window: validFrom, validTo, recordedAt, invalidatedAt.
`createdAt`	No	ISO 8601 creation time.
`expiresAt`	No	Caller-declared expiry instant, or null.
`sessionId`	No	Session identifier recorded with the write.
`sourceRaw`	No	The original origin label when it differed from sourceClass. Audit only; never evidence.
`updatedAt`	No	ISO 8601 time of the last change.
`confidence`	No	Caller-declared confidence in the observation, 0-1.
`observedAt`	No	ISO 8601 time the fact was observed.
`sourceClass`	No	Claimed origin class recorded with the write. A claim, never proof.
`verification`	No	Present only on a signed verification: the attestation this build checked.
`schemaVersion`	No	Storage schema version this entity was written under. A value above the build’s own version is preserved rather than downgraded.
`validityPolicy`	No	Declared expiry inputs and the effective expiration boundary derived from them.
`verificationStatus`	No	unverified, contradicted, expired, or verified. Only the separately configured signed-evidence verifier can produce verified.

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv0.42.1Oct 25, 2026

addedInput schema / description

Added value: +"ShadowGraph generates and returns canonical IDs. Supplying a creation id is refused before lookup or retry; keep returned IDs for later references."

addedInput schema / not

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

changedInput schema / properties / idempotencyKey / description

Previous value: -"Retry key scoped by project and operation: reuse it so a retry returns the first result instead of writing a duplicate. Without it every call creates a new entity."New value: +"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."

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 / properties / project / description

Previous value: -"Project namespace; records imported from a schema that predates projects may carry null."New value: +"Project namespace; null for an unattributed record or one imported from before projects."

Changed12 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."

addedInput schema / properties / confidence / description

Added value: +"How much the caller trusts this observation, 0-1. Defaults to 0.5. It does not verify anything."

addedInput schema / properties / expiresAt / description

Added value: +"ISO 8601 instant after which shadowgraph_maintain expires this fact. Combined with validTo, the earlier boundary wins."

changedInput schema / properties / idempotencyKey / description

Previous value: -"Retry key scoped by project and operation; reuse only for the same logical write."New value: +"Retry key scoped by project and operation: reuse it so a retry returns the first result instead of writing a duplicate. Without it every call creates a new entity."

addedInput schema / properties / key / description

Added value: +"Fact name, unique per project among active facts. Required and non-empty. Use the same key that a decision’s reopenWhen rules refer to."

addedInput schema / properties / project / description

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

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 / source / description

Previous value: -"Legacy alias for sourceClass. Unknown labels downgrade to agent_claimed with the raw label kept in sourceRaw."New value: +"Legacy alias for sourceClass. An unknown label downgrades to agent_claimed with the raw label kept in sourceRaw."

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."

changedInput schema / properties / verificationStatus / description

Previous value: -"Only `contradicted` may be set by a caller; `verified` and `expired` are rejected."New value: +"Only \"contradicted\" may be set by a caller, because it lowers trust. \"verified\" and \"expired\" are rejected: verification is not self-assertable and expiry is owned by shadowgraph_maintain."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "description": "A stored fact with its provenance claim and validity window.",
+  "properties": {
+    "actor": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Who performed the write."
+    },
+    "client": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Which client performed the write."
+    },
+    "confidence": {
+      "anyOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Caller-declared confidence in the observation, 0-1."
+    },
+    "createdAt": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "ISO 8601 creation time."
+    },
+    "expiresAt": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Caller-declared expiry instant, or null."
+    },
+    "id": {
+      "description": "Stable entity identifier.",
+      "type": "string"
+    },
+    "key": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Fact name, unique per project among active facts."
+    },
+    "kind": {
+      "description": "Entity kind: decision, attempt, memory, fact, relation, review, or alternative.",
+      "type": "string"
+    },
+    "observedAt": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "ISO 8601 time the fact was observed."
+    },
+    "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"
+    },
+    "sessionId": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Session identifier recorded with the write."
+    },
+    "source": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Legacy alias of sourceClass, retained for compatibility."
+    },
+    "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 expired."
+    },
+    "temporal": {
+      "description": "Bi-temporal window: validFrom, validTo, recordedAt, invalidatedAt.",
+      "type": "object"
+    },
+    "updatedAt": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "ISO 8601 time of the last change."
+    },
+    "validityPolicy": {
+      "description": "Declared expiry inputs and the effective expiration boundary derived from them.",
+      "type": "object"
+    },
+    "value": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "number"
+        },
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        },
+        {
+          "type": "array"
+        },
+        {
+          "type": "object"
+        }
+      ],
+      "description": "The observed value, any lossless JSON value."
+    },
+    "verification": {
+      "description": "Present only on a signed verification: the attestation this build checked.",
+      "type": "object"
+    },
+    "verificationStatus": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "unverified, contradicted, expired, or verified. Only the separately configured signed-evidence verifier can produce verified."
+    }
+  },
+  "required": [
+    "key"
+  ],
+  "type": "object"
+}

First observedv0.40.0Sep 2, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true and idempotentHint=false; the description goes beyond them by explaining that the prior active fact is superseded but retained as history, that each call commits a revision, and that no input can make a fact verified. What it leaves implicit is how retries interact with revision churn, which is left entirely to the schema's idempotencyKey field.

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?

Five short sentences, front-loaded with what the tool does, followed by routing, mutation semantics, and the trust invariant. Every sentence carries distinct information and none restates the title or annotations.

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 13-parameter mutation tool with full schema coverage, complete annotations, and an output schema, the description supplies the conceptual model an agent needs: identity, supersession with history, and the non-assertable verification rule. The remaining gap is guidance on the sibling supersede tool, which matters given the destructive annotation.

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?

Schema coverage is 100%, so all 13 parameters including the enums and the verified/expired rejection rule are already documented in structured data. The description only echoes the top-level concepts (project, key, provenance class, validity window) and adds no syntax, defaults, or interaction details beyond the schema, so the baseline of 3 applies.

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?

States a specific verb and resource ("Record one observed fact") plus the identity model (project + key), provenance class, and validity window. It also explicitly distinguishes itself from shadowgraph_remember, so an agent can route between the two without opening a schema.

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

Usage Guidelines4/5

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

Gives a concrete when-to-use rule ("Use for the fact keys reopenWhen rules name") and names the alternative that handles non-observational data. It does not address the overlap with the sibling shadowgraph_supersede, which also deals with replacement, so an agent gets no explicit guidance on when to prefer that tool instead.

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