@mnemosyne_os/sdk 1.2.0 → 1.2.1

package/README.md

@@ -23,9 +23,10 @@ and exposes a WebSocket API for Layer 2 apps to tap into its cognitive engine.
 
 | Package | Version | Role |
 |---------|---------|------|
+| [`@mnemosyne_os/mcp`](https://www.npmjs.com/package/@mnemosyne_os/mcp) | latest | MCP server — plug Claude / Cursor / any MCP agent into your vault |
 | [`@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.1.0`** | **SDK — build Layer 2 apps** |
+| **`@mnemosyne_os/sdk`** | **`1.2.0`** | **SDK — build Layer 2 apps** |
 
 ---
 
@@ -64,7 +65,7 @@ npm install @mnemosyne_os/sdk
   "id": "my-layer2-app",
   "name": "My Layer 2 App",
   "version": "1.0.0",
-  "mnemosyne_sdk": "^1.1.0",
+  "mnemosyne_sdk": "^1.2.0",
   "scopes": ["vault:read:DEV", "vault:write:DEV"],
   "vaults": ["DEV"],
   "intents": ["INGEST", "QUERY"]
@@ -128,6 +129,38 @@ await client.disconnect();
 
 ---
 
+## Semantic Ranking (v1.2+)
+
+By default `query()` returns the **N most recent chronicles** — fast (~5 ms) and good for "what changed lately" panes.
+For agent-style relevance, opt into the **semantic branch**:
+
+```typescript
+const result = await client.query('JWT auth refactor decisions', {
+  vault:    'DEV',
+  limit:    10,
+  semantic: true,                          // ← opt-in true semantic ranking
+  scope:    'SOURCE_CODE',                 // ← cognitive scope (boosts ARCHITECTURE / GIT / API)
+  spineTypeFilter: ['ARCHITECTURE', 'GIT'] // ← optional whitelist
+});
+
+console.log(result.chronicles);
+// result._semantic = { used: true, vectorDim: 768, vaultSize: 5912 }
+//   ↑ confirms the semantic branch ran (vs. silent fallback to recent)
+```
+
+| `QueryOptions` field | Default | What it does |
+|---|---|---|
+| `semantic` | `false` | Embeds the query and ranks by cosine × spineType weight. Without it: recent N. |
+| `scope` | `'SOURCE_CODE'` | Cognitive scope that drives the type-weight table (ARCHITECTURE ×1.40, GIT ×1.35, etc.). |
+| `spineTypeFilter` | `undefined` | Server-side SQL `IN` clause — restricts results to listed types. |
+| `threshold` | `0.0` | Minimum cosine score (0–1) before type-weighting. |
+
+The runtime applies an **exact-term boost** for identifier-like tokens in your query (uppercased words ≥4 chars, hyphenated codes, version numbers). Matching chronicles get `cosine × (1 + matchCount × 0.5)`, surfacing docs that contain rare identifiers verbatim — which dense embeddings alone tend to miss.
+
+The optional `_semantic` field on `QueryResult` is your debug breadcrumb: it tells you whether the semantic branch ran, what dimension the query vector had, how many chronicles were in the target vault, and the error message if it silently fell back to "recent" (e.g. embedding provider not registered).
+
+---
+
 ## Full API — `MnemoClientBrowser`
 
 ### Connection
@@ -284,6 +317,16 @@ if (!validation.valid) process.exit(1);
 
 ## Changelog
 
+### v1.2.0 — 2026-06-07 — Semantic Bridge
+
+- **NEW** `QueryOptions.semantic?: boolean` — opt-in true semantic ranking (server embeds query, ranks by cosine × spineType weight).
+- **NEW** `QueryOptions.scope?: string` — cognitive scope for the type-weight table (default `'SOURCE_CODE'`, boosts ARCHITECTURE / GIT / API).
+- **NEW** `QueryOptions.spineTypeFilter?: string[]` — server-side `IN` filter to restrict results to specific spineTypes.
+- **NEW** `QueryResult._semantic?: QuerySemanticDebug` — breadcrumb that tells you whether the semantic branch ran, the vector dim used, and the vault size (or the fallback reason).
+- **NEW** Exported `QuerySemanticDebug` type.
+- **FIX** Bundle no longer crashes under pure Node ESM. v1.1.0 inlined `ws` and produced a tsup `__require2('events')` shim that threw `Dynamic require of "events" is not supported` at module load — making `npm install @mnemosyne_os/sdk` followed by `import` from any plain Node script crash on startup. `ws` is now an `optionalDependency`, marked external in the build, so the SDK loads cleanly in any ESM context (MCP servers, CLIs, Node services).
+- **COMPAT** Fully backward-compatible: existing `query(text, options)` calls without the new fields behave exactly as in 1.1.0.
+
 ### v2.0.0 — 2026-05-01 — Phase 59 Active Cognitive Filter
 
 - **NEW** `bridge:read` scope — unlocks `computeResonance`, `getBridgeHistory`, `getBridgeSessions`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemosyne_os/sdk",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Official SDK for building Layer 2 apps on Mnemosyne OS — connects to the local AI memory runtime via WebSocket or Electron IPC.",
   "keywords": ["mnemosyne", "ai", "memory", "vector", "sdk", "sovereign", "layer2", "local-ai", "electron"],
   "author": {