Memory Portability Spec v1

Status: Draft v1 Release: v0.6.3.1 Encodings: JSON + TOON Round-trip: guaranteed

The Memory Portability Spec defines a stable export envelope so any ai-memory deployment can produce data that any other deployment can consume without loss. This page is a summary; the normative document is in the repo at docs/spec/v1.md.

Read the full spec → Browse the canonical schema →

Why portability v1 exists

1. Operators can move a store from machine A to machine B without losing embeddings or rerunning mining.
2. Third parties can write tools (diff, audit, archive) that consume the envelope rather than scraping live SQLite.
3. Round-trip guarantee: ai-memory export | ai-memory import produces a byte-equivalent store under --preserve-timestamps.

Envelope at a glance

{
  "schema_version": "v1",
  "source": "ai-memory-v0.6.3.1",
  "exported_at": "2026-04-29T12:00:00.000Z",
  "db_schema_version": 17,
  "namespaces":    [...],
  "memories":      [...],
  "links":         [...],
  "archived":      [...],
  "agents":        [...],
  "entities":      [...],
  "subscriptions": [...]   // secrets stripped
}

Embedding encoding

Embeddings are base64(magic_byte || raw_LE_f32_bytes). The magic byte (introduced in migration v17) declares the byte order:

Magic	Meaning	Reader behaviour
0x01	Little-endian f32	Accept
0x02	Big-endian f32	Reject (until v0.7)
(no header)	Legacy LE-f32	Accept (one major version)
any other	Unknown	Reject with EmbeddingFormatError

Conformance

• Producer-conformant — emits the v1 envelope correctly.
• Consumer-conformant — accepts any v1 envelope, preserves unknown fields.
• Round-trip-conformant — both, with byte-equivalence under --preserve-timestamps.

ai-memory v0.6.3.1 is producer- and consumer-conformant. Round-trip is demonstrated by the test plan in spec §10.

Out of scope for v1

• Multi-implementation interop (v2.0 — ROADMAP §7.6).
• Federation identity attestation (v0.7).
• Big-endian conversion (v0.7).
• Streaming exports / encrypted envelope (v2).

---

Companion artifact: the LongMemEval variant disclosure (4 rows: keyword baseline + semantic-rerank-on/off + autonomous-curator-on) landed alongside this spec in v0.6.3.1 P8.