From f7bda4c940b57381dce01c6bfe623cd973d16e6e Mon Sep 17 00:00:00 2001
From: Lance Martin <122662504+rlancemartin@users.noreply.github.com>
Date: Mon, 12 Aug 2024 13:42:57 -0700
Subject: [PATCH] Minor clarifications on Memory in docs (#1301)

* Minor clarifications on Memory in docs

* Address comments
---
 examples/persistence.ipynb          | 10 +++++--
 examples/persistence_postgres.ipynb | 42 ++++++++++++++++++++++++-----
 2 files changed, 43 insertions(+), 9 deletions(-)

diff --git a/examples/persistence.ipynb b/examples/persistence.ipynb
index 5592ed25d..869043cf1 100644
--- a/examples/persistence.ipynb
+++ b/examples/persistence.ipynb
@@ -11,10 +11,16 @@
         "\n",
         "When creating any LangGraph workflow, you can set them up to persist their state by doing using the following:\n",
         "\n",
-        "1. A [Checkpointer](https://langchain-ai.github.io/langgraph/reference/checkpoints/#basecheckpointsaver), such as the [AsyncSqliteSaver](https://langchain-ai.github.io/langgraph/reference/checkpoints/#asyncsqlitesaver)\n",
+        "1. A [Checkpointer](https://langchain-ai.github.io/langgraph/reference/checkpoints/#basecheckpointsaver).\n",
         "2. Call `compile(checkpointer=my_checkpointer)` when compiling the graph.\n",
         "\n",
-        "Example:\n",
+        "There are several options for checkpointers to use.\n",
+        "\n",
+        "1. [MemorySaver](https://langchain-ai.github.io/langgraph/reference/checkpoints/#memorysaver) is an in-memory key-value store for Graph state.\n",
+        "2. [SqliteSaver](https://langchain-ai.github.io/langgraph/reference/checkpoints/#sqlitesaver) allows you to save to a Sqlite db locally or in memory.\n",
+        "3. There are various external databases that can be used for persistence, such as [Postgres](https://langchain-ai.github.io/langgraph/how-tos/persistence_postgres/), [MongoDB](https://langchain-ai.github.io/langgraph/how-tos/persistence_mongodb/), and [Redis](https://langchain-ai.github.io/langgraph/how-tos/persistence_redis/).\n",
+        " \n",
+        "Here is an example using [MemorySaver](https://langchain-ai.github.io/langgraph/reference/checkpoints/#memorysaver) in memory:\n",
         "```python\n",
         "from langgraph.graph import StateGraph\n",
         "from langgraph.checkpoint.memory import MemorySaver\n",
diff --git a/examples/persistence_postgres.ipynb b/examples/persistence_postgres.ipynb
index a78003a0a..5fffa6153 100644
--- a/examples/persistence_postgres.ipynb
+++ b/examples/persistence_postgres.ipynb
@@ -9,7 +9,13 @@
     "\n",
     "When creating LangGraph agents, you can also set them up so that they persist their state. This allows you to do things like interact with an agent multiple times and have it remember previous interactions.\n",
     "\n",
-    "This example shows how to use `Postgres` as the backend for persisting checkpoint state using [`langgraph-checkpoint-postgres`](https://github.com/langchain-ai/langgraph/tree/main/libs/checkpoint-postgres) library."
+    "This example shows how to use `Postgres` as the backend for persisting checkpoint state using [`langgraph-checkpoint-postgres`](https://github.com/langchain-ai/langgraph/tree/main/libs/checkpoint-postgres) library.\n",
+    "\n",
+    "To start a Postgres database to work with you can do the following:\n",
+    "\n",
+    "```\n",
+    "$ cd libs/langgraph\n",
+    "$ make start-postgres"
    ]
   },
   {
@@ -38,7 +44,7 @@
    "metadata": {},
    "outputs": [
     {
-     "name": "stdin",
+     "name": "stdout",
      "output_type": "stream",
      "text": [
       "OPENAI_API_KEY:  ········\n"
@@ -102,7 +108,11 @@
    "id": "e9342c62-dbb4-40f6-9271-7393f1ca48c4",
    "metadata": {},
    "source": [
-    "## Use sync connection"
+    "## Use sync connection\n",
+    "\n",
+    "This sets up a synchronous connection to the database. \n",
+    "\n",
+    "Synchronous connections execute operations in a blocking manner, meaning each operation waits for completion before moving to the next one. The `DB_URI` is the database connection URI, with the protocol used for connecting to a PostgreSQL database, authentication, and host where database is running. The connection_kwargs dictionary defines additional parameters for the database connection."
    ]
   },
   {
@@ -136,7 +146,11 @@
    "id": "e39fc712-9e1c-4831-9077-dd07b0c13594",
    "metadata": {},
    "source": [
-    "### With a connection pool"
+    "### With a connection pool\n",
+    "\n",
+    "This manages a pool of reusable database connections: \n",
+    "- Advantages: Efficient resource utilization, improved performance for frequent connections\n",
+    "- Best for: Applications with many short-lived database operations\n"
    ]
   },
   {
@@ -237,7 +251,11 @@
    "id": "967c95c7-e392-4819-bd71-f29e91c68df3",
    "metadata": {},
    "source": [
-    "### With a connection"
+    "### With a connection\n",
+    "\n",
+    "This creates a single, dedicated connection to the database:\n",
+    "- Advantages: Simple to use, suitable for longer transactions\n",
+    "- Best for: Applications with fewer, longer-lived database operations"
    ]
   },
   {
@@ -252,6 +270,8 @@
     "\n",
     "with Connection.connect(DB_URI, **connection_kwargs) as conn:\n",
     "    checkpointer = PostgresSaver(conn)\n",
+    "    # NOTE: you need to call .setup() the first time you're using your checkpointer\n",
+    "    # checkpointer.setup()\n",
     "    graph = create_react_agent(model, tools=tools, checkpointer=checkpointer)\n",
     "    config = {\"configurable\": {\"thread_id\": \"2\"}}\n",
     "    res = graph.invoke({\"messages\": [(\"human\", \"what's the weather in sf\")]}, config)\n",
@@ -285,7 +305,11 @@
    "id": "49fb52fd-af31-4603-889d-66d783244bce",
    "metadata": {},
    "source": [
-    "### With a connection string"
+    "### With a connection string\n",
+    "\n",
+    "This creates a connection based on a connection string:\n",
+    "- Advantages: Simplicity, encapsulates connection details\n",
+    "- Best for: Quick setup or when connection details are provided as a string"
    ]
   },
   {
@@ -335,7 +359,11 @@
    "id": "c0a47d3e-e588-48fc-a5d4-2145dff17e77",
    "metadata": {},
    "source": [
-    "## Use async connection"
+    "## Use async connection\n",
+    "\n",
+    "This sets up an asynchronous connection to the database. \n",
+    "\n",
+    "Async connections allow non-blocking database operations. This means other parts of your application can continue running while waiting for database operations to complete. It's particularly useful in high-concurrency scenarios or when dealing with I/O-bound operations."
    ]
   },
   {