@memorylayerai/sdk 0.1.1 → 0.3.0

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.1.1",
+  "version": "0.3.0",
   "private": false,
   "description": "Official Node.js/TypeScript SDK for MemoryLayer",
   "main": "dist/index.js",

package/src/client.ts

@@ -35,6 +35,7 @@ export class MemoryLayerClient {
   private _search?: any;
   private _ingest?: any;
   private _router?: any;
+  private _graph?: any;
 
   constructor(config: ClientConfig = {}) {
     // Get API key from config or environment variable
@@ -113,4 +114,15 @@ export class MemoryLayerClient {
     }
     return this._router;
   }
+
+  /**
+   * Access graph visualization operations
+   */
+  get graph() {
+    if (!this._graph) {
+      const { GraphResource } = require('./resources/graph.js');
+      this._graph = new GraphResource(this.httpClient);
+    }
+    return this._graph;
+  }
 }

package/src/index.ts

@@ -41,6 +41,20 @@ export type {
   StreamChunk,
   StreamChoice,
   StreamDelta,
+  // Graph types
+  GraphData,
+  GraphNode,
+  GraphEdge,
+  GraphMetadata,
+  PaginationInfo,
+  NodeDetails,
+  GetGraphRequest,
+  GetNodeDetailsRequest,
+  GetNodeEdgesRequest,
+  GetNodeEdgesResponse,
+  MemoryStatus,
+  NodeType,
+  EdgeType,
 } from './types.js';
 
 // Resources (exported for advanced use cases)
@@ -48,3 +62,4 @@ export { MemoriesResource } from './resources/memories.js';
 export { SearchResource } from './resources/search.js';
 export { IngestResource } from './resources/ingest.js';
 export { RouterResource } from './resources/router.js';
+export { GraphResource } from './resources/graph.js';