Skip to main content
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 from three scopes (platform > org > 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: 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: 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:
  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).

​
Three scopes

Both cards compose from three scopes: 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 vary by section:
  • values.declared — union across scopes (platform ∪ org ∪ agent)
  • autonomy.forbidden_actions — union (deny-overrides: agent can never remove a platform or org forbidden action; they can only add more). This is the agent’s behavioral commitment on the alignment card.
  • autonomy.bounded_actions — agent-scoped (platform/org suggest defaults; agent cards take effect)
  • protected_surface (protection card) — strengthen-only union across platform → org → team → agent; org is the primary authoring scope. The agent can add entries but never remove or weaken a higher-scope entry. Enforced by Safe House L2 independent of agent self-declaration.
  • conscience.values — union with deduplication by content; platform/org commitments are inviolable floors
  • integrity_mode — strictest wins (if org requires enforce, agent cannot downgrade to observe)
  • capabilities.* — agent-scoped (capabilities are local to each agent’s tooling)
See Card Composition for the full composition 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.

​
How the cards are used

​
Runtime (gateway)

Every request through the Mnemom gateway:
  1. Fetches the agent’s canonical alignment card (KV-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 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.

​
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

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: 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).

​
See also