index1

AI memory system for coding agents — code index + cognitive facts, persistent across sessions.

# 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 -> 460 tokens (97% savings)
```

## Index Your Project

```bash
index1 index ./src ./docs    # Index source and docs
index1 status                # Check index stats
index1 search "your query"   # Test search
```

## Optional: Multilingual Enhancement

index1 v2 has built-in ONNX embedding (bge-small-en-v1.5). For better multilingual support:

```bash
curl -fsSL https://ollama.com/install.sh | sh
ollama pull nomic-embed-text           # Standard, 270MB
# or
ollama pull bge-m3                     # Best for CJK, 1.2GB

index1 config embed_backend ollama
index1 doctor                          # Verify setup
```

Without Ollama, ONNX embedding provides vector search out of the box.

## Web UI

```bash
index1 web                   # Start Web UI on port 6888
index1 web --port 8080       # Custom port
```

## MCP Tools Reference

| Tool | Description |
|------|-------------|
| `recall` | Unified search — code + cognitive facts, BM25 + vector hybrid |
| `learn` | Record insights, decisions, lessons learned (auto-classify + dedup) |
| `read` | Read file content + index metadata |
| `status` | Index and cognition statistics |
| `reindex` | Rebuild index for a path or collection |
| `config` | View or modify configuration |

## Troubleshooting

| Issue | Fix |
|-------|-----|
| Tools not showing | Check `.mcp.json` format and `index1` path |
| AI doesn't use recall | Add search rules to CLAUDE.md |
| `command not found` | Use full path from `which index1` |
| Chinese search returns 0 | Install Ollama + `bge-m3` model |
| No vector search | Built-in ONNX should work; run `index1 doctor` |