GitNexus KuzuDB Graph Schema: A Complete Technical Guide

GitNexus uses a hybrid KuzuDB graph schema that stores code elements in dedicated node tables while routing all relationships through a single generic edge table called CodeRelation.

The KuzuDB graph schema powers GitNexus's ability to map complex codebases across multiple programming languages. Defined entirely in gitnexus/src/core/kuzu/schema.ts, this schema creates a type-safe graph structure that supports both structural relationships and semantic vector search.

Core Components of the GitNexus KuzuDB Graph Schema

Node Tables: Code Element Entities

The schema defines dedicated node tables for every code element type, providing strongly-typed storage for repository entities. Core tables include File, Folder, Function, Class, Interface, Method, CodeElement, Community, and Process.

Beyond these core entities, the KuzuDB graph schema supports 18 language-specific tables for multi-language repositories. These include Struct, Enum, Macro, Trait, Impl, Namespace, Package, Module, and other constructs required for C, C++, Rust, Go, Java, C#, and additional languages.

Each node table schema includes element-specific columns such as startLine, endLine, isExported, filePath, and content, enabling precise source-code mapping.

The CodeRelation Edge Table

All relationships in the GitNexus KuzuDB graph schema flow through a single generic relation table named CodeRelation. This hybrid approach simplifies the graph model while maintaining expressiveness.

The CodeRelation table stores edge metadata including:

• type: The relationship category
• confidence: Numerical confidence score
• reason: Explanation for the relationship
• step: Process step identifier

Supported relationship types include:

• CONTAINS – Hierarchical containment
• DEFINES – Definition relationships
• IMPORTS – Dependency imports
• CALLS – Function/method invocations
• EXTENDS – Inheritance relationships
• IMPLEMENTS – Interface implementations
• MEMBER_OF – Membership associations
• STEP_IN_PROCESS – Workflow step relationships

The schema definition in gitnexus/src/core/kuzu/schema.ts includes a comprehensive CREATE REL TABLE statement enumerating every allowed FROM … TO … pair across all node tables.

Semantic Search with CodeEmbedding

The KuzuDB graph schema includes a dedicated CodeEmbedding table for vector storage, isolating high-dimensional embeddings from the main graph structure to avoid copy-on-write overhead.

Key characteristics:

• Stores nodeId references and 384-dimensional FLOAT vectors
• Supports Kuzu's HNSW index with cosine similarity for fast approximate nearest neighbor search
• Enables semantic code search across the repository graph

Schema Definition and Creation Order

DDL Statements in schema.ts

The gitnexus/src/core/kuzu/schema.ts module exports complete DDL strings for every component:

• FILE_SCHEMA, FUNCTION_SCHEMA, CLASS_SCHEMA, etc. – Individual node table creation statements
• RELATION_SCHEMA – The massive relationship table DDL connecting all node types
• EMBEDDING_SCHEMA – Vector table definition
• CREATE_VECTOR_INDEX_QUERY – HNSW index creation with cosine metric

Ordered Execution with SCHEMA_QUERIES

The schema guarantees correct initialization through SCHEMA_QUERIES, an ordered array that executes DDL in dependency-safe sequence:

1. Node table creation – All CREATE NODE TABLE statements execute first
2. Relation table creation – CREATE REL TABLE runs after nodes exist
3. Embedding table creation – Vector storage initialization
4. Index creation – HNSW vector index built last

This ordering prevents "table not found" errors during repository indexing, as implemented in the connection pool at gitnexus/src/mcp/core/kuzu-adapter.ts.

Working with the Schema: Practical Examples

Initializing the Database

Use the Kuzu adapter to initialize the schema in your target database:

import { initKuzu, executeQuery } from './gitnexus/src/mcp/core/kuzu-adapter.js';
import {
  SCHEMA_QUERIES,
  CREATE_VECTOR_INDEX_QUERY,
} from './gitnexus/src/core/kuzu/schema.js';

const dbPath = '/tmp/gitnexus-db/kuzu.db';
const repoId = 'my-repo';

// Initialize connection pool (opens DB read-only)
await initKuzu(repoId, dbPath);

// Execute schema creation in dependency order
for (const ddl of SCHEMA_QUERIES) {
  await executeQuery(repoId, ddl);
}

// Create HNSW vector index for semantic search
await executeQuery(repoId, CREATE_VECTOR_INDEX_QUERY);

Inserting Code Elements

Insert a function node with its metadata:

const INSERT_FUNCTION = `
  CREATE (:Function {
    id: $id,
    name: $name,
    filePath: $filePath,
    startLine: $start,
    endLine: $end,
    isExported: $exported,
    content: $content,
    description: $desc
  })
`;

await executeQuery(repoId, INSERT_FUNCTION, {
  id: 'fn-123',
  name: 'authenticateUser',
  filePath: 'src/auth.ts',
  start: 15,
  end: 42,
  exported: true,
  content: 'function authenticateUser(...) { ... }',
  desc: 'Validates user credentials against database',
});

Querying Relationships

Traverse CALLS relationships between functions:

const CALLS_QUERY = `
  MATCH (caller:Function)-[r:CodeRelation {type: 'CALLS'}]->(callee:Function)
  WHERE caller.id = $callerId
  RETURN callee.name AS functionName, 
         callee.filePath AS location, 
         r.confidence AS confidence
`;

const results = await executeQuery(repoId, CALLS_QUERY, { 
  callerId: 'fn-123' 
});
console.log('Functions called by fn-123:', results);

Performing Semantic Search

Execute vector similarity search using the embedding table:

import { EMBEDDING_TABLE_NAME } from './gitnexus/src/core/kuzu/schema.js';

// Assume queryVector is a Float32Array[384] generated from your embedding model
const SEMANTIC_SEARCH = `
  CALL ANN('knn', '${EMBEDDING_TABLE_NAME}', '${queryVector}', 
           topK := 5, metric := 'cosine')
`;

const similarNodes = await executeQuery(repoId, SEMANTIC_SEARCH);
console.log('Semantically similar code elements:', similarNodes);

Summary

• GitNexus implements a hybrid KuzuDB graph schema that stores code elements in type-specific node tables while routing all relationships through a single CodeRelation edge table.
• The schema supports 27+ node types including core entities (File, Function, Class) and 18 language-specific tables for multi-language repository analysis.
• Relationship types include CONTAINS, DEFINES, CALLS, IMPORTS, EXTENDS, IMPLEMENTS, MEMBER_OF, and STEP_IN_PROCESS.
• Semantic search capabilities are provided through the CodeEmbedding table with 384-dimensional vectors and HNSW index support using cosine similarity.
• Schema initialization follows a strict order defined in SCHEMA_QUERIES: node tables first, then relations, then embeddings, preventing dependency errors during database setup.

Frequently Asked Questions

What file defines the KuzuDB graph schema in GitNexus?

The complete schema definition resides in gitnexus/src/core/kuzu/schema.ts. This TypeScript module exports all DDL statements, table names, and the ordered SCHEMA_QUERIES array used to initialize the database.

How does GitNexus handle relationships between different code elements?

GitNexus uses a single generic relation table named CodeRelation that connects all node types. Rather than creating separate edge tables for each relationship type, the schema stores the relationship category in a type property within the CodeRelation table, supporting values like CALLS, IMPORTS, and CONTAINS.

Can GitNexus analyze repositories in programming languages other than TypeScript?

Yes. While GitNexus is written in TypeScript, its KuzuDB graph schema includes 18 language-specific node tables designed to support C, C++, Rust, Go, Java, C#, and other languages. These tables extend the core schema to capture language-specific constructs like Struct, Enum, Macro, Trait, and Module.

How does the schema support semantic code search?

The schema includes a dedicated CodeEmbedding node table that stores 384-dimensional floating-point vectors for code elements. Combined with the CREATE_VECTOR_INDEX_QUERY that builds an HNSW index using cosine similarity, this enables fast approximate nearest neighbor searches for semantic code retrieval across the repository graph.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}