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

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, 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 (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. 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:

# 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:

# 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"

# 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"

# 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, 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. 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.

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