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

# Agent Cards

> Every Mnemom agent has two cards — an alignment card (who the agent is and what it's allowed to do) and a protection card (how it's defended). Both are YAML, both are addressable resources, both compose across up to four scopes.

Every Mnemom agent has **two cards**:

* An **[alignment card](/concepts/alignment-cards)** — who the agent is, what it values, what it's allowed to do, and its self-declared behavioral limits. Agent-owned (with org/platform as the composition floor).
* A **[protection card](/concepts/protection-card)** — how Safe House guards the agent at runtime, and the org's enforced protection policy. Org-owned.

Both are YAML documents. Both compose across up to four scopes (platform > org > team *(optional)* > agent). Both are versioned, auditable, and edit-friendly. This page is the customer-facing orientation to the two-card model — how it fits together and why.

## The two cards

### Alignment card

The alignment card answers *who the agent is and what it may do*. Its sections:

| Section | What it declares |
| - | - |
| `identity` | Card ID, agent ID, issued\_at, expires\_at |
| `principal` | Who the agent serves (org, user, agent) and the nature of the relationship |
| `values` | Declared values, definitions, conflicts\_with, priority hierarchy |
| `conscience` | Inviolable commitments (BOUNDARY / FEAR / COMMITMENT / BELIEF / HOPE entries) |
| `integrity` | Enforcement mode (`observe` / `nudge` / `enforce`) — how integrity checkpoints act |
| `autonomy` | `bounded_actions`, `forbidden_actions`, escalation triggers, max autonomous value |
| `capabilities` | Tool mappings (`capability_name → tool pattern`), enforcement semantics |
| `enforcement` | Policy-level knobs: allow\_unmapped\_tools, default severities |
| `audit` | Trace format, retention, query endpoint, tamper evidence |
| `extensions` | Protocol-specific additions (A2A, MCP, user-defined) |

The full normative schema is at [/specifications/alignment-card-schema](/specifications/alignment-card-schema).

### Protection card

The protection card answers *how this agent is defended at runtime* and *what the org has declared as the protected surface*. Its sections:

| Section | What it declares |
| - | - |
| `mode` | `observe` / `nudge` / `enforce` (see below) |
| `thresholds` | Per-signal cutoffs (injection, exfiltration, canary, semantic-novelty, etc.) |
| `screen_surfaces` | Which surfaces Safe House inspects (`incoming`, `outgoing`, `tool_calls`, `tool_responses`). The front door runs once per enabled inbound surface a request carries, so `tool_responses` means each tool result is screened inside the request that carries it back to the model — see [When the front door runs](/concepts/safe-house#when-the-front-door-runs) |
| `trusted_sources` | Per-scope allowlists for data sources the agent may ingest without full scanning |
| `protected_surface` | **Org's enforced policy**: `assets` (sealed records, sensitive fields), `forbidden_operations` (categorically blocked actions), `escalation_required` (actions needing elevated authority). Org-owned — not agent-authored. Safe House L2 enforces it independent of what the agent declares. |

The full normative schema is at [/specifications/protection-card-schema](/specifications/protection-card-schema).

## Why two cards

Alignment and protection are different concerns with different stakeholders:

* **Alignment** is the agent's self-declaration (with org/platform as the floor): what it values, what it's *allowed to* do, and what it *promises* about logging. Editing the alignment card is an intentional product decision.
* **Protection** is the org's enforced policy: runtime monitoring surfaces, threat thresholds, trusted sources, and — critically — the **`protected_surface`** (assets, forbidden operations, escalation requirements). Editing the protection card is a security posture decision made by org admins, not by the agent.

Separating them means:

1. **Different edit cadence.** Alignment changes rarely; protection tuning is frequent. Two cards = two change histories.
2. **Different approvers.** Platform admins may need to approve alignment changes; org admins may manage protection tuning.
3. **Honest audit trails.** You can ask "what did the agent commit to?" separately from "how hard were we watching?"

Before the unified-cards model, these concerns were tangled: an AAP alignment card lived alongside a CLPI policy YAML and a Safe House JSON config. The unified model collapses the alignment side of the triangle (AAP card + CLPI policy + `agents.aip_enforcement_mode` + org conscience values all absorbed into one `alignment-card.yaml`) and elevates the protection side to a proper card (`protection-card.yaml` replaces the ad-hoc Safe House config).

## Up to four scopes

Both cards compose across scopes, in this order — every later layer can only tighten what earlier layers declared, never loosen:

| Scope | Purpose | Who edits |
| - | - | - |
| **Platform** | Defaults for all agents on Mnemom — the absolute floor | Mnemom platform team |
| **Org** | Defaults for all agents in an organization — the org-level floor | Org owner / admin |
| **Team** *(optional)* | Defaults for agents grouped into a team — only present when the agent belongs to one or more teams | Org owner/admin, or a delegated [Team Admin](/concepts/team-admin-role) |
| **Agent** | Per-agent overrides and specialization | Agent owner |

An agent in zero teams — including most personal-org agents — composes under the 3-layer `platform → org → agent` cascade. An agent in one or more teams picks up the team layer between org and agent. See [Team Scope](/concepts/team-scope).

Composition runs at **storage time**, not per request. When any scope changes, affected agents are marked `needs_recompose` and the background composer regenerates their canonical cards. Every gateway read hits the pre-composed canonical card, so the request path has zero merge cost.

Field-level composition semantics — union, strictest-wins, min/max, agent-scoped, and so on — vary by section. See [Card Composition](/concepts/card-composition) for the full field-by-field rules table and worked examples.

### Exemptions

Granular **exemptions** let an org admin waive specific sections of the org card for a specific agent without exempting the whole card. For example: "exempt this research agent from `forbidden_actions.no_external_api_calls`, nothing else."

Exemptions are:

* Section-specific (one exemption targets one field, not the whole card).
* Optionally pattern-scoped (specific values within the section).
* Time-bounded (default 90-day expiry) and audit-logged.
* Required fields: `reason`, `granted_by`, `granted_at`.

This replaces the legacy boolean `org_card_exempt` flag, which was an all-or-nothing escape hatch.

## The canonical URL surface

Both cards are first-class API resources, addressable through one uniform URL shape at every scope:

```
/v1/<resource>/<scope>/<scope_id>[/<verb>]
```

where `<resource>` is `alignment` or `protection`, `<scope>` is `platform` / `org` / `team` / `agent`, and `<scope_id>` is a stable identifier (the literal string `default` for the platform scope). The verbs are a small fixed set:

```bash theme={null}
GET    /v1/alignment/agent/mnm-512448e7                # this layer's spec
PUT    /v1/alignment/agent/mnm-512448e7                # full replace
DELETE /v1/alignment/org/acme-corp                      # clear this layer (org/team only)
POST   /v1/alignment/org/acme-corp/preview-compose      # dry-run composer
GET    /v1/alignment/agent/mnm-512448e7/effective       # composed view + per-field provenance
```

The same shape works for `protection`. One routing table covers every scope for both resources — authoring tools, CI Actions, and SDKs build it once.

Older, scope-specific URLs (`/v1/agents/{id}/alignment-card`, `/v1/orgs/{id}/alignment-template`, `/v1/admin/platform-card/alignment`, and their protection + preview-compose equivalents) still work: each returns an HTTP 308 Permanent Redirect ([RFC 7538](https://www.rfc-editor.org/rfc/rfc7538)) to its canonical equivalent, preserving the original method and body, with `Deprecation`/`Sunset`/`Link` headers pointing here. Point new code at the canonical URL directly — it's the same call, one hop shorter.

One legacy path per resource × scope, so org/team/platform callers don't have to infer the pattern:

| Legacy | Canonical |
| - | - |
| `/v1/agents/{id}/alignment-card` | `/v1/alignment/agent/{id}` |
| `/v1/agents/{id}/protection-card` | `/v1/protection/agent/{id}` |
| `/v1/orgs/{id}/alignment-template` | `/v1/alignment/org/{id}` |
| `/v1/orgs/{id}/protection-template` | `/v1/protection/org/{id}` |
| `/v1/teams/{id}/alignment-template` | `/v1/alignment/team/{id}` |
| `/v1/teams/{id}/protection-template` | `/v1/protection/team/{id}` |
| `/v1/admin/platform-card/alignment` | `/v1/alignment/platform/default` |
| `/v1/admin/platform-card/protection` | `/v1/protection/platform/default` |

Each row's `GET`/`PUT`/`DELETE`/`.../preview-compose` verbs redirect the same way — only the resource path changes.

This canonical surface is also the foundation for two more capabilities:

* **[Sub-resource verbs](/concepts/sub-resource-verbs)** — `PUT`/`PATCH /v1/<resource>/<scope>/<scope_id>/<primitive>` to set just one primitive without replacing the whole spec.
* **[AI helpers](/concepts/ai-helpers)** — `scaffold`, `explain`, `simulate` — natural-language and probing UX bound to the same root namespace.

## How the cards are used

### Runtime (gateway)

Every request through the Mnemom gateway:

1. Fetches the agent's canonical **alignment card** (cached, 5-min TTL; `needs_recompose` bypass on org-template updates).
2. Maps the unified card to the locked AAP `AlignmentCard` shape for any call to `@mnemom/agent-alignment-protocol`.
3. Extracts policy from `capabilities` + `enforcement` sections for policy evaluation via `@mnemom/policy-engine`.
4. Fetches the canonical **protection card** for [Safe House](/concepts/safe-house) detection. The card's `protected_surface` (org-owned `assets`, `forbidden_operations`, `escalation_required`) is the source of truth for Safe House L2 enforcement — independent of what the agent declares in its alignment card.
5. Applies alignment-card `autonomy.forbidden_actions` as a behavioral hard deny; applies `integrity_mode` to the checkpoint pipeline; applies protection-card `protected_surface.forbidden_operations` as the org's hard policy floor via Safe House.

All of this is one canonical-card read per concern, not a lazy per-request merge. One *read*, not one *screen*: the card is fetched once, then Safe House applies it once per enabled inbound surface the request carries — the message, and each tool result travelling back to the model in the same body.

### Observer (trace analysis)

The observer pipeline reads the canonical alignment card for trace verification (`verifyTrace` against the card's values/autonomy contract) and drift detection. It does not touch the protection card (protection is inline at the gateway).

### Website (human surfaces)

Agent owners edit alignment cards in the YAML-first card editor at `mnemom.ai/dashboard/agents/{id}/card`. Protection cards are edited under the security tab. Both surfaces show the **raw** agent-scope card alongside the **canonical** card (composed with platform + org defaults), so owners can see which values are coming from where.

Org admins manage org-scope templates and exemptions from the org dashboard.

### CLI

```bash theme={null}
mnemom card show                       # canonical alignment card (YAML)
mnemom card edit                       # open in $EDITOR
mnemom card publish agent.card.yaml    # validate, publish, trigger recompose
mnemom card evaluate agent.card.yaml --tools tools.json

mnemom protection show                 # canonical protection card (YAML)
mnemom protection edit
mnemom protection publish protection.card.yaml
```

There's no more separate `mnemom policy …` command; policy is now a section of the alignment card, exposed via `card evaluate`.

## Card lifecycle

* **Creation.** First publish triggers composition against platform + org scopes, writing a canonical card into `canonical_agent_cards`.
* **Amendment.** Updating the agent-scope card triggers `compose_agent_card` and writes a new canonical row.
* **Org template change.** Updating an org-scope template sets `needs_recompose` on all affected agents; the background composer regenerates them. Until recompose runs, reads serve the stale canonical with an explicit staleness flag.
* **Expiry.** `expires_at` in the alignment card is advisory; the composer refuses to emit a canonical card whose `expires_at` is in the past.
* **Audit.** Every mutation is logged to `governance_audit_log` synchronously with an `Idempotency-Key` + two-phase dedupe (reserve → finalize/release).

See [Card Lifecycle](/concepts/card-lifecycle) for state transitions and [Card Composition](/concepts/card-composition) for the recompose pipeline.

## Modes across both cards

Both cards use the `observe` / `nudge` / `enforce` vocabulary, but apply it to different layers:

| Value | Alignment card (`integrity_mode`) | Protection card (`mode`) |
| - | - | - |
| `observe` | Integrity checkpoints run; violations are logged but not acted on | Safe House detectors run; signals are logged |
| `nudge` | Violations trigger a nudge to the agent (soft warning) | Detectors return guidance; agent may choose to revise |
| `enforce` | Violations hard-block the action | Detectors may block the action outright |

A fleet is most coherent when both cards use matching modes across all agents. The [v2 fleet coherence scorer](/concepts/fleet-coherence) checks `integrity_mode` uniformity as a structural invariant (`integrity_uniform`).

## See also

* [Alignment Card (AAP 1.0 protocol surface)](/concepts/alignment-cards) — the protocol-level card, stable for external interop
* [Protection Card](/concepts/protection-card) — Safe House card schema and semantics
* [Card Composition](/concepts/card-composition) — the full platform → org → team → agent composition rules + exemptions
* [Alignment Card Schema](/specifications/alignment-card-schema) — normative unified-card YAML
* [Protection Card Schema](/specifications/protection-card-schema) — normative protection YAML
* [Safe House](/concepts/safe-house) — the runtime protection pipeline the protection card configures
* [Policy Engine](/concepts/policy-engine) — how `capabilities` + `enforcement` sections become runtime policy


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.