The ApertoMemory Format: Portable, Client-Side-Encrypted AI Memory

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 23 January 2027.¶

Copyright Notice

Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

Modern AI tools build user-specific memory: preferences, facts, learned behaviours, and procedural knowledge that improve the quality of assistance over time. This memory constitutes some of the most sensitive personal data in existence, and it is currently locked inside each provider's infrastructure. Switching tools destroys accumulated context, creating a form of vendor lock-in that operates on personal data rather than on price or features.¶

Existing portability efforts move memory as cleartext JSON with no integrity protection, no verifiable provenance, and no confidentiality guarantees against the storage layer. This document takes the opposite starting point: memory is encrypted and signed on the user's device before it goes anywhere, and every party except the user's own runtime is treated as untrusted.¶

This document specifies (1) the memory object data model and its deterministic CBOR encoding, (2) the cryptographic envelope (sign-then-encrypt with COSE) and the two bindings that authenticate it, (3) trust derivation and Custody Records, (4) the conversion paths between trust levels (migration, import, and the AI boundary), (5) the user-controlled key hierarchy including per-scope access separation, and (6) the portable export container. Synchronisation protocols and memory extraction from conversations are out of scope.¶

2. Conformance: Who This Specification Binds

The schema and rules of this document bind Producers and Consumers differently, and both obligations are required for conformance.¶

A Producer is bound strictly: it MUST NOT emit an object that violates this specification (Section 3.2). A Consumer has a second, separate obligation: it MUST handle input that does not match this specification without failing catastrophically. Hostile and corrupt objects exist, and refusing to read a whole container because one object inside it is malformed is a denial of service on the user's entire memory. So a validator SHOULD reject a payload carrying an empty Custody Record, because no Producer may write one -- and an implementation MUST still read the container it lives in, degrade that object's trust, and carry on. Both are required; neither substitutes for the other. Where the two obligations meet, this document states which is which.¶

Conformance for format_version 2 is defined by the test-vector set of Appendix A: fourteen vectors, six of which are refusal cases. Reproducing the byte strings of the positive vectors is necessary but not sufficient; an implementation that reproduces every byte and refuses none of the attacks implements the defect the vectors exist to catch. This is stated with unusual emphasis because format_version 1 was byte-compatible with implementations that checked nothing.¶

3. Data Model

A sealed Memory Object is a CBOR map containing exactly the fields a Blind Server is permitted to see, plus an encrypted envelope. All semantic content, including authorship and semantic timestamps, lives inside the envelope.¶

The normative schema is expressed in CDDL [RFC8610]:¶

sealed-object = {
  1 => bstr .size 16,   ; id: 128-bit random (NOT UUIDv7:
                        ;   time-ordered ids leak creation time)
  2 => bstr .size 16,   ; scope_id: opaque random identifier
  3 => uint,            ; format_version (this document: 2;
                        ;   1 = legacy, see Section on Legacy)
  4 => bstr,            ; COSE_Encrypt0 (AES-256-GCM, COSE alg 3,
                        ;   MTI; alg 24 OPTIONAL) whose plaintext
                        ;   is a COSE_Sign1 (EdDSA) over
                        ;   memory-payload. Both carry
                        ;   envelope-aad as external_aad.
  ? 5 => bstr .size 16, ; dek_wrap_ref (RESERVED)
}

memory-payload = {
  1 => mem-type,
  2 => tstr,            ; content: UTF-8 text (this rev: text only)
  3 => confidence,      ; 0.0 .. 1.0
  4 => provenance,
  5 => trust-level,     ; INFORMATIONAL ONLY - Section on Trust
  ? 6 => [* tstr],      ; tags
  7 => timestamps,      ; SEMANTIC times - MUST NOT appear
                        ;   in cleartext
  ? 8 => embedding,     ; RESERVED - MUST travel encrypted only
  ? 9 => epoch-seconds, ; expires_at. RESERVED
  ? 10 => {* tstr => any}, ; extensions. RESERVED
  ? 20 => custody,      ; present iff re-sealed - Section on
                        ;   Custody Records
  * uint => any,        ; unrecognised keys MUST be preserved
                        ;   on rewrite
}

mem-type = &( episodic: 1, semantic: 2, procedural: 3 )

confidence = float .ge 0.0

provenance = {
  1 => tstr,            ; producing tool (e.g. "amem-cli/0.2")
  2 => bstr .size 8,    ; author_key_id: first 8 bytes of
                        ;   SHA-256 of the author's Ed25519
                        ;   public key. BOUND to the verifying
                        ;   key - Section on Author Binding.
  ? 3 => tstr,          ; session identifier
}

trust-level = &( self: 1, trusted: 2,
                 third-party: 3, unverified: 4 )
; third-party (3) is reserved: this revision derives only
; self, trusted and unverified. Retained for wire
; compatibility with v1 payloads.

timestamps = { 1 => epoch-seconds, ? 2 => epoch-seconds }
                        ; created, updated

epoch-seconds = uint    ; seconds since 1970-01-01T00:00:00Z,
                        ;   as a BARE uint (see below)

embedding = { 1 => tstr, 2 => [* float] } ; model, vector

Object identifiers MUST be generated from a cryptographically secure random source. Time-ordered identifiers (such as UUIDv7) MUST NOT be used, as they leak creation-time metadata to the Blind Server.¶

The normative range of confidence is 0.0 to 1.0 inclusive. CDDL tooling does not express a closed float interval portably -- chained control operators on float ranges are rejected by common validators -- so the upper bound is stated here and enforced by test vector 013 rather than by the schema. A Producer MUST NOT write a value outside this range. A Consumer that reads one MUST NOT propagate it: the object is authentic, so it is not refused, but the value is reported as absent and the schema violation flagged (Section 8.3).¶

Timestamps are bare unsigned integers, deliberately not the CDDL prelude "time" (a tag-1 epoch datetime). Every object written so far, and every test vector, carries an untagged integer; requiring the tag now would invalidate every existing vault to gain nothing. The schema records what the format is, not what it might have been. (This divergence was found by validating the vectors with a second, independent CDDL implementation.)¶

Unrecognised integer keys in memory-payload MUST be preserved byte for byte when an object is re-encoded (see Section 13).¶

4. Encoding and Cryptographic Envelope

All structures are serialised as deterministically encoded CBOR as defined in Section 4.2 of [RFC8949].¶

The envelope construction is sign-then-encrypt:¶

1. The memory-payload map is encoded as deterministic CBOR and signed as the payload of a COSE_Sign1 structure [RFC9052] using EdDSA (Ed25519) [RFC8032], with the envelope-aad of Section 5.1 supplied as external_aad.¶
2. The COSE_Sign1 output is encrypted as the payload of a COSE_Encrypt0 structure using an AEAD algorithm under a single-use, per-object DEK with a 96-bit random nonce, with the same envelope-aad supplied as external_aad.¶

Placing the signature inside the encryption prevents the Blind Server from learning or correlating authorship. The server can neither learn nor verify authorship; signature verification is performed by Consumers after decryption, and Consumers MUST reject objects whose signature does not verify (Section 6).¶

The mandatory-to-implement AEAD algorithm is AES-256-GCM (COSE algorithm 3, [RFC9053]). ChaCha20/Poly1305 (COSE algorithm 24) is OPTIONAL. Each DEK MUST encrypt exactly one object; nonce reuse under a given key is thereby structurally excluded, and the random nonce serves as defence in depth.¶

All algorithms are referenced by COSE algorithm identifiers. Future migration (including to post-quantum algorithms) is a registry change, not a format change.¶

5. The Two Bindings

format_version 1 objects carried no cryptographic relationship between a signature, the author it claimed, and the cleartext envelope around it. format_version 2 binds both.¶

envelope-aad = [
  uint,                 ; format_version, as in the envelope
  bstr .size 16,        ; id, as in the envelope
  bstr .size 16,        ; scope_id, as in the envelope
]

6. Trust Is Derived, Never Declared

The trust-level field of memory-payload is carried for wire compatibility and MUST NOT be read as authoritative. A Consumer derives trust from which key verified the signature:¶

Trust is evaluated at read time against the current Keyring, and MUST NOT be frozen into the object: revoking a key downgrades every memory attributed to it, with no rewrite.¶

Verification is fail-closed. A Consumer that cannot authenticate an object MUST NOT return its content by default; reading it requires an explicit opt-in and yields trust "unverified".¶

Consumers MUST treat content whose derived trust is not "self" as untrusted DATA and MUST NOT give it instruction-level privilege (Section 15.2). This is the whole point of the author binding: without it, hostile text could claim to be the user's own memory.¶

An object carrying a Custody Record additionally reports its authorship as described in Section 7: derived provenance distinguishes the signer of the object as it stands from the author of its content, and reports "signed", "attested" or "unknown" authorship accordingly.¶

7. Custody Records

Re-sealing an object changes its signer. A re-sealed object's signature therefore proves CUSTODY, not authorship -- and the object says so, by carrying a Custody Record (memory-payload key 20):¶

custody = {
  1 => uint,            ; format_version it was re-sealed from
  2 => bstr .size 8,    ; author_key_id claimed by the
                        ;   original object
  3 => epoch-seconds,   ; when it was re-sealed
  ? 4 => bstr .size 8,  ; author_key_id PROVEN at re-seal
                        ;   time; absent = authorship could
                        ;   not be proven
}

The rules, each pinned by a test vector:¶

• An object carrying a Custody Record MUST NOT resolve to trust "self", whoever signed it. The custodian did not write it.¶
• A Custody Record is an attestation BY THE CUSTODIAN: it is honoured only when the verified signer is the vault Owner. Honouring one signed by anyone else would let any accepted third party attribute content to the Owner -- or to anyone -- and have it read as trusted (test vector 011).¶
• Field 4 present and naming a currently accepted key: the object opens as trust "trusted", authorship "attested", and the PROVEN author -- not the signer -- is reported as author_key_id (test vector 007).¶
• Field 4 absent, or naming a key that is not accepted: the object opens as trust "unverified", authorship "unknown", and NO author is reported: not the signer, and not the unaccepted key. The unproven original claim is exposed separately as a claimed author (test vectors 008, 012).¶
• A malformed or empty Custody Record degrades trust to "unverified"; it MUST NOT raise an error that aborts reading. A sub-map that throws is a denial of service on the whole container (test vector 014).¶

Note on test vector 014: its payload deliberately does NOT conform to the custody rule above -- an empty map has none of the required keys. That is the point of the vector, and the keys stay mandatory on purpose: making them optional would declare an empty Custody Record legal to WRITE, which it is not. A validator will reject that payload, and it should; an implementation must nevertheless read it, degrade it to "unverified", and continue (Section 2).¶

8. Conversion Paths Between Trust Levels

Most of this format holds trust constant: a sealed object is written at one trust level and read back at the same one. Three paths do not. They take data from one trust domain and emit it into another: migration (from the unbound format_version 1 into format_version 2), import (from an external container into a vault), and the AI boundary (from sealed objects into an AI system's context window). Every defect found in this format so far was found on one of these paths: the forgeable provenance of format_version 1 ([GHSA]), the import that destroyed the identity of an existing vault, the migration that would have re-signed hostile objects as the Owner's own (caught in review before release), and the custody attestation honoured from any accepted key. This is not a coincidence. A forgery only pays off where trust changes, so these are the paths an attacker studies, and they are specified here with the same care as the cryptography.¶

The rule uniting the three subsections: a conversion path MUST NOT output data at a higher trust level than it can prove for its input, and where proof is impossible the path MUST either refuse or explicitly mark the output as unproven. Silent upgrade is the defect class; each subsection names the form it takes on that path.¶

9. Key Hierarchy

All keys derive from, or are wrapped towards, material under exclusive user control:¶

passphrase --Argon2id--> master secret (32 bytes)
master secret --HKDF-SHA256--> Ed25519 seed (signing)
master secret --HKDF-SHA256--> X25519 seed (key agreement)
scope KEK (32 bytes random)
    <-- ECDH-ES(X25519) + HKDF-SHA256 + AES-256-KW -- master
object DEK (32 bytes random, single object)
    <-- AES-256-KW -- scope KEK

The Argon2id [RFC9106] parameters are fixed: memory 64 MiB, iterations 3, parallelism 4, 16-byte random salt, 32-byte output (the second recommended parameter choice of RFC 9106).¶

Key derivation uses HKDF-SHA256 [RFC5869]; key agreement uses X25519 [RFC7748]. HKDF info strings provide domain separation: "apertomemory/v1/sign", "apertomemory/v1/ka", and "apertomemory/v1/kek-wrap" concatenated with the scope_id. Binding the KEK wrap to the scope_id ensures a wrapped KEK cannot be transplanted between scopes.¶

The key hierarchy did not change in format_version 2, and the HKDF info strings deliberately retain the "v1" label: altering them would break every existing vault for no security benefit. The label names the hierarchy, not the object format.¶

Key wrapping uses AES Key Wrap [RFC3394]. Server-side key escrow is out of scope of this format: a lost passphrase without a recovery mechanism means unrecoverable memory, and implementations SHOULD offer user-held recovery codes.¶

10. Portable Export Container

The export container serialises a complete memory set into a single file (conventionally with the .amem extension):¶

amem-export = {
  1 => uint,              ; export_version (this document: 1)
  2 => vault-public,      ; salt, public keys, wrapped scope
                          ;   KEKs, accepted author keys
  3 => [* bstr],          ; sealed-objects (encoded)
  4 => {* bstr => bstr},  ; object id => wrapped DEK
}
vault-public = {
  "salt" => bstr .size 16,
  "sign_pub" => bstr .size 32,
  "ka_pub" => bstr .size 32,
  "scopes" => {* tstr => scope-entry },
  ? "known_keys" => {* tstr => bstr .size 32 },
                          ; accepted third-party author keys:
                          ;   hex key_id => Ed25519 public key
}
scope-entry = {
  "scope_id" => bstr .size 16,
  "kek_wrapped" => bstr,
  "eph_pub" => bstr .size 32,
}

The container holds only public keys, wrapped keys, and sealed objects; it is therefore safe to transport over untrusted channels. Possession of the file plus the user's passphrase is sufficient to reconstruct the entire memory on a new device.¶

Two rules govern reading a container:¶

• Failures MUST be isolated per object. One hostile or corrupt object must never prevent the rest of the container from being read: a container-wide failure is a denial of service on the user's entire memory. A corrupt container that cannot be parsed at all MUST produce a clean, single error rather than leak parser internals.¶
• The set of accepted third-party author keys travels in the container metadata (known_keys) and is what makes an attested object resolve to trust "trusted" after import. With an empty or absent set, the same objects MUST degrade to "unverified" (Section 6).¶

11. Consumer Behaviour

Interoperability requires more than parseability. A Consumer claiming full conformance MUST take the type, confidence, creation time, and scope of memory objects into account when selecting which objects to surface to an AI system, and SHOULD prefer higher confidence and more recent objects when context is limited -- subject to the validation rule of Section 8.3 on out-of-range confidence.¶

Consumers MUST apply the derivation rules of Section 6 and the boundary rules of Section 8.3 whenever memory content is surfaced to an AI system.¶

12. Legacy Objects (format_version 1)

format_version 1 objects carry neither binding: their signature proves only internal consistency, and their envelope is unauthenticated. They MUST NOT be reported as verified. They MAY be read under the same explicit opt-in as any unauthenticated object, always as trust "unverified" (test vector 009), and SHOULD be re-sealed by migration.¶

Re-sealing follows Section 8.1: only objects whose authorship can be proven under a key the reader accepts may be re-sealed without a Custody Record.¶

13. Versioning and Extensibility

The format_version field governs breaking changes, and is protected against downgrade by the envelope binding (Section 5.1). Additive changes use new integer keys in memory-payload or the reserved extensions map; implementations MUST preserve unrecognised keys byte for byte when re-encoding, so that older tools do not destroy data written by newer tools.¶

14. Implementation Status

This section is to be removed before publishing as an RFC.¶

This section records the status of known implementations of the format defined by this specification, per the process in [RFC7942]. Listing here does not imply endorsement.¶

Python (reference implementation)

Package "apertomemory" on PyPI, version 0.2.1; source at https://github.com/apertomemory/apertomemory. MIT licence. Coverage: complete (key hierarchy, seal/open with both bindings, trust derivation, custody records, migration, scopes, vault, export/import container, MCP adapter). Generates the format_version 2 test-vector set and conforms to all fourteen vectors, including the six refusal cases.¶

TypeScript

Package "apertomemory" for npm, version 0.2.1; source at https://github.com/apertomemory/apertomemory-js. MIT licence. Runs on Node.js 20+ and in browsers; no native code. Conforms to all fourteen format_version 2 vectors, including the six refusal cases; interoperability with the Python implementation verified in both directions.¶

15. Security Considerations

16. Privacy Considerations

Erasure of an individual object is achieved by destroying its wrapped DEK (cryptographic erasure); the sealed blob becomes permanently unreadable even if retained by append-only storage. This provides a technical mechanism for erasure obligations such as those in data protection regulation.¶

The export container is itself a data portability mechanism: it gives users a complete, machine-readable, provider-independent copy of their AI memory, aligned with portability rights such as Article 20 of the GDPR.¶

17. IANA Considerations

This document requests registration of the following media type in the "Media Types" registry, per [RFC6838]:¶

Type name:

application¶

Subtype name:

amem+cbor¶

Required parameters:

N/A¶

Optional parameters:

N/A¶

Encoding considerations:

binary (CBOR)¶

Security considerations:

See the Security Considerations section of this document. Content is client-side encrypted and signed; the container carries no cleartext user data.¶

Interoperability considerations:

Deterministic CBOR encoding per RFC 8949, Section 4.2.¶

Published specification:

This document.¶

Applications that use this media type:

AI memory producers and consumers implementing the ApertoMemory format.¶

Fragment identifier considerations:

N/A¶

Additional information:

File extension: .amem; Macintosh file type code: none.¶

Person and email address to contact:

Andrea Ferro <irn@irn3.com>¶

Intended usage:

COMMON¶

Restrictions on usage:

None¶

Author/Change controller:

IETF¶

Appendix A. Test Vectors

The normative conformance artefact for format_version 2 is the machine-readable vector set [VECTORS], generated by the reference implementation. An implementation is conformant if it reproduces the byte strings of the positive vectors AND refuses every case marked as a refusal. Six of the fourteen vectors are refusal cases (marked * below).¶

Test vectors 001 and 002 of the previous revisions remain valid for the key hierarchy, which is unchanged; their inlined values appear in draft-ferro-apertomemory-01.¶

Acknowledgments

The memory-type taxonomy (episodic, semantic, procedural) follows established cognitive-science terminology also adopted by other AI memory efforts.¶

The author thanks Valentina Tognizioli, not only for what she did, but for who she is. Watching how she used and shaped AI agents in her everyday work sparked the idea for this format. But her real contribution is harder to cite: a way of seeing things differently, of noticing what matters, of never giving up. It changed how the author approaches his own work. Every page of this document carries a trace of her. Without her, none of this would exist.¶

Changes from draft-ferro-apertomemory-01

• Specified format_version 2, closing the forgeable-provenance defect of format_version 1 (GHSA-jwrj-j847-ph54): envelope binding and author binding via COSE external_aad, with a kid consistency rule.¶
• Trust is now derived from which key verified the signature, at read time, fail-closed; the payload trust-level field is informational only.¶
• Added Custody Records (payload key 20) for re-sealed objects, with the resolution table and the custodian-only attestation rule.¶
• Added the Conversion Paths Between Trust Levels section: migration semantics (migrate / attribute / refuse, with quarantine), hardened import, and the AI-boundary rules.¶
• Added a Conformance section separating Producer and Consumer obligations; documented reserved fields explicitly.¶
• Replaced the inline test vectors with the machine-readable format_version 2 vector set (fourteen vectors, six refusal cases) as the normative conformance artefact.¶
• Container: documented known_keys in vault-public and the two container-reading rules (per-object failure isolation; accepted keys travel with the container).¶
• Security Considerations: added Offline Verification Oracle and Residual and Accepted Risks; updated the threat model for tamper detection.¶
• Implementations of -00 and -01 do NOT remain conforming. This is a deliberate breaking change on a security boundary.¶

Author's Address