> ## Documentation Index > Fetch the complete documentation index at: https://docs.mnemom.ai/llms.txt > Use this file to discover all available pages before exploring further. # Trust Recovery > Recover agent trust scores by reclassifying card-gap violations and amending alignment cards When an agent's trust score drops due to violations, the **cause** matters. Not every violation reflects a genuine behavioral failure -- sometimes the agent acted correctly but the alignment card was missing a capability. These are **card gaps**, and they can be recovered through reclassification. This guide walks through the full recovery workflow: identifying whether a violation is a card gap or a behavior gap, submitting a reclassification request, amending the alignment card, and triggering score recomputation. *** ## Understanding card\_gap vs behavior\_gap Before reclassifying a violation, you need to determine its root cause. Violations fall into two categories, and only one is eligible for reclassification. **The alignment card was outdated or incomplete.** The agent behaved correctly given its actual capabilities, but the card did not declare those capabilities. Common causes: * **New tools added without updating the card** -- e.g., added MCP browser tools but the card did not declare `web_fetch` in `bounded_actions` * **Configuration drift after deployment changes** -- infrastructure updates introduced new action types the card did not anticipate * **Incomplete initial card setup** -- the card was created from a template and never customized to match the agent's real toolset **Example:** An agent uses `mcp__browser__navigate` to fetch documentation during a research task. The card lists `bounded_actions: ["inference", "read", "write"]` but does not include `web_fetch`. The integrity checkpoint flags a boundary violation -- but the agent did exactly what it was supposed to do. The card was wrong, not the agent. **Eligible for reclassification:** Yes. **The agent genuinely violated its declared intent.** The card accurately described the expected behavior, but the agent acted outside those boundaries. Common causes: * **Used forbidden actions** -- the agent performed an action explicitly listed in `forbidden_actions` * **Exceeded autonomy boundaries** -- the agent took autonomous action beyond its declared limits (e.g., spent over the `max_autonomous_value` threshold) * **Failed to escalate when required** -- an escalation trigger condition was met but the agent did not escalate **Example:** An agent with `forbidden_actions: ["exfiltrate_data"]` sends user data to an external endpoint. The card was correct; the agent violated it. **Eligible for reclassification:** No. Address the root cause by fixing agent behavior, adjusting prompting, or tightening escalation triggers. The root cause that inspired CLPI: an agent repeatedly broke verification due to configuration drift (new tools added without updating the alignment card). The violations were config errors, not behavioral errors, yet trust scores declined. *** ## Reclassification workflow ### Step 1: Identify violations to reclassify Review recent violations via API or dashboard to find checkpoints that may be card gaps. Fetch existing reclassifications and pending violations: ```bash theme={null} curl https://api.mnemom.ai/v1/agents/{agent_id}/reclassifications \ -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" ``` Or check the agent's canonical alignment card and evaluate it against the tools the agent actually uses — the composed card's `capabilities` and `enforcement` sections are what the policy engine enforces, and unmapped tools surface as `card_gap` candidates: ```bash theme={null} # Fetch the canonical alignment card (includes composition metadata) curl -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \ "https://api.mnemom.ai/v1/alignment/agent/{agent_id}?include_composition=true" # Or evaluate a tool set against the agent's current canonical card to see # coverage + violations. The policy is derived server-side from the card -- # you pass the agent and the tools, not a policy document. curl -X POST https://api.mnemom.ai/v1/policies/evaluate \ -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "{agent_id}", "tools": [{ "name": "mcp__browser__navigate" }, { "name": "mcp__filesystem__read_file" }], "dry_run": true }' ``` Look for checkpoints where: * The `verdict` is `boundary_violation` * The agent's action was correct given its real capabilities * The checkpoint's `concerns[]` (each with a `category`, `severity`, and `evidence`) describe a capability the card didn't declare, rather than a genuine policy breach * The card's `bounded_actions` or `escalation_triggers` did not cover the action Only violations classified as `card_gap` are eligible for reclassification. Attempting to reclassify a genuine `behavior_gap` will be rejected by the API and may flag the agent for review. ### Step 2: Submit reclassification request Submit a reclassification for each checkpoint that was a card gap. Include a clear reason documenting why this was a card issue, not a behavioral one. ```bash curl theme={null} curl -X POST https://api.mnemom.ai/v1/agents/{agent_id}/reclassify \ -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "checkpoint_id": "ic-abc12345", "reason": "Agent correctly used mcp__browser__navigate for research, but web_fetch was missing from card bounded_actions" }' ``` ```typescript TypeScript theme={null} const response = await fetch( `https://api.mnemom.ai/v1/agents/${agentId}/reclassify`, { method: 'POST', headers: { 'X-Mnemom-Api-Key': apiKey, 'Content-Type': 'application/json', }, body: JSON.stringify({ checkpoint_id: 'ic-abc12345', reason: 'Agent correctly used mcp__browser__navigate for research, but web_fetch was missing from card bounded_actions', }), } ); ``` ```python Python theme={null} import httpx response = httpx.post( f"https://api.mnemom.ai/v1/agents/{agent_id}/reclassify", headers={"X-Mnemom-Api-Key": api_key}, json={ "checkpoint_id": "ic-abc12345", "reason": "Agent correctly used mcp__browser__navigate for research, but web_fetch was missing from card bounded_actions", }, ) ``` The API returns a reclassification record with a unique ID and status. Reclassifications take effect immediately for score computation purposes. ### Step 3: Amend the alignment card Reclassification removes the penalty for past violations, but without updating the card, the same violation will recur on the next checkpoint. Always amend the card alongside reclassification. Update the card to include the missing capability. You can PUT a full replacement card (the full unified-card shape is in [/specifications/alignment-card-schema](/specifications/alignment-card-schema)), or, since only `autonomy.bounded_actions` needs to change here, PATCH just that sub-resource: ```bash theme={null} curl -X PATCH https://api.mnemom.ai/v1/alignment/agent/{agent_id}/autonomy \ -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H 'If-Match: "sha256:"' \ -H "Content-Type: application/json" \ -d '{ "bounded_actions": ["inference", "read", "write", "web_fetch", "web_search"] }' ``` `If-Match` is required on this sub-resource endpoint (optimistic concurrency) -- read the current hash from the card's `content_hash` field (`GET /v1/alignment/agent/{agent_id}`) first. This is a JSON merge patch: `bounded_actions` here replaces the whole array, so include the agent's existing bounded actions alongside the new one -- not just `web_fetch`. Or link the card amendment directly to the reclassification for a cleaner audit trail: ```bash theme={null} curl -X POST https://api.mnemom.ai/v1/agents/{agent_id}/reclassify \ -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "checkpoint_id": "ic-abc12345", "reason": "Card gap: web_fetch missing from bounded_actions", "card_amendment_id": "amend-xyz789" }' ``` Reclassifying without amending the card is a common mistake. The violation is forgiven, but the next checkpoint with the same action will produce a new violation. Always close the gap. ### Step 4: Trigger score recomputation After reclassification and card amendment, trigger a score recomputation to reflect the changes immediately. Without this step, the score updates on the next scheduled recomputation cycle. ```bash theme={null} curl -X POST https://api.mnemom.ai/v1/reputation/{agent_id}/recompute \ -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" ``` The recomputation recalculates all five scoring components (Integrity Ratio, Compliance, Drift Stability, Trace Completeness, and Coherence Compatibility) using the updated violation classifications. ### Step 5: Monitor trust graph propagation Score changes do not stop at the reclassified agent. A recurring sweep looks back over recent reclassifications and walks outward from each reclassified agent through recorded trust edges (team membership and other explicit trust relationships), breadth-first, up to 3 hops and 50 agents per sweep. Every agent it reaches gets its own Trust Rating fully recomputed from its own checkpoint data — see [Trust Graph Propagation](/concepts/card-lifecycle#trust-graph-propagation) for the full mechanics and its bounds. Subscribe to webhook events to be notified as connected agents' scores move: ```bash theme={null} curl -X POST https://api.mnemom.ai/v1/orgs/{org_id}/webhooks \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "url": "https://your-server.com/webhooks/mnemom", "event_types": ["reputation.score_changed", "reputation.grade_changed"] }' ``` ### Step 6: Export compliance record After recovery, export the full compliance record for audit purposes. The export includes the original violations, reclassification decisions, card amendments, and score history. ```bash theme={null} curl https://api.mnemom.ai/v1/agents/{agent_id}/compliance-export \ -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" ``` The export is a JSON document suitable for regulatory review, SOC 2 evidence, or internal governance reporting. *** ## Best practices Violations continue to impact scores until reclassified. The longer a card-gap violation sits unaddressed, the more it drags down the Compliance and Integrity components. Reclassification without a card amendment is incomplete. The same action will trigger the same violation on the next checkpoint. Close the loop. Run `POST /v1/policies/evaluate` against your agent's real tools regularly. Its `card_gaps` field surfaces systematic gaps between what your agent does and what the card declares before they turn into checkpoint violations. Reclassification reasons are stored in the audit trail. Write reasons that a reviewer (human or automated) can understand months later. Before publishing a new card version, review reclassification history to ensure all known gaps are addressed in the updated card. Use `mnemom card evaluate card.yaml --tools ` to catch card gaps before they become violations. Run this in CI after any card or tool configuration change — see [CI/CD policy gates](/guides/ci-cd-policy-gates). *** ## See also * [Card Lifecycle](/concepts/card-lifecycle) -- How cards evolve over time * [Reputation Scores](/concepts/reputation-scores) -- Score computation methodology * [Reclassification API](/api-reference/reclassification-overview) -- Full API reference for reclassification endpoints * [Card Management](/guides/card-management) -- Creating, validating, and publishing alignment cards * [Policy Management](/guides/policy-management) -- Policy setup and configuration This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.