# fsq-codebase

Zero-config codebase indexer with FSQ embeddings for fast semantic code search. Why Finite Scalar Quantization to compress? Because nobody has tried it before, that's why. Also FSQ still loosely maintains the shape of the vector and does not need a codebook, in case I ever wanted to round trip the embeddings back to code (for example for previewing purposes, like a jpg thumbnail). 

## Features

- **Fast semantic search**: 10x compression with int8 embeddings, 2.7x faster search
- **Multi-language**: Python, JavaScript, TypeScript, Go, Rust, Java, and more
- **Zero-config**: Just point at a directory and search
- **MCP server**: Claude Code integration via Model Context Protocol

## Installation

Work in progress. For now you would need to build the model yourself. ANd 

## Quick Start

### Python API

```python
from fsq_codebase import CodebaseIndex, FSQEmbedder

# Index a codebase
index = CodebaseIndex.create("./my-project")
results = index.query("add rate limiting", top_k=10)
print(results.tree())

# Or use the embedder directly
embedder = FSQEmbedder.from_bundled("codet5plus-96d")
embeddings = embedder.encode(["def hello(): pass", "function greet() {}"])
```

### MCP Server (Claude Code)

```bash
# Start the MCP server
fsq-codebase --index ./codebase.index
```

Configure in Claude Code's `.mcp.json`:

```json
{
  "mcpServers": {
    "fsq-codebase": {
      "command": "fsq-codebase",
      "args": ["--index", "./codebase.index", "--verbose"]
    }
  }
}
```

## Bundled Models

| Model | Encoder | FSQ Dim | Size |
|-------|---------|---------|------|
| `codet5plus-96d` | CodeT5+ 110M | 96 | 268 KB |
| `unixcoder-96d` | UniXcoder | 96 | 652 KB |

The encoder (CodeT5+ or UniXcoder) downloads automatically from HuggingFace on first use (~440MB).

## Performance

Compared to CodeT5+ baseline on CoIR benchmark:

| Model | MRR | Storage | Search Speed |
|-------|-----|---------|--------------|
| CodeT5+ baseline | 0.9699 | 1024B | 0.39ms |
| **fsq-codebase** | **0.9706** | 96B | 0.14ms |

**10.7x compression** with **2.7x faster search** while maintaining accuracy.

## License

MIT