@memorylayerai/sdk 0.2.0 → 0.3.0

package/README.md

@@ -28,11 +28,42 @@ yarn add @memorylayerai/sdk
 
 ## Quick Start
 
-### 1. Get Your API Key
+### Option 1: Transparent Router (Zero Code Changes) ⚡
+
+The easiest way to add memory - just change your OpenAI baseURL:
+
+```typescript
+import OpenAI from 'openai';
+
+const openai = new OpenAI({
+  baseURL: 'https://api.memorylayer.ai/v1',  // ← Just change this
+  apiKey: 'ml_your_memorylayer_key'          // ← Use your MemoryLayer key
+});
+
+// That's it! Memory is automatically 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
+
+See [Transparent Router Guide](#transparent-router) for details.
+
+### Option 2: Manual Integration (Full Control)
+
+For more control over memory retrieval and injection:
+
+#### 1. Get Your API Key
 
 Sign up at [memorylayer.com](https://memorylayer.com) and create an API key from your project settings.
 
-### 2. Initialize the Client
+#### 2. Initialize the Client
 
 ```typescript
 import { MemoryLayer } from '@memorylayerai/sdk';
@@ -44,7 +75,7 @@ const client = new MemoryLayer({
 });
 ```
 
-### 3. Create Memories
+#### 3. Create Memories
 
 ```typescript
 // Create a single memory
@@ -61,7 +92,7 @@ const memory = await client.memories.create({
 console.log('Memory created:', memory.id);
 ```
 
-### 4. Search Memories
+#### 4. Search Memories
 
 ```typescript
 // Hybrid search (vector + keyword + graph)
@@ -82,6 +113,124 @@ 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.
+
+### Basic Usage
+
+```typescript
+import OpenAI from 'openai';
+
+const openai = new OpenAI({
+  baseURL: 'https://api.memorylayer.ai/v1',
+  apiKey: process.env.MEMORYLAYER_API_KEY
+});
+
+const response = await openai.chat.completions.create({
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'What are my preferences?' }]
+});
+```
+
+### Configuration Headers
+
+Control memory injection with optional headers:
+
+```typescript
+const response = await openai.chat.completions.create({
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'Hello!' }],
+  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
+  }
+});
+```
+
+### Injection Modes
+
+- **safe**: Only fact + preference (minimal risk)
+- **balanced** (default): fact + preference + trusted summaries
+- **full**: All memory types including snippets
+
+### Diagnostic Headers
+
+Every response includes diagnostic headers:
+
+```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
+
+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);
+}
+```
+
+### 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:
+
+```typescript
+const response = await openai.chat.completions.create({ ... });
+
+// Get generated session ID
+const sessionId = response.headers?.['x-memory-session-id'];
+
+// Store it and send on next request
+const nextResponse = await openai.chat.completions.create({
+  messages: [...],
+  headers: {
+    'x-memory-session-id': sessionId  // ← Persist this!
+  }
+});
+```
+
+### Error Handling
+
+The router gracefully degrades on errors:
+
+```typescript
+const response = await openai.chat.completions.create({ ... });
+
+// Check memory status
+const memoryStatus = response.headers?.['x-memory-status'];
+if (memoryStatus === 'error') {
+  console.warn('Memory retrieval failed:', response.headers?.['x-memory-error-code']);
+  console.log('But the request still succeeded (graceful degradation)');
+}
+```
+
+### Migration from Manual Integration
+
+See [examples/MIGRATION_GUIDE.md](../../examples/MIGRATION_GUIDE.md) for a complete migration guide.
+
 ## Core Features
 
 ### Memory Management

package/dist/index.cjs

@@ -414,11 +414,197 @@ var init_router = __esm({
   }
 });
 
+// src/resources/graph.ts
+var graph_exports = {};
+__export(graph_exports, {
+  GraphResource: () => GraphResource
+});
+var GraphResource;
+var init_graph = __esm({
+  "src/resources/graph.ts"() {
+    "use strict";
+    init_errors();
+    GraphResource = class {
+      constructor(httpClient) {
+        this.httpClient = httpClient;
+      }
+      /**
+       * Get graph data for a space/project
+       * 
+       * Fetches nodes (memories, documents, entities) and edges (relationships)
+       * for visualization. Supports pagination and filtering.
+       * 
+       * @param request - Graph data request with filters
+       * @returns Graph data with nodes, edges, metadata, and pagination
+       * 
+       * @example
+       * ```typescript
+       * const graphData = await client.graph.getGraph({
+       *   spaceId: 'project-123',
+       *   limit: 100,
+       *   nodeTypes: ['memory', 'document'],
+       *   relationshipTypes: ['extends', 'updates']
+       * });
+       * 
+       * console.log(`Found ${graphData.nodes.length} nodes`);
+       * console.log(`Found ${graphData.edges.length} edges`);
+       * ```
+       * 
+       * Requirements: 6.1
+       */
+      async getGraph(request) {
+        if (!request.spaceId || request.spaceId.trim().length === 0) {
+          throw new ValidationError(
+            "Space ID is required",
+            [{ field: "spaceId", message: "Space ID is required" }]
+          );
+        }
+        const query = {};
+        if (request.cursor) {
+          query.cursor = request.cursor;
+        }
+        if (request.limit !== void 0) {
+          query.limit = request.limit.toString();
+        }
+        if (request.nodeTypes && request.nodeTypes.length > 0) {
+          query.nodeTypes = request.nodeTypes.join(",");
+        }
+        if (request.relationshipTypes && request.relationshipTypes.length > 0) {
+          query.relationshipTypes = request.relationshipTypes.join(",");
+        }
+        if (request.startDate) {
+          query.startDate = request.startDate;
+        }
+        if (request.endDate) {
+          query.endDate = request.endDate;
+        }
+        return this.httpClient.request({
+          method: "GET",
+          path: `/v1/graph/spaces/${request.spaceId}`,
+          query
+        });
+      }
+      /**
+       * Get detailed information for a specific node
+       * 
+       * Fetches node data, connected edges, and neighboring nodes.
+       * 
+       * @param request - Node details request
+       * @returns Node details with edges and connected nodes
+       * 
+       * @example
+       * ```typescript
+       * const details = await client.graph.getNodeDetails({
+       *   nodeId: 'memory-456'
+       * });
+       * 
+       * console.log(`Node: ${details.node.label}`);
+       * console.log(`Connected to ${details.connectedNodes.length} nodes`);
+       * ```
+       * 
+       * Requirements: 6.2
+       */
+      async getNodeDetails(request) {
+        if (!request.nodeId || request.nodeId.trim().length === 0) {
+          throw new ValidationError(
+            "Node ID is required",
+            [{ field: "nodeId", message: "Node ID is required" }]
+          );
+        }
+        return this.httpClient.request({
+          method: "GET",
+          path: `/v1/graph/nodes/${request.nodeId}`
+        });
+      }
+      /**
+       * Get edges connected to a specific node
+       * 
+       * Fetches edges and connected nodes, optionally filtered by edge type.
+       * 
+       * @param request - Node edges request
+       * @returns Edges and connected nodes
+       * 
+       * @example
+       * ```typescript
+       * const edges = await client.graph.getNodeEdges({
+       *   nodeId: 'memory-456',
+       *   edgeTypes: ['extends', 'updates']
+       * });
+       * 
+       * console.log(`Found ${edges.edges.length} edges`);
+       * ```
+       * 
+       * Requirements: 6.3
+       */
+      async getNodeEdges(request) {
+        if (!request.nodeId || request.nodeId.trim().length === 0) {
+          throw new ValidationError(
+            "Node ID is required",
+            [{ field: "nodeId", message: "Node ID is required" }]
+          );
+        }
+        const query = {};
+        if (request.edgeTypes && request.edgeTypes.length > 0) {
+          query.edgeTypes = request.edgeTypes.join(",");
+        }
+        return this.httpClient.request({
+          method: "GET",
+          path: `/v1/graph/nodes/${request.nodeId}/edges`,
+          query
+        });
+      }
+      /**
+       * Get all graph pages using async iteration
+       * 
+       * Automatically handles pagination to fetch all nodes and edges.
+       * Yields each page of results as they are fetched.
+       * 
+       * @param request - Initial graph request (without cursor)
+       * @yields Graph data for each page
+       * 
+       * @example
+       * ```typescript
+       * for await (const page of client.graph.getAllGraphPages({ spaceId: 'project-123' })) {
+       *   console.log(`Page has ${page.nodes.length} nodes`);
+       *   // Process nodes...
+       * }
+       * ```
+       * 
+       * @example
+       * ```typescript
+       * // Collect all nodes
+       * const allNodes: GraphNode[] = [];
+       * for await (const page of client.graph.getAllGraphPages({ spaceId: 'project-123' })) {
+       *   allNodes.push(...page.nodes);
+       * }
+       * console.log(`Total nodes: ${allNodes.length}`);
+       * ```
+       * 
+       * Requirements: 6.4
+       */
+      async *getAllGraphPages(request) {
+        let cursor;
+        let hasMore = true;
+        while (hasMore) {
+          const page = await this.getGraph({
+            ...request,
+            cursor
+          });
+          yield page;
+          cursor = page.pagination.nextCursor;
+          hasMore = page.pagination.hasMore;
+        }
+      }
+    };
+  }
+});
+
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
   APIError: () => APIError,
   AuthenticationError: () => AuthenticationError,
+  GraphResource: () => GraphResource,
   IngestResource: () => IngestResource,
   MemoriesResource: () => MemoriesResource,
   MemoryLayerClient: () => MemoryLayerClient,
@@ -704,6 +890,16 @@ var MemoryLayerClient = class {
     }
     return this._router;
   }
+  /**
+   * Access graph visualization operations
+   */
+  get graph() {
+    if (!this._graph) {
+      const { GraphResource: GraphResource2 } = (init_graph(), __toCommonJS(graph_exports));
+      this._graph = new GraphResource2(this.httpClient);
+    }
+    return this._graph;
+  }
 };
 
 // src/index.ts
@@ -712,10 +908,12 @@ init_memories();
 init_search();
 init_ingest();
 init_router();
+init_graph();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   APIError,
   AuthenticationError,
+  GraphResource,
   IngestResource,
   MemoriesResource,
   MemoryLayerClient,

package/dist/index.d.cts

@@ -31,6 +31,7 @@ declare class MemoryLayerClient {
     private _search?;
     private _ingest?;
     private _router?;
+    private _graph?;
     constructor(config?: ClientConfig$1);
     /**
      * Access memory operations
@@ -48,6 +49,10 @@ declare class MemoryLayerClient {
      * Access router operations
      */
     get router(): any;
+    /**
+     * Access graph visualization operations
+     */
+    get graph(): any;
 }
 
 /**
@@ -308,6 +313,171 @@ interface StreamChunk {
     /** Array of streaming choices */
     choices: StreamChoice[];
 }
+/**
+ * Memory status for visualization
+ */
+type MemoryStatus = 'latest' | 'older' | 'forgotten' | 'expiring' | 'new';
+/**
+ * Node types in the graph
+ */
+type NodeType = 'memory' | 'document' | 'entity';
+/**
+ * Edge types in the graph
+ */
+type EdgeType = 'updates' | 'extends' | 'derives' | 'similarity';
+/**
+ * Node in the graph (memory, document, or entity)
+ */
+interface GraphNode {
+    /** Unique identifier for the node */
+    id: string;
+    /** Type of node */
+    type: NodeType;
+    /** Display label (truncated content or title) */
+    label: string;
+    /** Node data */
+    data: {
+        /** Full content (for memory nodes) */
+        content?: string;
+        /** Title (for document nodes) */
+        title?: string;
+        /** Memory status */
+        status?: MemoryStatus;
+        /** Creation timestamp (ISO 8601) */
+        createdAt: string;
+        /** Expiration timestamp (ISO 8601) */
+        expiresAt?: string;
+        /** Source reference */
+        source?: string;
+        /** Additional metadata */
+        metadata?: Record<string, any>;
+    };
+    /** Optional position hints for layout */
+    position?: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Edge in the graph (relationship or similarity)
+ */
+interface GraphEdge {
+    /** Unique identifier for the edge */
+    id: string;
+    /** Source node ID */
+    source: string;
+    /** Target node ID */
+    target: string;
+    /** Type of edge */
+    type: EdgeType;
+    /** Display label for the edge */
+    label?: string;
+    /** Edge data */
+    data: {
+        /** Strength of the relationship (0.0 to 1.0) */
+        strength: number;
+        /** Additional metadata */
+        metadata?: Record<string, any>;
+    };
+}
+/**
+ * Graph metadata and statistics
+ */
+interface GraphMetadata {
+    /** Total number of nodes */
+    totalNodes: number;
+    /** Number of memory nodes */
+    memoryCount: number;
+    /** Number of document nodes */
+    documentCount: number;
+    /** Number of entity nodes */
+    entityCount: number;
+    /** Total number of edges */
+    totalEdges: number;
+    /** Number of relationship edges */
+    relationshipCount: number;
+    /** Number of similarity edges */
+    similarityCount: number;
+}
+/**
+ * Pagination information
+ */
+interface PaginationInfo {
+    /** Whether there are more results */
+    hasMore: boolean;
+    /** Cursor for the next page */
+    nextCursor?: string;
+    /** Total count (optional, may be expensive to compute) */
+    totalCount?: number;
+}
+/**
+ * Complete graph data structure
+ */
+interface GraphData {
+    /** Array of nodes */
+    nodes: GraphNode[];
+    /** Array of edges */
+    edges: GraphEdge[];
+    /** Graph metadata and statistics */
+    metadata: GraphMetadata;
+    /** Pagination information */
+    pagination: PaginationInfo;
+}
+/**
+ * Request to get graph data
+ */
+interface GetGraphRequest {
+    /** Space/project ID to fetch graph for */
+    spaceId: string;
+    /** Pagination cursor (optional) */
+    cursor?: string;
+    /** Maximum number of nodes to return (default: 500, max: 2000) */
+    limit?: number;
+    /** Filter by node types */
+    nodeTypes?: NodeType[];
+    /** Filter by relationship types */
+    relationshipTypes?: EdgeType[];
+    /** Filter by start date (ISO 8601) */
+    startDate?: string;
+    /** Filter by end date (ISO 8601) */
+    endDate?: string;
+}
+/**
+ * Node details response
+ */
+interface NodeDetails {
+    /** The node */
+    node: GraphNode;
+    /** Edges connected to this node */
+    edges: GraphEdge[];
+    /** Neighboring nodes */
+    connectedNodes: GraphNode[];
+}
+/**
+ * Request to get node details
+ */
+interface GetNodeDetailsRequest {
+    /** Node ID */
+    nodeId: string;
+}
+/**
+ * Request to get node edges
+ */
+interface GetNodeEdgesRequest {
+    /** Node ID */
+    nodeId: string;
+    /** Filter by edge types (optional) */
+    edgeTypes?: EdgeType[];
+}
+/**
+ * Response for get node edges
+ */
+interface GetNodeEdgesResponse {
+    /** Edges connected to the node */
+    edges: GraphEdge[];
+    /** Nodes connected via these edges */
+    connectedNodes: GraphNode[];
+}
 
 /**
  * Configuration for the HTTP client
@@ -489,4 +659,113 @@ declare class RouterResource {
     stream(request: RouterRequest): AsyncIterable<StreamChunk>;
 }
 
-export { APIError, AuthenticationError, type Choice, type ClientConfig$1 as ClientConfig, type CreateMemoryRequest, type IngestFileRequest, IngestResource, type IngestResponse, type IngestTextRequest, type ListMemoriesRequest, MemoriesResource, type Memory, MemoryLayerClient, MemoryLayerError, type Message, NetworkError, RateLimitError, type RouterRequest, RouterResource, type RouterResponse, type SearchRequest, SearchResource, type SearchResponse, type SearchResult, type StreamChoice, type StreamChunk, type StreamDelta, type UpdateMemoryRequest, type Usage, ValidationError, type ValidationErrorDetail };
+/**
+ * Resource for graph visualization operations
+ *
+ * Provides methods to fetch graph data (nodes and edges) for visualization.
+ *
+ * Requirements: 6.1, 6.2, 6.3, 6.4
+ */
+declare class GraphResource {
+    private httpClient;
+    constructor(httpClient: HTTPClient);
+    /**
+     * Get graph data for a space/project
+     *
+     * Fetches nodes (memories, documents, entities) and edges (relationships)
+     * for visualization. Supports pagination and filtering.
+     *
+     * @param request - Graph data request with filters
+     * @returns Graph data with nodes, edges, metadata, and pagination
+     *
+     * @example
+     * ```typescript
+     * const graphData = await client.graph.getGraph({
+     *   spaceId: 'project-123',
+     *   limit: 100,
+     *   nodeTypes: ['memory', 'document'],
+     *   relationshipTypes: ['extends', 'updates']
+     * });
+     *
+     * console.log(`Found ${graphData.nodes.length} nodes`);
+     * console.log(`Found ${graphData.edges.length} edges`);
+     * ```
+     *
+     * Requirements: 6.1
+     */
+    getGraph(request: GetGraphRequest): Promise<GraphData>;
+    /**
+     * Get detailed information for a specific node
+     *
+     * Fetches node data, connected edges, and neighboring nodes.
+     *
+     * @param request - Node details request
+     * @returns Node details with edges and connected nodes
+     *
+     * @example
+     * ```typescript
+     * const details = await client.graph.getNodeDetails({
+     *   nodeId: 'memory-456'
+     * });
+     *
+     * console.log(`Node: ${details.node.label}`);
+     * console.log(`Connected to ${details.connectedNodes.length} nodes`);
+     * ```
+     *
+     * Requirements: 6.2
+     */
+    getNodeDetails(request: GetNodeDetailsRequest): Promise<NodeDetails>;
+    /**
+     * Get edges connected to a specific node
+     *
+     * Fetches edges and connected nodes, optionally filtered by edge type.
+     *
+     * @param request - Node edges request
+     * @returns Edges and connected nodes
+     *
+     * @example
+     * ```typescript
+     * const edges = await client.graph.getNodeEdges({
+     *   nodeId: 'memory-456',
+     *   edgeTypes: ['extends', 'updates']
+     * });
+     *
+     * console.log(`Found ${edges.edges.length} edges`);
+     * ```
+     *
+     * Requirements: 6.3
+     */
+    getNodeEdges(request: GetNodeEdgesRequest): Promise<GetNodeEdgesResponse>;
+    /**
+     * Get all graph pages using async iteration
+     *
+     * Automatically handles pagination to fetch all nodes and edges.
+     * Yields each page of results as they are fetched.
+     *
+     * @param request - Initial graph request (without cursor)
+     * @yields Graph data for each page
+     *
+     * @example
+     * ```typescript
+     * for await (const page of client.graph.getAllGraphPages({ spaceId: 'project-123' })) {
+     *   console.log(`Page has ${page.nodes.length} nodes`);
+     *   // Process nodes...
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Collect all nodes
+     * const allNodes: GraphNode[] = [];
+     * for await (const page of client.graph.getAllGraphPages({ spaceId: 'project-123' })) {
+     *   allNodes.push(...page.nodes);
+     * }
+     * console.log(`Total nodes: ${allNodes.length}`);
+     * ```
+     *
+     * Requirements: 6.4
+     */
+    getAllGraphPages(request: Omit<GetGraphRequest, 'cursor'>): AsyncGenerator<GraphData, void, undefined>;
+}
+
+export { APIError, AuthenticationError, type Choice, type ClientConfig$1 as ClientConfig, type CreateMemoryRequest, type EdgeType, type GetGraphRequest, type GetNodeDetailsRequest, type GetNodeEdgesRequest, type GetNodeEdgesResponse, type GraphData, type GraphEdge, type GraphMetadata, type GraphNode, GraphResource, type IngestFileRequest, IngestResource, type IngestResponse, type IngestTextRequest, type ListMemoriesRequest, MemoriesResource, type Memory, MemoryLayerClient, MemoryLayerError, type MemoryStatus, type Message, NetworkError, type NodeDetails, type NodeType, type PaginationInfo, RateLimitError, type RouterRequest, RouterResource, type RouterResponse, type SearchRequest, SearchResource, type SearchResponse, type SearchResult, type StreamChoice, type StreamChunk, type StreamDelta, type UpdateMemoryRequest, type Usage, ValidationError, type ValidationErrorDetail };

package/dist/index.d.ts

@@ -31,6 +31,7 @@ declare class MemoryLayerClient {
     private _search?;
     private _ingest?;
     private _router?;
+    private _graph?;
     constructor(config?: ClientConfig$1);
     /**
      * Access memory operations
@@ -48,6 +49,10 @@ declare class MemoryLayerClient {
      * Access router operations
      */
     get router(): any;
+    /**
+     * Access graph visualization operations
+     */
+    get graph(): any;
 }
 
 /**
@@ -308,6 +313,171 @@ interface StreamChunk {
     /** Array of streaming choices */
     choices: StreamChoice[];
 }
+/**
+ * Memory status for visualization
+ */
+type MemoryStatus = 'latest' | 'older' | 'forgotten' | 'expiring' | 'new';
+/**
+ * Node types in the graph
+ */
+type NodeType = 'memory' | 'document' | 'entity';
+/**
+ * Edge types in the graph
+ */
+type EdgeType = 'updates' | 'extends' | 'derives' | 'similarity';
+/**
+ * Node in the graph (memory, document, or entity)
+ */
+interface GraphNode {
+    /** Unique identifier for the node */
+    id: string;
+    /** Type of node */
+    type: NodeType;
+    /** Display label (truncated content or title) */
+    label: string;
+    /** Node data */
+    data: {
+        /** Full content (for memory nodes) */
+        content?: string;
+        /** Title (for document nodes) */
+        title?: string;
+        /** Memory status */
+        status?: MemoryStatus;
+        /** Creation timestamp (ISO 8601) */
+        createdAt: string;
+        /** Expiration timestamp (ISO 8601) */
+        expiresAt?: string;
+        /** Source reference */
+        source?: string;
+        /** Additional metadata */
+        metadata?: Record<string, any>;
+    };
+    /** Optional position hints for layout */
+    position?: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Edge in the graph (relationship or similarity)
+ */
+interface GraphEdge {
+    /** Unique identifier for the edge */
+    id: string;
+    /** Source node ID */
+    source: string;
+    /** Target node ID */
+    target: string;
+    /** Type of edge */
+    type: EdgeType;
+    /** Display label for the edge */
+    label?: string;
+    /** Edge data */
+    data: {
+        /** Strength of the relationship (0.0 to 1.0) */
+        strength: number;
+        /** Additional metadata */
+        metadata?: Record<string, any>;
+    };
+}
+/**
+ * Graph metadata and statistics
+ */
+interface GraphMetadata {
+    /** Total number of nodes */
+    totalNodes: number;
+    /** Number of memory nodes */
+    memoryCount: number;
+    /** Number of document nodes */
+    documentCount: number;
+    /** Number of entity nodes */
+    entityCount: number;
+    /** Total number of edges */
+    totalEdges: number;
+    /** Number of relationship edges */
+    relationshipCount: number;
+    /** Number of similarity edges */
+    similarityCount: number;
+}
+/**
+ * Pagination information
+ */
+interface PaginationInfo {
+    /** Whether there are more results */
+    hasMore: boolean;
+    /** Cursor for the next page */
+    nextCursor?: string;
+    /** Total count (optional, may be expensive to compute) */
+    totalCount?: number;
+}
+/**
+ * Complete graph data structure
+ */
+interface GraphData {
+    /** Array of nodes */
+    nodes: GraphNode[];
+    /** Array of edges */
+    edges: GraphEdge[];
+    /** Graph metadata and statistics */
+    metadata: GraphMetadata;
+    /** Pagination information */
+    pagination: PaginationInfo;
+}
+/**
+ * Request to get graph data
+ */
+interface GetGraphRequest {
+    /** Space/project ID to fetch graph for */
+    spaceId: string;
+    /** Pagination cursor (optional) */
+    cursor?: string;
+    /** Maximum number of nodes to return (default: 500, max: 2000) */
+    limit?: number;
+    /** Filter by node types */
+    nodeTypes?: NodeType[];
+    /** Filter by relationship types */
+    relationshipTypes?: EdgeType[];
+    /** Filter by start date (ISO 8601) */
+    startDate?: string;
+    /** Filter by end date (ISO 8601) */
+    endDate?: string;
+}
+/**
+ * Node details response
+ */
+interface NodeDetails {
+    /** The node */
+    node: GraphNode;
+    /** Edges connected to this node */
+    edges: GraphEdge[];
+    /** Neighboring nodes */
+    connectedNodes: GraphNode[];
+}
+/**
+ * Request to get node details
+ */
+interface GetNodeDetailsRequest {
+    /** Node ID */
+    nodeId: string;
+}
+/**
+ * Request to get node edges
+ */
+interface GetNodeEdgesRequest {
+    /** Node ID */
+    nodeId: string;
+    /** Filter by edge types (optional) */
+    edgeTypes?: EdgeType[];
+}
+/**
+ * Response for get node edges
+ */
+interface GetNodeEdgesResponse {
+    /** Edges connected to the node */
+    edges: GraphEdge[];
+    /** Nodes connected via these edges */
+    connectedNodes: GraphNode[];
+}
 
 /**
  * Configuration for the HTTP client
@@ -489,4 +659,113 @@ declare class RouterResource {
     stream(request: RouterRequest): AsyncIterable<StreamChunk>;
 }
 
-export { APIError, AuthenticationError, type Choice, type ClientConfig$1 as ClientConfig, type CreateMemoryRequest, type IngestFileRequest, IngestResource, type IngestResponse, type IngestTextRequest, type ListMemoriesRequest, MemoriesResource, type Memory, MemoryLayerClient, MemoryLayerError, type Message, NetworkError, RateLimitError, type RouterRequest, RouterResource, type RouterResponse, type SearchRequest, SearchResource, type SearchResponse, type SearchResult, type StreamChoice, type StreamChunk, type StreamDelta, type UpdateMemoryRequest, type Usage, ValidationError, type ValidationErrorDetail };
+/**
+ * Resource for graph visualization operations
+ *
+ * Provides methods to fetch graph data (nodes and edges) for visualization.
+ *
+ * Requirements: 6.1, 6.2, 6.3, 6.4
+ */
+declare class GraphResource {
+    private httpClient;
+    constructor(httpClient: HTTPClient);
+    /**
+     * Get graph data for a space/project
+     *
+     * Fetches nodes (memories, documents, entities) and edges (relationships)
+     * for visualization. Supports pagination and filtering.
+     *
+     * @param request - Graph data request with filters
+     * @returns Graph data with nodes, edges, metadata, and pagination
+     *
+     * @example
+     * ```typescript
+     * const graphData = await client.graph.getGraph({
+     *   spaceId: 'project-123',
+     *   limit: 100,
+     *   nodeTypes: ['memory', 'document'],
+     *   relationshipTypes: ['extends', 'updates']
+     * });
+     *
+     * console.log(`Found ${graphData.nodes.length} nodes`);
+     * console.log(`Found ${graphData.edges.length} edges`);
+     * ```
+     *
+     * Requirements: 6.1
+     */
+    getGraph(request: GetGraphRequest): Promise<GraphData>;
+    /**
+     * Get detailed information for a specific node
+     *
+     * Fetches node data, connected edges, and neighboring nodes.
+     *
+     * @param request - Node details request
+     * @returns Node details with edges and connected nodes
+     *
+     * @example
+     * ```typescript
+     * const details = await client.graph.getNodeDetails({
+     *   nodeId: 'memory-456'
+     * });
+     *
+     * console.log(`Node: ${details.node.label}`);
+     * console.log(`Connected to ${details.connectedNodes.length} nodes`);
+     * ```
+     *
+     * Requirements: 6.2
+     */
+    getNodeDetails(request: GetNodeDetailsRequest): Promise<NodeDetails>;
+    /**
+     * Get edges connected to a specific node
+     *
+     * Fetches edges and connected nodes, optionally filtered by edge type.
+     *
+     * @param request - Node edges request
+     * @returns Edges and connected nodes
+     *
+     * @example
+     * ```typescript
+     * const edges = await client.graph.getNodeEdges({
+     *   nodeId: 'memory-456',
+     *   edgeTypes: ['extends', 'updates']
+     * });
+     *
+     * console.log(`Found ${edges.edges.length} edges`);
+     * ```
+     *
+     * Requirements: 6.3
+     */
+    getNodeEdges(request: GetNodeEdgesRequest): Promise<GetNodeEdgesResponse>;
+    /**
+     * Get all graph pages using async iteration
+     *
+     * Automatically handles pagination to fetch all nodes and edges.
+     * Yields each page of results as they are fetched.
+     *
+     * @param request - Initial graph request (without cursor)
+     * @yields Graph data for each page
+     *
+     * @example
+     * ```typescript
+     * for await (const page of client.graph.getAllGraphPages({ spaceId: 'project-123' })) {
+     *   console.log(`Page has ${page.nodes.length} nodes`);
+     *   // Process nodes...
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Collect all nodes
+     * const allNodes: GraphNode[] = [];
+     * for await (const page of client.graph.getAllGraphPages({ spaceId: 'project-123' })) {
+     *   allNodes.push(...page.nodes);
+     * }
+     * console.log(`Total nodes: ${allNodes.length}`);
+     * ```
+     *
+     * Requirements: 6.4
+     */
+    getAllGraphPages(request: Omit<GetGraphRequest, 'cursor'>): AsyncGenerator<GraphData, void, undefined>;
+}
+
+export { APIError, AuthenticationError, type Choice, type ClientConfig$1 as ClientConfig, type CreateMemoryRequest, type EdgeType, type GetGraphRequest, type GetNodeDetailsRequest, type GetNodeEdgesRequest, type GetNodeEdgesResponse, type GraphData, type GraphEdge, type GraphMetadata, type GraphNode, GraphResource, type IngestFileRequest, IngestResource, type IngestResponse, type IngestTextRequest, type ListMemoriesRequest, MemoriesResource, type Memory, MemoryLayerClient, MemoryLayerError, type MemoryStatus, type Message, NetworkError, type NodeDetails, type NodeType, type PaginationInfo, RateLimitError, type RouterRequest, RouterResource, type RouterResponse, type SearchRequest, SearchResource, type SearchResponse, type SearchResult, type StreamChoice, type StreamChunk, type StreamDelta, type UpdateMemoryRequest, type Usage, ValidationError, type ValidationErrorDetail };

package/dist/index.js

@@ -413,6 +413,191 @@ var init_router = __esm({
   }
 });
 
+// src/resources/graph.ts
+var graph_exports = {};
+__export(graph_exports, {
+  GraphResource: () => GraphResource
+});
+var GraphResource;
+var init_graph = __esm({
+  "src/resources/graph.ts"() {
+    "use strict";
+    init_errors();
+    GraphResource = class {
+      constructor(httpClient) {
+        this.httpClient = httpClient;
+      }
+      /**
+       * Get graph data for a space/project
+       * 
+       * Fetches nodes (memories, documents, entities) and edges (relationships)
+       * for visualization. Supports pagination and filtering.
+       * 
+       * @param request - Graph data request with filters
+       * @returns Graph data with nodes, edges, metadata, and pagination
+       * 
+       * @example
+       * ```typescript
+       * const graphData = await client.graph.getGraph({
+       *   spaceId: 'project-123',
+       *   limit: 100,
+       *   nodeTypes: ['memory', 'document'],
+       *   relationshipTypes: ['extends', 'updates']
+       * });
+       * 
+       * console.log(`Found ${graphData.nodes.length} nodes`);
+       * console.log(`Found ${graphData.edges.length} edges`);
+       * ```
+       * 
+       * Requirements: 6.1
+       */
+      async getGraph(request) {
+        if (!request.spaceId || request.spaceId.trim().length === 0) {
+          throw new ValidationError(
+            "Space ID is required",
+            [{ field: "spaceId", message: "Space ID is required" }]
+          );
+        }
+        const query = {};
+        if (request.cursor) {
+          query.cursor = request.cursor;
+        }
+        if (request.limit !== void 0) {
+          query.limit = request.limit.toString();
+        }
+        if (request.nodeTypes && request.nodeTypes.length > 0) {
+          query.nodeTypes = request.nodeTypes.join(",");
+        }
+        if (request.relationshipTypes && request.relationshipTypes.length > 0) {
+          query.relationshipTypes = request.relationshipTypes.join(",");
+        }
+        if (request.startDate) {
+          query.startDate = request.startDate;
+        }
+        if (request.endDate) {
+          query.endDate = request.endDate;
+        }
+        return this.httpClient.request({
+          method: "GET",
+          path: `/v1/graph/spaces/${request.spaceId}`,
+          query
+        });
+      }
+      /**
+       * Get detailed information for a specific node
+       * 
+       * Fetches node data, connected edges, and neighboring nodes.
+       * 
+       * @param request - Node details request
+       * @returns Node details with edges and connected nodes
+       * 
+       * @example
+       * ```typescript
+       * const details = await client.graph.getNodeDetails({
+       *   nodeId: 'memory-456'
+       * });
+       * 
+       * console.log(`Node: ${details.node.label}`);
+       * console.log(`Connected to ${details.connectedNodes.length} nodes`);
+       * ```
+       * 
+       * Requirements: 6.2
+       */
+      async getNodeDetails(request) {
+        if (!request.nodeId || request.nodeId.trim().length === 0) {
+          throw new ValidationError(
+            "Node ID is required",
+            [{ field: "nodeId", message: "Node ID is required" }]
+          );
+        }
+        return this.httpClient.request({
+          method: "GET",
+          path: `/v1/graph/nodes/${request.nodeId}`
+        });
+      }
+      /**
+       * Get edges connected to a specific node
+       * 
+       * Fetches edges and connected nodes, optionally filtered by edge type.
+       * 
+       * @param request - Node edges request
+       * @returns Edges and connected nodes
+       * 
+       * @example
+       * ```typescript
+       * const edges = await client.graph.getNodeEdges({
+       *   nodeId: 'memory-456',
+       *   edgeTypes: ['extends', 'updates']
+       * });
+       * 
+       * console.log(`Found ${edges.edges.length} edges`);
+       * ```
+       * 
+       * Requirements: 6.3
+       */
+      async getNodeEdges(request) {
+        if (!request.nodeId || request.nodeId.trim().length === 0) {
+          throw new ValidationError(
+            "Node ID is required",
+            [{ field: "nodeId", message: "Node ID is required" }]
+          );
+        }
+        const query = {};
+        if (request.edgeTypes && request.edgeTypes.length > 0) {
+          query.edgeTypes = request.edgeTypes.join(",");
+        }
+        return this.httpClient.request({
+          method: "GET",
+          path: `/v1/graph/nodes/${request.nodeId}/edges`,
+          query
+        });
+      }
+      /**
+       * Get all graph pages using async iteration
+       * 
+       * Automatically handles pagination to fetch all nodes and edges.
+       * Yields each page of results as they are fetched.
+       * 
+       * @param request - Initial graph request (without cursor)
+       * @yields Graph data for each page
+       * 
+       * @example
+       * ```typescript
+       * for await (const page of client.graph.getAllGraphPages({ spaceId: 'project-123' })) {
+       *   console.log(`Page has ${page.nodes.length} nodes`);
+       *   // Process nodes...
+       * }
+       * ```
+       * 
+       * @example
+       * ```typescript
+       * // Collect all nodes
+       * const allNodes: GraphNode[] = [];
+       * for await (const page of client.graph.getAllGraphPages({ spaceId: 'project-123' })) {
+       *   allNodes.push(...page.nodes);
+       * }
+       * console.log(`Total nodes: ${allNodes.length}`);
+       * ```
+       * 
+       * Requirements: 6.4
+       */
+      async *getAllGraphPages(request) {
+        let cursor;
+        let hasMore = true;
+        while (hasMore) {
+          const page = await this.getGraph({
+            ...request,
+            cursor
+          });
+          yield page;
+          cursor = page.pagination.nextCursor;
+          hasMore = page.pagination.hasMore;
+        }
+      }
+    };
+  }
+});
+
 // src/http-client.ts
 init_errors();
 var HTTPClient = class {
@@ -686,6 +871,16 @@ var MemoryLayerClient = class {
     }
     return this._router;
   }
+  /**
+   * Access graph visualization operations
+   */
+  get graph() {
+    if (!this._graph) {
+      const { GraphResource: GraphResource2 } = (init_graph(), __toCommonJS(graph_exports));
+      this._graph = new GraphResource2(this.httpClient);
+    }
+    return this._graph;
+  }
 };
 
 // src/index.ts
@@ -694,9 +889,11 @@ init_memories();
 init_search();
 init_ingest();
 init_router();
+init_graph();
 export {
   APIError,
   AuthenticationError,
+  GraphResource,
   IngestResource,
   MemoriesResource,
   MemoryLayerClient,

package/package.json

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