Proposed Standard for .uai/memory-maintenance.uai

Full report

On this page

Executive Summary

This report proposes a machine-verifiable standard for a mandatory file named .uai/memory-maintenance.uai that every deployable agent and every deployable system must carry without exception. The recommended design uses YAML 1.2 or JSON as the authoring syntax, canonicalizes the document into JSON, and validates it with JSON Schema Draft 2020-12. Versioning should follow Semantic Versioning, timestamps should use RFC 3339 date-time strings in UTC, and newly created subject and entry identifiers should use UUIDv7 for time-ordered indexing and auditability. For policy enforcement, the strongest default is: missing file = build failure and deployment denial; invalid file = startup denial for any system with persistent memory; runtime drift = alert plus memory write quarantine or degraded mode, depending on declared profile.

That recommendation aligns with the uploaded UAIX materials, which emphasize project-local memory under .uai/, explicit active-versus-cold memory boundaries, and disciplined memory handling rather than ad hoc persistence. The specification below converts that architectural direction into a concrete, enforceable contract suitable for CI/CD, runtime policy checks, and organizational audit.

The design also builds directly on established security and privacy guidance. JSON Schema Draft 2020-12 is current and explicitly supports modern schema composition and validation features. OPA is designed to separate policy decision-making from policy enforcement and is already documented for CI/CD and runtime use. NIST publications provide the basis for key management, access control families, ABAC, contingency planning, and media sanitization. Official California sources require purpose disclosure, retention disclosure, reasonable necessity and proportionality, and consumer rights such as deletion and limiting the use of sensitive personal information. Official privacy-regulator guidance also reinforces data minimization, storage limitation, periodic review, deletion or anonymization of unnecessary data, and the distinction between pseudonymization and anonymization.

The result is not an existing external standard; it is a proposed organizational standard. But it is intentionally designed so that teams can implement it immediately with off-the-shelf validators, policy engines, audit systems, and deployment gates.

Standards Basis and Scope

The proposed file should be required for any deployable unit that either stores memory, brokers memory, retrieves memory, exports memory, or makes decisions based on retained state. In practice that includes LLM agents, orchestration services, memory APIs, edge devices with local caches or embeddings, worker processes with replayable state, and stateless agents that intentionally declare no persistent memory. Requiring the file even for stateless systems is useful because it forces an explicit declaration that persistence is disabled, which is auditable and prevents accidental state creep.

The format choice should be conservative and automation-friendly. YAML 1.2 is a strict superset of JSON, and the YAML specification explicitly positions its JSON schema support as a lowest common denominator for modern language interoperability. JSON Schema Draft 2020-12 is the right validation target because it has a stable metaschema and modern validation features such as dynamic references, redesigned array keywords, and unevaluated-item semantics. Semantic Versioning provides a clear compatibility contract for the schema itself. RFC 3339 provides a well-specified Internet date-time profile, and RFC 9562 standardizes UUIDv7 as a time-ordered UUID format based on Unix epoch milliseconds.

For policy enforcement and access decisions, ABAC is the most natural default for memory systems because authorization often depends on subject attributes, object attributes, requested operation, and environmental conditions. NIST SP 800-162 defines ABAC in exactly those terms, and OWASP’s authorization guidance recommends least privilege, deny-by-default, validation on every request, and logging around authorization decisions. OPA is an especially strong fit because its purpose is to centralize policy decisions while allowing different enforcement points across the stack.

For security operations, the memory-maintenance file should be treated as a configuration artifact that drives encryption, access control, backup, retention, sanitization, and logging behavior. NIST SP 800-53 identifies access control, audit and accountability, contingency planning, system and communications protection, and PII processing/privacy families as core security and privacy control areas. NIST SP 800-57 provides guidance and best practices for cryptographic key management. NIST’s media sanitization guidance defines sanitization as rendering access to target data infeasible for a given level of effort. OWASP guidance reinforces minimizing sensitive storage, using strong encryption and authenticated modes, separating keys from data, and logging “when, where, who, and what” for auditable events.

Exact File Specification

Normative file rules

The specification should define the following baseline rules:

The top-level schema should be closed (additionalProperties: false) to force deterministic governance, with a single extensibility box (extensions) reserved for organization-specific additions. That pattern keeps the root strict while allowing controlled innovation.

Required and optional top-level fields

Required nested structures

The most important nested fields should be mandated as follows:

Semantic validation rules

These rules should be enforced in addition to syntactic schema validation:

JSON Schema excerpt

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:uai:memory-maintenance:1.0.0",
  "title": "UAI Memory Maintenance",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "spec",
    "schema_version",
    "document_version",
    "subject",
    "governance",
    "memory_model",
    "lifecycle",
    "storage",
    "access_control",
    "security",
    "resilience",
    "privacy",
    "observability",
    "enforcement"
  ],
  "properties": {
    "spec": { "const": "uai.memory-maintenance" },
    "schema_version": {
      "type": "string",
      "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$"
    },
    "document_version": {
      "type": "string",
      "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$"
    },
    "subject": {
      "type": "object",
      "additionalProperties": false,
      "required": ["subject_id", "name", "kind", "statefulness", "tenancy", "deployment_class"],
      "properties": {
        "subject_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
        },
        "name": { "type": "string", "minLength": 1, "maxLength": 200 },
        "kind": { "type": "string", "enum": ["agent", "system"] },
        "statefulness": { "type": "string", "enum": ["stateless", "stateful"] },
        "tenancy": { "type": "string", "enum": ["single-tenant", "multi-tenant"] },
        "deployment_class": { "type": "string", "enum": ["cloud", "edge", "hybrid", "on-prem"] }
      }
    },
    "memory_model": {
      "type": "object",
      "additionalProperties": false,
      "required": ["persistence_enabled", "entry_id_format", "required_entry_fields", "classes"],
      "properties": {
        "persistence_enabled": { "type": "boolean" },
        "entry_id_format": { "type": "string", "enum": ["uuidv7"] },
        "required_entry_fields": {
          "type": "array",
          "items": { "type": "string" },
          "contains": { "const": "entry_id" }
        },
        "classes": {
          "type": "array",
          "minItems": 1,
          "items": { "$ref": "#/$defs/memoryClass" }
        }
      }
    },
    "storage": {
      "type": "object",
      "additionalProperties": false,
      "required": ["primary_store", "consistency", "replication", "conflict_resolution"],
      "properties": {
        "consistency": {
          "type": "object",
          "required": ["model"],
          "properties": {
            "model": { "type": "string", "enum": ["strong", "session", "eventual"] }
          }
        },
        "conflict_resolution": {
          "type": "object",
          "required": ["strategy"],
          "properties": {
            "strategy": {
              "type": "string",
              "enum": ["none", "last-write-wins", "vector-clock", "manual-review"]
            }
          }
        }
      }
    },
    "extensions": { "type": "object" }
  },
  "$defs": {
    "memoryClass": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "class_id",
        "purpose",
        "default_classification",
        "retention_rule",
        "access_policy",
        "encryption_profile",
        "backup_policy"
      ],
      "properties": {
        "class_id": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,63}$" },
        "purpose": { "type": "string", "minLength": 1, "maxLength": 500 },
        "default_classification": {
          "type": "string",
          "enum": ["public", "internal", "confidential", "restricted"]
        },
        "retention_rule": { "type": "string" },
        "access_policy": { "type": "string" },
        "encryption_profile": { "type": "string" },
        "backup_policy": { "type": "string" }
      }
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "subject": { "properties": { "statefulness": { "const": "stateless" } } }
        }
      },
      "then": {
        "properties": {
          "memory_model": { "properties": { "persistence_enabled": { "const": false } } }
        }
      }
    },
    {
      "if": {
        "properties": {
          "subject": { "properties": { "tenancy": { "const": "multi-tenant" } } }
        }
      },
      "then": {
        "properties": {
          "access_control": {
            "required": ["tenant_isolation"],
            "properties": {
              "tenant_isolation": { "not": { "const": "none" } }
            }
          }
        }
      }
    }
  ]
}

This schema shape is consistent with JSON Schema Draft 2020-12’s current metaschema and feature set. YAML can be authored and then normalized into the JSON data model before this schema is applied.

YAML schema excerpt

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "urn:uai:memory-maintenance:1.0.0"
title: "UAI Memory Maintenance"
type: object
additionalProperties: false
required:
  - spec
  - schema_version
  - document_version
  - subject
  - governance
  - memory_model
  - lifecycle
  - storage
  - access_control
  - security
  - resilience
  - privacy
  - observability
  - enforcement
properties:
  spec:
    const: uai.memory-maintenance
  schema_version:
    type: string
  subject:
    type: object
    additionalProperties: false
    required: [subject_id, name, kind, statefulness, tenancy, deployment_class]
  memory_model:
    type: object
    additionalProperties: false
    required: [persistence_enabled, entry_id_format, required_entry_fields, classes]

Sample YAML file

spec: uai.memory-maintenance
schema_version: 1.0.0
document_version: 1.2.0

subject:
  subject_id: 018f22e2-79b0-7cc3-98c4-dc0c0c07398f
  name: customer-support-agent
  kind: agent
  statefulness: stateful
  tenancy: single-tenant
  deployment_class: cloud

governance:
  owner: support-ai-platform
  approvers: [security, privacy, sre]
  last_reviewed_at: 2026-06-01T00:00:00Z
  review_interval_days: 90
  next_review_due_at: 2026-08-30T00:00:00Z

memory_model:
  persistence_enabled: true
  entry_id_format: uuidv7
  required_entry_fields:
    - entry_id
    - class_id
    - state
    - classification
    - created_at
    - modified_at
    - retention_until
    - subject_ref
    - checksum_sha256
  classes:
    - class_id: session
      purpose: Current task context and short-lived conversational state
      default_classification: confidential
      retention_rule: rr-session
      access_policy: ap-workload
      encryption_profile: enc-app
      backup_policy: bp-standard
    - class_id: profile
      purpose: User preferences and stable service settings
      default_classification: restricted
      retention_rule: rr-profile
      access_policy: ap-least-privilege
      encryption_profile: enc-app
      backup_policy: bp-standard
    - class_id: audit
      purpose: Reconstruction of memory mutations and access events
      default_classification: confidential
      retention_rule: rr-audit
      access_policy: ap-audit
      encryption_profile: enc-app
      backup_policy: bp-compliance

lifecycle:
  states: [candidate, active, archived, tombstoned, purged]
  archival:
    enabled: true
    searchable_metadata_only: true
  retention_rules:
    - rule_id: rr-session
      trigger: created_at
      archive_after: P7D
      delete_after: P30D
      legal_hold_overrides: true
    - rule_id: rr-profile
      trigger: modified_at
      archive_after: P180D
      delete_after: P730D
      legal_hold_overrides: true
    - rule_id: rr-audit
      trigger: created_at
      archive_after: P365D
      delete_after: P2555D
      legal_hold_overrides: true
  deletion:
    mode: crypto-erase
    tombstone_ttl: P7D
    purge_sla: P7D

storage:
  primary_store:
    kind: postgres
    residency: us-central
  consistency:
    model: strong
  replication:
    enabled: true
    topology: multi-region
    sync_mode: synchronous
    max_replication_lag_seconds: 5
  conflict_resolution:
    strategy: none

access_control:
  authorization_model: abac
  deny_by_default: true
  tenant_isolation: none
  access_policies:
    - policy_id: ap-workload
      allowed_roles: [runtime, sre-break-glass]
      required_attributes:
        purpose: support
    - policy_id: ap-least-privilege
      allowed_roles: [runtime]
    - policy_id: ap-audit
      allowed_roles: [security-audit, runtime]
  break_glass:
    enabled: true
    approval_required: true
    max_duration_minutes: 60

security:
  encryption_at_rest:
    required: true
    algorithm: AES-256-GCM
  encryption_in_transit:
    required: true
    minimum: TLS1.2
  integrity:
    checksum: SHA-256
  key_management:
    provider: kms
    rotation_interval_days: 90
    separate_keys_per_environment: true
  inline_secrets_forbidden: true

resilience:
  backups:
    enabled: true
    frequency: P1D
    retention: P35D
    immutable: true
  restore_testing:
    interval: P30D
    target_rto: PT4H
    target_rpo: PT1H

privacy:
  personal_data_present: true
  lawful_basis: contract
  minimization_required: true
  pseudonymization: true
  retention_limit_enforced: true
  dsr:
    erasure_supported: true
    correction_supported: true
    export_supported: true
    response_sla_days: 30

observability:
  audit_log:
    enabled: true
    pii_in_logs: minimized
    retention: P365D
    required_events:
      - memory.create
      - memory.read
      - memory.update
      - memory.archive
      - memory.delete.requested
      - memory.delete.completed
      - policy.break_glass
  metrics:
    - memory_entries_total
    - memory_archival_backlog
    - memory_deletion_backlog
    - replication_lag_seconds
    - backup_restore_success_rate
    - dsr_open_requests
  alerts:
    - missing_spec_file
    - invalid_spec_file
    - overdue_review
    - backup_failure
    - deletion_sla_breach
    - replication_lag_breach

enforcement:
  bootstrap:
    required: true
    startup_block_on_invalid: true
  ci:
    schema_validation: required
    policy_validation: required
    signature_required: true
  runtime:
    periodic_revalidation: PT1H
    drift_action: quarantine-writes
  os_hooks:
    watch_file_changes: true
    unauthorized_change_action: alert-and-quarantine

Sample JSON file

{
  "spec": "uai.memory-maintenance",
  "schema_version": "1.0.0",
  "document_version": "1.0.0",
  "subject": {
    "subject_id": "018f22e2-79b0-7cc3-98c4-dc0c0c07398f",
    "name": "stateless-router-agent",
    "kind": "agent",
    "statefulness": "stateless",
    "tenancy": "single-tenant",
    "deployment_class": "cloud"
  },
  "governance": {
    "owner": "platform-routing",
    "approvers": ["security"],
    "last_reviewed_at": "2026-06-01T00:00:00Z",
    "review_interval_days": 90,
    "next_review_due_at": "2026-08-30T00:00:00Z"
  },
  "memory_model": {
    "persistence_enabled": false,
    "entry_id_format": "uuidv7",
    "required_entry_fields": ["entry_id", "created_at"],
    "classes": [
      {
        "class_id": "ephemeral",
        "purpose": "In-process request correlation only",
        "default_classification": "internal",
        "retention_rule": "rr-ephemeral",
        "access_policy": "ap-runtime-only",
        "encryption_profile": "enc-none",
        "backup_policy": "bp-none"
      }
    ]
  },
  "lifecycle": {
    "states": ["candidate", "active", "purged"],
    "archival": { "enabled": false, "searchable_metadata_only": true },
    "retention_rules": [
      {
        "rule_id": "rr-ephemeral",
        "trigger": "created_at",
        "archive_after": "P0D",
        "delete_after": "PT0S",
        "legal_hold_overrides": false
      }
    ],
    "deletion": { "mode": "provider-delete", "tombstone_ttl": "PT0S", "purge_sla": "PT1M" }
  },
  "storage": {
    "primary_store": { "kind": "none", "residency": "not-applicable" },
    "consistency": { "model": "strong" },
    "replication": { "enabled": false, "topology": "single-region", "sync_mode": "synchronous", "max_replication_lag_seconds": 0 },
    "conflict_resolution": { "strategy": "none" }
  },
  "access_control": {
    "authorization_model": "abac",
    "deny_by_default": true,
    "tenant_isolation": "none",
    "access_policies": [{ "policy_id": "ap-runtime-only", "allowed_roles": ["runtime"] }],
    "break_glass": { "enabled": false, "approval_required": false, "max_duration_minutes": 0 }
  },
  "security": {
    "encryption_at_rest": { "required": false, "algorithm": "none" },
    "encryption_in_transit": { "required": true, "minimum": "TLS1.2" },
    "integrity": { "checksum": "SHA-256" },
    "key_management": { "provider": "none", "rotation_interval_days": 0, "separate_keys_per_environment": false },
    "inline_secrets_forbidden": true
  },
  "resilience": {
    "backups": { "enabled": false, "frequency": "P0D", "retention": "P0D", "immutable": false },
    "restore_testing": { "interval": "P0D", "target_rto": "PT0S", "target_rpo": "PT0S" }
  },
  "privacy": {
    "personal_data_present": false,
    "lawful_basis": "not-applicable",
    "minimization_required": true,
    "pseudonymization": false,
    "retention_limit_enforced": true,
    "dsr": { "erasure_supported": false, "correction_supported": false, "export_supported": false, "response_sla_days": 0 }
  },
  "observability": {
    "audit_log": { "enabled": true, "pii_in_logs": "prohibited", "retention": "P30D", "required_events": ["policy.load"] },
    "metrics": ["policy_load_success"],
    "alerts": ["missing_spec_file", "invalid_spec_file"]
  },
  "enforcement": {
    "bootstrap": { "required": true, "startup_block_on_invalid": true },
    "ci": { "schema_validation": "required", "policy_validation": "required", "signature_required": true },
    "runtime": { "periodic_revalidation": "PT1H", "drift_action": "terminate" },
    "os_hooks": { "watch_file_changes": true, "unauthorized_change_action": "alert-and-terminate" }
  }
}

Memory Lifecycle and Storage Rules

A useful lifecycle model for memory entries is: candidate → active → archived → tombstoned → purged, with side states for rejected and legal_hold. Every entry should be born with immutable creation metadata, classification, purpose binding, and integrity metadata before it can be promoted to active use. If the system supports archival, archival should preserve minimum metadata necessary for retrieval, legal response, and audit, while minimizing the searchable payload surface. Deletion should be a two-step process: first tombstone for replication and consistency safety, then purge by provider delete, cryptographic erase, or secure sanitization according to the declared deletion mode. NIST’s sanitization guidance defines the goal as rendering access infeasible; regulator guidance also emphasizes periodic review, deletion or anonymization of data no longer needed, and documented retention schedules.

flowchart LR
    A[Candidate] -->|validation, classification, checksum, purpose binding| B[Active]
    A -->|validation failure| X[Rejected]
    B -->|archive_after reached| C[Archived]
    B -->|delete_after reached| D[Tombstoned]
    C -->|delete_after reached or DSR erasure| D
    B -->|legal hold| H[Legal hold]
    C -->|legal hold| H
    H -->|hold released| C
    D -->|replication settled + backup expiry + purge job| E[Purged]

Creation, retention, archival, deletion

Creation rules should require these minimum entry attributes at write time: entry_id, class_id, state, classification, created_at, modified_at, retention_until, subject_ref, origin, and checksum_sha256. created_at and modified_at should use UTC RFC 3339 date-time strings, and identifiers should be UUIDv7 where entries are generated by the platform rather than imported. That provides sortable identifiers and auditable timestamps.

Retention should be rule-driven, not ad hoc. Each memory class should bind to a named retention rule with a trigger clock such as created_at, modified_at, or conversation_closed_at. Privacy guidance is explicit that organizations should be able to justify how long they keep personal data, document standard retention periods where possible, and erase or anonymize data they no longer need. California law also requires businesses to disclose retention periods or the criteria used to determine them and prohibits retention longer than reasonably necessary for the disclosed purpose.

Archival should never be synonymous with indefinite retention. The spec should require archive_after, delete_after, and legal_hold_overrides. Archived data should carry the same deletion schedule unless a lawful hold or documented exception applies. If searchable_metadata_only = true, the archive must index only bounded metadata fields such as entry_id, class_id, created_at, subject_ref, and classification, leaving full payload retrieval to a privileged path.

Deletion should be split into three policy layers: logical delete, replication/tombstone window, and physical purge. Logical deletion creates a tombstone with deletion reason and actor. The tombstone lives only long enough to synchronize replicas and prevent resurrection. Physical purge then runs by one of three declared mechanisms: provider delete, cryptographic erase, or secure sanitization. Stronger systems should prefer crypto-erase or verified secure-delete semantics for stores under direct control.

Access control, encryption, backups, replication, consistency, conflict resolution

Authorization should default to ABAC with deny-by-default and request-time evaluation. That is especially important for memory because access should usually depend on actor role, tenant, purpose, environment, object classification, and sometimes legal hold state. NIST defines ABAC precisely as authorization determined from subject, object, operation, and environment attributes against policy; OWASP further recommends least privilege, deny-by-default, and permission validation on every request.

Encryption policy should distinguish at rest, in transit, and optionally in use. At-rest encryption should be required for any persistent memory. At-transit encryption should be mandatory for all networked access paths. Key rotation, separation of keys from data, and inventory of key-provider ownership should be explicitly declared. NIST key-management guidance and OWASP cryptographic-storage guidance support that model, with OWASP also stressing that the best way to protect sensitive data is not to store it unnecessarily in the first place.

Backups should be policy-driven and testable. The file should state whether backups are enabled, their frequency, retention, immutability, and restore-test interval. NIST treats contingency planning and backup-related controls as first-class security concerns, and key-management guidance also explicitly intersects with backup handling. The practical rule should be: no backup policy declaration, no persistent rollout.

Replication and consistency must be explicit because memory systems differ radically here. Some need strong consistency; others can accept eventual consistency. When eventual consistency is declared, the file must also declare a conflict policy. A reasonable default is none for strong consistency, last-write-wins only for low-value ephemeral state, and vector-clock or manual-review for higher-value user data or multi-writer replicated edge scenarios.

Logging and auditability

Every memory system should log create, read, update, archive, delete-request, delete-complete, restore, replication-conflict, key-rotation, break-glass, and policy-load events. OWASP’s logging guidance emphasizes consistency, security-event logging, audit trails for data addition/modification/deletion, logging of higher-risk functions, access to sensitive data, encryption-key activities, and recording “when, where, who and what” for each event.

Enforcement and Integration

The policy mandate should be simple:

Every deployable agent and every deployable system MUST contain .uai/memory-maintenance.uai. No exceptions. Missing or invalid files block promotion to any environment.

That is stronger than “best practice,” and it should be enforced at four layers: source control and CI, artifact build and signing, bootstrap/startup, and runtime drift monitoring.

flowchart TD
    A[Repository or device manifest] --> B[Presence check for .uai/memory-maintenance.uai]
    B -->|missing| Z[Fail immediately]
    B -->|present| C[Parse YAML or JSON]
    C --> D[JSON Schema validation]
    D --> E[Semantic lint rules]
    E --> F[OPA or Conftest policy evaluation]
    F --> G[Artifact signing / attestation]
    G --> H[Bootstrap loads spec before memory init]
    H --> I[Runtime periodic revalidation]
    I --> J[OS or file-watch drift detection]
    J --> K[Audit log + alert + quarantine / terminate]

OPA is particularly well suited here because it is explicitly built to unify policy enforcement across the stack and to decouple decision-making from enforcement. Its documentation calls out use in CI/CD pipelines, Kubernetes, microservices, API gateways, and more. Policy tests can be automated with opa test, and the documentation explicitly notes --fail-on-empty as useful in CI/CD so that missing test execution does not silently pass. Conftest is a practical complement because it is designed to test structured configuration data, supports JSON and YAML, and can return deny, warn, or structured violation results.

Recommended enforcement points

Failure modes

The default failure mode should depend on declared risk, but the file requirement itself never relaxes.

Example OPA policy

package uai.memory

deny contains msg if {
  not input.files[".uai/memory-maintenance.uai"]
  msg := "missing required file .uai/memory-maintenance.uai"
}

deny contains msg if {
  file := input.parsed[".uai/memory-maintenance.uai"]
  file.spec != "uai.memory-maintenance"
  msg := "invalid spec identifier"
}

deny contains msg if {
  file := input.parsed[".uai/memory-maintenance.uai"]
  file.subject.statefulness == "stateless"
  file.memory_model.persistence_enabled
  msg := "stateless subjects cannot enable persistence"
}

deny contains msg if {
  file := input.parsed[".uai/memory-maintenance.uai"]
  file.subject.tenancy == "multi-tenant"
  file.access_control.tenant_isolation == "none"
  msg := "multi-tenant subjects must declare tenant isolation"
}

This kind of policy is directly aligned with OPA and Conftest’s documented configuration-testing model.

OS-level hooks

OS-level or filesystem hooks should not be the primary policy mechanism, but they are valuable for tamper detection. On Linux, kernel fanotify is explicitly documented as a file-system monitoring framework intended for monitoring tools and early error detection/recovery workflows. In practice, a hardened implementation can use platform-native file watches to detect unauthorized changes to .uai/memory-maintenance.uai, compare its digest against the loaded attested version, and quarantine writes if it changes without an approved rollout path.

Migration and Compatibility

The schema should use a two-version model:

Versioning should follow SemVer rules: incompatible schema changes increment the major version; additive backward-compatible changes increment the minor version; clarifications and bug fixes increment the patch version. SemVer is explicit about those meanings.

Compatibility rules

A practical compatibility contract is:

For that reason, the root object should stay closed, and experimental organization-specific data should be confined to extensions. That allows compatibility without turning the standard into an unbounded free-for-all.

Migration strategy

The safest rollout model is dual-read, single-write:

1. Readers support current and previous major line during the migration window.
2. Writers emit only the current major line.
3. Migration jobs transform old files before deploy or promote.
4. Policy engines reject artifacts that still contain sunset versions after the deadline.

JSON Patch is a useful migration representation because it is a standard for sequential patch operations against JSON documents.

Example migration manifest:

[
  { "op": "add", "path": "/compatibility", "value": { "migrated_from": "0.9.0" } },
  { "op": "replace", "path": "/schema_version", "value": "1.0.0" },
  { "op": "add", "path": "/enforcement/runtime/drift_action", "value": "quarantine-writes" }
]

Backward-compatible defaults

Recommended default policy for schema evolution:

• Keep major version 1.x closed to field removals.
• Allow only additive optional fields in minor versions.
• Sunset each major version with an explicit compatible_read_until date.
• Require migration tests and golden fixtures for every schema change.
• Publish a machine-readable changelog and migration guide with each non-patch release.

Security Privacy and Compliance

The most important security principle is that memory is not just data storage; it is also a decision surface. If an attacker can read, modify, replay, or resurrect memory, they can often steer the system. That is why the spec should require least privilege, deny-by-default access control, encryption at rest and in transit, integrity metadata, strong logging, signed policy artifacts, and purge semantics that are more rigorous than simply setting a delete flag. NIST and OWASP guidance strongly support those controls.

For privacy, the file should force teams to declare whether personal data is present and, if so, the lawful basis, minimization approach, retention limits, and data-subject-right handling. Official guidance on data minimization says collected personal data must be adequate, relevant, and limited to what is necessary for the purpose; it also says organizations should periodically review data and delete what they no longer need. Storage limitation guidance similarly requires that organizations justify retention periods, document them where possible, and erase or anonymize data when no longer needed.

Pseudonymization should be treated as a risk-reduction control, not as a declaration that privacy law no longer applies. Official regulator guidance is explicit that pseudonymized data is still personal data and can be re-attributed with additional information if that information exists; that additional information must be kept separately and protected with technical and organizational controls.

For California compliance, the file should support at least these mappings:

Those mappings are grounded in official California law and guidance: the Civil Code requires disclosure of categories, purposes, and retention periods or criteria, limits retention to what is reasonably necessary, and requires reasonable security procedures; the Attorney General’s CCPA guidance describes rights to know, delete, correct, opt out, and limit use of sensitive personal information.

Recommended default privacy posture

The default organization-wide posture should be:

• privacy.personal_data_present: true unless a system is demonstrably free of personal data.
• privacy.minimization_required: true.
• privacy.retention_limit_enforced: true.
• security.inline_secrets_forbidden: true.
• access_control.deny_by_default: true.
• observability.audit_log.pii_in_logs: minimized or prohibited.
• lifecycle.archival.searchable_metadata_only: true.
• resilience.backups.immutable: true for persistent systems.

That default is conservative and maps cleanly to data minimization, storage limitation, reasonable security, and audit expectations.

Templates Testing and Organizational Rollout

Recommended default policy template

A good default organizational mandate can itself be represented declaratively:

policy_id: UAI-MEM-001
title: Mandatory Memory Maintenance Specification
requirement: Every deployable agent and system MUST include .uai/memory-maintenance.uai
scope:
  includes: [agents, systems, services, workers, device-firmware, memory-apis]
  exceptions: none
enforcement:
  repo: fail-on-missing
  ci: fail-on-missing-or-invalid
  deploy: deny-on-missing-or-invalid
  runtime: block-memory-init-on-invalid
review:
  cadence_days: 90
audit:
  retain_evidence_for: P365D

Templates by agent and system profile

Profile-specific deltas:

# Multi-tenant delta
subject:
  tenancy: multi-tenant
access_control:
  tenant_isolation: namespace
memory_model:
  required_entry_fields:
    - tenant_id
storage:
  consistency:
    model: session
  conflict_resolution:
    strategy: vector-clock

# Edge-device delta
subject:
  deployment_class: edge
storage:
  primary_store:
    kind: device-flash
  consistency:
    model: eventual
  replication:
    enabled: true
    topology: edge-sync
    sync_mode: asynchronous
    max_replication_lag_seconds: 86400
  conflict_resolution:
    strategy: manual-review
resilience:
  backups:
    enabled: false
privacy:
  pseudonymization: true

Validation suites and tests

Testing should be layered:

OPA documents policy testing and coverage, and Conftest documents configuration testing plus policy verification workflows suitable for CI.

Monitoring metrics

The file should drive an expected metric set; if the runtime cannot emit these metrics, the system should be considered partially non-compliant.

Organizational rollout plan

A practical rollout can be done in four phases.

Foundation. Publish the schema, default templates, validation CLI, and CI policy packages. At this stage, start collecting coverage only: which repos, services, and devices have the file and which do not.

Soft enforcement. Enable CI warnings for missing or invalid files, plus runtime logging of missing specs in non-production. Require every new project to adopt the file from day one.

Hard enforcement. Turn warnings into build failures for new services and production promotion failures for existing services. Persistent memory systems should not start without a valid file. Artifact signing should include the spec digest in attestation metadata.

Audit and sustainment. Add organization-wide scans, quarterly review attestations, restore-drill evidence, and privacy/compliance scorecards. Unknown or stale schema lines should trigger remediation work items automatically.

The recommended business rule is simple: no .uai/memory-maintenance.uai, no production.

Open questions and limitations

The specification above is immediately implementable, but a few items still require organization-specific decisions:

• Exact retention durations by memory class should be set with legal, privacy, and records-management input rather than copied blindly across all systems.
• Cross-border data residency and transfer controls are jurisdiction-specific and should be reflected in storage.primary_store.residency and any replication targets.
• The direct EUR-Lex GDPR text was not accessible in this environment, so the GDPR-oriented recommendations here are grounded in official regulator guidance that quotes materially equivalent data-minimization, storage-limitation, and pseudonymization principles, plus official California statutory and AG sources for CCPA/CPRA obligations.

The main conclusion does not depend on those open items: the file should be mandatory, schema-validated, policy-enforced, and loaded before any memory subsystem can operate.