Knowledge Graph

At the heart of noodlbox is a knowledge graph - a structured representation of your code that captures symbols, relationships, and organizational patterns.

Why a Graph?

Code is inherently relational:

• Functions call other functions
• Classes inherit from other classes
• Modules import other modules
• Features span multiple files

Relational databases struggle with these interconnections. A graph database makes traversing relationships natural and fast.

Node Types

CodeSymbol

The fundamental unit: functions, classes, methods, variables.

{
  name: "authenticateUser",
  symbol_type: "Function",
  file_path: "src/auth/authenticate.ts",
  line_number: 42
}

File

Source files in your repository.

{
  path: "src/auth/authenticate.ts",
  extension: "ts"
}

Community

Functional groupings detected by modularity analysis.

{
  label: "Authentication",
  cohesion: 0.92,
  symbol_count: 85
}

Process

Execution flows through the codebase.

{
  label: "UserLogin",
  process_type: "cross_community",
  step_count: 5
}

Relationship Types

CALLS

Function/method call relationships.

(authenticate:CodeSymbol)-[:CALLS]->(validateToken:CodeSymbol)

CONTAINED_BY

Symbols contained in files.

(authenticate:CodeSymbol)-[:CONTAINED_BY]->(authFile:File)

MEMBER_OF

Symbols belonging to communities.

(authenticate:CodeSymbol)-[:MEMBER_OF]->(authCommunity:Community)

STEP_IN_PROCESS

Steps in execution processes.

(authenticate:CodeSymbol)-[:STEP_IN_PROCESS {step: 2}]->(loginProcess:Process)

Querying the Graph

noodlbox uses Cypher, a declarative graph query language:

Find all callers of a function

MATCH (caller:CodeSymbol)-[:CALLS]->(target:CodeSymbol)
WHERE target.name = "authenticateUser"
RETURN caller.name, caller.file_path

Trace execution paths

MATCH path = (entry:CodeSymbol)-[:CALLS*1..5]->(target:CodeSymbol)
WHERE entry.name = "handleRequest"
RETURN path

Find community relationships

MATCH (s1:CodeSymbol)-[:MEMBER_OF]->(c1:Community),
      (s2:CodeSymbol)-[:MEMBER_OF]->(c2:Community),
      (s1)-[:CALLS]->(s2)
WHERE c1 <> c2
RETURN c1.label, c2.label, count(*) as cross_calls

Graph Database

noodlbox uses Kuzu, an embedded graph database optimized for analytical queries. This enables:

• Fast traversals across millions of relationships
• Complex pattern matching
• Efficient aggregations

Accessing the Schema

Use the Database Schema resource to inspect the graph structure:

GET db://schema/{repository}

This returns all node types, relationship types, and their properties.

Learn More

• MCP Cypher Query Tool - Execute graph queries
• Database Schema Resource - Explore the schema
• Communities - How communities are structured