Code Graph

A minimal guide to turning a code repository into a knowledge graph and querying it. The pipeline extracts facts such as modules, symbols, routes, storage, services, and dependencies with the external enola extractor, loads them as typed graph nodes and edges, and answers structured queries — no LLM or embedding provider involved.

Before You Start

Complete Quickstart to understand basic operations
Read Pipelines and Tasks for how a custom pipeline is assembled from tasks
Have the enola binary available: it is installed automatically on the first run (pinned release, checksum-verified, placed in ~/.cognee/bin), or install it yourself and point ENOLA_PATH at it
Set CODE_GRAPH_REPO_PATH to the repository you want to index — it defaults to the current working directory
No LLM Providers or embedding configuration is required: both the pipeline and SearchType.CODE are deterministic

Code in Action

import asyncio
import json
import os

import cognee
from cognee import SearchType
from cognee.shared.logging_utils import ERROR, setup_logging
from cognee.tasks.code_graph import get_code_graph_tasks


async def main():
    repo_path = os.getenv("CODE_GRAPH_REPO_PATH", os.getcwd())

    # Start clean so the example is reproducible.
    await cognee.prune.prune_data()
    await cognee.prune.prune_system(metadata=True)

    print(f"Extracting code graph from: {repo_path}")
    await cognee.run_custom_pipeline(
        # Pass index_vectors=True only if these facts should also be available
        # to semantic/LLM retrievers; SearchType.CODE does not need it.
        tasks=get_code_graph_tasks(repo_path),
        data=repo_path,
        dataset="code_graph_demo",
        pipeline_name="code_graph_pipeline",
        # This pipeline is deterministic (no LLM/embedding calls), so skip the
        # first-run LLM/embedding connection checks and stay truly keyless.
        skip_connection_test=True,
    )

    print("Listing the first indexed code facts")
    search_results = await cognee.search(
        query_type=SearchType.CODE,
        query_text="",
        datasets=["code_graph_demo"],
        code_query={
            "operation": "query_facts",
            "kinds": ["module", "symbol", "route", "storage", "service"],
            "limit": 20,
        },
    )

    print(json.dumps(search_results, indent=2, default=str))

    print("Module-level architecture overview, drawn as a Mermaid diagram")
    architecture = await cognee.search(
        query_type=SearchType.CODE,
        query_text="",
        datasets=["code_graph_demo"],
        # Symbol-to-symbol edges are rolled up to the modules that declare
        # them; routes/storage/services hang off their modules. The result
        # includes deterministic Mermaid source (paste it into any Markdown
        # renderer that supports ```mermaid fences); "diagram": "dot" gives
        # Graphviz, and any other operation accepts the same option.
        code_query={"operation": "architecture", "max_nodes": 40},
    )
    # search() returns one {dataset_id, dataset_name, search_result} entry per
    # dataset; the CODE operation's result is the (single) search_result item.
    for entry in architecture:
        payload = entry.get("search_result") if isinstance(entry, dict) else None
        if isinstance(payload, list) and payload:
            payload = payload[0]
        diagram = payload.get("diagram") if isinstance(payload, dict) else None
        if diagram and diagram.get("source"):
            print(diagram["source"])

    print("Architecture findings enola's explainers produced (with their evidence facts)")
    insights = await cognee.search(
        query_type=SearchType.CODE,
        query_text="",
        datasets=["code_graph_demo"],
        # Structural findings (cycles, declared-layer violations) score 1.0;
        # heuristic ones (hotspots, god-class, complexity outliers) score below.
        code_query={"operation": "insights", "min_confidence": 0.5, "limit": 10},
    )
    print(json.dumps(insights, indent=2, default=str))

    # Other deterministic operations use the same API shape. Ids may be
    # cognee node ids or enola's own 32-hex fact ids (from facts.jsonl):
    # code_query={"operation": "explore", "id": "<fact id>", "max_depth": 2}
    # code_query={"operation": "traverse", "node_ids": ["<fact id>"], "direction": "reverse"}
    # code_query={"operation": "find_path", "source_id": "<id>", "target_id": "<id>"}
    # code_query={"operation": "impact_analysis", "id": "<fact id>", "max_depth": 3}
    # code_query={"operation": "query_facts", "kind": "dependency", "prop": "type",
    #             "prop_value": "package"}   # declared packages from manifests (purl names)
    # code_query={"operation": "delta"}    # last ingestion's changes + the snapshot receipt


if __name__ == "__main__":
    logger = setup_logging(log_level=ERROR)
    asyncio.run(main())

What Just Happened

Step 1: Choose the Repository and Start Clean

repo_path = os.getenv("CODE_GRAPH_REPO_PATH", os.getcwd())

# Start clean so the example is reproducible.
await cognee.prune.prune_data()
await cognee.prune.prune_system(metadata=True)

The repository to index comes from CODE_GRAPH_REPO_PATH, falling back to the directory you run the script from. Pruning first means the graph you inspect afterwards contains only what this run extracted.

Step 2: Run the Code Graph Pipeline

print(f"Extracting code graph from: {repo_path}")
await cognee.run_custom_pipeline(
    # Pass index_vectors=True only if these facts should also be available
    # to semantic/LLM retrievers; SearchType.CODE does not need it.
    tasks=get_code_graph_tasks(repo_path),
    data=repo_path,
    dataset="code_graph_demo",
    pipeline_name="code_graph_pipeline",
    # This pipeline is deterministic (no LLM/embedding calls), so skip the
    # first-run LLM/embedding connection checks and stay truly keyless.
    skip_connection_test=True,
)

get_code_graph_tasks() returns the three ordered tasks the pipeline runs: extract (run enola over the repository and map its facts to DataPoints), load the graph nodes, then load the typed relations as edges. Because nothing here calls an LLM or an embedding model, skip_connection_test=True skips the first-run provider checks so the pipeline runs without any API key.

Step 3: Query the Graph with SearchType.CODE

print("Listing the first indexed code facts")
search_results = await cognee.search(
    query_type=SearchType.CODE,
    query_text="",
    datasets=["code_graph_demo"],
    code_query={
        "operation": "query_facts",
        "kinds": ["module", "symbol", "route", "storage", "service"],
        "limit": 20,
    },
)

print(json.dumps(search_results, indent=2, default=str))

SearchType.CODE is driven by the structured code_query argument rather than by query_text, which stays empty here. The query_facts operation filters the extracted facts — by kinds in this case — and returns the first limit matches, so the result is a deterministic listing rather than a similarity ranking.

Step 4: Draw the Architecture and Read the Insights

print("Module-level architecture overview, drawn as a Mermaid diagram")
architecture = await cognee.search(
    query_type=SearchType.CODE,
    query_text="",
    datasets=["code_graph_demo"],
    # Symbol-to-symbol edges are rolled up to the modules that declare
    # them; routes/storage/services hang off their modules. The result
    # includes deterministic Mermaid source (paste it into any Markdown
    # renderer that supports ```mermaid fences); "diagram": "dot" gives
    # Graphviz, and any other operation accepts the same option.
    code_query={"operation": "architecture", "max_nodes": 40},
)
# search() returns one {dataset_id, dataset_name, search_result} entry per
# dataset; the CODE operation's result is the (single) search_result item.
for entry in architecture:
    payload = entry.get("search_result") if isinstance(entry, dict) else None
    if isinstance(payload, list) and payload:
        payload = payload[0]
    diagram = payload.get("diagram") if isinstance(payload, dict) else None
    if diagram and diagram.get("source"):
        print(diagram["source"])

print("Architecture findings enola's explainers produced (with their evidence facts)")
insights = await cognee.search(
    query_type=SearchType.CODE,
    query_text="",
    datasets=["code_graph_demo"],
    # Structural findings (cycles, declared-layer violations) score 1.0;
    # heuristic ones (hotspots, god-class, complexity outliers) score below.
    code_query={"operation": "insights", "min_confidence": 0.5, "limit": 10},
)
print(json.dumps(insights, indent=2, default=str))

The architecture operation rolls symbol-level edges up to the modules that declare them and returns a ready-to-render diagram alongside the nodes — Mermaid by default, Graphviz with "diagram": "dot". The insights operation returns the findings enola’s explainers produced over the same graph, each with the evidence facts behind it; min_confidence separates the structural findings that always score 1.0 from the heuristic ones below it.

Step 5: Reuse the Same Shape for Other Operations

# Other deterministic operations use the same API shape. Ids may be
# cognee node ids or enola's own 32-hex fact ids (from facts.jsonl):
# code_query={"operation": "explore", "id": "<fact id>", "max_depth": 2}
# code_query={"operation": "traverse", "node_ids": ["<fact id>"], "direction": "reverse"}
# code_query={"operation": "find_path", "source_id": "<id>", "target_id": "<id>"}
# code_query={"operation": "impact_analysis", "id": "<fact id>", "max_depth": 3}
# code_query={"operation": "query_facts", "kind": "dependency", "prop": "type",
#             "prop_value": "package"}   # declared packages from manifests (purl names)
# code_query={"operation": "delta"}    # last ingestion's changes + the snapshot receipt

Every other operation is the same cognee.search() call with a different code_query. Take a fact id from the query_facts output above and feed it to explore to see a fact’s neighborhood, traverse to walk edges in one direction, find_path to connect two facts, or impact_analysis to see what depends on a fact. query_facts also filters on a fact property with prop and prop_value; the dependency example above lists the packages declared in the repository’s manifests. There is also a delta operation, which needs no fact id: code_query={"operation": "delta"} reports what the last ingestion changed in each repository. Every operation’s full argument list, defaults, and the fact kinds a query can filter on are in the SearchType reference.

Advanced Usage

Make the Facts Available to Semantic Retrievers

get_code_graph_tasks(repo_path, index_vectors=True) also writes the extracted facts to the vector store, so semantic and LLM-backed retrievers can reach them. It is opt-in because SearchType.CODE reads the graph only; enabling it adds embedding calls and therefore needs an embedding provider configured.

Query Across Repositories

Graph paths only exist inside a single dataset. To follow paths across repositories, generate one Enola append/multi-repository snapshot covering all of them and ingest that into one dataset. Repositories indexed into separate datasets are searched independently, and no path can connect them.

Index a Public Repository by URL

A GitHub/GitLab repository URL passed to plain add() or remember() — with no content_type — is recognised as a repository by its shape, shallow-cloned, and ingested as one code-repo item that takes the same code graph route, plus the repository’s own documents:

await cognee.add("https://github.com/owner/repo", dataset_name="my_repo")
await cognee.cognify(datasets=["my_repo"])

# Or in one call
await cognee.remember("https://github.com/owner/repo", dataset_name="my_repo")

Use remember(url, content_type="code") instead when you want only the code graph (no repository documents), several repositories in one call, or repo_credentials for a private remote. Clones land under COGNEE_REPOS_DIR (default ~/.cognee/repos) either way, and both paths need git on PATH and ALLOW_HTTP_REQUESTS enabled. Deeper forge URLs (/blob/, /tree/, /issues, GitLab’s /-/ pages) are still treated as web pages; see add() for the exact detection rules.

Index a Private Repository

remember(url, content_type="code", repo_credentials="<token>") clones a private https remote using an out-of-band token — a GitHub App installation token, for example. It is sent as HTTP basic auth under the x-access-token username, the scheme GitHub expects. The token reaches git through environment-level config rather than the URL, so nothing derived from the URL can carry it: the clone directory name, the persisted git remote, log lines, and git’s own error output all use the credential-free URL. repo_credentials is code-only — passing it with any other content_type raises ValueError.Credentials embedded in the URL userinfo (https://x-access-token:<token>@github.com/org/repo.git) still work, but are the legacy path. Either way, the source recorded on each result item is redacted, so a token never surfaces in a remember() result.To connect a whole organization instead of one repository at a time, see the GitHub integration.

Query the Code Graph Through recall()

recall() reaches the same deterministic operations without assembling a search() call. The "code" scope is explicit opt-in — neither "auto" nor "all" includes it — and code_query takes the same operation dict this guide uses:

results = await cognee.recall(
    "UserService",
    scope=["code"],
    code_query={"operation": "impact_analysis", "name": "UserService", "max_depth": 3},
)

Omitting code_query runs explore seeded with the query text, and entries come back with source="code", so a scope=["graph", "code"] call keeps the two lanes apart in the results. For the full parameter behavior, see recall().

Provide Your Own enola Binary

ENOLA_PATH always wins over the auto-installed binary, so point it at your own build to control the version. Setting ENOLA_AUTO_INSTALL=false disables the automatic download entirely — the run then fails with an install error instead of fetching the pinned release. For the exact release URL, the pinned version, the cache path, and the supported platform builds, see Where the enola binary comes from.

Pipelines

How tasks are orchestrated into a pipeline.

run_custom_pipeline()

The full parameter surface of the call this guide uses.

Custom Tasks and Pipelines

Write your own tasks and assemble them into a pipeline.

Getting Started

Core Concepts

Setup Configuration

Guides

Examples

CLI

OSS

Before You Start

Code in Action

What Just Happened

Step 1: Choose the Repository and Start Clean

Step 2: Run the Code Graph Pipeline

Step 3: Query the Graph with SearchType.CODE

Step 4: Draw the Architecture and Read the Insights

Step 5: Reuse the Same Shape for Other Operations

Advanced Usage

Pipelines

run_custom_pipeline()

Custom Tasks and Pipelines

​Before You Start

​Code in Action

​What Just Happened

​Step 1: Choose the Repository and Start Clean

​Step 2: Run the Code Graph Pipeline

​Step 3: Query the Graph with SearchType.CODE

​Step 4: Draw the Architecture and Read the Insights

​Step 5: Reuse the Same Shape for Other Operations

​Advanced Usage

Pipelines

run_custom_pipeline()

Custom Tasks and Pipelines

Before You Start

Code in Action

What Just Happened

Step 1: Choose the Repository and Start Clean

Step 2: Run the Code Graph Pipeline

Step 3: Query the Graph with SearchType.CODE

Step 4: Draw the Architecture and Read the Insights

Step 5: Reuse the Same Shape for Other Operations

Advanced Usage