atlas-iac/services/hermes/contracts/hux/memory.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://hermes.bstein.dev/contracts/hux/v1/memory.schema.json",
  "title": "HUX memory ledger entry",
  "description": "A single remembered item (HUX-02). Memory is a ledger: entries are appended, approved, expired or forgotten, never edited in place. Forgotten entries keep their audit trail but drop content.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema",
    "id",
    "owner",
    "scope",
    "kind",
    "content",
    "status",
    "approval_mode",
    "sensitivity",
    "ttl",
    "source",
    "provenance",
    "created_at",
    "updated_at",
    "audit",
    "reason",
    "retrievable",
    "revision"
  ],
  "properties": {
    "schema": {
      "const": "hux.memory.v1"
    },
    "id": {
      "$ref": "common.schema.json#/$defs/id"
    },
    "owner": {
      "$ref": "common.schema.json#/$defs/user_ref"
    },
    "scope": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "level"
      ],
      "properties": {
        "level": {
          "type": "string",
          "enum": [
            "global",
            "project",
            "conversation"
          ]
        },
        "scope_id": {
          "$ref": "common.schema.json#/$defs/id"
        }
      }
    },
    "kind": {
      "type": "string",
      "enum": [
        "preference",
        "fact",
        "instruction",
        "context"
      ]
    },
    "content": {
      "type": "string",
      "maxLength": 2000
    },
    "status": {
      "type": "string",
      "enum": [
        "proposed",
        "active",
        "rejected",
        "expired",
        "forgotten",
        "no_store"
      ]
    },
    "approval_mode": {
      "type": "string",
      "enum": [
        "automatic",
        "ask",
        "no_store"
      ]
    },
    "sensitivity": {
      "$ref": "common.schema.json#/$defs/sensitivity"
    },
    "topic": {
      "type": "string",
      "enum": [
        "general",
        "health",
        "finance",
        "legal",
        "relationships",
        "credentials",
        "minors",
        "location",
        "biometric"
      ]
    },
    "ttl": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "policy"
      ],
      "properties": {
        "policy": {
          "type": "string",
          "enum": [
            "never",
            "expires_at",
            "decay"
          ]
        },
        "expires_at": {
          "$ref": "common.schema.json#/$defs/timestamp"
        },
        "decay_days": {
          "type": "integer",
          "minimum": 1,
          "maximum": 3650
        }
      }
    },
    "source": {
      "$ref": "common.schema.json#/$defs/evidence_ref"
    },
    "provenance": {
      "$ref": "common.schema.json#/$defs/provenance"
    },
    "created_at": {
      "$ref": "common.schema.json#/$defs/timestamp"
    },
    "updated_at": {
      "$ref": "common.schema.json#/$defs/timestamp"
    },
    "audit": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "at",
          "action",
          "actor"
        ],
        "properties": {
          "at": {
            "$ref": "common.schema.json#/$defs/timestamp"
          },
          "action": {
            "type": "string",
            "enum": [
              "proposed",
              "approved",
              "rejected",
              "expired",
              "forgotten",
              "exported",
              "no_store",
              "superseded",
              "retrieval_removed",
              "edited"
            ]
          },
          "actor": {
            "$ref": "common.schema.json#/$defs/actor"
          },
          "note": {
            "type": "string",
            "maxLength": 200
          }
        }
      }
    },
    "reason": {
      "type": "string",
      "description": "Why the assistant proposed remembering this, in the user's terms.",
      "minLength": 1,
      "maxLength": 280
    },
    "supersedes": {
      "$ref": "common.schema.json#/$defs/id",
      "description": "An edit is a new entry that supersedes the old one; the old entry moves to forgotten."
    },
    "retrievable": {
      "type": "boolean",
      "description": "False removes the entry from retrieval without deleting audit. Forgotten, rejected, expired and no_store entries are never retrievable."
    },
    "revision": {
      "$ref": "common.schema.json#/$defs/revision"
    },
    "identity": {
      "$ref": "common.schema.json#/$defs/identity"
    }
  }
}