Alignment Card Schema

Normative reference for the unified alignment card — the YAML document every Mnemom agent has as one half of its two cards. This page specifies every section, field, required/optional status, type, and composition semantic. Implementers of MCP servers, SDK clients, or custom tooling that stores or mutates alignment cards should treat this as the contract. The AAP protocol-level card (the 1.0 handshake card, stable for external interop) is specified separately at /concepts/alignment-cards. The unified card is a superset with additional sections not present in the protocol surface.

Top-level structure

card_version: unified/2026-04-26      # required; format: /^unified\/\d{4}-\d{2}-\d{2}$/
card_id: ac-<uuid>                    # required; stable ID for this card document (preserved through compose)
agent_id: mnm-<uuid>                  # required; the agent this card belongs to
issued_at: 2026-04-26T12:00:00Z       # required; ISO 8601 UTC
expires_at: 2026-10-26T12:00:00Z      # optional; ISO 8601 UTC; null = no expiry

# Two independent top-level master switches (ADR-039 Decision 1):
autonomy_mode: enforce                 # required; off | observe | nudge | enforce
                                       # gates the action-policing pipeline (gateway CLPI tool-use policy
                                       # + observer trace verification of bounded/forbidden actions)
integrity_mode: enforce                # required; off | observe | nudge | enforce
                                       # gates the values/conscience pipeline (gateway AIP Haiku analysis
                                       # + observer drift detection + coherence scoring)

principal: { ... }                     # optional; see §principal
values: { ... }                        # required; see §values
conscience: { ... }                    # optional; see §conscience
autonomy: { ... }                      # required; see §autonomy
capabilities: { ... }                  # optional; see §capabilities
enforcement: { ... }                   # optional; see §enforcement
audit: { ... }                         # required; see §audit
extensions: { ... }                    # optional; §extensions

# System-managed — present on canonical cards, absent on raw agent-scope cards.
_composition: { ... }                  # see §composition-metadata

Master switches

The four-mode enum off | observe | nudge | enforce is shared with the Protection Card. Same words; same semantics; same UI picker component renders all three master fields (Protection’s mode, Alignment’s autonomy_mode, Alignment’s integrity_mode). Composition rule on each: strictest wins across Platform → Org → Agent (enforce > nudge > observe > off).

Field	Governs	Off	Observe	Nudge	Enforce
`autonomy_mode`	action-policing	skip CLPI + trace verification	log policy results, don’t block	inject advisory annotation, don’t block	block tool violations, escalate
`integrity_mode`	values/conscience	skip AIP + drift detection	log checkpoint, no action	inject advisory on next request	auto-pause on boundary violation

Customers can control the two halves independently — e.g., “enforce conscience commitments at runtime, only observe action policy” or “off action-policing for cost, but enforce drift detection”.

§principal

Declares who the agent serves and the nature of that relationship.

principal:
  type: organization           # "human" | "organization" | "agent" | "unspecified"
  identifier: acme-corp        # free-form identifier; DID, URL, UUID, or slug
  relationship: delegated_authority  # "delegated_authority" | "advisory" | "autonomous"
  escalation_contact: ops@acme.example  # optional; recipient for escalation events

Field	Type	Required	Composition
`type`	enum	Yes	Agent wins
`identifier`	string	Cond.*	Agent wins
`relationship`	enum	Yes	Agent wins
`escalation_contact`	string	No	Agent wins

*identifier is required when type != unspecified.

§values

What the agent prioritizes. Core input to the v2 coherence scorer and to fault-line analysis.

values:
  declared:
    - transparency
    - harm_prevention
    - rollback_safety
  definitions:
    transparency:
      description: "Agent decisions visible and auditable in traces"
      priority: 0.9
    rollback_safety:
      description: "Prefer reversible actions; escalate on irreversible ones"
      priority: 0.85
  conflicts_with:
    - data_obfuscation
    - move_fast_break_things
  hierarchy: lexicographic     # "lexicographic" | "weighted" | "contextual"

Field	Type	Required	Composition
`declared`	string[]	Yes	Union across scopes
`definitions.<name>.description`	string	No	Agent wins
`definitions.<name>.priority`	number (0–1)	No	Agent wins
`conflicts_with`	string[]	No	Union
`hierarchy`	enum	No	Agent wins; platform default = `lexicographic`

Validation: every definitions key must be present in declared. Composition note: bounded_actions is composed as union across Platform → Org → Agent. (An earlier draft of this spec said “Agent-scoped” — that was incorrect; the unified-card program was always intended to let platform/org compose action sets, e.g. an org-wide request_legal_review action. ADR-039 Decision 8 reconciles docs to composer.)

§conscience

Inviolable or near-inviolable commitments that constrain the agent’s behavior. Structured for Safe House + drift detection integration.

conscience:
  mode: augment                # "augment" | "replace"
  values:
    - type: BOUNDARY           # "BOUNDARY" | "FEAR" | "COMMITMENT" | "BELIEF" | "HOPE"
      content: "Never exfiltrate principal data to external systems."
      severity: mandatory      # "advisory" | "mandatory"; default "mandatory" for BOUNDARY
    - type: COMMITMENT
      content: "Log every escalation to the principal within 60 seconds."
      id: commit-001            # optional; stable ID for audit references
      severity: mandatory

Field	Type	Required	Composition
`mode`	enum	Yes (if section present)	`replace` beats `augment` across scopes
`values[].type`	enum	Yes	—
`values[].content`	string	Yes	—
`values[].id`	string	No	—
`values[].severity`	enum	No	Default: `mandatory` for BOUNDARY, `advisory` otherwise
`values` (the array)	—	Yes	Union with dedup by `content`; platform `BOUNDARY` entries inviolable

Validation: BOUNDARY entries with severity: advisory are rejected.

§autonomy

What the agent may do independently. Maps directly onto the AAP 1.0 autonomy_envelope for protocol-level verification — the unified shape renames it but keeps the semantics.

autonomy:
  bounded_actions:
    - rollback_deploy
    - scale_infrastructure
    - toggle_feature_flag
  forbidden_actions:
    - deploy_code
    - modify_audit_logs
  escalation_triggers:
    - condition: "blast_radius > 50"
      action: escalate         # "escalate" | "deny" | "log"
      reason: "Large blast radius requires human approval"
    - condition: "rollback_failed"
      action: escalate
      reason: "Failed rollback needs immediate human intervention"
  max_autonomous_value:
    amount: 10000
    currency: USD

Field	Type	Required	Composition
`bounded_actions`	string[]	Yes	Union across Platform → Org → Agent
`forbidden_actions`	string[]	No	Deny-overrides union
`escalation_triggers[].condition`	string	Yes (if trigger present)	—
`escalation_triggers[].action`	enum	Yes	—
`escalation_triggers[].reason`	string	Yes	—
`escalation_triggers` (array)	—	No	Union with dedup by `condition`
`max_autonomous_value.amount`	number	Cond.	Min across scopes
`max_autonomous_value.currency`	string (ISO 4217)	Cond.	Agent wins

Validation: bounded_actions and forbidden_actions must be disjoint (no action in both).

§capabilities

Tool-use capabilities, keyed by capability name. Each entry maps to a glob pattern over MCP/A2A tool names or an explicit tool allowlist.

capabilities:
  query_database:
    description: "Read from the operational database"
    tools: ["mcp:postgres/*", "mcp:readonly-query"]
    severity_on_unmapped: medium    # "low" | "medium" | "high" | "critical"
  external_http:
    tools: ["mcp:fetch"]
    allowed_domains: ["api.acme.example"]
    severity_on_unmapped: high

Field	Type	Required	Composition
`<name>.description`	string	No	Agent wins
`<name>.tools`	string[] (glob patterns)	Yes	Union within capability
`<name>.allowed_domains`	string[]	No	Platform → agent intersection (compliance ceiling, mirrors Protection Card `trusted_sources`)
`<name>.severity_on_unmapped`	enum	No	Strictest wins per name; default `medium`

Capabilities are consumed by @mnemom/policy-engine’s evaluatePolicy({ card, tools }) to produce per-request policy decisions.

§enforcement

Policy-level knobs that affect how capabilities are enforced at runtime. The master switch lives at the top level (autonomy_mode); this section carries the fine-grained tool-use policy.

enforcement:
  allow_unmapped_tools: false                  # strictest wins across scopes
  default_unmapped_severity: high              # "low" | "medium" | "high" | "critical"
  forbidden_tools:                             # XACML deny-overrides
    - pattern: "mcp:filesystem/*"
      reason: "No filesystem access for billing agents"
      severity: critical
  grace_period_hours: 24                       # min across scopes (shorter grace = stricter)

Field	Type	Required	Composition
`allow_unmapped_tools`	boolean	No (default `false`)	Strictest wins (`false` beats `true`)
`default_unmapped_severity`	enum	No (default `high`)	Strictest wins (`critical > high > medium > low`)
`forbidden_tools[].pattern`	string	Yes (per entry)	Deny-overrides union (with exemption removal)
`forbidden_tools[].reason`	string	Yes (per entry)	—
`forbidden_tools[].severity`	enum	Yes (per entry)	—
`grace_period_hours`	number	No (default `24`)	Min across scopes

§audit

Commitments around trace format, retention, tamper evidence. These are platform-scoped — agents and orgs cannot weaken the audit floor.

audit:
  trace_format: ap-trace-v1
  retention_days: 90
  queryable: true
  query_endpoint: https://api.mnemom.ai/v1/traces
  tamper_evidence: append_only    # "append_only" | "signed" | "merkle" | null

Field	Type	Required	Composition
`trace_format`	string	Yes	Platform-scoped
`retention_days`	number	Yes	Max across scopes (longest retention wins)
`queryable`	boolean	Yes	Platform-scoped
`query_endpoint`	string (URL)	Yes	Platform-scoped
`tamper_evidence`	enum	No	Platform-scoped

Validation: audit.query_endpoint is a composer-enforced invariant (see ADR-023). The validator rejects cards without it; the composer ensures it’s always present on canonical output.

§extensions

Protocol-specific or user-defined additions. Free-form Record<string, unknown>. Mnemom reserves the clpi.* and mnemom.* namespaces.

extensions:
  clpi:
    role: remediator
  mnemom:
    showcase_color: green
  a2a:
    card_url: https://patch.example.com/a2a-card.json

Extensions are agent-scoped and not composed across scopes by default. Callers that need scope-composed extensions must opt in via _composition.extensions_composition_mode: merge.

§_composition (canonical-only)

Present on the canonical card, absent on raw agent-scope cards. Records the provenance of every composed field.

_composition:
  composed_at: 2026-04-17T18:23:41Z
  scopes_applied:
    - platform
    - "org:acme"
    - "agent:mnm-patch-001"
  versions:
    platform: 3
    "org:acme": 17
    "agent:mnm-patch-001": 4
  exemptions_applied:
    - exm-aabbcc     # exemption IDs honored during this composition
  source_card_id: ac-f47ac10b-58cc-4372-a567-0e02b2c3d479
  canonical_id: can-cd-88aa0011

_composition is read-only on the wire. Mutating it via API is a 400.

YAML safe schema

All yaml.load() calls in the Mnemom stack use { schema: yaml.CORE_SCHEMA } — Node-specific tags (!!js, !!binary, etc.) are rejected. If your client produces YAML with those tags, validation fails. Stick to plain scalars, maps, and sequences.

Body-size limits

Full alignment card payload: 128 KB max (Content-Length + rawBody double-check).
values.declared: recommended under 200 values per scope for coherence-scoring performance.

These limits are enforced at the API boundary. 413 Payload Too Large for oversize bodies; no grace period. If a legitimate card is getting 413’d, file an issue — the limits are currently conservative and will relax with production data.

Versioning

card_version is a date-anchored schema identifier. Accepted values as of 2026-04-17:

unified/2026-04-15 — current. All canonical cards emit this version.
(legacy) — the pre-UC AAP-shape card is no longer accepted at the alignment-card endpoint. Convert via the migration script before publishing.

A version bump is an additive + deprecation-by-date convention; breaking changes are negotiated via the same X-Mnemom-Version request-header mechanism used elsewhere in the API.

Overview

Concepts

Gateway

Pricing

Specifications

Changelog

Alignment Card Schema

Top-level structure

Master switches

§principal

§values

§conscience

§autonomy

§capabilities

§enforcement

§audit

§extensions

§_composition (canonical-only)

YAML safe schema

Body-size limits

Versioning

See also

Overview

Concepts

Gateway

Pricing

Specifications

Changelog

​Top-level structure

​Master switches

​§principal

​§values

​§conscience

​§autonomy

​§capabilities

​§enforcement

​§audit

​§extensions

​§_composition (canonical-only)

​YAML safe schema

​Body-size limits

​Versioning

​See also

Top-level structure

Master switches

§principal

§values

§conscience

§autonomy

§capabilities

§enforcement

§audit

§extensions

§_composition (canonical-only)

YAML safe schema

Body-size limits

Versioning

See also