codegraphcontext 0.2.7__tar.gz → 0.2.9__tar.gz

codegraphcontext-0.2.9/MANIFEST.in

@@ -0,0 +1,4 @@
+prune website
+prune images
+prune vscode-extension
+prune playground

{codegraphcontext-0.2.7/src/codegraphcontext.egg-info → codegraphcontext-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codegraphcontext
-Version: 0.2.7
+Version: 0.2.9
 Summary: An MCP server that indexes local code into a graph database to provide context to AI assistants.
 Author-email: Shashank Shekhar Singh <shashankshekharsingh1205@gmail.com>
 License: MIT License
@@ -50,6 +50,7 @@ Requires-Dist: pytest
 Requires-Dist: nbformat
 Requires-Dist: nbconvert>=7.16.6
 Requires-Dist: pathspec>=0.12.1
+Requires-Dist: falkordb>=0.1.0
 Requires-Dist: falkordblite>=0.1.0; sys_platform != "win32" and python_version >= "3.12"
 Provides-Extra: parsing
 Requires-Dist: tree-sitter>=0.21.0; extra == "parsing"
@@ -146,7 +147,7 @@ A powerful **MCP server** and **CLI toolkit** that indexes local code into a gra
 ---
 
 ## Project Details
-- **Version:** 0.2.7
+- **Version:** 0.2.9
 - **Authors:** Shashank Shekhar Singh <shashankshekharsingh1205@gmail.com>
 - **License:** MIT License (See [LICENSE](LICENSE) for details)
 - **Website:** [CodeGraphContext](http://codegraphcontext.vercel.app/)
@@ -179,7 +180,7 @@ A powerful **MCP server** and **CLI toolkit** that indexes local code into a gra
 -   **Interactive Setup:** A user-friendly command-line wizard for easy setup.
 -   **Dual Mode:** Works as a standalone **CLI toolkit** for developers and as an **MCP server** for AI agents.
 -   **Multi-Language Support:** Full support for 14 programming languages.
--   **Flexible Database Backend:** FalkorDB Lite (default, inbuilt for Unix and through WSL for Windows) or Neo4j (all platforms via Docker/native).
+-   **Flexible Database Backend:** KùzuDB (default, zero-config for all platforms), FalkorDB Lite (Unix-only), FalkorDB Remote, or Neo4j (all platforms via Docker/native).
 
 ---
 
@@ -201,14 +202,16 @@ Each language parser extracts functions, classes, methods, parameters, inheritan
 
 ## Database Options
 
-CodeGraphContext supports two graph database backends:
+CodeGraphContext supports multiple graph database backends to suit your environment:
 
-| Feature | FalkorDB Lite (Default) | Neo4j |
-| :--- | :--- | :--- |
-| **Setup** | Zero-config / In-process | Docker / External |
-| **Platform** | Unix / WSL / macOS | All (incl. Windows Native) |
-| **Use Case** | Local dev & Quick tests | Production & Massive graphs |
-| **Requirement**| Python 3.12+ | Any supported Python |
+| Feature | KùzuDB (Default) | FalkorDB Lite | Neo4j |
+| :--- | :--- | :--- | :--- |
+| **Setup** | Zero-config / Embedded | Zero-config / In-process | Docker / External |
+| **Platform** | **All (Windows Native, macOS, Linux)** | Unix-only (Linux/macOS/WSL) | All Platforms |
+| **Use Case** | Desktop, IDE, Local development | Specialized Unix development | Enterprise, Massive graphs |
+| **Requirement**| `pip install kuzu` | `pip install falkordblite` | Neo4j Server / Docker |
+| **Speed** | ⚡ Extremely Fast | ⚡ Fast | 🚀 Scalable |
+| **Persistence**| Yes (to disk) | Yes (to disk) | Yes (to disk) |
 
 ---
 
@@ -315,10 +318,11 @@ Use CodeGraphContext as an **MCP server** for AI assistants:
     ``` 
     </details>
 
-2.  **Database Setup (Automatic for Unix/WSL)**
+2.  **Database Setup (Automatic)**
     
-    - **FalkorDB Lite (Default):** If you're on Unix/Linux/macOS/WSL with Python 3.12+, you're done! FalkorDB Lite is already configured.
-    - **Neo4j (Optional/Windows):** To use Neo4j instead, or if you're on Windows without WSL, run: `cgc neo4j setup`
+    - **KùzuDB (Default):** Runs natively on Windows, macOS, and Linux without any setup. Just `pip install kuzu` and you're ready!
+    - **FalkorDB Lite (Alternative):** Supported on Unix/macOS/WSL for Python 3.12+.
+    - **Neo4j (Alternative):** To use Neo4j instead, or if you prefer a server-based approach, run: `cgc neo4j setup`
 
 ---
 

{codegraphcontext-0.2.7 → codegraphcontext-0.2.9}/README.md

@@ -84,7 +84,7 @@ A powerful **MCP server** and **CLI toolkit** that indexes local code into a gra
 ---
 
 ## Project Details
-- **Version:** 0.2.7
+- **Version:** 0.2.9
 - **Authors:** Shashank Shekhar Singh <shashankshekharsingh1205@gmail.com>
 - **License:** MIT License (See [LICENSE](LICENSE) for details)
 - **Website:** [CodeGraphContext](http://codegraphcontext.vercel.app/)
@@ -117,7 +117,7 @@ A powerful **MCP server** and **CLI toolkit** that indexes local code into a gra
 -   **Interactive Setup:** A user-friendly command-line wizard for easy setup.
 -   **Dual Mode:** Works as a standalone **CLI toolkit** for developers and as an **MCP server** for AI agents.
 -   **Multi-Language Support:** Full support for 14 programming languages.
--   **Flexible Database Backend:** FalkorDB Lite (default, inbuilt for Unix and through WSL for Windows) or Neo4j (all platforms via Docker/native).
+-   **Flexible Database Backend:** KùzuDB (default, zero-config for all platforms), FalkorDB Lite (Unix-only), FalkorDB Remote, or Neo4j (all platforms via Docker/native).
 
 ---
 
@@ -139,14 +139,16 @@ Each language parser extracts functions, classes, methods, parameters, inheritan
 
 ## Database Options
 
-CodeGraphContext supports two graph database backends:
+CodeGraphContext supports multiple graph database backends to suit your environment:
 
-| Feature | FalkorDB Lite (Default) | Neo4j |
-| :--- | :--- | :--- |
-| **Setup** | Zero-config / In-process | Docker / External |
-| **Platform** | Unix / WSL / macOS | All (incl. Windows Native) |
-| **Use Case** | Local dev & Quick tests | Production & Massive graphs |
-| **Requirement**| Python 3.12+ | Any supported Python |
+| Feature | KùzuDB (Default) | FalkorDB Lite | Neo4j |
+| :--- | :--- | :--- | :--- |
+| **Setup** | Zero-config / Embedded | Zero-config / In-process | Docker / External |
+| **Platform** | **All (Windows Native, macOS, Linux)** | Unix-only (Linux/macOS/WSL) | All Platforms |
+| **Use Case** | Desktop, IDE, Local development | Specialized Unix development | Enterprise, Massive graphs |
+| **Requirement**| `pip install kuzu` | `pip install falkordblite` | Neo4j Server / Docker |
+| **Speed** | ⚡ Extremely Fast | ⚡ Fast | 🚀 Scalable |
+| **Persistence**| Yes (to disk) | Yes (to disk) | Yes (to disk) |
 
 ---
 
@@ -253,10 +255,11 @@ Use CodeGraphContext as an **MCP server** for AI assistants:
     ``` 
     </details>
 
-2.  **Database Setup (Automatic for Unix/WSL)**
+2.  **Database Setup (Automatic)**
     
-    - **FalkorDB Lite (Default):** If you're on Unix/Linux/macOS/WSL with Python 3.12+, you're done! FalkorDB Lite is already configured.
-    - **Neo4j (Optional/Windows):** To use Neo4j instead, or if you're on Windows without WSL, run: `cgc neo4j setup`
+    - **KùzuDB (Default):** Runs natively on Windows, macOS, and Linux without any setup. Just `pip install kuzu` and you're ready!
+    - **FalkorDB Lite (Alternative):** Supported on Unix/macOS/WSL for Python 3.12+.
+    - **Neo4j (Alternative):** To use Neo4j instead, or if you prefer a server-based approach, run: `cgc neo4j setup`
 
 ---
 

{codegraphcontext-0.2.7 → codegraphcontext-0.2.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codegraphcontext"
-version = "0.2.7"
+version = "0.2.9"
 description = "An MCP server that indexes local code into a graph database to provide context to AI assistants."
 authors = [{ name = "Shashank Shekhar Singh", email = "shashankshekharsingh1205@gmail.com" }]
 readme = "README.md"
@@ -29,6 +29,7 @@ dependencies = [
     "nbformat",
     "nbconvert>=7.16.6",
     "pathspec>=0.12.1",
+    "falkordb>=0.1.0",
     "falkordblite>=0.1.0; sys_platform != 'win32' and python_version >= '3.12'"
 ]
 

{codegraphcontext-0.2.7 → codegraphcontext-0.2.9}/src/codegraphcontext/cli/cli_helpers.py

@@ -1,6 +1,6 @@
-# src/codegraphcontext/cli/cli_helpers.py
 import asyncio
 import json
+import uuid
 import urllib.parse
 from pathlib import Path
 import time
@@ -27,10 +27,32 @@ def _initialize_services():
 
     try:
         db_manager.get_driver()
-    except ValueError as e:
-        console.print(f"[bold red]Database Connection Error:[/bold red] {e}")
-        console.print("Please ensure your Neo4j credentials are correct and the database is running.")
-        return None, None, None
+    except Exception as e:
+        # Check if this is a FalkorDB failure that should trigger a KùzuDB fallback
+        from ..core.database_falkordb import FalkorDBUnavailableError
+        if isinstance(e, FalkorDBUnavailableError):
+            console.print(f"[yellow]⚠ FalkorDB Lite is not functional in this environment: {e}[/yellow]")
+            console.print("[cyan]Falling back to KùzuDB for a reliable experience...[/cyan]")
+            
+            # Close the broken driver/socket
+            try:
+                db_manager.close_driver()
+            except Exception:
+                pass
+            
+            # Re-initialize explicitly with KùzuDB
+            from ..core.database_kuzu import KuzuDBManager
+            db_manager = KuzuDBManager()
+            try:
+                db_manager.get_driver()
+                console.print("[green]✓[/green] Successfully switched to KùzuDB fallback")
+            except Exception as kuzu_e:
+                console.print(f"[bold red]Critical Error:[/bold red] Both FalkorDB and KùzuDB failed: {kuzu_e}")
+                return None, None, None
+        else:
+            console.print(f"[bold red]Database Connection Error:[/bold red] {e}")
+            console.print("Please ensure your database is configured correctly or run 'cgc doctor'.")
+            return None, None, None
     
     # The GraphBuilder requires an event loop, even for synchronous-style execution
     try:
@@ -263,16 +285,28 @@ def cypher_helper_visual(query: str):
 import webbrowser
 
 def visualize_helper(query: str):
-    """Generates a visualization."""
+    """"Generates a visualization."""
     services = _initialize_services()
     if not all(services):
         return
 
     db_manager, _, _ = services
     
-    # Check if FalkorDB
-    if "FalkorDB" in db_manager.__class__.__name__:
+    # Check Backend Type
+    backend = getattr(db_manager, "name", "").lower()
+    if not backend:
+        # Fallback check
+        if "FalkorDB" in db_manager.__class__.__name__:
+            backend = "falkordb"
+        elif "Kuzu" in db_manager.__class__.__name__:
+            backend = "kuzudb"
+        else:
+            backend = "neo4j"
+
+    if backend == "falkordb":
         _visualize_falkordb(db_manager)
+    elif backend == "kuzudb":
+        _visualize_kuzudb(db_manager)
     else:
         try:
             encoded_query = urllib.parse.quote(query)
@@ -391,6 +425,138 @@ def _visualize_falkordb(db_manager):
         db_manager.close_driver()
 
 
+def _visualize_kuzudb(db_manager):
+    console.print("[dim]Generating KùzuDB visualization (showing up to 500 relationships)...[/dim]")
+    try:
+        data_nodes = []
+        data_edges = []
+        
+        with db_manager.get_driver().session() as session:
+            # Fetch nodes and edges
+            # KùzuDB returns dicts for n, r, m in the result
+            q = "MATCH (n)-[r]->(m) RETURN n, r, m LIMIT 500"
+            result = session.run(q)
+            
+            seen_nodes = set()
+            
+            # Helper to extract Node ID and props
+            def process_node(node):
+                uid = None
+                lbl = 'Node'
+                props = {}
+                
+                # Handle Kuzu Node Object (processed by wrapper)
+                if hasattr(node, 'properties'):
+                    props = node.properties or {}
+                    if hasattr(node, 'labels') and node.labels:
+                        lbl = node.labels[0]
+                    if hasattr(node, 'id'):
+                        uid = str(node.id)
+                # Handle Dictionary (raw Kuzu result)
+                elif isinstance(node, dict):
+                    if '_id' in node:
+                        uid = f"{node['_id']['table']}_{node['_id']['offset']}"
+                    lbl = node.get('_label', 'Node')
+                    props = {k: v for k, v in node.items() if not k.startswith('_')}
+                
+                if not uid:
+                    uid = str(uuid.uuid4())
+                    
+                name = props.get('name', str(uid))
+                
+                if uid not in seen_nodes:
+                    seen_nodes.add(uid)
+                    color = "#97c2fc" # Default blue
+                    if "Repository" == lbl: color = "#ffb3ba"
+                    elif "File" == lbl: color = "#baffc9"
+                    elif "Class" == lbl: color = "#bae1ff"
+                    elif "Function" == lbl: color = "#ffffba"
+                    elif "Module" == lbl: color = "#ffdfba"
+                    
+                    data_nodes.append({
+                        "id": uid, 
+                        "label": name, 
+                        "group": lbl, 
+                        "title": str(props),
+                        "color": color
+                    })
+                return uid
+            
+            # Iterate results
+            for record in result:
+                # record is dict-like access to row items
+                n = record['n']
+                r = record['r']
+                m = record['m']
+                
+                nid = process_node(n)
+                mid = process_node(m)
+                
+                # Process Edge
+                e_type = 'REL'
+                if hasattr(r, 'type'):
+                    e_type = r.type
+                elif isinstance(r, dict):
+                    e_type = r.get('_label', 'REL')
+                elif hasattr(r, 'label'): # Some versions
+                     e_type = r.label
+                
+                data_edges.append({
+                    "from": nid,
+                    "to": mid,
+                    "label": e_type,
+                    "arrows": "to"
+                })
+        
+        filename = "codegraph_viz.html"
+        html_content = f"""
+<!DOCTYPE html>
+<html>
+<head>
+  <title>CodeGraphContext KùzuDB Visualization</title>
+  <script type="text/javascript" src="https://unpkg.com/vis-network/standalone/umd/vis-network.min.js"></script>
+  <style type="text/css">
+    #mynetwork {{
+      width: 100%;
+      height: 100vh;
+      border: 1px solid lightgray;
+    }}
+  </style>
+</head>
+<body>
+  <div id="mynetwork"></div>
+  <script type="text/javascript">
+    var nodes = new vis.DataSet({json.dumps(data_nodes)});
+    var edges = new vis.DataSet({json.dumps(data_edges)});
+    var container = document.getElementById('mynetwork');
+    var data = {{ nodes: nodes, edges: edges }};
+    var options = {{
+        nodes: {{ shape: 'dot', size: 16 }},
+        physics: {{ stabilization: false }},
+        layout: {{ improvedLayout: false }}
+    }};
+    var network = new vis.Network(container, data, options);
+  </script>
+</body>
+</html>
+"""
+        
+        out_path = Path(filename).resolve()
+        with open(out_path, "w") as f:
+            f.write(html_content)
+            
+        console.print(f"[green]Visualization generated at:[/green] {out_path}")
+        console.print("Opening in default browser...")
+        webbrowser.open(f"file://{out_path}")
+
+    except Exception as e:
+        console.print(f"[bold red]Visualization failed:[/bold red] {e}")
+        import traceback
+        traceback.print_exc()
+    finally:
+        db_manager.close_driver()
+
+
 def reindex_helper(path: str):
     """Force re-index by deleting and rebuilding the repository."""
     time_start = time.time()

{codegraphcontext-0.2.7 → codegraphcontext-0.2.9}/src/codegraphcontext/cli/config_manager.py

@@ -48,7 +48,7 @@ DEFAULT_CONFIG = {
 
 # Configuration key descriptions
 CONFIG_DESCRIPTIONS = {
-    "DEFAULT_DATABASE": "Default database backend (neo4j|falkordb)",
+    "DEFAULT_DATABASE": "Default database backend (neo4j|falkordb|kuzudb)",
     "FALKORDB_PATH": "Path to FalkorDB database file",
     "FALKORDB_SOCKET_PATH": "Path to FalkorDB Unix socket",
     "INDEX_VARIABLES": "Index variable nodes in the graph (lighter graph if false)",
@@ -75,7 +75,7 @@ CONFIG_DESCRIPTIONS = {
 
 # Valid values for each config key
 CONFIG_VALIDATORS = {
-    "DEFAULT_DATABASE": ["neo4j", "falkordb"],
+    "DEFAULT_DATABASE": ["neo4j", "falkordb", "kuzudb"],
     "INDEX_VARIABLES": ["true", "false"],
     "ALLOW_DB_DELETION": ["true", "false"],
     "DEBUG_LOGS": ["true", "false"],

{codegraphcontext-0.2.7 → codegraphcontext-0.2.9}/src/codegraphcontext/cli/main.py

@@ -229,6 +229,13 @@ def _load_credentials():
     from dotenv import dotenv_values
     from codegraphcontext.cli.config_manager import ensure_config_dir
     
+    # Capture DATABASE_TYPE from actual shell env BEFORE we load .env files.
+    # If the user ran `DATABASE_TYPE=falkordb cgc …` we must not let
+    # DEFAULT_DATABASE=neo4j in .env steal priority later.
+    shell_db_type = os.environ.get('DATABASE_TYPE')
+    if shell_db_type and not os.environ.get('CGC_RUNTIME_DB_TYPE'):
+        os.environ['CGC_RUNTIME_DB_TYPE'] = shell_db_type
+
     # Ensure config directory exists (lazy initialization)
     ensure_config_dir()
     
@@ -272,9 +279,16 @@ def _load_credentials():
     for config in config_sources:
         merged_config.update(config)
     
-    # Apply merged config to environment
+    # Apply merged config to environment.
+    # IMPORTANT: DB-selection keys set in the shell must win over .env defaults.
+    # E.g. `DATABASE_TYPE=falkordb cgc index …` must not be overridden by
+    # DEFAULT_DATABASE=neo4j sitting in ~/.codegraphcontext/.env
+    DB_OVERRIDE_KEYS = {"DATABASE_TYPE", "CGC_RUNTIME_DB_TYPE", "DEFAULT_DATABASE"}
     for key, value in merged_config.items():
         if value is not None:  # Only set non-None values
+            # Never let .env clobber a DB-type key that the user already set in the shell
+            if key in DB_OVERRIDE_KEYS and key in os.environ:
+                continue
             os.environ[key] = str(value)
     
     # Report what was loaded
@@ -287,14 +301,31 @@ def _load_credentials():
         console.print("[yellow]No configuration file found. Using defaults.[/yellow]")
     
     
-    # Show which database is actually being used
-    # Check for runtime override first (from -db/--database flag)
+    # Show which database is actually being used.
+    # When DATABASE_TYPE is explicitly set, trust it.  When it's left to auto-
+    # detect, call get_database_manager() so the banner can never lie: e.g. if
+    # falkordblite is installed but its native .so is missing (frozen bundle),
+    # the factory falls back to KùzuDB and we display that correctly.
     runtime_db = os.environ.get("CGC_RUNTIME_DB_TYPE")
-    if runtime_db:
-        default_db = runtime_db.lower()
+    explicit_db = (
+        runtime_db
+        or os.environ.get("DEFAULT_DATABASE")
+        or os.environ.get("DATABASE_TYPE")
+    )
+
+    if explicit_db:
+        default_db = explicit_db.lower()
     else:
-        default_db = os.environ.get("DEFAULT_DATABASE", "falkordb").lower()
-    
+        # No explicit choice — ask the factory which backend it will use
+        try:
+            from codegraphcontext.core import get_database_manager
+            _mgr = get_database_manager()
+            default_db = _mgr.get_backend_type()   # e.g. 'falkordb' / 'kuzudb'
+        except Exception:
+            # Factory failed entirely — still show a best-guess
+            from codegraphcontext.core import _is_falkordb_available
+            default_db = "falkordb" if _is_falkordb_available() else "kuzudb"
+
     if default_db == "neo4j":
         has_neo4j_creds = all([
             os.environ.get("NEO4J_URI"),
@@ -308,18 +339,26 @@ def _load_credentials():
             else:
                 console.print("[cyan]Using database: Neo4j[/cyan]")
         else:
-            console.print("[yellow]⚠ DEFAULT_DATABASE=neo4j but credentials not found. Falling back to FalkorDB.[/yellow]")
+            console.print("[yellow]⚠ DEFAULT_DATABASE=neo4j but credentials not found. Falling back to default.[/yellow]")
+    elif default_db == "falkordb":
+        console.print("[cyan]Using database: FalkorDB Lite[/cyan]")
+    elif default_db == "kuzudb":
+        console.print("[cyan]Using database: KùzuDB[/cyan]")
     elif default_db == "falkordb-remote":
         host = os.environ.get("FALKORDB_HOST")
         if host:
             console.print(f"[cyan]Using database: FalkorDB Remote ({host})[/cyan]")
         else:
             console.print("[yellow]⚠ DATABASE_TYPE=falkordb-remote but FALKORDB_HOST not set.[/yellow]")
-    else:
+    elif default_db == "falkordb":
         if os.environ.get("FALKORDB_HOST"):
             console.print(f"[cyan]Using database: FalkorDB Remote ({os.environ.get('FALKORDB_HOST')})[/cyan]")
         else:
             console.print("[cyan]Using database: FalkorDB[/cyan]")
+    else:
+        console.print(f"[cyan]Using database: {default_db}[/cyan]")
+
+
 
 # ============================================================================
 # CONFIG COMMAND GROUP

codegraphcontext-0.2.9/src/codegraphcontext/core/__init__.py

@@ -0,0 +1,176 @@
+# src/codegraphcontext/core/__init__.py
+"""
+Core database management module.
+
+Supports Neo4j, FalkorDB Lite, remote FalkorDB, and KùzuDB backends.
+Use DATABASE_TYPE environment variable to switch:
+- DATABASE_TYPE=kuzudb - Uses embedded KùzuDB (Recommended for cross-platform zero-config)
+- DATABASE_TYPE=falkordb - Uses embedded FalkorDB Lite (Unix-only)
+- DATABASE_TYPE=falkordb-remote - Uses a remote/hosted FalkorDB server over TCP
+- DATABASE_TYPE=neo4j - Uses Neo4j server
+- If not set, auto-detects based on what's available
+
+ Priority (no DATABASE_TYPE set):
+  1. FalkorDB Lite  (Unix + Python 3.12+ + falkordblite installed)
+  2. KùzuDB         (cross-platform fallback)
+  3. Remote FalkorDB (if FALKORDB_HOST is set)
+  4. Neo4j           (if credentials are configured)
+"""
+import os
+import platform
+from typing import Union
+
+import importlib.util
+
+def _is_kuzudb_available() -> bool:
+    """Check if KùzuDB is installed."""
+    try:
+        return importlib.util.find_spec("kuzu") is not None
+    except ImportError:
+        return False
+
+def _is_falkordb_available() -> bool:
+    """Check if FalkorDB Lite is installed (Unix only)."""
+    if platform.system() == "Windows":
+        return False
+
+    import sys
+    if sys.version_info < (3, 12):
+        return False
+    try:
+        import redislite
+        return hasattr(redislite, 'falkordb_client')
+    except ImportError:
+        return False
+
+def _is_falkordb_remote_configured() -> bool:
+    """Check if a remote FalkorDB host is configured."""
+    return bool(os.getenv('FALKORDB_HOST'))
+
+def _is_neo4j_configured() -> bool:
+    """Check if Neo4j is configured with credentials."""
+    return all([
+        os.getenv('NEO4J_URI'),
+        os.getenv('NEO4J_USERNAME'),
+        os.getenv('NEO4J_PASSWORD')
+    ])
+
+def get_database_manager() -> Union['DatabaseManager', 'FalkorDBManager', 'FalkorDBRemoteManager', 'KuzuDBManager']:
+    """
+    Factory function to get the appropriate database manager based on configuration.
+
+    Selection logic:
+    1. Runtime Override: 'CGC_RUNTIME_DB_TYPE' (set via --database flag)
+    2. Configured Default: 'DEFAULT_DATABASE' (set via 'cgc default database')
+    3. Legacy Env Var: 'DATABASE_TYPE'
+    4. Implicit Default: KùzuDB (Best cross-platform zero-config)
+    5. Auto-detect: Remote FalkorDB (if FALKORDB_HOST is set)
+    6. Fallback Default: FalkorDB Lite (if Unix and available)
+    7. Fallback: Neo4j (if configured)
+    """
+    from codegraphcontext.utils.debug_log import info_logger
+
+    # 1. Runtime Override (CLI flag) or Config/Env
+    db_type = os.getenv('CGC_RUNTIME_DB_TYPE')
+    if not db_type:
+        db_type = os.getenv('DEFAULT_DATABASE')
+    if not db_type:
+        db_type = os.getenv('DATABASE_TYPE')
+
+    if db_type:
+        db_type = db_type.lower()
+        if db_type == 'kuzudb':
+            if not _is_kuzudb_available():
+                raise ValueError("Database set to 'kuzudb' but Kùzu is not installed.\nRun 'pip install kuzu'")
+            from .database_kuzu import KuzuDBManager
+            info_logger("Using KùzuDB (explicit)")
+            return KuzuDBManager()
+
+        elif db_type == 'falkordb':
+            if not _is_falkordb_available():
+                info_logger("FalkorDB Lite is not supported or not installed. Falling back to KùzuDB.")
+                if _is_kuzudb_available():
+                    from .database_kuzu import KuzuDBManager
+                    return KuzuDBManager()
+                raise ValueError("Database set to 'falkordb' but FalkorDB Lite is not installed or not supported on this OS.\nRun 'pip install falkordblite'")
+            
+            from .database_falkordb import FalkorDBManager, FalkorDBUnavailableError
+            try:
+                mgr = FalkorDBManager()
+                info_logger("Using FalkorDB Lite (explicit)")
+                return mgr
+            except FalkorDBUnavailableError as falkor_err:
+                info_logger(f"FalkorDB Lite not functional ({falkor_err}). Falling back to KùzuDB.")
+                if _is_kuzudb_available():
+                    from .database_kuzu import KuzuDBManager
+                    return KuzuDBManager()
+                raise
+
+        elif db_type == 'falkordb-remote':
+            if not _is_falkordb_remote_configured():
+                raise ValueError(
+                    "Database set to 'falkordb-remote' but FALKORDB_HOST is not set.\n"
+                    "Set the FALKORDB_HOST environment variable to your remote FalkorDB host."
+                )
+            from .database_falkordb_remote import FalkorDBRemoteManager
+            info_logger("Using remote FalkorDB (explicit)")
+            return FalkorDBRemoteManager()
+
+        elif db_type == 'neo4j':
+            if not _is_neo4j_configured():
+                raise ValueError("Database set to 'neo4j' but it is not configured.\nRun 'cgc neo4j setup' to configure Neo4j.")
+            from .database import DatabaseManager
+            info_logger("Using Neo4j Server (explicit)")
+            return DatabaseManager()
+        else:
+            raise ValueError(f"Unknown database type: '{db_type}'. Use 'kuzudb', 'falkordb', 'falkordb-remote', or 'neo4j'.")
+
+    # 4. Implicit Default -> FalkorDB Lite (Unix Zero Config)
+    if _is_falkordb_available():
+        from .database_falkordb import FalkorDBManager, FalkorDBUnavailableError
+        try:
+            mgr = FalkorDBManager()
+            info_logger("Using FalkorDB Lite (default)")
+            return mgr
+        except FalkorDBUnavailableError as falkor_err:
+            info_logger(
+                f"FalkorDB Lite not functional in this environment ({falkor_err}). "
+                "Falling back to KùzuDB."
+            )
+            # fall through to KùzuDB below
+
+    # 5. Implicit Default -> KùzuDB (Best Zero Config)
+    if _is_kuzudb_available():
+        from .database_kuzu import KuzuDBManager
+        info_logger("Using KùzuDB (default)")
+        return KuzuDBManager()
+
+    # 6. Auto-detect: Remote FalkorDB (if FALKORDB_HOST is set)
+    if _is_falkordb_remote_configured():
+        from .database_falkordb_remote import FalkorDBRemoteManager
+        info_logger("Using remote FalkorDB (auto-detected via FALKORDB_HOST)")
+        return FalkorDBRemoteManager()
+
+    # 7. Fallback if configured
+    if _is_neo4j_configured():
+        from .database import DatabaseManager
+        info_logger("Using Neo4j Server (auto-detected)")
+        return DatabaseManager()
+
+    error_msg = "No database backend available.\n"
+    error_msg += "Recommended: Install KùzuDB for zero-config ('pip install kuzu')\n"
+
+    if platform.system() != "Windows":
+        error_msg += "Alternative: Install FalkorDB Lite ('pip install falkordblite')\n"
+
+    error_msg += "Alternative: Run 'cgc neo4j setup' to configure Neo4j."
+
+    raise ValueError(error_msg)
+
+# For backward compatibility, export managers
+from .database import DatabaseManager
+from .database_falkordb import FalkorDBManager
+from .database_falkordb_remote import FalkorDBRemoteManager
+from .database_kuzu import KuzuDBManager
+
+__all__ = ['DatabaseManager', 'FalkorDBManager', 'FalkorDBRemoteManager', 'KuzuDBManager', 'get_database_manager']