Policy Management

Policy is part of the alignment card. In the unified card model, what used to be a standalone policy document lives in the alignment card’s capabilities and enforcement sections. There is no separate PUT /v1/agents/:id/policy endpoint — publish the alignment card and the policy travels with it. The mnemom policy … CLI group has been removed in favor of mnemom card validate / mnemom card evaluate / mnemom card publish.This guide has been updated for the unified model. Sections that reference the AAP protocol shape describe the protocol-level interop surface; the unified card is what you write in production.

Policies bridge Alignment Cards (abstract values and bounded actions) to concrete tool usage enforcement. An alignment card declares that an agent may perform web_fetch. The card’s capabilities section defines that web_fetch means the agent can call mcp__browser__navigate and mcp__browser__click, but not mcp__filesystem__delete. The card declares intent. The enforcement section enforces it. A policy is made of:

Capability mappings (capabilities) — which concrete MCP tools satisfy which capability
Forbidden rules (enforcement.forbidden_tools) — which tools are always blocked, with reasons and severities
Enforcement defaults (enforcement, plus the card’s top-level autonomy_mode) — how unmapped tools are handled and how long new tools get a grace period

This guide walks through creating, testing, publishing, and managing policies using the CLI and API.

Quick start

Capability mapping walkthrough

Capability mappings are the core of every policy. They bridge the gap between what your alignment card declares (abstract semantic actions) and what your agent actually invokes (concrete MCP tool names).

Start from your alignment card

Look at your card’s autonomy.bounded_actions. These are the abstract actions your agent has declared:

{
  "autonomy": {
    "bounded_actions": [
      "web_fetch",
      "web_search",
      "read",
      "write",
      "send_response"
    ]
  }
}

(The AAP 1.0 protocol-level interop card places bounded_actions under a different parent key — see /concepts/alignment-cards for that surface, which is not submitted to mnemom card validate.) Each of these needs at least one capability mapping in your policy.

Identify concrete tools

List the MCP tools your agent actually uses. If you are unsure, check your agent’s recent traces:

mnemom logs --agent support-agent

This gives you the concrete tool names like mcp__browser__navigate, mcp__browser__click, mcp__filesystem__read_file, and so on.

Create the mappings

For each bounded action, create a capability mapping that lists the concrete tools implementing it, and (optionally) the bounded actions it binds via required_actions:

capabilities:
  web_browsing:
    description: "Browser-based research and navigation"
    tools:
      - "mcp__browser__*"
    required_actions:
      - "web_fetch"
      - "web_search"

In this example, the card declares web_fetch and web_search as bounded actions. The agent uses mcp__browser__navigate, mcp__browser__click, and mcp__browser__screenshot to perform those actions. The glob pattern mcp__browser__* covers all of them. Remember that required_actions is validated server-side only today — publish or validate with --agent to check it.

Use glob patterns for tool families

Glob patterns let you match groups of related tools without listing each one:

Pattern	Matches
`mcp__browser__*`	All browser tools (`navigate`, `click`, `screenshot`, etc.)
`mcp__filesystem__read*`	`read_file`, `read_directory`, `read_metadata`
`mcp____list`	Any MCP server’s list operations
`custom_tool_v?`	`custom_tool_v1`, `custom_tool_v2`, etc.

Start with broad globs during initial development, then tighten them as you understand which specific tools your agent uses. A mapping like mcp__browser__* is fine for week one. By month two, you should enumerate the specific tools for tighter control.

Verify coverage

After writing your mappings, check that every bounded action is covered. Because coverage depends on required_actions, which the offline validator doesn’t yet recognize (see the note above), check it through the API instead of the local card evaluate:

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": "mnm-550e8400-e29b-41d4-a716-446655440000",
    "tools": [{ "name": "mcp__browser__navigate" }, { "name": "mcp__filesystem__read_file" }],
    "dry_run": true
  }'

The response’s coverage object tells you which bounded actions are mapped and which are missing. Aim for 100% coverage in production cards.

API-based management

Policy is part of the alignment card. Get, set, and resolve it through the alignment-card endpoints — there’s no separate /v1/agents/{id}/policy surface after the 2026-04-15 unified-cards consolidation.

Publish policy (set the alignment card)

Publish the alignment card with your capabilities and enforcement sections embedded. The server validates the card against the unified schema, recomposes it against platform + org scopes, and writes the canonical output.

curl -X PUT https://api.mnemom.ai/v1/alignment/agent/{agent_id} \
  -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \
  -H "Content-Type: text/yaml" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data-binary @alignment-card.yaml

curl -X PUT https://api.mnemom.ai/v1/alignment/agent/{agent_id} \
  -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "card_version": "unified/2026-04-26",
    "card_id": "ac-support-agent-v2",
    "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
    "issued_at": "2026-03-04T00:00:00Z",
    "autonomy_mode": "observe",
    "integrity_mode": "observe",
    "principal": { "type": "human", "identifier": "you@example.com", "relationship": "delegated_authority" },
    "values": { "declared": ["transparency", "honesty"] },
    "autonomy": {
      "bounded_actions": ["inference", "read", "web_fetch", "web_search"],
      "forbidden_actions": ["exfiltrate_data"],
      "escalation_triggers": []
    },
    "capabilities": {
      "web_browsing": {
        "tools": ["mcp__browser__*"],
        "required_actions": ["web_fetch", "web_search"]
      }
    },
    "enforcement": {
      "allow_unmapped_tools": false,
      "default_unmapped_severity": "medium",
      "grace_period_hours": 24,
      "forbidden_tools": [
        {
          "pattern": "mcp__filesystem__delete*",
          "reason": "File deletion not permitted",
          "severity": "critical"
        }
      ]
    },
    "audit": {
      "retention_days": 90,
      "queryable": true,
      "query_endpoint": "https://api.mnemom.ai/v1/traces",
      "tamper_evidence": "append_only"
    }
  }'

The response is the canonical card — your input composed with platform + org scopes (strictest-wins on enforcement mode, deny-overrides union on forbidden patterns, etc). See Card Composition for the per-field rules.

Fetch the canonical card

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

Add ?include_composition=true to include the _composition metadata block showing which scope contributed which section — useful when debugging “why did this org-level forbidden pattern end up on my agent’s canonical card?”

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

YAML is the canonical content type; pass Accept: application/json to get JSON back.

Evaluate tools against the active policy

Test a set of tools against the agent’s current policy (the capabilities + enforcement sections of its canonical card) without making a real gateway request. The policy is derived server-side from the agent’s published canonical alignment card — you don’t pass a policy document, just the agent_id and the tools to check:

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": "mnm-550e8400-e29b-41d4-a716-446655440000",
    "tools": [{ "name": "mcp__browser__navigate" }, { "name": "mcp__filesystem__delete" }],
    "context": "cicd",
    "dry_run": true
  }'

agent_id and a non-empty tools array are required. context defaults to "cicd". Set dry_run: true to skip persisting the result (useful when calling this repeatedly from CI). The agent must already have a published canonical alignment card (PUT /v1/agents/{agent_id}/alignment-card or PUT /v1/alignment/agent/{agent_id}) — otherwise the endpoint 404s. You must also be a member of the org that governs the agent: for anyone else the endpoint returns the same 404 Agent not found as for an unknown agent. A missing or non-string agent_id is a 400. The evaluate endpoint returns a verdict (pass, warn, or fail) and per-tool detail: which capability each tool matched, which forbidden rule it tripped, or whether it fell through to unmapped_tool_action. Use this in CI to catch regressions before publishing a card — POST /v1/policies/evaluate/historical does the same thing against the agent’s actual recent traces.

Historical evaluation

To evaluate against actual recent traces (rather than a hypothetical tool list), use the historical endpoint:

curl -X POST https://api.mnemom.ai/v1/policies/evaluate/historical \
  -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
    "limit": 100
  }'

This replays the agent’s most recent limit traces (default 50, capped at 200) against the agent’s current canonical card, surfacing any tool call that would violate today’s rules. Pass an optional card_json to evaluate the traces against a hypothetical card instead of the agent’s published one — useful for checking “would this candidate card have caught what actually happened.” It’s a useful input for card_gap reclassification (see Trust Recovery). The same org-membership rule applies: an agent outside your orgs returns 404 Agent not found.

Multi-environment strategies

Separate policies per environment

Use a different top-level autonomy_mode (and enforcement defaults) per environment’s agent card to catch issues progressively:

Development
Production

In development, keep enforcement loose so agents can explore new tools without blocking:

autonomy_mode: observe
enforcement:
  allow_unmapped_tools: true
  grace_period_hours: 168 # 7 days

In production, enforce strictly. Every tool should be explicitly mapped or explicitly forbidden:

autonomy_mode: enforce
enforcement:
  allow_unmapped_tools: false
  default_unmapped_severity: high
  grace_period_hours: 24

Org-level baseline, agent-level specialization

Publish an org-wide alignment card (PUT /v1/alignment/org/{org_id}) for security rules that apply to every agent in the org, and let each agent’s own card (PUT /v1/alignment/agent/{agent_id}) add agent-specific capabilities on top of it. The server composes platform → org → team → agent into one canonical card for the agent (see Card Composition). The merge rules ensure an agent-level card can strengthen but never weaken the org baseline:

Section	Merge Strategy	Effect
`capabilities`	Union (per capability: `tools`/`required_actions` union, `severity_on_unmapped` strictest-wins)	Agent can add new mappings but cannot remove org mappings
`enforcement.forbidden_tools`	Union	Both org and agent forbidden rules are enforced
`autonomy_mode` / `integrity_mode`	Strictest wins (`enforce` > `nudge` > `observe` > `off`)	Agent can strengthen but cannot weaken the org’s mode
`autonomy.escalation_triggers`	Union	Both org and agent triggers are evaluated

Version control your policies

Keep card.yaml alongside your agent code in version control. This gives you:

Diff visibility — every policy change is reviewed in a pull request
Rollback capability — revert to a previous policy by reverting the commit
CI gating — validate and test policies automatically on every push

# .github/workflows/card-check.yml
name: Card Check
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @mnemom/mnemom
      - name: Validate card
        run: mnemom card validate card.yaml
      - name: Evaluate card policy
        run: mnemom card evaluate card.yaml --tools mcp__browser__navigate,mcp__slack__post_message --strict

Using policy recommendations

The Intelligence Layer turns a risk forecast into a concrete policy recommendation. First generate a forecast from a fault-line analysis (POST /v1/teams/forecast), then pass its forecast_id here — the recommendation draws on the forecast’s observed agent behavior, failure modes, and fault-line structure.

Generate a recommendation

curl -X POST https://api.mnemom.ai/v1/teams/recommend-policy \
  -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "forecast_id": "rf-8f21c0a49d3b",
    "constraints": { "enforcement_mode": "warn" }
  }'

The response’s recommended_policy is a complete policy document with:

capability_mappings derived from observed tool usage patterns (each entry’s tools + card_actions)
forbidden rules based on detected violations and near-misses
escalation_triggers from historical escalation patterns
defaults (recommended enforcement mode) based on team maturity

alongside a top-level rationale array explaining each recommended field, and expected_coverage / fault_lines_addressed summary numbers.

Policy recommendations are a starting point, not a final policy. Always review the generated policy, adjust mappings to match your specific agent architecture, and test against historical traces before publishing.

Review and customize

rationale gives you a field + reason + confidence (0-1) for each recommended section. Focus your review on the low-confidence entries, where the system was less certain about the correct mapping:

{
  "recommended_policy": {
    "capability_mappings": {
      "web_browsing": { "tools": ["mcp__browser__*"], "card_actions": ["web_fetch", "web_search"] },
      "data_export": { "tools": ["mcp__csv__export", "mcp__sheets__write"], "card_actions": ["write"] }
    },
    "forbidden": [],
    "escalation_triggers": [],
    "defaults": { "enforcement_mode": "warn" }
  },
  "rationale": [
    { "field": "capability_mappings.web_browsing", "reason": "Matches 94% of observed browser tool calls", "confidence": 0.95 },
    { "field": "capability_mappings.data_export", "reason": "Mapped to 'write' but may warrant a separate card action", "confidence": 0.62 }
  ],
  "expected_coverage": 0.88,
  "fault_lines_addressed": 2
}

recommended_policy comes back in this capability-mapping shape (card_actions), not the alignment card’s own capabilities/enforcement shape. Before publishing, fold it into your card: each capability_mappings.<name> becomes capabilities.<name> with card_actions renamed to required_actions, forbidden entries become enforcement.forbidden_tools, and defaults.enforcement_mode maps to the card’s top-level autonomy_mode.

Best practices

Start in observe mode

Begin with autonomy_mode: observe to see what your policy would catch without blocking agent traffic. Graduate to nudge and then enforce after testing confirms the policy matches your expectations.

Evaluate before publishing

Always run mnemom card evaluate before mnemom card publish. Evaluating against your agent’s tools shows you the real-world impact of your policy before it affects live requests.

Align mappings with card actions

Keep capability mappings tightly aligned with your alignment card’s bounded_actions. Every card action should have a corresponding mapping, and every mapping should reference a real card action.

Aim for >90% coverage

Review coverage reports regularly. Unmapped card actions fall through to defaults, which may not match your intent. Target 100% coverage in production policies.

Set a grace period

enforcement.grace_period_hours prevents newly-added tools from immediately becoming violations. When your card composes with an org/platform floor, the shortest grace period across all layers wins.

Version control your cards

Store card.yaml in your repository alongside agent code. Use CI validation to catch policy issues before deploy and maintain a clear audit trail of every change.

Identity & Cards

Posture & Policy

Detection & Safe House

Reputation & Risk

Lifecycle

Quick start

Capability mapping walkthrough

Start from your alignment card

Identify concrete tools

Create the mappings

Use glob patterns for tool families

Verify coverage

API-based management

Publish policy (set the alignment card)

Fetch the canonical card

Evaluate tools against the active policy

Historical evaluation

Multi-environment strategies

Separate policies per environment

Org-level baseline, agent-level specialization

Version control your policies

Using policy recommendations

Generate a recommendation

Review and customize

Best practices

Start in observe mode

Evaluate before publishing

Align mappings with card actions

Aim for >90% coverage

Set a grace period

Version control your cards

See also

​Quick start

​Capability mapping walkthrough

​Start from your alignment card

​Identify concrete tools

​Create the mappings

​Use glob patterns for tool families

​Verify coverage

​API-based management

​Publish policy (set the alignment card)

​Fetch the canonical card

​Evaluate tools against the active policy

​Historical evaluation

​Multi-environment strategies

​Separate policies per environment

​Org-level baseline, agent-level specialization

​Version control your policies

​Using policy recommendations

​Generate a recommendation

​Review and customize

​Best practices

Start in observe mode

Evaluate before publishing

Align mappings with card actions

Aim for >90% coverage

Set a grace period

Version control your cards

​See also

Quick start

Capability mapping walkthrough

Start from your alignment card

Identify concrete tools

Create the mappings

Use glob patterns for tool families

Verify coverage

API-based management

Publish policy (set the alignment card)

Fetch the canonical card

Evaluate tools against the active policy

Historical evaluation

Multi-environment strategies

Separate policies per environment

Org-level baseline, agent-level specialization

Version control your policies

Using policy recommendations

Generate a recommendation

Review and customize

Best practices

See also