> ## 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 AAP & AIP
> Migrating to the current AAP (2.0.0) and AIP (1.3.0) SDK releases, including the 1.0.0 stability commitment and the 2.0.0 card-shape breaking change.
The current SDK releases are [`@mnemom/agent-alignment-protocol`](https://github.com/mnemom/aap) **2.0.0** and [`@mnemom/agent-integrity-protocol`](https://github.com/mnemom/aip) **1.3.0**. AIP has had no breaking changes since its 1.0.0 stability commitment — 1.1.0 through 1.3.0 are additive. AAP had one breaking release since 1.0.0: **2.0.0**, which renamed two card fields. If you are upgrading from the 0.x series, start with the **1.0.0** section below, then apply the **2.0.0** section on top of it. If you are already on AAP 1.x, jump straight to **Upgrading to AAP 2.0.0**.
## Upgrading to AAP 2.0.0
AAP 2.0.0 renamed two top-level `AlignmentCard` fields (the unified-cards shape you see in the 1.0.0 examples below already anticipated this rename, so if you built against the unified card documented on this page you may already be compliant):
| Before (AAP 1.x) | After (AAP 2.0.0) |
| - | - |
| `autonomy_envelope` | `autonomy` |
| `audit_commitment` | `audit` |
| `AuditCommitment` type / `AuditStorage` / `StorageType` | `Audit` type; the legacy `storage` sub-object is removed — the platform validator rejects `audit.storage` |
| `EU_COMPLIANCE_AUDIT_COMMITMENT` preset | `EU_COMPLIANCE_AUDIT` preset |
| — | `AlignmentMode` type added (`autonomy_mode` / `integrity_mode` on the card) |
```bash theme={null}
npm install @mnemom/agent-alignment-protocol@2.0.0
# or
pip install agent-alignment-protocol==2.0.0
```
```diff theme={null}
card = AlignmentCard(
...,
- autonomy_envelope=Autonomy(bounded_actions=[...]),
+ autonomy=Autonomy(bounded_actions=[...]),
- audit_commitment=Audit(**EU_COMPLIANCE_AUDIT_COMMITMENT),
+ audit=Audit(**EU_COMPLIANCE_AUDIT),
)
```
Field *contents* are unchanged — only the top-level key names moved. AIP is unaffected: it has no `autonomy_envelope` or `audit_commitment` field of its own.
This is a real major-version break: mnemom-api's live `X-Mnemom-Schema` unified card identity (`unified/2026-04-15`) already uses `autonomy` / `audit`, so a 1.x SDK reading a card straight from the API works fine — the break only bites your own code if it constructs an `AlignmentCard` object using the old `autonomy_envelope=`/`audit_commitment=` constructor keywords.
## Upgrading to AAP & AIP 1.0.0
**Backward compatible.** Existing 0.x alignment cards continue to work unchanged. The 1.0.0 server accepts every 0.x card shape. Update at your own pace.
## The 1.0.0 stability commitment
The 1.0.0 release makes three explicit promises about what happens next:
1. **Breaking changes now require a major bump to 2.0.** Field renames, removals, type changes, or required-parameter additions cannot ship within 1.x.
2. **Each major version is supported for 18 months** from the release of its successor (see [API versioning](/guides/api-versioning)). That 18-month window is longer than most APIs and reflects our commitment to agentic callers that cannot self-update in response to deprecation notices.
3. **Deprecation signals are explicit.** Deprecated versions return `Deprecation`, `Sunset`, and `Link` response headers (see [API versioning](/guides/api-versioning#deprecation-signals)). No API version is deprecated as of this writing.
The 1.x line will receive bug fixes and strictness improvements. New *card-format* features are reserved for 2.0.
## What changed
| Area | Before (0.5.x) | After (1.0.0) |
| - | - | - |
| AAP npm package | `@mnemom/agent-alignment-protocol@0.5.0` | `@mnemom/agent-alignment-protocol@1.0.0` |
| AAP PyPI package | `agent-alignment-protocol==0.5.0` | `agent-alignment-protocol==1.0.0` |
| AIP npm package | `@mnemom/agent-integrity-protocol@0.4.x–0.8.0` | `@mnemom/agent-integrity-protocol@1.0.0` |
| AIP PyPI package | `agent-integrity-proto==0.4.x–0.8.0` | `agent-integrity-proto==1.0.0` |
| Protocol version emitted on new cards | `"0.5.0"` | `"1.0.0"` |
| Python `__version__` (AAP) / `AIP_VERSION` | `"0.5.0"` / `"0.4.x"` | `"1.0.0"` / `"1.0.0"` |
| Breaking-change policy | 0.x semantics — breaking changes at minor bumps | Locked — breaking changes require 2.0 |
Nothing else changed. No alignment card schema edits, no endpoint removals, no signature changes.
**AIP callers on 0.7.x or earlier:** AIP 0.8.0 (also shipped 2026-04-13 as the pre-1.0 audit) removed `WindowManager` and `createWindowState` from the public exports. Window state is now managed internally by `createClient()`. If you import either symbol directly, migrate to `createClient()` before bumping to 1.0.0. The `WindowState` *type* remains exported.
## Migration
### Update your SDKs
Install the 1.0.0 releases. Both protocols shipped on the same day with coordinated semver.
```bash theme={null}
npm install @mnemom/agent-alignment-protocol@1.0.0 \
@mnemom/agent-integrity-protocol@1.0.0
```
Or with pnpm:
```bash theme={null}
pnpm add @mnemom/agent-alignment-protocol@1.0.0 \
@mnemom/agent-integrity-protocol@1.0.0
```
```bash theme={null}
pip install 'agent-alignment-protocol==1.0.0' \
'agent-integrity-proto==1.0.0'
```
Or with uv:
```bash theme={null}
uv pip install 'agent-alignment-protocol==1.0.0' \
'agent-integrity-proto==1.0.0'
```
After updating, any new alignment card created via the SDK carries the updated internal protocol version.
### Update your alignment cards
Migrate your existing alignment cards to the **unified card shape** so they pass `mnemom card validate` and can be published. Choose the approach that matches how you manage your cards:
```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" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"card_version": "unified/2026-04-15",
"card_id": "ac-your-card-id",
"agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
"issued_at": "2026-04-13T00:00:00Z",
"expires_at": "2026-10-13T00:00:00Z",
"principal": { "type": "human", "relationship": "delegated_authority" },
"values": {
"declared": ["transparency", "honesty", "harm_prevention"],
"hierarchy": "lexicographic"
},
"autonomy": {
"bounded_actions": ["inference", "read", "write"],
"forbidden_actions": ["exfiltrate_data"]
},
"audit": {
"trace_format": "ap-trace-v1",
"retention_days": 90,
"queryable": true,
"tamper_evidence": "append_only"
}
}'
```
If you version-control your card as a local file, a version-number bump alone still fails `mnemom card validate` — the platform expects the **unified field structure**, which differs from the 0.x card layout. Update your file to the unified shape:
1. Set `card_version: "unified/2026-04-15"` at the top level, replacing the old protocol-version field.
2. Add top-level `autonomy_mode: observe` and `integrity_mode: observe` (or `enforce`).
3. Move your bounded/forbidden actions and escalation triggers under an `autonomy:` block.
4. Move your audit settings under an `audit:` block, and add `query_endpoint: https://api.mnemom.ai/v1/traces`.
5. Add `principal.identifier` if `principal.type` is not `unspecified`.
The [Card Management worked example](/guides/card-management) shows a complete unified card you can copy and map your existing values into. Then validate and publish:
```bash theme={null}
mnemom card validate alignment-card.yaml
mnemom card publish alignment-card.yaml --agent my-agent
```
See [Alignment Card Schema](/specifications/alignment-card-schema) for the full unified field reference, or [Card Management](/guides/card-management) for a complete worked example you can copy.
See [Alignment Card Management](/guides/card-management) for the full lifecycle (claim, link, rekey).
### Rebuild and redeploy
Rebuild your service with the updated lockfiles and deploy. There are no runtime flags to flip, no environment variables to set, and no compatibility shims to configure.
```bash theme={null}
# TypeScript
npm ci && npm run build
# Python
pip install -r requirements.txt
```
### Verify 1.0.0 is in use
Confirm the upgrade from three places:
**SDK version at runtime.**
```typescript theme={null}
import { AIP_VERSION } from '@mnemom/agent-integrity-protocol';
console.log(AIP_VERSION);
// → "1.0.0"
```
```python theme={null}
import aap
from aip import AIP_VERSION
print(aap.__version__) # → "2.0.0" (the installed AAP package version)
print(AIP_VERSION) # → "1.0.0" (AIP's protocol version — distinct from the AIP package version, 1.3.0)
```
**API response headers.** Every response echoes the date-header API version in use:
```bash theme={null}
curl -i https://api.mnemom.ai/v1/alignment/agent/$AGENT_ID \
-H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \
-H "X-Mnemom-Version: 2026-08-17" | grep -i x-mnemom-version
# → X-Mnemom-Version: 2026-08-17
```
See [API versioning](/guides/api-versioning) for how to pin to a specific date. The SDKs do **not** set this header themselves — pin it yourself on requests where you need stable behavior.
**Card contents.** Fetch a card you just wrote and confirm `card_version`:
```bash theme={null}
curl https://api.mnemom.ai/v1/alignment/agent/$AGENT_ID \
-H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" | jq '.card_version'
# → "unified/2026-04-15"
```
## Coming from 0.1.0? You can skip 0.5
The 0.x series was backward-compatible throughout — a `0.1.0` card is still accepted by the 1.0.0 server. If you are on 0.1.0, you do **not** need to pass through the [0.1.0 → 0.5.0 guide](/guides/upgrading-to-0-5) first. Bump directly to 1.0.0 using the steps above; replace `"0.5.0"` with `"1.0.0"` wherever it appears in that guide's examples.
The 0.5.0 guide remains online as a historical migration record (useful mainly for the YAML authoring and Trust Edges context it introduced, both of which carry forward unchanged).
## What's *not* in 1.0.0
Because 1.0.0 was a stability commitment rather than a redesign, several things were deliberately absent from that release:
* **No new endpoints.** The API surface was the same as 0.5.x.
* **No deprecations yet.** No `Deprecation` or `Sunset` headers were emitted on any endpoint as of the 1.0.0 cut.
* **No unified agent card.** The unified card shape (`autonomy`, `audit`, unified alignment + protection cards) arrived shortly after, in mnemom-api's own `unified/2026-04-15` cutover, and later became the AAP 2.0.0 SDK shape (see above).
* **No changes to ZK proof formats or Merkle tree structure.** Those are versioned separately by the AAP/AIP protocol specs, not by the SDK semver.
## Where things stand now
AAP 2.0.0 shipped the card-field rename above. AIP has stayed at the 1.0.0 stability commitment through 1.3.0 — all additive, no breaking changes. A broader vision of unifying AAP alignment cards with policy YAML into a single agent-card format was floated in the 1.0.0-era CHANGELOGs; it has not shipped as of this writing, and no date is committed.
Each SDK's own breaking-change policy (a major bump required, per the 1.0.0 stability commitment above) is separate from mnemom-api's own date-header API versioning — see [API versioning](/guides/api-versioning#support-window) for that policy's 18-month support window, and pin `X-Mnemom-Version` in production so behavior stays stable until you choose to migrate.
## Checklist
### Update SDK packages
Install `@mnemom/agent-alignment-protocol@2.0.0` and `@mnemom/agent-integrity-protocol@1.3.0` (or the PyPI equivalents).
### Update alignment cards
Migrate every alignment card to the unified shape — use the Via YAML / JSON file tab in the previous step, or publish via API using `card_version: "unified/2026-04-15"`. If your own code constructs `AlignmentCard`/`Audit`/`Autonomy` objects directly, apply the AAP 2.0.0 field renames too.
### Rebuild and redeploy
Ship the bumped lockfiles to every environment that calls the Mnemom API or emits AIP checkpoints.
### Pin your API version
Send `X-Mnemom-Version: 2026-08-17` on every production request — the SDKs do not set this header for you.
### Verify
Read back `AIP_VERSION` / `aap.__version__` at runtime, check `X-Mnemom-Version` on a live response, and confirm `card_version` on a freshly-written card.
## FAQ
No. The 1.0.0 server accepts every 0.x card shape, and no endpoint signatures changed. 1.0.0 is a commitment that future breaking changes require a major bump, not a redesign of the current surface.
Yes, but narrowly: two top-level `AlignmentCard` field names moved (`autonomy_envelope` → `autonomy`, `audit_commitment` → `audit`). Field contents, endpoints, and AIP are unaffected. See **Upgrading to AAP 2.0.0** above.
No. Cards on different protocol versions coexist without issues. Roll the update at whatever cadence suits you.
AIP 0.8.0 (shipped the same day as 1.0.0 as the pre-1.0 audit) removed `WindowManager` and `createWindowState` from public exports. Switch to `createClient()`, which manages window state internally, before jumping to a current AIP release.
Yes — 1.1.0 through 1.3.0 have all been additive (new optional fields, no removals or renames).
## See also
* [API versioning](/guides/api-versioning) — Pinning to a specific `X-Mnemom-Version` date header and understanding the support window.
* [Alignment Card Management](/guides/card-management) — Creating, claiming, and linking cards.
* [Alignment Cards](/concepts/alignment-cards) — Schema reference for the current card model.
* [Upgrading to AAP 0.5.0](/guides/upgrading-to-0-5) — Historical migration record for the `0.1.0 → 0.5.0` jump.
* [Changelog](/changelog) — Full release history.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.