@getzep/zep-cloud 3.0.1 → 3.0.3

package/examples/langgraph/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "agent",
+  "version": "1.0.0",
+  "description": "A simple agent built with LangGraph.js",
+  "type": "module",
+  "scripts": {
+    "start": "tsx agent.ts"
+  },
+  "dependencies": {
+    "@getzep/zep-cloud": "^2.5.0",
+    "@langchain/core": "^0.3.40",
+    "@langchain/langgraph": "^0.2.51",
+    "@langchain/openai": "^0.4.4",
+    "commander": "^12.0.0",
+    "dotenv": "^16.4.1",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3",
+    "uuid": "^9.0.1"
+  }
+}

package/examples/langgraph/zep-memory.ts

@@ -0,0 +1,271 @@
+// zep-memory.ts
+import { ZepClient } from "@getzep/zep-cloud";
+import { RoleType } from "@getzep/zep-cloud/dist/api";
+import { BaseMessage, AIMessage, HumanMessage, SystemMessage } from "@langchain/core/messages";
+import { v4 as uuidv4 } from "uuid";
+
+/**
+ * ZepMemory adapter for LangGraph
+ * This class provides memory persistence for LangGraph using Zep
+ */
+export class ZepMemory {
+  private client: ZepClient;
+  private sessionId: string;
+  private initialized: boolean = false;
+  private userId?: string;
+
+  /**
+   * Create a new ZepMemory instance
+   * @param apiKey - Zep API key
+   * @param sessionId - Optional session ID, will generate a new one if not provided
+   * @param userId - Optional user ID to associate with the session
+   */
+  constructor(apiKey: string, sessionId?: string, userId?: string) {
+    this.client = new ZepClient({
+      apiKey,
+    });
+    this.sessionId = sessionId || uuidv4();
+    this.userId = userId;
+  }
+
+  /**
+   * Initialize the memory session
+   * @param userId - Optional user ID to associate with the session
+   */
+  async initialize(userId?: string): Promise<void> {
+    if (this.initialized) return;
+
+    try {
+      // Use provided userId or the one from constructor or generate a new one
+      const userIdToUse = userId || this.userId || `user-${uuidv4()}`;
+      this.userId = userIdToUse;
+
+      // Check if user exists, create if not
+      let userExists = false;
+      try {
+        console.log("userIdToUse", userIdToUse);
+        await this.client.user.get(userIdToUse);
+        userExists = true;
+        console.log(`Using existing user: ${userIdToUse}`);
+      } catch (error) {
+        console.log(error.constructor.name);
+        if (error.constructor.name === "NotFoundError") {
+          // User doesn't exist, we'll create it
+          console.log(`User ${userIdToUse} not found, will create`);
+        } else {
+          // For other errors, log and rethrow
+          console.error(`Error checking if user exists: ${userIdToUse}:`, error);
+          throw error;
+        }
+      }
+
+      // Create user if it doesn't exist
+      if (!userExists) {
+        try {
+          await this.client.user.add({
+            userId: userIdToUse,
+            firstName: 'Sarah',
+            lastName: 'Smith',
+            email: `${userIdToUse}@example.com`, // Placeholder email
+          });
+          console.log(`Created new user: ${userIdToUse}`);
+        } catch (error) {
+          console.error(`Failed to create user ${userIdToUse}:`, error);
+          throw error;
+        }
+      }
+
+      // Check if session exists
+      let sessionExists = false;
+      try {
+        await this.client.memory.getSession(this.sessionId);
+        sessionExists = true;
+        console.log(`Using existing session: ${this.sessionId}`);
+      } catch (error) {
+        if (error.constructor.name === "NotFoundError") {
+          // Session doesn't exist, we'll create it
+          console.log(`Session ${this.sessionId} not found, will create`);
+        } else {
+          // For other errors, log and rethrow
+          console.error(`Error checking if session exists ${this.sessionId}:`, error);
+          throw error;
+        }
+      }
+
+      // Create session if it doesn't exist
+      if (!sessionExists) {
+        try {
+          await this.client.memory.addSession({
+            sessionId: this.sessionId,
+            userId: userIdToUse,
+          });
+          console.log(`Created new session: ${this.sessionId}`);
+        } catch (error) {
+          console.error(`Failed to create session ${this.sessionId}:`, error);
+          throw error;
+        }
+      }
+
+      this.initialized = true;
+    } catch (error) {
+      console.error("Failed to initialize Zep memory:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Add a message to memory
+   * @param message - LangChain message to add
+   * @param withContext - Whether to return the Zep context string from memory
+   */
+  async addMessage(message: BaseMessage, withContext: boolean = false): Promise<string | undefined> {
+    if (!this.initialized) {
+      throw new Error("Memory not initialized");
+    }
+
+    try {
+      // Convert LangChain message to Zep message format
+      const zepMessage = this.convertToZepMessage(message);
+      
+      // Add message to Zep memory
+      const response = await this.client.memory.add(this.sessionId, {
+        messages: [zepMessage],
+        returnContext: withContext
+      });
+
+      return response.context;
+    } catch (error) {
+      console.error("Failed to add message to Zep memory:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Add multiple messages to memory
+   * @param messages - Array of LangChain messages to add
+   */
+  async addMessages(messages: BaseMessage[]): Promise<void> {
+    if (!this.initialized) {
+      throw new Error("Memory not initialized");
+    }
+
+    try {
+      // Convert LangChain messages to Zep message format
+      const zepMessages = messages.map(msg => this.convertToZepMessage(msg));
+      
+      // Add messages to Zep memory
+      await this.client.memory.add(this.sessionId, {
+        messages: zepMessages,
+      });
+    } catch (error) {
+      console.error("Failed to add messages to Zep memory:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Get messages from memory
+   * @param limit - Maximum number of messages to retrieve
+   */
+  async getMessages(limit: number = 10): Promise<BaseMessage[]> {
+    if (!this.initialized) {
+      throw new Error("Memory not initialized");
+    }
+
+    try {
+      const response = await this.client.memory.getSessionMessages(this.sessionId, {
+        limit,
+      });
+
+      // Convert Zep messages to LangChain messages
+      return (response.messages || []).map(msg => this.convertToLangChainMessage(msg));
+    } catch (error) {
+      console.error("Failed to get messages from Zep memory:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Get memory with context for the current session
+   * This retrieves messages along with any context
+   */
+  async getMemoryWithContext(): Promise<{ messages: BaseMessage[], context?: string }> {
+    if (!this.initialized) {
+        throw new Error("Memory not initialized");
+    }
+
+    try {
+      const memory = await this.client.memory.get(this.sessionId);
+      
+      // Convert messages to LangChain format
+      const messages = (memory.messages || []).map(msg => this.convertToLangChainMessage(msg));
+      
+      return {
+        messages,
+        context: memory.context,
+      };
+    } catch (error) {
+      console.error("Failed to get memory with context:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Get the session ID
+   */
+  getSessionId(): string {
+    return this.sessionId;
+  }
+
+  /**
+   * Get the user ID
+   */
+  getUserId(): string | undefined {
+    return this.userId;
+  }
+
+  /**
+   * Convert a LangChain message to a Zep message
+   * @param message - LangChain message to convert
+   */
+  private convertToZepMessage(message: BaseMessage) {
+    let roleType: RoleType;
+    let role = "";
+
+    if (message instanceof AIMessage) {
+      roleType = "assistant" as RoleType;
+    } else if (message instanceof HumanMessage) {
+      roleType = "user" as RoleType;
+    } else if (message instanceof SystemMessage) {
+      roleType = "system" as RoleType;
+    } else {
+      // Handle other message types (FunctionMessage, ToolMessage, etc.)
+      roleType = "function" as RoleType;
+    }
+
+    return {
+      content: message.content as string,
+      roleType,
+      role,
+    };
+  }
+
+  /**
+   * Convert a Zep message to a LangChain message
+   * @param message - Zep message to convert
+   */
+  private convertToLangChainMessage(message: any): BaseMessage {
+    const { content, roleType } = message;
+
+    if (roleType === "assistant") {
+      return new AIMessage(content);
+    } else if (roleType === "user") {
+      return new HumanMessage(content);
+    } else if (roleType === "system") {
+      return new SystemMessage(content);
+    } else {
+      // Default to HumanMessage for other types
+      return new HumanMessage(content);
+    }
+  }
+} 

package/examples/memory/chat_shoe_store_history.ts

@@ -0,0 +1,102 @@
+import { RoleType } from "../../src/api/";
+
+export const history: {
+    name: string;
+    role: RoleType;
+    content: string;
+}[] = [
+    {
+        name: "user",
+        role: "user",
+        content: "Hi there, I'm looking for a new pair of shoes. I'm not sure where to start.",
+    },
+    {
+        name: "assistant",
+        role: "assistant",
+        content:
+            "Hello! I'd be happy to help you find the perfect pair of shoes. To get started, could you tell me what brand you're interested in, or if you're open to any brand?",
+    },
+    {
+        name: "user",
+        role: "user",
+        content: "I like Nike and Adidas, but I'm open to other brands too.",
+    },
+    {
+        name: "assistant",
+        role: "assistant",
+        content:
+            "That's great! It's important to find the right shoe for your needs. Could you tell me what you'll be using these shoes for mainly? For example, are they for running, basketball, or casual wear?",
+    },
+    {
+        name: "user",
+        role: "user",
+        content: "I'll be using them for running.",
+    },
+    {
+        name: "assistant",
+        role: "assistant",
+        content:
+            "Fantastic! Now, could you please provide me with your shoe size and foot width? This information will help me narrow down the options for you.",
+    },
+    {
+        name: "user",
+        role: "user",
+        content: "I wear a men's size 10, and I'm not sure about the foot width.",
+    },
+    {
+        name: "assistant",
+        role: "assistant",
+        content:
+            "Thank you. Based on your size, I'll make sure to suggest shoes with a wide range of sizes and widths available.",
+    },
+    {
+        name: "user",
+        role: "user",
+        content: "I have a bit of a pronation issue. Do I need to consider that while choosing shoes?",
+    },
+    {
+        name: "assistant",
+        role: "assistant",
+        content:
+            "Yes, pronation is essential when choosing running shoes. It refers to the way your foot rolls inward or outward when you walk or run. For pronation issues, stability or motion control shoes are usually recommended. I'll make sure to consider this in my suggestions.",
+    },
+    {
+        name: "user",
+        role: "user",
+        content: "Great, I have a budget of around $120.",
+    },
+    {
+        name: "assistant",
+        role: "assistant",
+        content:
+            "Perfect! I'll make sure to find the best running shoes that fit your preferences, taking into account your brand preferences, running needs, size, and budget.",
+    },
+    {
+        name: "assistant",
+        role: "assistant",
+        content:
+            "I've found a few great options for you. The first one is the Brooks Ghost 14, which is known for its cushioning and support, ideal for runners with pronation issues. It's available in your size, and it's within your budget.",
+    },
+    {
+        name: "user",
+        role: "user",
+        content: "I've heard good things about Brooks, but I was kind of hoping to get a Nike or an Adidas shoe.",
+    },
+    {
+        name: "assistant",
+        role: "assistant",
+        content:
+            "I understand. In that case, I'd recommend the Adidas Ultraboost 21. It's a popular choice among runners for its comfort, energy return, and stability. Plus, it's on sale at $129.99 today, almost within your budget.",
+    },
+    {
+        name: "user",
+        role: "user",
+        content: "They're nice looking. Yes, I think I'll go with those.",
+    },
+    {
+        name: "assistant",
+        role: "assistant",
+        content:
+            "Excellent choice! To complete the purchase, I'll need you to provide your credit card information in our secure payment form. This will allow us to process your order and ensure a smooth delivery.",
+    },
+];

package/examples/memory/memory_example.ts

@@ -0,0 +1,103 @@
+import { v4 as uuidv4 } from "uuid";
+import { CreateUserRequest, Message, NotFoundError } from "../../src/api";
+import { ZepClient } from "../../src";
+
+// @ts-ignore
+import { history } from "./chat_shoe_store_history";
+
+function sleep(ms: number) {
+    const date = Date.now();
+    let currentDate = 0;
+    do {
+        currentDate = Date.now();
+    } while (currentDate - date < ms);
+}
+
+async function main() {
+    const projectApiKey = process.env.ZEP_API_KEY;
+
+    const client = new ZepClient({
+        apiKey: projectApiKey,
+    });
+
+    // Create a user
+    const userId = uuidv4();
+    const userRequest: CreateUserRequest = {
+        userId: `amy${userId}`,
+        metadata: { role: "admin" },
+        email: "amy@acme.com",
+        firstName: "Amy",
+        lastName: "Wu",
+    };
+    const user = await client.user.add(userRequest);
+    console.debug("Created user ", user);
+
+    // Example thread ID
+    const threadId = uuidv4();
+
+    // Add thread associated with the above user
+    try {
+        await client.thread.create({
+            threadId: threadId,
+            userId: user.userId!,
+        });
+        console.debug("Adding new thread ", threadId);
+    } catch (error) {
+        console.debug("Got error:", error);
+    }
+
+    // Get thread
+    try {
+        const thread = await client.thread.get(threadId);
+        console.debug("Retrieved thread ", thread);
+    } catch (error) {
+        console.debug("Got error:", error);
+    }
+
+    // Add memory. We could do this in a batch, but we'll do it one by one rather to
+    // ensure that summaries and other artifacts are generated correctly.
+    try {
+        for (const { role, name, content } of history) {
+            await client.thread.addMessages(threadId, {
+                messages: [{ role, name, content }],
+            });
+        }
+        console.debug("Added new messages for thread ", threadId);
+    } catch (error) {
+        console.debug("Got error:", error);
+    }
+
+    console.log("Sleeping for 5 seconds to let background tasks complete...");
+    sleep(5000); // Sleep for 5 seconds
+    console.log("Done sleeping!");
+
+    // Get newly added memory
+    try {
+        console.debug("Getting user context for the thread ", threadId);
+        const memory = await client.thread.getUserContext(threadId, {mode: "summary"});
+        console.log("Context: ", memory.context);
+        if (memory.context) {
+            console.debug("Memory Context: ", memory.context);
+        }
+    } catch (error) {
+        if (error instanceof NotFoundError) {
+            console.error("thread not found:", error.message);
+        } else {
+            console.error("Got error:", error);
+        }
+    }
+
+    // get thread messages
+    try {
+        const threadMessagesResult = await client.thread.get(threadId, { limit: 10, cursor: 1 });
+        console.debug("thread messages: ", JSON.stringify(threadMessagesResult));
+    } catch (error) {
+        if (error instanceof NotFoundError) {
+            console.error("thread not found:", error.message);
+        } else {
+            console.error("Got error:", error);
+        }
+    }
+}
+
+main();

package/examples/users/users.ts

@@ -0,0 +1,79 @@
+import { v4 as uuidv4 } from "uuid";
+import { ZepClient } from "../../src";
+import { CreateUserRequest, UpdateUserRequest } from "../../src/api";
+
+async function main() {
+    const projectApiKey = process.env.ZEP_API_KEY;
+
+    const client = new ZepClient({
+        apiKey: projectApiKey,
+    });
+
+    // Create multiple users
+    for (let i = 0; i < 3; i++) {
+        const userId = uuidv4();
+        const userRequest: CreateUserRequest = {
+            userId: userId,
+            email: `user${i}@example.com`,
+            firstName: `John${i}`,
+            lastName: `Doe${i}`,
+        };
+
+        try {
+            const user = await client.user.add(userRequest);
+            console.log(`Created user ${i + 1}: ${user.userId}`);
+        } catch (e) {
+            console.log(`Failed to create user ${i + 1}: ${e}`);
+        }
+    }
+
+    // Update the first user
+    const firstUser = (await client.user.listOrdered())?.users?.[0];
+    if (!firstUser) {
+        console.log("No user found");
+        return;
+    }
+    const userId = firstUser.userId;
+    const userRequest: UpdateUserRequest = {
+        email: "updated_user@example.com",
+        firstName: "UpdatedJohn",
+        lastName: "UpdatedDoe",
+    };
+
+    try {
+        if (!userId) {
+            throw new Error("No user found");
+        }
+        const updatedUser = await client.user.update(userId, userRequest);
+        console.log(`Updated user: ${updatedUser}`);
+    } catch (e) {
+        console.log(`Failed to update user: ${e}`);
+    }
+
+    // Delete the second user
+    const userIdToDelete = (await client.user.listOrdered())?.users?.[1]?.userId;
+    try {
+        if (!userIdToDelete) {
+            throw new Error("No user found");
+        }
+        await client.user.delete(userIdToDelete);
+        console.log(`Deleted user: ${userIdToDelete}`);
+    } catch (e) {
+        console.log(`Failed to delete user: ${e}`);
+    }
+
+    // List all users
+    try {
+        console.log("All users:");
+        const usersResult = await client.user.listOrdered({ pageSize: 10, pageNumber: 1 });
+        if (usersResult && usersResult.users) {
+            for (const user of usersResult.users) {
+                console.log(user.userId);
+            }
+        }
+    } catch (e) {
+        console.log(`Failed to list users: ${e}`);
+    }
+}
+
+main();

package/index.js

@@ -0,0 +1,46 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.composeContextString = exports.ZepTimeoutError = exports.ZepError = exports.ZepEnvironment = exports.ZepClient = exports.Zep = void 0;
+exports.Zep = __importStar(require("./api"));
+var wrapper_1 = require("./wrapper");
+Object.defineProperty(exports, "ZepClient", { enumerable: true, get: function () { return wrapper_1.ZepClient; } });
+var environments_1 = require("./environments");
+Object.defineProperty(exports, "ZepEnvironment", { enumerable: true, get: function () { return environments_1.ZepEnvironment; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "ZepError", { enumerable: true, get: function () { return errors_1.ZepError; } });
+Object.defineProperty(exports, "ZepTimeoutError", { enumerable: true, get: function () { return errors_1.ZepTimeoutError; } });
+var contextString_1 = require("./contextString");
+Object.defineProperty(exports, "composeContextString", { enumerable: true, get: function () { return contextString_1.composeContextString; } });

package/jest.config.mjs

@@ -0,0 +1,42 @@
+/** @type {import('jest').Config} */
+export default {
+    preset: "ts-jest",
+    testEnvironment: "node",
+    projects: [
+        {
+            displayName: "unit",
+            preset: "ts-jest",
+            testEnvironment: "node",
+            moduleNameMapper: {
+                "^(\.{1,2}/.*)\.js$": "$1",
+            },
+            roots: ["<rootDir>/tests"],
+            testPathIgnorePatterns: ["\.browser\.(spec|test)\.[jt]sx?$", "/tests/wire/"],
+            setupFilesAfterEnv: [],
+        },
+        {
+            displayName: "browser",
+            preset: "ts-jest",
+            testEnvironment: "<rootDir>/tests/BrowserTestEnvironment.ts",
+            moduleNameMapper: {
+                "^(\.{1,2}/.*)\.js$": "$1",
+            },
+            roots: ["<rootDir>/tests"],
+            testMatch: ["<rootDir>/tests/unit/**/?(*.)+(browser).(spec|test).[jt]s?(x)"],
+            setupFilesAfterEnv: [],
+        },
+        ,
+        {
+            displayName: "wire",
+            preset: "ts-jest",
+            testEnvironment: "node",
+            moduleNameMapper: {
+                "^(\.{1,2}/.*)\.js$": "$1",
+            },
+            roots: ["<rootDir>/tests/wire"],
+            setupFilesAfterEnv: ["<rootDir>/tests/mock-server/setup.ts"],
+        },
+    ],
+    workerThreads: false,
+    passWithNoTests: true,
+};