Zep AI icon

Zep AI

AI Tool for interacting with Zep memory and knowledge graph. Provides operations to store/retrieve conversation memory, search knowledge graphs, and manage user context.

Actions9

Overview

The "Search Knowledge Graph" operation of the Zep AI node allows users to query a knowledge graph for relevant information based on a search query. This operation is useful in scenarios where you want to retrieve structured or semi-structured data about entities, relationships, or episodes stored within a knowledge graph associated with a user or a specific graph ID.

Practical examples include:

  • Searching for relationships (edges) between entities related to a user’s data.
  • Finding specific entities (nodes) that match a query.
  • Retrieving episodes (data points or events) relevant to a search term.
  • Filtering results by minimum fact rating to get higher quality or more relevant facts.
  • Limiting the number of returned results for performance or UI considerations.

This operation is beneficial in AI applications, customer support systems, or any context where enriched contextual knowledge retrieval from a graph database enhances decision-making or conversational AI responses.

Properties

Name Meaning
User ID The unique identifier of the user whose knowledge graph will be searched. Example: "user-123".
Search Query The text query string used to search the knowledge graph for matching information.
Graph ID Optional. The specific graph ID to search within. If not provided, the user's default graph is used.
Search Scope Defines what part of the graph to search:
- Edges (Relationships)
- Nodes (Entities)
- Episodes (Data)
Max Results Maximum number of search results to return. Range: 1 to 100. Default is 10.
Minimum Fact Rating Filters results by a minimum fact relevance rating between 0.0 and 1.0. Only applicable when searching edges (relationships).

Output

The output JSON contains the following fields:

  • query: The original search query string.
  • userId: The user ID used for the search.
  • scope: The search scope selected (edges, nodes, or episodes).
  • results: An array of search result objects returned by the knowledge graph API. Each result represents a matching edge, node, or episode depending on the scope.
  • totalResults: The count of results returned.
  • response: The full raw response object from the API call, which may contain additional metadata or pagination info.

No binary data is output by this operation.

Dependencies

  • Requires an active connection to the Zep AI API service at https://api.getzep.com.
  • Requires an API authentication token credential configured in n8n for the Zep AI service.
  • The node uses HTTP POST requests with JSON payloads to interact with the Zep API endpoints.
  • No other external dependencies are required.

Troubleshooting

  • Common Issues:

    • Missing or invalid API credentials will cause authentication failures.
    • Providing neither a User ID nor a Graph ID may lead to errors or empty results.
    • Invalid values for maxResults (outside 1-100) or minFactRating (outside 0.0-1.0) may cause validation errors.
    • Network connectivity issues can prevent successful API calls.

  • Error Messages:

    • "Unknown operation: searchGraph" — indicates the operation parameter was not set correctly.
    • "Either Graph ID or User ID must be provided" — if both identifiers are missing when required.
    • JSON parsing errors if input parameters are malformed (not typical for this operation but possible in others).

  • Resolutions:

    • Ensure API credentials are correctly set up and valid.
    • Provide either a valid User ID or Graph ID.
    • Validate input parameters before execution.
    • Check network connectivity and API endpoint availability.

Links and References

Discussion