index1

# index1

AI memory system for coding agents with BM25 + vector hybrid search. Provides 6 MCP tools for intelligent code/doc search and cognitive fact recording.

## What it does

- **Dual memory**: corpus (code index) + cognition (episodic facts)
- **Hybrid search**: BM25 full-text + vector semantic search with RRF fusion
- **Structure-aware chunking**: Markdown, Python, Rust, JavaScript, plain text
- **MCP Server**: 6 tools (`recall`, `learn`, `read`, `status`, `reindex`, `config`)
- **CJK optimized**: Chinese/Japanese/Korean query detection with dynamic weight tuning
- **Built-in ONNX embedding**: Vector search works out of the box, no Ollama required
- **Graceful degradation**: Works without any embedding service (BM25-only mode)

## Install

```bash
# Recommended
pipx install index1

# Or via pip
pip install index1

# Or via npm (auto-installs Python package)
npx index1@latest
```

One-click plugin setup:

```bash
index1 setup                 # Auto-configure hooks + MCP for Claude Code
```

Verify:

```bash
index1 --version
index1 doctor        # Check environment
```

## Setup MCP

Create `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "index1": {
      "type": "stdio",
      "command": "index1",
      "args": ["serve"]
    }
  }
}
```

> If `index1` is not in PATH, use the full path from `which index1`.

## Add Search Rules

Add to your project's `.claude/CLAUDE.md`:

```markdown
## Search Strategy

This project has index1 MCP Server configured (recall + 5 other tools). When searching code:

1. Known identifiers (function/class/file names) -> Grep/Glob directly (4ms)
2. Exploratory questions ("how does XX work") -> recall first, then Grep for details
3. CJK query for English code -> must use recall (Grep can't cross languages)
4. High-frequency keywords (50+ expected matches) -> prefer recall (saves 90%+ context)
```

**Impact**:

```
Without rules: Grep "search" -> 881 lines -> 35,895 tokens
With rules:    recall        -> 5 summaries ->...