> ## 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 Cards
> Declarative specifications of an AI agent's intended values, boundaries, and behavioral commitments
# Alignment Cards
An Alignment Card is a structured, machine-readable document that declares an AI agent's alignment posture: its values, the boundaries of its autonomous behavior, and its commitments around audit and transparency. Think of it as a passport for agent intent -- it states who the agent serves, what it believes, what it will and will not do, and how it logs its decisions.
Alignment Cards are the foundational data structure of the [Agent Alignment Protocol (AAP)](/protocols/aap/specification). Every other AAP operation -- [AP-Traces](/concepts/ap-traces), [verification](/protocols/aap/specification), [value coherence](/concepts/value-coherence), and [drift detection](/concepts/drift-detection) -- references an Alignment Card as its source of truth.
**This page describes the AAP 1.0 protocol-level card structure** — the minimum surface every AAP implementation must support. In production, Mnemom stores and serves a richer **unified alignment card** that adds first-class `conscience`, `integrity`, `capabilities`, and `enforcement` sections, and supports three-scope composition (platform > org > agent).
For the unified model, see [Agent Cards](/concepts/agent-cards) (the two-card product story), [Card Composition](/concepts/card-composition) (scope hierarchy), and the normative [Alignment Card Schema](/specifications/alignment-card-schema).
The AAP protocol surface on this page is unchanged and remains the stable contract for external agent interoperability.
Alignment Cards declare intent, not guarantee behavior. An agent can publish a card claiming any set of values. The card becomes meaningful only when paired with AP-Traces that can be verified against it and integrity checkpoints that analyze the agent's reasoning in real time.
## Why Alignment Cards exist
Current agent protocols solve capability discovery (A2A Agent Cards), tool integration (MCP), and payment authorization. None of them address a fundamental question: **is this agent serving its principal's interests?**
Alignment Cards fill this gap by making the answer to that question observable. They give principals, auditors, and other agents a structured declaration to verify behavior against.
## Structure
An Alignment Card contains five required blocks and one optional block:
| Block | Purpose | Required |
| --------------------- | -------------------------------------- | -------- |
| **Identity** | Agent ID, card ID, version, timestamps | Yes |
| **Principal** | Who the agent serves and how | Yes |
| **Values** | What the agent prioritizes | Yes |
| **Autonomy Envelope** | What the agent can do independently | Yes |
| **Audit Commitment** | How the agent logs decisions | Yes |
| **Extensions** | Protocol-specific additions (A2A, MCP) | No |
### Identity fields
Every card begins with identity and versioning metadata:
```json theme={null}
{
"aap_version": "1.0.0",
"card_id": "ac-f47ac10b-58cc-4372-a567-0e02b2c3d479",
"agent_id": "did:web:shopping.agent.example.com",
"issued_at": "2026-01-31T12:00:00Z",
"expires_at": "2026-07-31T12:00:00Z"
}
```
* `card_id` is a unique identifier (UUID or URI) for this specific version of the card.
* `agent_id` identifies the agent itself, using a DID (Decentralized Identifier), URL, or UUID.
* `issued_at` and `expires_at` establish the card's validity window.
### Principal block
The principal block declares who the agent serves and the nature of that relationship:
```json theme={null}
{
"principal": {
"type": "human",
"relationship": "delegated_authority",
"escalation_contact": "mailto:user@example.com"
}
}
```
Three relationship types are defined:
| Relationship | Meaning |
| --------------------- | --------------------------------------------------- |
| `delegated_authority` | Agent acts within bounds set by principal |
| `advisory` | Agent recommends; principal decides |
| `autonomous` | Agent operates independently within declared values |
### Values block
The values block declares the agent's operational priorities:
```json theme={null}
{
"values": {
"declared": ["principal_benefit", "transparency", "minimal_data"],
"conflicts_with": ["deceptive_marketing", "hidden_fees"],
"hierarchy": "lexicographic"
}
}
```
AAP defines a set of standard value identifiers:
| 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 |
Custom values are supported but must be defined in a `definitions` block:
```json theme={null}
{
"values": {
"declared": ["principal_benefit", "eco_preference"],
"definitions": {
"eco_preference": {
"name": "Ecological Preference",
"description": "Prefer environmentally sustainable options when quality and price are comparable",
"priority": 3
}
},
"hierarchy": "lexicographic"
}
}
```
The `conflicts_with` array lists values the agent refuses to coordinate with during [value coherence checks](/concepts/value-coherence).
### What belongs in values.declared
`values.declared` is consulted by the AIP integrity monitor at runtime to verify that the agent's actual reasoning aligns with its stated commitments. Only include values the agent will genuinely apply in its decision-making.
**Do declare** — ethical and behavioral values that drive how the agent makes decisions:
* `transparency`, `honesty`, `accuracy`, `safety`, `accountability`, `helpfulness`, `fairness`, `deliberation_before_action`
These represent the agent's decision-making commitments and should appear in AP-Traces via `values_applied` when they influence a decision.
**Do NOT declare** — role capabilities, operational principles, or job-function descriptors:
| What you might want to declare | Where it actually belongs |
| ------------------------------------------------ | ---------------------------------------------------------------------- |
| `fiduciary_precision` | `extensions.clpi.role` or `extensions` metadata |
| `organizational_clarity` | `extensions.clpi.role` or `extensions` metadata |
| `conservative_risk_management` (as a role label) | `extensions` metadata — unless it materially changes ethical reasoning |
| `read_documents` (a capability) | `autonomy_envelope.bounded_actions` |
**Rule of thumb**: If removing the value from a card would change HOW the agent reasons about ethics, it's a value. If it describes WHAT the agent is or does in its role, it belongs in `extensions`.
**Cross-cutting baseline**: All agents in a team should share a common baseline of behavioral values — `transparency`, `honesty`, `accountability`, `accuracy`, `safety`, `quality`, `helpfulness`, `deliberation_before_action`. Role-specific values layer on top of this shared baseline, not in place of it.
Custom values declared by one agent but not others create fault lines in fleet coherence analysis. If the divergence is intentional role specialization — for example, a CFO agent has `fiduciary_precision` and a CoS agent has `organizational_clarity` — set `extensions.clpi.role` on each agent's card. The fault line analyzer uses this field to classify those divergences as `complementary` (by design) rather than `resolvable` (a gap to fill).
### Autonomy envelope block
The autonomy envelope defines the boundaries of independent action:
```json theme={null}
{
"autonomy_envelope": {
"bounded_actions": ["search", "compare", "recommend", "add_to_cart"],
"escalation_triggers": [
{
"condition": "action_type == \"purchase\"",
"action": "escalate",
"reason": "Purchases require explicit approval"
},
{
"condition": "purchase_value > 100",
"action": "escalate",
"reason": "Exceeds autonomous spending limit"
},
{
"condition": "shares_personal_data",
"action": "escalate",
"reason": "Data sharing requires consent"
}
],
"max_autonomous_value": {
"amount": 100,
"currency": "USD"
},
"forbidden_actions": ["store_payment_credentials", "subscribe_to_services"]
}
}
```
This block has four components:
* **bounded\_actions**: Actions the agent may take without escalation.
* **escalation\_triggers**: Conditions that require the agent to pause and seek approval. Each trigger specifies a condition, an action (`escalate`, `deny`, or `log`), and a human-readable reason.
* **max\_autonomous\_value**: Optional financial ceiling for independent decisions.
* **forbidden\_actions**: The agent's self-declared behavioral commitment — actions it promises never to take. These compose via deny-overrides union with platform and org floors; the agent can add entries but cannot remove a higher-scope entry.
Forbidden actions are the hardest boundary. During [verification](/protocols/aap/specification), taking a forbidden action produces a `FORBIDDEN_ACTION` violation at `CRITICAL` severity. During [integrity checking](/concepts/integrity-checkpoints), intent to take a forbidden action triggers a `boundary_violation` verdict.
**`autonomy.forbidden_actions` vs. `protected_surface.forbidden_operations`**
`autonomy.forbidden_actions` is the agent's *behavioral commitment* — declared by the agent (with org/platform as the floor). The protection card's `protected_surface.forbidden_operations` is the org's *enforced policy*, authored by the org and applied by Safe House L2 independent of what the agent declares. An empty or naive agent still gets the org's `protected_surface` floor enforced. See [Agent Cards](/concepts/agent-cards) for the two-card model.
### Audit commitment block
The audit commitment declares how the agent logs and exposes its decisions:
```json theme={null}
{
"audit_commitment": {
"trace_format": "ap-trace-v1",
"retention_days": 90,
"queryable": true,
"query_endpoint": "https://shopping.agent.example.com/api/v1/traces",
"tamper_evidence": "append_only"
}
}
```
Key fields:
* `queryable`: Whether external parties can query the agent's traces.
* `tamper_evidence`: Mechanism for ensuring trace integrity (`append_only`, `signed`, or `merkle`).
### Extensions block
Extensions allow protocol-specific metadata without modifying the core schema:
```json theme={null}
{
"extensions": {
"a2a": {
"agent_card_url": "https://shopping.agent.example.com/.well-known/agent.json"
},
"mcp": {
"tool_alignment_requirements": ["consent_logging", "rate_limiting"]
}
}
}
```
Extensions must be namespaced by protocol identifier. Implementations ignore unrecognized extensions.
## Complete example
Here is a full Alignment Card for a shopping assistant agent:
```json theme={null}
{
"aap_version": "1.0.0",
"card_id": "ac-f47ac10b-58cc-4372-a567-0e02b2c3d479",
"agent_id": "did:web:shopping.agent.example.com",
"issued_at": "2026-01-31T12:00:00Z",
"expires_at": "2026-07-31T12:00:00Z",
"principal": {
"type": "human",
"relationship": "delegated_authority",
"escalation_contact": "mailto:user@example.com"
},
"values": {
"declared": ["principal_benefit", "transparency", "minimal_data"],
"conflicts_with": ["deceptive_marketing", "hidden_fees"],
"hierarchy": "lexicographic"
},
"autonomy_envelope": {
"bounded_actions": ["search", "compare", "recommend", "add_to_cart"],
"escalation_triggers": [
{
"condition": "action_type == \"purchase\"",
"action": "escalate",
"reason": "Purchases require explicit approval"
},
{
"condition": "purchase_value > 100",
"action": "escalate",
"reason": "Exceeds autonomous spending limit"
},
{
"condition": "shares_personal_data",
"action": "escalate",
"reason": "Data sharing requires consent"
}
],
"max_autonomous_value": {
"amount": 100,
"currency": "USD"
},
"forbidden_actions": ["store_payment_credentials", "subscribe_to_services"]
},
"audit_commitment": {
"trace_format": "ap-trace-v1",
"retention_days": 90,
"queryable": true,
"query_endpoint": "https://shopping.agent.example.com/api/v1/traces",
"tamper_evidence": "append_only"
},
"extensions": {
"a2a": {
"agent_card_url": "https://shopping.agent.example.com/.well-known/agent.json"
}
}
}
```
## How Cards are used
Alignment Cards serve as the reference point across the entire Mnemom trust plane:
1. **Publication**: Agents publish their card at `/.well-known/alignment-card.json`. Other agents and auditors can fetch it.
2. **Trace Verification**: Every [AP-Trace](/concepts/ap-traces) references a `card_id`. Verification checks that the trace's actions, values, and escalation behavior are consistent with the card.
3. **Integrity Analysis**: The [Agent Integrity Protocol (AIP)](/concepts/integrity-checkpoints) compresses the card into a \~500-token summary and includes it in the conscience prompt that evaluates the agent's thinking blocks.
4. **Value Coherence**: Before two agents collaborate, they exchange cards and run a [coherence check](/concepts/value-coherence) to confirm their values are compatible.
5. **Drift Detection**: [Drift detection](/concepts/drift-detection) compares traces over time against the card to identify behavioral divergence.
6. **Policy Evaluation**: The [Policy Engine](/concepts/policy-engine) validates that the tools an agent uses map to capabilities declared in the card's `bounded_actions`. This bridges the gap between abstract card declarations and concrete tool usage.
## Card Lifecycle
Alignment cards are **lifecycle-managed artifacts** — they evolve as the agent's capabilities change. The [Card Lifecycle](/concepts/card-lifecycle) system tracks amendments, enables violation reclassification, and supports trust recovery.
Key lifecycle capabilities:
* **Amendment tracking**: Every card update creates a versioned amendment with diffs, preserving the full change history
* **Violation reclassification**: When a violation was caused by a missing card capability (a `card_gap`) rather than agent misbehavior, it can be reclassified and excluded from trust scoring
* **Trust recovery**: After reclassification and card amendment, trust scores recover automatically — see the [Trust Recovery guide](/guides/trust-recovery)
* **Compliance export**: Full audit trail of card changes, violations, and reclassifications for regulatory compliance
When you add new tools to your agent, update the card's `bounded_actions` and [policy](/concepts/policy-engine) to match. The 24-hour grace period gives you time to do this after tools are first observed, but proactive updates prevent violations entirely.
## Card versioning and updates
Cards are versioned through their `card_id` and `issued_at`/`expires_at` timestamps. When an agent's alignment posture changes:
1. Issue a new card with a new `card_id` and updated `issued_at`.
2. The old card remains valid until its `expires_at` or until explicitly revoked via `/.well-known/alignment-card-revocations.json`.
3. AP-Traces generated during the old card's validity period reference the old `card_id`. Traces generated after the update reference the new one.
4. Formal amendments are tracked with version history and diffs — see [Card Lifecycle](/concepts/card-lifecycle) for details.
Keep card lifetimes reasonable. A 6-month expiration is typical. Shorter lifetimes increase operational overhead; longer lifetimes risk the card becoming stale relative to actual behavior.
## Managing your card
**Gateway-provisioned (unclaimed) agents do not receive a canonical alignment card.** When the gateway auto-provisions an agent, it writes a legacy alignment-card row only. A canonical alignment card — and everything downstream of it (durable integrity checkpoints, analytical verdict headers, guaranteed AP-Traces) — is composed only when the agent is claimed and onboarded. Until then, `GET /v1/agents/{id}/checkpoints` returns an empty list and verdict headers reflect fail-open defaults. See [Unclaimed agent integrity behavior](/guides/agent-claim-flow#between-steps-integrity-during-the-unclaimed-phase) for details.
When you connect an agent via the Mnemom Gateway, a default alignment card is created automatically. This default card uses generic values and minimal autonomy -- it is a starting point, not a finished card. To make the card meaningful, you should customize it to reflect your agent's actual values, boundaries, and capabilities.
### Three ways to customize
There are three ways to update your agent's alignment card:
| Method | Best For |
| --------------------------------------- | ----------------------------------------------------------------- |
| **CLI** (`mnemom card publish`) | Local development, CI/CD pipelines, version-controlled card files |
| **Dashboard** (agent page card editor) | Quick edits, visual exploration, teams that prefer a GUI |
| **API** (`PUT /v1/alignment/agent/:id`) | Programmatic updates, automation, custom tooling |
See the [Card Management guide](/guides/card-management) for detailed walkthroughs of each method.
### Minimal card file
Save this as `alignment-card.yaml`, fill in your `agent_id`, and publish it with the CLI:
```yaml theme={null}
card_version: "unified/2026-04-15"
agent_id: $AGENT_ID
autonomy_mode: observe
integrity_mode: observe
values:
declared: [transparency, honesty, harm_prevention]
hierarchy: lexicographic
principal:
type: organization
identifier: your-org
relationship: delegated_authority
autonomy:
bounded_actions: [inference, read, write]
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
```
```bash theme={null}
mnemom card validate alignment-card.yaml
mnemom card publish alignment-card.yaml --agent $AGENT_ID
```
Start with `autonomy_mode: observe` and `integrity_mode: observe` — this logs policy results without blocking, giving you a picture of real traffic before tightening to `nudge` or `enforce`. See [Alignment Card Schema](/specifications/alignment-card-schema) for all fields.
### Validation
Cards are validated against AAP spec requirements on publish. The validation checks required blocks, value definitions, bounded actions, escalation trigger evaluability, and expiry dates.
Use `mnemom card validate` for local pre-flight checks before publishing. This runs the same validation locally without making any API calls, and is CI-friendly (exit code 0 on pass, 1 on fail).
See the [CLI reference](/gateway/cli) for full command documentation.
### Organization card templates (Enterprise)
Organization card templates require an Enterprise plan.
Organizations can define a base alignment card template that all agents inherit. Agent cards layer on top of the org template -- org values cannot be removed by individual agents, ensuring consistent organizational alignment policy.
This is similar to how [custom conscience values](/gateway/conscience-values) work at the org level, but applied to the full alignment card structure rather than just the conscience prompt.
Note that the org's **protection card template** — including `protected_surface` (sealed assets, forbidden operations, escalation requirements) — is separate from the alignment card template. `protected_surface` is org-owned and enforced by Safe House independently of what the agent declares here.
See the [Organization Card Templates guide](/gateway/org-card-templates) for setup and configuration details.
## Relationship to A2A Agent Cards
If you use Google's A2A protocol for agent discovery, the Alignment Card extends the A2A Agent Card rather than replacing it. The A2A Agent Card describes capabilities (what the agent can do). The Alignment Card describes alignment (what the agent will and will not do, and why). The `extensions.a2a.agent_card_url` field links the two.
## Best practices
Vague forbidden actions like "harmful behavior" are unverifiable. Use concrete actions: `delete_without_confirmation`, `share_credentials`, `exfiltrate_data`.
Only list values that appear in your AP-Traces. Declaring `fairness` but never applying it in decisions produces verification warnings.
Prefer the standard value identifiers (`principal_benefit`, `transparency`, etc.) for interoperability. Use custom values only when the standard set does not cover your needs.
Escalation triggers are the card's most actionable component. Define clear conditions, not aspirational ones.
## Limitations
An Alignment Card is a declaration, not a guarantee. Agents can publish cards claiming any values. The card's value comes from being verifiable against observed behavior via AP-Traces and integrity checkpoints -- not from the declaration itself.
## See also
* [Card Lifecycle](/concepts/card-lifecycle) -- Amendment tracking, reclassification, and trust recovery
* [Policy Engine](/concepts/policy-engine) -- Governance-as-code bridging cards to concrete tools
* [AP-Traces](/concepts/ap-traces) -- How agent actions are recorded for verification against cards
* [Integrity Checkpoints](/concepts/integrity-checkpoints) -- Real-time analysis of agent thinking against cards
* [Value Coherence](/concepts/value-coherence) -- Checking card compatibility between agents
* [AAP Specification](/protocols/aap/specification) -- Full normative specification