@avee1234/memport 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abhi Das
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# memport
+
+[![CI](https://github.com/abhid1234/memport/actions/workflows/ci.yml/badge.svg)](https://github.com/abhid1234/memport/actions/workflows/ci.yml) [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) ![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)
+
+**[▶ Play with it live →](https://memport.vercel.app)** · export → import → conformance round-trip on the real library, in your browser.
+
+**The open, portable format for AI agent memory.** Export memory from any store, import it into any harness. Zero dependencies.
+
+> Working name — the concept was queued as "openmemory," but that collides with Mem0's shipping product, so this is deliberately differentiated. See [`vision.md`](vision.md).
+
+Agent memory today is locked in: Mem0 keeps it in its cloud, Zep in a proprietary graph, and every harness in its own private store. There's no vendor-neutral way to move, back up, or audit what an agent remembers. memport is the thin open layer *between* stores — a format, not another backend.
+
+```bash
+memport export --from ./mem-store        # any store → the neutral .memport format
+memport import --to  ./other-store        # .memport → any target store
+memport conformance a.memport b.memport   # how much memory survived the round-trip?
+memport diff a.memport b.memport          # what was added / dropped / changed
+```
+
+Same playbook as [opentrajectory](https://github.com/abhid1234/opentrajectory) (format for agent traces) and [constraintguard](https://github.com/abhid1234/constraintguard) (format for constraints): own the open interoperability standard, not the storage.
+
+Status: **drafting** — see [`roadmap.md`](roadmap.md). Grounded in the memory-portability gap (arXiv:2605.11032).
+
+MIT · zero dependencies · harness-neutral

package/bin/memport.js

@@ -0,0 +1,377 @@
+#!/usr/bin/env node
+// memport CLI — a thin subcommand dispatcher. `validate`, `export`, `import`,
+// and `conformance` today; new subcommands slot in without a rewrite.
+//
+//   memport validate <file> [--json]
+//   memport export --from <dir-or-file> [--to <file>] [--adapter <name>]
+//   memport import --from <set-file> --to <target> [--adapter <name>] [--mode merge|replace|fail] [--json]
+//   memport conformance <before.memport> <after.memport> [--json] [--min <0..1>]
+//
+// Exit codes:
+//   0 — success (input valid / export written / import written / scored)
+//   1 — input parsed but failed validation (validate, export's produced set,
+//       import's input set, conformance's input sets), or `--mode fail` blocked
+//       by a non-empty target, or a `--min` gate the `score` fell short of
+//   2 — usage/IO error: no path, unknown subcommand, file not found, invalid JSON
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import {
+  validateMemoryRecord,
+  validateMemorySet,
+  exportMemory,
+  ExportError,
+  importMemory,
+  ImportError,
+  scoreConformance,
+  ConformanceError,
+} from '../src/index.js';
+
+const USAGE = [
+  'usage: memport validate <file> [--json]',
+  '       memport export --from <dir-or-file> [--to <file>] [--adapter <name>]',
+  '       memport import --from <set-file> --to <target> [--adapter <name>] [--mode merge|replace|fail] [--json]',
+  '       memport conformance <before.memport> <after.memport> [--json] [--min <0..1>]',
+].join('\n');
+
+function fail(message, code) {
+  process.stderr.write(`${message}\n`);
+  process.exit(code);
+}
+
+function runValidate(args) {
+  const json = args.includes('--json');
+  const paths = args.filter((a) => a !== '--json');
+
+  if (paths.length === 0) {
+    fail(`error: no file given\n${USAGE}`, 2);
+  }
+  const file = paths[0];
+
+  let raw;
+  try {
+    raw = readFileSync(file, 'utf8');
+  } catch {
+    fail(`error: cannot read file: ${file}`, 2);
+  }
+
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (e) {
+    fail(`error: invalid JSON in ${file}: ${e.message}`, 2);
+  }
+
+  const isSet = Array.isArray(data);
+  const result = isSet ? validateMemorySet(data) : validateMemoryRecord(data);
+
+  if (json) {
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    process.exit(result.valid ? 0 : 1);
+  }
+
+  if (result.valid) {
+    const count = isSet ? data.length : 1;
+    process.stdout.write(`✓ valid (${count} record${count === 1 ? '' : 's'})\n`);
+    process.exit(0);
+  }
+
+  process.stdout.write(`✗ invalid (${result.errors.length} error${result.errors.length === 1 ? '' : 's'})\n`);
+  result.errors.forEach((e, i) => {
+    const loc = e.index !== undefined ? `[${e.index}]${e.path ? '.' + e.path : ''}` : e.path || '(record)';
+    process.stdout.write(`  ${i + 1}. ${loc} — ${e.message}\n`);
+  });
+  process.exit(1);
+}
+
+// Parse `--flag value` options; returns { from, to, adapter } (undefined if
+// absent). Unknown flags and a missing value are usage errors.
+function parseExportArgs(args) {
+  const opts = {};
+  const known = { '--from': 'from', '--to': 'to', '--adapter': 'adapter' };
+  for (let i = 0; i < args.length; i++) {
+    const key = known[args[i]];
+    if (!key) fail(`error: unknown option: ${args[i]}\n${USAGE}`, 2);
+    const value = args[i + 1];
+    if (value === undefined || value.startsWith('--')) {
+      fail(`error: ${args[i]} requires a value\n${USAGE}`, 2);
+    }
+    opts[key] = value;
+    i++;
+  }
+  return opts;
+}
+
+function runExport(args) {
+  const { from, to, adapter } = parseExportArgs(args);
+
+  if (!from) {
+    fail(`error: --from is required\n${USAGE}`, 2);
+  }
+
+  let set;
+  try {
+    set = exportMemory(from, adapter ? { adapter } : {});
+  } catch (e) {
+    if (e instanceof ExportError && e.code === 'invalid_set') {
+      // The source produced an invalid set — print the #1 errors, write nothing.
+      process.stdout.write(`✗ export produced an invalid memory set (${e.errors.length} error${e.errors.length === 1 ? '' : 's'})\n`);
+      e.errors.forEach((err, i) => {
+        const loc = err.index !== undefined ? `[${err.index}]${err.path ? '.' + err.path : ''}` : err.path || '(record)';
+        process.stdout.write(`  ${i + 1}. ${loc} — ${err.message}\n`);
+      });
+      process.exit(1);
+    }
+    // unknown_adapter / source_not_found / invalid_json — usage/IO errors.
+    fail(`error: ${e.message}`, 2);
+  }
+
+  const output = `${JSON.stringify(set, null, 2)}\n`;
+
+  if (to) {
+    try {
+      writeFileSync(to, output);
+    } catch (e) {
+      fail(`error: cannot write file: ${to}: ${e.message}`, 2);
+    }
+    process.stderr.write(`✓ exported ${set.length} record${set.length === 1 ? '' : 's'} → ${to}\n`);
+  } else {
+    process.stdout.write(output);
+  }
+  process.exit(0);
+}
+
+// Print the #1 structured errors under a header line (shared by validate,
+// export's invalid-output path, and import's invalid-input path).
+function printErrors(header, errors) {
+  process.stdout.write(`${header} (${errors.length} error${errors.length === 1 ? '' : 's'})\n`);
+  errors.forEach((e, i) => {
+    const loc = e.index !== undefined ? `[${e.index}]${e.path ? '.' + e.path : ''}` : e.path || '(record)';
+    process.stdout.write(`  ${i + 1}. ${loc} — ${e.message}\n`);
+  });
+}
+
+// Parse `--flag value` options for import; adds `--mode` and the boolean
+// `--json` on top of export's `--from/--to/--adapter`.
+function parseImportArgs(args) {
+  const opts = {};
+  const known = { '--from': 'from', '--to': 'to', '--adapter': 'adapter', '--mode': 'mode' };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--json') {
+      opts.json = true;
+      continue;
+    }
+    const key = known[args[i]];
+    if (!key) fail(`error: unknown option: ${args[i]}\n${USAGE}`, 2);
+    const value = args[i + 1];
+    if (value === undefined || value.startsWith('--')) {
+      fail(`error: ${args[i]} requires a value\n${USAGE}`, 2);
+    }
+    opts[key] = value;
+    i++;
+  }
+  return opts;
+}
+
+function runImport(args) {
+  const { from, to, adapter, mode, json } = parseImportArgs(args);
+
+  if (!from) fail(`error: --from is required\n${USAGE}`, 2);
+  if (!to) fail(`error: --to is required\n${USAGE}`, 2);
+
+  // Load the set from --from. It must parse to a JSON array; a non-array (or
+  // unreadable / unparseable) source is a usage error (exit 2). The array's
+  // contents are validated inside importMemory.
+  let raw;
+  try {
+    raw = readFileSync(from, 'utf8');
+  } catch {
+    fail(`error: cannot read file: ${from}`, 2);
+  }
+  let set;
+  try {
+    set = JSON.parse(raw);
+  } catch (e) {
+    fail(`error: invalid JSON in ${from}: ${e.message}`, 2);
+  }
+  if (!Array.isArray(set)) {
+    fail(`error: ${from} must contain a memory set (a JSON array of records)`, 2);
+  }
+
+  const opts = {};
+  if (adapter) opts.adapter = adapter;
+  if (mode) opts.mode = mode;
+
+  let report;
+  try {
+    report = importMemory(set, to, opts);
+  } catch (e) {
+    if (e instanceof ImportError && e.code === 'invalid_set') {
+      // The input set failed validation — print the #1 errors, write nothing.
+      printErrors('✗ import received an invalid memory set', e.errors);
+      process.exit(1);
+    }
+    if (e instanceof ImportError && e.code === 'target_not_empty') {
+      // --mode fail blocked by a non-empty target — nothing written.
+      fail(`error: ${e.message}`, 1);
+    }
+    // unknown_adapter / unknown_mode / target_is_directory / write_failed /
+    // invalid_json — usage/IO errors.
+    if (e instanceof ImportError) fail(`error: ${e.message}`, 2);
+    throw e;
+  }
+
+  if (json) {
+    process.stdout.write(`${JSON.stringify(report)}\n`);
+    process.exit(0);
+  }
+
+  process.stderr.write(
+    `✓ imported ${report.written} record${report.written === 1 ? '' : 's'} ` +
+      `(${report.skipped} skipped, ${report.unsupported.length} unsupported) → ${to}\n`,
+  );
+  process.exit(0);
+}
+
+// Parse `conformance`'s two positional file paths plus the boolean `--json`
+// and the valued `--min`. Positionals (file paths) and `--flag`s can interleave;
+// an unknown option, a missing `--min` value, or the wrong positional count are
+// usage errors caught here or by the caller.
+function parseConformanceArgs(args) {
+  const positionals = [];
+  const opts = { json: false };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--json') {
+      opts.json = true;
+    } else if (arg === '--min') {
+      const value = args[i + 1];
+      if (value === undefined || value.startsWith('--')) {
+        fail(`error: --min requires a value\n${USAGE}`, 2);
+      }
+      opts.min = value;
+      i++;
+    } else if (arg.startsWith('--')) {
+      fail(`error: unknown option: ${arg}\n${USAGE}`, 2);
+    } else {
+      positionals.push(arg);
+    }
+  }
+  return { positionals, opts };
+}
+
+// Load a memport set file for conformance: readable, parseable JSON, and a JSON
+// array. Its records are validated inside `scoreConformance`. Anything else is a
+// usage/IO error (exit 2).
+function loadSetFile(file) {
+  let raw;
+  try {
+    raw = readFileSync(file, 'utf8');
+  } catch {
+    fail(`error: cannot read file: ${file}`, 2);
+  }
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (e) {
+    fail(`error: invalid JSON in ${file}: ${e.message}`, 2);
+  }
+  if (!Array.isArray(data)) {
+    fail(`error: ${file} must contain a memory set (a JSON array of records)`, 2);
+  }
+  return data;
+}
+
+function runConformance(args) {
+  const { positionals, opts } = parseConformanceArgs(args);
+
+  if (positionals.length !== 2) {
+    fail(`error: conformance takes exactly two files: <before> <after>\n${USAGE}`, 2);
+  }
+  const [beforeFile, afterFile] = positionals;
+
+  // Optional `--min` CI gate: a float in [0, 1]. A non-numeric or out-of-range
+  // value is a usage error (exit 2), distinct from the gate itself failing.
+  let min;
+  if (opts.min !== undefined) {
+    min = Number(opts.min);
+    if (!Number.isFinite(min) || min < 0 || min > 1) {
+      fail(`error: --min must be a number in [0, 1], got: ${opts.min}\n${USAGE}`, 2);
+    }
+  }
+
+  const before = loadSetFile(beforeFile);
+  const after = loadSetFile(afterFile);
+
+  let report;
+  try {
+    report = scoreConformance(before, after);
+  } catch (e) {
+    if (e instanceof ConformanceError && e.code === 'invalid_set') {
+      // An input set failed validation — print the #1 errors naming the side/file.
+      const file = e.side === 'before' ? beforeFile : afterFile;
+      printErrors(`✗ ${e.side} set is invalid (${file})`, e.errors);
+      process.exit(1);
+    }
+    if (e instanceof ConformanceError) fail(`error: ${e.message}`, 2);
+    throw e;
+  }
+
+  const gatePassed = min === undefined || report.score >= min;
+
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(report)}\n`);
+    process.exit(gatePassed ? 0 : 1);
+  }
+
+  const pct = (report.score * 100).toFixed(1);
+  const mark = report.score === 1 || gatePassed ? '✓' : '✗';
+  process.stdout.write(
+    `${mark} conformance ${pct}% (${report.preserved}/${report.total} preserved, ` +
+      `${report.degraded.length} degraded, ${report.lost.length} lost)\n`,
+  );
+
+  if (report.lost.length > 0) {
+    process.stdout.write(`lost (${report.lost.length}):\n`);
+    for (const r of report.lost) {
+      process.stdout.write(`  - ${r.id} (${r.kind}) — "${r.content}"\n`);
+    }
+  }
+  if (report.degraded.length > 0) {
+    process.stdout.write(`degraded (${report.degraded.length}):\n`);
+    for (const r of report.degraded) {
+      process.stdout.write(`  - ${r.id} — ${r.fields.join(', ')}\n`);
+    }
+  }
+
+  if (!gatePassed) {
+    process.stderr.write(
+      `error: conformance ${pct}% is below the --min ${(min * 100).toFixed(1)}% threshold\n`,
+    );
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+function main() {
+  const [subcommand, ...rest] = process.argv.slice(2);
+
+  switch (subcommand) {
+    case 'validate':
+      return runValidate(rest);
+    case 'export':
+      return runExport(rest);
+    case 'import':
+      return runImport(rest);
+    case 'conformance':
+      return runConformance(rest);
+    default:
+      fail(
+        subcommand
+          ? `error: unknown subcommand: ${subcommand}\n${USAGE}`
+          : USAGE,
+        2,
+      );
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@avee1234/memport",
+  "version": "0.1.0",
+  "description": "The open, portable format for AI agent memory — export from any store, import into any harness. Zero dependencies.",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "memport": "bin/memport.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "copy:lib": "node site/sync-lib.mjs"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "memory",
+    "portability",
+    "interoperability",
+    "schema",
+    "mem0",
+    "open-format",
+    "conformance",
+    "zero-dependency"
+  ],
+  "license": "MIT",
+  "homepage": "https://memport.vercel.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abhid1234/memport.git"
+  },
+  "bugs": {
+    "url": "https://github.com/abhid1234/memport/issues"
+  }
+}