Legacy library
This page describes the old TypeScript @sylphx/coderag library. It is not the Locus MCP server. The live server is local Rust BM25 in @sylphx/locus. Start at the quickstart.
API Overview
Locus provides a comprehensive API for semantic code search with vector embeddings. This reference documents all exported types, classes, and functions.
Installation
npm install @sylphx/coderagPackage Structure
Locus uses ESM-only exports with TypeScript support. The package provides both a main entry point and specialized subpath exports:
Main Entry Point
import { CodebaseIndexer } from '@sylphx/coderag'Exports all core functionality including:
- CodebaseIndexer (primary class)
- Search functions (hybrid, semantic, keyword)
- Embedding providers
- Storage implementations
- AST chunking utilities
- Type definitions
Subpath Exports
Specialized exports for advanced use cases:
// Indexer only
import { CodebaseIndexer } from '@sylphx/coderag/indexer'
// TF-IDF utilities
import { buildSearchIndex, searchDocuments } from '@sylphx/coderag/tfidf'
// Storage implementations
import { PersistentStorage, MemoryStorage } from '@sylphx/coderag/storage'
// Utilities
import { scanFiles, detectLanguage } from '@sylphx/coderag/utils'Import Patterns
Basic Usage
import { CodebaseIndexer } from '@sylphx/coderag'
const indexer = new CodebaseIndexer({
codebaseRoot: '/path/to/codebase',
storage: new PersistentStorage()
})
await indexer.index()
const results = await indexer.search('authentication')With Embeddings
import {
CodebaseIndexer,
createEmbeddingProvider,
PersistentStorage
} from '@sylphx/coderag'
const embeddingProvider = createEmbeddingProvider({
provider: 'openai',
model: 'text-embedding-3-small',
dimensions: 1536,
apiKey: process.env.OPENAI_API_KEY
})
const indexer = new CodebaseIndexer({
codebaseRoot: '/path/to/codebase',
storage: new PersistentStorage(),
embeddingProvider
})
await indexer.index()Hybrid Search
import { CodebaseIndexer, hybridSearch } from '@sylphx/coderag'
const indexer = new CodebaseIndexer({ /* ... */ })
await indexer.index()
const results = await hybridSearch('authentication flow', indexer, {
vectorWeight: 0.7, // 70% semantic, 30% keyword
limit: 10
})TypeScript Support
Locus includes comprehensive TypeScript definitions:
import type {
IndexerOptions,
SearchResult,
EmbeddingProvider,
CodebaseFile,
ChunkResult
} from '@sylphx/coderag'
// Type-safe configuration
const options: IndexerOptions = {
codebaseRoot: './src',
maxFileSize: 1048576,
watch: true
}
// Type-safe results
const results: SearchResult[] = await indexer.search('query')Environment Variables
Locus respects the following environment variables:
# OpenAI API configuration
OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://api.openai.com/v1 # Optional: custom endpoint
# Embedding model configuration
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_DIMENSIONS=1536 # Optional: override defaultCore Concepts
Chunk-Based Indexing
Locus uses AST-based chunking to split code at semantic boundaries (functions, classes, etc.). This provides better search granularity than file-level indexing.
import { chunkCodeByAST } from '@sylphx/coderag'
const chunks = await chunkCodeByAST(
code,
'example.ts',
{ maxChunkSize: 1000, preserveContext: true }
)
// Returns: ChunkResult[] with type, startLine, endLine, contentPersistent Storage
Locus uses SQLite via LibSQL for persistent storage:
import { PersistentStorage } from '@sylphx/coderag'
const storage = new PersistentStorage({
codebaseRoot: '/path/to/codebase',
// Automatically creates ~/.coderag/projects/<hash>/
})Incremental Updates
File changes are detected and indexed incrementally:
const indexer = new CodebaseIndexer({
codebaseRoot: './src',
watch: true,
onFileChange: (event) => {
console.log(`File ${event.type}: ${event.path}`)
}
})
await indexer.index()
// Subsequent calls detect changes and update incrementallyAPI Reference
- CodebaseIndexer - Main indexing and search class
- Storage - Persistent and in-memory storage
- Search Functions - Hybrid, semantic, and keyword search
- Embeddings - Embedding provider configuration
- AST Chunking - Code chunking utilities
- Types - TypeScript type definitions
Next Steps
- Read the CodebaseIndexer API for the main class documentation
- Explore Search Functions for advanced search capabilities
- Learn about Embedding Providers for semantic search