Skip to content

RajX-dev/N3MO

BranchesTags

Repository files navigation

N3MO In Action

N3MO Banner PyPI version License: PolyForm Noncommercial 1.0.0 Python Docker Status Discord MCP Registry CI

A structural code intelligence layer that transforms source code into a queryable knowledge graph for search, impact analysis, and AI-powered development.

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

📜 Licensed under PolyForm Noncommercial 1.0.0 — Source available for noncommercial use. • Need commercial use? Get a commercial license →

What is N3MO • Benchmarks • Architecture • Installation • MCP • Usage • Roadmap

🎯 What is N3MO?

N3MO is a symbol-centric code intelligence layer. Instead of scanning raw text, it parses your source code's ASTs, maps call graphs, and models dependencies in a queryable relational database — deterministically, with zero LLM calls at index time.

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 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 agents query the actual code graph, enabling fast, hallucination-free refactoring.
  • ⚡ No Embeddings, No Drift — N3MO is pure static analysis: Tree-sitter AST parsing into PostgreSQL. There's no vector index to keep in sync, no embedding cost per repo, and no semantic-similarity guesswork — every edge in the graph is an exact, verifiable relationship.

📊 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 Tree-sitter grammars
Indexing Method N/A N/A ✅ Deterministic AST parse — no embeddings, no LLM calls

🛠️ The Core Problem N3MO Solves

❌ Without N3MO

Developer: "Where does 'login' appear?"
Tool:      grep -r "login" .
Result:    647 matches across 89 files
           ...now what?

✅ With N3MO

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

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

📊 Benchmarks

All benchmarks measured on Intel i5-13450HX, 24 GB RAM, NVMe SSD.

Django — Optimization History

Django is the primary benchmark target: 3,021 files, ~43K symbols, ~181K calls.

Django Index Time (minutes)
═══════════════════════════════════════════════════════════════

v0.3 Baseline       ██████████████████████████████████████████████  23 min   1×
SPLIT_PART Fix      ██████████████████████                          11 min   2×
Batch Inserts       █████████                                        5 min   4.6×
+ Multiprocessing   ████                                           2.5 min   9× 🚀

═══════════════════════════════════════════════════════════════
Optimization Index Time Speedup What Changed
v0.3 baseline 23 min 1× Per-symbol DB inserts, naive call resolution
+ SPLIT_PART query fix 11 min 2× Eliminated redundant string splitting in call resolution
+ Batch inserts 5 min 4.6× Symbols, imports, and calls batched per file (1 transaction)
+ Multiprocessing ~2.5 min ~9× ProcessPoolExecutor distributes AST parsing across cores

✅ All results are real measurements on the Django repository. Multiprocessing gains scale with core count.

TensorFlow — Enterprise-Scale Monorepo

Tested on TensorFlow — a 36,000-file, multi-language (C++/Python) monorepo.

Metric Result
Repo size (total files) ~36,000
Files processed & indexed 14,611 (after filtering tests, configs, and non-source files)
Total symbols extracted 79,523
Total call edges extracted 480,851
Full index time (cold start) 14.06 minutes
Peak memory (Docker container) 185 MB RAM
CPU utilization ~5%

N3MO scales from a 3K-file pure-Python repo (Django) to a 36K-file multi-language enterprise monorepo (TensorFlow) — roughly a 5× larger indexing job at near-linear throughput, without significant resource overhead. Symbol/edge-per-file and incremental (warm) re-index numbers for TensorFlow are being finalized in the full benchmark report.

ScanCode Toolkit — Large Codebase

Tested on ScanCode Toolkit — ~600K lines of Python.

Metric Result
Lines of code ~600,000
Full index time ~3 minutes
Processing mode Single-threaded (v0.3)

Incremental Re-Indexing

N3MO uses SHA-256 file hashing to skip unchanged files on subsequent runs.

Scenario Time Notes
Full index (first run) Baseline All files parsed and inserted
No changes (re-run) < 1 second Hash comparison only, zero DB writes
1 file modified < 2 seconds Only the changed file is re-parsed and upserted

These results are from the built-in benchmark script on a 20-file synthetic repository. Real-world incremental performance is proportional to the number of changed files, not the total repository size.

Query Performance

Impact analysis uses PostgreSQL recursive CTEs with cycle guards. Query times are independent of repository size — they depend only on the size of the result subgraph.

Query Type Typical Latency
Direct callers of a symbol < 10 ms
Full blast radius (depth ≤ 5) < 50 ms
Complete graph traversal < 200 ms

Running the Benchmark

python benchmarks/benchmark_indexing.py

🏗️ Architecture

Knowledge graph model

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

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

    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
Loading

System flow

sequenceDiagram
    participant User as User / CI
    participant CLI as N3MO CLI
    participant DB as PostgreSQL (Docker)
    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
Loading

Data model

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
    }
Loading

✨ Core Capabilities

Ingestion & Parsing

  • Multi-language support — 27 Tree-sitter grammars supported (dynamically loaded); actively benchmarked on 10 major languages including Python, JS/TS, Go, Java, and C/C++
  • 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 positives (e.g. allows contest.py while skipping test_*.py)

Analysis & Querying

  • Symbol extraction — functions, classes, methods with full file path + line context
  • Hierarchical modeling — parent-child relationships (Module → Class → Method)
  • Call graph construction — who calls whom, resolved at ingestion time
  • Scope-aware resolution — class scope > local file > imports > qualified dot paths > global
  • Blast radius analysis — recursive CTE traversal to arbitrary depth with cycle guards

Performance

  • Connection pooling — ThreadedConnectionPool eliminates per-symbol DB round trips
  • Batch inserts — symbols, imports, and calls batched per file in single transactions
  • Optimized queries — SPLIT_PART fix delivered a 2× speedup on call resolution

Visualization & Integration

  • Interactive graph — vis.js orbit map with click-to-inspect nodes, sidebar, and depth slider
  • Dark mode — toggleable canvas dark mode with real-time node/edge updates, persisted in localStorage
  • Premium styling — sleek interactive dashboard landing page UI and graph visualizer styled with Bricolage Grotesque, Inter, and JetBrains Mono typography
  • SKILL.md profile — system instructions to configure Claude as an impact-aware coding agent
  • Native MCP server — first-class integration with Cursor, Claude Desktop, and Windsurf
  • Git hooks — automatic re-indexing on every commit
  • CI pipeline — GitHub Actions with linting (ruff), type checking (mypy), and pytest

🌐 Supported Languages
Python JavaScript TypeScript Go
Rust Java C C++
C# Kotlin Swift Scala
Ruby PHP Haskell Perl
Lua R Elixir Dart
Groovy PowerShell MATLAB Delphi
Bash Zig OCaml …and more

Tree-sitter parsing supported for 27 languages. Deep semantic call graph mapping currently optimized for Python, JS/TS, and Java.

🚀 Installation

Prerequisites

Docker Python Git

Quick start

Install N3MO directly from PyPI:

# Install the package
pip install n3mo

# Start Docker containers & initialize the database
n3mo setup

Alternatively, for contributors running in editable mode:

git clone https://github.com/RajX-dev/N3MO.git
cd N3MO
pip install -e .
n3mo setup

🤖 Model Context Protocol (MCP)

N3MO includes a native MCP server that exposes repository analysis and graph traversal tools to LLM agents (like Claude, Cursor, or Windsurf).

Automatic Claude Desktop Setup

# Navigate to the workspace you want Claude to analyze, then run:
n3mo mcp install

This registers N3MO and sets up the paths automatically. Restart Claude Desktop and you're ready!

🧠 Claude Skill (System Instructions)

To configure Claude to run N3MO impact queries proactively before changing code in the editor, import or copy-paste the custom instructions from the SKILL.md profile.

Cursor Setup

  1. Go to Settings → Models → MCP.
  2. Click + Add New MCP Server.
  3. Set the configuration details:
    • Name: n3mo
    • Type: command
    • Command: n3mo mcp start (or uvx n3mo mcp start to run directly)
    • Environment Variables: TARGET_CODE_DIR=/absolute/path/to/your/active/workspace
  4. Click Save, and Cursor will instantly be able to index and query your workspace blast radius.

🧰 Available MCP Tools

Tool Description
n3mo_index Ingests and indexes the codebase
n3mo_search_symbol Locates the definition of a symbol across the workspace (file path, line number)
n3mo_get_dependencies Finds all external symbols that a given symbol calls (forward-dependency graph)
n3mo_get_file_symbols Lists all classes and functions defined inside a specific file
n3mo_get_blast_radius Traces the transitive impact/call graph of a code symbol

⚓ GitHub Webhook Integration

For team collaboration and automated pull-request analysis in your CI/CD pipeline, visit n3mo.shop to get started with the GitHub Webhook integration.

💰 Pricing & Licensing

N3MO is free under the PolyForm Noncommercial 1.0.0 License for local usage and single-developer MCP integrations.

  • 100% Free & Local — CLI queries, local MCP integrations, and the visualizer with zero limits.
  • Enterprise Licensing — for large-scale organization deployments or commercial licensing terms, reach out to the author.

💻 Usage

Index a repository

cd /path/to/your/project
n3mo index

What gets indexed:

  • ✅ Source files in all 27 supported languages
  • ❌ Virtual environments (venv/, .venv/)
  • ❌ Dependencies (node_modules/, site-packages/)
  • ❌ Build artifacts (.git/, __pycache__/, dist/)
  • ❌ Test / fixture directories (tests/, mocks/, specs/)

Visualizer

Dark Mode — Radial Layout

Dark Mode Radial Layout

Horizontal Tree View

Horizontal Tree View

Example terminal output:

  ◈ IMPACT ANALYSIS
  ──────────────────────────────────────────────────────────────────
  Target:  authenticate_user
  ──────────────────────────────────────────────────────────────────

  ◉ Direct Callers  (3 symbols)

  ▸ login_endpoint             api/auth.py:12
  ▸ refresh_token              api/token.py:23
  ▸ validate_session           middleware/auth.py:89

  ◎ Ripple Effects  (5 symbols)

    ╰─▸ POST /login              routes.py:67
    ╰─▸ admin_login              admin/views.py:34
    ╰─▸ require_auth             decorators.py:12
    ╰─▸ dashboard_view           views/dashboard.py:8
    ╰─▸ settings_view            views/settings.py:22

  ──────────────────────────────────────────────────────────────────
  Total impacted: 8 references  │  depth ≤ 3

Dependency graph visualization

graph LR
    A[main.py] --> B[auth.py::login]
    A --> C[db.py::connect]
    B --> D[utils.py::hash_password]
    B --> E[models.py::User]
    C --> F[config.py::DB_URI]

    style A fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
    style B fill:#4ecdc4,stroke:#0ca89e,stroke-width:2px,color:#000
    style C fill:#45b7d1,stroke:#1098ad,stroke-width:2px,color:#000
    style D fill:#96ceb4,stroke:#63b598,stroke-width:2px,color:#000
    style E fill:#ffd93d,stroke:#f5c200,stroke-width:2px,color:#000
    style F fill:#e0e0e0,stroke:#a0a0a0,stroke-width:2px,color:#000
Loading

🛠️ Technology Stack

Component Technology Purpose
Parser Tree-sitter Error-tolerant syntax analysis across 27 languages
Database PostgreSQL Relational graph storage + recursive CTE queries
Runtime Python Core logic + multiprocessing
Infrastructure Docker Containerization
Visualization JavaScript Interactive impact graph
AI Integration MCP Native tool for LLM agents

🗺️ Roadmap

All four development phases have been completed. N3MO is stable and actively maintained.

Phase Component Status
Phase 1 — Foundations
Docker setup ✅ Complete
Database schema ✅ Complete
Tree-sitter integration ✅ Complete
Symbol + call extraction ✅ Complete
Blast radius (recursive CTE) ✅ Complete
Interactive visualizer ✅ Complete
Phase 2 — Performance
Connection pooling ✅ Complete
Batch DB operations (symbols/imports/calls) ✅ Complete
SPLIT_PART query optimization ✅ Complete
--file / --depth CLI flags ✅ Complete
Interactive depth slider ✅ Complete
Phase 3 — Correctness & Scaling
Incremental re-index (file hashing) ✅ Complete
Multiprocessing (AST parsing) ✅ Complete
Scope-aware call resolution ✅ Complete
CTE cycle guard ✅ Complete
Full type annotations + mypy ✅ Complete
pytest suite + CI ✅ Complete
Multi-language support (27 languages) ✅ Complete
Phase 4 — Distribution
MCP server (Cursor / Claude / Windsurf) ✅ Complete
Real-time git-hook indexing ✅ Complete
Phase 1: Foundations ✅ Complete
  • Docker environment (PostgreSQL)
  • Database schema — Projects, Symbols, Calls, Imports tables
  • Tree-sitter parser integration
  • Symbol extractor with full AST traversal
  • Idempotent upsert logic
  • Blast radius via recursive CTE
  • Interactive vis.js visualizer
Phase 2: Performance ✅ Complete
  • psycopg2.pool.ThreadedConnectionPool — replace per-call connections
  • execute_values() batch inserts for symbols, imports, and calls — 1 transaction per file
  • SPLIT_PART query optimization for call resolution
  • --file and --depth CLI flags for targeted impact analysis
  • Interactive depth slider in visualizer

Results: Django (3,021 files, ~43K symbols, ~181K calls) — 23min → 2.5min (9× faster)

Phase 3: Correctness + Scaling ✅ Complete
  • SHA-256 file hashing for incremental re-index
  • ProcessPoolExecutor for parallel AST parsing
  • Scope-aware call resolution using imports table
  • CTE cycle guard (visited node tracking)
  • Full type annotations, mypy clean checking in CI
  • pytest unit + integration test suite
  • GitHub Actions CI pipeline
  • Multi-language support (27 languages)
Phase 4: Distribution ✅ Complete
  • MCP server — N3MO as a tool for Cursor, Claude Code, Windsurf
  • Real-time incremental indexing via git hooks

📝 Design Principles

1. Structure before semantics Map the code skeleton (AST) before adding AI analysis. A correct graph is worth more than a smart but wrong one.

2. Database as source of truth All state lives in PostgreSQL, eliminating in-memory complexity and enabling graph queries that application-level traversal cannot match.

3. Correctness over speed The parser must handle syntax errors gracefully without corrupting the graph. A fast indexer that silently drops symbols is worse than a slow one that gets everything right.

4. Idempotent operations Re-running ingestion produces identical results, enabling safe incremental updates and CI/CD integration.

🤝 Contributing

Contributions are welcome! Please read the CONTRIBUTING.md guide to get started with setting up the project, coding standards, and running checks locally.

Development Setup

# Install with dev dependencies
pip install -e ".[dev]"

# Lint
ruff check n3mo/

# Type check
mypy n3mo/

# Tests
pytest tests/

📜 License

Licensed under the PolyForm Noncommercial 1.0.0 License.

  • ✅ Free for personal projects, academic research, and hobby tools
  • ✅ Source available — view, modify, and distribute for noncommercial purposes
  • ⚠️ Noncommercial — you may not use it for commercial purposes
  • ⚠️ Restrictions apply on offering it as a service

For commercial deployments or proprietary modifications, contact for licensing options.

See LICENSE for full legal details.

👨💻 Author

Raj Shekhar — Delhi Technological University

GitHub LinkedIn

🙏 Acknowledgments

  • Tree-sitter — for robust, incremental, error-tolerant parsing
  • PostgreSQL — for making recursive graph queries possible without a graph database
  • Docker — for reproducible, single-command environments
  • vis.js — for the interactive graph visualization
  • FastAPI — for the high-performance REST layer

⭐ Star this repo if you find it useful — thanks for visiting!

Building tools for understanding code at scale.

Visitors Alt



███╗   ██╗    ██████╗   ███╗   ███╗    ██████╗ 
████╗  ██║   ╚════██╗   ████╗ ████║   ██╔═══██╗
██╔██╗ ██║    █████╔╝   ██╔████╔██║   ██║   ██║
██║╚██╗██║    ╚═══██╗   ██║╚██╔╝██║   ██║   ██║
██║ ╚████║   ██████╔╝   ██║ ╚═╝ ██║   ╚██████╔╝
╚═╝  ╚═══╝    ╚═════╝   ╚═╝     ╚═╝    ╚═════╝ 
C O D E   I N T E L L I G E N C E   L A Y E R

About

A high-performance code intelligence engine that transforms repositories into queryable symbol-centric knowledge graphs. Features deep impact analysis (blast radius detection) with a professional interactive UI and VS Code deep-linking

n3mo.shop

Resources

Readme

License

View license

Contributing

Contributing
Activity

Stars

12 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases 2

v2.0.1: MCP Registry Support & License Alignment Latest
Jul 5, 2026
+ 1 release

Packages

 
 
 

Contributors

Languages