indexin 3.1.3
Lightweight code context engine for AI assistants
License: MIT
Requires Python: >=3.10
Keywords: code, search, ai, mcp, embedding

# Indexin

A lightweight, efficient code context engine for AI assistants with automatic incremental indexing.

[![PyPI version](https://badge.fury.io/py/indexin.svg)](https://badge.fury.io/py/indexin)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- 🚀 **Automatic Incremental Indexing** - Detects file changes and indexes automatically
- 💾 **Memory Efficient** - Streaming processing, ~200MB memory usage
- 🔍 **Semantic Search** - Natural language code search with embeddings
- 📊 **Code Graph Analysis** - Symbol lookup, dependencies, call graph
- 🎯 **Zero Configuration** - Works out of the box with sensible defaults
- 🔌 **MCP Server** - Pure Model Context Protocol server, no external dependencies
- 🌐 **Multi-Provider** - Supports SiliconFlow, OpenAI, Ollama

## Installation

```bash
pip install indexin
```

## Quick Start

### Set API Key

```bash
# SiliconFlow (recommended for China users)
export SILICONFLOW_API_KEY="your-key"

# Or OpenAI
export OPENAI_API_KEY="your-key"

# Or use local Ollama (no API key needed)
```

### Command Line Usage

```bash
# Index current directory
indexin index

# Search code
indexin search "authentication flow"
```

### MCP Server Usage

Add to your MCP client configuration (Claude Desktop, Cursor, Windsurf, etc.):

```json
{
  "mcpServers": {
    "indexin": {
      "command": "python",
      "args": ["-m", "indexin.mcp"],
      "env": {
        "SILICONFLOW_API_KEY": "your-key"
      }
    }
  }
}
```

## MCP Tools

Indexin provides 7 powerful tools for code understanding:

### Core Tools

- **`set_project`** - Set project root directory
- **`search_code`** - Semantic code search (auto-indexes if needed)
- **`get_symbol`** - Find symbol definitions (auto-indexes if needed)
- **`get_dependencies`** - Get file dependencies and dependents (auto-indexes if needed)
- **`get_callers`** - Find function callers (auto-indexes if needed)
- **`get_status`** - Get indexing status (auto-indexes if needed)
- **`clear_index`** - Clear all indexed data

### Automatic Indexing

All read operations automatically detect file changes and perform incremental indexing **silently**:

```
User: search_code("authentication")
System: [Detects changes] → [Indexes silently] → [Returns results]
User sees: Only search results
```

No manual indexing needed! The system keeps itself up-to-date automatically.

## Configuration

Environment variables:

```bash
# Embedding provider (auto-detects by default)
EMBEDDING_PROVIDER=siliconflow  # auto, siliconflow, openai, ollama

# Batch size for embeddings
EMBEDDING_BATCH_SIZE=32

# Maximum file size to index (MB)
MAX_FILE_SIZE_MB=1

# Chunk size for code splitting
CHUNK_MAX_CHARS=1500

# Concurrent files to process
CONCURRENT_FILES=5
```

## Supported Languages

Python, JavaScript, TypeScript, Go, Java, Rust, C/C++, C#, PHP, Ruby, Shell, JSON, YAML, Markdown

## Architecture

Simple and efficient design:

- **`config.py`** - Configuration management
- **`utils.py`** - File filtering (entropy detection, temp files)
- **`embedder.py`** - Embedding providers
- **`parser.py`** - Tree-sitter code parsing
- **`storage.py`** - Vector storage (JSON-based)
- **`graph.py`** - Code graph (symbols, imports)
- **`core.py`** - Core indexing logic with auto-indexing
- **`cli.py`** - Command line interface
- **`mcp.py`** - MCP server

## Performance

Tested on a 55-file project:

- **Indexing time**: ~30 seconds (first time)
- **Incremental update**: ~3-5 seconds (changed files only)
- **Memory usage**: ~200MB
- **Search latency**: ~1 second

## Smart Features

### Entropy Detection

Automatically skips encrypted/obfuscated files (entropy > 7.5):

```python
# Detects and skips:
- Compiled binaries
- Encrypted files
- Obfuscated code (pyarmor, etc.)
```

### Temp File Filtering

Automatically ignores temporary and generated files:

```python
# Skips:
- .pyc, __pycache__
- node_modules
- .git, .svn
- *.min.js, *.bundle.js
- And more...
```

### Incremental Indexing

Only re-indexes changed files using MD5 hash comparison:

```python
# First index: 55 files, 30 seconds
# No changes: 0 files, 0.1 seconds
# 3 files changed: 3 files, 3 seconds
```

## Use Cases

### For AI Coding Assistants

```python
# Find authentication code
search_code("user authentication")

# Understand a class
get_symbol("UserManager")

# Analyze dependencies
get_dependencies("auth/login.py")

# Find who calls a function
get_callers("validate_token")
```

### For Code Analysis

```python
# Project overview
get_status()

# Dependency graph
get_dependencies("main.py")

# Call graph analysis
get_callers("critical_function")
```

## Comparison with Other Tools

| Feature | Indexin | DeepContext | Others |
|---------|---------|-------------|--------|
| Auto-indexing | ✅ Silent | ❌ Manual | ❌ Manual |
| Memory usage | ~200MB | Varies | Varies |
| Incremental | ✅ Hash-based | ✅ | ⚠️ Limited |
| Dependencies | ✅ | ❌ | ⚠️ Limited |
| Call graph | ✅ | ❌ | ⚠️ Limited |
| Setup | Zero config | API key | Complex |

## Development

### Install from source

```bash
git clone https://github.com/yourusername/indexin.git
cd indexin
pip install -e .
```

### Run tests

```bash
# Test all MCP tools
python -m pytest tests/

# Test CLI
indexin index
indexin search "test query"
```

## Requirements

- Python 3.10+
- httpx >= 0.27.0
- mcp >= 1.0.0
- rich >= 13.0.0
- tree-sitter >= 0.23.0
- tree-sitter-python >= 0.23.0
- tree-sitter-javascript >= 0.23.0
- tree-sitter-typescript >= 0.23.0

## License

MIT License - see LICENSE file for details

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

- **Issues**: [GitHub Issues](https://github.com/yourusername/indexin/issues)
- **Documentation**: [Full Documentation](https://github.com/yourusername/indexin)
- **PyPI**: [Package Page](https://pypi.org/project/indexin/)

## Changelog

### v3.0.0 (Latest)

- ✨ Automatic incremental indexing
- ✨ Silent auto-indexing on all read operations
- ✨ Enhanced code graph with dependencies and callers
- ✨ Entropy-based file filtering
- ✨ Streaming file hash calculation
- 🚀 Memory optimized (~200MB)
- 🐛 Fixed event loop issues from v2
- 🎯 Zero configuration required

### v2.0.0

- Complete rewrite with DDD architecture
- Pure MCP server (no HTTP daemon)
- ❌ Had memory issues (8GB)

### v1.0.0

- Initial release
- HTTP daemon architecture
- Basic indexing and search

## Acknowledgments

Built with ❤️ for developers who want smarter code understanding.

---

**Make your AI assistant understand your codebase better with Indexin!**