Votre première cartouche

Une cartouche est une app web dans une fenêtre du canvas Mnemosyne, avec votre mémoire comme backend. Du dossier vide à la cartouche qui tourne, avec un agent IA qui fait la frappe.

Ce qu'il vous faut

1. Mnemosyne OS, ouvert. Il possède les coffres et la passerelle locale. Téléchargez-le si ce n'est pas déjà fait.
2. Node.js 18 ou plus récent.
3. Un agent de code : Claude Code, Cursor, Copilot, celui que vous utilisez.

Étape 1 : donnez votre mémoire à votre agent

Facultatif, et ça change tout le reste. Connectez votre agent par MCP et il lit les décisions, les notes et le code que vous avez déjà écrits pendant qu'il construit.

Un bloc de config par client : Connecter Claude à Mnemosyne.

astuce

MNEMO_VAULTS nomme les coffres que l'agent a le droit de voir. Rien d'autre n'est atteignable, et les coffres en protection Maximum gardent leurs garanties.

Étape 2 : le prompt d'environnement

Ouvrez un terminal dans un dossier vide, lancez votre agent dedans, et collez ceci.

Prépare-moi un projet de cartouche Mnemosyne OS.

1. Vérifie que Node.js est en version 18 ou plus. Arrête-toi et dis-le moi si
   ce n'est pas le cas.
2. Génère le boilerplate officiel dans un dossier my-cartridge :
   npx degit Mnemosyne-OS/Mnemosyne-Neural-OS/examples/cartridge-boilerplate my-cartridge
3. Depuis ce dossier, installe puis mets le SDK à jour. Le template épingle une
   ancienne plage exprès, donc la deuxième commande compte :
   npm install
   npm install @mnemosyne_os/cartridge-sdk@latest
4. Lis AGENTS.md à la racine du scaffold, en entier, avant toute chose. C'est
   la surface de build qui fait foi : forme du manifeste, vocabulaire des
   permissions, et la liste complète des actions de l'hôte. N'invente jamais
   une action ou une API qui n'y figure pas. Si une capacité manque à cette
   liste, elle n'existe pas : dis-le.
5. Renomme l'app. Dans mnemo-plugin.json ET package.json, mets "name" à
   @mon-pseudo/ma-cartouche. Les deux fichiers doivent être d'accord.
6. Lance npm run build et confirme que ça passe.
7. Lance npm run dev et laisse-le servir sur 127.0.0.1:5185.

Ensuite arrête-toi et dis-moi ce que tu as fait. N'écris encore aucun code
fonctionnel.

Vous obtenez une cartouche qui marche : elle réclame son propre coffre, écrit et relit de la mémoire, appelle le modèle de l'hôte et ouvre un dialogue de dossier natif.

Choisissez le nom une seule fois

La propriété du coffre est indexée sur le name du manifeste. Changez-le plus tard et le lancement suivant crée un coffre neuf en abandonnant l'ancien, avec tout ce qu'il contient.

Étape 3 : liez-la dans l'app

MnemoHub → Mes apps → Dashboard DEV → Mes cartouches dev → « Lier une cartouche locale », puis choisissez votre dossier my-cartridge.

Le manifeste pointe vers votre serveur Vite, vous avez donc le hot reload dans la fenêtre Mnemosyne.

La première cartouche liée est gratuite. Les slots suivants demandent une licence Engramm active.

Étape 4 : le prompt de construction

De retour dans votre agent, dans le dossier du projet :

Construis ma cartouche dans ce dossier.

Ce qu'elle fait : <décrivez votre app en quelques phrases>.

Règles :
- Lis AGENTS.md en entier d'abord. Chaque appel à l'hôte est
  await sdk.invoke('<action>', payload), et sa table d'actions est la seule
  liste d'actions qui existe. Ne devine aucune API.
- Déclare le MINIMUM de permissions dans mnemo-plugin.json. Trop en demander
  fait rejeter une cartouche à la revue, et vault:write est marquée sensible.
- Réclame le coffre sandbox une fois au boot, avant toute écriture :
  const { vault } = await sdk.ensureSandbox();
  Ensuite vise toujours ce coffre par son nom.
- Le premier appel qui a besoin d'une permission ouvre un dialogue natif et
  attend mon clic. Garde la séquence de boot rejouable et mets un bouton
  Réessayer à côté de l'erreur.
- Appelle onHostConfig() une fois au démarrage et style tout avec les variables
  CSS de l'hôte (--bg-void, --bg-surface, --text-primary, --accent). La
  cartouche suit alors mon thème et ma couleur d'accent.
- Garde src/sdk/mnemo-sdk.ts comme simple ré-export. Ne réimplémente jamais le
  transport postMessage.
- Lance npm run build à la fin et corrige ce qu'il signale.

Les pièges

• Le premier appel protégé attend un humain. L'hôte ouvre son dialogue d'autorisation natif au premier appel qui a besoin d'une permission, et le délai du SDK est de cinq minutes pour cette raison. Gardez la séquence de boot rejouable : les accords persistent, une réponse tardive se rattrape en rappelant.
• vault:write porte tout. Sans elle dans le manifeste, ensureSandbox(), describeVaultTile() et socialIngest() sont refusés instantanément, sans aucun dialogue. Retirez-la si vous n'écrivez jamais de mémoire.
• Les cartouches partagent une origine. Elles se chargent toutes depuis mnemo-plugin://app/<id>, donc localStorage et IndexedDB ne sont pas isolés entre cartouches installées. Mettez l'état dans votre coffre.
• Les permissions sont plus larges qu'elles n'en ont l'air. Un seul vault:write débloque aussi l'installation et la désinstallation de plugins, la création de coffres, la suppression de conversations et DocWatch. dialog:open donne la lecture et l'écriture des types de fichiers autorisés partout sous le dossier personnel.
• Le coffre existe au premier lancement, jamais à l'installation.

Étape 5 : publier

Le store est une voie. L'autre consiste à donner votre lien de dépôt, qui s'installe directement dans l'app de la personne : voir Partager votre app.

Quatre choses que le préflight du store vérifie :

1. entrypoints.renderer devient "index.html", en relatif. La valeur de dev est http://localhost:5185/index.html, que le préflight rejette.
2. Committez dist/. Le protocole mnemo-plugin:// sert dist/<fichier> en premier, et aucun build ne tourne sur la machine de l'utilisateur.
3. Gardez base: './' dans vite.config.ts. Un chemin absolu /assets/… fait un 404 sous le protocole personnalisé.
4. Manifeste à la racine du dépôt, son name égal à l'id d'app soumis, et un champ repository dans package.json.

Hébergez le dépôt sur github.com, gitlab.com ou bitbucket.org.

Ensuite cliquez « Publier » sur votre cartouche liée. Le formulaire de soumission se remplit depuis votre manifeste, et vous le signez avec votre portefeuille souverain. Publier demande une licence Engramm active.

La revue est manuelle et gardée par le fondateur. Attendez-vous à un humain, et à un délai.

Côté argent

Aucun paiement, aucun achat intégré et aucun partage de revenus n'est câblé aujourd'hui. L'écran économie du store est une annonce.

À lire ensuite

• Partager votre app pour la mettre devant des gens sans attendre une fiche dans le store.
• Trois façons de construire si une cartouche n'est pas la bonne forme pour votre idée.
• Le boilerplate, avec l'AGENTS.md que votre agent lit.
• MnemoReader, une vraie cartouche livrée dont vous pouvez lire toute la source.