Advisor Neo4j Champion

A Neo4j graph database specialist that helps you design graph data models, write efficient Cypher queries, optimize database performance, and build graph-powered applications for relationship-heavy domains.

When to Use This Agent

Choose Advisor Neo4j Champion when:

• Designing graph data models for relationship-heavy domains
• Writing and optimizing Cypher queries for Neo4j
• Implementing graph algorithms (shortest path, community detection, PageRank)
• Building recommendation engines, fraud detection, or knowledge graphs
• Migrating from relational databases to Neo4j for relationship queries

Consider alternatives when:

• Working with simple key-value or document data (use a general database agent)
• Building relational database schemas (use a SQL/DBA agent)
• Using other graph databases like Amazon Neptune or Azure CosmosDB Gremlin (use the relevant agent)

Quick Start

Copy
# .claude/agents/advisor-neo4j-champion.yml
name: Advisor Neo4j Champion
description: Neo4j graph database design and Cypher queries
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - WebSearch

Example invocation:

claude "Design a Neo4j graph model for a social network with users, posts, comments, likes, and follower relationships, including optimized Cypher queries for feed generation and friend recommendations"

Core Concepts

Graph Data Modeling

Concept	Relational Equivalent	Graph Advantage
Node	Row in a table	Rich properties, multiple labels
Relationship	Foreign key / join table	First-class with properties, direction
Label	Table name	Multiple labels per node
Property	Column	Flexible schema per node
Path	Multi-table JOIN	Native traversal, no joins

Cypher Query Patterns

Copy
// Create graph schema
CREATE CONSTRAINT user_email IF NOT EXISTS
FOR (u:User) REQUIRE u.email IS UNIQUE;

CREATE INDEX user_name IF NOT EXISTS
FOR (u:User) ON (u.name);

// Create nodes and relationships
CREATE (alice:User {name: 'Alice', email: '[email protected]', joinedAt: datetime()})
CREATE (bob:User {name: 'Bob', email: '[email protected]', joinedAt: datetime()})
CREATE (alice)-[:FOLLOWS {since: datetime()}]->(bob)
CREATE (post:Post {id: randomUUID(), content: 'Hello Graph!', createdAt: datetime()})
CREATE (alice)-[:POSTED]->(post)
CREATE (bob)-[:LIKED {at: datetime()}]->(post);

// Friend-of-friend recommendations
MATCH (user:User {email: '[email protected]'})-[:FOLLOWS]->(friend)-[:FOLLOWS]->(recommended)
WHERE NOT (user)-[:FOLLOWS]->(recommended) AND recommended <> user
WITH recommended, count(friend) AS mutualFriends
ORDER BY mutualFriends DESC
LIMIT 10
RETURN recommended.name, mutualFriends;

// News feed: posts from followed users, ordered by recency
MATCH (user:User {email: '[email protected]'})-[:FOLLOWS]->(friend)-[:POSTED]->(post:Post)
OPTIONAL MATCH (post)<-[likes:LIKED]-()
WITH post, friend, count(likes) AS likeCount
ORDER BY post.createdAt DESC
LIMIT 20
RETURN post.content, friend.name AS author, likeCount, post.createdAt;

// Shortest path between users
MATCH path = shortestPath(
  (a:User {name: 'Alice'})-[:FOLLOWS*..6]-(b:User {name: 'Charlie'})
)
RETURN [node in nodes(path) | node.name] AS connectionPath,
       length(path) AS degrees;

Graph Algorithm Integration

Copy
// Community detection using Louvain
CALL gds.louvain.stream('social-graph')
YIELD nodeId, communityId
WITH gds.util.asNode(nodeId) AS user, communityId
RETURN communityId, collect(user.name) AS members, count(*) AS size
ORDER BY size DESC;

// PageRank for influence scoring
CALL gds.pageRank.write('social-graph', {
  writeProperty: 'influenceScore',
  maxIterations: 20,
  dampingFactor: 0.85
});

Configuration

Parameter	Description	Default
neo4j_version	Neo4j version (5.x, aura)	5
deployment	Deployment model (standalone, cluster, aura)	Auto-detect
gds_version	Graph Data Science library version	latest
apoc_enabled	Enable APOC procedures	true
memory_config	Heap and page cache settings	Auto-tuned
driver	Application driver (neo4j-driver, spring-data)	neo4j-driver

Best Practices

1. Model relationships as first-class entities, not as node properties. In a relational mindset, you might store user.friendIds = [1, 2, 3]. In a graph, create explicit relationships: (alice)-[:FOLLOWS]->(bob). Relationships can have properties (since, strength), can be traversed efficiently, and can be queried by type. Properties on nodes that represent relationships miss the core value of graph databases.

2. Use relationship types as verbs and node labels as nouns. :FOLLOWS, :POSTED, :LIKED, :PURCHASED are clear relationship types. :User, :Post, :Product are clear node labels. Avoid generic relationships like :RELATED_TO — they force the query to filter by properties rather than leveraging the graph's structural typing. Specific relationship types enable faster traversals.

3. Index properties used in MATCH clause WHERE filters. Cypher queries start by finding initial nodes (usually via index lookup) and then traverse relationships. Without an index on the starting property, the query scans all nodes. Create indexes on properties used in WHERE clauses of initial MATCH patterns: user emails, product IDs, and any property used for lookups.

4. Limit traversal depth to prevent query explosion. Queries like MATCH (a)-[*]->(b) traverse the entire reachable graph, which can be billions of paths. Always specify a maximum depth: (a)-[:FOLLOWS*1..3]->(b) limits to 3 hops. For algorithms that need full traversal, use the Graph Data Science library which is optimized for whole-graph operations.

5. Design the graph model around your query patterns, not your entity model. If your most common query is "find products purchased by people who also purchased X," model it so that traversal is efficient: (Product)<-[:PURCHASED]-(User)-[:PURCHASED]->(Product). If the model requires 5 hops for your most common query, restructure it. A graph model that makes common queries simple is better than one that is "correctly" normalized.

Common Issues

Cypher queries are slow despite correct logic. The most common performance issue is missing indexes on starting nodes. Use PROFILE before your query to see the execution plan. Look for NodeByLabelScan (full scan) where NodeIndexSeek (index lookup) should appear. Add indexes for the properties used in your WHERE clauses. Also check for Cartesian products caused by disconnected MATCH patterns.

Graph model becomes overly complex with too many relationship types. Starting with 30 relationship types makes queries verbose and the model hard to understand. Consolidate relationships that share the same semantics: :LIKED_POST, :LIKED_COMMENT, :LIKED_PHOTO can be simplified to :LIKED with the target node's label distinguishing the type. Use relationship properties for attributes rather than creating separate relationship types for each variant.

Memory consumption grows beyond server capacity as the graph scales. Neo4j performs best when the entire graph fits in memory (page cache + heap). For graphs exceeding available memory, configure page cache to cover the most-queried portion, use read replicas to distribute query load, and consider sharding via Neo4j Fabric for very large graphs. Monitor page cache hit ratios — below 95% indicates the cache is too small for the working set.