@mnemosyne_os/sdk 1.0.0 → 1.2.0

package/README.md

@@ -13,7 +13,7 @@
 
 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.
+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.**
 
@@ -25,15 +25,14 @@ and exposes an IPC/WebSocket API for Layer 2 apps to tap into its cognitive engi
 |---------|---------|------|
 | [`@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** |
+| **`@mnemosyne_os/sdk`** | **`1.1.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
+- **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`)
 
 ---
 
@@ -45,7 +44,18 @@ npm install @mnemosyne_os/sdk
 
 ---
 
-## Quick Start
+## 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`
 
@@ -54,14 +64,51 @@ npm install @mnemosyne_os/sdk
   "id": "my-layer2-app",
   "name": "My Layer 2 App",
   "version": "1.0.0",
-  "mnemosyne_sdk": "^1.0.0",
+  "mnemosyne_sdk": "^1.1.0",
   "scopes": ["vault:read:DEV", "vault:write:DEV"],
   "vaults": ["DEV"],
   "intents": ["INGEST", "QUERY"]
 }
 ```
 
-### 2. Connect and use
+### 2. Connect in your React app
+
+```typescript
+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
 
 ```typescript
 import { MnemoClient } from '@mnemosyne_os/sdk';
@@ -72,44 +119,75 @@ const client = await MnemoClient.connect({
   // 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 });
+await client.ingest({ content: 'My content', spineType: 'NOTE', vault: 'DEV' });
+const result = await client.query('my search', { 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
+## Full API — `MnemoClientBrowser`
 
-The SDK supports two transport modes, auto-detected by default:
+### Connection
+
+```typescript
+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
+
+```typescript
+// Ingest
+await client.ingest(content, spineType, vault?, metadata?);
+
+// Query
+const chronicles = await client.query(text, vault?, limit?);
+```
 
-| 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 |
+### Resonances (cognitive workspaces)
 
 ```typescript
-// Force WebSocket (external app)
-const client = await MnemoClient.connect({ appId: '...', manifest: '...', transport: 'ws' });
+// List active resonances from the vault
+const resonances = await client.resonancesList();
 
-// Force IPC (embedded Layer 2 app)
-const client = await MnemoClient.connect({ appId: '...', manifest: '...', transport: 'ipc' });
+// Update current position (persisted as DECISION chronicle)
+await client.updatePosition('resonance-id', 'Phase 52 — polish complete', 'Phase 52');
+```
+
+### Monorepo
+
+```typescript
+// 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
+
+```typescript
+// List connected Layer 2 apps (requires scope: 'agents:read', intent: 'LIST_AGENTS')
+const agents = await client.agentsList();
+```
+
+### Events
+
+```typescript
+// OS push events (chronicle:new, etc.)
+client.onPush((event) => { /* ... */ });
+
+// Disconnection
+client.onDisconnect(() => { /* reconnect logic */ });
 ```
 
 ---
@@ -120,17 +198,18 @@ 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)
+  | '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)
 ```
 
 ---
@@ -140,82 +219,94 @@ type MnemoScope =
 ```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'
+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'
 ```
 
 ---
 
-## Events
+## SpineTypes
 
 ```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();
+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';
 ```
 
 ---
 
-## NFT Licence (MnemoStore)
+## Events (Push)
 
-Apps distributed on [MnemoStore](https://github.com/yaka0007/Mnemosyne-Neural-OS) can gate access with NFT licences:
+The OS pushes real-time events to all connected clients. Handle them with `onPush`:
 
-```typescript
-// In your app.manifest.json, declare:
-// "scopes": ["nft:validate"]
+| Event `type` | Payload | Trigger |
+|---|---|---|
+| `chronicle:new` | `{ vault, spineType, sourceApp, ts }` | Any client calls `ingest()` |
 
-// 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.
+More event types coming in future releases (agent:connected, tamper-alert, nft-revoked…).
 
 ---
 
-## 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.
+## NFT Licence (MnemoStore)
 
-### `client.query(text, options?)`
+Apps distributed on MnemoStore can gate access with NFT licences:
 
-Semantic search over your app's chronicles. Results are isolated to your `appId`.
+```json
+// app.manifest.json
+{ "scopes": ["nft:validate"] }
+```
 
-### `client.requestShare(request)`
+```typescript
+// Via MnemoClient (Node.js)
+const validation = await client.validateNFTLicense('0xYourWalletAddress');
+if (!validation.valid) process.exit(1);
+```
 
-Requests access to another app's chronicles. Triggers a consent popup in Mnemosyne OS.
+> Validation is done on-chain by Mnemosyne OS — cached 5 min to avoid blockchain spam.
 
-### `client.disconnect()`
+---
 
-Gracefully closes the connection.
+## Changelog
+
+### v2.0.0 — 2026-05-01 — Phase 59 Active Cognitive Filter
+
+- **NEW** `bridge:read` scope — unlocks `computeResonance`, `getBridgeHistory`, `getBridgeSessions`
+- **UPGRADE** `computeResonance` now uses **true vector embedding** (Phase 59):
+  embed input text → cosine vs. stored bridge spine vectors → real similarity scores.
+  Falls back to keyword heuristic (Phase 58) when embedding model is offline.
+- **NEW** `docs/BRIDGE_API.md` — full Bridge API reference
+- **NEW** `docs/MANIFEST.md` — `mnemoapp.json` manifest specification
+- **NEW** `mnemoapp.json` replaces `app.manifest.json` (old format still accepted, deprecated)
+- **NEW** `api_version: "2.0"` field in manifest (replaces `mnemosyne_sdk`)
+
+### 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
 
 ---