Skip to main content

Three ways to build

Mnemosyne OS opens three doors. Different transports, different manifests, different libraries. Pick yours first.

You want to buildUseIt runs
A window inside the Mnemosyne canvas: a tool, a panel, an app on MnemoHubCartridgeas a sandboxed iframe inside the app
A program of your own: a Node service, an agent, a separate desktop or web appLayer 2 appas its own process, over a local WebSocket
Memory access for an AI assistant you already use (Claude, Cursor, Hermes)MCP serveras an MCP server your assistant spawns

Pixels inside Mnemosyne: cartridge. Your own process: Layer 2. An AI agent: MCP.

Cartridge​

A React or Vite app loaded in a sandboxed iframe inside the Mnemosyne window. No Node, no Electron, no filesystem. Every call to the OS is an async postMessage through the SDK.

  • Library: @mnemosyne_os/cartridge-sdk
  • Manifest: mnemo-plugin.json
  • Permissions: vault:read, vault:write, model:infer, dialog:open, metrics:read, settings:read, settings:write, scout:run. You declare them, the user grants them.
  • Distribution: MnemoHub, or a public repo people install from directly.
  • Start here: Your first cartridge.

Layer 2 app​

A standalone program connecting to the running OS on ws://127.0.0.1:7799. Your code runs outside, the memory stays on the machine.

  • Library: @mnemosyne_os/sdk (MnemoClientBrowser for browser and Electron renderers, MnemoClient for Node)
  • Manifest: app.manifest.json
  • Scopes: per vault and per intent, like vault:read:DEV, vault:write:SOCIAL, llm:query. Enforced server side.
  • Scaffold in one command:
npm create @mnemosyne_os/app my-app
import { MnemoClientBrowser } from '@mnemosyne_os/sdk';

const client = await MnemoClientBrowser.connect();
await client.register(manifest);            // the app.manifest.json shape
const hits = await client.query('JWT refactor decisions', 'DEV', 10);

MCP server​

No code at all. Point Claude Desktop, Claude Code, Cursor or Hermes at @mnemosyne_os/mcp and your assistant queries and writes your vaults as tools.

Setup, one config block per client: Connect Claude to Mnemosyne.

Do not mix the two SDKs​

@mnemosyne_os/sdk and @mnemosyne_os/cartridge-sdk are different libraries for different rails. The Layer 2 SDK inside a cartridge gives you a WebSocket client the sandbox will never let connect.

The app catches it: a folder holding an app.manifest.json is refused, with a message saying a cartridge needs mnemo-plugin.json.

The gateway is always on​

No switch to flip. While Mnemosyne OS is open, port 7799 is listening. Close the app and the external surfaces go quiet.