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.

Two paths to card management. The JSON/YAML templates on this page are the AAP 1.0 protocol-level surface — the minimum shape every AAP implementation must accept. For authoring Mnemom agent cards in production, the preferred path is the unified card model, which adds first-class conscience, integrity, capabilities, and enforcement sections plus three-scope composition. See Alignment Card Schema for the normative unified shape, and use mnemom card edit or the dashboard YAML editor rather than hand-crafting JSON.The AAP templates below remain accurate for protocol-level interop with external agents (A2A, MCP). They are not going anywhere — they’re just the narrower of two surfaces.

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 envelope, and audit commitment.

JSON
YAML

{
  "aap_version": "1.0.0",
  "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",

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

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

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

  "audit_commitment": {
    "trace_format": "ap-trace-v1",
    "retention_days": 90,
    "queryable": true,
    "tamper_evidence": "append_only"
  }
}

aap_version: "1.0.0"
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"

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

values:
  declared: []
  hierarchy: lexicographic

autonomy_envelope:
  bounded_actions: []
  escalation_triggers: []
  forbidden_actions: []

audit_commitment:
  trace_format: ap-trace-v1
  retention_days: 90
  queryable: true
  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 autonomy envelope

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

{
  "autonomy_envelope": {
    "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_commitment": {
    "trace_format": "ap-trace-v1",
    "retention_days": 365,
    "queryable": true,
    "tamper_evidence": "append_only"
  }
}

Full example: Customer support agent

JSON
YAML

{
  "aap_version": "1.0.0",
  "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",

  "principal": {
    "type": "human",
    "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_envelope": {
    "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_commitment": {
    "trace_format": "ap-trace-v1",
    "retention_days": 365,
    "queryable": true,
    "tamper_evidence": "append_only"
  }
}

# Customer support agent alignment card
aap_version: "1.0.0"
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"

principal:
  type: human
  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_envelope:
  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_commitment:
  trace_format: ap-trace-v1
  retention_days: 365
  queryable: true
  tamper_evidence: append_only

Publishing via CLI

Validate your card

Run local validation to check compliance against the unified schema (ADR-008) before publishing. The CLI accepts both YAML and JSON files:

YAML

mnemom card validate my-card.yaml

JSON

mnemom card validate my-card.json

This checks required blocks (principal, values, autonomy, audit), value definitions, bounded actions, escalation trigger evaluability, capability mappings, enforcement rules, and expiry dates. Exit code 0 means the card is valid; exit code 1 means there are errors.

Evaluate against tools (optional)

Before publishing, evaluate the card’s policy against the tools your agent uses:

mnemom card evaluate my-card.yaml --tools mcp__browser__navigate,mcp__slack__post_message --agent my-agent

This checks that every tool maps to a declared bounded action and that no forbidden rules are violated. See CI/CD Policy Gates for integrating this into your pipeline.

Publish the card

Upload the validated card to your agent:

YAML

mnemom card publish my-card.yaml --agent my-agent

JSON

mnemom card publish my-card.json --agent my-agent

The CLI validates again before uploading, asks for confirmation, and optionally re-verifies existing traces against the new card.

Edit an existing card

To modify your agent’s current card directly, use the edit command. It fetches the active card, opens it in your $EDITOR, and publishes the changes on save:

mnemom card edit --agent my-agent

Verify publication

Confirm the card is active:

mnemom card show --agent my-agent

The output is displayed as structured YAML showing principal, values, autonomy, capabilities, enforcement, and audit commitment.

CI integration

Add validation to your CI pipeline to catch card issues before deploy:

# GitHub Actions example
- name: Validate alignment card
  run: npx mnemom card validate card.yaml
- name: Evaluate card policy
  run: npx mnemom card evaluate card.yaml --tools mcp__browser__navigate --agent my-agent
  env:
    MNEMOM_API_KEY: ${{ secrets.MNEMOM_API_KEY }}

# Pre-commit hook
#!/bin/sh
npx mnemom card validate card.yaml || exit 1

Publishing via dashboard

Navigate to your agent

Open the Mnemom dashboard and select your agent from the agents list.

Open the alignment card section

Scroll to the Alignment Card panel on the agent page. Your current card (or the default) is displayed here.

Choose your editor

Switch between the Visual editor (form-based, guided), JSON editor (raw JSON), and YAML editor (YAML with comments) using the tabs at the top of the card panel.

Edit and save

Make your changes, then click Save. The dashboard validates the card before saving and shows any errors inline.

Verify the update

The card panel updates immediately after saving. You can also confirm via CLI with mnemom card show.

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/agents/{agent_id}/alignment-card. 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. Authenticate with either an API key or a Bearer JWT. Send Idempotency-Key so retries are safe to replay.

curl -X PUT https://api.mnemom.ai/v1/agents/{agent_id}/alignment-card \
  -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"

principal:
  type: human
  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
  tamper_evidence: append_only
YAML

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. The legacy PATCH /v1/agents/{id}/card endpoint was removed in UC-4 (2026-04-15) along with the separate /v1/agents/{id}/cfd/config and /v1/agents/{id}/policy endpoints. All three are now absorbed into the unified alignment-card and protection-card shapes. See the migration guide if you’re upgrading an older client.

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_envelope`, `audit_commitment` 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 (ADR-008) 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

Alignment card management

Creating a Card

Start from the template

Choose values

Define autonomy envelope

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

Guides

Safe House

​Alignment card management

​Creating a Card

​Start from the template

​Choose values

​Define autonomy envelope

​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

Alignment card management

Creating a Card

Start from the template

Choose values

Define autonomy envelope

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