Skip to main content
Between 2026-04-13 and 2026-04-17, Mnemom migrated from a split AAP card + CLPI policy + Safe House config model to the unified card model. This guide is for early adopters who had agents on the pre-UC model. It documents what changed, what the automatic migration did for you, and what (if anything) you need to verify or update. If your first Mnemom agent was created on or after 2026-04-16, you are already on the unified model. This guide is primarily historical; skim the “What changed” section for context and skip the rest.

​
What changed

​
Three things became one

The pre-UC governance artifacts for a single agent:
ArtifactWhere it livedWhat it declared
AAP alignment cardalignment_cards rowIdentity, principal, values, autonomy envelope, audit commitment
CLPI policypolicies rowCapability mappings, forbidden tools, enforcement mode
Safe House configsh_configs rowDetector thresholds, screen surfaces, trusted sources
Each had its own endpoint, its own CLI command group, its own amendment history, and its own role in the request path. The gateway lazy-merged them on every request. The post-UC model collapses the first two into one unified alignment card and elevates the third into a proper protection card:
ArtifactWhere it livesWhat it declares
Alignment card (unified)canonical_agent_cards (composed) + alignment_cards (raw agent-scope)Identity, principal, values, conscience, integrity, autonomy, capabilities, enforcement, audit
Protection cardcanonical_protection_cards (composed) + sh_configs (raw agent-scope)Mode, thresholds, screen_surfaces, trusted_sources
New first-class sections in the alignment card:
  • conscience — inviolable commitments (absorbed from org-scope org_conscience_values + orgs.conscience_mode)
  • integrity — enforcement mode (absorbed from agents.aip_enforcement_mode column)
  • capabilities + enforcement — policy fields (absorbed from the old separate policies table)
Plus three-scope composition (platform > org > agent) and granular exemptions.

​
Three things that did NOT change

  • AAP 1.0 protocol is untouched. @mnemom/agent-alignment-protocol@1.0.0 still emits and consumes the same shape. External agent interop still uses the AAP card for handshakes. The unified card is a superset; the gateway maps unified → AAP at the boundary.
  • AIP 1.0 protocol is untouched. Integrity checkpoint semantics are stable.
  • Safe House detection types are stable. The SafeHouseConfig type that detectors consume (PatternMatcher, SignalScorer, etc.) didn’t change. UC swapped the fetch source underneath, not the type.

​
What the automatic migration did

On 2026-04-15, the UC-3 data migration ran against production. For every active agent:
  1. Read alignment_cards (AAP card) + policies (CLPI policy) + agents.aip_enforcement_mode + org conscience values.
  2. Composed them into a unified alignment card.
  3. Ran compose_agent_card(agent_id) to generate the canonical row.
  4. Same for protection: sh_configs → unified protection card → compose_protection_card.
Result: 103/103 production agents composed in 31 seconds. No customer action was required. The migration is idempotent — re-running it would produce the same canonical output. The raw alignment_cards and sh_configs rows are retained for historical reference but no longer serve the request path.

​
What’s removed

The following endpoints are gone:
Old endpointReplacement
GET /v1/agents/:id/card (AAP shape)GET /v1/agents/:id/alignment-card (unified shape, YAML or JSON)
PATCH /v1/agents/:id/cardPUT /v1/agents/:id/alignment-card
GET /v1/agents/:id/cfd/configGET /v1/agents/:id/protection-card
PUT /v1/agents/:id/cfd/configPUT /v1/agents/:id/protection-card
GET/PUT/DELETE /v1/agents/:id/policyAbsorbed into the alignment card (capabilities + enforcement sections)
GET/PUT/DELETE /v1/orgs/:id/card-templateGET/PUT/DELETE /v1/orgs/:id/alignment-template
GET/PUT/DELETE /v1/orgs/:id/policyAbsorbed into the org alignment template
PUT /v1/agents/:id/org-card-exemptReplaced by granular exemptions: POST /v1/agents/:id/exemptions
No deprecation window — at n=1 external install base, we cut the old endpoints outright. See ADR-006 amendment (2026-04-15) for the reasoning. The following CLI commands are gone:
Old commandReplacement
mnemom initNot needed — mnemom register is the entry point
mnemom policy show/publish/evaluate/validatemnemom card evaluate agent.card.yaml --tools tools.json and card commands
mnemom migrate-configAutomatic on first run — ~/.smoltbot/ auto-migrates to ~/.mnemom/auth.json
mnemom agents … (subcommands)Removed — server-side agent resolution
The following database columns are now dormant and will be dropped in the UC-14 cleanup migration:
  • agents.org_card_exempt
  • agents.aip_enforcement_mode
  • orgs.conscience_mode
  • orgs.conscience_values_enabled
The canonical-card composer still reads them as fallbacks for any agent whose raw storage predates UC-4; once the fallback rate is confirmed zero over a 7-day rolling window, the columns and the fallback code path are dropped together.

​
Verifying your agents are on the unified model

For anyone who had agents pre-UC, the following checks confirm your migration succeeded.

​
Check 1: every agent has a canonical alignment card

curl -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \
  https://api.mnemom.ai/v1/agents/{agent_id}/alignment-card?include_composition=true
Expected: a unified/2026-04-15 card with _composition metadata showing composed_at within the last week (or since your last card edit, whichever is more recent). If you get a 404 or the returned card is card_version: "0.5.0" (the old AAP version), that’s a migration miss — file an issue.

​
Check 2: every agent has a canonical protection card

curl -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \
  https://api.mnemom.ai/v1/agents/{agent_id}/protection-card?include_composition=true
Expected: card_version: protection/2026-04-15.

​
Check 3: no references to legacy endpoints in your clients

If you have any clients calling the old endpoints, they’re getting 404s now. Search your integrations: 
# In your client code
grep -rn "/v1/agents/[^/]*/card\b" .
grep -rn "/v1/agents/[^/]*/cfd/config" .
grep -rn "/v1/agents/[^/]*/policy" .
grep -rn "/v1/orgs/[^/]*/card-template" .
Replace with:
  • /v1/agents/{id}/alignment-card
  • /v1/agents/{id}/protection-card
  • The alignment-card endpoint (policy fields are now card sections)
  • /v1/orgs/{id}/alignment-template

​
Check 4: CLI is on the unified version

mnemom --version   # expect: @mnemom/mnemom@<recent>
mnemom card show   # should print YAML, not JSON
If mnemom init or mnemom policy still work, your CLI is outdated. Update: 
npm install -g @mnemom/mnemom@latest

​
Writing cards for the unified model

  • YAML is canonical. The editor and CLI use YAML. JSON still works at the API boundary for machine clients, but the authored source is YAML.
  • Follow the alignment-card-schema. The sections you care about are values, conscience, integrity, autonomy, capabilities, audit. Most authors never need to touch principal or enforcement.
  • Compose, don’t duplicate. If your org has a shared value like harm_prevention, put it in the org template, not in every agent’s card. The composer takes care of the rest.
  • Use exemptions sparingly, with reasons. Exemptions are audit-logged and expire. They’re the right tool for a genuine specialist need; not a convenient override.

​
Pre-UC card format (archival reference)

For completeness, the pre-UC AAP 0.5 card looked like this. Your alignment_cards table still has historical rows in this shape, but no request path reads them directly anymore. 
{
  "aap_version": "0.5.0",
  "card_id": "ac-...",
  "agent_id": "mnm-...",
  "principal": { ... },
  "values": { ... },
  "autonomy_envelope": {         // renamed to `autonomy` in unified
    "bounded_actions": [...],
    "forbidden_actions": [...],
    "escalation_triggers": [...]
  },
  "audit_commitment": { ... }    // renamed to `audit` in unified
}
Plus a separate CLPI Policy YAML file and a Safe House JSON config. Those are all gone. The capabilities, enforcement, conscience, and integrity sections in the unified card absorb everything they used to hold.

​
See also