Using Neo4j with Hypermode

Connect your Hypermode agent to Neo4j for graph database operations

Neo4j

Graph database platform for connected data

Overview

Neo4j is a powerful graph database that excels at managing highly connected data and complex relationships. This guide will walk you through connecting your Hypermode agent to Neo4j.

Prerequisites

Before connecting Neo4j to Hypermode Agents, you’ll need:

1. A Neo4j database instance (free options include Neo4j Sandbox and Neo4j Aura free tier)
2. A Hypermode Agents account

This guide will walk you through the steps of connecting to Neo4j using the free Neo4j Sandbox, but you can also use Neo4j Aura or a self-hosted instance.

Setting up Neo4j

Step 1: Create a Neo4j Sandbox

First, navigate to https://sandbox.neo4j.com/ and create an account. Choose “Blank Sandbox” from the list of available options.

Neo4j Sandbox provides free temporary instances perfect for testing. For production use, consider Neo4j Aura or a self-hosted instance.

Step 2: Note your connection details

Once your Neo4j sandbox instance is created (it may take a moment), you can navigate to the “Connection details” tab to view the connection credentials for your Neo4j sandbox instance.

Note the username, password, and Bolt URL - you’ll use these in the next step to create a Neo4j connection in Hypermode Agents.

Creating your Neo4j agent

Step 1: Create a new agent

From the Hypermode Agents dashboard, create a new agent:

1. Select the “Create agent” button
2. Describe your agent in a few sentences, we’ll use “The agent is a Neo4j expert”

Step 3: View your agent profile

Once created, navigate to your agent’s details page. Here you can view and edit the agent instructions that were created from your initial agent description preceding the agent creation process.

You can update the agent instructions at any time to help align the agent’s background and skills with your use case.

Connecting to Neo4j

Step 1: Add the Neo4j connection

Navigate to the Connections tab in Hypermode Agents and add Neo4j:

1. Click “Add connection”
2. Select the “Connect” button next to Neo4j in the list of available connections

Step 2: Configure credentials

Enter your Neo4j credentials from the Neo4j Sandbox details page.

Ensure you’re using the Bolt URL endpoint format.

Understanding Neo4j’s schemaless nature

Unlike traditional databases, Neo4j doesn’t require you to define schemas upfront. This means:

• Flexible node creation: Add nodes with any labels and properties on the fly
• Dynamic relationships: Create relationships of any type between nodes
• Evolving data models: Your graph structure can grow and change organically
• No migrations needed: Add new node types or properties without schema updates

This flexibility makes Neo4j perfect for:

• Exploratory data analysis
• Rapidly evolving data models
• Complex, heterogeneous datasets
• Real-world relationship modeling

Example graph model

Here’s a simple example of how nodes and relationships work in Neo4j:

This model shows:

• Nodes: Person, Company, and Product (represented as circles)
• Relationships: WORKS_AT, MAKER_OF, BY_COMPANY (represented as arrows)
• Each node can have properties (like name, age, price)
• Relationships can also have properties (like since, role)

Testing the connection

Test 1: Create your first nodes

Start a new thread with your agent and create some nodes dynamically:

Create nodes for this scenario:
- A Person named "Alice" who is 28 years old
- A Company named "TechCorp" founded in 2020
- A Product named "GraphApp" with a price of $99

Test 2: Create relationships

Now connect your nodes based on our model:

Create these relationships:
- Alice WORKS_AT TechCorp (since 2021)
- Alice is MAKER_OF GraphApp
- GraphApp is BY_COMPANY TechCorp

Test 3: Visualize in Neo4j Browser

After your agent creates the data, switch to Neo4j Browser to see the results:

1. Click the “Open” button in your Neo4j Sandbox
2. Run the visualization query:

   MATCH (n) RETURN n

Test 4: Query your graph

Back in your agent thread, use Cypher to explore your data:

Run a Cypher query to find all products made by people who work at TechCorp, showing the full relationship path.

Example: Building a dynamic knowledge graph

Here’s how to leverage Neo4j’s schemaless nature to build a flexible knowledge graph:

Let's expand our graph with more data:
1. Add another Person "Bob" who also works at TechCorp
2. Add a new Company "StartupInc"
3. Add Products "DataTool" and "AIAssistant"
4. Create relationships showing Bob made DataTool, and StartupInc made AIAssistant
5. Add a COMPETES_WITH relationship between the two companies

Your agent can dynamically add:

• New node types as you discover them
• Properties specific to each entity
• Relationships that make sense in context
• No need to predefine any structure!

What you can do

With your Neo4j connection and its three core tools, your agent can:

• Create Node: Dynamically add entities with any labels and properties
• Create Relationship: Connect nodes with typed relationships and properties
• Run Cypher Query: Perform complex graph operations including:
  • Pattern matching and traversal
  • Aggregations and analytics
  • Graph algorithms
  • Data updates and deletions
  • Schema-free exploration

Troubleshooting

Common issues

Connection refused error

• Check if your sandbox is still active (they expire after 3 days)
• Ensure the URL includes the correct port (usually 7474)

Authentication failed

• Confirm username and password are correct
• Sandbox passwords are auto-generated - copy carefully
• Try resetting the password in the sandbox console

Learn more

• Neo4j Documentation
• Cypher Query Language
• Tutorial: Using Hypermode Agents to extract and build knowledge graphs