@mnemosyne_os/sdk

Official SDK for building Layer 2 apps on Mnemosyne OS
Connect your app to a local sovereign AI memory runtime — no cloud dependency.

What is Mnemosyne OS?

Mnemosyne OS is a sovereign, local-first AI memory runtime built on Electron.
It runs on your machine, stores everything locally (SQLite + vector embeddings),
and exposes a WebSocket API for Layer 2 apps to tap into its cognitive engine.

No cloud. No telemetry. Your data stays on your machine.

Ecosystem

| Package | Version | Role | |---------|---------|------| | @mnemosyne_os/forge | 1.4.7 | CLI — scaffold, chronicles, MCP server | | @mnemosyne_os/sync | 0.0.1 | P2P — multi-agent synchronization | | @mnemosyne_os/sdk | 1.1.0 | SDK — build Layer 2 apps |

Requirements

• Mnemosyne OS Dev Edition running on your machine (SDK WS Server on port 7799)
• Node.js ≥ 18 (for MnemoClient) OR any modern browser / Electron renderer (for MnemoClientBrowser)

Install

npm install @mnemosyne_os/sdk

Two Clients — Pick the Right One

| Client | Environment | Transport | |--------|------------|-----------| | MnemoClientBrowser | React, Vite, Next.js, Electron renderer | Native WebSocket API | | MnemoClient | Node.js, Electron main process | ws package + IPC |

In most Layer 2 apps (Vite/React/Electron renderer), use MnemoClientBrowser.

Quick Start — Browser / React / Vite

1. Create your app.manifest.json

{
  "id": "my-layer2-app",
  "name": "My Layer 2 App",
  "version": "1.0.0",
  "mnemosyne_sdk": "^1.1.0",
  "scopes": ["vault:read:DEV", "vault:write:DEV"],
  "vaults": ["DEV"],
  "intents": ["INGEST", "QUERY"]
}

2. Connect in your React app

import { MnemoClientBrowser } from '@mnemosyne_os/sdk';
import type { AppManifest, Chronicle } from '@mnemosyne_os/sdk';

const MANIFEST: AppManifest = {
  id: 'my-layer2-app', name: 'My Layer 2 App', version: '1.0.0',
  mnemosyne_sdk: '^1.1.0',
  scopes: ['vault:read:DEV', 'vault:write:DEV'],
  vaults: ['DEV'],
  intents: ['INGEST', 'QUERY'],
};

// Connect and register
const client = await MnemoClientBrowser.connect();
await client.register(MANIFEST);

// Ingest content
await client.ingest('My note to remember', 'NOTE', 'DEV');

// Semantic query
const chronicles: Chronicle[] = await client.query('my search', 'DEV', 10);

// Real-time push events from the OS
client.onPush((event) => {
  if (event.type === 'chronicle:new') {
    console.log('New chronicle from:', event.sourceApp);
  }
});

// Graceful close
client.close();

Quick Start — Node.js External App

import { MnemoClient } from '@mnemosyne_os/sdk';

const client = await MnemoClient.connect({
  appId: 'my-layer2-app',
  manifest: './app.manifest.json',
  // transport: 'auto' → WebSocket if external, IPC if embedded in Mnemosyne OS
});

await client.ingest({ content: 'My content', spineType: 'NOTE', vault: 'DEV' });
const result = await client.query('my search', { limit: 5 });
console.log(result.chronicles);

await client.disconnect();

Full API — MnemoClientBrowser

Connection

const client = await MnemoClientBrowser.connect(
  '127.0.0.1', // host (default)
  7799,        // port (default)
  15_000,      // timeout ms (default)
);

await client.register(manifest); // → RegisterResult (token stored internally)
client.close();

Vault

// Ingest
await client.ingest(content, spineType, vault?, metadata?);

// Query
const chronicles = await client.query(text, vault?, limit?);

Resonances (cognitive workspaces)

// List active resonances from the vault
const resonances = await client.resonancesList();

// Update current position (persisted as DECISION chronicle)
await client.updatePosition('resonance-id', 'Phase 52 — polish complete', 'Phase 52');

Monorepo

// Git log (requires scope: 'monorepo:read', intent: 'GIT_LOG')
const commits = await client.gitLog(20, '30 days ago');

// Read a .md file from the OS repo
const content = await client.readFile('docs/ARCHITECTURE.md');

Agents

// List connected Layer 2 apps (requires scope: 'agents:read', intent: 'LIST_AGENTS')
const agents = await client.agentsList();

Events

// OS push events (chronicle:new, etc.)
client.onPush((event) => { /* ... */ });

// Disconnection
client.onDisconnect(() => { /* reconnect logic */ });

Scopes & Zero-Trust

Every app declares its permissions in app.manifest.json.
The OS refuses any operation not declared in the manifest — Zero-Trust by design.

type MnemoScope =
  | 'vault:read:DEV'      | 'vault:write:DEV'
  | 'vault:read:SOCIAL'   | 'vault:write:SOCIAL'
  | 'vault:read:PERSONAL' | 'vault:write:PERSONAL'
  | 'vault:read:FINANCE'  | 'vault:write:FINANCE'
  | 'vault:read:COOK'     | 'vault:write:COOK'
  | 'share:request'       | 'share:grant'
  | 'monorepo:read'        // git log + readFile
  | 'agents:read'          // list connected agents
  | 'nft:validate'         // MnemoStore NFT licence validation
  | 'neural:graph:read'    // NeuralGraph access
  | 'llm:query';           // Direct LLM queries (premium)

Available RPC Methods

import { MNEMOSYNE_METHODS } from '@mnemosyne_os/sdk';

MNEMOSYNE_METHODS.REGISTER         // 'sdk.register'
MNEMOSYNE_METHODS.INGEST           // 'sdk.ingest'
MNEMOSYNE_METHODS.QUERY            // 'sdk.query'
MNEMOSYNE_METHODS.RESONANCES_LIST  // 'sdk.resonances.list'
MNEMOSYNE_METHODS.UPDATE_POSITION  // 'sdk.resonance.updatePosition'
MNEMOSYNE_METHODS.GIT_LOG          // 'sdk.git.log'
MNEMOSYNE_METHODS.READ_FILE        // 'sdk.readFile'
MNEMOSYNE_METHODS.LIST_AGENTS      // 'sdk.agents.list'
MNEMOSYNE_METHODS.SHARE            // 'sdk.share'
MNEMOSYNE_METHODS.NFT_VALIDATE     // 'sdk.nft.validate'
MNEMOSYNE_METHODS.GRAPH_QUERY      // 'sdk.graph.query'
MNEMOSYNE_METHODS.CORRELATE        // 'sdk.correlate'
MNEMOSYNE_METHODS.FORGET           // 'sdk.forget'

SpineTypes

type SpineType =
  | 'GIT' | 'ARCHITECTURE' | 'DECISION' | 'DEBUG' | 'FEATURE'
  | 'REDDIT_POST' | 'LINKEDIN_POST' | 'SOCIAL_NODE'
  | 'DOCUMENT' | 'NOTE' | 'CUSTOM'
  | 'RESONANCE'        // cognitive workspace node
  | 'SESSION'          // session context / resume snapshot
  | 'POSITION_UPDATE'  // current phase/position marker
  | 'API' | 'DOC' | 'ERROR';

Events (Push)

The OS pushes real-time events to all connected clients. Handle them with onPush:

| Event type | Payload | Trigger | |---|---|---| | chronicle:new | { vault, spineType, sourceApp, ts } | Any client calls ingest() |

More event types coming in future releases (agent:connected, tamper-alert, nft-revoked…).

NFT Licence (MnemoStore)

Apps distributed on MnemoStore can gate access with NFT licences:

// app.manifest.json
{ "scopes": ["nft:validate"] }

// Via MnemoClient (Node.js)
const validation = await client.validateNFTLicense('0xYourWalletAddress');
if (!validation.valid) process.exit(1);

Validation is done on-chain by Mnemosyne OS — cached 5 min to avoid blockchain spam.

Changelog

v1.1.0 — 2026-04-27

• NEW MnemoClientBrowser — zero-dependency browser client (native WebSocket API)
• NEW sdk.resonances.list — fetch real Resonance objects from the vault
• NEW sdk.resonance.updatePosition — persist session position as DECISION chronicle
• NEW sdk.readFile — read .md files from the OS repo (monorepo:read scope)
• NEW Push events — onPush() handler for real-time OS→client notifications
• TYPES Added GitCommit, AgentInfo, RESONANCE/SESSION/POSITION_UPDATE SpineTypes
• TYPES Added monorepo:read, agents:read scopes; GIT_LOG, LIST_AGENTS intents
• FIX Chronicle.content is now optional (some vault records only store vectors)

v1.0.0 — 2026-04-24

• Initial release: MnemoClient, sdk.ingest, sdk.query, sdk.git.log, sdk.agents.list, JWT Zero-Trust

Contributing & Core Access

This SDK is open source (MIT). The Mnemosyne OS core runtime is proprietary.

• Layer 2 apps: build freely using this SDK — no core access needed.
• Core Contributors: contact [email protected] for NDA + scoped repo access.

License

MIT © Tony Trochet / XPACEGEMS LLC