Upgrading to AAP & AIP 1.0.0

On 2026-04-13 both protocol SDKs — @mnemom/agent-alignment-protocol and @mnemom/agent-integrity-protocol — shipped 1.0.0. This is a stability commitment release: the public API surface is now locked, and breaking changes require a major bump to 2.0. The migration itself is small. There are no schema changes, no endpoint removals, and no signature changes on the customer-facing surface. Upgrading from 0.5.x is a version-string bump plus a rebuild.

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:

Breaking changes now require a major bump to 2.0. Field renames, removals, type changes, or required-parameter additions cannot ship within 1.x.
Each major version is supported for 18 months from the release of its successor (see 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.
Deprecation signals are explicit. Deprecated versions return Deprecation, Sunset, and Link response headers, and API key owners receive email notifications at T+0, T+12 months, T+16 months, and T+17 months.

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/[email protected]`	`@mnemom/[email protected]`
AAP PyPI package	`agent-alignment-protocol==0.5.0`	`agent-alignment-protocol==1.0.0`
AIP npm package	`@mnemom/[email protected]–0.8.0`	`@mnemom/[email protected]`
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.

TypeScript / npm

npm install @mnemom/[email protected] \
            @mnemom/[email protected]

Or with pnpm:

pnpm add @mnemom/[email protected] \
         @mnemom/[email protected]

Python / PyPI

pip install 'agent-alignment-protocol==1.0.0' \
            'agent-integrity-proto==1.0.0'

Or with uv:

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:

Via API

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"
    }
  }'

Via YAML / JSON file

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:

Set card_version: "unified/2026-04-15" at the top level, replacing the old protocol-version field.
Add top-level autonomy_mode: observe and integrity_mode: observe (or enforce).
Move your bounded/forbidden actions and escalation triggers under an autonomy: block.
Move your audit settings under an audit: block, and add query_endpoint: https://api.mnemom.ai/v1/traces.
Add principal.identifier if principal.type is not unspecified.

The Card Management worked example shows a complete unified card you can copy and map your existing values into. Then validate and publish:

mnemom card validate alignment-card.yaml
mnemom card publish alignment-card.yaml --agent my-agent

See Alignment Card Schema for the full unified field reference, or Card Management for a complete worked example you can copy.

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

# 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

import { AIP_VERSION } from '@mnemom/agent-integrity-protocol';

console.log(AIP_VERSION);
// → "1.0.0"

Python

import aap
from aip import AIP_VERSION

print(aap.__version__)   # → "1.0.0"
print(AIP_VERSION)       # → "1.0.0"

API response headers. Every response echoes the date-header API version in use:

curl -i https://api.mnemom.ai/v1/alignment/agent/$AGENT_ID \
  -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \
  -H "X-Mnemom-Version: 2026-04-13" | grep -i x-mnemom-version
# → X-Mnemom-Version: 2026-04-13

See API versioning for how to pin to a specific date. The 1.0.0 SDKs pin to 2026-04-13 by default.

Card contents. Fetch a card you just wrote and confirm card_version:

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 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 is a stability commitment rather than a redesign, several things you might expect are not here:

No new endpoints. The API surface is the same as 0.5.x.
No schema changes. Alignment card, AP-trace, and integrity checkpoint schemas are unchanged.
No deprecations yet. No Deprecation or Sunset headers are emitted on any endpoint as of the 1.0.0 cut. The deprecation machinery is in place for future use.
No unified agent card. The unified YAML agent card (AAP + CLPI) is a 2.0 target, not a 1.0 feature. See Forward-looking below.
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.

Forward-looking: 2.0 roadmap

The 1.0.0 CHANGELOG entries include a forward-looking note: a 2.0 is planned that unifies AAP alignment cards and CLPI policy YAML into a single YAML agent card with runtime composition. The target is 6–12 months post-1.0, informed by production data from the 1.0 install base. Until then, 1.x receives bug fixes and strictness improvements only — new card-format features are reserved for 2.0. When 2.0 ships, the 1.x line will enter the standard 18-month deprecation window.

The forward-looking note in the AAP and AIP 1.0.0 CHANGELOGs predates the unified-cards model that describes the actual card model shipped in mnemom-api today. The 2.0 unified YAML agent card remains a planned future evolution on top of the unified-cards foundation.

Support window

Under our API versioning policy, each major version is supported for 18 months from the date its successor ships. In concrete terms:

1.0.0 is the current major. It will be supported for at least 18 months after 2.0 ships.
When a new dated API version deprecates an endpoint or field in 1.0.0, you will receive Deprecation and Sunset response headers plus email notifications at T+0, T+12 months, T+16 months, and T+17 months.
Enterprise contracts may negotiate extended support; security vulnerabilities use an accelerated 30-day minimum window.

Pin your integrations to X-Mnemom-Version: 2026-04-13 in production so behavior stays stable until you choose to migrate. See API versioning for pinning details.

Checklist

Update SDK packages

Install @mnemom/[email protected] and @mnemom/[email protected] (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".

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-04-13 on every production request. The 1.0.0 SDKs do this by default.

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

Is this a breaking change?

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 will require a 2.0 bump, not a redesign of the current surface.

Do I need to update all my agents at once?

No. Cards on different protocol versions coexist without issues. Roll the update at whatever cadence suits you.

What if I'm still on AIP 0.7.x with `WindowManager`?

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

Will 1.x get new features?

Bug fixes and strictness improvements, yes. New card-format features are reserved for 2.0 per the 1.0.0 CHANGELOG’s forward-looking note.

When does the 18-month support window start?

The 18-month clock for 1.0.0 starts the day 2.0 ships. Until then, 1.0.0 is the current major and receives ongoing support.

​Upgrading to AAP & AIP 1.0.0

​The 1.0.0 stability commitment

​What changed

​Migration

​Coming from 0.1.0? You can skip 0.5

​What’s not in 1.0.0

​Forward-looking: 2.0 roadmap

​Support window

​Checklist

​FAQ

​See also

Upgrading to AAP & AIP 1.0.0

The 1.0.0 stability commitment

What changed

Migration

Coming from 0.1.0? You can skip 0.5

What’s not in 1.0.0

Forward-looking: 2.0 roadmap

Support window

Checklist

FAQ

See also