Alignment Card Management

Alignment Cards are structured declarations of your agent’s values, boundaries, and behavioral commitments. Every agent connected via the Mnemom Gateway gets a default card automatically — but that default card uses generic values and minimal autonomy. It does not represent what your agent actually does or cares about. Customizing your card is how you make alignment verification meaningful. A card that accurately reflects your agent’s real values and tools produces useful integrity scores. A generic card produces noise.

Templates use the unified card shape. The JSON/YAML templates on this page use the unified card format — the shape mnemom card validate and PUT /v1/alignment/agent/{id} both expect. A card copied verbatim from any template below will validate and publish without modification. See Alignment Card Schema for the full normative spec.For protocol-level interop with external agents (A2A, MCP), the same unified shape is also the AAP protocol-level card specified at /concepts/alignment-cards. Production cards you manage here are a superset that adds conscience, capabilities, enforcement, and integrity_config on top of that protocol surface.

Creating a card

An alignment card is a structured document that follows the AAP specification. You can author cards in JSON or YAML — the API accepts both formats and stores cards as JSON internally.

Start from the template

Every card requires five blocks: identity, principal, values, autonomy, and audit — plus two top-level master switches (autonomy_mode and integrity_mode) that control action-policing and values verification independently.

JSON
YAML

{
  "card_version": "unified/2026-04-15",
  "card_id": "ac-YOUR_CARD_ID",
  "agent_id": "YOUR_AGENT_ID",
  "issued_at": "2026-02-21T00:00:00Z",
  "expires_at": "2026-08-21T00:00:00Z",

  "autonomy_mode": "observe",
  "integrity_mode": "observe",

  "principal": {
    "type": "human",
    "identifier": "you@example.com",
    "relationship": "delegated_authority",
    "escalation_contact": "mailto:you@example.com"
  },

  "values": {
    "declared": [],
    "hierarchy": "lexicographic"
  },

  "autonomy": {
    "bounded_actions": [],
    "escalation_triggers": [],
    "forbidden_actions": []
  },

  "audit": {
    "trace_format": "ap-trace-v1",
    "retention_days": 90,
    "queryable": true,
    "query_endpoint": "https://api.mnemom.ai/v1/traces",
    "tamper_evidence": "append_only"
  }
}

card_version: "unified/2026-04-15"
card_id: ac-YOUR_CARD_ID
agent_id: YOUR_AGENT_ID
issued_at: "2026-02-21T00:00:00Z"
expires_at: "2026-08-21T00:00:00Z"

autonomy_mode: observe
integrity_mode: observe

principal:
  type: human
  identifier: you@example.com
  relationship: delegated_authority
  escalation_contact: mailto:you@example.com

values:
  declared: []
  hierarchy: lexicographic

autonomy:
  bounded_actions: []
  escalation_triggers: []
  forbidden_actions: []

audit:
  trace_format: ap-trace-v1
  retention_days: 90
  queryable: true
  query_endpoint: https://api.mnemom.ai/v1/traces
  tamper_evidence: append_only

Choose values

values.declared accepts any value identifier — validation is shape-only (a non-empty string or {id, ...params}), so nothing stops you from inventing one. What actually belongs there, the recommended baseline, and the distinction between a value and a role/capability descriptor are covered in Alignment Cards § What belongs in values.declared — read that before picking your list. For a value outside that baseline, add a definitions entry so it’s self-documenting:

{
  "values": {
    "declared": ["transparency", "honesty", "harm_prevention", "editorial_independence"],
    "definitions": {
      "editorial_independence": {
        "name": "Editorial Independence",
        "description": "Maintain independence from commercial interests when producing content",
        "priority": 4
      }
    },
    "hierarchy": "lexicographic"
  }
}

Only declare values your agent actually applies. Declaring fairness but never referencing it in decisions produces verification warnings.

Define the autonomy block

List the actions your agent actually takes as bounded_actions. These should match your agent’s real tools and capabilities:

{
  "autonomy": {
    "bounded_actions": ["inference", "read", "write", "edit", "web_fetch", "web_search"],
    "escalation_triggers": [
      {
        "condition": "named_entity_critical",
        "action": "escalate",
        "reason": "Critical claims about named entities require human review"
      },
      {
        "condition": "legal_claims_present",
        "action": "escalate",
        "reason": "Legal assertions require legal review"
      }
    ],
    "forbidden_actions": ["fabricate_sources", "impersonate_human", "exfiltrate_data"]
  }
}

Escalation triggers use evaluable conditions — single-token identifiers or simple comparisons that the condition evaluator can process. Examples: named_entity_critical, purchase_value > 100, shares_personal_data. Forbidden actions are semantic identifiers, not prose descriptions. Use concrete action names like delete_without_confirmation, not vague phrases like “harmful behavior”.

Set audit commitment

Declare how your agent logs decisions and whether external parties can query traces:

{
  "audit": {
    "trace_format": "ap-trace-v1",
    "retention_days": 365,
    "queryable": true,
    "query_endpoint": "https://api.mnemom.ai/v1/traces",
    "tamper_evidence": "append_only"
  }
}

Full example: Customer support agent

JSON
YAML

{
  "card_version": "unified/2026-04-15",
  "card_id": "ac-cs-agent-001-v1",
  "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
  "issued_at": "2026-02-21T00:00:00Z",
  "expires_at": "2026-08-21T00:00:00Z",

  "autonomy_mode": "enforce",
  "integrity_mode": "enforce",

  "principal": {
    "type": "human",
    "identifier": "support-team@example.com",
    "relationship": "delegated_authority",
    "escalation_contact": "mailto:support-team@example.com"
  },

  "values": {
    "declared": [
      "principal_benefit",
      "transparency",
      "honesty",
      "privacy",
      "customer_satisfaction"
    ],
    "definitions": {
      "customer_satisfaction": {
        "name": "Customer Satisfaction",
        "description": "Prioritize resolving customer issues efficiently and empathetically",
        "priority": 5
      }
    },
    "conflicts_with": ["upsell_pressure", "data_harvesting"],
    "hierarchy": "lexicographic"
  },

  "autonomy": {
    "bounded_actions": [
      "inference",
      "read",
      "search_knowledge_base",
      "create_ticket",
      "update_ticket",
      "send_response"
    ],
    "escalation_triggers": [
      {
        "condition": "refund_amount > 500",
        "action": "escalate",
        "reason": "Refunds over $500 require manager approval"
      },
      {
        "condition": "legal_claims_present",
        "action": "escalate",
        "reason": "Legal claims require legal team review"
      },
      {
        "condition": "customer_churn_risk",
        "action": "escalate",
        "reason": "High churn risk accounts need human intervention"
      }
    ],
    "max_autonomous_value": {
      "amount": 500,
      "currency": "USD"
    },
    "forbidden_actions": [
      "access_payment_credentials",
      "modify_billing_without_consent",
      "share_customer_data_externally",
      "make_legal_commitments"
    ]
  },

  "audit": {
    "trace_format": "ap-trace-v1",
    "retention_days": 365,
    "queryable": true,
    "query_endpoint": "https://api.mnemom.ai/v1/traces",
    "tamper_evidence": "append_only"
  }
}

# Customer support agent alignment card
card_version: "unified/2026-04-15"
card_id: ac-cs-agent-001-v1
agent_id: mnm-550e8400-e29b-41d4-a716-446655440000
issued_at: "2026-02-21T00:00:00Z"
expires_at: "2026-08-21T00:00:00Z"

autonomy_mode: enforce
integrity_mode: enforce

principal:
  type: human
  identifier: support-team@example.com
  relationship: delegated_authority
  escalation_contact: mailto:support-team@example.com

values:
  declared:
    - principal_benefit
    - transparency
    - honesty
    - privacy
    - customer_satisfaction
  definitions:
    customer_satisfaction:
      name: Customer Satisfaction
      description: Prioritize resolving customer issues efficiently and empathetically
      priority: 5
  conflicts_with:
    - upsell_pressure
    - data_harvesting
  hierarchy: lexicographic

autonomy:
  bounded_actions:
    - inference
    - read
    - search_knowledge_base
    - create_ticket
    - update_ticket
    - send_response
  escalation_triggers:
    # Financial threshold -- requires manager approval
    - condition: "refund_amount > 500"
      action: escalate
      reason: "Refunds over $500 require manager approval"
    # Legal exposure -- route to legal team
    - condition: legal_claims_present
      action: escalate
      reason: Legal claims require legal team review
    # Retention risk -- human intervention needed
    - condition: customer_churn_risk
      action: escalate
      reason: High churn risk accounts need human intervention
  max_autonomous_value:
    amount: 500
    currency: USD
  forbidden_actions:
    - access_payment_credentials
    - modify_billing_without_consent
    - share_customer_data_externally
    - make_legal_commitments

audit:
  trace_format: ap-trace-v1
  retention_days: 365
  queryable: true
  query_endpoint: https://api.mnemom.ai/v1/traces
  tamper_evidence: append_only

Publishing via CLI

Publishing via dashboard

For paste-from-file workflows, use the JSON or YAML editor. Copy your local card file and paste it directly into the corresponding editor tab, then save. This is faster than manually filling in the visual editor for complex cards.

Publishing via API

Update your agent’s alignment card directly with a PUT request to /v1/alignment/agent/{agent_id} — the canonical Resources × Scope × Verb URL. The body is the unified alignment card in YAML (canonical) or JSON. Publishing triggers composition — the server regenerates the agent’s canonical card against platform + org scopes before the response returns.

The older /v1/agents/{agent_id}/alignment-card URL still works but only 308-redirects here (sunset 2027-01-15). Use the canonical /v1/alignment/agent/{agent_id} directly.

Authenticate with either an API key or a Bearer JWT. Send Idempotency-Key so retries are safe to replay.

Who can publish. Publishing is authorized by organization membership, not by who originally claimed the agent. Any member of the organization that governs the agent — role owner, admin, or member — can publish its cards, so teammates can manage shared agents without re-claiming them. You never pass an organization id: the server derives it from the agent. A caller who is not a member of the agent’s org receives 403 Forbidden with code agent_org_forbidden, naming both the org and the agent.

curl -X PUT https://api.mnemom.ai/v1/alignment/agent/{agent_id} \
  -H "X-Mnemom-Api-Key: mnm_your_key_here" \
  -H "Content-Type: text/yaml" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data-binary @- <<'YAML'
card_version: unified/2026-04-15
card_id: ac-your-card-id
agent_id: your-agent-id
issued_at: "2026-02-21T00:00:00Z"
expires_at: "2026-08-21T00:00:00Z"

autonomy_mode: observe
integrity_mode: observe

principal:
  type: human
  identifier: you@example.com
  relationship: delegated_authority

values:
  declared:
    - transparency
    - honesty
  hierarchy: lexicographic

autonomy:
  bounded_actions:
    - inference
    - read
  forbidden_actions:
    - exfiltrate_data

audit:
  trace_format: ap-trace-v1
  retention_days: 90
  queryable: true
  query_endpoint: https://api.mnemom.ai/v1/traces
  tamper_evidence: append_only
YAML

curl -X PUT https://api.mnemom.ai/v1/alignment/agent/{agent_id} \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "card_version": "unified/2026-04-15",
    "card_id": "ac-your-card-id",
    "agent_id": "your-agent-id",
    "issued_at": "2026-02-21T00:00:00Z",
    "expires_at": "2026-08-21T00:00:00Z",
    "autonomy_mode": "observe",
    "integrity_mode": "observe",
    "principal": { "type": "human", "identifier": "you@example.com", "relationship": "delegated_authority" },
    "values": {
      "declared": ["transparency", "honesty"],
      "hierarchy": "lexicographic"
    },
    "autonomy": {
      "bounded_actions": ["inference", "read"],
      "forbidden_actions": ["exfiltrate_data"],
      "escalation_triggers": []
    },
    "audit": {
      "trace_format": "ap-trace-v1",
      "retention_days": 90,
      "queryable": true,
      "query_endpoint": "https://api.mnemom.ai/v1/traces",
      "tamper_evidence": "append_only"
    }
  }'

The response is the canonical card — your agent-scope input composed with platform + org scopes. Pass ?include_composition=true to include the _composition metadata block showing which scope contributed which fields.

Organization card templates

Your card composes with your org’s alignment template (if one is set) and the platform floor to produce your agent’s canonical card — org values and forbidden actions always apply on top of what you declare here. For setting up an org template, granting per-agent exemptions from it, and debugging why a composed field has a value you didn’t set, see Managing Card Composition.

Validation rules

mnemom card validate runs every check below; any failure exits non-zero (there’s no separate warning tier — a failed check blocks validation):

Check	Rule
Valid JSON/YAML	Must parse without errors.
`card_version`, `agent_id`	Required, non-empty strings.
`autonomy_mode`, `integrity_mode`	Required top-level fields, one of `off \| observe \| nudge \| enforce`.
`principal`	Required object with `type` and `relationship` from their respective enums; `identifier` required unless `type` is `unspecified`.
`values.declared`	Required, non-empty array of strings (or `{id, ...params}` objects).
`values.definitions`	If present, every key must match an entry actually in `values.declared` — a definition for an undeclared value fails.
`autonomy.bounded_actions`	Required, non-empty array of strings; must be disjoint from `forbidden_actions`.
`autonomy.escalation_triggers`	If present, each entry needs a non-empty `condition`, an `action` from a fixed enum, and a non-empty `reason`.
`audit`	Required; `retention_days` and `queryable` required, `query_endpoint` required when `queryable` is `true`.
Legacy fields	`integrity.enforcement_mode`, `enforcement.mode`, `enforcement.unmapped_tool_action`, `enforcement.fail_open`, and `audit.storage` are all rejected — use the current top-level/unified fields instead.
`_composition`	Rejected on an inbound card — it’s a server-assigned response field.

When you’re online with an agent to validate against, mnemom card validate runs the same check server-side (composed against your org/platform floor) instead of this offline check set — pass --offline to force the local rules.

Policy integration

Policy is now part of the alignment card itself. The unified schema includes capability mappings, forbidden rules, and enforcement defaults directly in the card:

Card defines capabilities: Your card’s autonomy.bounded_actions lists semantic categories like web_fetch, read, write
Card maps tools: The capabilities section maps concrete tool names (like mcp__browser__*) to those card categories
Card defines enforcement: The enforcement section sets the mode (observe/warn/enforce) and defaults for unmapped tools
Evaluation bridges all three: mnemom card evaluate checks that every tool maps to a declared bounded action

When adding new tools, update the card to add both the capability to bounded_actions and the tool-to-capability mapping in capabilities. The enforcement section’s grace_period_hours field, if you set one, gives you time to make these updates after new tools are first observed before its default_unmapped_severity starts applying.

Amendment tracking

Every card update creates a formal amendment with version history and diffs. Amendments can be linked to reclassification requests — proving that a violation was caused by a card gap rather than agent misbehavior. See Card Lifecycle for details.

Best practices

Version control your cards

Keep alignment card files (JSON or YAML) in your repository alongside your agent code. Use mnemom card validate in CI to catch issues before deploy.

Match bounded actions to real tools

Your bounded_actions list should reflect your agent’s actual tools and capabilities. Adding actions the agent never takes produces noise; missing actions the agent does take produces false violations.

Set meaningful expiry dates

A 6-month expiration is typical. Shorter lifetimes increase operational overhead; longer lifetimes risk the card becoming stale relative to actual behavior.

Use escalation triggers for real decisions

Escalation triggers are the card’s most actionable component. Define triggers for situations where your agent genuinely needs human approval, not aspirational conditions.

Define custom values precisely

Every custom value needs a clear description in the definitions block. Vague definitions lead to inconsistent verification results.

Review cards after capability changes

When you add or remove tools from your agent, update the alignment card and policy to match. Stale cards produce misleading integrity scores.

Identity & Cards

Posture & Policy

Detection & Safe House

Reputation & Risk

Lifecycle

Alignment Card Management

Creating a card

Start from the template

Choose values

Define the autonomy block

Set audit commitment

Full example: Customer support agent

Publishing via CLI

Publishing via dashboard

Publishing via API

Organization card templates

Validation rules

Policy integration

Amendment tracking

Best practices

Version control your cards

Match bounded actions to real tools

Set meaningful expiry dates

Use escalation triggers for real decisions

Define custom values precisely

Review cards after capability changes

See also

​Creating a card

​Start from the template

​Choose values

​Define the autonomy block

​Set audit commitment

​Full example: Customer support agent

​Publishing via CLI

​Publishing via dashboard

​Publishing via API

​Organization card templates

​Validation rules

​Policy integration

​Amendment tracking

​Best practices

Version control your cards

Match bounded actions to real tools

Set meaningful expiry dates

Use escalation triggers for real decisions

Define custom values precisely

Review cards after capability changes

​See also

Creating a card

Start from the template

Choose values

Define the autonomy block

Set audit commitment

Full example: Customer support agent

Publishing via CLI

Publishing via dashboard

Publishing via API

Organization card templates

Validation rules

Policy integration

Amendment tracking

Best practices

See also