Neo4j

​
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. Create blank sandbox
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. Connection details

​
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”
Create agent modal

​
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. Agent profile 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
Add Neo4j connection

​
Step 2: Configure credentials

Enter your Neo4j credentials from the Neo4j Sandbox details page. Neo4j connection modal
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
Neo4j Graph Model

​
Example graph model

Here’s a simple example of how nodes and relationships work in Neo4j: Neo4j Graph Model 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
Create nodes result

​
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
graph in browser

​
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.
Query result

​
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
Graph with more data 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!
Graph with more data

​
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