> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mnemom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Alignment Card Management

> Create, validate, publish, and manage alignment cards for your AI agents

[Alignment Cards](/concepts/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.

<Note>
  **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](/specifications/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](/concepts/alignment-cards) — a separate, still-stable surface that is not submitted to `mnemom card validate`.
</Note>

## Creating a card

An alignment card is a structured document that follows the [AAP specification](/protocols/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.

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    {
      "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"
      }
    }
    ```
  </Tab>

  <Tab title="YAML">
    ```yaml theme={null}
    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
    ```
  </Tab>
</Tabs>

### 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:

```json theme={null}
{
  "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"
  }
}
```

<Tip>
  Only declare values your agent actually applies. Declaring `fairness` but never referencing it in decisions produces verification warnings.
</Tip>

### Define the autonomy block

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    {
      "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"
      }
    }
    ```
  </Tab>

  <Tab title="YAML">
    ```yaml theme={null}
    # 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
    ```
  </Tab>
</Tabs>

## Publishing via CLI

<Steps>
  ### Validate your card

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

  <CodeGroup>
    ```bash YAML theme={null}
    mnemom card validate my-card.yaml
    ```

    ```bash JSON theme={null}
    mnemom card validate my-card.json
    ```
  </CodeGroup>

  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:

  ```bash theme={null}
  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](/guides/ci-cd-policy-gates) for integrating this into your pipeline.

  ### Publish the card

  Upload the validated card to your agent:

  <CodeGroup>
    ```bash YAML theme={null}
    mnemom card publish my-card.yaml --agent my-agent
    ```

    ```bash JSON theme={null}
    mnemom card publish my-card.json --agent my-agent
    ```
  </CodeGroup>

  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:

  ```bash theme={null}
  mnemom card edit --agent my-agent
  ```

  ### Verify publication

  Confirm the card is active:

  ```bash theme={null}
  mnemom card show --agent my-agent
  ```

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

  ### CI integration

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

  ```yaml theme={null}
  # 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 }}
  ```

  ```bash theme={null}
  # Pre-commit hook
  #!/bin/sh
  npx mnemom card validate card.yaml || exit 1
  ```
</Steps>

## Publishing via dashboard

<Steps>
  ### Navigate to your agent

  Open the [Mnemom dashboard](https://mnemom.ai/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`.
</Steps>

<Tip>
  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.
</Tip>

## 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](/specifications/alignment-card-schema) in YAML (canonical) or JSON. Publishing triggers composition — the server regenerates the agent's canonical card against platform + org scopes before the response returns.

<Info>
  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.
</Info>

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

<Note>
  **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.
</Note>

<CodeGroup>
  ```bash API Key (YAML) theme={null}
  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
  ```

  ```bash Bearer Token (JSON) theme={null}
  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"
      }
    }'
  ```
</CodeGroup>

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)

<Info>
  Organization card templates require an Enterprise plan. Contact [sales](https://mnemom.ai/pricing) to enable this feature.
</Info>

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

1. Navigate to **Organization Settings** in the dashboard
2. Open the **Alignment Card Template** section
3. Enable the org template toggle
4. Configure your base card using the visual or JSON editor
5. 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:

1. A double-confirm flow in the dashboard (confirm intent, then confirm again with reason)
2. A written reason that is stored in the audit trail
3. 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](/gateway/org-card-templates) 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    |

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

## 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:

1. **Card defines capabilities**: Your card's `autonomy.bounded_actions` lists semantic categories like `web_fetch`, `read`, `write`
2. **Card maps tools**: The `capabilities` section maps concrete tool names (like `mcp__browser__*`) to those card categories
3. **Card defines enforcement**: The `enforcement` section sets the mode (observe/warn/enforce) and defaults for unmapped tools
4. **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](/guides/trust-recovery) -- proving that a violation was caused by a card gap rather than agent misbehavior. See [Card Lifecycle](/concepts/card-lifecycle) for details.

## Best practices

<CardGroup cols={2}>
  <Card title="Version control your cards" icon="code-branch">
    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.
  </Card>

  <Card title="Match bounded actions to real tools" icon="wrench">
    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.
  </Card>

  <Card title="Set meaningful expiry dates" icon="calendar">
    A 6-month expiration is typical. Shorter lifetimes increase operational overhead; longer lifetimes risk the card becoming stale relative to actual behavior.
  </Card>

  <Card title="Use escalation triggers for real decisions" icon="arrow-up-from-bracket">
    Escalation triggers are the card's most actionable component. Define triggers for situations where your agent genuinely needs human approval, not aspirational conditions.
  </Card>

  <Card title="Define custom values precisely" icon="pen-ruler">
    Every custom value needs a clear `description` in the `definitions` block. Vague definitions lead to inconsistent verification results.
  </Card>

  <Card title="Review cards after capability changes" icon="rotate">
    When you add or remove tools from your agent, update the alignment card and [policy](/guides/policy-management) to match. Stale cards produce misleading integrity scores.
  </Card>
</CardGroup>

## See also

* [Alignment Cards concept](/concepts/alignment-cards) -- Full specification of card structure and semantics
* [Card Lifecycle](/concepts/card-lifecycle) -- Amendment tracking, reclassification, and trust recovery
* [Policy Management](/guides/policy-management) -- Policy setup alongside card management
* [CLI Reference](/gateway/cli) -- `mnemom card show`, `card publish`, and `card validate` commands
* [Organization Card Templates](/gateway/org-card-templates) -- Org-level card policies (Enterprise)
* [AAP Specification](/protocols/aap/specification) -- Normative protocol specification