AI Helpers

The cards API ships three AI-forward verbs that make manifest authoring self-serve. They wrap the platform’s existing capabilities — LLM, policy engine, observer — and surface them through care-framed HTTP endpoints.

Verb	Endpoint	What it does
scaffold	`POST /v1/<resource>/scaffold`	Natural-language description → starting-point manifest YAML + reasoning.
explain	`POST /v1/<resource>/<scope>/<id>/explain`	”Why did the policy engine flag this?” Returns structured trace + remediations.
simulate	`POST /v1/<resource>/<scope>/<id>/simulate`	Dry-run gateway + observer against a hypothetical tool call.

All three are read-style POSTs. They don’t mutate state, so they don’t take Idempotency-Key or If-Match. They’re idempotent by construction.

scaffold — natural language to a manifest

You describe what you want; the platform writes the starting manifest.

curl -X POST https://api.mnemom.ai/v1/alignment/scaffold \
  -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "A finance agent that reads invoices, drafts payment summaries, and posts to a treasury Slack channel — never executes payments itself",
    "scope": "agent",
    "hints": {
      "industry": "finance",
      "risk_appetite": "conservative"
    }
  }'

Response:

{
  "ok": true,
  "resource": "alignment",
  "manifest": "card_version: \"unified/2026-04-26\"\nagent_id: \"<placeholder>\"\nautonomy_mode: observe\n...",
  "reasoning": "This manifest covers a finance agent that depends on read-only access to invoices and outbound communication. The agent's principal would benefit from a `delegated_authority` relationship — payments are an irreversible external write and stay outside the agent's autonomy. Two values are declared: `alignment_with_principal_objective` and `policy_attentiveness` with `domain: financial`. The audit retention is 90 days reflecting finance-domain norms.",
  "suggested_catalog_entries": ["alignment_with_principal_objective", "policy_attentiveness", "deliberation_before_action"],
  "coverage_gaps": [],
  "cached": false,
  "model": "claude-haiku-4-5-20251001"
}

manifest — editable YAML. Run it through PUT /v1/alignment/<scope>/<id> to commit, or hand it to the mnemom/cards-action for PR review.
reasoning — care-framed prose explaining the choices.
suggested_catalog_entries — values the model would recommend; consider them, then accept or adjust.
coverage_gaps — primitives the model thinks would benefit from operator attention.
cached — true when the response was served from the description-hash cache (24h TTL).

See Card Management for the full authoring flow.

explain — why did the policy engine flag this?

You ask “what’s wrong with this agent’s spec?”; the platform runs the policy engine and translates the structured findings into prose you can act on.

curl -X POST https://api.mnemom.ai/v1/alignment/agent/smolt-512448e7/explain \
  -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "ok": true,
  "resource": "alignment",
  "trace": {
    "verdict": "warn",
    "violations": [],
    "warnings": [
      {"type": "unmapped_tool", "tool": "filesystem_read", "reason": "..."}
    ],
    "card_gaps": [],
    "coverage": { "coverage_pct": 92, "total_card_actions": 13, "mapped_card_actions": [...] }
  },
  "reasoning": "The alignment policy evaluation completed in 2ms with verdict `warn`. 1 warning present. Coverage: 92% of the agent's declared actions map to capabilities (12/13).",
  "suggested_remediations": [
    {
      "for": "warning",
      "index": 0,
      "remediation": "Mapping `filesystem_read` to a capability would replace this warning with explicit coverage. Run `PATCH /v1/alignment/agent/smolt-512448e7/capabilities`.",
      "method": "PATCH",
      "url": "/v1/alignment/agent/smolt-512448e7/capabilities"
    }
  ],
  "enriched": false
}

Each remediation carries a method + url hint that points at the sub-resource verb that would resolve it. Care-framing throughout — the prose uses “would benefit from”, “depends on”, “would close this gap” rather than compliance language. Set "enrich": true in the body to call the LLM and expand the structured remediations into long-form prose (off by default; rate-limited). See the explain guide for the full debug-and-fix flow.

simulate — dry-run before you commit

You describe a hypothetical tool call; the platform runs the gateway and observer evaluators against the agent’s current spec and tells you whether the call would be allowed.

curl -X POST https://api.mnemom.ai/v1/alignment/agent/smolt-512448e7/simulate \
  -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "candidate_tool_call": {
      "tool_name": "campfire_send_message",
      "tool_args": {"channel": "treasury", "message": "..."}
    }
  }'

Response:

{
  "ok": true,
  "resource": "alignment",
  "allowed": "conditional",
  "conditions": ["receipt:think needed before invoking `campfire_send_message`"],
  "suggestions": ["Run the `think` consultation first, then retry — the gateway hook would clear."],
  "gateway_decision": {
    "verdict": "warn",
    "violations": [],
    "warnings": [],
    "missing_receipts": ["think"]
  },
  "observer_assessment": {
    "verdict": "pass",
    "violations": [],
    "warnings": []
  },
  "evaluated_at": "2026-05-21T18:42:13Z"
}

allowed is one of:

"true" — both gateway and observer pass with no conditions.
"false" — at least one verdict is fail.
"conditional" — passes but requires a receipt or carries warnings. The conditions[] array names what’s needed.

Use this before you commit a manifest change, or to test whether a specific tool call would clear the policy. See the simulate guide for the full pre-commit workflow.

Rate limits

LLM-backed verbs (scaffold, and explain/simulate when called with "enrich": true) share a per-principal budget:

Window	Default	Override
Per user	10 calls/hour	`LLM_USER_HOURLY_CAP` env var
Per org	100 calls/hour	`LLM_ORG_HOURLY_CAP` env var

On exceed: 429 Too Many Requests with a Retry-After header and a care-framed body. explain and simulate are pure-sync (no LLM) by default; they don’t consume the LLM budget unless you pass "enrich": true.

Care-framed by construction

Every customer-facing string in the response surface — error messages, reasoning prose, suggested remediations — is asserted by the platform’s care-framing test to avoid compliance vocabulary (Blocked / Denied / Required / Forbidden / Violation / Must). The replacement vocabulary is would benefit from, depends on, run X then retry, you’d be supported by. LLM-generated prose runs through a post-check that swaps any slips automatically.

Cache + freshness

scaffold caches LLM responses by a hash of the input (model + scope + description + hints). Identical inputs return identical outputs without burning the LLM budget — 24-hour TTL. explain and simulate are not cached — they consume live spec state.

Sub-resource verbs — the write surface the remediations point at.
Agent Cards — the URL surface that wraps it all.
Policy engine — what explain and simulate are surfacing.
Care-framing doctrine — the operator vocabulary every helper uses.

Overview

Identity & Cards

Posture & Policy

Detection & Safe House

AEGIS

Reputation & Risk

Lifecycle

Gateway

Pricing

Policy

Specifications

Changelog

scaffold — natural language to a manifest

explain — why did the policy engine flag this?

simulate — dry-run before you commit

Rate limits

Care-framed by construction

Cache + freshness

​scaffold — natural language to a manifest

​explain — why did the policy engine flag this?

​simulate — dry-run before you commit

​Rate limits

​Care-framed by construction

​Cache + freshness

​Related reading

scaffold — natural language to a manifest

explain — why did the policy engine flag this?

simulate — dry-run before you commit

Rate limits

Care-framed by construction

Cache + freshness

Related reading