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, interfaces, enums, and more.

{
  name: "authenticateUser",
  symbol_type: "Function",
  file_path: "src/auth/authenticate.ts",
  line_number: 42,
  content: "export function authenticateUser(...) { ... }",
  signature: "authenticateUser(credentials: Credentials): Promise<User>"
}

Symbol types by language:

TypeScript	Python
Class, Method, Function	Class, Method, Function
Attribute, Interface	Attribute
TypeAlias, Enum	TypeAlias, Enum
Constant, Export	Constant

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

Storage Architecture

noodlbox uses LanceDB as a unified storage layer for both graph queries and full-text search.

Graph Storage

Graph relationships are stored and queried using lance-graph, enabling:

Fast traversals across millions of relationships
Complex pattern matching with Cypher queries
Efficient aggregations

Full-Text Search

Code search uses LanceDB's built-in FTS with BM25 ranking (powered by Tantivy). This provides:

Relevance-ranked search results
Code-aware stopword filtering
Fast incremental indexing

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

On this page