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

# Upgrading to AAP 0.5.0

> Step-by-step migration guide for updating your agents, cards, and policies to AAP 0.5.0

<Note>
  **Historical migration record.** AAP is now at 1.0.0. New integrations should follow [Upgrading to AAP & AIP 1.0.0](/guides/upgrading-to-1-0). This page is kept for customers still on `0.1.0` cards and for the YAML authoring and Trust Edges context it introduced.
</Note>

AAP 0.5.0 aligns the `aap_version` field across the entire Mnemom ecosystem — SDKs, schemas, fixtures, and examples all now default to `"0.5.0"`. This release also introduces YAML policy authoring and the Trust Edges API.

<Info>
  **This is a backward-compatible release.** Existing cards with `aap_version: "0.1.0"` continue to work. No breaking changes. We recommend updating your cards at your own pace.
</Info>

## What changed

| Area                  | Before                              | After                                            |
| --------------------- | ----------------------------------- | ------------------------------------------------ |
| `aap_version` default | `"0.1.0"`                           | `"0.5.0"`                                        |
| Policy authoring      | JSON only                           | JSON or YAML                                     |
| Trust edges           | Not available                       | `GET`/`POST`/`DELETE /v1/agents/:id/trust-edges` |
| Test fixtures         | Mixed versions (`"1.0"`, `"0.1.0"`) | Consistent `"0.5.0"`                             |

## Step 1: Update your Alignment Cards

Update the `aap_version` field in your existing alignment cards from `"0.1.0"` to `"0.5.0"`.

### Via API

<Note>
  Endpoint updated for historical accuracy. The original `PATCH /v1/agents/{id}/card` this page was written against was replaced by `PUT /v1/alignment/agent/{id}` in the 2026-04-15 unified-cards consolidation. If you're following this guide end-to-end today, use the unified alignment endpoint and the body shape shown below.
</Note>

```bash 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" \
  -d '{
    "card_version": "unified/2026-04-15",
    "card_id": "ac-your-card-id",
    "agent_id": "your-agent-id",
    "issued_at": "2026-03-04T00:00:00Z",
    "expires_at": "2026-09-04T00:00:00Z",
    "autonomy_mode": "observe",
    "integrity_mode": "observe",
    "principal": { "type": "human", "identifier": "you@example.com", "relationship": "delegated_authority" },
    "values": {
      "declared": ["transparency", "honesty", "harm_prevention"],
      "hierarchy": "lexicographic"
    },
    "autonomy": {
      "bounded_actions": ["inference", "read", "write"],
      "forbidden_actions": ["exfiltrate_data"],
      "escalation_triggers": []
    },
    "audit": {
      "trace_format": "ap-trace-v1",
      "retention_days": 90,
      "queryable": true,
      "query_endpoint": "https://api.mnemom.ai/v1/traces",
      "tamper_evidence": "append_only"
    }
  }'
```

### Via CLI

If you manage your card as a local JSON file, update the `aap_version` field and republish:

```bash theme={null}
# Edit your card file
sed -i '' 's/"aap_version": "0.1.0"/"aap_version": "0.5.0"/' alignment-card.json

# Validate and publish
mnemom card validate alignment-card.json
mnemom card publish alignment-card.json
```

### Via dashboard

1. Open the [Mnemom dashboard](https://mnemom.ai/dashboard)
2. Select your agent
3. Open the **Alignment Card** panel
4. Switch to the **JSON editor**
5. Change `"aap_version": "0.1.0"` to `"aap_version": "0.5.0"`
6. Click **Save**

## Step 2: Update SDK packages

Update to the latest SDK versions that default to `aap_version: "0.5.0"`:

<CodeGroup>
  ```bash npm theme={null}
  npm install @mnemom/agent-alignment-protocol@0.5.0
  ```

  ```bash pip theme={null}
  pip install agent-alignment-protocol==0.5.0
  ```

  ```bash pnpm theme={null}
  pnpm add @mnemom/agent-alignment-protocol@0.5.0
  ```
</CodeGroup>

After updating, any new cards created via the SDK will default to `aap_version: "0.5.0"` automatically.

## New feature: YAML policy authoring

The Mnemom API now accepts policies in YAML format alongside JSON. YAML policies are easier to read, support comments, and are the recommended format going forward.

<Note>
  The standalone `PUT /v1/agents/{id}/policy` endpoint this section originally used was removed in the 2026-04-15 unified-cards consolidation. Policy is now embedded in the unified alignment card's `capabilities` and `enforcement` sections — publish it via `PUT /v1/alignment/agent/{id}`. The YAML body below is the shape of just those sections; the full card has more required fields (see [alignment-card schema](/specifications/alignment-card-schema)).
</Note>

### YAML policy sections (embedded in the alignment card)

```yaml theme={null}
# Map concrete tools to card-level capability categories
capabilities:
  web_browsing:
    tools:
      - "mcp__browser__*"
    card_actions:
      - web_fetch

enforcement:
  default_mode: warn
  unmapped_tool_action: warn
  grace_period_hours: 24
```

Publish the whole alignment card (with the sections above embedded) to activate the policy:

```bash 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" \
  --data-binary @alignment-card.yaml
```

Both `text/yaml` and `application/yaml` content types are accepted. JSON remains fully supported — use whichever format fits your workflow.

<Tip>
  YAML cards support inline comments, making them ideal for documenting the reasoning behind specific policy rules directly in the card file.
</Tip>

## New feature: YAML card authoring

In addition to YAML policies, AAP 0.5.0 introduces YAML as an authoring format for alignment cards. Write your cards in YAML for readability, and they are stored as JSON in the database.

<Info>
  YAML is an **authoring format** — the API converts it to JSON on ingest. Cards are always stored and returned as JSON. You can author in whichever format you prefer.
</Info>

### Complete YAML card example

Here is a full alignment card written in YAML:

```yaml theme={null}
# alignment-card.yaml
aap_version: "0.5.0"
card_id: ac-research-agent-v1
agent_id: smolt-research-agent
issued_at: "2026-03-04T00:00:00Z"
expires_at: "2026-09-04T00:00:00Z"

principal:
  type: human
  relationship: delegated_authority
  escalation_contact: mailto:team@example.com

values:
  declared:
    - transparency
    - honesty
    - harm_prevention
    - minimal_data
  hierarchy: lexicographic

autonomy_envelope:
  bounded_actions:
    - inference
    - read
    - write
    - web_fetch
    - web_search
  escalation_triggers:
    - condition: named_entity_critical
      action: escalate
      reason: Critical claims about named entities require human review
  forbidden_actions:
    - fabricate_sources
    - exfiltrate_data
    - impersonate_human

audit_commitment:
  trace_format: ap-trace-v1
  retention_days: 90
  queryable: true
  tamper_evidence: append_only
```

### Publish via CLI

The CLI accepts both `.yaml` and `.json` card files:

```bash theme={null}
# Validate a YAML card
mnemom card validate my-card.yaml

# Publish it to your agent
mnemom card publish my-card.yaml
```

The CLI detects the file extension and handles conversion automatically. Validation rules are identical for both formats.

### Publish via dashboard

The dashboard card editor now includes a **YAML tab** alongside the Visual and JSON editors:

<Steps>
  ### Open the card editor

  Navigate to your agent in the [dashboard](https://mnemom.ai/dashboard) and open the **Alignment Card** panel.

  ### Switch to the YAML tab

  Click the **YAML** tab at the top of the card editor. You can paste or write your card in YAML format directly.

  ### Save

  Click **Save**. The dashboard validates and converts the YAML to JSON before storing. Any syntax or schema errors are shown inline.
</Steps>

<Tip>
  YAML cards support inline comments, making them ideal for documenting why specific values, triggers, or forbidden actions were chosen — context that is lost in JSON.
</Tip>

## New feature: Trust Edges API

Trust edges define explicit trust relationships between agents. An agent can declare that it trusts another agent, creating a directed edge in the trust graph. Trust edges influence reputation propagation and coherence scoring.

### Create a trust edge

```bash theme={null}
curl -X POST https://api.mnemom.ai/v1/agents/{agent_id}/trust-edges \
  -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to_agent": "smolt-target-agent",
    "weight": 0.9,
    "reason": "manual"
  }'
```

### List trust edges

```bash theme={null}
curl https://api.mnemom.ai/v1/agents/{agent_id}/trust-edges \
  -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY"
```

Response:

```json theme={null}
{
  "agent_id": "smolt-my-agent",
  "direction": "out",
  "count": 1,
  "edges": [
    {
      "id": "te-abc123",
      "from_agent": "smolt-my-agent",
      "to_agent": "smolt-target-agent",
      "trust_level": "high",
      "reason": "Verified partner agent for data pipeline",
      "created_at": "2026-03-04T12:00:00Z"
    }
  ]
}
```

### Remove a trust edge

```bash theme={null}
curl -X DELETE https://api.mnemom.ai/v1/agents/{agent_id}/trust-edges/{edge_id} \
  -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY"
```

Trust levels: `low`, `medium`, `high`. Higher trust levels give more weight to the target agent's reputation in coherence calculations.

## Checklist

Use this checklist to verify your upgrade is complete:

<Steps>
  ### Update alignment cards

  Set `aap_version` to `"0.5.0"` on all agent cards via API, CLI, or dashboard.

  ### Update SDK packages

  Install `@mnemom/agent-alignment-protocol@0.5.0` (npm) or `agent-alignment-protocol==0.5.0` (pip).

  ### Update local card files

  If you version-control alignment card files (JSON or YAML), update `aap_version` in those files and commit. Consider switching to YAML for better readability and inline comments.

  ### Verify

  Run `mnemom card show` for each agent to confirm the updated version is active.
</Steps>

## FAQ

<AccordionGroup>
  <Accordion title="Is this a breaking change?">
    No. Existing cards with `aap_version: "0.1.0"` continue to work without modification. The API accepts both old and new version values. We recommend updating to `"0.5.0"` for consistency, but there is no deadline.
  </Accordion>

  <Accordion title="Do I need to update all my agents at once?">
    No. You can update agents incrementally. Cards with different `aap_version` values coexist without issues.
  </Accordion>

  <Accordion title="Will my existing policies still work?">
    Yes. Policies are unaffected by the `aap_version` change. The new YAML support is additive — existing JSON policies continue to work as before.
  </Accordion>

  <Accordion title="Can I mix JSON and YAML across cards and policies?">
    Yes. YAML support is per-file. You can author some cards in YAML and others in JSON, and the same goes for policies. The API normalizes everything to JSON on ingest, so there are no compatibility issues.
  </Accordion>

  <Accordion title="What happens if I don't upgrade?">
    Nothing breaks. However, new SDK versions default to `"0.5.0"`, so new cards created via the SDK will use the new version. Keeping older cards at `"0.1.0"` is fine but may cause minor inconsistencies in reports.
  </Accordion>

  <Accordion title="How do trust edges affect my reputation score?">
    Trust edges influence how reputation signals propagate between agents. Declaring trust in a high-reputation agent has a small positive effect on coherence scoring. Declaring trust in a low-reputation agent has no negative effect — trust edges are additive.
  </Accordion>
</AccordionGroup>

## See also

* [Alignment Card Management](/guides/card-management) — Creating and managing alignment cards
* [Policy Management](/guides/policy-management) — Policy authoring in YAML and JSON
* [Policy DSL Specification](/specifications/policy-dsl) — Full normative schema for policy files
* [Changelog](/changelog) — Full release history