index1 — AI-Native Project Knowledge Base
Description: Give your AI coding assistant project memory. BM25 + vector hybrid search, MCP Server, < 200ms response. Works with Claude Code, Cursor, Windsurf, Cline.

# Project Memory
for AI Coding Assistants

BM25 + vector hybrid search. One-line install. Zero config.
Your AI assistant finally understands your entire codebase.

Install from PyPI View Benchmark
`pipx install index1`

index1 tested in real-world Claude grep! Comparison of index1 + Claude grep vs Claude grep only:

< 200ms
Hybrid search response
90-99%
Context token savings
5
MCP tools for AI agents
0
Config required

## Why index1?

Native search tools return too many results, flooding your AI's context window. index1 returns just what matters.

🔍

### Hybrid Search

BM25 full-text + vector semantic search with Reciprocal Rank Fusion. Finds what keyword search misses.

💾

### Single-File Storage

Everything in one SQLite file. FTS5 + sqlite-vec. No external database, no Docker, no services to manage.

🌐

### CJK Optimized

Dynamic weight tuning for Chinese/Japanese/Korean queries (BM25=0.2, Vector=0.8). Built-in jieba tokenizer.

✂️

### Smart Chunking

Structure-aware splitting: headings for Markdown, AST for Python, regex patterns for Rust/JS/TS. 5 language-specific chunkers.

⚡

### L1/L2 Cache

Two-tier query cache with 10-min TTL. Repeated queries return in < 1ms. Cache hit rate 70%+ in typical sessions.

🔧

### Graceful Degradation

Ollama not installed? Falls back to BM25-only search automatically. No crash, no error, still works.

## 3 Steps to Start

From install to AI-powered search in under 2 minutes.

# Terminal

    # 1. Install
    pipx install index1

    # 2. Index your project
    index1 index ./src ./docs

    # 3. Search (or let your AI agent search via MCP)
    index1 search "how does authentication work"

.mcp.json (Claude Code / Cursor / Windsurf)

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

## Works Everywhere

MCP-native. Plug into any AI coding assistant that supports the Model Context Protocol.

🤖

### Claude Code

MCP stdio
📝

### Cursor

MCP stdio
🐾

### OpenClaw

MCP stdio
🌊

### Windsurf

MCP stdio
📦

### Cline

VS Code
💻

### CLI / Scripts

index1 search
🌐

### Web UI

port 6888
🔗

### Any MCP Client

stdio

## Performance

Benchmarked on 17,725 chunks / 1,707 documents / Apple M2.

40-180ms
Hybrid Search (cold)
BM25 + Vector + RRF fusion
< 1ms
Cached Query
L1/L2 two-tier cache
90-99%
Token Savings
vs Grep returning all matches

The Problem: `grep "config"` returns 5,000-35,000 tokens. `index1 search "config"` returns ~400 tokens of the most relevant results.

Full Benchmark Report →

## Architecture

Simple, local, no external services required.

    Claude Code ──▶ MCP Server (stdio)
                        │
    CLI ────────────▶ Query Engine ──▶ SQLite
                        │               ├── FTS5 (BM25)
    Web UI ─────────┘               └── sqlite-vec (vector)
                        │
                  Ollama Embedding (optional)

### Storage

Single SQLite file at `~/.claude-index1/knowledge.db`. Portable, backupable, zero maintenance.

### Search

BM25 + vector with RRF (k=60). CJK-aware weight tuning. Cosine similarity reranking.

### Embedding

Ollama-powered. Supports nomic-embed-text, bge-m3, all-minilm. Or runs BM25-only without it.

## Choose Your Model

Ollama is optional but recommended. Pick a model that fits your needs.

Model | Dim | Disk | RAM | Best For
--- | --- | --- | --- | ---
`all-minilm` | 384 | ~45 MB | ~250 MB | English, low-resource machines
`nomic-embed-text` default | 768 | ~270 MB | ~500 MB | English + Chinese, general use
`bge-m3` | 1024 | ~1.2 GB | ~1.2 GB | Chinese-optimized, 100+ languages

## Give Your AI Assistant
Project Memory

One command. Works in 2 minutes. Free and open source.

Install index1 Star on GitHub