Introducing Entity Types: Smarter, Structured Memory for Agents

Zep is a memory layer for AI agents built on a temporal knowledge graph that captures evolving user interactions and business data. It enables agents to recall relevant information over time, enabling accurate, personalized, and context-aware responses.

Today, we're introducing Entity Types—both Default and Custom—to enhance Zep's ability to model structured data within its knowledge graph. This feature allows developers to define and utilize domain-specific entities (or nodes) in a graph, improving the precision and relevance of agent memory.

Rethinking Ontologies for Agentic Apps

An ontology is a formal way of describing concepts, their properties, and the relationships between them within a specific domain.

Traditional ontology frameworks like RDF and OWL offer expressive modeling capabilities but can be complex and unwieldy for many applications.

For Zep's Entity Types, we've adopted a more developer-friendly approach by using Pydantic and Zod-like models. This choice simplifies the definition of entity schemas, making it more accessible for developers to integrate structured data into their applications.

Introducing Default Entity Types

To enrich Zep user graphs for common use cases, Zep now includes a set of Default Entity Types. These are pre-defined structures that Zep can automatically identify and classify within user graphs. The current default entity types are:

• User: Represents a human participant in the current chat thread. Created when you call user.add or equivalent in TypeScript or Go.
• Preference: Captures a preference expressed by a User (e.g., "I like pop music").
• Procedure: Defines a multi-step instruction for agent behavior (e.g., "When the user asks for code, respond only with code snippets followed by a bullet point explanation").

Example:

When a user states, "I prefer window over aisle," Zep automatically creates an entity, or node, classified as Preference, capturing the user's airline seating preference.

Default Entity Types enable straightforward filtering and retrieval for preferences and procedures. For example, the following will retrieve all Preference nodes related to the search phrase seating, using both BM25 and semantic search sources:

client.graph.search(
    user_id=user_id,
    query="seating",
    scope="nodes",
    search_filters=SearchFilters(
        node_labels=["Preference"]
    )
)

GraphSearchResults(
│   edges=None,
│   nodes=[
│   │   EntityNode(
│   │   │   attributes={
│   │   │   │   'category': 'Travel Seating Preference',
│   │   │   │   'description': 'Preference for window seat instead of aisle seat.',
│   │   │   │   'labels': ['Entity', 'Preference']
│   │   │   },
│   │   │   created_at='2025-05-15T05:06:03.712749Z',
│   │   │   labels=['Entity', 'Preference'],
│   │   │   name='window seat preference',
│   │   │   summary='Jane Doe prefers a window seat over an aisle seat.',
│   │   │   uuid_='584bd0f5-4735-4258-8984-a1dae2cf228f',
│   │   │   graph_id='f3b516dc-887e-4f2d-bda3-b46376859e4f'
│   │   )
│   ]
)

Unlocking Domain Expertise with Custom Entity Types

While default types are useful, the true power for building specialized agents comes from Custom Entity Types. This functionality is critical when your agent needs to operate in deep vertical use cases or across broad enterprise domains with specific data models.

Custom Entity Types allow you to define your own schemas, tailoring the knowledge graph to the precise needs of your application. You provide a description for the entity type and for each of its fields.

If an entity extracted by Zep matches a predefined Custom Entity Type, Zep will classify the entity accordingly and populate the entity's fields.

Example: Modeling Airline Travel Preferences

Imagine building an AI travel agent. Understanding a user's detailed air travel preferences is crucial for providing relevant recommendations. With Custom Entity Types, you can model these preferences explicitly.

Here's how you might define this in Python using Zep's EntityModel, a subclass of Pydantic's BaseModel:

class AirTravelPreferences(EntityModel):
    """
    A traveler’s broad flight-related preferences.
    """
    cabin_class: EntityText = Field(
        description="Desired cabin class (e.g. Economy, Business, First)",
        default=None
    )
    seat_location: EntityText = Field(
        description="Preferred seat position (aisle, window, bulkhead, exit row)",
        default=None
    )
    max_layovers: EntityInt = Field(
        description="Maximum number of connections acceptable",
        default=None
    )

The resulting entity from a conversation between a user and the agentic travel agent might look like this:

Capturing Structured Data and Refining Search

The introduction of entity types provides two key benefits:

1. Structured Data Capture: Entities are no longer opaque nodes. They become structured objects with well-defined fields. This allows your agent to access specific attributes of an entity directly, rather than relying solely on undifferentiated nodes and node text descriptions. For example, after a conversation, your agent could directly query for the user's max_layovers from an AirTravelPreferences entity.
2. Filtered Search Results: As discussed above, you can now filter graph searches by one or more entity types. This significantly improves the precision of information retrieval. If you're looking for airlines a user likes, you can specifically request nodes of type AirlinePreference.

This ability to work with structured, domain-specific entity types allows agents to operate with a much deeper understanding and precision, leading to more accurate and helpful interactions, especially in complex or specialized domains.

SDK Support

We've ensured that Default and Custom Entity Types are supported across all our official Zep SDKs: Python, TypeScript, and Go.

While the examples above are shown in Python, you can find details for all supported languages in our documentation to start leveraging this new functionality regardless of your preferred language environment.

Building More Intelligent Agents

Introducing Default and Custom Entity Types marks a big step forward for Zep, giving your agents richer, structured memories tailored to your specific domain. With these new capabilities, you can build smarter, more personalized applications that tackle both specialized and enterprise-scale challenges.

We're continually improving Zep to support your evolving needs. Check out our documentation to see Entity Types in action. We're excited to see what you build!