Skip to main content

Your first cartridge

A cartridge is a web app in a window on the Mnemosyne canvas, with your memory as its backend. Empty folder to running cartridge, with an AI agent doing the typing.

What you need​

  1. Mnemosyne OS, open. It owns the vaults and the local gateway. Download it if you have not yet.
  2. Node.js 18 or newer.
  3. A coding agent: Claude Code, Cursor, Copilot, whichever you use.

Step 1: give your agent your memory​

Optional, and it changes the rest. Connect your agent through MCP and it reads the decisions, notes and code you already wrote while it builds.

One config block per client: Connect Claude to Mnemosyne.

tip

MNEMO_VAULTS names the vaults the agent may see. Nothing else is reachable, and vaults under Maximum protection keep their guarantees.

Step 2: the environment prompt​

Open a terminal in an empty folder, start your agent there, and paste this.

Set up a Mnemosyne OS cartridge project for me.

1. Check that Node.js is 18 or newer. Stop and tell me if it is not.
2. Scaffold the official boilerplate into a folder called my-cartridge:
   npx degit Mnemosyne-OS/Mnemosyne-Neural-OS/examples/cartridge-boilerplate my-cartridge
3. From that folder, install and bring the SDK up to date. The template pins an
   old range on purpose, so the second command matters:
   npm install
   npm install @mnemosyne_os/cartridge-sdk@latest
4. Read AGENTS.md at the root of the scaffold, in full, before anything else.
   It is the authoritative build surface: manifest shape, permission
   vocabulary, and the complete list of host actions. Never invent an action
   or an API that is not in it. If a capability is missing from that list, it
   does not exist: say so.
5. Rename the app. In BOTH mnemo-plugin.json and package.json, set "name" to
   @my-handle/my-cartridge. The two files must agree.
6. Run npm run build and confirm it passes.
7. Run npm run dev and leave it serving on 127.0.0.1:5185.

Then stop and tell me what you did. Write no feature code yet.

You get a working cartridge: it claims its own vault, writes and reads memory, calls the host model, and opens a native folder dialog.

Pick the name once

Vault ownership is keyed on the manifest name. Change it later and the next launch creates a fresh vault and abandons the old one, with everything in it.

MnemoHub → My Apps → Dev Dashboard → My dev cartridges → "Link a local cartridge", then pick your my-cartridge folder.

The manifest points at your Vite dev server, so you get hot reload inside the Mnemosyne window.

The first linked cartridge is free. Further slots need an active Engramm license.

Step 4: the build prompt​

Back in your agent, in the project folder:

Build my cartridge in this folder.

What it does: <describe your app in a few sentences>.

Rules:
- Read AGENTS.md in full first. Every host call is
  await sdk.invoke('<action>', payload), and its action table is the only list
  of actions that exists. Do not guess APIs.
- Declare the MINIMUM permissions in mnemo-plugin.json. Over-declaring gets a
  cartridge rejected at review, and vault:write is flagged as sensitive.
- Claim the sandbox vault once at boot, before any write:
  const { vault } = await sdk.ensureSandbox();
  Then always target that vault by name.
- The first call needing a permission opens a native dialog and waits for me to
  click. Keep the boot sequence retryable and put a Retry button next to the
  error.
- Call onHostConfig() once at startup and style everything with the host CSS
  variables (--bg-void, --bg-surface, --text-primary, --accent). The cartridge
  then follows my theme and my accent colour.
- Keep src/sdk/mnemo-sdk.ts as a plain re-export. Never reimplement the
  postMessage transport.
- Run npm run build when you are done and fix whatever it reports.

The traps​

  • The first gated call waits for a human. The host opens a native authorization dialog on the first call needing a permission, and the SDK timeout is five minutes for that reason. Keep the boot sequence retryable: grants persist, so a late answer is recovered by calling again.
  • vault:write is load bearing. Without it in the manifest, ensureSandbox(), describeVaultTile() and socialIngest() are refused instantly, no dialog shown. Remove it if you never write memory.
  • Cartridges share an origin. They all load from mnemo-plugin://app/<id>, so localStorage and IndexedDB are not isolated between installed cartridges. Put state in your vault.
  • Permissions are coarser than they look. One vault:write also unlocks plugin install and uninstall, vault creation, conversation deletion and DocWatch. dialog:open grants read and write of allowlisted file types anywhere under the user's home.
  • The vault exists at first launch, never at install.

Step 5: publish​

The store is one route. The other is handing someone your repo link, which installs straight into their app: see Share your app.

Four things the store preflight enforces:

  1. entrypoints.renderer becomes "index.html", relative. The dev default is http://localhost:5185/index.html, which the preflight rejects.
  2. Commit dist/. The mnemo-plugin:// protocol serves dist/<file> first, and no build runs on the user's machine.
  3. Keep base: './' in vite.config.ts. An absolute /assets/… path 404s under the custom protocol.
  4. Manifest at the repo root, its name matching the submitted app id, and a repository field in package.json.

Host the repo on github.com, gitlab.com or bitbucket.org.

Then hit "Publish" on your linked cartridge. It fills the submission form from your manifest, and you sign it with your sovereign wallet. Publishing needs an active Engramm license.

Review is manual and founder gated. Expect a human, and a delay.

On money

No payment, no in-app purchase and no revenue split are wired today. The store's economy screen is an announcement.