MemoryWrite

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/aimeat-io/json-schema/aimeat-io-memory-write-schema.json",
  "title": "MemoryWrite",
  "x-generated": "2026-11-01",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/aimeat-io-openapi.json#/components/schemas/MemoryWrite",
  "type": "object",
  "required": [
    "key",
    "value"
  ],
  "properties": {
    "key": {
      "type": "string",
      "description": "Hierarchical key (slash-separated)"
    },
    "value": {
      "description": "Any JSON value"
    },
    "visibility": {
      "$ref": "#/$defs/Visibility"
    },
    "group_id": {
      "type": "string",
      "description": "Sharing group ID (required when visibility is 'group')"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "ttl_hours": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Time-to-live in hours (null = permanent)"
    },
    "expected_version": {
      "type": "integer",
      "minimum": 0,
      "description": "Optimistic lock: the `version` you read from this record. The write is refused with 409 VERSION_CONFLICT if the record has changed since; 0 asserts that the key does not exist yet. Omit it and the write proceeds as before (last write wins).\n"
    },
    "owner_scope": {
      "type": "boolean",
      "description": "Write this record under the OWNER's namespace instead of the caller's own. Memory is keyed by whoever wrote it, so without this an agent's write lands under its GAII and the owner's own tools do not see it as theirs.\nRequires the `memory:write-as-owner` scope, which the owner grants per agent. The flag is required as well as the scope: granting the scope alone must never redirect writes an agent was already making, or its own records move out from under its own reads.\nDoes NOT change `visibility` — where a record lives and who may read it are separate.\nThe server-trusted keys (`openrouter.*`, `ai-usage.*`, `profile.*`) stay refused unless the agent also holds `memory:write-reserved`, which is deliberately not part of `*`.\n"
    },
    "agent": {
      "type": "string",
      "description": "Owner-session only — target GAII to store this entry under one of the owner's own agents instead of the owner's GHII. Ignored for agent sessions. The agent must belong to the calling owner.\n"
    },
    "ai_provenance_id": {
      "type": "string",
      "description": "Attach an ALREADY-MINTED AI provenance record to this write - typically the one `/v1/ai/complete` returned in `meta.provenance`. This is the publish path: the record is minted private at generation and becomes anonymously resolvable exactly while the item carrying it is public. It must belong to the caller's own account, or it is ignored.\nWhen it is absent and the writer is an AGENT or ECOSYSTEM principal, the node stamps one itself (`ai-generated`, `humanInvolvement: none`, `stampedBy: node`, `observed: false`, with the inference stated in `notes`): silence from an agent must not read as \"a human wrote it\". An OWNER principal is never stamped. The writer is the caller, wherever the record lands: an agent's `owner_scope` write is stamped as the agent's.\n"
    },
    "ai_provenance": {
      "allOf": [
        {
          "$ref": "#/$defs/AiProvenanceDeclaration"
        }
      ],
      "description": "How this value was made, declared with the write and recorded against the bytes stored, wherever the write lands (owner_scope included). Needs `provenance:write` on the grant and the session; without it the write is refused 403 SCOPE_DENIED and nothing is stored. A block that does not parse is 400 INVALID_INPUT. The response names the record in `ai_provenance_id`.\nThe hash of a value that is not a string is taken over its canonical JSON: object keys sorted at every level (RFC 8785 order), no whitespace. A record minted before 2026-10-08 carries the hash of the value as it was written.\n"
    }
  },
  "$defs": {
    "AiProvenanceDeclaration": {
      "type": "object",
      "description": "What a caller SAYS about how the content in this request was made — the input block, not the stored record. It is the same shape the MCP write tools take as `ai_provenance`, so a statement means one thing whichever surface it arrives on.\n\nWhat is deliberately absent is identity. There is no principal, no node and no attestation here: the node fills in who you are, which node, when, and the hash of the exact bytes, and it never takes any of those from the caller. A declaration is believed about the HOW and never about the WHO.\n\nOmitting the block is not an error. For an AGENT or ECOSYSTEM principal the node then stamps a record itself (`stampedBy: node`) — silence from a non-human writer must not read as \"a human wrote it\" — while an OWNER principal is never stamped.\n",
      "required": [
        "level"
      ],
      "properties": {
        "level": {
          "type": "string",
          "enum": [
            "original",
            "assisted",
            "synthesized",
            "ai-generated"
          ],
          "description": "How much of this a model made. `original` = a person wrote it, no model involved. `assisted` = a person wrote it and a model edited or refined it. `synthesized` = a model combined real sources into new content at someone's direction. `ai-generated` = a model produced it.\n"
        },
        "method": {
          "type": "string",
          "enum": [
            "human",
            "rewritten",
            "summarized",
            "translated",
            "synthesized",
            "fully-generated",
            "multi-agent",
            "transcribed"
          ],
          "description": "Optional detail under `level`."
        },
        "media_kind": {
          "type": "string",
          "enum": [
            "text",
            "image",
            "audio",
            "video",
            "code",
            "data"
          ],
          "description": "What kind of thing this is. It gives the label its words (a picture is not \"this text\") and decides whether the deep-fake rule applies, which reaches image, audio and video only. Omitted: the node states text for text it stores, and nothing for bytes.\n"
        },
        "media_type": {
          "type": "string",
          "description": "The IANA media type of the bytes."
        },
        "resembles_real": {
          "type": "string",
          "enum": [
            "yes",
            "no",
            "unknown"
          ],
          "description": "For image, audio or video: does it resemble a real person, place, object or event? Public synthetic media is labelled either way; this decides only whether the record cites the deep-fake rule.\n"
        },
        "human_involvement": {
          "type": "string",
          "enum": [
            "none",
            "light-review",
            "editorial-control",
            "full-human"
          ],
          "description": "Whether a person examined what the model produced. Only a step where someone reads the SUBSTANCE and can reject it counts — a skim, a spell-check or clicking publish is `light-review` at most. Omitted means `none`.\n"
        },
        "model": {
          "type": "string",
          "description": "The model that produced it, as the provider names it. When the declarer made it, this is its own model id. Without it the record says only who served the model, never which one, and an app publish answers with the `provenance-without-model` hint.\n"
        },
        "provider": {
          "type": "string",
          "description": "Who SERVED the model, when that is not obvious from its name. Worth stating whenever the declarer routes through an intermediary: \"which model\" and \"who ran it\" are different questions, and a router alias answers neither on its own.\n"
        },
        "sources": {
          "type": "array",
          "maxItems": 100,
          "description": "For synthesized content, where the material came from.",
          "items": {
            "type": "object",
            "required": [
              "url"
            ],
            "properties": {
              "url": {
                "type": "string",
                "format": "uri",
                "pattern": "^https?://",
                "description": "http or https ONLY, checked at the door. A declaration carrying any other scheme is refused with a validation error rather than minted."
              },
              "title": {
                "type": "string"
              },
              "retrieved_at": {
                "type": "string",
                "format": "date-time"
              },
              "role": {
                "type": "string",
                "description": "How it was used, e.g. 'primary' or 'background'."
              }
            }
          }
        },
        "notes": {
          "type": "string",
          "maxLength": 1000,
          "description": "Anything a reader needs to interpret the above. Never prompt text or anything private — the record is publishable alongside the content.\n"
        }
      }
    },
    "OrganismVisibility": {
      "type": "string",
      "pattern": "^organism:[A-Za-z0-9][A-Za-z0-9_-]{0,127}$",
      "description": "`organism:<organism id>`: readable by the active members of that organism and the agents it admits, never by an anonymous caller or a visitor from another node. Node-local.\n"
    },
    "Visibility": {
      "default": "private",
      "description": "Who may read a memory record. `members` is any signed-in account of this node, `group` the members of a sharing group, and `organism:<organism id>` the active members of that one organism and the agents it admits; the writer's account must be an active member of it, or the write is refused with 400 NOT_ORGANISM_MEMBER. Neither `members` nor `organism:<id>` is ever federated. Stored files take StoredFileVisibility.\n",
      "oneOf": [
        {
          "type": "string",
          "enum": [
            "private",
            "owner",
            "group",
            "members",
            "public"
          ]
        },
        {
          "$ref": "#/$defs/OrganismVisibility"
        }
      ]
    }
  }
}