# Understanding the Qualified Name System for Code Snippets and Graph Nodes in codebase-memory-mcp

> Learn how the qualified name system in codebase-memory-mcp generates unique identifiers for code elements. Precisely reference functions, classes, and methods across your entire codebase with this powerful system.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: deep-dive
- Published: 2026-07-16

---

**The qualified name system in codebase-memory-mcp creates unique, dot-separated identifiers by combining a module's import path with symbol names, enabling precise reference to any function, class, or method across the entire codebase.**

The codebase-memory-mcp project implements a robust naming convention that assigns every code definition a globally unique identifier. This qualified name system serves as the backbone for the graph engine, allowing nodes to reference specific source fragments unambiguously across multiple languages and projects.

## How Qualified Names Are Constructed

The repository defines a strict construction pattern that varies by symbol type. Each qualified name is a dot-separated string that encodes the hierarchical location of a definition within the codebase.

### Function and Class Naming Conventions

For top-level definitions, the system concatenates the module's qualified name with the symbol identifier:

- **Functions**: `module_qn + "." + function_name`
- **Classes**: `module_qn + "." + class_name`

In [`scripts/gen-py-stdlib.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/gen-py-stdlib.py), the generation logic implements this at line 170 for classes (`f"{current_module_qn}.{node.name}"`) and line 184 for functions (`f"{current_module_qn}.{name}"`). The data structures that hold these names, `StubClass` and `StubFunction`, declare the `qualified_name` field at lines 88-92 and 96-99 respectively.

### Method Naming Conventions

Methods receive qualified names that incorporate their parent class's qualified name, ensuring uniqueness even when method names collide across different classes:

- **Pattern**: `class_qn + "." + method_name`

When emitting methods in [`scripts/gen-py-stdlib.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/gen-py-stdlib.py) (around line 286), the generator prefixes the method with the owning class's qualified name using the pattern `f"{mod_qn}.{f.short_name}"` (where `f` represents the function stub).

## Implementation in the Generation Pipeline

The core logic that assembles qualified names resides in [`scripts/gen-py-stdlib.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/gen-py-stdlib.py). This script generates C source code that populates the CBM type registry, using the qualified name as the primary key.

At lines 356-389, the generated C code assigns the qualified name to the registry: `rt.qualified_name = "..."`. This creates the binding between the graph nodes and their corresponding source definitions. The construction follows these patterns:

```python

# From scripts/gen-py-stdlib.py - Class qualified name construction (lines 170-175)

class_qualified_name = f"{current_module_qn}.{node.name}"

# From scripts/gen-py-stdlib.py - Function qualified name construction (lines 184-186)

function_qualified_name = f"{current_module_qn}.{name}"

# From scripts/gen-py-stdlib.py - Method emission (around line 286)

method_qualified_name = f"{class_qualified_name}.{method_name}"

```

## Using Qualified Names with the Graph Engine

Every definition node in the graph stores its identity in an attribute named `qualified_name`. This attribute matches exactly the string built by the generation rules, creating a consistent addressing scheme across the entire system.

The public API exposes this through the `get_code_snippet()` function, which accepts a `qualified_name` parameter to locate exact source fragments. Because qualified names uniquely resolve to single definitions across all languages and projects, the graph engine can retrieve specific nodes without ambiguity.

## Code Examples

The following examples demonstrate how to construct and use qualified names according to the codebase-memory-mcp specification:

```python

# Example: Building a qualified name for a function

module_qn = "Text.Pandoc.Readers"
fn_name = "getReader"
fn_qn = f"{module_qn}.{fn_name}"

# Result: "Text.Pandoc.Readers.getReader"

```

```python

# Example: Building a qualified name for a method

class_qn = "github.com/go-chi/chi/v5.(*node)"
method = "findRoute"
method_qn = f"{class_qn}.{method}"

# Result: "github.com/go-chi/chi/v5.(*node).findRoute"

```

```python

# Retrieving a snippet via the public API

snippet = get_code_snippet(qualified_name="github.com/go-chi/chi/v5.(*node).findRoute")

```

## Summary

- **Qualified names** in codebase-memory-mcp are dot-separated strings combining module import paths with symbol identifiers.
- **Functions and classes** use the pattern `module_qn.name`, while **methods** use `class_qn.name`.
- The generation logic lives in [`scripts/gen-py-stdlib.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/gen-py-stdlib.py), specifically between lines 88-389, where `StubClass` and `StubFunction` data structures are defined and populated.
- The **graph engine** uses these names as node keys, enabling the `get_code_snippet(qualified_name=...)` API to retrieve specific source fragments.
- This system ensures unique identification across multilingual codebases and prevents naming collisions.

## Frequently Asked Questions

### What is the purpose of the qualified name system in codebase-memory-mcp?

The qualified name system provides globally unique identifiers for every function, class, and method in the codebase. This allows the graph engine to reference specific definitions unambiguously and enables the `get_code_snippet()` API to retrieve exact source fragments without collisions.

### How does codebase-memory-mcp handle method qualified names differently from functions?

While functions use the module's qualified name as their prefix (`module_qn.function_name`), methods incorporate their parent class's qualified name (`class_qn.method_name`). This distinction ensures that methods with common names like `get` or `set` remain unique when belonging to different classes.

### Which file contains the logic for generating qualified names?

The primary logic resides in [`scripts/gen-py-stdlib.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/gen-py-stdlib.py). This file defines the `StubClass` and `StubFunction` data structures (lines 88-99) and implements the construction patterns at lines 170-175 for classes, lines 184-186 for functions, and lines 275-286 for the final emission of qualified names to the CBM type registry.

### How do I retrieve a code snippet using a qualified name?

Use the public API function `get_code_snippet(qualified_name="...")`, passing the dot-separated qualified name string as the parameter. The name must match the exact format generated by the system, such as `Text.Pandoc.Readers.getReader` for functions or `github.com/go-chi/chi/v5.(*node).findRoute` for methods.