# MemoryAI Protocol v1

> **Status:** Working Draft (informational)
> **Editor:** Vu Duc Minh, MemoryAI
> **First published:** 2026-05-28
> **License:** This spec is published under CC BY 4.0. Reference implementation
> at `server/engine/brain_export/` is MIT-licensed.

## Abstract

The **MemoryAI Protocol v1** defines an interchange format for *agent
memory* — the persistent identity, preferences, decisions, and learned
context that any AI agent accumulates over time. The goal is a vendor-neutral
container so a user's brain can move between cloud services, on-prem
installations, and third-party implementations without lock-in.

This document specifies:

1. The **Bundle Format** — a self-contained JSON document representing a
   complete or partial brain.
2. The **HTTP Profile** — the wire endpoints any conforming implementation
   should expose.
3. **Conformance levels** — what implementers must, should, and may support.

The reference implementation is open-source (MIT) at
`server/engine/brain_export/` in the MemoryAI repository. Anyone may
implement this protocol without permission. The name "MemoryAI Protocol"
is a trademark of MemoryAI; conforming implementations should describe
themselves as "MemoryAI-Protocol-compatible" rather than "MemoryAI."

---

## 1. Why a protocol

In 2026, every major LLM vendor is shipping memory features (Anthropic
Projects + Memory, ChatGPT Memory, Gemini Personalization, …). Each
implementation locks the user's identity to that vendor's storage.

The **MemoryAI Protocol v1** decouples three concerns:

| Layer | Concern | Today |
|------:|---------|-------|
| Encoding | What memory looks like on disk | One JSON schema per vendor |
| Transport | How brains move between systems | None — vendors don't export |
| Reasoning | How memory gets recalled and used | Tightly coupled to vendor LLM |

A protocol that locks down only the **encoding + transport layers** lets
the reasoning layer stay competitive between vendors. The user owns the
brain; vendors compete on quality.

This mirrors the historical pattern: HTTP didn't dictate how websites
should look, but it standardized how content moved between client and
server. Browsers competed on rendering. The MemoryAI Protocol aspires to
that role for AI memory.

---

## 2. Terminology

The key words MUST, SHOULD, MAY follow [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).

- **Brain** — the complete memory state of one identity (typically one user
  or one organizational tenant).
- **Chunk** — a single memory unit (one fact, decision, preference, etc.).
- **DNA chunk** — a chunk of `memory_type` ∈
  `{preference, decision, identity, pitfall, procedure}` that conforming
  implementations MUST NOT auto-decay or auto-delete.
- **Bundle** — a single JSON document containing some slice of a Brain.
- **Implementation** — any system that produces or consumes Bundles.
- **Producer** — an implementation that exports Bundles.
- **Consumer** — an implementation that imports Bundles.

---

## 3. Bundle Format v1

A Bundle is a single JSON document with this top-level shape:

```json
{
  "format": "memoryai-bundle",
  "version": 1,
  "generator": "<implementation-name>/<version>",
  "exported_at": "<ISO-8601 datetime>",

  "manifest": {
    "tenant_id":      "<uuid|null>",
    "tenant_name":    "<string|null>",
    "tenant_plan":    "<string|null>",
    "scope":          "full" | "dna_only" | "since",
    "since":          "<ISO-8601 datetime|null>",
    "embedding_model": "<string>",
    "embedding_dim":   <integer>,
    "counts":         { "chunks": N, "memory_edges": N, ... },
    "checksum":       "<sha256 hex of canonical body>"
  },

  "chunks":        [ChunkRecord, ...],
  "memory_edges":  [EdgeRecord, ...],
  "entities":      [EntityRecord, ...],
  "l2_sessions":   [L2SessionRecord, ...],
  "mood_states":   [MoodRecord, ...],
  "agents":        [AgentRecord, ...]
}
```

### 3.1 Required envelope fields

A valid Bundle MUST contain `format`, `version`, and `manifest`. The
`format` field MUST equal the literal string `"memoryai-bundle"`. The
`version` field MUST be an integer ≥ 1. The `manifest` object MUST
contain `scope`, `embedding_model`, and `embedding_dim`.

A consumer MUST reject a Bundle whose `version` is greater than the
maximum it supports.

### 3.2 ChunkRecord

```json
{
  "id":             <integer>,
  "content":        "<string>",         (REQUIRED)
  "content_hash":   "<sha256 hex>",
  "memory_type":    "<string>",         (REQUIRED, see § 3.7)
  "embedding":      "<base64 float32 array | null>",
  "embedding_model": "<string>",
  "tags":           [<string>, ...],
  "zone":           "standard" | "important" | "critical" | "ephemeral",
  "importance":     <float 0..1>,
  "is_pinned":      <bool>,
  "decay_score":    <float 0..1>,
  "tier":           "hot" | "warm" | "cold",
  "created_at":     "<ISO-8601>",
  "accessed_at":    "<ISO-8601>",
  "valid_until":    "<ISO-8601 | null>",
  "metadata":       <object>
}
```

### 3.3 EdgeRecord (Hebbian graph)

```json
{ "chunk_a": <int>, "chunk_b": <int>, "edge_type": "<string>",
  "weight":  <float>, "co_activation_count": <int>,
  "created_at": "<ISO-8601>", "updated_at": "<ISO-8601>" }
```

### 3.4 EntityRecord

```json
{ "name":         "<string>",      (REQUIRED)
  "frequency":    <int>,
  "first_seen":   "<ISO-8601>",
  "last_seen":    "<ISO-8601>",
  "is_dna":       <bool> }
```

### 3.5 Embedding encoding

`embedding` fields MUST be one of:

- `null` — embedding not transmitted (consumer re-embeds lazily)
- A **base64-encoded** little-endian array of `float32` values.
  The array length MUST equal `manifest.embedding_dim`.

When the consumer's local `embedding_model` differs from the manifest's,
the consumer SHOULD drop embeddings (use `null`) and re-embed lazily on
next recall. The consumer MAY accept embeddings from a different model
when explicit user opt-in is given, but reject is the safe default.

### 3.6 Checksum

`manifest.checksum` is the SHA-256 hex digest of:

1. The Bundle with `manifest.checksum` removed.
2. Serialized as JSON with sorted keys, no whitespace.
3. Encoded as UTF-8.

A consumer SHOULD verify the checksum on import and warn (not reject) on
mismatch.

### 3.7 Memory types

Conforming implementations MUST recognize at least these `memory_type`
values; they MAY define additional vendor-specific values prefixed with
`x_`:

- `fact` — general information, may decay
- `episodic` — conversation events, may decay
- `goal` — active objectives, may decay
- `error` — failures, may decay
- `preference` — DNA, MUST NOT decay
- `decision` — DNA, MUST NOT decay
- `identity` — DNA, MUST NOT decay
- `pitfall` — DNA, MUST NOT decay (failure-to-avoid memory)
- `procedure` — DNA, MUST NOT decay (learned workflow)
- `life_event` — high-importance event, MAY have soft-invalidation rules

DNA chunks are recognized by either `memory_type ∈ {preference, decision,
identity, pitfall, procedure}`, or `zone ∈ {critical, important}`, or
`is_pinned = true`. Any of these conditions are sufficient.

### 3.8 Idempotency rules (Consumer side)

A Consumer importing a Bundle MUST:

1. Skip chunks whose `content_hash` already exists in the target tenant
   (no duplicate insert; the existing row is preserved).
2. UPSERT memory_edges on `(source, target, edge_type)` — accumulate
   `co_activation_count`, take MAX of `weight`, refresh `updated_at`.
3. UPSERT entities on `(tenant_id, entity_name)` — accumulate `frequency`,
   take latest `last_seen`, OR `is_dna`.

The Consumer MUST NOT modify the source tenant's `tenant_id`. The Bundle's
manifest `tenant_id` is informational only; the Consumer assigns its own.

---

## 4. HTTP Profile (RECOMMENDED)

Conforming HTTP implementations SHOULD expose at least:

| Method | Path | Body | Returns |
|--------|------|------|---------|
| `POST` | `/v1/brain/export`  | `{scope, since?}` | Bundle |
| `POST` | `/v1/brain/export/stream` | same | NDJSON stream |
| `POST` | `/v1/brain/import`  | Bundle | `ImportReport` |
| `POST` | `/v1/brain/import/file` | multipart | `ImportReport` |
| `GET`  | `/v1/spec`          | — | this protocol document |

`ImportReport` shape:
```json
{ "success": bool,
  "report": {
    "bundle_format":  "<string>",
    "bundle_version": <int>,
    "embedding_model_match": <bool>,
    "chunks":        { "inserted": N, "skipped_duplicate": N, "skipped_invalid": N },
    "memory_edges":  { "upserted": N, "skipped": N },
    "entities":      { "upserted": N },
    "l2_sessions":   { "inserted": N },
    "mood_states":   { "upserted": N },
    "agents":        { "upserted": N },
    "warnings":      [<string>, ...]
} }
```

Authentication and rate limiting are out of scope of this spec.

---

## 5. Conformance levels

### Level 1 — **Producer**

An implementation MAY claim Producer conformance if it can emit a
Bundle that:

- passes the envelope check in § 3.1
- correctly encodes embeddings per § 3.5
- includes a valid `checksum` per § 3.6
- declares accurate `manifest.counts`

### Level 2 — **Consumer**

An implementation MAY claim Consumer conformance if it can ingest any
spec-conformant Bundle and:

- enforce idempotency rules in § 3.8
- enforce DNA-protection rules in § 3.7
- handle embedding model mismatch per § 3.5

### Level 3 — **Bidirectional**

An implementation that satisfies Levels 1 + 2 AND can round-trip a
Bundle (export → import → re-export) producing an equivalent Bundle
(same `chunks` set by `content_hash`, same `entities` by name) MAY
claim Bidirectional conformance.

The MemoryAI cloud implementation passes Level 3. The reference E2E
test suite (`tests/test_brain_export_e2e.py` in the MemoryAI repo) is
the canonical conformance test.

---

## 6. Security considerations

- Bundles MUST NOT include API keys, audit logs, or other credentials.
- Producers MUST NOT export memory data the user has marked deleted.
- Consumers MUST treat bundle content as untrusted input (sanitize for
  prompt injection on chunks before downstream LLM use).
- Bundle filenames SHOULD use `.json` extension. `.memoryai` is reserved
  but not yet standardized.

---

## 7. Versioning

This document is **MemoryAI Protocol v1**. Future versions will:

- Bump the `version` field in the envelope.
- Maintain backward compatibility for one major version.
- Be published under the same URL pattern (`memoryai.dev/spec/v2`, etc.).

A future v2 may add: chunk_deltas (provenance chain), entity_relationships
(typed graph), personality records, trust graph snapshots, federated
brain references.

---

## 8. Reference implementation

- `server/engine/brain_export/schema.py` — envelope validator + constants
- `server/engine/brain_export/exporter.py` — Bundle producer
- `server/engine/brain_export/importer.py` — Bundle consumer
- `server/routes/brain_export.py` — HTTP endpoints
- `tests/test_brain_export.py` — unit tests
- `tests/test_brain_export_e2e.py` — round-trip conformance tests

All under MIT license. Pull requests welcome at
[github.com/CH270035/memoryai](https://github.com/CH270035/memoryai).

---

## Acknowledgments

The 3 DNA lines that motivate this protocol are documented in
`architecture/PROJECT_DNA.md`. DNA #3 — *"Brain belongs to the user, not
to any one vendor"* — is the protocol's reason for existing.