🔍 N3MO

A 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

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

---

🎯 What is N3MO?

N3MO addresses a fundamental challenge in software engineering: understanding large codebases. Unlike simple code search tools that rely on text matching, N3MO models code structure first — capturing symbols, their relationships, and their call chains.

The Problem It Solves

❌ Traditional grep/search:  "Where does 'login' appear?"
✅ N3MO:                     "What will break if I change the login function?"

Critical questions N3MO answers:

• 🔎 What functions and classes exist in this repository?
• 🎯 Where is this symbol being used — directly and transitively?
• 💥 What is the blast radius of changing this function?
• 🕸️ How do these components actually connect?

---

🏗️ Architecture

Knowledge graph model

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

graph TB
    subgraph repo["Repository Analysis"]
        A["📄 Source Code"] -->|Tree-sitter| B["🌳 AST Parser"]
        B --> C["🔍 Symbol Extractor"]
    end

    subgraph kg["Knowledge Graph"]
        D[("🗄️ PostgreSQL")]
        E["📦 Projects"]
        F["🔤 Symbols"]
        G["🔗 Relationships"]
        D --- E
        D --- F
        D --- G
    end

    subgraph query["Query Engine"]
        H["📊 Dependency Graph"]
        I["📞 Call Graph"]
        J["💥 Impact Analysis"]
    end

    C --> D
    D --> H
    D --> I
    D --> J
    H --> K["🎨 Visualization"]
    I --> K
    J --> K

    style repo fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style kg fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style query fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style A fill:#e2e8f0,stroke:#4a5568,color:#1a202c
    style B fill:#cbd5e0,stroke:#4a5568,color:#1a202c
    style C fill:#cbd5e0,stroke:#4a5568,color:#1a202c
    style D fill:#fc8181,stroke:#c53030,color:#1a202c,stroke-width:3px
    style E fill:#a0aec0,stroke:#4a5568,color:#1a202c
    style F fill:#a0aec0,stroke:#4a5568,color:#1a202c
    style G fill:#a0aec0,stroke:#4a5568,color:#1a202c
    style H fill:#90cdf4,stroke:#2c5282,color:#1a202c
    style I fill:#90cdf4,stroke:#2c5282,color:#1a202c
    style J fill:#90cdf4,stroke:#2c5282,color:#1a202c
    style K fill:#9ae6b4,stroke:#2f855a,color:#1a202c

Loading

System flow

sequenceDiagram
    participant User
    participant CLI
    participant Docker
    participant Parser
    participant DB as PostgreSQL
    participant Viz as Visualizer

    User->>CLI: n3mo index
    CLI->>Docker: Start containers
    Docker->>Parser: Mount repository
    Parser->>Parser: Walk file tree
    Parser->>Parser: Parse AST (Tree-sitter)
    Parser->>DB: Store symbols & relations
    DB-->>Parser: Confirm storage

    User->>CLI: n3mo impact "function_name"
    CLI->>DB: Query call graph
    DB->>DB: Recursive CTE traversal
    DB-->>Viz: Return dependency tree
    Viz-->>User: Display graph (HTML/JS)

Loading

Data model

erDiagram
    PROJECT ||--o{ SYMBOL : contains
    SYMBOL ||--o{ SYMBOL : "calls/inherits"
    SYMBOL {
        uuid id PK
        string kind "function|class|variable"
        string name
        string file_path
        int line_number
        uuid parent_id FK
        uuid project_id FK
    }
    PROJECT {
        uuid id PK
        string name
        string root_path
        timestamp indexed_at
    }

Loading

---

✨ Features

Current capabilities (v0.3)

• ✅ AST-based parsing — Tree-sitter integration for error-tolerant Python analysis
• ✅ Symbol extraction — functions, classes, methods with full file + line context
• ✅ Hierarchical modeling — Module → Class → Method parent-child relationships
• ✅ Call graph construction — who calls whom, captured at ingestion time
• ✅ Blast radius analysis — recursive CTE traversal to arbitrary depth
• ✅ Idempotent ingestion — re-indexing updates existing data without duplication
• ✅ Interactive visualizer — vis.js graph with click-to-inspect nodes and sidebar
• ✅ Docker-first — single-command infrastructure setup

In development (v0.4)

• 🚧 Connection pooling — eliminate per-symbol DB round trips
• 🚧 Batch inserts — 1 transaction per file, not per row
• 🚧 Incremental re-index — SHA-256 file hashing, skip unchanged files
• 🚧 Multiprocessing — parallel AST parsing via ProcessPoolExecutor
• 🚧 Scope-aware call resolution — use imports table, eliminate false positives
• 🚧 Test suite — pytest with real Postgres integration tests
• 🚧 GitHub Actions CI — lint, typecheck, test on every PR

---

🚀 Installation

Prerequisites

Quick start

# 1. Clone the repository
git clone https://github.com/RajX-dev/N3MO.git
cd N3MO

# 2. Configure environment
cp .env.example .env

# 3. Start infrastructure
docker-compose up -d

# 4. Install the CLI
pip install -e .

# 5. Verify
n3mo --help

---

💻 Usage

Index a repository

# Navigate to any Python repository
cd /path/to/your/project

# Run the indexer
n3mo index

What gets indexed:

• ✅ Python files (.py)
• ❌ Virtual environments (venv/, .venv/)
• ❌ Dependencies (node_modules/, site-packages/)
• ❌ Build artifacts (.git/, __pycache__/, dist/)

Blast radius analysis

# Find everything affected by changing a function
n3mo impact "authenticate_user"

# Open an interactive visual graph in your browser
n3mo impact "authenticate_user" --graph

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		Error-tolerant syntax analysis
Database		Relational graph storage + recursive CTE queries
Runtime		Core logic
Infrastructure		Containerization
Visualization		Interactive impact graph

---

📊 Benchmarks

Tested on ScanCode Toolkit — a real-world open source Python project with ~600k lines of code.

Metric	v0.3 (current)
Repository	nexB/scancode-toolkit
Lines of code	~600,000
Index time	~3 minutes
Processing mode	Single-threaded
Hardware	Intel i5-13450HX, 24GB RAM, NVMe SSD

✅ Real measured result on a real public repo — clone it and try yourself.

Multiprocessing (v0.4) will produce a proper before/after comparison once implemented. No projections until the code exists.

---

🗺️ Roadmap

Development timeline

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	🔵 Next
	Batch DB operations	🔵 Next
	Incremental re-index (file hashing)	🔵 Next
	Multiprocessing (AST parsing)	🔵 Next
Phase 3 — Correctness
	Scope-aware call resolution	⏳ Planned
	CTE cycle guard	⏳ Planned
	Full type annotations + mypy	⏳ Planned
	pytest suite + CI	⏳ Planned
Phase 4 — Distribution
	MCP server (Cursor / Claude Code)	⏳ Planned
	FastAPI REST layer	⏳ Planned
	JavaScript / TypeScript support	⏳ Planned
	Real-time git-hook indexing	⏳ Planned
	pgvector semantic search	⏳ Planned

Legend: ✅ Complete  |  🔵 In Progress  |  ⏳ Planned

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 🔵 In Progress

• psycopg2.pool.ThreadedConnectionPool — replace per-call connections
• execute_values() batch inserts — 1 transaction per file
• SHA-256 file hashing for incremental re-index
• ProcessPoolExecutor for parallel AST parsing

Phase 3: Correctness + Quality ⏳ Planned

• Scope-aware call resolution using imports table
• CTE cycle guard (visited node tracking)
• Full type annotations, mypy --strict clean
• pytest unit + integration test suite
• GitHub Actions CI pipeline

Phase 4: Distribution ⏳ Planned

• MCP server — N3MO as a tool for Cursor, Claude Code, Windsurf
• FastAPI REST layer — GET /impact/{symbol}, POST /index
• JavaScript / TypeScript support
• Real-time incremental indexing via git hooks
• pgvector semantic search — "find functions that do X"

---

📝 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 follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development setup

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

# Lint
ruff check src/

# Type check
mypy src/

# Tests
pytest tests/

---

📜 License

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

• ✅ Free for personal projects and internal tools
• ✅ Open source — view, modify, and distribute freely
• ⚠️ Copyleft — derivative works must also be AGPL-3.0
• ⚠️ Network use — modified versions run as a web service must share changes

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

See LICENSE for full legal details.

---

👨‍💻 Author

Raj Shekhar — Delhi Technological University

---

🙏 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

---

⭐ Star this repo if you find it useful!

Building tools for understanding code at scale.