Skip to navigation
Build with ContextWork with Graphs

Create a Context Graph

Create shared or domain context that is not owned by one Zep user

Overview

Create a shared Context Graph when the context belongs to a customer account, project, product, organization, or business domain instead of one application user. Zep gives each graph a UUID. The API addresses the graph with this graph_uuid.

When to create a Context Graph

Create a graph when you need to:

  • Create shared knowledge bases across multiple users
  • Build domain-specific knowledge graphs independent of user context
  • Maintain separate graphs for testing or experimentation
  • Implement custom graph architectures for specialized use cases

Use a user graph when the context belongs to one application user and the application needs Zep users, threads, user summaries, or thread.get_context.

Create the graph

graph.create does not accept an identifier. Zep generates the UUID of the graph and returns it in the uuid field of the response. Store this UUID in your database next to the application record that owns the graph, for example a zep_graph_uuid column on the account record. Use the UUID on every later call. The name and description fields describe the graph. They are not addresses.

from zep_cloud.client import Zep
client = Zep(
    api_key=API_KEY,
)
# Create a Context Graph. Zep generates its UUID.
graph = client.graph.create(
    name="EMEA Support",
    description="Customer support cases and escalation history for EMEA.",
)
# Store the UUID next to your own account record
zep_graph_uuid = graph.uuid_
print(f"Created graph with UUID: {zep_graph_uuid}")

Each call to graph.create makes a new graph. If your application can retry a create, you can send an Idempotency-Key with the call: idempotency_key in Python, idempotencyKey in the TypeScript request options, or option.WithIdempotencyKey in Go. A retry with the same key then returns the first result and does not make a second graph.

Bind a content policy

A new graph copies the current project content policy when you create it. The optional content_policy field of the create body adds categories and rules to that policy, and content_policy.project_revision rejects the create with 409 content_policy_revision_stale when the project policy changed after you read it. The bound policy is read-only after creation. When a graph needs a different policy, create a new graph.

Describe graphs for routing

Set a distinct name and description when agents can access more than one Context Graph. The graph directory searches name and description, so the description should state what an agent should query the graph for and what the graph does not contain.

Seed the graph

A shared Context Graph created with graph.create starts empty. A user graph starts with a user node that represents its subject. A shared Context Graph has no node until you add data. Before you add ongoing data, seed the graph with facts about its subject. Later data can then attach to a well-formed subject.

For example, give a new company graph the company’s name, industry, and key people. Seed it by adding episodes with graph.episode.add, by asserting known relationships with graph.edge.add, or both.

Work with the graph

After creation, you can use the same graph methods that apply to user graphs:

Customizing Graph Structure

You can customize these Context Graphs with entity and edge types. See Customizing Graph Structure for details.

Next Steps