> ## 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 part of the alignment card.** In the [unified card model](/concepts/agent-cards), 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.
</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 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

<Steps>
  ### Create your alignment card

  Policy is defined directly in the alignment card's `capabilities` and `enforcement` sections. Here is a minimal but complete example for a customer support agent:

  ```yaml theme={null}
  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
    relationship: delegated_authority
    identifier: "you@example.com"

  values:
    declared:
      - transparency
      - honesty

  autonomy:
    bounded_actions:
      - web_fetch
      - web_search
      - read
      - write
      - send_response
    forbidden_actions:
      - exfiltrate_data
    escalation_triggers:
      - condition: "tool_matches('mcp__payment__*')"
        action: escalate
        reason: "Payment operations require human approval"

  capabilities:
    web_browsing:
      description: "Browser-based research and navigation"
      tools:
        - "mcp__browser__*"
    file_operations:
      description: "Reading and writing local files"
      tools:
        - "mcp__filesystem__read*"
        - "mcp__filesystem__write*"
    communication:
      description: "Sending messages and notifications"
      tools:
        - "mcp__slack__post_message"
        - "mcp__email__send"

  enforcement:
    allow_unmapped_tools: false
    default_unmapped_severity: medium
    grace_period_hours: 24
    forbidden_tools:
      - pattern: "mcp__filesystem__delete*"
        reason: "File deletion not permitted for support agents"
        severity: critical
      - pattern: "mcp__admin__*"
        reason: "Administrative operations require escalation"
        severity: high

  audit:
    retention_days: 90
    queryable: true
    query_endpoint: "https://api.mnemom.ai/v1/traces"
    tamper_evidence: append_only
  ```

  <Tip>
    `autonomy_mode` and `integrity_mode` are the card's top-level master switches (`off` / `observe` / `nudge` / `enforce`) — the legacy `enforcement.mode` and `integrity.enforcement_mode` locations are rejected. Start at `observe` to see what the policy would catch before it can block anything.
  </Tip>

  <Note>
    A capability can also bind to specific `autonomy.bounded_actions` via `capabilities.<name>.required_actions` (an array of action names) — this is what the API's coverage report and `_composition` metadata key off. That field is accepted by the server (`PUT` the card directly, as below) but the CLI's offline validator currently doesn't recognize it, so a card using it will fail `mnemom card validate`/`card evaluate` run without `--agent`. Validate with `--agent <name>` (the default, server-authoritative mode) instead of `--offline` if you rely on it.
  </Note>

  ### Validate locally

  Run local validation to check schema compliance before publishing. Without `--agent` set (and no `MNEMOM_AGENT` env var), 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. Pass `--agent <name>` to validate server-side instead (composes against your org/platform floor, catching conflicts the offline check can't see); `--offline` forces the local-only path even when an agent is set.

  ### Evaluate against tools

  Test your card's policy against the tools your agent actually uses. This runs entirely locally against the embedded policy engine -- no API call, no `--agent` needed:

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

  This evaluates each tool against the card's capability mappings, forbidden rules, and defaults, and prints a coverage report. Pass `--tool-manifest tools.json` (a JSON array of tool names, or `{"name": "..."}` objects) instead of `--tools` for a larger tool set. Add `--strict` to also exit non-zero on warnings, not just failures -- useful for a CI gate.

  <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 to your agent:

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

  The CLI re-validates the card, and — when run interactively (a TTY) — asks for confirmation before uploading and archiving the previous card version. In a non-interactive CI run (no TTY) it skips the confirmation prompt automatically.
</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 bounded action, create a capability mapping that lists the concrete tools implementing it, and (optionally) the bounded actions it binds via `required_actions`:

```yaml theme={null}
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. |

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

```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 '{
    "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.

<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-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"
      }
    }'
  ```
</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. 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:

```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 '{
    "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:

```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 '{
    "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](/guides/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:

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

    ```yaml theme={null}
    autonomy_mode: observe
    enforcement:
      allow_unmapped_tools: true
      grace_period_hours: 168 # 7 days
    ```
  </Tab>

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

    ```yaml theme={null}
    autonomy_mode: enforce
    enforcement:
      allow_unmapped_tools: false
      default_unmapped_severity: high
      grace_period_hours: 24
    ```
  </Tab>
</Tabs>

### 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](/concepts/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

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

```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'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.

<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

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

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

<CardGroup cols={2}>
  <Card title="Start in observe mode" icon="triangle-exclamation">
    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.
  </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="Set a grace period" icon="clock">
    `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.
  </Card>

  <Card title="Version control your cards" icon="code-branch">
    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.
  </Card>
</CardGroup>

## See also

* [Policy Engine](/concepts/policy-engine) -- How the policy engine evaluates tools against policies
* [Policy DSL Specification](/specifications/policy-dsl) -- The underlying capability-mapping schema the policy engine compiles your card's `capabilities`/`enforcement` sections into (also the shape returned by `POST /v1/teams/recommend-policy`)
* [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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.