diff --git a/cachematrix.R b/cachematrix.R
index a50be65aa44..bb255fe656e 100644
--- a/cachematrix.R
+++ b/cachematrix.R
@@ -1,15 +1,45 @@
-## Put comments here that give an overall description of what your
-## functions do
+## A "matrix" that carries an embedded cached value of it's inverse
 
-## Write a short comment describing this function
+# the matrix is implemented as a "poor man's object" i.e. a record of
+# closures with a shared mutable environment. 
+# the two functions set() and get() allow accessing and mutating the 
+# embedded matrix object, while set.inverse and get.inverse allow 
+# manipulation of the inverse object in the shared environment.
+#
+#
 
-makeCacheMatrix <- function(x = matrix()) {
 
+makeCacheMatrix <- function(x = matrix()) {
+  inverse <- NULL
+  set <- function(y) {
+    x <<- y
+    inverse <<- NULL
+  }
+  get <- function() x
+  set.inverse <- function(result) inverse <<- result
+  get.inverse <- function() inverse
+  list(set = set, get = get,
+       set.inverse = set.inverse,
+       get.inverse = get.inverse)
 }
 
 
-## Write a short comment describing this function
+# Cache solve can be used to get the inverse of a matrix 
+# in a smart way by looking up the cached value and memoizing 
+# it after a computation for future use. 
 
-cacheSolve <- function(x, ...) {
-        ## Return a matrix that is the inverse of 'x'
+cacheSolve <- function(matrix, ...) {
+  res <- matrix$get.inverse()
+  if(!is.null(res)) {
+    message("getting cached data")
+    return(res)
+  }
+  data <- matrix$get()
+  res <- solve(data)
+  matrix$set.inverse(res)
+  res
 }
+
+#example of invertible matrix
+# hilbert <- function(n) { i <- 1:n; 1 / outer(i - 1, i, "+") }
+# h8 <- hilbert(8)
\ No newline at end of file