memvelope

An open standard for taking your AI chat history with you. Memvelope turns a ChatGPT or Claude export into one deterministic JSON file you own, and gives distilled memory a machine-checkable shape. MIT licensed, zero dependencies.

Converting an export is fully local. It reads off disk and makes no network requests. There is no network path in this package at all - nothing is uploaded, and nothing is fetched.

The spec is served at memvelope.com/spec. The browser converter at memvelope.com runs the same code this package ships.

Two layers:

• envelope-v0 is the lossless archive. Your full export, normalized into one JSON file. The envelope is a pure function of the export, so the same input produces the same bytes every time. Conformance is an exact diff.
• memvelope-ir-v0 is the distilled-facts layer. Eight keys per fact, explicit nulls, validated against a published JSON Schema.

Install

npm install -g memvelope

Or run it without installing via npx. Node 18 or newer. No dependencies.

Convert an export

npx memvelope conversations.json

Detects the provider, walks the conversation tree, writes <provider>-<latest-date>.mve.json. Prints a one-line receipt: conversations read, kept, skipped, messages, output size, elapsed.

ChatGPT exports can split across numbered files. Pass them all, or the folder, and they merge into one envelope:

npx memvelope conversations-000.json conversations-001.json -o me.mve.json
npx memvelope ./my-export-folder

The CLI streams the export off disk, so it handles files past the browser's ~200MB cap. A multi-hundred-MB export converts in seconds. Nothing is uploaded anywhere - there is no code path that could.

Validate a facts document

The package ships a zero-dependency conformance checker and its fixture corpus:

node node_modules/memvelope/fixtures/ir/validate-ir.mjs facts.mv.json

Run it with no arguments from inside the package directory and it exercises the bundled corpus - documents under valid/ must validate, documents under invalid/ must not. The schema itself is served at memvelope.com/schema/memvelope-ir-v0.schema.json.

Use it as a library

import { readFileSync } from 'node:fs';
import { convertExport } from 'memvelope';

// One array per input file, so a split ChatGPT export is just more entries.
const result = convertExport([JSON.parse(readFileSync('conversations.json', 'utf8'))]);
if (!result.ok) throw new Error(result.error);

console.log(result.provider, result.envelope.conversations.length);

public/converter.js is the reference implementation of the envelope-v0 mapping. Its pure functions run identically in the browser and under plain Node - no bundler, no dependencies. convertExport takes an array of parsed exports, one entry per file, and returns {ok, envelope, provider, skipped}. It reports bad input by returning {ok: false, error} rather than throwing, so check ok before reading envelope. Passing a single parsed export directly instead of wrapping it in an array is the easy mistake: it yields {ok: false} and no exception. detectProvider is exported alongside it.

Conformance fixtures

The repo carries golden fixtures: an input export and the exact envelope it must produce. From a clone:

node fixtures/run.mjs        # reference converter against the goldens
node fixtures/run-cli.mjs    # proves CLI output is byte-identical

A converter in any language is conformant iff it reproduces these envelopes byte-for-byte under the canonical serialization profile in SPEC.md. One fixture is a branched ChatGPT mapping with an abandoned branch - the case the v0.2.0 active-path rule exists for.

What else is in the repo

• SPEC.md - the normative text for both layers, served at /spec
• public/schema/ - both JSON Schemas (draft-07), served under /schema/
• public/ - the static site, including the browser converter
• worker.js - the minimal static-assets worker that serves memvelope.com
• integrations/ - a worked example of writing an envelope reader

The site is a static directory, so there is nothing to deploy in the usual sense - any file server can host public/. worker.js is how memvelope.com itself is served, and that setup is specific to this project's hosting rather than part of the format.

License

MIT. Copyright (c) 2026 Indistinct.