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

> Governance-as-code: capability mappings, forbidden rules, and enforcement modes, all declared in the alignment card's capabilities + enforcement sections

<Note>
  The Policy Engine is **Phase 1 of [CLPI (Card Lifecycle & Policy Intelligence)](/concepts/clpi)** — the governance layer that transforms alignment cards into lifecycle-managed artifacts with policy enforcement, trust recovery, risk intelligence, and on-chain anchoring.
</Note>

The policy engine translates [Alignment Card](/concepts/alignment-cards) declarations into enforceable rules over concrete tools. An alignment card says an agent may perform `web_fetch`. The `capabilities` section of the same card says `web_fetch` means `mcp__browser__navigate` and `mcp__browser__click` — but not `mcp__filesystem__delete`. The card declares intent. The `enforcement` section enforces it.

<Note>
  **Policy is part of the alignment card, not a separate artifact.** The `capabilities`, `enforcement`, and per-capability `forbidden` rules live as sections of the unified card. There is no standalone policy YAML file, no `PUT /v1/agents/:id/policy` endpoint, and no `mnemom policy` CLI group. Use `mnemom card evaluate` + `PUT /v1/alignment/agent/{id}` instead. See the [policy management guide](/guides/policy-management) for the customer workflow.
</Note>

<Note>
  The policy engine is a parallel enforcement layer to [alignment enforcement](/gateway/enforcement) (observe/nudge/enforce). Alignment enforcement checks agent behavior against card values. Policy enforcement checks tool usage against the card's `capabilities` + `enforcement` sections. Both run independently and produce separate verdicts.
</Note>

## How the engine reads the card

The policy engine reads three sections of the canonical (composed) alignment card:

| Section                         | Purpose                                                                                                          |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `capabilities`                  | Bridge card-level semantic actions (`web_fetch`, `read_file`) to concrete tool glob patterns (`mcp__browser__*`) |
| `enforcement.forbidden`         | Tools that are always blocked, regardless of mappings                                                            |
| `enforcement` (top-level knobs) | Fallback behavior for unmatched tools — `default_mode`, `unmapped_tool_action`, `grace_period_hours`             |

Two optional card sections extend the model:

| Section                         | Purpose                                                                   |
| ------------------------------- | ------------------------------------------------------------------------- |
| `autonomy.escalation_triggers`  | Conditions that trigger escalation regardless of individual tool verdicts |
| `autonomy.max_autonomous_value` | Currency-denominated ceiling on autonomous actions                        |

The full normative schema for these sections is at [/specifications/alignment-card-schema](/specifications/alignment-card-schema).

### Example excerpt of a card's policy sections

```yaml theme={null}
# ... (values, principal, autonomy sections omitted) ...

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

  file_reading:
    tools:
      - "mcp__filesystem__read*"
      - "mcp__filesystem__list*"
    card_actions:
      - read_file

enforcement:
  default_mode: warn              # warn | enforce | off
  unmapped_tool_action: warn      # allow | warn | deny
  unmapped_severity: medium
  grace_period_hours: 24
  forbidden:
    - pattern: "mcp__filesystem__delete*"
      reason: "File deletion not permitted"
      severity: critical
    - pattern: "mcp__shell__*"
      reason: "Shell execution not permitted"
      severity: high
```

## Three evaluation contexts

The same `capabilities` + `enforcement` sections are evaluated at three stages, each with different inputs and consequences.

<Tabs>
  <Tab title="CI/CD (Static)">
    ### CI/CD evaluation

    Static evaluation runs in pipelines before deployment. It validates the card against the unified schema and evaluates its policy sections against a declared tool list.

    **Commands:**

    ```bash theme={null}
    # Validate the card (schema + structure)
    mnemom card validate card.yaml

    # Evaluate the card's policy against a tool list
    mnemom card evaluate card.yaml --tools mcp__browser__navigate,mcp__slack__post_message
    ```

    **What it checks:**

    * Card YAML conforms to the unified schema (capability glob validity, enforcement-mode enums, forbidden-rule structure).
    * Capability `card_actions` reference actions that exist in `autonomy.bounded_actions`.
    * Each tool in the `--tools` list matches a capability, hits a forbidden rule, or falls through to the `unmapped_tool_action` default.
    * Coverage report identifies card actions with no backing capability mapping.

    **Use case:** pre-deploy gates. See the [CI/CD policy gates guide](/guides/ci-cd-policy-gates) for GitHub Actions + GitLab CI templates.
  </Tab>

  <Tab title="Gateway (Live)">
    ### Gateway evaluation

    Live evaluation runs in real-time as requests pass through the Mnemom gateway. The policy engine extracts tool names from the request body, checks each tool against the agent's canonical card, and returns a verdict.

    **How it works:**

    1. Request arrives at the gateway.
    2. Gateway reads the canonical alignment card (KV-cached, 5-min TTL).
    3. Each tool in the request is checked against `enforcement.forbidden` first.
    4. Remaining tools are matched against `capabilities[*].tools` globs.
    5. Unmatched tools fall through to `enforcement.unmapped_tool_action`.
    6. A verdict is returned via the `X-Policy-Verdict` response header.

    **Verdict headers:**

    | Header Value             | Meaning                                                     |
    | ------------------------ | ----------------------------------------------------------- |
    | `X-Policy-Verdict: pass` | All tools passed policy checks                              |
    | `X-Policy-Verdict: warn` | One or more tools triggered warnings (logged, not blocked)  |
    | `X-Policy-Verdict: fail` | One or more tools violated policy (blocked in enforce mode) |

    **Enforcement interaction:** `enforcement.default_mode` determines the gateway response:

    | `default_mode` | `pass`        | `warn`        | `fail`                                                                                                        |
    | -------------- | ------------- | ------------- | ------------------------------------------------------------------------------------------------------------- |
    | `off`          | No evaluation | No evaluation | No evaluation                                                                                                 |
    | `warn`         | Allow         | Allow + log   | Allow + log                                                                                                   |
    | `enforce`      | Allow         | Allow + log   | Gated same-turn on both transports: HTTP 403 (non-streaming); gated before delivery (streaming, adds latency) |
  </Tab>

  <Tab title="Observer (Post)">
    ### Observer evaluation

    Post-action evaluation runs after an action completes. It analyzes what actually happened against what the card expected.

    **What it detects:**

    * **card\_gap violations** — tools the agent used successfully but that are not represented in any capability mapping. These are tools that should be in the card but are not.
    * **Frequency anomalies** — tools used at rates that exceed expected patterns.
    * **New tool discovery** — tools appearing for the first time, subject to grace-period handling.

    **Feeds into reclassification:** observer findings feed the reclassification pipeline at `POST /v1/agents/{id}/reclassify`. A `card_gap` detection is a candidate for reclassification + an amendment to the card's `capabilities` section — see [Trust Recovery](/guides/trust-recovery).

    **Feeds into proving:** when the gateway's policy evaluation detects `card_gap` signals alongside a `boundary_violation`, [ZK proving is deferred](/protocols/aip/verifiable-verdicts#deferred-proofs) instead of immediately dispatched to GPUs. This prevents stale alignment cards from driving up proving costs during rapid iteration.
  </Tab>
</Tabs>

## Capability mapping

Capability mappings are the core of the card's policy sections. They bridge the gap between what the card declares (abstract actions like `web_fetch`) and what agents actually invoke (concrete tool names like `mcp__browser__navigate`).

### Structure

Each capability has a name, a list of tool glob patterns, and a list of card actions it satisfies:

```yaml theme={null}
capabilities:
  web_browsing:
    tools:
      - "mcp__browser__navigate"
      - "mcp__browser__click"
      - "mcp__browser__screenshot"
    card_actions:
      - web_fetch
      - web_search

  database_read:
    tools:
      - "mcp__postgres__query"
      - "mcp__postgres__list_tables"
    card_actions:
      - read_data
```

### Glob patterns

Tool patterns support standard glob syntax for flexible matching:

| 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 card 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, enumerate the specific tools.
</Tip>

### How matching works

When the policy engine evaluates a tool, it follows this order:

1. **Forbidden check:** does the tool match any `enforcement.forbidden[].pattern`? If yes, the tool is a violation regardless of capability mappings.
2. **Capability match:** does the tool match any `capabilities[*].tools` glob? If yes, the tool is allowed and mapped to the corresponding card actions.
3. **Default fallback:** if neither forbidden nor mapped, apply `enforcement.unmapped_tool_action`.

A tool can match multiple capabilities. This isn't an error — it means the tool satisfies multiple card actions (e.g., a file-read tool satisfying both `read_file` and `read_source_code`).

## Enforcement modes

`enforcement.default_mode` is the card's policy-enforcement posture:

<CardGroup cols={3}>
  <Card title="Warn" icon="triangle-exclamation">
    Log violations but do not block. `X-Policy-Verdict: warn` header returned. **Default mode.**
  </Card>

  <Card title="Enforce" icon="ban">
    Block requests with policy violations, same-turn on both transports. `X-Policy-Verdict: fail` header returned. HTTP 403 for non-streaming requests; streaming responses are gated before delivery (which adds latency).
  </Card>

  <Card title="Off" icon="power-off">
    Skip policy evaluation entirely. No `X-Policy-Verdict` header. No performance overhead.
  </Card>
</CardGroup>

<Warning>
  Policy enforcement (`enforcement.default_mode`), action-policing alignment (`autonomy_mode`), and values-policing alignment (`integrity_mode`) are three parallel systems with three independent master switches. Setting one to `enforce` does not affect the others — an agent can sit at `autonomy_mode: observe` + `integrity_mode: enforce` + `enforcement.default_mode: nudge` simultaneously, each on its own independent ladder.
</Warning>

### Relationship to the alignment master switches

| System                        | Master switch                                       | What it checks                                        | Verdict source                                     |
| ----------------------------- | --------------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------- |
| **Action-policing alignment** | `autonomy_mode` (alignment card, top-level)         | Tool calls + bounded-action envelope                  | CLPI tool-use policy + observer trace verification |
| **Values-policing alignment** | `integrity_mode` (alignment card, top-level)        | Agent behavior against card values + conscience       | AIP integrity checkpoints + drift detection        |
| **Policy enforcement**        | `enforcement.default_mode` (alignment card, nested) | Tool usage against policy rules + capability mappings | Policy engine evaluation                           |

Both systems produce independent verdicts. Both are surfaced in the [conscience timeline](/gateway/enforcement) and [observability exports](/guides/observability).

## Forbidden rules

`enforcement.forbidden` defines tools that must never be used, regardless of capability mappings. They're always checked first in the evaluation pipeline.

```yaml theme={null}
enforcement:
  forbidden:
    - pattern: "mcp__filesystem__delete*"
      reason: "File deletion not permitted"
      severity: critical
    - pattern: "mcp__shell__*"
      reason: "Shell execution not permitted"
      severity: high
    - pattern: "mcp__*__drop_table"
      reason: "Table deletion not permitted"
      severity: critical
    - pattern: "mcp__email__send_bulk*"
      reason: "Bulk email sending restricted"
      severity: medium
```

Each rule has three fields:

| Field      | Type          | Description                             |
| ---------- | ------------- | --------------------------------------- |
| `pattern`  | string (glob) | Tool name pattern to match              |
| `reason`   | string        | Human-readable explanation for auditing |
| `severity` | enum          | `critical`, `high`, `medium`, or `low`  |

<Note>
  Policy `enforcement.forbidden` rules complement alignment card `autonomy.forbidden_actions`. Card forbidden actions declare intent ("this agent must never delete files"). Policy forbidden rules enforce that intent at the tool level ("block all tools matching `mcp__filesystem__delete*`"). Both are checked — card-level by alignment enforcement, tool-level by policy enforcement.
</Note>

## Unmapped tool handling

When a tool does not match any capability or forbidden rule, `enforcement.unmapped_tool_action` determines what happens.

```yaml theme={null}
enforcement:
  unmapped_tool_action: warn
  unmapped_severity: medium
  grace_period_hours: 24
```

### Unmapped tool actions

| Action  | Behavior                                                         |
| ------- | ---------------------------------------------------------------- |
| `deny`  | Treat the unmapped tool as a violation. Blocked in enforce mode. |
| `warn`  | Log a warning but allow the tool invocation. **Default.**        |
| `allow` | Silently permit the tool. No log entry.                          |

### Choosing the right default

<Tabs>
  <Tab title="Development">
    Use `allow` during early development when tool sets are still evolving. This avoids noise from constantly changing tool inventories.
  </Tab>

  <Tab title="Staging">
    Use `warn` in staging environments. This surfaces unmapped tools in logs and coverage reports without blocking agent functionality. This is the default.
  </Tab>

  <Tab title="Production">
    Use `deny` in production when you have a mature, stable card. Every tool the agent uses should be explicitly mapped or explicitly forbidden.
  </Tab>
</Tabs>

## Grace period

New tools appear when agents gain new MCP server connections or when tool providers add capabilities. The grace period prevents these newly discovered tools from immediately becoming violations.

```yaml theme={null}
enforcement:
  grace_period_hours: 24
```

**How it works:**

1. The policy engine tracks when each tool is first seen via `tool_first_seen` records.
2. When an unmapped or forbidden tool is encountered, the engine checks how long ago it was first seen.
3. If the tool was first seen within the grace period window, the violation is **downgraded to a warning** (the verdict drops from `fail` to `warn`), and the request proceeds. Under enforce mode, this means the request is **not blocked**.
4. After the grace period expires, the tool falls back to the configured `unmapped_tool_action` (or its forbidden severity, for forbidden-pattern matches).

The window is per-(agent, tool): each agent's first observation of each tool starts its own clock. The clock cannot be back-dated.

This gives operators time to amend the card's `capabilities` section after adding new tools or MCP servers, without immediately triggering violations in enforce mode.

<Warning>
  **Security implication.** With the default 24h grace, brand-new tools — including ones introduced by an attacker via prompt injection, MCP server compromise, or tool-name overlap — get a 24-hour pass on enforce mode. Mature agents with stable tool inventories aren't exposed; agents that add tools dynamically, run untrusted MCP servers, or accept tool definitions from user input absolutely are.

  If your threat model includes adversarial tool introduction, set `grace_period_hours: 0` on the alignment card to disable the grace path entirely. There is no API to back-date a `tool_first_seen` record, so `0` is the only way to make enforce strict from the moment a card is published. See [Enforcement § Grace period](/gateway/enforcement#grace-period-read-this-before-enabling-enforce).
</Warning>

| Use case                                                                                                      | Recommended `grace_period_hours`                          |
| ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| Adversarial threat model (untrusted user input, untrusted MCP servers, agents accepting tool defs from users) | **`0`**                                                   |
| Test harness / CI matrix                                                                                      | `0`                                                       |
| Production with stable tool inventory + mature card                                                           | `0` (no operational benefit when the tool list is stable) |
| Production with frequent tool additions, trusted operators                                                    | `24` (default)                                            |
| Slow-cadence operational teams                                                                                | `48`–`168`                                                |

## Composition across scopes

In organizations with multiple agents, the `capabilities` and `enforcement` sections compose from platform → org → agent scopes per [card composition](/concepts/card-composition) rules. These are merged at storage time, not request time: every gateway read hits the pre-composed canonical card.

### Merge rules

| Section                            | Merge strategy                              | Effect                                                                        |
| ---------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------- |
| `capabilities`                     | Union                                       | Agent can add new capabilities but cannot remove platform or org capabilities |
| `enforcement.forbidden`            | Deny-overrides union                        | Both org and agent forbidden rules are enforced; agent cannot subtract        |
| `enforcement.default_mode`         | Strictest wins (`enforce` > `warn` > `off`) | Agent can tighten, not loosen                                                 |
| `enforcement.unmapped_tool_action` | Org is floor                                | Agent can strengthen (`allow` → `warn` → `deny`) but cannot weaken            |
| `autonomy.escalation_triggers`     | Union                                       | Both org and agent triggers are evaluated                                     |

### Strengthening enforcement

The org mode acts as a floor; the agent can only move in the stricter direction:

```
allow → warn → deny     (unmapped_tool_action)
off   → warn → enforce  (default_mode)
```

If the org sets `unmapped_tool_action: warn`, an agent can set it to `deny` (stricter) but not `allow` (weaker).

### Transaction guardrails

Transaction-scoped cards can further restrict the composed enforcement via intersection semantics. A transaction guardrail can only narrow what's permitted — never expand it.

```yaml theme={null}
# Transaction-level override: restrict to read-only tools for this operation
transaction_guardrails:
  allowed_capabilities:
    - file_reading
    - database_read
  # All other capabilities are denied for this transaction
```

## Coverage report

Every `mnemom card evaluate` run produces a coverage report that quantifies how well the card's `capabilities` section maps to its `autonomy.bounded_actions`. This identifies gaps between what the card declares and what the policy actually covers.

### Coverage metrics

| Metric                  | Description                                                         |
| ----------------------- | ------------------------------------------------------------------- |
| `total_card_actions`    | Number of actions declared in the card's `autonomy.bounded_actions` |
| `mapped_card_actions`   | Number of card actions covered by at least one capability           |
| `unmapped_card_actions` | Card actions with no corresponding capability                       |
| `coverage_pct`          | `mapped_card_actions / total_card_actions * 100`                    |

### Example output

```json theme={null}
{
  "coverage": {
    "total_card_actions": 8,
    "mapped_card_actions": 6,
    "unmapped_card_actions": 2,
    "coverage_pct": 75.0,
    "unmapped_actions": [
      "send_notification",
      "generate_report"
    ],
    "mapped_actions": {
      "web_fetch": ["web_browsing"],
      "web_search": ["web_browsing"],
      "read_file": ["file_reading"],
      "read_data": ["database_read"],
      "write_data": ["database_write"],
      "compare": ["data_analysis"]
    }
  }
}
```

<Warning>
  A coverage percentage below 100% means some card actions have no backing capability mapping. Tools implementing those actions will fall through to `enforcement.unmapped_tool_action`. Aim for 100% coverage in production cards.
</Warning>

### Using coverage in CI/CD

```bash theme={null}
# Evaluate a card and fail if any card action is unmapped (sub-100% coverage)
mnemom card evaluate \
  card.yaml \
  --tools mcp__browser__navigate,mcp__filesystem__read_file \
  --strict

# Exit code 1 on warnings (any unmapped action) as well as failures
```

`card evaluate` always prints the coverage percentage and lists unmapped actions. Coverage gating is binary: without `--strict` only hard policy violations exit non-zero; with `--strict` any unmapped action (i.e. coverage below 100%) is treated as a warning that also exits `1`. This integrates naturally into pre-deploy gates: a card change that introduces an unmapped action blocks the merge. See [CI/CD policy gates](/guides/ci-cd-policy-gates) for the full pipeline template.

## Putting it together

Here's the full alignment card for a research agent that can browse the web and read files but cannot delete anything or execute shell commands:

```yaml theme={null}
card_version: unified/2026-04-15
card_id: ac-research-agent-v2
agent_id: mnm-your-agent-id
issued_at: "2026-03-04T00:00:00Z"

principal:
  type: human
  relationship: delegated_authority

values:
  declared: [transparency, harm_prevention, accuracy]

autonomy:
  bounded_actions:
    - inference
    - web_fetch
    - web_search
    - read_file
    - search
  forbidden_actions:
    - delete_files
    - execute_shell
    - exfiltrate_data

capabilities:
  web_browsing:
    description: "Browser-based research and navigation"
    tools:
      - "mcp__browser__navigate"
      - "mcp__browser__click"
      - "mcp__browser__screenshot"
      - "mcp__browser__evaluate_script"
    card_actions: [web_fetch, web_search]

  file_reading:
    tools:
      - "mcp__filesystem__read_file"
      - "mcp__filesystem__list_directory"
    card_actions: [read_file]

  search:
    tools:
      - "mcp__search__query"
      - "mcp__search__suggest"
    card_actions: [search]

enforcement:
  default_mode: warn
  unmapped_tool_action: warn
  unmapped_severity: medium
  grace_period_hours: 24
  forbidden:
    - pattern: "mcp__filesystem__delete*"
      reason: "File deletion not permitted for research agents"
      severity: critical
    - pattern: "mcp__filesystem__write*"
      reason: "File writing not permitted for research agents"
      severity: high
    - pattern: "mcp__shell__*"
      reason: "Shell execution never permitted"
      severity: critical

audit:
  trace_format: ap-trace-v1
  retention_days: 90
  tamper_evidence: append_only
```

## Limitations

* Policy evaluation adds latency to gateway requests (typically under 5 ms for cards with fewer than 100 capability patterns).
* Glob patterns match tool names only, not tool arguments. A tool can be permitted by policy but still violate alignment constraints based on how it's called.
* Grace periods are tracked per-agent, not per-card-version. Updating a card doesn't reset grace-period timers for previously seen tools.
* Coverage reports require a valid `autonomy.bounded_actions` list. Agents with an empty envelope get a coverage report with 0% coverage (no denominator).

## Policy engine and AEGIS Managed Rules

The Policy Engine is **Phase 1 of CLPI**; AEGIS [Managed Rules](/concepts/managed-rules) are a separate (but composable) layer. When a Managed Rule promotes, the gateway loads it via the tiered KV → R2 → in-isolate read substrate. The policy engine still enforces card-defined capability mappings; the Managed Rule adds detection thresholds that screen the inputs and outputs the policy engine then allows or denies. Both compose through the same [cards composition primitive](/concepts/aegis) — the recipe (detection content) and the rule (control-plane state) flow into the cards cascade Platform → Org → Team → Agent under strictest-wins composition.

## See also

* [AEGIS Managed Rules](/concepts/managed-rules) — the cross-tenant signed rule plane that composes with policy
* [Alignment Card Schema](/specifications/alignment-card-schema) — normative schema for the unified alignment card (including capabilities + enforcement sections)
* [Policy Management Guide](/guides/policy-management) — step-by-step guide to authoring and deploying the `capabilities` + `enforcement` sections
* [CI/CD Policy Gates](/guides/ci-cd-policy-gates) — `mnemom card evaluate` in GitHub Actions and GitLab CI
* [Card Lifecycle](/concepts/card-lifecycle) — how alignment cards evolve and interact with policy
* [Card Composition](/concepts/card-composition) — how platform / org / agent scopes merge
* [Enforcement Modes](/gateway/enforcement) — alignment enforcement (observe/nudge/enforce) vs. policy enforcement