Skip to content

Haslab-dev/CortexIndex

BranchesTags

Repository files navigation

Cortex Index — Local-First AI Code Intelligence Engine

A persistent knowledge graph for your codebase. Cortex Index converts source code into a queryable graph with symbol resolution, call tracking, and token-optimized AI context building — all local, no cloud, no vector DB.

⚡ Key Features

  • 30 MCP Tools — Full Model Context Protocol (MCP v1.0) over stdio + HTTP JSON-RPC 2.0
  • 🧠 Brain System — Persistent .cortex/brain.md stores project purpose, rules, and knowledge. Created on cortex init, queryable via cortex_brain_get/update/append MCP tools. AI agents learn once, remember forever.
  • Memory-Safe Streaming Index — Streaming parse callback with bounded batch buffers (10K nodes/edges). No unbounded accumulation. 24GB → <500MB RSS fix verified.
  • Multi-Language Support — Go (real AST), TypeScript/JavaScript, Python, Rust, C/C++, Java, Kotlin, Swift — functions, structs, classes, interfaces, imports, enums, and argument type references extracted from all 8 languages.
  • Incremental & Git-Aware — fsnotify watcher (300ms debounce), Git hook integration, branch comparison.
  • Project-Local — No global database. Each project owns .cortex/ next to it. cortex init creates it. cortex clean resets it.
  • Visual Web UI — Dark/light mode dashboard with force-directed SVG graph, data explorer, and search.
  • Embedded Storage — SQLite (default) or Pebble LSM tree (optional pkg/storage/pebble/).

🏗️ Architecture

                    ┌──────────────┐
                    │  AI Agent     │
                    │ (Claude/etc)  │
                    └──────┬───────┘
                           │ MCP (Stdio / HTTP)
              ┌────────────▼────────────┐
              │    Cortex MCP Server     │
              │  30 tools · JSON-RPC 2.0 │
              └────────────┬────────────┘
                           │
         ┌─────────────────┼─────────────────┐
         │                 │                  │
    ┌────▼────┐     ┌─────▼─────┐     ┌─────▼────┐
    │ Query    │     │ Knowledge  │     │ Context   │
    │ Planner  │     │ Graph Eng  │     │ Builder   │
    └────┬────┘     └─────┬─────┘     └─────┬────┘
         └────────────────┼─────────────────┘
                          │
              ┌───────────▼───────────┐
              │   Storage Layer        │
              │   SQLite / Pebble      │
              │   .cortex/data/        │
              └───────────┬───────────┘
                          │
              ┌───────────▼───────────┐
              │   Incremental Indexer  │
              │   Streaming Parser     │
              │   (bounded 10K batch)  │
              └───────────┬───────────┘
                          │
         ┌──────────────────────┼──────────────────────┐
         │          │           │            │          │
    ┌───▼───┐  ┌───▼───┐  ┌───▼───┐  ┌───▼───┐  ┌───▼───┐
    │  Go   │  │TS/JS  │  │Python │  │ Rust  │  │C/C++  │
    │(AST)  │  │(regex)│  │(regex)│  │(regex)│  │(regex)│
    └───────┘  └───────┘  └───────┘  └───────┘  └───────┘
    ┌───▼───┐  ┌───▼───┐  ┌───▼───┐
    │ Java  │  │Kotlin │  │ Swift │
    │(regex)│  │(regex)│  │(regex)│
    └───────┘  └───────┘  └───────┘

🚀 Getting Started

# Install
git clone https://github.com/Haslab-dev/CortexIndex.git
cd CortexIndex && make build && go install ./cmd/cortex

# Or quick install with Go
go install github.com/Haslab-dev/CortexIndex/cmd/cortex@latest

# Create a project
cd ~/my-project
cortex init            # creates .cortex/ with brain.md + project.json
cortex index           # full index (88 files / 530 symbols in ~84ms)
cortex serve           # HTTP API + UI at localhost:8080

# Quick MCP test
cortex mcp call cortex_get_project_summary '{}'
cortex mcp call cortex_find_symbol '{"name":"InitDB"}'

🧠 Brain System — Persistent Agent Knowledge

The brain file (.cortex/brain.md) records your project's purpose, rules, and explanations. Created automatically on cortex init. AI agents read it to understand context without codebase exploration.

# View
cortex brain

# Set purpose + rules
cortex brain update "## Purpose\nAPI router for 10+ LLM providers with cost tracking"

# Append knowledge
cortex brain append "Providers self-register via init() calling Register()"

# Via MCP (agent-friendly)
cortex mcp call cortex_brain_update '{"content":"## Purpose\n..."}'
cortex mcp call cortex_brain_append '{"line":"Uses Pebble for cold storage"}'

The brain persists between agent sessions — knowledge learned once is retained.

📊 Performance Benchmarks

Tested on my-ai-router (88 files, 530 symbols, Go + TypeScript codebase):

Operation Time Notes
Cold full index 84ms Streaming parse + batch edge resolution
Incremental index 60ms Hash-based skip for unchanged files
Symbol lookup <2ms SQLite indexed queries
Call graph <5ms Depth-3 traversal
Architecture map <3ms Single query aggregation
Idle RSS ~25MB After GC stabilization
Full index RSS <150MB Bounded batch buffers at 10K
Storage (SQLite) ~2MB 88 files, 4038 edges

Memory safety fix (24GB → <500MB) verified: streaming callback eliminates unbounded []*ParseResult accumulation, batch buffers capped at 10K nodes/edges, cache eviction every 5 minutes with 10K max entries.

🔌 30 MCP Tools Reference

🧠 Brain (3 tools)

Tool Description Example
cortex_brain_get Read brain.md (purpose/rules) {}
cortex_brain_update Replace brain.md content {"content":"## Purpose\n..."}
cortex_brain_append Append line as "Learned" {"line":"Uses Pebble storage"}

🔍 High-Level Intelligence (5 tools)

Tool Description Example
cortex_build_context Token-optimized AI context bundle (symbol + callers + callees + risk + advice) {"name":"AnthropicProvider"}
cortex_find_entry_points Find main/Init/Serve/Start functions {}
cortex_find_dead_code Functions with zero callers {}
cortex_get_diagnostics Health report + parse failures {}
cortex_compare_branches Git branch diff (files + symbols) {"branch":"main"}

🔎 Code Intelligence (7 tools)

Tool Description Example
cortex_find_symbol Search symbol by name {"name":"AnthropicProvider"}
cortex_get_definition Get symbol definition location {"name":"InitDB"}
cortex_find_references All symbols referencing target {"name":"GatewayContext"}
cortex_find_callers Functions calling target {"name":"Execute"}
cortex_find_callees Functions called by target {"name":"handleChatCompletions"}
cortex_search_text Full-text search (name/doc/sig/path) {"query":"pricing"}
cortex_search_path Search files by path {"query":"providers"}

📁 Structure Navigation (5 tools)

Tool Description Example
cortex_get_file File metadata + symbols (auto-detects dirs) {"path":"pkg/db/db.go"}
cortex_list_symbols All symbols in a file {"path":"pkg/gateway/router.go"}
cortex_get_module Files in a directory {"path":"internal/gateway"}
cortex_get_package Same as get_module (alias) {"path":"pkg/db"}
cortex_explore_directory Directory contents with metadata {"path":"providers"}

🏛️ Architecture (4 tools)

Tool Description Example
cortex_get_architecture Module-level architecture map {}
cortex_get_dependency_graph Import/dependency edges {}
cortex_get_call_graph Call tree (depth-3) for a symbol {"name":"main"}
cortex_get_type_graph Type hierarchy (structs/interfaces) {}

📊 Project Intelligence (6 tools)

Tool Description Example
cortex_get_project_summary Files, symbols, nodes, edges, health {}
cortex_get_stats Same as summary {}
cortex_get_health Service health check {}
cortex_get_recent_changes Git branch + dirty files {}
cortex_index Trigger full re-index {}
cortex_get_type_graph Type nodes (struct/class/interface/enum) {}

🔌 MCP Client Configuration

Claude Desktop / Antigravity / Cursor

{
  "mcpServers": {
    "cortex-index": {
      "command": "cortex",
      "args": ["mcp", "stdio"]
    }
  }
}

HTTP Transport (server already running)

{
  "mcpServers": {
    "cortex-http": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Kilo AI (~/.config/kilo/kilo.json)

{
  "mcp": {
    "cortex-index": {
      "type": "local",
      "command": ["cortex", "mcp", "stdio"]
    }
  }
}

🧪 Tutorial: AI Agent Exploring a Codebase

Step 1 — Project overview

cortex mcp call cortex_get_project_summary '{}'
# → 88 files, 530 symbols, 4038 edges, HEALTHY

Step 2 — Understand a symbol

cortex mcp call cortex_build_context '{"name":"AnthropicProvider"}'
# → Target, risk score, callers, callees, neighbors, AI advice

Step 3 — Trace usage

cortex mcp call cortex_find_callers '{"name":"AnthropicProvider"}'
# → 33 callers including handleChatCompletions, GetPricing, etc.

cortex mcp call cortex_find_references '{"name":"GatewayContext"}'
# → All files referencing this type

Step 4 — Explore architecture

cortex mcp call cortex_get_architecture '{}'
# → Module grouping with file/symbol counts

cortex mcp call cortex_get_dependency_graph '{}'
# → 200 import/dependency edges

Step 5 — Debug with graph

cortex mcp call cortex_get_call_graph '{"name":"handleChatCompletions"}'
# → Call tree showing request flow

cortex mcp call cortex_find_dead_code '{}'
# → 423 candidate dead functions

Step 6 — Persistent learning

cortex brain update "## Purpose\nAI router proxying to 10+ LLM providers"

cortex brain append "Each provider self-registers via init() → Register()"

cortex mcp call cortex_brain_append '{"line":"Cache middleware calls Execute() on cache-miss"}'

🧪 Testing & Verification

# Unit tests
make test              # go test ./... + UI typecheck

# Full integration test
cd ~/my-project && cortex init && cortex index && cortex serve

# MCP tool verification
cortex mcp call cortex_find_symbol '{"name":"main"}'
cortex mcp call cortex_brain_get '{}'

# Memory test (watch RSS)
/usr/bin/time -l cortex index

Verified Results (27/27 tools + 3 brain = 30/30 PASS)

Category Tools Status
Brain brain_get, brain_update, brain_append ✅
Symbol find_symbol, search_symbol, get_definition, search_text, search_path ✅
Reference find_references, find_callers, find_callees ✅
File get_file, list_symbols, get_module, get_package, explore_directory ✅
Graph get_call_graph, get_dependency_graph, get_type_graph ✅
Architecture get_architecture ✅
Intelligence build_context, find_entry_points, find_dead_code, get_diagnostics, compare_branches ✅
Project get_project_summary, get_stats, get_health, get_recent_changes, index ✅

🛠️ CLI Reference

cortex init              # Create .cortex/ + project.json + brain.md
cortex index             # Full codebase indexing
cortex watch             # Real-time file watcher
cortex clean             # Remove indexed data, keep config

cortex brain             # Read brain.md
cortex brain update      # Replace brain.md content
cortex brain append      # Append "Learned" line

cortex status            # Index health + stats
cortex doctor            # System check
cortex serve             # HTTP API + MCP + UI on :8080
cortex start -d          # Daemon mode (background)
cortex stop              # Stop daemon

cortex mcp stdio         # MCP via stdin/stdout
cortex mcp call <tool>   # Direct tool invocation

cortex hooks install     # Git hooks (commit/checkout/merge)
cortex hooks remove      # Remove hooks

📊 UI Dashboard

The dashboard includes:

  • Overview — Real-time metrics, indexing activity chart, language distribution
  • Graph — Force-directed SVG graph with glow edges, node dragging, dark/light mode
  • Data Explorer — Browse nodes, edges, files, and metadata with pagination
  • Search — AI-powered semantic symbol search
  • Insights — Architecture risk analysis
  • Settings — Engine configuration

Built with React 19 + Vite 6 + Tailwind CSS 4 + d3-force + Recharts.

🔧 Build from Source

make build        # Build binary + UI
make build-ui     # UI only
make serve        # Run backend on :8080
make ui           # Run UI dev server on :3000
make dev          # Both concurrently
make install      # Install globally

📄 License

MIT License © 2026 Cortex Index Team.

About

Local-first AI code intelligence engine & persistent semantic OS for your codebase. Features: 22 native MCP tools, Go AST graph engine, Context Builder, and a Bun-powered Web UI dashboard.

Resources

Readme
Activity
Custom properties

Stars

6 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages