N3MO

<!-- mcp-name: io.github.RajX-dev/n3mo -->
<div align="center">

<img src="docs/n3mo_intro.gif" alt="N3MO In Action" width="750">

<br>

![N3MO Banner](https://img.shields.io/badge/N3MO-Code%20Intelligence%20Engine-blue?style=for-the-badge)
[![PyPI version](https://img.shields.io/pypi/v/n3mo?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/n3mo/)
[![License: AGPL v3.0](https://img.shields.io/badge/license-AGPL%20v3.0-green?style=for-the-badge)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10+-blue?style=for-the-badge&logo=python)](https://www.python.org)
[![Docker](https://img.shields.io/badge/docker-required-2496ED?style=for-the-badge&logo=docker)](https://www.docker.com)
[![Status](https://img.shields.io/badge/status-stable-brightgreen?style=for-the-badge)]()
[![MCP Registry](https://img.shields.io/badge/MCP-Registry-purple?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik05Ljc5NSAxLjY5NGE0LjI4NyA0LjI4NyAwIDAgMSA2LjA2MSAwIDQuMjggNC4yOCAwIDAgMSAxLjE4MSAzLjgxOSA0LjI4MiA0LjI4MiAwIDAgMSAzLjgxOSAxLjE4MSA0LjI4NyA0LjI4NyAwIDAgMSAwIDYuMDYxbC02Ljc5MyA2Ljc5M2EuMjQ5LjI0OSAwIDAgMCAwIC4zNTNsMi42MTcgMi42MThhLjc1Ljc1IDAgMSAxLTEuMDYxIDEuMDYxbC0yLjYxNy0yLjYxOGExLjc1IDEuNzUgMCAwIDEgMC0yLjQ3NWw2Ljc5My02Ljc5M2EyLjc4NSAyLjc4NSAwIDEgMC0zLjkzOS0zLjkzOWwtNS45IDUuOWEuNzM0LjczNCAwIDAgMS0uMjQ5LjE2NS43NDkuNzQ5IDAgMCAxLS44MTItMS4yMjVsNS45LTUuOTAxYTIuNzg1IDIuNzg1IDAgMSAwLTMuOTM5LTMuOTM5TDIuOTMxIDEwLjY4QS43NS43NSAwIDEgMSAxLjg3IDkuNjE5bDcuOTI1LTcuOTI1WiIvPjxwYXRoIGQ9Ik0xMi40MiA0LjA2OWEuNzUyLjc1MiAwIDAgMSAxLjA2MSAwIC43NTIuNzUyIDAgMCAxIDAgMS4wNjFMNy4zMyAxMS4yOGEyLjc4OCAyLjc4OCAwIDAgMCAwIDMuOTQgMi43ODggMi43ODggMCAwIDAgMy45NCAwbDYuMTUtNi4xNTFhLjc1Mi43NTIgMCAwIDEgMS4wNjEgMCAuNzUyLjc1MiAwIDAgMSAwIDEuMDYxbC02LjE1MSA2LjE1YTQuMjg1IDQuMjg1IDAgMSAxLTYuMDYtNi4wNmw2LjE1LTYuMTUxWiIvPjwvc3ZnPg==)](https://registry.modelcontextprotocol.io/?q=n3mo)
[![CI](https://img.shields.io/github/actions/workflow/status/RajX-dev/N3MO/ci.yml?branch=main&style=for-the-badge&logo=github&label=CI)](https://github.com/RajX-dev/N3MO/actions)

**A structural code intelligence engine that transforms repositories into queryable knowledge graphs.**

*Parse once. Query forever. Know exactly what breaks before it does.*

**📜 Licensed under AGPL-3.0** — Free for personal/internal use • [Contact for commercial licensing](#-license)

[What is N3MO](#-what-is-n3mo) • [Architecture](#-architecture) • [Installation](#-installation) • [GitHub App & Pricing](#-github-app-and-commercial-tiers) • [Usage](#-usage) • [Benchmarks](#-benchmarks) • [Roadmap](#-roadmap)

</div>

---

## 🎯 What is N3MO?

N3MO is a symbol-centric code intelligence engine. Instead of scanning raw text, it parses your source code's ASTs, maps call graphs, and models dependencies in a queryable relational database.

For engineering leaders and teams, N3MO acts as a **structural insurance policy** for your codebases.

### 💡 Why N3MO?

*   **🛡️ Eliminate Regression Risks:** Utility functions are rarely refactored because developers fear unknown side effects. N3MO maps the transitive blast radius of any symbol to arbitrary depth, showing you exactly what will break before you make the edit.
*   **🏎️ Rapid Developer Onboarding:** Instead of senior engineers spending hours explaining codebase flow to new hires, developers can run one command to visualize complex call chains and parent-child dependencies interactively.
*   **🤖 AI-Agent Ready Infrastructure:** Modern LLM agents (Cursor, Claude Desktop) are limited by context windows and text search. N3MO's native MCP server lets AI agents query the actual code graph, enabling fast, hallucination-free refactoring.

### 📊 How N3MO Compares

| Capability | Grep / Text Search | IDE "Find References" | N3MO Code Graph |
| :--- | :--- | :--- | :--- |
| **Analysis Basis** | Substring matching | AST-based, direct refs only | Relational knowledge graph |
| **Transitive Traversal** | ❌ None | ❌ Manual, one level at a time | ⚡ **Instant to arbitrary depth** |
| **Blast Radius Mapping** | ❌ None | ❌ Flat search-result list | 🎨 **Interactive visual orbit map** |
| **CI/CD Integration** | ❌ None | ❌ Bound to IDE runtime | ⚙️ **Dockerized CLI + CTE queries** |
| **AI Agent Integration** | ❌ Injected file chunks | ⚠️ Manual context copy | 🤖 **Native MCP server** |
| **Language Coverage** | ✅ Any text file | ⚠️ Language-specific plugins | ✅ **27 languages via Tree-sitter** |

### 🛠️ The Core Problem N3MO Solves

<table>
<tr>
<td width="50%">

**❌ Without N3MO**
<pre>
Developer: "Where does 'login' appear?"
Tool:      grep -r "login" .
Result:    647 matches across 89 files
           ...now what?
</pre>

</td>
<td width="50%">

**✅ With N3MO**
<pre>
Developer: "What breaks if I change login?"
Tool:      n3mo impact "login"
Result:    3 direct callers → 5 ripple effects
           Full blast radius in < 50ms
</pre>

</td>
</tr>
</table>

> **N3MO doesn't find text — it understands structure.** It traces the actual call graph, not string matches.

**Questions N3MO answers instantly:**

| | Question | How |
|:---:|:---|:---|
| 🔎 | What functions and classes exist in this repo? | Full symbol index across 27 languages |
| 🎯 | Where is this symbol used — directly *and* transitively? | Recursive CTE traversal to arbitrary depth |
| 💥 | What is the **blast radius** of changing this function? | Interactive orbit map with depth slider |
| 🕸️ | How do these components actually connect? | Call graph + parent-child hierarchy |
| 🤖 | Can my AI agent understand this codebase structurally? | Native MCP server for Cursor / Claude |

---

## 🏗️ Architecture

### Knowledge graph model

N3MO builds a **symbol-centric knowledge graph** stored in PostgreSQL:

```mermaid
graph TD
    A["📄 Source Code"] -->|Tree-sitter| B["🌳 AST Parser"]
    B --> C["🔍 Symbol Extractor"]
    D["🔄 Git Hooks"] -->|post-commit| A

    C --> E[("🗄️ PostgreSQL<br/>Projects · Symbols · Calls<br/>Imports · Files")]

    E --> F["💥 Impact Analysis"]
    E --> G["📞 Call Graph"]
    E --> H["📊 Dependency Graph"]

    F --> I["🎨 Visualizer"]
    G --> I
    H --> I

    F --> J["🤖 MCP Server"]
    F --> K["⚓ GitHub Webhook"]

    style A fill:#6c63ff,stroke:#4a3fbf,color:#fff
    style B fill:#7c74ff,stroke:#4a3fbf,color:#fff
    style C fill:#7c74ff,stroke:#4a3fbf,color:#fff
    style D fill:#ffd93d,stroke:#d4b800,color:#1a202c
    style E fill:#ff6b6b,stroke:#c53030,color:#fff,stroke-width:3px
    style F fill:#45b7d1,stroke:#2c8ea8,color:#1a202c
    style G fill:#45b7d1,stroke:#2c8ea8,color:#1a202c
    style H fill:#45b7d1,stroke:#2c8ea8,color:#1a202c
    style I fill:#9ae6b4,stroke:#2f855a,color:#1a202c
    style J fill:#ffd93d,stroke:#d4b800,color:#1a202c
    style K fill:#ffd93d,stroke:#d4b800,color:#1a202c
```

### System flow

```mermaid
sequenceDiagram
    participant User as User / CI
    participant CLI as N3MO CLI
    participant DB as PostgreSQL (Docker)
    participant API as GitHub Webhook API
    participant Viz as Graph Visualizer

    rect rgb(26, 27, 46)
    Note over User, DB: Indexing Flow (Local CLI)
    User->>CLI: n3mo index
    CLI->>DB: Start PostgreSQL container (if not running)
    CLI->>CLI: Walk file tree (SHA-256 hash checks)
    CLI->>CLI: Parse AST (Tree-sitter, multiprocessing)
    CLI->>DB: Batch insert symbols, calls, imports
    CLI->>DB: Resolve imports & call links
    DB-->>CLI: Success
    CLI-->>User: Complete summary
    end

    rect rgb(26, 27, 46)
    Note over User, Viz: Query & Visualization Flow
    User->>CLI: n3mo impact "symbol" --graph
    CLI->>DB: Recursive CTE traversal (depth & file filters)
    DB-->>CLI: Blast radius subgraph
    CLI->>Viz: Generate orbital vis.js HTML
    CLI->>User: Launch local web server & open browser
    end

    rect rgb(26, 27, 46)
    Note over API, DB: Webhook / PR Flow
    API->>API: Receive GitHub webhook on PR open/update
    API->>API: Clone/checkout head & base commit
    API->>API: Check LOC limit vs Subscription tier
    API->>DB: Index changes (multiprocessing AST parsing)
    API->>DB: Resolve call graph impacts
    API-->>User: Post markdown report comment on PR
    end
```

### Data model

```mermaid
erDiagram
    PROJECT ||--o{ SYMBOL : contains
    PROJECT ||--o{ CALL : tracks
    PROJECT ||--o{ IMPORT : tracks
    PROJECT ||--o{ FILE : indexes
    SYMBOL ||--o{ CALL : "source of"
    SYMBOL ||--o{ CALL : "resolved to"
    SYMBOL ||--o{ SYMBOL : "parent of"

    PROJECT {
        uuid id PK
        text name
        text repo_url
        timestamp created_at
    }
    SYMBOL {
        uuid id PK
        uuid project_id FK
        text name
        text file_path
        text kind "function|class|method"
        text signature
        int start_line
        int end_line
        uuid parent_id FK
    }
    CALL {
        uuid id PK
        uuid project_id FK
        uuid source_symbol_id FK
        text call_name
        int line_number
        uuid resolved_symbol_id FK
    }
    IMPORT {
        uuid id PK
        uuid project_id FK
        text file_path
        text module
        text name
        text alias
        uuid resolved_symbol_id FK
    }
    FILE {
        uuid project_id FK
        text file_path PK
        text sha256
    }
```

---

## ✨ Core Capabilities

### Ingestion & Parsing

- **Multi-language support** — 27 languages via dynamic Tree-sitter grammar loading (Python, JS/TS, Go, Rust, Java, C/C++, C#, Kotlin, Swift, Scala, Ruby, PHP, Haskell, Perl, and more)
- **Parallel AST ingestion** — `ProcessPoolExecutor` distributes CPU-bound parsing across all available cores
- **Incremental re-indexing** — SHA-256 file hashing skips unchanged files automatically
- **Idempotent operations** — re-indexing updates existing data without duplication
- **Smart exclusions** — case-insensitive directory filters and camelCase-aware filename checks prevent false positi