Neo4j Knowledge Graph

​

Overview

​

Configuration

​

Environment Variables

# Neo4j Configuration (Optional)
NEO4J_URL=neo4j+s://your-instance.databases.neo4j.io
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-password

​

Mem0 Configuration

if neo4j_url and neo4j_password:
    config["graph_store"] = {
        "provider": "neo4j",
        "config": {
            "url": neo4j_url,
            "username": neo4j_username,
            "password": neo4j_password,
        }
    }

​

How It Works

​

Dual Storage Strategy

​

Entity & Relationship Extraction

1. Extracts Entities: Identifies people, places, concepts, and objects
2. Identifies Relationships: Determines how entities relate to each other
3. Creates Graph Nodes: Stores entities as nodes in Neo4j
4. Creates Graph Edges: Connects related entities with labeled relationships

​

Memory Classification Integration

• LONG_TERM memories: Build persistent identity and preference graphs
• SHORT_TERM memories: Create temporary context nodes that can be pruned
• EPISODIC memories: Link events chronologically with temporal relationships
• SEMANTIC memories: Connect factual knowledge in concept hierarchies
• PROCEDURAL memories: Map step-by-step processes with ordered relationships

​

Graph Schema

​

Node Types

• Person: User identities, colleagues, contacts
• Concept: Technologies, tools, methodologies
• Event: Meetings, deadlines, milestones
• Preference: User likes, dislikes, settings
• Knowledge: Facts, definitions, learnings

​

Relationship Types

• KNOWS: Person-to-person connections
• PREFERS: User preferences
• WORKS_ON: Project/task relationships
• HAPPENED_BEFORE/AFTER: Temporal event ordering
• RELATED_TO: Conceptual connections
• PART_OF: Hierarchical relationships

​

Benefits of Graph Storage

​

1. Relationship-Based Retrieval

• “What projects is Sarah working on?” → Follow WORKS_ON edges from Sarah node
• “What happened before the product launch?” → Traverse HAPPENED_BEFORE relationships

​

2. Multi-Hop Reasoning

• User → KNOWS → Colleague → WORKS_ON → Project
• Enables queries like “Show me projects that people I know are working on”

​

3. Temporal Understanding

• Link episodic memories chronologically
• Understand sequences of events
• Build timelines of project progress

​

4. Contextual Clustering

• All memories about a specific person
• All memories related to a project
• All preferences in a category

​

Startup Logging

==================================================
MEM0 CONFIGURATION:
  Vector Store: supabase
  Graph Store: neo4j
==================================================

==================================================
MEM0 CONFIGURATION:
  Vector Store: supabase
  Graph Store: disabled
==================================================

​

Querying the Graph

​

Through Memory API

# Search uses both vector similarity and graph relationships
results = memory.search(
    "What projects am I working on?",
    user_id=user_id,
    limit=10
)

​

Direct Neo4j Queries

// Find all people the user knows
MATCH (user:Person {id: $userId})-[:KNOWS]->(contact:Person)
RETURN contact.name

// Find chronologically ordered events
MATCH (e1:Event)-[:HAPPENED_BEFORE]->(e2:Event)
WHERE e1.userId = $userId
RETURN e1, e2
ORDER BY e1.timestamp

// Find related concepts
MATCH (c1:Concept)-[:RELATED_TO*1..3]-(c2:Concept)
WHERE c1.name = "React"
RETURN c2.name

​

Performance Considerations

​

When to Use Neo4j

• Complex relationship queries
• Multi-hop reasoning
• Timeline/chronological queries
• Entity-centric retrieval
• Knowledge graph visualization

• Simple semantic search
• Single-user personal notes
• Minimal relationship complexity
• Cost-sensitive deployments

​

Scaling

• Vector Store: Scales with number of memories (embeddings)
• Graph Store: Scales with number of entities + relationships
• Query Performance: Graph queries are fastest for relationship traversal, vector queries for semantic similarity

​

Memory API Integration

​

Adding Memories

# Automatically extracts entities and relationships
result = memory.add(
    messages,
    user_id=request.user_id,
    metadata=metadata
)

​

Searching Memories

# Combines vector similarity + graph relationships
results = memory.search(
    request.query,
    user_id=request.user_id,
    limit=request.limit
)

​

Filtering by Type

# Graph can filter by memory_type metadata
results = memory.search(
    query,
    user_id=user_id,
    filters={"memory_type": "EPISODIC"}
)

​

Visualization

​

Neo4j Browser

1. Open your Neo4j instance URL in a browser
2. Log in with your credentials
3. Run Cypher queries to explore the graph
4. Click nodes and edges to see properties
5. Use the graph visualization to understand relationships

​

Example Visualization Query

// Visualize user's knowledge graph
MATCH (n)-[r]-(m)
WHERE n.userId = $userId
RETURN n, r, m
LIMIT 100

​

Best Practices

1. Start with Vector-Only: Begin without Neo4j, add it when relationship queries become necessary
2. Use Managed Neo4j: Services like Neo4j AuraDB handle scaling and backups
3. Monitor Graph Size: Track node and relationship counts to understand storage growth
4. Leverage Memory Types: Use classification metadata to organize graph nodes effectively
5. Combine Search Methods: Use vector search for discovery, graph traversal for exploration
6. Regular Backups: Export graph data periodically, especially for production deployments

​

Troubleshooting

​

Graph Store Not Enabled

• Check that NEO4J_URL and NEO4J_PASSWORD are set in .env
• Verify environment variables are loaded (load_dotenv() in main.py:11)
• Restart the Memory API after updating environment variables

​

Connection Errors

• Verify Neo4j instance is running and accessible
• Check firewall rules allow connections to Neo4j port (usually 7687)
• Confirm credentials are correct
• For Neo4j AuraDB, ensure IP allowlist includes your server

​

Performance Issues

• Create indexes on frequently queried properties
• Limit relationship depth in multi-hop queries
• Use LIMIT clauses to bound result sets
• Consider caching frequent queries