Agent Cards

Every Mnemom agent has two cards:

An alignment card — 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 — 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.

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

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:

Different edit cadence. Alignment changes rarely; protection tuning is frequent. Two cards = two change histories.
Different approvers. Platform admins may need to approve alignment changes; org admins may manage protection tuning.
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
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. 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 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:

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) 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 — PUT/PATCH /v1/<resource>/<scope>/<scope_id>/<primitive> to set just one primitive without replacing the whole spec.
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:

Fetches the agent’s canonical alignment card (cached, 5-min TTL; needs_recompose bypass on org-template updates).
Maps the unified card to the locked AAP AlignmentCard shape for any call to @mnemom/agent-alignment-protocol.
Extracts policy from capabilities + enforcement sections for policy evaluation via @mnemom/policy-engine.
Fetches the canonical protection card for 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.
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

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 for state transitions and 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 checks integrity_mode uniformity as a structural invariant (integrity_uniform).

Overview

Identity & Cards

Posture & Policy

Detection & Safe House

AEGIS

Reputation & Risk

Lifecycle

Gateway

Pricing

Policy

Specifications

Changelog

The two cards

Alignment card

Protection card

Why two cards

Up to four scopes

Exemptions

The canonical URL surface

How the cards are used

Runtime (gateway)

Observer (trace analysis)

Website (human surfaces)

CLI

Card lifecycle

Modes across both cards

See also

​The two cards

​Alignment card

​Protection card

​Why two cards

​Up to four scopes

​Exemptions

​The canonical URL surface

​How the cards are used

​Runtime (gateway)

​Observer (trace analysis)

​Website (human surfaces)

​CLI

​Card lifecycle

​Modes across both cards

​See also

The two cards

Alignment card

Protection card

Why two cards

Up to four scopes

Exemptions

The canonical URL surface

How the cards are used

Runtime (gateway)

Observer (trace analysis)

Website (human surfaces)

CLI

Card lifecycle

Modes across both cards

See also