AiDex

AiDex

The persistent brain for AI coding agents.

AiDex is an MCP server that gives AI coding assistants a memory, semantic search, and live telemetry — local-first, model-agnostic. Works with any MCP-compatible AI assistant: Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, VS Code Copilot, and more.

Three Pillars

🧠 Memory — Tasks, notes, and session-notes survive every chat. Auto-logged history, scheduled tasks, cross-session continuity. Your AI knows tomorrow what mattered today.

🔍 Search — Three modes: exact (identifier), semantic (concept), hybrid (RRF fusion of both). Embeds code, docs, and workspace items into one ranking. Cross-project — every repo in one query. Optional LLM layer translates non-English queries and reranks results.

🌐 Telemetry — LogHub receives live logs from any app via HTTP (no SDK). The AI watches what your code actually does, not just what it says. Live-streamed in the Viewer.

What's Inside — 33 Tools in One Server

12 languages — C#, TypeScript, JavaScript, Rust, Python, C, C++, Java, Go, PHP, Ruby, HCL/Terraform

# Find where "PlayerHealth" is defined — 1 call, ~50 tokens
aidex_query({ term: "PlayerHealth" })
→ Engine.cs:45, Player.cs:23, UI.cs:156

# All methods in a file — without reading the whole file
aidex_signature({ file: "src/Engine.cs" })
→ class GameEngine { Update(), Render(), LoadScene(), ... }

# What changed in the last 2 hours?
aidex_query({ term: "render", modified_since: "2h" })

# Search across ALL your projects at once
aidex_global_query({ term: "TransparentWindow", mode: "contains" })
→ Found in: LibWebAppGpu (3 hits), DebugViewer (1 hit)

# Leave a note for your next session
aidex_note({ path: ".", note: "Test the parser fix after restart" })

# Create a task while working
aidex_task({ path: ".", action: "create", title: "Fix edge case in parser", priority: 1, tags: "bug" })

Table of Contents

• What's Inside
• Semantic Search & LLM Layer 🆕
• The Problem
• The Solution
• Why Not Just Grep?
• How It Works
• Features
• Supported Languages
• Quick Start
• Available Tools
• Time-based Filtering
• Project Structure
• Session Notes
• Task Backlog
• Global Search
• AI Guidelines
• Log Hub
• Debug Dashboard
• Screenshots — LLM-Optimized
• Interactive Viewer
• CLI Usage
• Performance
• Technology
• Contributing
• License

Semantic Search & LLM Layer

v2.0 added semantic search via locally-run embeddings — your AI can find a function even when it doesn't know the exact identifier.

Three modes — pick the right tool for the question

What gets embedded

• Code — every method and type, three-tier chunking (signature + doc-comment + weighted identifier bag)
• Docs — Markdown sections (README, CHANGELOG, docs/, plan files), split at heading boundaries
• Workspace — tasks, task logs, session notes, archived note history

One ranking, all kinds. A query like "how to write logs from external programs" surfaces the README's ## Log Hub section first, then the log method in commands/log.ts, then any related task.

Setup

// Enable embeddings on a project (one-time, ~30s for AiDex itself, cached afterwards)
aidex_init({ path: ".", embeddings: true })

// Search
aidex_search({ query: "how do we batch requests to the LLM", path: "." })
aidex_search({ query: "retry with backoff", scope: "all" })  // across every embedded project

Or use the Settings tab in the Viewer (aidex_settings({ path: ".", open: true })) — toggles for embeddings, LLM provider, model, and the privacy switch.

Optional LLM layer

When an Anthropic / OpenAI / OpenRouter / Ollama / HuggingFace API key is configured, AiDex can:

• Translate non-English queries → "wie speichere ich Logs lokal" finds the right code
• Expand vague queries into 2-4 concrete subqueries (RRF-merged)
• Rerank top-N retrieval candidates

Privacy switch llm_send_code defaults to off — only your literal query and metadata (paths, names, anchors) are sent. Code bodies stay local. Per-project, easy to verify in Settings.

Local-first: works fully offline with pure embeddings. The LLM layer is opt-in, never required.

The Problem

Every time your AI assistant searches for code, it:

• Greps through thousands of files → hundreds of results flood the context
• Reads file after file to understand the structure → more context consumed
• Forgets everything when the session ends → repeat from scratch

A single "Where is X defined?" question can eat 2,000+ tokens. Do that 10 times and you've burned half your context on navigation alone.

The Solution

Index once, query forever:

# Before: grep flooding your context
AI: grep "PlayerHealth" → 200 hits in 40 files
AI: read File1.cs, File2.cs, File3.cs...
→ 2000+ tokens consumed, 5+ tool calls

# After: precise results, minimal context
AI: aidex_query({ term: "PlayerHealth" })
→ Engine.cs:45, Player.cs:23, UI.cs:156
→ ~50 tokens, 1 tool call

Result: 50-80% less context used for code navigation.

Why Not Just Grep?

The real cost of grep: Every grep result includes surrounding context. Search for User in a large project and you'll get hundreds of hits - comments, strings, partial matches. Your AI reads through all of them, burning context tokens on noise.

AiDex indexes identifiers: It uses Tree-sitter to actually parse your code. When you search for User, you get the class definition, the method parameters, the variable declarations - not every comment that mentions "user".

How It Works

1. Index your project once (~1 second per 1000 files)

   aidex_init({ path: "/path/to/project" })

   Copy to clipboard

2. AI searches the index instead of grepping

   aidex_query({ term: "Calculate", mode: "starts_with" })
   → All functions starting with "Calculate" + exact line numbers
   
   aidex_query({ term: "Player", modified_since: "2h" })
   → Only matches changed in the last 2 hours

   Copy to clipboard

3. Get file overviews without reading entire files

   aidex_signature({ file: "src/Engine.cs" })
   → All classes, methods, and their signatures

   Copy to clipboard

The index lives in .aidex/index.db (SQLite) - fast, portable, no external dependencies.

Features

• Tree-sitter Parsing: Real code parsing, not regex — indexes identifiers, ignores keywords and noise
• ~50 Tokens per Search: vs 2000+ with grep — your AI keeps its context for actual work
• Persistent Index: Survives between sessions — no re-scanning, no re-reading
• Incremental Updates: Re-index single files after changes, not the whole project
• Time-based Filtering: Find what changed in the last hour, day, or week
• Auto-Cleanup: Excluded files (e.g., build outputs) are automatically removed from index
• Zero Dependencies: SQLite with WAL mode — single file, fast, portable

Supported Languages

Quick Start

Prerequisites

• Node.js ≥ 18 (check with node --version)
  • macOS: brew install node or nvm install 18 && nvm use 18
  • Linux: use your package manager or nvm
  • Windows: nodejs.org
  • If you use nvm, the repo ships a .nvmrc — nvm use picks the right version automatically.

1. Install

…