Zep

https://help.getzep.com/welcome
Admin
Zep is a memory layer for AI assistants and agents that continuously learns from user interactions...
Tokens:81,798
Snippets:523
Trust Score:8.4
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Zep Go SDK

Source: https://help.getzep.com/welcome/sdks

This snippet shows how to fetch the Zep Go SDK for your Go project. It uses the `go get` command to download and install the `github.com/getzep/zep-go/v2` module, making Zep's Go client available for use.

```Go
go get github.com/getzep/zep-go/v2
```

--------------------------------

### Install Zep Python SDK with pip

Source: https://help.getzep.com/welcome/quickstart

Installs the Zep Python SDK using the pip package manager. It is recommended to set up a virtual environment before installation.

```Python
$ pip install zep-cloud
```

--------------------------------

### Install Zep Python SDK using pip

Source: https://help.getzep.com/welcome/sdks

Instructions to install the Zep Python SDK using the pip package manager. It is recommended to set up a virtual environment before installation.

```bash
$ pip install zep-cloud
```

--------------------------------

### Get User API Success Response Example

Source: https://help.getzep.com/welcome/sdk-reference/user/get

Provides an example JSON payload returned by the Get User API upon successful retrieval of user data, showing typical fields and their placeholder values.

```json
{
  "created_at": "created_at",
  "deleted_at": "deleted_at",
  "email": "email",
  "fact_rating_instruction": {
    "examples": {
      "high": "high",
      "low": "low",
      "medium": "medium"
    },
    "instruction": "instruction"
  },
  "first_name": "first_name",
  "id": 1,
  "last_name": "last_name",
  "metadata": {
    "key": "value"
  },
  "project_uuid": "project_uuid",
  "session_count": 1,
  "updated_at": "updated_at",
  "user_id": "user_id",
  "uuid": "uuid"
}
```

--------------------------------

### Install Zep Go SDK

Source: https://help.getzep.com/welcome/quickstart

This snippet shows how to fetch the Zep Go SDK. After setting up your Go project, use this command to add the Zep library to your dependencies, enabling Go applications to interact seamlessly with Zep Cloud services.

```Go
go get github.com/getzep/zep-go/v2
```

--------------------------------

### Install Zep Cloud SDK with pnpm

Source: https://help.getzep.com/welcome/sdks

This snippet demonstrates how to install the Zep Cloud SDK using the pnpm package manager. It adds the @getzep/zep-cloud package to your project dependencies, enabling you to use Zep's functionalities.

```pnpm
npm install @getzep/zep-cloud
```

--------------------------------

### Install Python Dependencies for LangGraph and Zep

Source: https://help.getzep.com/welcome/ecosystem/langgraph-memory

This command installs the necessary Python packages, including `zep-cloud`, `langchain-openai`, `langgraph`, and `ipywidgets`, required to run the LangGraph agent example with Zep memory.

```Shell
pip install zep-cloud langchain-openai langgraph ipywidgets
```

--------------------------------

### Import necessary Graphiti libraries

Source: https://help.getzep.com/welcome/graphiti/graphiti/quick-start

This code snippet imports the essential Python libraries required to work with Graphiti, including `asyncio`, `json`, `logging`, `os`, `datetime`, `dotenv`, `Graphiti` from `graphiti_core`, `EpisodeType`, and `NODE_HYBRID_SEARCH_RRF` for search configurations. Users should ensure Graphiti is installed before running this.

```Python
import asyncio
import json
import logging
import os
from datetime import datetime, timezone
from logging import INFO

from dotenv import load_dotenv

from graphiti_core import Graphiti
from graphiti_core.nodes import EpisodeType
from graphiti_core.search.search_config_recipes import NODE_HYBRID_SEARCH_RRF
```

--------------------------------

### Initialize Graphiti with Neo4j Connection and Indices

Source: https://help.getzep.com/welcome/graphiti/graphiti/quick-start

Connects Graphiti to a Neo4j database and builds necessary indices and constraints. This setup is a prerequisite for using other Graphiti functionalities and should be performed once. It also includes error handling and ensures the connection is properly closed.

```Python
# Initialize Graphiti with Neo4j connection
graphiti = Graphiti(neo4j_uri, neo4j_user, neo4j_password)

try:
    # Initialize the graph database with graphiti's indices. This only needs to be done once.
    await graphiti.build_indices_and_constraints()

    # Additional code will go here

finally:
    # Close the connection
    await graphiti.close()
    print('\nConnection closed')
```

--------------------------------

### Example API Response for Get Users

Source: https://help.getzep.com/welcome/sdk-reference/user/list-ordered

An example JSON response structure returned by the `/api/v2/users-ordered` endpoint, showing user data, pagination details, and typical user object properties.

```JSON
{
  "row_count": 1,
  "total_count": 1,
  "users": [
    {
      "created_at": "created_at",
      "deleted_at": "deleted_at",
      "email": "email",
      "first_name": "first_name",
      "id": 1,
      "last_name": "last_name",
      "metadata": {
        "key": "value"
      },
      "project_uuid": "project_uuid",
      "session_count": 1,
      "updated_at": "updated_at",
      "user_id": "user_id",
      "uuid": "uuid"
    }
  ]
}
```

--------------------------------

### Install Zep Cloud SDK with pnpm

Source: https://help.getzep.com/welcome/quickstart

This snippet demonstrates how to install the Zep Cloud JavaScript/TypeScript SDK using the pnpm package manager. This is the initial step to integrate Zep Cloud into your Node.js or TypeScript project, ensuring all necessary dependencies are available.

```pnpm
npm install @getzep/zep-cloud
```

--------------------------------

### Example Prompt for Guiding LLMs in Progressive Data Extraction

Source: https://help.getzep.com/welcome/structured-data-extraction

This example prompt illustrates how to instruct an LLM to progressively collect data. It shows how to inform the LLM about already collected data and remaining required fields, guiding it to collect information gradually rather than asking for everything at once.

```Text
You have already collected the following data:
- Company name: Acme Inc.
- Lead name: John Doe
- Lead email: [email protected]

You still need to collect the following data:
- Lead phone number
- Lead budget
- Product name
- Zip code

Do not ask for all fields at once. Rather, work the fields
into your conversation with the user and gradually collect the data.
```

--------------------------------

### Example Response for Get Session Memory

Source: https://help.getzep.com/welcome/sdk-reference/memory/get

An example JSON structure returned upon a successful GET request to retrieve session memory.

```JSON
{
  "context": "context",
  "facts": [
    "facts"
  ],
  "messages": [
    {
      "content": "content",
      "role_type": "norole",
      "created_at": "created_at",
      "metadata": {
        "key": "value"
      },
      "processed": true,
      "role": "role",
      "token_count": 1,
      "updated_at": "updated_at",
      "uuid": "uuid"
    }
  ],
  "metadata": {
    "key": "value"
  },
  "relevant_facts": [
    {
      "content": "content",
      "created_at": "created_at",
      "fact": "fact",
      "uuid": "uuid",
      "expired_at": "expired_at",
      "invalid_at": "invalid_at",
      "name": "name",
      "rating": 1.1,
      "source_node_name": "source_node_name",
      "target_node_name": "target_node_name",
      "valid_at": "valid_at"
    }
  ],
  "summary": {
    "content": "content",
    "created_at": "created_at",
    "metadata": {
      "key": "value"
    },
    "related_message_uuids": [
      "related_message_uuids"
    ],
    "token_count": 1,
    "uuid": "uuid"
  }
}
```

--------------------------------

### Performing Node Search with Predefined Recipes in Graphiti (Python)

Source: https://help.getzep.com/welcome/graphiti/graphiti/quick-start

This example illustrates how to perform a direct node search using Graphiti's predefined search recipes. It specifically utilizes the `NODE_HYBRID_SEARCH_RRF` recipe, which is optimized for retrieving nodes instead of edges, and shows how to modify the search limit for the recipe.

```Python
# Example: Perform a node search using _search method with standard recipes
print(
    '\nPerforming node search using _search method with standard recipe NODE_HYBRID_SEARCH_RRF:'
)

# Use a predefined search configuration recipe and modify its limit
node_search_config = NODE_HYBRID_SEARCH_RRF.model_copy(deep=True)
node_search_config.limit = 5  # Limit to 5 results

# Execute the node search
node_search_results = await graphiti._search(
    query='California Governor',
    config=node_search_config,
)

# Print node search results
print('\nNode Search Results:')
for node in node_search_results.nodes:
    print(f'Node UUID: {node.uuid}')
    print(f'Node Name: {node.name}')
    node_summary = node.summary[:100] + '...' if len(node.summary) > 100 else node.summary
    print(f'Content Summary: {node_summary}')
    print(f"Node Labels: {', '.join(node.labels)}")
    print(f'Created At: {node.created_at}')
    if hasattr(node, 'attributes') and node.attributes:
        print('Attributes:')
        for key, value in node.attributes.items():
            print(f'  {key}: {value}')
        print('---')
```

--------------------------------

### Integrate Zep as a LangChain LangGraph Tool

Source: https://help.getzep.com/welcome/sdks

This example demonstrates how to integrate Zep's memory retrieval methods as an agentic tool within a LangChain LangGraph application. It shows the creation of a `search_facts` tool that queries a user's graph for relevant information.

```Python
from zep_cloud.client import AsyncZep

from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, MessagesState
from langgraph.prebuilt import ToolNode

zep = AsyncZep(api_key=os.environ.get('ZEP_API_KEY'))

@tool
async def search_facts(state: MessagesState, query: str, limit: int = 5):
    """Search for facts in all conversations had with a user.

    Args:
        state (MessagesState): The Agent's state.
        query (str): The search query.
        limit (int): The number of results to return. Defaults to 5.
    Returns:
        list: A list of facts that match the search query.
    """
    search_results = await zep.graph.search(
        user_id=state['user_name'],
        query=query,
        limit=limit,
    )

    return [edge.fact for edge in search_results.edges]

tools = [search_facts]
tool_node = ToolNode(tools)
llm = ChatOpenAI(model='gpt-4o-mini', temperature=0).bind_tools(tools)
```

--------------------------------

### Install Graphiti Core Library

Source: https://help.getzep.com/welcome/graphiti/graphiti/installation

Instructions to install the core Graphiti library using either pip or Poetry.

```Python
pip install graphiti-core
```

```Python
poetry add graphiti-core
```

--------------------------------

### Get User Sessions API Reference

Source: https://help.getzep.com/welcome/sdk-reference/user/get-sessions

Comprehensive API documentation for retrieving user sessions. Includes HTTP method, endpoint, path parameters, request headers, successful response schema, example response, and error handling.

```APIDOC
GET /api/v2/users/:userId/sessions

Path parameters:
  userId: string (Required)
    User ID

Headers:
  Authorization: string (Required)
    Header authentication of the form Api-Key <token>

Response (200 OK):
  Returns all sessions for a user.
  Schema:
    classifications: map from strings to strings or null
    created_at: string or null
    deleted_at: string or null
    ended_at: string or null
    fact_rating_instruction: object or null (Deprecated, Show 2 properties)
    facts: list of strings or null (Deprecated)
    id: integer or null
    metadata: map from strings to any or null (Deprecated)
    project_uuid: string or null
    session_id: string or null
    updated_at: string or null (Deprecated)
    user_id: string or null
    uuid: string or null

  Example Response:
  [
    {
      "classifications": {
        "key": "value"
      },
      "created_at": "created_at",
      "deleted_at": "deleted_at",
      "ended_at": "ended_at",
      "fact_rating_instruction": {
        "instruction": "instruction"
      },
      "facts": [
        "facts"
      ],
      "id": 1,
      "metadata": {
        "key": "value"
      },
      "project_uuid": "project_uuid",
      "session_id": "session_id",
      "updated_at": "updated_at",
      "user_id": "user_id",
      "uuid": "uuid"
    }
  ]

Errors:
  500: User Get Sessions Request Internal Server Error
```

--------------------------------

### Use Zep as an Agentic Tool

Source: https://help.getzep.com/welcome/quickstart

Zep’s memory retrieval methods can be used as agentic tools, enabling your agent to query Zep for relevant information.
The example below shows how to create a LangChain LangGraph tool to search for facts in a user’s graph.

```Python
from zep_cloud.client import AsyncZep

from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, MessagesState
from langgraph.prebuilt import ToolNode

zep = AsyncZep(api_key=os.environ.get('ZEP_API_KEY'))

@tool
async def search_facts(state: MessagesState, query: str, limit: int = 5):
    """Search for facts in all conversations had with a user.

    Args:
        state (MessagesState): The Agent's state.
        query (str):
        limit (int): The number of results to return. Defaults to 5.
    Returns:
        list: A list of facts that match the search query.
    """
    search_results = await zep.graph.search(
        user_id=state['user_name'],
        query=query,
        limit=limit,
    )

    return [edge.fact for edge in search_results.edges]

tools = [search_facts]
tool_node = ToolNode(tools)
llm = ChatOpenAI(model='gpt-4o-mini', temperature=0).bind_tools(tools)
```

--------------------------------

### Python Client Example to Get a Group

Source: https://help.getzep.com/welcome/sdk-reference/group/get-group

Demonstrates how to use the Zep Python SDK to retrieve a group by its ID. It requires an API key for authentication.

```Python
from zep_cloud.client import Zep

client = Zep(
    api_key="YOUR_API_KEY",
)
client.group.get_group(
    group_id="groupId",
)
```

--------------------------------

### Install Graphiti Google Gemini Integration Package

Source: https://help.getzep.com/welcome/graphiti/graphiti/installation

This command installs the `google-genai` extra for `graphiti-core` using Poetry, enabling integration with Google Gemini.

```bash
poetry add "graphiti-core[google-genai]"
```

--------------------------------

### Search Zep Graph for Edges and Nodes

Source: https://help.getzep.com/welcome/sdks

This snippet illustrates how to search for specific information within a user's or group's graph using the `client.graph.search` method. It provides examples for searching edges and nodes in a user's graph, and searching edges in a group graph.

```Python
# Search for edges in a user's graph
edge_results = client.graph.search(
    user_id=user_id,
    query="What projects is Jane working on?",
    scope="edges",  # Default is "edges"
    limit=5
)

# Search for nodes in a user's graph
node_results = client.graph.search(
    user_id=user_id,
    query="Jane Smith",
    scope="nodes",
    limit=5
)

# Search in a group graph
group_results = client.graph.search(
    group_id=group_id,
    query="Project Alpha",
    scope="edges",
    limit=5
)
```

--------------------------------

### Example JSON Response for Get Group (200 OK)

Source: https://help.getzep.com/welcome/sdk-reference/group/get-group

Illustrates the structure and typical fields of a successful 200 OK response when retrieving a group, including metadata and group-specific properties.

```JSON
{
  "created_at": "created_at",
  "description": "description",
  "external_id": "external_id",
  "fact_rating_instruction": {
    "examples": {
      "high": "high",
      "low": "low",
      "medium": "medium"
    },
    "instruction": "instruction"
  },
  "group_id": "group_id",
  "id": 1,
  "name": "name",
  "project_uuid": "project_uuid",
  "uuid": "uuid"
}
```

--------------------------------

### Get User API Request Parameters and Headers

Source: https://help.getzep.com/welcome/sdk-reference/user/get

Details the required path parameters and authentication headers for making a successful Get User API request.

```APIDOC
Path Parameters:
  userId:
    Type: string
    Required: true
    Description: The user_id of the user to get.

Headers:
  Authorization:
    Type: string
    Required: true
    Description: Header authentication of the form Api-Key <token>
```

--------------------------------

### Retrieve User Node with Zep Python SDK

Source: https://help.getzep.com/welcome/sdk-reference/user/get-node

Example demonstrating how to use the Zep Python SDK to fetch a user's node by providing the user ID and API key for client initialization.

```Python
from zep_cloud.client import Zep

client = Zep(
    api_key="YOUR_API_KEY",
)
client.user.get_node(
    user_id="userId",
)
```

--------------------------------

### Add Business Data to Zep Graph

Source: https://help.getzep.com/welcome/sdks

This snippet demonstrates how to add text and JSON data to a user's graph or a group graph using the `client.graph.add` method. It shows examples for adding text to a user's graph, JSON data to a user's graph, and text data to a shared group graph.

```Python
# Add text data to a user's graph
new_episode = client.graph.add(
    user_id=user_id,
    type="text",
    data="Jane Smith is a senior software engineer who has been with Acme Corp for 5 years."
)
print("New episode created:", new_episode)
# Add JSON data to a user's graph
import json
json_data = {
    "employee": {
        "name": "Jane Smith",
        "position": "Senior Software Engineer",
        "department": "Engineering",
        "projects": ["Project Alpha", "Project Beta"]
    }
}
client.graph.add(
    user_id=user_id,
    type="json",
    data=json.dumps(json_data)
)

# Add data to a group graph (shared across users)
group_id = "engineering_team"
client.graph.add(
    group_id=group_id,
    type="text",
    data="The engineering team is working on Project Alpha and Project Beta."
)
```

--------------------------------

### Example Tool Picking Classification Result

Source: https://help.getzep.com/welcome/dialog-classification

An example of the classified tool, demonstrating the output of the tool picking classification for a user query.

```Text
"research topics or find information with a web search"
```

--------------------------------

### Example JSON Response for Get Group Edges

Source: https://help.getzep.com/welcome/sdk-reference/graph/edge/get-by-group-id

An example of the successful JSON response returned by the 'Get Group Edges' API endpoint, illustrating the structure and typical values of an edge object.

```JSON
[
  {
    "created_at": "created_at",
    "fact": "fact",
    "name": "name",
    "source_node_uuid": "source_node_uuid",
    "target_node_uuid": "target_node_uuid",
    "uuid": "uuid",
    "attributes": {
      "key": "value"
    },
    "episodes": [
      "episodes"
    ],
    "expired_at": "expired_at",
    "invalid_at": "invalid_at",
    "valid_at": "valid_at"
  }
]
```

--------------------------------

### API Reference for Get Users Endpoint

Source: https://help.getzep.com/welcome/sdk-reference/user/list-ordered

Detailed API documentation for the GET `/api/v2/users-ordered` endpoint, including required headers, optional query parameters for pagination, the structure of the successful response, and possible error codes.

```APIDOC
Endpoint: GET /api/v2/users-ordered
Description: Returns all users.

Headers:
  Authorization:
    Type: string
    Required: true
    Description: Header authentication of the form Api-Key <token>

Query Parameters:
  pageNumber:
    Type: integer
    Optional: true
    Description: Page number for pagination, starting from 1
  pageSize:
    Type: integer
    Optional: true
    Description: Number of users to retrieve per page

Response (200 Retrieved):
  row_count:
    Type: integer or null
  total_count:
    Type: integer or null
  users:
    Type: list of objects or null
    Properties:
      created_at: string
      deleted_at: string
      email: string
      first_name: string
      id: integer
      last_name: string
      metadata: object (key: value)
      project_uuid: string
      session_count: integer
      updated_at: string
      user_id: string
      uuid: string

Errors:
  400: User List Ordered Request Bad Request Error
  500: User List Ordered Request Internal Server Error
```

--------------------------------

### Initialize Zep Client with API Key (Python)

Source: https://help.getzep.com/welcome/quickstart

This snippet demonstrates how to initialize the Zep client in Python using your API key. The Python SDK supports both synchronous and asynchronous usage; for async operations, import `AsyncZep` instead of `Zep` and remember to `await` client calls.

```Python
import os
from zep_cloud.client import Zep

API_KEY = os.environ.get('ZEP_API_KEY')

client = Zep(
    api_key=API_KEY,
)
```

--------------------------------

### Example API Response for Get Entity Edges (200 OK)

Source: https://help.getzep.com/welcome/sdk-reference/graph/node/get-edges

This JSON example illustrates the structure of a successful (200 OK) response from the Get Entity Edges API. It shows a list containing a single edge object with various properties like UUIDs, timestamps, and attributes.

```JSON
[
  {
    "created_at": "created_at",
    "fact": "fact",
    "name": "name",
    "source_node_uuid": "source_node_uuid",
    "target_node_uuid": "target_node_uuid",
    "uuid": "uuid",
    "attributes": {
      "key": "value"
    },
    "episodes": [
      "episodes"
    ],
    "expired_at": "expired_at",
    "invalid_at": "invalid_at",
    "valid_at": "valid_at"
  }
]
```

--------------------------------

### Create a New Zep User (Python)

Source: https://help.getzep.com/welcome/quickstart

This snippet shows how to create a new user in Zep using the Python SDK. User-level data, such as extracted facts and entities, is stored here and is designed to be accessible across all of the user's associated sessions.

```Python
# Create a new user
user_id = "user123"
new_user = client.user.add(
    user_id=user_id,
    email="[email protected]",
    first_name="Jane",
    last_name="Smith",
)
```

--------------------------------

### Example 200 OK Response for List Document Collections API

Source: https://help.getzep.com/welcome/sdk-reference/deprecated/document/list-collections

An example JSON response body returned by the Zep API when successfully retrieving a list of document collections via the GET /api/v2/collections endpoint.

```JSON
[
  [
    {
      "created_at": "created_at",
      "description": "description",
      "document_count": 1,
      "document_embedded_count": 1,
      "embedding_dimensions": 1,
      "embedding_model_name": "embedding_model_name",
      "is_auto_embedded": true,
      "is_indexed": true,
      "is_normalized": true,
      "metadata": {
        "key": "value"
      },
      "name": "name",
      "updated_at": "updated_at",
      "uuid": "uuid"
    }
  ]
]
```

--------------------------------

### Configure Zep API Key in .env file

Source: https://help.getzep.com/welcome/quickstart

This snippet illustrates how to set up your Zep API key in a .env file. This is a common and recommended practice for securely managing sensitive credentials outside of your codebase, preventing them from being hardcoded directly into your application.

```Text
ZEP_API_KEY=your_api_key_here
```

--------------------------------

### Example Zep Memory Context Output

Source: https://help.getzep.com/welcome/ecosystem/langgraph-memory

This example illustrates the structure and content of the `memory.context` object. It shows how facts and entities are represented, including their valid date ranges and summaries, providing a detailed view of the conversational context maintained by Zep.

```TEXT
FACTS and ENTITIES represent relevant context to the current conversation.

# These are the most relevant facts and their valid date ranges
# format: FACT (Date range: from - to)
<FACTS>
- Daniel99db is worried about his sick dog. (2025-01-24 02:11:54 - present)
- Daniel Chalef is worried about his sick dog. (2025-01-24 02:11:54 - present)
- The assistant asks how the user is feeling. (2025-01-24 02:11:51 - present)
- Daniel99db has been a bit stressful lately due to his dog. (2025-01-24 02:11:53 - present)
- Daniel99db has been a bit stressful lately due to work. (2025-01-24 02:11:53 - present)
- Daniel99db is a user. (2025-01-24 02:11:51 - present)
- user has the id of Daniel99db (2025-01-24 02:11:50 - present)
- user has the name of Daniel Chalef (2025-01-24 02:11:50 - present)
</FACTS>
# These are the most relevant entities
# ENTITY_NAME: entity summary
<ENTITIES>
- worried: Daniel Chalef (Daniel99db) is feeling stressed lately, primarily due to work-related issues and concerns about his sick dog, which has made him worried.
- Daniel99db: Daniel99db, or Daniel Chalef, is currently experiencing stress primarily due to work-related issues and concerns about his sick dog. Despite these challenges, he has shown a desire for interaction by initiating conversations, indicating his openness to communication.
- sick: Daniel Chalef, also known as Daniel99db, is feeling stressed lately, primarily due to work-related issues and concerns about his sick dog. He expresses worry about his dog's health.
- Daniel Chalef: Daniel Chalef, also known as Daniel99db, has been experiencing stress recently, primarily related to work issues and concerns about his sick dog. Despite this stress, he has been feeling generally well and has expressed a desire to connect with others, as indicated by his friendly greeting, "Hi there?".
- dog: Daniel99db, also known as Daniel Chalef, mentioned that he has been feeling a bit stressed lately, which is related to both work and his dog.
- work: Daniel Chalef, also known as Daniel99db, has been experiencing stress lately, primarily related to work.
- feeling: The assistant initiates a conversation by asking how the user is feeling today, indicating a willingness to listen and provide support.
</ENTITIES>
```

--------------------------------

### Configure Zep API Key in .env File

Source: https://help.getzep.com/welcome/sdks

This snippet illustrates how to set up your Zep API key in a `.env` file. This is a common practice for securely managing sensitive credentials, ensuring they are not hardcoded directly into your application.

```dotenv
ZEP_API_KEY=your_api_key_here
```

--------------------------------

### API Reference: Get All Sessions

Source: https://help.getzep.com/welcome/sdk-reference/memory/list-sessions

Detailed API documentation for retrieving a paginated list of all sessions. Includes endpoint, authentication, query parameters, and response schema.

```APIDOC
Endpoint: GET /api/v2/sessions-ordered

Headers:
  Authorization: string (Required)
    Description: Header authentication of the form Api-Key <token>

Query Parameters:
  page_number: integer (Optional)
    Description: Page number for pagination, starting from 1
  page_size: integer (Optional)
    Description: Number of sessions to retrieve per page.
  order_by: string (Optional)
    Description: Field to order the results by: created_at, updated_at, user_id, session_id.
  asc: boolean (Optional)
    Description: Order direction: true for ascending, false for descending.

Response (200 OK):
  Description: List of sessions
  Schema:
    {
      "response_count": 1,
      "sessions": [
        {
          "classifications": {
            "key": "value"
          },
          "created_at": "created_at",
          "deleted_at": "deleted_at",
          "ended_at": "ended_at",
          "facts": [
            "facts"
          ],
          "id": 1,
          "metadata": {
            "key": "value"
          },
          "project_uuid": "project_uuid",
          "session_id": "session_id",
          "updated_at": "updated_at",
          "user_id": "user_id",
          "uuid": "uuid"
        }
      ],
      "total_count": 1
    }

Errors:
  400: Memory List Sessions Request Bad Request Error
  500: Memory List Sessions Request Internal Server Error
```

--------------------------------

### JSON Example: Successful Get Entity Types Response

Source: https://help.getzep.com/welcome/sdk-reference/graph

A sample JSON payload representing a successful response from the Get Entity Types API, showing the structure for `edge_types` and `entity_types`.

```json
{
  "edge_types": [
    {
      "description": "description",
      "name": "name",
      "properties": [
        {
          "description": "description",
          "name": "name",
          "type": "Text"
        }
      ],
      "source_targets": [
        {}
      ]
    }
  ],
  "entity_types": [
    {
      "description": "description",
      "name": "name",
      "properties": [
        {
          "description": "description",
          "name": "name",
          "type": "Text"
        }
      ]
    }
  ]
}
```

--------------------------------

### Initialize Zep Client with API Key in Python

Source: https://help.getzep.com/welcome/sdks

This snippet demonstrates how to initialize the Zep client using your API key in Python. The client object is essential for interacting with the Zep API, allowing you to perform operations like managing users, sessions, and memory.

```Python
import os
from zep_cloud.client import Zep

API_KEY = os.environ.get('ZEP_API_KEY')

client = Zep(
    api_key=API_KEY,
)
```

--------------------------------

### Source .env file in terminal

Source: https://help.getzep.com/welcome/quickstart

This snippet shows how to load environment variables from a .env file into your current terminal session. This action makes the ZEP_API_KEY available to your applications, allowing for proper client initialization without exposing the key in code.

```Shell
source .env
```

--------------------------------

### REST API Endpoint and Success Response for Get DocumentCollection

Source: https://help.getzep.com/welcome/sdk-reference/deprecated/document/get-collection

Details the HTTP GET endpoint for retrieving a document collection and provides an example of the successful 200 OK JSON response body, outlining the structure and data types of the returned DocumentCollection object.

```APIDOC
GET https://api.getzep.com/api/v2/collections/:collectionName

200 OK Response Body:
{
  "created_at": "created_at",
  "description": "description",
  "document_count": 1,
  "document_embedded_count": 1,
  "embedding_dimensions": 1,
  "embedding_model_name": "embedding_model_name",
  "is_auto_embedded": true,
  "is_indexed": true,
  "is_normalized": true,
  "metadata": {
    "key": "value"
  },
  "name": "name",
  "updated_at": "updated_at",
  "uuid": "uuid"
}
```

--------------------------------

### Source .env File in Terminal Session

Source: https://help.getzep.com/welcome/sdks

This snippet provides the command to load environment variables from your `.env` file into the current terminal session. Sourcing the file makes the `ZEP_API_KEY` accessible to your applications running in that session.

```bash
source .env
```

--------------------------------

### Example JSON Response for Get Session Messages

Source: https://help.getzep.com/welcome/sdk-reference/memory/get-session-messages

Illustrates the structure of a successful JSON response when retrieving session messages, including message content, metadata, and pagination details.

```JSON
{
  "messages": [
    {
      "content": "content",
      "role_type": "norole",
      "created_at": "created_at",
      "metadata": {
        "key": "value"
      },
      "processed": true,
      "role": "role",
      "token_count": 1,
      "updated_at": "updated_at",
      "uuid": "uuid"
    }
  ],
  "row_count": 1,
  "total_count": 1
}
```

--------------------------------

### Example JSON Response for Batch Get Documents

Source: https://help.getzep.com/welcome/sdk-reference/deprecated/document/batch-get-documents

Illustrates the structure of a successful JSON response when retrieving documents in a batch, including document content, metadata, and timestamps.

```JSON
[
  [
    {
      "content": "content",
      "created_at": "created_at",
      "document_id": "document_id",
      "embedding": [
        1.1
      ],
      "is_embedded": true,
      "metadata": {
        "key": "value"
      },
      "updated_at": "updated_at",
      "uuid": "uuid"
    }
  ]
]
```

--------------------------------

### Create a New Zep User in Python

Source: https://help.getzep.com/welcome/sdks

This snippet shows how to create a new user in Zep using the Python SDK. Users are central to Zep's knowledge graph, as facts and entities learned from messages are stored at the user level, making them accessible across all of the user's sessions.

```Python
# Create a new user
user_id = "user123"
new_user = client.user.add(
    user_id=user_id,
    email="[email protected]",
    first_name="Jane",
    last_name="Smith",
)
```

--------------------------------

### Configure Graphiti for Neo4j and LLM connections

Source: https://help.getzep.com/welcome/graphiti/graphiti/quick-start

This snippet sets up logging and configures environment variables for Graphiti's connection to a Neo4j database and OpenAI for LLM inference. It checks for `NEO4J_URI`, `NEO4J_USER`, and `NEO4J_PASSWORD`, raising an error if they are not set. It also notes the default use of OpenAI and support for Anthropic and Groq.

```Python
# Configure logging
logging.basicConfig(
    level=INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    datefmt='%Y-%m-%d %H:%M:%S',
)
logger = logging.getLogger(__name__)

load_dotenv()

# Neo4j connection parameters
# Make sure Neo4j Desktop is running with a local DBMS started
neo4j_uri = os.environ.get('NEO4J_URI', 'bolt://localhost:7687')
neo4j_user = os.environ.get('NEO4J_USER', 'neo4j')
neo4j_password = os.environ.get('NEO4J_PASSWORD', 'password')

if not neo4j_uri or not neo4j_user or not neo4j_password:
    raise ValueError('NEO4J_URI, NEO4J_USER, and NEO4J_PASSWORD must be set')
```

--------------------------------

### API Response Example: Get Episodes for a Node

Source: https://help.getzep.com/welcome/sdk-reference/graph/node/get-episodes

A sample JSON response illustrating the data structure returned when successfully retrieving episodes for a node, including episode content, metadata, and UUID.

```JSON
{
  "episodes": [
    {
      "content": "content",
      "created_at": "created_at",
      "uuid": "uuid",
      "processed": true,
      "role": "role",
      "role_type": "norole",
      "session_id": "session_id",
      "source": "text",
      "source_description": "source_description"
    }
  ]
}
```

--------------------------------

### Configure Zep and OpenAI API Keys in .env File

Source: https://help.getzep.com/welcome/walkthrough

Set up your environment by creating a `.env` file. This file should contain your `ZEP_API_KEY` (obtained from Zep dashboard) and `OPENAI_API_KEY` for authentication with Zep Cloud and OpenAI services.

```Shell
ZEP_API_KEY=<key>
OPENAI_API_KEY=<key>
```

--------------------------------

### Deprecated API: Get Session Summaries Request and 200 OK Response

Source: https://help.getzep.com/welcome/sdk-reference/deprecated/memory/get-summaries

Illustrates the HTTP GET request to the deprecated endpoint for retrieving session summaries and provides an example of a successful 200 OK JSON response, showing the structure of the returned data.

```APIDOC
GET
https://api.getzep.com/api/v2/sessions/:sessionId/summary

200 Retrieved
{
  "row_count": 1,
  "summaries": [
    {
      "content": "content",
      "created_at": "created_at",
      "metadata": {
        "key": "value"
      },
      "related_message_uuids": [
        "related_message_uuids"
      ],
      "token_count": 1,
      "uuid": "uuid"
    }
  ],
  "total_count": 1
}
```

--------------------------------

### Create a New Zep Session (Python)

Source: https://help.getzep.com/welcome/quickstart

This snippet demonstrates how to create a new session for a user in Zep using the Python SDK. A session acts as a distinct chat thread, serving as a container for messages exchanged between a user and an assistant, and is uniquely linked to a specific user.

```Python
import uuid

# Generate a unique session ID
session_id = uuid.uuid4().hex

# Create a new session for the user
client.memory.add_session(
    session_id=session_id,
    user_id=user_id,
)
```

--------------------------------

### Python Client: Get Episodes for a Node

Source: https://help.getzep.com/welcome/sdk-reference/graph/node/get-episodes

Example Python code demonstrating how to use the Zep client library to fetch episodes for a given node UUID. An API key is required for client initialization.

```Python
from zep_cloud.client import Zep

client = Zep(
    api_key="YOUR_API_KEY",
)
client.graph.node.get_episodes(
    node_uuid="node_uuid",
)
```

--------------------------------

### Initialize Zep and OpenAI Python Clients

Source: https://help.getzep.com/welcome/walkthrough

This code snippet demonstrates the necessary imports and client initialization for both Zep and OpenAI in Python. It loads API keys from environment variables and sets up the `Zep` and `OpenAI` client instances for further interaction.

```python
import os
import json
import uuid

from openai import OpenAI
import rich

from dotenv import load_dotenv
from zep_cloud.client import Zep
from zep_cloud import Message

load_dotenv()

zep = Zep(api_key=os.environ.get("ZEP_API_KEY"))

oai_client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY"),
)
```

--------------------------------

### Get User Node API Response and Error Details

Source: https://help.getzep.com/welcome/sdk-reference/user/get-node

Details the successful response structure (200 OK) for retrieving a user's node, including an example JSON payload, and lists potential error responses.

```APIDOC
Response: 200 Retrieved
  node: object or null
    Description: Response object containing the User node.
    Properties:
      created_at: string
      name: string
      summary: string
      uuid: string
      attributes: object (key-value pairs)
      labels: array of strings

Errors:
  404: User Get Node Request Not Found Error
  500: User Get Node Request Internal Server Error
```

```json
{
  "node": {
    "created_at": "created_at",
    "name": "name",
    "summary": "summary",
    "uuid": "uuid",
    "attributes": {
      "key": "value"
    },
    "labels": [
      "labels"
    ]
  }
}
```

--------------------------------

### Search the Graph

Source: https://help.getzep.com/welcome/quickstart

Use the `graph.search` method to search for edges or nodes in the graph. This is useful for finding specific information about a user or group.

```Python
# Search for edges in a user's graph
edge_results = client.graph.search(
    user_id=user_id,
    query="What projects is Jane working on?",
    scope="edges",  # Default is "edges"
    limit=5
)

# Search for nodes in a user's graph
node_results = client.graph.search(
    user_id=user_id,
    query="Jane Smith",
    scope="nodes",
    limit=5
)

# Search in a group graph
group_results = client.graph.search(
    group_id=group_id,
    query="Project Alpha",
    scope="edges",
    limit=5
)
```

--------------------------------

### LangChain LangGraph Tool: search_facts API

Source: https://help.getzep.com/welcome/quickstart

API documentation for the `search_facts` LangChain LangGraph tool, which allows agents to search for facts within a user's Zep graph.

```APIDOC
search_facts(state: MessagesState, query: str, limit: int = 5)
  state: MessagesState - The Agent's state.
  query: str - The search query.
  limit: int - The number of results to return. Defaults to 5.
Returns: list - A list of facts that match the search query.
```

--------------------------------

### Example Response for Get User Episodes API

Source: https://help.getzep.com/welcome/sdk-reference/graph/episode/get-by-user-id

Illustrates the JSON structure returned by the API when successfully retrieving user episodes. It shows a list of episode objects, each containing properties such as content, creation timestamp, UUID, and role.

```JSON
{
  "episodes": [
    {
      "content": "content",
      "created_at": "created_at",
      "uuid": "uuid",
      "processed": true,
      "role": "role",
      "role_type": "norole",
      "session_id": "session_id",
      "source": "text",
      "source_description": "source_description"
    }
  ]
}
```

--------------------------------

### Initialize Zep Async Client

Source: https://help.getzep.com/welcome/ecosystem/langgraph-memory

This Python snippet demonstrates how to import the necessary classes from the `zep_cloud` library and initialize the `AsyncZep` client. It retrieves the API key from environment variables, ensuring secure access to Zep services.

```python
from zep_cloud.client import AsyncZep
from zep_cloud import Message

zep = AsyncZep(api_key=os.environ.get('ZEP_API_KEY'))
```

--------------------------------

### Example JSON Response for Get Group Episodes

Source: https://help.getzep.com/welcome/sdk-reference/graph/episode/get-by-group-id

Illustrates the structure of the JSON response returned when successfully retrieving episodes by group ID. The response contains a list of episode objects, each with details such as content, creation timestamp, UUID, and role information.

```json
{
  "episodes": [
    {
      "content": "content",
      "created_at": "created_at",
      "uuid": "uuid",
      "processed": true,
      "role": "role",
      "role_type": "norole",
      "session_id": "session_id",
      "source": "text",
      "source_description": "source_description"
    }
  ]
}
```

--------------------------------

### JSON Response Example: Group Facts

Source: https://help.getzep.com/welcome/sdk-reference/deprecated/group/get-facts

Illustrative JSON structure of the successful response from the 'Get Group Facts' API endpoint, showing the 'facts' array with individual fact properties like content, creation timestamp, UUID, and validity periods.

```JSON
{
  "facts": [
    {
      "content": "content",
      "created_at": "created_at",
      "fact": "fact",
      "uuid": "uuid",
      "expired_at": "expired_at",
      "invalid_at": "invalid_at",
      "name": "name",
      "rating": 1.1,
      "source_node_name": "source_node_name",
      "target_node_name": "target_node_name",
      "valid_at": "valid_at"
    }
  ]
}
```

--------------------------------

### Create a New Zep Session in Python

Source: https://help.getzep.com/welcome/sdks

This snippet demonstrates how to create a new session for a user in Zep using the Python SDK. A session acts as a chat thread, serving as a container for messages exchanged between a user and an assistant within a specific conversation.

```Python
import uuid

# Generate a unique session ID
session_id = uuid.uuid4().hex

# Create a new session for the user
client.memory.add_session(
    session_id=session_id,
    user_id=user_id,
)
```

--------------------------------

### API Response Example: Get Episode Success (200)

Source: https://help.getzep.com/welcome/sdk-reference/graph/episode/get

This JSON snippet illustrates the expected structure of a successful 200 OK response when retrieving an episode. It includes fields such as content, creation timestamp, UUID, and session ID.

```APIDOC
{
  "content": "content",
  "created_at": "created_at",
  "uuid": "uuid",
  "processed": true,
  "role": "role",
  "role_type": "norole",
  "session_id": "session_id",
  "source": "text",
  "source_description": "source_description"
}
```

--------------------------------

### Adding a User with Zep Cloud Client

Source: https://help.getzep.com/welcome/users

Demonstrates how to add a new user to the Zep Cloud client by providing user details such as ID, email, first name, and last name.

```Python
from zep_cloud.client import Zep

client = Zep(api_key=API_KEY)

new_user = client.user.add(
    user_id=user_id,
    email="[email protected]",
    first_name="Jane",
    last_name="Smith",
)
```

--------------------------------

### Example 200 OK Response for Get Session API

Source: https://help.getzep.com/welcome/sdk-reference/memory/get-session

This JSON snippet illustrates the structure of a successful response (HTTP 200 OK) when retrieving a session from the Zep API. It includes various session properties like classifications, timestamps, metadata, and IDs.

```JSON
{
  "classifications": {
    "key": "value"
  },
  "created_at": "created_at",
  "deleted_at": "deleted_at",
  "ended_at": "ended_at",
  "fact_rating_instruction": {
    "examples": {
      "high": "high",
      "low": "low",
      "medium": "medium"
    },
    "instruction": "instruction"
  },
  "facts": [
    "facts"
  ],
  "id": 1,
  "metadata": {
    "key": "value"
  },
  "project_uuid": "project_uuid",
  "session_id": "session_id",
  "updated_at": "updated_at",
  "user_id": "user_id",
  "uuid": "uuid"
}
```

--------------------------------

### Listing Users with Zep Cloud Client

Source: https://help.getzep.com/welcome/users

Explains how to list all users, with optional pagination parameters like page size and page number, using the Zep Cloud client.

```Python
# List the first 10 users
result = client.user.list_ordered(page_size=10, page_number=1)
```

--------------------------------

### Retrieve Zep Session Message (Python SDK)

Source: https://help.getzep.com/welcome/sdk-reference/memory/get-session-message

Example Python code demonstrating how to use the Zep SDK to retrieve a specific message from a session. This method is deprecated; consider using `graph.episodes.get` instead.

```Python
from zep_cloud.client import Zep

client = Zep(
    api_key="YOUR_API_KEY",
)
client.memory.get_session_message(
    session_id="sessionId",
    message_uuid="messageUUID",
)
```

--------------------------------

### Initialize Zep and OpenAI Clients in Python

Source: https://help.getzep.com/welcome/ecosystem/chainlit

This snippet demonstrates how to import necessary modules from Zep Python SDK and ChainLit, retrieve API keys from environment variables, and initialize AsyncOpenAI and AsyncZep clients for use in a ChainLit application.

```Python
# Import necessary modules from Zep Python SDK and ChainLit.
from zep_cloud.client import AsyncZep
from zep_cloud.memory import Memory, Session
from zep_cloud.message import Message
import chainlit as cl
import uuid
import os
from openai import AsyncOpenAI

# Retrieve API keys from environment variables.
ZEP_API_KEY = os.environ.get("ZEP_API_KEY")
OPENAI_API_KEY = os.environ.get("OPENAI_API_KEY")

# Initialize clients for OpenAI GPT-4 and Zep with respective API keys.
openai_client = AsyncOpenAI(api_key=OPENAI_API_KEY)
zep = AsyncZep(api_key=ZEP_API_KEY)
```

--------------------------------

### Python: List Entity Types using Zep Client

Source: https://help.getzep.com/welcome/sdk-reference/graph

Example Python code demonstrating how to initialize the Zep client with an API key and call the `list_entity_types` method to retrieve entity type data.

```Python
from zep_cloud.client import Zep

client = Zep(
    api_key="YOUR_API_KEY",
)
client.graph.list_entity_types()
```
Tokens:
Raw