NEURODEX

Complete project memory for AI code assistants. One call, full context, zero guessing.

NEURODEX gives LLMs persistent, symbol-level knowledge of your entire codebase across sessions. No extra AI models, no cloud, no API keys. Built on SQLite FTS5 and tree-sitter.

pip install neurodex
neurodex init                 # index your project
neurodex install              # wire into Claude Code / Codex

What It Does

Your AI assistant starts every session knowing nothing. NEURODEX fixes that.

Without NEURODEX                          With NEURODEX
─────────────────────                   ─────────────────────
Session starts → blank                  Session starts → neurodex_brain()
"What is this project?" → read 10+     → 14k tokens: every module,
  files, still incomplete                 every function signature,
"Fix the auth bug" → grep, read 5        every dependency, every
  more files, guess at structure          past decision
Total: 20+ file reads                  Total: 0 file reads to start

Architecture

graph TB
    subgraph "Index Time (pure algorithmic, no AI)"
        TS[tree-sitter AST] --> CH[Chunker]
        CH --> FTS[SQLite FTS5]
        CH --> NODES[Symbol Nodes]
        CH --> EDGES[Typed Edges]
    end

    subgraph "Query Time"
        BRAIN[Brain Generator] --> |reads| FTS
        BRAIN --> |reads| NODES
        BRAIN --> |reads| EDGES
        SEARCH[BM25 Search] --> |queries| FTS
        IMPACT[Impact Analysis] --> |traverses| EDGES
        REFS[Reference Finder] --> |scans| FTS
        REFS --> |scans| EDGES
        XPROJ[Cross-Project] --> |bridges| EDGES
    end

    subgraph "MCP Server"
        LLM[Claude / Codex] --> |neurodex_brain| BRAIN
        LLM --> |neurodex_search| SEARCH
        LLM --> |neurodex_impact| IMPACT
        LLM --> |neurodex_references| REFS
        LLM --> |neurodex_cross_impact| XPROJ
        LLM --> |neurodex_save| FTS
    end

How It Works

Session Start

sequenceDiagram
    participant LLM as Claude / Codex
    participant MCP as NEURODEX MCP Server
    participant DB as SQLite (local)

    LLM->>MCP: neurodex_brain()
    MCP->>DB: Read nodes, edges, chunks, insights
    MCP-->>LLM: Complete project brain (~14k tokens)
    Note over LLM: Now knows every module,<br/>function signature, dependency,<br/>and past session decision
    LLM->>LLM: Ready to work (zero file reads)

Making a Change

sequenceDiagram
    participant User
    participant LLM as Claude / Codex
    participant MCP as NEURODEX MCP Server

    User->>LLM: "Rename BrandProfile to BrandIdentity"
    LLM->>MCP: neurodex_references("BrandProfile")
    MCP-->>LLM: 13 references in 13 files with exact lines
    LLM->>MCP: neurodex_impact("brands/models.py")
    MCP-->>LLM: 20 affected symbols, risk 0.73
    LLM->>MCP: neurodex_cross_impact("brands/models.py")
    MCP-->>LLM: 3 cross-project contracts affected
    LLM->>LLM: Makes targeted edits (reads only lines it changes)
    LLM->>MCP: neurodex_save("Renamed BrandProfile → BrandIdentity")
    Note over MCP: Saved for future sessions

Cross-Project Awareness

graph LR
    subgraph Backend
        BE_ROUTE[POST /auth/login] --> BE_SVC[AuthService.login]
        BE_SVC --> BE_REPO[UserRepository]
    end

    subgraph Frontend
        FE_PAGE[LoginPage.tsx] --> FE_API[fetch '/auth/login']
    end

    subgraph Mobile
        MOB_SCREEN[LoginScreen.dart] --> MOB_API[api.post '/auth/login']
    end

    BE_ROUTE -.->|contract| FE_API
    BE_ROUTE -.->|contract| MOB_API

    style BE_ROUTE fill:#f96
    style FE_API fill:#f96
    style MOB_API fill:#f96

When you change a backend endpoint, neurodex_cross_impact finds every frontend and mobile file that consumes it.

MCP Tools

Project Brain

The brain is not a markdown file. It is a compressed, structured representation of the entire project that the LLM processes in full.

PROJECT: ContentPlatform
  AI-powered SaaS for brand social content generation
  Stack: FastAPI, PostgreSQL, SuperTokens, Celery+Redis

MODULES:
  [auth] User authentication, JWT, Google/Apple OAuth
    files: models.py, oauth.py, repository.py, router.py, security.py, service.py
    · service.py:27-77 class AuthService
    · service.py:49-77 async def login(email: str, password: str) → LoginResponse
    · security.py:15-28 def create_access_token(user_id: str) → str
    § User: email(str), password_hash(str | None), full_name(str)
    § LoginResponse: access_token(str), refresh_token(str), expires_in(int)
    uses: common, core, organizations

  [brands] Brand profiles, RAG persona builder
    · models.py:29-84 class BrandProfile(BaseModel, TenantMixin)
    · persona_builder.py:23-25 build_brand_persona_from_url(url: str)
    § BrandProfile: name(String), voice_summary(Optional[str]), colors(Optional[dict])
    uses: common, core, generation

KEY FLOWS:
  [API] POST /auth/login (auth) → common → core
  [API] POST /brands/{id}/analyze (brands) → common → generation
  [TASK] execute_generation_job (tasks) → core

MEMORY:
  ! Brand colors extracted via Playwright screenshot, NOT HTML parsing
  ! N+1 in analytics fixed with selectinload, don't remove it

Every symbol has its file and exact line range. The LLM can target service.py:49-77 without reading the file first.

Setup

Install

pip install neurodex

Index a Project

cd your-project
neurodex init

Wire into Claude Code

neurodex install

This adds the MCP server to ~/.claude/settings.json and injects usage instructions into your project's CLAUDE.md.

Index Multiple Projects

cd backend && neurodex init
cd ../frontend && neurodex init
cd ../mobile && neurodex init

Create a Workspace (Cross-Repo Search)

neurodex workspace create "MyApp" /path/to/backend /path/to/frontend /path/to/mobile

CLI Commands

Benchmarks

Tested against ContentPlatform (342 files, 314 indexed):

Cross-project on GakkoDeck (4 repos, 1542 files):

What Gets Indexed

Language Support

18 languages with AST parsing: Python, JavaScript, TypeScript, Go, Rust, Java, C, C++, C#, Ruby, PHP, Swift, Kotlin, Scala, Dart, Elixir, Haskell, Lua

16 languages with regex fallback: SQL, Bash, Markdown, YAML, TOML, JSON, XML, HTML, CSS, SCSS, Vue, Svelte, Jupyter, and more

Tech Stack

Zero external services. Everything runs locally. Total install size ~20MB.

License

MIT