Policy Engine

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

The policy engine translates Alignment Card 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.

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 for the customer workflow.

The policy engine is a parallel enforcement layer to alignment 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.

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.

Example excerpt of a card’s policy sections

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

CI/CD (Static)
Gateway (Live)
Observer (Post)

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:

# 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 for GitHub Actions + GitLab CI templates.

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:

Request arrives at the gateway.
Gateway reads the canonical alignment card (KV-cached, 5-min TTL).
Each tool in the request is checked against enforcement.forbidden first.
Remaining tools are matched against capabilities[*].tools globs.
Unmatched tools fall through to enforcement.unmapped_tool_action.
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	HTTP 403 block (non-streaming); nudge-fallback (streaming)

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.Feeds into proving: when the gateway’s policy evaluation detects card_gap signals alongside a boundary_violation, ZK proving is deferred instead of immediately dispatched to GPUs. This prevents stale alignment cards from driving up proving costs during rapid iteration.

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:

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.

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.

How matching works

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

Forbidden check: does the tool match any enforcement.forbidden[].pattern? If yes, the tool is a violation regardless of capability mappings.
Capability match: does the tool match any capabilities[*].tools glob? If yes, the tool is allowed and mapped to the corresponding card actions.
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:

Warn

Log violations but do not block. X-Policy-Verdict: warn header returned. Default mode.

Enforce

Block requests with policy violations. X-Policy-Verdict: fail header returned. HTTP 403 for non-streaming requests.

Off

Skip policy evaluation entirely. No X-Policy-Verdict header. No performance overhead.

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.

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 and observability exports.

Forbidden rules

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

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`

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.

Unmapped tool handling

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

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

Development
Staging
Production

Use allow during early development when tool sets are still evolving. This avoids noise from constantly changing tool inventories.

Use warn in staging environments. This surfaces unmapped tools in logs and coverage reports without blocking agent functionality. This is the default.

Use deny in production when you have a mature, stable card. Every tool the agent uses should be explicitly mapped or explicitly forbidden.

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.

enforcement:
  grace_period_hours: 24

How it works:

The policy engine tracks when each tool is first seen via tool_first_seen records.
When an unmapped or forbidden tool is encountered, the engine checks how long ago it was first seen.
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.
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.

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.

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

# 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

{
  "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"]
    }
  }
}

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.

Using coverage in CI/CD

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

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 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 — the recipe (detection content) and the rule (control-plane state) flow into the cards cascade Platform → Org → Team → Agent under strictest-wins composition.

​Policy Engine

​How the engine reads the card

​Example excerpt of a card’s policy sections

​Three evaluation contexts

​CI/CD evaluation

​Gateway evaluation

​Observer evaluation

​Capability mapping

​Structure

​Glob patterns

​How matching works

​Enforcement modes

Warn

Enforce

Off

​Relationship to the alignment master switches

​Forbidden rules

​Unmapped tool handling

​Unmapped tool actions

​Choosing the right default

​Grace period

​Composition across scopes

​Merge rules

​Strengthening enforcement

​Transaction guardrails

​Coverage report

​Coverage metrics

​Example output

​Using coverage in CI/CD

​Putting it together

​Limitations

​Policy engine and AEGIS Managed Rules

​See also

Policy Engine

How the engine reads the card

Example excerpt of a card’s policy sections

Three evaluation contexts

CI/CD evaluation

Gateway evaluation

Observer evaluation

Capability mapping

Structure

Glob patterns

How matching works

Enforcement modes

Relationship to the alignment master switches

Forbidden rules

Unmapped tool handling

Unmapped tool actions

Choosing the right default

Grace period

Composition across scopes

Merge rules

Strengthening enforcement

Transaction guardrails

Coverage report

Coverage metrics

Example output

Using coverage in CI/CD

Putting it together

Limitations

Policy engine and AEGIS Managed Rules

See also