Managing Card Composition

How to actually use the three-scope composition model: managing org templates, granting and revoking exemptions, reading canonical cards, and debugging where a field came from. The conceptual page is the why and the rules; this page is the how.

Who does what

Actor	What they manage	Where
Mnemom platform team	Platform policy (alignment + protection floors)	`platform_policies` row — not user-editable
Org owner / admin	Org templates (alignment + protection) and org-wide exemptions	`/dashboard/orgs/{id}/templates` + CLI
Agent owner	Agent’s raw alignment + protection cards	`/dashboard/agents/{id}/card` + `mnemom card edit`

Each scope can only edit its own layer. An agent owner cannot override an forbidden_actions entry from the org scope; an org admin cannot downgrade the platform’s audit.retention_days floor.

Managing an org alignment template

View the current template

# CLI
curl -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \
  https://api.mnemom.ai/v1/alignment/org/{org_id}

Or visit /dashboard/orgs/{id}/templates in the website for a YAML-first editor.

Update the template

Publishing a new org template triggers mark_agents_for_recompose(org_id), which sets needs_recompose = true on every agent in the org. The background composer then regenerates each canonical card.

curl -X PUT https://api.mnemom.ai/v1/alignment/org/{org_id} \
  -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \
  -H "Content-Type: text/yaml" \
  -H "Idempotency-Key: <uuid>" \
  --data-binary @org-template.yaml

What an org template looks like

# org-template.yaml
card_version: unified/2026-04-15

values:
  declared:
    - principal_benefit
    - harm_prevention
    - transparency
  hierarchy: lexicographic

conscience:
  mode: augment
  values:
    - type: BOUNDARY
      content: "Never exfiltrate customer data to third-party tooling."
      severity: mandatory

integrity:
  enforcement_mode: enforce     # strictest wins — agents cannot downgrade

autonomy:
  forbidden_actions:
    - send_external_notification
    - modify_audit_logs

audit:
  retention_days: 120           # max across scopes wins — this lengthens beyond the platform floor

Every field you omit falls through to the platform default. Every field you include acts according to its composition rule.

Recompose timing

For small orgs (under 50 agents), recompose completes in under 2 seconds.
For large orgs (1000+ agents), the background worker paces the batch. Until recompose finishes, reads serve the previous canonical with the needs_recompose: true flag set.
The gateway respects the flag: when serving a needs_recompose canonical, it bypasses its 5-minute KV cache so changes are picked up as soon as recompose finishes.

To see recompose progress:

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.mnemom.ai/v1/orgs/{org_id}/agents?needs_recompose=true"

Empty response = recompose is done.

Managing an org protection template

Same shape as the alignment template, different fields:

# org-protection-template.yaml
card_version: protection/2026-04-15

mode: enforce                   # strictest across scopes wins

thresholds:
  injection_score: 0.70
  exfiltration_score: 0.80

screen_surfaces:
  incoming: true
  outgoing: true
  tool_calls: true
  tool_responses: true

trusted_sources:
  domains:
    - internal.acme.example

curl -X PUT https://api.mnemom.ai/v1/protection/org/{org_id} \
  -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \
  -H "Content-Type: text/yaml" \
  --data-binary @org-protection-template.yaml

Granting an exemption

Exemptions let an org admin waive a specific section of the org card for a specific agent, with an explicit reason, audit trail, and expiry. Use them when a single agent has a legitimate need that diverges from the org floor.

When to grant one

Specialist roles. An audit agent that needs modify_audit_logs (forbidden at platform scope) may be granted a scoped exemption with justification.
Debug workflows. A red-team agent that needs a canary pass-through for testing.
Legacy exceptions. An agent that predates a new org-wide forbidden action and needs time to migrate.

How to grant

curl -X POST https://api.mnemom.ai/v1/agents/{agent_id}/exemptions \
  -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "exempt_section": "autonomy.forbidden_actions",
    "exempt_patterns": ["modify_audit_logs"],
    "reason": "Audit agent requires modify_audit_logs for its compaction job; platform exemption granted by audit team 2026-04-17",
    "granted_by": "[email protected]",
    "expires_at": "2026-07-17T00:00:00Z"
  }'

Rules

Rule	Why
Exemption expires (default 90 days). Set `expires_at: null` for permanent — rare and audit-flagged.	Exemptions are narrow, contextual, and time-bounded by design.
`granted_by` and `reason` are required. Length minimums enforced.	Audit trail is the whole point.
`BOUNDARY`-typed conscience entries cannot be exempted.	Inviolable commitments are inviolable.
Exemptions on forbidden-action `modify_audit_logs` + `exfiltrate_data` are owner-only.	Platform-critical deny can only be waived by platform-level authorization.
Every grant + revocation writes a `governance_audit_log` row synchronously.	Non-repudiable.

Listing active exemptions for an agent

curl -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \
  https://api.mnemom.ai/v1/agents/{agent_id}/exemptions

Revoking an exemption

curl -X DELETE \
  -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \
  https://api.mnemom.ai/v1/agents/{agent_id}/exemptions/{exemption_id}

Deleting an exemption triggers an immediate compose_agent_card(agent_id) call — the canonical card is regenerated within a second or two with the exemption no longer honored.

Reading a canonical card

Via CLI

mnemom card show

mnemom card show renders the full composed card. The _composition metadata block — which scopes contributed which fields and which exemptions were honored — is not surfaced by the CLI today; use the API below to retrieve it.

Via API

curl -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \
  -H "Accept: text/yaml" \
  "https://api.mnemom.ai/v1/alignment/agent/{agent_id}?include_composition=true"

The response includes the composed card plus _composition metadata showing which scopes contributed which fields and which exemptions were honored.

Sample output

card_version: unified/2026-04-15
card_id: can-cd-88aa0011
agent_id: mnm-patch-001
issued_at: 2026-04-17T18:23:41Z

values:
  declared:
    - transparency        # from platform
    - harm_prevention     # from platform
    - incident_containment  # from org:acme
    - rollback_safety     # from org:acme
    - move_fast_break_things  # from agent
conscience:
  mode: augment
  values:
    - type: BOUNDARY      # from platform — inviolable
      content: "Never exfiltrate principal data to external systems."
autonomy:
  bounded_actions:        # from agent (agent-scoped)
    - rollback_deploy
    - scale_infrastructure
  forbidden_actions:      # deny-overrides union
    - exfiltrate_data     # from platform
    - modify_audit_logs   # from platform
    - send_external_notification  # from org:acme

_composition:
  composed_at: 2026-04-17T18:23:41Z
  scopes_applied: [platform, "org:acme", "agent:mnm-patch-001"]
  versions:
    platform: 3
    "org:acme": 17
    "agent:mnm-patch-001": 4
  exemptions_applied: []
  source_card_id: ac-f47ac10b
  canonical_id: can-cd-88aa0011

Debugging composition

”Why does this field have this value?”

The canonical card is the effective state. If a value you didn’t put in the agent card is still there, it came from a higher scope. Check _composition.scopes_applied and cross-reference with the per-field rules at /concepts/card-composition.

”Why isn’t my agent-scope change showing up?”

Three possibilities:

Recompose is still running. Check needs_recompose on the canonical row. The background worker clears it within seconds for small orgs, within a minute or two for larger orgs.
A higher scope is overriding. If you set integrity.enforcement_mode: observe at agent scope and the org requires enforce, the strictest-wins rule means your agent-scope value never takes effect. Look at _composition.scopes_applied to confirm your scope is listed.
Exemption not granted. If you’re trying to remove an org-scope forbidden_actions entry, you need an exemption. Setting something to false at agent scope doesn’t override a deny from a higher scope.

`card_source` structured log

Every gateway + observer card read emits a structured log entry with card_source: canonical_hit (or canonical_miss_fallback in the rare case where the canonical row is missing and the composer is still catching up). You can grep your gateway logs to see the actual read pattern:

# Example: count canonical hits vs fallbacks in the last hour
# (shape depends on your log aggregator)
grep 'card_source:' gateway.log | awk -F'card_source:' '{print $2}' | awk '{print $1}' | sort | uniq -c

The production criterion requires zero fallback events on production — indicating the canonical table is fully populated and every request reads from it.

Common patterns

Tightening the org forbidden list

You want to add external_http as forbidden for every agent in an org:

PUT /v1/alignment/org/{org_id} with autonomy.forbidden_actions including the new entry.
Wait for recompose to complete (needs_recompose=false on all agents).
Verify one agent’s canonical card shows the new entry in autonomy.forbidden_actions.
Agents that legitimately need external_http get individual exemptions.

Loosening a threshold for one agent

Protection card thresholds follow floor-plus-override: agents can set stricter (lower) thresholds but not looser (higher). If you need a looser threshold for a specific agent, that’s an exemption, not an agent-scope override.

Adding a conscience commitment fleet-wide

A new BOUNDARY commitment (“never modify the customer-facing price in an automated way”):

Add to org template’s conscience.values array.
Publish. Recompose propagates the new commitment to every canonical card.
The commitment is inviolable — no agent-scope exemption will remove it without platform-level authorization.

Guides

Safe House

Managing Card Composition

Who does what

Managing an org alignment template

View the current template

Update the template

What an org template looks like

Recompose timing

Managing an org protection template

Granting an exemption

When to grant one

How to grant

Rules

Listing active exemptions for an agent

Revoking an exemption

Reading a canonical card

Via CLI

Via API

Sample output

Debugging composition

”Why does this field have this value?”

”Why isn’t my agent-scope change showing up?”

`card_source` structured log

Common patterns

Tightening the org forbidden list

Loosening a threshold for one agent

Adding a conscience commitment fleet-wide

See also

​Who does what

​Managing an org alignment template

​View the current template

​Update the template

​What an org template looks like

​Recompose timing

​Managing an org protection template

​Granting an exemption

​When to grant one

​How to grant

​Rules

​Listing active exemptions for an agent

​Revoking an exemption

​Reading a canonical card

​Via CLI

​Via API

​Sample output

​Debugging composition

​”Why does this field have this value?”

​”Why isn’t my agent-scope change showing up?”

​card_source structured log

​Common patterns

​Tightening the org forbidden list

​Loosening a threshold for one agent

​Adding a conscience commitment fleet-wide

​See also

Who does what

Managing an org alignment template

View the current template

Update the template

What an org template looks like

Recompose timing

Managing an org protection template

Granting an exemption

When to grant one

How to grant

Rules

Listing active exemptions for an agent

Revoking an exemption

Reading a canonical card

Via CLI

Via API

Sample output

Debugging composition

”Why does this field have this value?”

”Why isn’t my agent-scope change showing up?”

`card_source` structured log

Common patterns

Tightening the org forbidden list

Loosening a threshold for one agent

Adding a conscience commitment fleet-wide

See also