mneme-storage (JavaScript / TypeScript)

Official SDK for Mneme: encrypted file storage on Filecoin. Works in Node.js 20+ and in browsers, with TypeScript types included.

Files are encrypted on your device and sent straight to Filecoin storage providers (2 copies). They never pass through Mneme or any other server.

Install

npm install mneme-storage

Use

Create an API key in the Mneme web app (API Keys), then:

import { Mneme } from 'mneme-storage';

const mneme = new Mneme({ apiKey: 'mnm_live_...' });

const file = await mneme.upload('video.mp4');      // Node: a path. Browser: a File / Blob.
console.log(file.id, file.status);                 // file-42 stored_on_filecoin

await mneme.downloadToFile(file.id, 'copy.mp4');   // Node (streamed)
const blob = await mneme.download(file.id);        // browser or Node
const { files } = await mneme.list();
await mneme.delete(file.id);

| Method | What it does | |---|---| | upload(input, { wait, onProgress, signal }) | Uploads one file. wait: false resolves as soon as the bytes reached Filecoin; Mneme finishes on its own. | | uploadMany(inputs) | Uploads many files in as few uploads as possible (cheaper). | | download(id) / downloadToFile(id, path) / downloadStream(id) | Downloads, checks every chunk, decrypts. | | list({ offset, limit }) | One page of your files (100 at most). | | get(id) · waitUntilStored(id) · delete(id) | Details, wait until stored, delete. | | findByName(name) · findByHash(sha256Hex) | Find your file by its name or by the SHA-256 of its content. | | filecoinInfo(id) | Where the file lives on Filecoin: providers, data sets, piece CIDs. | | account() · storageStats() · listKeys() | Quota and usage, vault totals, your API keys (names only). | | uploadStatus(uploadId) · cancelUpload(uploadId) | State of an upload; cancel one that was started but not finished. Files returned by upload carry their uploadId. |

Errors throw MnemeError (with .status, the HTTP status code).

Mainnet or testnet

The SDK uses mainnet (the live Mneme backend, real Filecoin) by default. network: 'testnet' uses a Mneme test backend running on your computer (npm run local in the Mneme project), which stores on the Filecoin Calibration testnet with free test coins. The same code runs on both:

const mneme = new Mneme({ apiKey: 'mnm_live_...', network: 'testnet' }); // or 'mainnet'

or, without touching the code: export MNEME_NETWORK=testnet. Use an API key from the backend you talk to (the local site's API Keys page for testnet). baseUrl (or MNEME_BASE_URL) points the SDK at any other backend address.

Command line

export MNEME_API_KEY=mnm_live_...
npx mneme-storage upload photo.jpg video.mp4
npx mneme-storage list
npx mneme-storage download FILE_ID out.jpg
npx mneme-storage delete FILE_ID
npx mneme-storage info FILE_ID          # details + where it lives on Filecoin
npx mneme-storage find report.pdf       # also: find-hash, account, stats, keys, upload-status, cancel
npx mneme-storage list --network testnet

Add --json for machine-readable output, --no-wait to return as soon as the bytes reached Filecoin, or --network testnet (or MNEME_NETWORK=testnet) for the testnet.

Uploads count towards your plan exactly like uploads in the web app. Files you upload here open in the web app, and the other way round.