@memorylayerai/sdk 0.3.0 → 0.4.0

package/README.md

@@ -28,30 +28,30 @@ yarn add @memorylayerai/sdk
 
 ## Quick Start
 
-### Option 1: Transparent Router (Zero Code Changes) ⚡
+### Option 1: Transparent Router (Beta) - Drop-in OpenAI Proxy ⚡
 
-The easiest way to add memory - just change your OpenAI baseURL:
+Change your baseURL to add automatic memory injection:
 
 ```typescript
 import OpenAI from 'openai';
 
 const openai = new OpenAI({
-  baseURL: 'https://api.memorylayer.ai/v1',  // ← Just change this
+  baseURL: 'https://api.memorylayer.ai/v1',  // ← Point to MemoryLayer
   apiKey: 'ml_your_memorylayer_key'          // ← Use your MemoryLayer key
 });
 
-// That's it! Memory is automatically injected
+// Memory is automatically retrieved and injected
 const response = await openai.chat.completions.create({
   model: 'gpt-4',
   messages: [{ role: 'user', content: 'What are my preferences?' }]
 });
 ```
 
-**Benefits:**
-- ✅ Zero code changes to your application
-- ✅ Automatic memory injection
-- ✅ Works with existing OpenAI SDK code
-- ✅ Configurable via headers
+**Current Status:**
+- ✅ Works with `/v1/chat/completions` (non-streaming)
+- ✅ OpenAI-compatible responses
+- ✅ Configurable via headers (use `fetch`/`axios` for guaranteed header support)
+- ⏳ Streaming support coming soon
 
 See [Transparent Router Guide](#transparent-router) for details.
 
@@ -115,7 +115,12 @@ results.forEach(result => {
 
 ## Transparent Router
 
-The transparent router is an OpenAI-compatible proxy that automatically injects memory context into your requests. It's the easiest way to add memory to your application.
+The transparent router is an OpenAI-compatible proxy that automatically injects memory context into your requests.
+
+**Current Status:**
+- ✅ Works with `/v1/chat/completions` (non-streaming)
+- ✅ OpenAI-compatible responses
+- ⏳ Streaming support coming soon
 
 ### Basic Usage
 
@@ -135,67 +140,52 @@ const response = await openai.chat.completions.create({
 
 ### Configuration Headers
 
-Control memory injection with optional headers:
+Control memory injection with optional headers. **Note:** For guaranteed header support, use `fetch` or `axios` directly:
 
 ```typescript
-const response = await openai.chat.completions.create({
-  model: 'gpt-4',
-  messages: [{ role: 'user', content: 'Hello!' }],
+// Using fetch for guaranteed header support
+const response = await fetch('https://api.memorylayer.ai/v1/chat/completions', {
+  method: 'POST',
   headers: {
-    'x-memory-user-id': 'user_123',              // User scope
-    'x-memory-session-id': 'sess_abc',           // Session scope
-    'x-memory-limit': '10',                      // Max memories
-    'x-memory-injection-mode': 'balanced',       // safe|balanced|full
-    'x-memory-injection-strategy': 'system_append', // Injection strategy
-    'x-memory-disabled': 'false'                 // Enable/disable
-  }
+    'Authorization': `Bearer ${process.env.MEMORYLAYER_API_KEY}`,
+    'Content-Type': 'application/json',
+    'x-memory-user-id': 'user_123',              // User scope (required for multi-user apps)
+    'x-memory-session-id': 'sess_abc',           // Session scope (persist from response)
+    'x-memory-limit': '10',                      // Max memories to inject
+    'x-memory-injection-mode': 'safe',           // safe|full (balanced coming soon)
+    'x-memory-disabled': 'false'                 // Enable/disable memory
+  },
+  body: JSON.stringify({
+    model: 'gpt-4',
+    messages: [{ role: 'user', content: 'Hello!' }]
+  })
 });
 ```
 
 ### Injection Modes
 
-- **safe**: Only fact + preference (minimal risk)
-- **balanced** (default): fact + preference + trusted summaries
-- **full**: All memory types including snippets
+- **safe** (default): Only fact + preference types (minimal risk, structured data)
+- **full**: All memory types including snippets (maximum context, higher token usage)
+- **balanced**: Trusted summaries + facts + preferences (coming soon)
 
 ### Diagnostic Headers
 
-Every response includes diagnostic headers:
+Every response includes diagnostic headers showing what happened:
 
 ```typescript
-const response = await openai.chat.completions.create({ ... });
-
-console.log('Memories retrieved:', response.headers?.['x-memory-hit-count']);
-console.log('Tokens injected:', response.headers?.['x-memory-injected-tokens']);
-console.log('Max score:', response.headers?.['x-memory-max-score']);
-console.log('Query rewriting:', response.headers?.['x-memory-rewrite']);
-console.log('Memory status:', response.headers?.['x-memory-status']);
-console.log('Session ID:', response.headers?.['x-memory-session-id']);
-```
-
-### Streaming Support
+const response = await fetch('https://api.memorylayer.ai/v1/chat/completions', { ... });
 
-Streaming works seamlessly:
-
-```typescript
-const stream = await openai.chat.completions.create({
-  model: 'gpt-4',
-  messages: [{ role: 'user', content: 'Tell me about myself' }],
-  stream: true,
-  headers: {
-    'x-memory-user-id': 'user_123'
-  }
-});
-
-for await (const chunk of stream) {
-  const content = chunk.choices[0]?.delta?.content || '';
-  process.stdout.write(content);
-}
+console.log('Memories retrieved:', response.headers.get('x-memory-hit-count'));
+console.log('Tokens injected:', response.headers.get('x-memory-injected-tokens'));
+console.log('Max score:', response.headers.get('x-memory-max-score'));
+console.log('Query rewriting:', response.headers.get('x-memory-rewrite'));
+console.log('Memory status:', response.headers.get('x-memory-status'));
+console.log('Session ID:', response.headers.get('x-memory-session-id'));  // Persist this!
 ```
 
 ### Session Management
 
-If you don't provide `x-memory-user-id` or `x-memory-session-id`, the router generates a session ID. Persist it for conversation continuity:
+For chat applications, persist `x-memory-session-id` from response headers and pass it in subsequent requests:
 
 ```typescript
 const response = await openai.chat.completions.create({ ... });

package/dist/index.cjs

@@ -251,6 +251,24 @@ var init_search = __esm({
         if (request.filter) {
           query.filter = JSON.stringify(request.filter);
         }
+        if (request.enableQueryRewriting !== void 0) {
+          query.enableQueryRewriting = request.enableQueryRewriting.toString();
+        }
+        if (request.enableEntityExpansion !== void 0) {
+          query.enableEntityExpansion = request.enableEntityExpansion.toString();
+        }
+        if (request.enableGraphConnectivity !== void 0) {
+          query.enableGraphConnectivity = request.enableGraphConnectivity.toString();
+        }
+        if (request.enableSemanticDedup !== void 0) {
+          query.enableSemanticDedup = request.enableSemanticDedup.toString();
+        }
+        if (request.rerankingStrategy) {
+          query.rerankingStrategy = request.rerankingStrategy;
+        }
+        if (request.fusionWeights) {
+          query.fusionWeights = JSON.stringify(request.fusionWeights);
+        }
         return this.httpClient.request({
           method: "GET",
           path: "/v1/search",

package/dist/index.d.cts

@@ -169,6 +169,24 @@ interface SearchRequest {
     filter?: Record<string, any>;
     /** Minimum relevance score threshold (0-1) */
     threshold?: number;
+    /** Enable query rewriting (default: true) */
+    enableQueryRewriting?: boolean;
+    /** Enable entity expansion search (default: false) */
+    enableEntityExpansion?: boolean;
+    /** Enable graph connectivity search (default: false) */
+    enableGraphConnectivity?: boolean;
+    /** Enable semantic deduplication (default: false) */
+    enableSemanticDedup?: boolean;
+    /** Reranking strategy: 'none', 'cross-encoder', 'llm' (default: 'none') */
+    rerankingStrategy?: 'none' | 'cross-encoder' | 'llm';
+    /** Custom fusion weights for multi-method retrieval */
+    fusionWeights?: {
+        vector?: number;
+        bm25?: number;
+        recency?: number;
+        entity?: number;
+        graph?: number;
+    };
 }
 /**
  * Search result
@@ -180,6 +198,20 @@ interface SearchResult {
     score: number;
     /** Highlighted text snippets */
     highlights?: string[];
+    /** Score breakdown by retrieval method */
+    scoreBreakdown?: {
+        vectorScore?: number;
+        bm25Score?: number;
+        recencyScore?: number;
+        entityScore?: number;
+        graphScore?: number;
+    };
+    /** Connected memories (if graph enhancement enabled) */
+    connections?: Array<{
+        memoryId: string;
+        connectionType: 'updates' | 'extends' | 'derives' | 'similarity';
+        connectionStrength: number;
+    }>;
 }
 /**
  * Search response

package/dist/index.d.ts

@@ -169,6 +169,24 @@ interface SearchRequest {
     filter?: Record<string, any>;
     /** Minimum relevance score threshold (0-1) */
     threshold?: number;
+    /** Enable query rewriting (default: true) */
+    enableQueryRewriting?: boolean;
+    /** Enable entity expansion search (default: false) */
+    enableEntityExpansion?: boolean;
+    /** Enable graph connectivity search (default: false) */
+    enableGraphConnectivity?: boolean;
+    /** Enable semantic deduplication (default: false) */
+    enableSemanticDedup?: boolean;
+    /** Reranking strategy: 'none', 'cross-encoder', 'llm' (default: 'none') */
+    rerankingStrategy?: 'none' | 'cross-encoder' | 'llm';
+    /** Custom fusion weights for multi-method retrieval */
+    fusionWeights?: {
+        vector?: number;
+        bm25?: number;
+        recency?: number;
+        entity?: number;
+        graph?: number;
+    };
 }
 /**
  * Search result
@@ -180,6 +198,20 @@ interface SearchResult {
     score: number;
     /** Highlighted text snippets */
     highlights?: string[];
+    /** Score breakdown by retrieval method */
+    scoreBreakdown?: {
+        vectorScore?: number;
+        bm25Score?: number;
+        recencyScore?: number;
+        entityScore?: number;
+        graphScore?: number;
+    };
+    /** Connected memories (if graph enhancement enabled) */
+    connections?: Array<{
+        memoryId: string;
+        connectionType: 'updates' | 'extends' | 'derives' | 'similarity';
+        connectionStrength: number;
+    }>;
 }
 /**
  * Search response

package/dist/index.js

@@ -250,6 +250,24 @@ var init_search = __esm({
         if (request.filter) {
           query.filter = JSON.stringify(request.filter);
         }
+        if (request.enableQueryRewriting !== void 0) {
+          query.enableQueryRewriting = request.enableQueryRewriting.toString();
+        }
+        if (request.enableEntityExpansion !== void 0) {
+          query.enableEntityExpansion = request.enableEntityExpansion.toString();
+        }
+        if (request.enableGraphConnectivity !== void 0) {
+          query.enableGraphConnectivity = request.enableGraphConnectivity.toString();
+        }
+        if (request.enableSemanticDedup !== void 0) {
+          query.enableSemanticDedup = request.enableSemanticDedup.toString();
+        }
+        if (request.rerankingStrategy) {
+          query.rerankingStrategy = request.rerankingStrategy;
+        }
+        if (request.fusionWeights) {
+          query.fusionWeights = JSON.stringify(request.fusionWeights);
+        }
         return this.httpClient.request({
           method: "GET",
           path: "/v1/search",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memorylayerai/sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "private": false,
   "description": "Official Node.js/TypeScript SDK for MemoryLayer",
   "main": "dist/index.js",

package/src/resources/search.ts

@@ -46,6 +46,31 @@ export class SearchResource {
       query.filter = JSON.stringify(request.filter);
     }
 
+    // New advanced retrieval options
+    if (request.enableQueryRewriting !== undefined) {
+      query.enableQueryRewriting = request.enableQueryRewriting.toString();
+    }
+
+    if (request.enableEntityExpansion !== undefined) {
+      query.enableEntityExpansion = request.enableEntityExpansion.toString();
+    }
+
+    if (request.enableGraphConnectivity !== undefined) {
+      query.enableGraphConnectivity = request.enableGraphConnectivity.toString();
+    }
+
+    if (request.enableSemanticDedup !== undefined) {
+      query.enableSemanticDedup = request.enableSemanticDedup.toString();
+    }
+
+    if (request.rerankingStrategy) {
+      query.rerankingStrategy = request.rerankingStrategy;
+    }
+
+    if (request.fusionWeights) {
+      query.fusionWeights = JSON.stringify(request.fusionWeights);
+    }
+
     return this.httpClient.request<SearchResponse>({
       method: 'GET',
       path: '/v1/search',

package/src/types.ts

@@ -66,6 +66,24 @@ export interface SearchRequest {
   filter?: Record<string, any>;
   /** Minimum relevance score threshold (0-1) */
   threshold?: number;
+  /** Enable query rewriting (default: true) */
+  enableQueryRewriting?: boolean;
+  /** Enable entity expansion search (default: false) */
+  enableEntityExpansion?: boolean;
+  /** Enable graph connectivity search (default: false) */
+  enableGraphConnectivity?: boolean;
+  /** Enable semantic deduplication (default: false) */
+  enableSemanticDedup?: boolean;
+  /** Reranking strategy: 'none', 'cross-encoder', 'llm' (default: 'none') */
+  rerankingStrategy?: 'none' | 'cross-encoder' | 'llm';
+  /** Custom fusion weights for multi-method retrieval */
+  fusionWeights?: {
+    vector?: number;
+    bm25?: number;
+    recency?: number;
+    entity?: number;
+    graph?: number;
+  };
 }
 
 /**
@@ -78,6 +96,20 @@ export interface SearchResult {
   score: number;
   /** Highlighted text snippets */
   highlights?: string[];
+  /** Score breakdown by retrieval method */
+  scoreBreakdown?: {
+    vectorScore?: number;
+    bm25Score?: number;
+    recencyScore?: number;
+    entityScore?: number;
+    graphScore?: number;
+  };
+  /** Connected memories (if graph enhancement enabled) */
+  connections?: Array<{
+    memoryId: string;
+    connectionType: 'updates' | 'extends' | 'derives' | 'similarity';
+    connectionStrength: number;
+  }>;
 }
 
 /**