Skip to content

Graph Intelligence & Code Architecture Guide

Cortex provides a zero-CGO static code and knowledge graph intelligence engine, natively ported and integrated into the Cortex memory platform.

1. Zero-CGO Static AST Extractor (internal/domain/ast)

The AST extractor analyzes codebase repositories and extracts structured symbols and relationships without sending code to LLMs or consuming external API tokens.

Supported Languages

  • Go (.go): Native parsing via go/parser and go/ast. Extracts modules, packages, structs, interfaces, methods, functions, and direct call invocations.
  • .NET Ecosystem:
  • C# (.cs): Namespaces, using directives, classes, interfaces, structs, records, enums, and methods.
  • F# (.fs, .fsi, .fsx): open imports, modules, types (records/unions/classes), and let functions.
  • VB.NET (.vb): Imports, Namespace, Class, Interface, Structure, Module, Sub, and Function.
  • Java & Kotlin (.java, .kt, .kts): Packages, imports, classes, data classes, interfaces, objects, enums, records, and functions/methods.
  • Rust (.rs): Modules (mod), imports (use), structs, enums, traits, and functions (fn).
  • C / C++ (.c, .cpp, .cc, .cxx, .h, .hpp, .hxx): #include directives, namespaces, classes, structs, and functions.
  • PHP (.php): Namespaces, use statements, classes, interfaces, traits, enums, and functions.
  • Ruby (.rb): require/require_relative, modules, classes, and def methods.
  • Swift (.swift): Modules, imports, classes, structs, protocols, enums, extensions, and functions.
  • TypeScript / JavaScript (.ts, .tsx, .js, .jsx, .mjs, .cjs): ES modules, import declarations, exported classes, functions, and arrow functions.
  • Python (.py, .pyw): Modules, package imports (from X import Y), classes, methods, and functions.
  • SQL (.sql): Database table definitions (CREATE TABLE).

Structural Relationships

  • defines: File/module declares a struct, class, or function.
  • imports: File imports an external package or module.
  • calls: Function/method invokes another symbol.
  • implements: Method implements an interface or belongs to a receiver struct.
  • uses: Symbol references a type or model.

2. Graph Analytics & Algorithms (internal/domain/graph)

Community Detection (Louvain / Hub Partitioning)

  • Partitions the project graph into tightly-coupled subsystems.
  • Automatically assigns community names using the Hub Node (the symbol with highest degree in the cluster).
  • Computes internal cohesion scores for each community.

God Nodes (Architectural Bottlenecks)

  • Identifies critical hubs with disproportionate connectivity (in_degree + out_degree).
  • Automatically filters utility noise types (string, error, context.Context, etc.).

Surprising Connections

  • Scores and flags anomalous cross-module edges, peripheral-to-hub couplings, and critical semantic edges (contradicts, supersedes).

Dependency Cycles (Tarjan SCC)

  • Detects circular dependencies and import loops across modules.

Blast Radius Calculation

  • Calculates upstream and downstream impact when modifying a symbol or file.
  • Outputs the list of impacted files, direct dependent callers, and percentage of the project graph affected.

3. CLI Code Intelligence (cortex code)

The cortex code command exposes the same AST and graph engine from the terminal (see CLI-REFERENCE.md for the authoritative command contract). cortex code, cortex code help, cortex code --help, and cortex code -h print the subcommand list and exit 0; every subcommand defaults --project to default.

Subcommand Synopsis Purpose
scan cortex code scan [path] [--project=NAME] [--max-files=N] Scan a repository and index AST symbols (delegates to cortex ingest; --max-files default 500).
symbols cortex code symbols [--project=NAME] [--kind=KIND] [--file=PATH] List up to 100 indexed symbols, optionally filtered by kind or file.
analyze cortex code analyze [--project=NAME] Run Graphify analytics: totals, average cohesion, god nodes, and import cycles.
impact cortex code impact <target> [--project=NAME] [--hops=N] [--json] Blast radius for a symbol or file (--hops default 3; alias blast-radius).
diff cortex code diff [--staged] [--project=NAME] [--hops=N] [--json] Blast radius of uncommitted Git changes (--staged/--cached; --hops default 3).
graph cortex code graph [--project=NAME] [--format=mermaid] [--symbol=S] [--hops=N] [--max-nodes=N] Export or visualize the dependency graph (--format mermaid, ascii/tree, json; --hops default 2, --max-nodes default 50).
map cortex code map [--project=NAME] [--budget=N] Generate a compact token-budgeted Repo-Map for LLMs (--budget default 2048; alias repo-map).
tests cortex code tests <target> [--project=NAME] [--hops=N] [--json] Find impacted test files and functions for Fast-TDD (--hops default 3; aliases test-map, impacted-tests).
find cortex code find <query> [--project=NAME] [--kind=K] [--file=PATH] [--limit=N] [--regex] [--json] Search symbols by substring or regex (--limit default 50; alias search-symbols). 
cortex code scan . --project cortex
cortex code impact CalculateBlastRadius --project cortex --hops=2
cortex code diff --staged --json
cortex code tests CalculateBlastRadius

4. Server Endpoints & MCP Tools

REST Endpoints

  • GET /api/graph/project-graph?project=<name>: Loads the complete code and knowledge graph for a project.
  • GET /api/graph/analytics?project=<name>: Generates architectural health diagnostics (God nodes, communities, cycles).
  • GET /api/graph/blast-radius?node_id=<id>&depth=<n>: Computes blast radius for any node.
  • POST /api/graph/ingest-code: Extracts AST symbols from a local directory and persists them to PostgreSQL.
  • POST /api/graph/resolve: Resolves knowledge contradictions with supersedes edges.

MCP Tools

  • cortex_ingest_code: Extracts and indexes symbols and relationships via 2-Pass Static AST parsing into dedicated tables.
  • cortex_get_code_symbols: Queries indexed symbols (functions, structs, interfaces, classes) with filters and regex search.
  • cortex_code_map: Generates a token-budgeted PageRank structural repository map.
  • cortex_code_tests: Pinpoints impacted test suites using reverse call graphs (essential for Fast-TDD).
  • cortex_get_blast_radius: Inquires affected symbols and files when planning code changes (supports include_tests: true).
  • cortex_analyze_architecture: Analyzes subsystem communities (Louvain), god nodes, and architectural hubs.
  • cortex_detect_cycles: Detects circular dependencies and import loops (Tarjan SCC).
  • cortex_relate: Establishes typed relationships between observations and entities.
  • cortex_graph / cortex_graph_path: Traverses neighborhoods and calculates shortest paths in the knowledge graph.
  • cortex_graph_subgraph: Traverses bounded heterogeneous subgraphs (observations, entities, actors, sessions).

5. Web UI Features (web/src/app/graph/page.tsx)

  • Project Switcher: Select any project (cortex, kardex, default, or all) to load its complete graph.
  • AST Code Scanner Modal: Scan local directories (., D:\my-project) to instantly map symbols into PostgreSQL.
  • Louvain Communities View: Distinct color-coded functional clusters.
  • Interactive Blast Radius View: Highlights impacted nodes in red/amber and dims unaffected elements.
  • Architectural Health Drawer: Real-time metrics for God nodes, surprising connections, and cycles.
  • Obsidian Vault Exporter: One-click download of project Markdown notes with [[WikiLinks]].