Skip to main content

​
Alignment Card Management

Alignment Cards are structured declarations of your agent’s values, boundaries, and behavioral commitments. Every agent connected via smoltbot 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.

​
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. 
{
  "aap_version": "0.5.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 IdentifierDescription
principal_benefitPrioritize principal’s interests
transparencyDisclose reasoning and limitations
minimal_dataCollect only necessary information
harm_preventionAvoid actions causing harm
honestyDo not deceive or mislead
user_controlRespect user autonomy and consent
privacyProtect personal information
fairnessAvoid 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

{
  "aap_version": "0.5.0",
  "card_id": "ac-cs-agent-001-v1",
  "agent_id": "smolt-cs-agent-001",
  "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"
  }
}

​
Publishing via CLI

1
Validate your card
2
Run local validation to check AAP spec compliance before publishing. The CLI accepts both JSON and YAML files:
3
JSON
smoltbot card validate my-card.json
YAML
smoltbot card validate my-card.yaml
4
This checks required blocks, value definitions, bounded actions, escalation trigger evaluability, and expiry dates. Exit code 0 means the card is valid; exit code 1 means there are errors.
5
Publish the card
6
Upload the validated card to your agent:
7
JSON
smoltbot card publish my-card.json
YAML
smoltbot card publish my-card.yaml
8
The CLI validates again before uploading, asks for confirmation, and optionally re-verifies existing traces against the new card.
9
Verify publication
10
Confirm the card is active:
11
smoltbot card show
12
CI integration
13
Add validation to your CI pipeline to catch card issues before deploy:
14
# GitHub Actions example
- name: Validate alignment card
  run: npx smoltbot card validate alignment-card.json
15
# Pre-commit hook
#!/bin/sh
npx smoltbot card validate alignment-card.json || exit 1

​
Publishing via Dashboard

2
Open the Mnemom dashboard and select your agent from the agents list.
3
Open the alignment card section
4
Scroll to the Alignment Card panel on the agent page. Your current card (or the default) is displayed here.
5
Choose your editor
6
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.
7
Edit and save
8
Make your changes, then click Save. The dashboard validates the card before saving and shows any errors inline.
9
Verify the update
10
The card panel updates immediately after saving. You can also confirm via CLI with smoltbot 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 PATCH request: 
curl -X PATCH https://api.mnemom.ai/v1/agents/{agent_id}/card \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "card_json": {
      "aap_version": "0.5.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" },
      "values": { "declared": ["transparency", "honesty"], "hierarchy": "lexicographic" },
      "autonomy_envelope": {
        "bounded_actions": ["inference", "read"],
        "escalation_triggers": [],
        "forbidden_actions": ["exfiltrate_data"]
      },
      "audit_commitment": {
        "trace_format": "ap-trace-v1",
        "retention_days": 90,
        "queryable": true,
        "tamper_evidence": "append_only"
      }
    }
  }'
See the API reference for full request/response details.

​
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

  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 for the full setup walkthrough.

​
Validation Rules

Reference table of all validation checks performed during smoltbot card validate and on publish:
CheckRuleSeverity
Valid JSON/YAMLMust parse without errorsError
Required blocksprincipal, values, autonomy_envelope, audit_commitment must be presentError
Non-empty valuesvalues.declared must have at least one entryError
Custom definitionsEvery non-standard value must have a definitions entryWarning
Bounded actionsMust list at least one actionError
Evaluable triggersCondition must be a single-token identifier or comparison expressionWarning
Expiryexpires_at must be in the futureError
Warnings do not prevent publishing but are reported in validation output. Fix warnings to improve verification quality.

​
Policy Integration

Alignment cards and policies work together. The card declares what an agent can do (bounded_actions), while the policy defines which tools map to those capabilities:
  1. Card defines capabilities: Your card’s bounded_actions lists semantic categories like web_fetch, read, write
  2. Policy maps tools: Your policy maps concrete tool names (like mcp__browser__*) to those card categories
  3. Evaluation bridges both: The policy engine checks that every tool the agent uses maps to a declared bounded action
When adding new tools, update both the card (add the capability to bounded_actions) and the policy (add the tool-to-capability mapping). 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 smoltbot 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.