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 AAP 1.0 card uses a different schema and is specified at /concepts/alignment-cards — a separate, still-stable surface that is not submitted to mnemom card validate.

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": "[email protected]",
    "relationship": "delegated_authority",
    "escalation_contact": "mailto:[email protected]"
  },

  "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: [email protected]
  relationship: delegated_authority
  escalation_contact: mailto:[email protected]

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

Select from the standard value identifiers and add custom values as needed:

Standard Identifier	Description
`principal_benefit`	Prioritize principal’s interests
`transparency`	Disclose reasoning and limitations
`minimal_data`	Collect only necessary information
`harm_prevention`	Avoid actions causing harm
`honesty`	Do not deceive or mislead
`user_control`	Respect user autonomy and consent
`privacy`	Protect personal information
`fairness`	Avoid discriminatory outcomes

For custom values, add a definitions entry:

{
  "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": "[email protected]",
    "relationship": "delegated_authority",
    "escalation_contact": "mailto:[email protected]"
  },

  "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: [email protected]
  relationship: delegated_authority
  escalation_contact: mailto:[email protected]

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: [email protected]
  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": "[email protected]", "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 (Enterprise)

Organization card templates require an Enterprise plan. Contact sales to enable this feature.

Org card templates let you define a base alignment card that all agents in your organization inherit. This ensures consistent alignment policy across your fleet — every agent shares the same core values, forbidden actions, and audit requirements.

How composition works

When an org template is active, the canonical card for each agent is computed by composing the org template with the agent’s individual card:

Values: Org values are always included. Agent values are added on top. Agents cannot remove org values.
Forbidden actions: Org forbidden actions are always included. Agents can add more but cannot remove any.
Bounded actions: Agent-specific. The org template does not restrict which actions an agent can take.
Escalation triggers: Org triggers are always included. Agents can add more.
Audit commitment: Org audit commitment is the floor. Agents can increase retention or add capabilities but cannot weaken audit requirements.

Setting up

Navigate to Organization Settings in the dashboard
Open the Alignment Card Template section
Enable the org template toggle
Configure your base card using the visual or JSON editor
Save — all agents in the org immediately inherit the template

Agent exemptions

In rare cases, an agent may need to be exempt from the org template. Exemptions require:

A double-confirm flow in the dashboard (confirm intent, then confirm again with reason)
A written reason that is stored in the audit trail
Owner or admin role

Exempted agents operate with only their individual card. Use exemptions sparingly — they weaken organizational alignment guarantees. See the Organization Card Templates guide for the full setup walkthrough.

Validation rules

Reference table of all validation checks performed during mnemom card validate and on publish:

Check	Rule	Severity
Valid JSON/YAML	Must parse without errors	Error
Required blocks	`principal`, `values`, `autonomy`, `audit` must be present	Error
Non-empty values	`values.declared` must have at least one entry	Error
Custom definitions	Every non-standard value must have a `definitions` entry	Warning
Bounded actions	Must list at least one action	Error
Evaluable triggers	Condition must be a single-token identifier or comparison expression	Warning
Expiry	`expires_at` must be in the future	Error

Warnings do not prevent publishing but are reported in validation output. Fix warnings to improve verification quality.

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 24-hour grace period gives you time to make these updates after new tools are first observed.

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.

Guides

Safe House

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 (Enterprise)

How composition works

Setting up

Agent exemptions

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 (Enterprise)

​How composition works

​Setting up

​Agent exemptions

​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 (Enterprise)

How composition works

Setting up

Agent exemptions

Validation rules

Policy integration

Amendment tracking

Best practices

See also