> ## 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.

# Policy Management

> Create, test, publish, and manage governance policies for your AI agents

<Note>
  **Policy is now part of the alignment card.** In the [unified card model](/concepts/agent-cards), the standalone CLPI Policy YAML is absorbed into 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 is removed; use `mnemom card evaluate agent.card.yaml --tools tools.json` instead.

  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.
</Note>

Policies bridge [Alignment Cards](/concepts/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 defines three things:

* **Capability mappings** -- which concrete MCP tools satisfy which card-level actions
* **Forbidden rules** -- which tools are always blocked, with reasons and severities
* **Defaults** -- how unmapped tools are handled, what enforcement mode to use, and how long new tools get a grace period

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

## Quick start

<Steps>
  ### Create your alignment card

  Policy is now defined directly in the alignment card. Create a YAML alignment card that includes capability mappings, forbidden rules, and enforcement defaults. Here is a fully annotated example for a customer support agent:

  ```yaml theme={null}
  meta:
    schema_version: "1.0"
    name: "support-agent-policy"
    description: "Policy for customer support agents"
    scope: agent

  capability_mappings:
    web_browsing:
      description: "Browser-based research and navigation"
      tools:
        - "mcp__browser__*"
      card_actions:
        - "web_fetch"
        - "web_search"

    file_operations:
      description: "Reading and writing local files"
      tools:
        - "mcp__filesystem__read*"
        - "mcp__filesystem__write*"
      card_actions:
        - "read"
        - "write"

    communication:
      description: "Sending messages and notifications"
      tools:
        - "mcp__slack__post_message"
        - "mcp__email__send"
      card_actions:
        - "send_response"

  forbidden:
    - pattern: "mcp__filesystem__delete*"
      reason: "File deletion not permitted for support agents"
      severity: critical
    - pattern: "mcp__admin__*"
      reason: "Administrative operations require escalation"
      severity: high

  escalation_triggers:
    - condition: "tool_matches('mcp__payment__*')"
      action: escalate
      reason: "Payment operations require human approval"

  defaults:
    unmapped_tool_action: warn
    unmapped_severity: medium
    fail_open: true
    enforcement_mode: warn
    grace_period_hours: 24
  ```

  <Tip>
    The `scope: agent` field means this policy layers on top of any org-level policy. Use `scope: org` for organization-wide baselines that apply to all agents. See [Policy Merge](#multi-environment-strategies) for how the two levels combine.
  </Tip>

  ### Validate locally

  Run local validation to check schema compliance before publishing. This is a local-only check with no API call -- safe for CI pipelines:

  ```bash theme={null}
  mnemom card validate card.yaml
  ```

  Exit code `0` means the card is valid. Exit code `1` means there are errors. Fix any reported issues before proceeding.

  ### Evaluate against tools

  Test your card's policy against the tools your agent actually uses:

  ```bash theme={null}
  mnemom card evaluate card.yaml --tools mcp__browser__navigate,mcp__slack__post_message --agent my-agent
  ```

  This evaluates each tool against the card's capability mappings, forbidden rules, and defaults. Use this to verify coverage before publishing.

  <Warning>
    Always run `card evaluate` before publishing. A card that looks correct in isolation can produce unexpected violations when evaluated against real agent tools. Testing first shows you the impact before it affects live traffic.
  </Warning>

  ### Publish

  Upload the validated card (with embedded policy) to your agent:

  ```bash theme={null}
  mnemom card publish card.yaml --agent my-agent
  ```

  The CLI validates again before uploading, asks for confirmation, and archives the previous card version. Use `--yes` to skip the confirmation prompt in CI workflows.
</Steps>

## 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:

```json theme={null}
{
  "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](/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:

```bash theme={null}
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 card action, create a capability mapping that lists the concrete tools implementing it:

```yaml theme={null}
capability_mappings:
  web_browsing:
    description: "Browser-based research and navigation"
    tools:
      - "mcp__browser__*"
    card_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.

### 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.                    |

<Tip>
  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.
</Tip>

### Verify coverage

After writing your mappings, check that every card action is covered:

```bash theme={null}
mnemom card evaluate card.yaml --tools mcp__browser__navigate,mcp__filesystem__read_file --agent my-agent
```

The coverage report tells you which card 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.

<CodeGroup>
  ```bash cURL (YAML) theme={null}
  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
  ```

  ```bash cURL (JSON) theme={null}
  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-15",
      "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__*"],
          "card_actions": ["web_fetch", "web_search"]
        }
      },
      "enforcement": {
        "default_mode": "warn",
        "unmapped_tool_action": "warn",
        "grace_period_hours": 24,
        "forbidden": [
          {
            "pattern": "mcp__filesystem__delete*",
            "reason": "File deletion not permitted",
            "severity": "critical"
          }
        ]
      },
      "audit": {
        "trace_format": "ap-trace-v1",
        "retention_days": 90,
        "queryable": true,
        "query_endpoint": "https://api.mnemom.ai/v1/traces",
        "tamper_evidence": "append_only"
      }
    }'
  ```
</CodeGroup>

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](/concepts/card-composition) for the per-field rules.

### Fetch the canonical card

```bash theme={null}
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?"

```bash theme={null}
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:

```bash theme={null}
curl -X POST https://api.mnemom.ai/v1/policies/evaluate \
  -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "policy": { "meta": { "schema_version": "1.0", "name": "support-agent", "scope": "agent" } },
    "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
    "tools": [{ "name": "mcp__browser__navigate" }, { "name": "mcp__filesystem__delete" }],
    "context": "gateway"
  }'
```

The `policy` field is the policy document to evaluate against; pass the inline policy YAML (parsed into JSON) you want to test. See the [Policy DSL spec](/specifications/policy-dsl) for the canonical schema.

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 a date range of actual past traces.

### Historical evaluation

To evaluate against an actual trace window (rather than a hypothetical tool list), use the historical endpoint:

```bash theme={null}
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 '{
    "policy": { "meta": { "schema_version": "1.0", "name": "support-agent", "scope": "agent" } },
    "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
    "from": "2026-02-01T00:00:00Z",
    "to": "2026-03-01T00:00:00Z"
  }'
```

This replays every tool the agent actually used in the window against the current policy, surfacing any tool that would violate today's rules. It's the primary input for `card_gap` reclassification (see [Trust Recovery](/guides/trust-recovery)).

## Multi-environment strategies

### Separate policies per environment

Use different enforcement modes across environments to catch issues progressively:

<Tabs>
  <Tab title="Development">
    In development, keep enforcement loose so agents can explore new tools without blocking:

    ```yaml theme={null}
    defaults:
      unmapped_tool_action: allow
      enforcement_mode: warn
      grace_period_hours: 168  # 7 days
    ```
  </Tab>

  <Tab title="Staging">
    In staging, surface warnings so you can identify unmapped tools and policy gaps before production:

    ```yaml theme={null}
    defaults:
      unmapped_tool_action: warn
      enforcement_mode: warn
      grace_period_hours: 24
    ```
  </Tab>

  <Tab title="Production">
    In production, enforce strictly. Every tool should be explicitly mapped or explicitly forbidden:

    ```yaml theme={null}
    defaults:
      unmapped_tool_action: deny
      enforcement_mode: enforce
      grace_period_hours: 24
    ```
  </Tab>
</Tabs>

### Org-level baseline, agent-level specialization

Use `scope: org` for organization-wide security rules that apply to every agent. Use `scope: agent` for per-agent customizations that add capabilities on top of the org baseline.

The merge rules ensure agents can strengthen but never weaken org-level policy:

| Section               | Merge Strategy | Effect                                                          |
| --------------------- | -------------- | --------------------------------------------------------------- |
| `capability_mappings` | Union          | Agent can add new mappings but cannot remove org mappings       |
| `forbidden`           | Union          | Both org and agent forbidden rules are enforced                 |
| `defaults`            | Org is floor   | Agent can strengthen (e.g., `warn` to `deny`) but cannot weaken |
| `escalation_triggers` | Union          | Both org and agent triggers are evaluated                       |

### Version control your policies

Keep `policy.yaml` files 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

```yaml theme={null}
# .github/workflows/card-check.yml
name: Card Check
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate card
        run: npx mnemom card validate card.yaml
      - name: Evaluate card policy
        run: npx mnemom card evaluate card.yaml --tools mcp__browser__navigate,mcp__slack__post_message --agent my-agent --format json
        env:
          MNEMOM_API_KEY: ${{ secrets.MNEMOM_API_KEY }}
```

## 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

```bash theme={null}
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 includes a complete policy YAML with:

* Capability mappings derived from observed tool usage patterns
* Forbidden rules based on detected violations and near-misses
* Escalation triggers from historical escalation patterns
* Recommended enforcement mode based on team maturity

<Note>
  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.
</Note>

### Review and customize

The recommendation includes confidence scores for each section. Focus your review on low-confidence mappings where the system was uncertain about the correct card action mapping:

```json theme={null}
{
  "recommendation": {
    "capability_mappings": {
      "web_browsing": {
        "confidence": 0.95,
        "tools": ["mcp__browser__*"],
        "card_actions": ["web_fetch", "web_search"]
      },
      "data_export": {
        "confidence": 0.62,
        "tools": ["mcp__csv__export", "mcp__sheets__write"],
        "card_actions": ["write"],
        "review_note": "Mapped to 'write' but may warrant a separate card action"
      }
    }
  }
}
```

## Best practices

<CardGroup cols={2}>
  <Card title="Start with warn mode" icon="triangle-exclamation">
    Begin with `enforcement_mode: warn` to observe what your policy catches without blocking agent traffic. Graduate to `enforce` after testing confirms the policy matches your expectations.
  </Card>

  <Card title="Evaluate before publishing" icon="flask-vial">
    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.
  </Card>

  <Card title="Align mappings with card actions" icon="link">
    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.
  </Card>

  <Card title="Aim for >90% coverage" icon="chart-line">
    Review coverage reports regularly. Unmapped card actions fall through to defaults, which may not match your intent. Target 100% coverage in production policies.
  </Card>

  <Card title="Use the grace period" icon="clock">
    The default 24-hour grace period prevents new tools from immediately becoming violations. This gives you time to update the policy after adding new MCP servers or tools.
  </Card>

  <Card title="Version control policies" icon="code-branch">
    Store `policy.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.
  </Card>
</CardGroup>

## See also

* [Policy Engine](/concepts/policy-engine) -- How the policy engine evaluates tools against policies
* [Policy DSL Specification](/specifications/policy-dsl) -- Full normative schema for policy YAML files
* [CLI Reference](/gateway/cli) -- CLI commands including `card validate`, `card evaluate`, and `card publish`
* [CI/CD Policy Gates](/guides/ci-cd-policy-gates) -- Integrating card evaluation into your deployment pipeline
* [Alignment Card Management](/guides/card-management) -- Creating and managing alignment cards with embedded policy
* [Enforcement Modes](/gateway/enforcement) -- Alignment enforcement (observe/nudge/enforce) vs. policy enforcement