Simple, Text-based Semantic Queries

The simplest form of search query is a text-based semantic simailrity query. No metadata filter is required, and the query is simply a string of text. Zep will convert the query into an embedding and find semantically similar documents, chat history summaries, or chat messages.

Below is an example search against a chat session using only search text.

1
from zep_cloud.client import AsyncZep
2
3
client = AsyncZep(
4
    api_key=API_KEY,
5
)
6
7
search_results = await client.memory.search(
8
    session_id,
9
    text=query,
10
    search_scope="messages",
11
    metadata={"where": {"jsonpath": '$[*] ? (@.bar == "foo")'}},
12
)

Read more about chat message history search.

Maximal Marginal Relevance Re-Ranking

Zep supports re-ranking search results using Maximal Marginal Relevance (MMR) over both chat history memory and document collections.

Maximal Marginal Relevance (MMR) helps balance relevance and diversity in results returned during information retrieval, which is useful in vector similarity searches for Retrieval-Augmented Generation (RAG) type applications.

A similarity search may return many highly ranked results that are very similar to each other. Since each subsequent result doesn’t add much new information to a prompt, adding these may not be very useful.

MMR helps to reduce redundancy in the results by re-ranking the results to promote diversity, with very similar results downranked in favor of different, but still relevant, results.

How Zep’s MMR Re-Ranking Works

When you run a search re-ranked by MMR, Zep retrieves double the number of results, K, you requested. The entire resultset is then reranked using MMR, and the top K results are returned.

If you request fewer than 10 results, Zep will return 10 results, but still return to you the top K results you requested.

Zep’s MMR algorithm is SIMD-hardware accelerated on amd64 archicture CPUs, ensuring that MMR adds little overhead to your search.

Constructing an MMR Re-Ranked Search Query

MMR Search over Chat History

1
from zep_cloud.client import AsyncZep
2
3
client = AsyncZep(
4
    api_key=API_KEY,
5
)
6
7
search_results = await client.memory.search(
8
    session_id,
9
    text=query,
10
    search_scope="summary", # This could be messages or summary
11
    search_type="mmr",
12
    mmr_lambda=0.5, # tune diversity vs relevance
13
)

MMR Search over Document Collections

1
# This assumes you've created a collection and added documents to it
2
docs = await client.document.search(
3
    collection_name,
4
    text=query,
5
    search_type="mmr",
6
    mmr_lambda=0.5,
7
    limit=3,
8
)

Filtering using Metadata

Zep supports filtering search queries by metadata. Metadata filters are JSONPath queries augmented by a simple boolean logic overlay.

JSONPath queries allow for building sophisticated filters that match on elements at any level of the JSON document. The boolean logic overlay allows for combining multiple JSONPath queries using and and or operators.

Useful resources for building and testing JSONPath queries

• JSONPath Syntax
• JSONPath Online Evaluator
• JSONPath Expression Tester.

Constructing a JSONPath Query Filter

The simplest form of a metadata filter looks as follows:

1
{
2
  "where": { "jsonpath": "$[*] ? (@.foo == \"bar\")" }
3
}

If a metadata field foo is equal to the string "bar", then the document or message will be returned in the search results.

Executing the above query against a chat session looks as follows:

1
search_results = await client.memory.search(
2
    session_id,
3
    text="Is Lauren Olamina a character in a book",
4
    metadata={
5
        "where": {
6
            "jsonpath": '$[*] ? (@.author == "Octavia Butler")'
7
        }
8
    },
9
)

Combining multiple JSONPath filters using boolean logic

Multiple JSONPath queries can be combined using boolean logic. The following example will return documents or messages where the author field is equal to "Octavia Butler" and the title field is equal to "Parable of the Sower".

1
{
2
  "where": {
3
    "and": [
4
      { "jsonpath": "$[*] ? (@.author == \"Octavia Butler\")" },
5
      { "jsonpath": "$[*] ? (@.title == \"Parable of the Sower\")" }
6
    ]
7
  }
8
}

Similarly, the following example will return documents or messages where the author field is equal to "Octavia Butler" or the title field is equal to "Parable of the Sower".

1
{
2
  "where": {
3
    "or": [
4
      { "jsonpath": "$[*] ? (@.author == \"Octavia Butler\")" },
5
      { "jsonpath": "$[*] ? (@.title == \"Parable of the Sower\")" }
6
    ]
7
  }
8
}

Filter logic can be combined to create arbitrarily complex filters. For example, the following filter will return documents or messages where:

• the author field is equal to ("Octavia Butler" and the title field is equal to "Parable of the Sower")
• or the title field is equal to "Parable of the Talents".

1
{
2
  "where": {
3
    "or": [
4
      {
5
        "and": [
6
          { "jsonpath": "$[*] ? (@.author == \"Octavia Butler\")" },
7
          { "jsonpath": "$[*] ? (@.title == \"Parable of the Sower\")" }
8
        ]
9
      },
10
      { "jsonpath": "$[*] ? (@.title == \"Parable of the Talents\")" }
11
    ]
12
  }
13
}

Querying by Message Creation Date

Memory search supports querying by message creation date. The following example will return documents or messages created between June 1, 2023 and June 31, 2023.

Datetime strings must be in ISO 8601 format.

1
{
2
  "start_date": "2023-06-01",
3
  "end_date": "2023-06-31"
4
}