@mnemosyne_os/sdk 1.0.0

package/README.md

@@ -0,0 +1,233 @@
+# @mnemosyne_os/sdk
+
+> **Official SDK for building Layer 2 apps on [Mnemosyne OS](https://github.com/yaka0007/Mnemosyne-Neural-OS)**  
+> Connect your app to a local sovereign AI memory runtime — no cloud dependency.
+
+[![npm version](https://img.shields.io/npm/v/@mnemosyne_os/sdk)](https://www.npmjs.com/package/@mnemosyne_os/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js ≥18](https://img.shields.io/badge/node-%3E%3D18-green)](https://nodejs.org)
+
+---
+
+## 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 an IPC/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`](https://www.npmjs.com/package/@mnemosyne_os/forge) | `1.4.7` | CLI — scaffold, chronicles, MCP server |
+| [`@mnemosyne_os/sync`](https://www.npmjs.com/package/@mnemosyne_os/sync) | `0.0.1` | P2P — multi-agent synchronization |
+| **`@mnemosyne_os/sdk`** | `1.0.0` | **SDK — build Layer 2 apps** |
+
+---
+
+## Requirements
+
+- **Mnemosyne OS Dev Edition** must be running on your machine
+- The SDK WebSocket server runs on `ws://127.0.0.1:7799` (localhost only)
+- Node.js ≥ 18
+
+---
+
+## Install
+
+```bash
+npm install @mnemosyne_os/sdk
+```
+
+---
+
+## Quick Start
+
+### 1. Create your `app.manifest.json`
+
+```json
+{
+  "id": "my-layer2-app",
+  "name": "My Layer 2 App",
+  "version": "1.0.0",
+  "mnemosyne_sdk": "^1.0.0",
+  "scopes": ["vault:read:DEV", "vault:write:DEV"],
+  "vaults": ["DEV"],
+  "intents": ["INGEST", "QUERY"]
+}
+```
+
+### 2. Connect and use
+
+```typescript
+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
+});
+
+// Ingest content into the vault
+await client.ingest({
+  content: 'My content to remember',
+  spineType: 'NOTE',
+  vault: 'DEV',
+});
+
+// Semantic query
+const result = await client.query('my search query', { limit: 5 });
+console.log(result.chronicles);
+
+// Cross-app share (triggers a consent popup in Mnemosyne OS)
+const share = await client.requestShare({
+  fromAppId: 'other-app-id',
+  reason: 'I need access to correlate data',
+});
+
+await client.disconnect();
+```
+
+---
+
+## Transport Modes
+
+The SDK supports two transport modes, auto-detected by default:
+
+| Mode | When | How |
+|------|------|-----|
+| `ws` | External Node.js app | JSON-RPC over `ws://127.0.0.1:7799` |
+| `ipc` | Embedded in Mnemosyne OS renderer | `window.mnemosyne` Electron IPC bridge |
+| `auto` | Default | Detects `window.mnemosyne` → IPC, otherwise WS |
+
+```typescript
+// Force WebSocket (external app)
+const client = await MnemoClient.connect({ appId: '...', manifest: '...', transport: 'ws' });
+
+// Force IPC (embedded Layer 2 app)
+const client = await MnemoClient.connect({ appId: '...', manifest: '...', transport: 'ipc' });
+```
+
+---
+
+## 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.
+
+```typescript
+// Available scopes
+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'
+  | 'nft:validate'        // MnemoStore NFT licence validation
+  | 'neural:graph:read'   // NeuralGraph access
+  | 'llm:query';          // Direct LLM queries (premium)
+```
+
+---
+
+## Available RPC Methods
+
+```typescript
+import { MNEMOSYNE_METHODS } from '@mnemosyne_os/sdk';
+
+// All methods available on ws://127.0.0.1:7799
+MNEMOSYNE_METHODS.REGISTER      // 'sdk.register'
+MNEMOSYNE_METHODS.INGEST        // 'sdk.ingest'
+MNEMOSYNE_METHODS.QUERY         // 'sdk.query'
+MNEMOSYNE_METHODS.CORRELATE     // 'sdk.correlate'
+MNEMOSYNE_METHODS.FORGET        // 'sdk.forget'
+MNEMOSYNE_METHODS.SHARE         // 'sdk.share'
+MNEMOSYNE_METHODS.NFT_VALIDATE  // 'sdk.nft.validate'
+MNEMOSYNE_METHODS.GRAPH_QUERY   // 'sdk.graph.query'
+```
+
+---
+
+## Events
+
+```typescript
+// Listen for events
+const unsubscribe = client.on('connected', (e) => console.log('Connected!', e.data));
+client.on('disconnected', () => console.log('OS disconnected'));
+client.on('tamper-alert', (e) => console.warn('Tamper detected:', e.data));
+client.on('nft-revoked', (e) => console.warn('NFT licence revoked:', e.data));
+
+// Cleanup
+unsubscribe();
+```
+
+---
+
+## NFT Licence (MnemoStore)
+
+Apps distributed on [MnemoStore](https://github.com/yaka0007/Mnemosyne-Neural-OS) can gate access with NFT licences:
+
+```typescript
+// In your app.manifest.json, declare:
+// "scopes": ["nft:validate"]
+
+// Then validate on startup:
+const validation = await client.validateNFTLicense('0xYourWalletAddress');
+if (!validation.valid) {
+  alert('Please purchase a licence on MnemoStore to use this app.');
+  process.exit(1);
+}
+```
+
+> Validation is done on-chain by Mnemosyne OS (not the SDK itself).  
+> Results are cached for 5 minutes to avoid blockchain spam.
+
+---
+
+## API Reference
+
+### `MnemoClient.connect(options)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `appId` | `string` | required | Must match `manifest.id` |
+| `manifest` | `string \| AppManifest` | required | Path to `app.manifest.json` or inline object |
+| `transport` | `'ws' \| 'ipc' \| 'auto'` | `'auto'` | Transport mode |
+| `wsPort` | `number` | `7799` | WebSocket port |
+| `timeoutMs` | `number` | `30000` | RPC timeout |
+
+### `client.ingest(payload)`
+
+Ingests content into the vault. Content is vectorized by the Mnemosyne OS runtime.
+
+### `client.query(text, options?)`
+
+Semantic search over your app's chronicles. Results are isolated to your `appId`.
+
+### `client.requestShare(request)`
+
+Requests access to another app's chronicles. Triggers a consent popup in Mnemosyne OS.
+
+### `client.disconnect()`
+
+Gracefully closes the connection.
+
+---
+
+## 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 `tony@xpacegems.com` for NDA + scoped repo access.
+
+---
+
+## License
+
+MIT © [Tony Trochet / XPACEGEMS LLC](https://xpacegems.com)