Policy management

Policy is now part of the alignment card. In the unified card model (UC-4..UC-8), 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 (autonomy_envelope) describe the protocol-level interop surface; the unified card is what you write in production.

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

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:

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

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 for how the two levels combine.

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:

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:

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.

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.

Publish

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

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.

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 (unified shape) or autonomy_envelope.bounded_actions (AAP protocol shape). These are the abstract actions your agent has declared:

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

Each of these needs at least one capability mapping in your policy.

Identify concrete tools

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

mnemom traces list --agent support-agent --format tools

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:

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.

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

Verify coverage

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

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 UC-4 (2026-04-15).

Publish policy (set the alignment card)

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

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

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

Fetch the canonical card

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

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

curl -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \
  "https://api.mnemom.ai/v1/agents/{agent_id}/alignment-card?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:

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": ["mcp__browser__navigate", "mcp__filesystem__delete"],
    "context": "gateway"
  }'

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:

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",
    "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).

Multi-environment strategies

Separate policies per environment

Use different enforcement modes across environments to catch issues progressively:

Development
Staging
Production

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

defaults:
  unmapped_tool_action: allow
  enforcement_mode: warn
  grace_period_hours: 168  # 7 days

In staging, surface warnings so you can identify unmapped tools and policy gaps before production:

defaults:
  unmapped_tool_action: warn
  enforcement_mode: warn
  grace_period_hours: 24

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

defaults:
  unmapped_tool_action: deny
  enforcement_mode: enforce
  grace_period_hours: 24

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

# .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 can analyze your team’s fault lines and generate policy recommendations based on observed agent behavior, common violation patterns, and alignment card structure.

Generate a recommendation

curl -X POST https://api.mnemom.ai/v1/teams/recommend-policy \
  -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "team-support-ops",
    "analysis_window_days": 30
  }'

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

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

Review and customize

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:

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

Start with warn mode

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.

Evaluate before publishing

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

Align mappings with card actions

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

Aim for >90% coverage

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

Use the grace period

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.

Version control policies

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.

Guides

Safe House

Policy Management

Policy management

Quick start

Capability mapping walkthrough

Start from your alignment card

Identify concrete tools

Create the mappings

Use glob patterns for tool families

Verify coverage

API-based management

Publish policy (set the alignment card)

Fetch the canonical card

Evaluate tools against the active policy

Historical evaluation

Multi-environment strategies

Separate policies per environment

Org-level baseline, agent-level specialization

Version control your policies

Using policy recommendations

Generate a recommendation

Review and customize

Best practices

Start with warn mode

Evaluate before publishing

Align mappings with card actions

Aim for >90% coverage

Use the grace period

Version control policies

See also

Guides

Safe House

​Policy management

​Quick start

​Capability mapping walkthrough

​Start from your alignment card

​Identify concrete tools

​Create the mappings

​Use glob patterns for tool families

​Verify coverage

​API-based management

​Publish policy (set the alignment card)

​Fetch the canonical card

​Evaluate tools against the active policy

​Historical evaluation

​Multi-environment strategies

​Separate policies per environment

​Org-level baseline, agent-level specialization

​Version control your policies

​Using policy recommendations

​Generate a recommendation

​Review and customize

​Best practices

Start with warn mode

Evaluate before publishing

Align mappings with card actions

Aim for >90% coverage

Use the grace period

Version control policies

​See also

Policy management

Quick start

Capability mapping walkthrough

Start from your alignment card

Identify concrete tools

Create the mappings

Use glob patterns for tool families

Verify coverage

API-based management

Publish policy (set the alignment card)

Fetch the canonical card

Evaluate tools against the active policy

Historical evaluation

Multi-environment strategies

Separate policies per environment

Org-level baseline, agent-level specialization

Version control your policies

Using policy recommendations

Generate a recommendation

Review and customize

Best practices

See also