contextlite

v2.0.7

Published

5 months ago

RAG Systems Were a Mistake - Replace vector databases with 0.3ms mathematically optimal context selection

ContextLite npm Package

RAG Systems Were a Mistake - Replace slow vector databases with mathematically optimal context selection.

⚡ 0.3ms response time (vs 30-50ms for vector DBs) | 🎯 Provably optimal results | 💰 $0 ongoing costs | 🔒 100% local

A Node.js wrapper for ContextLite - the ultra-fast context engine that makes vector databases obsolete.

⬇️ More Downloads & Platforms

🚀 Quick Start

Installation

# Install globally for CLI access
npm install -g contextlite

# Or install locally for programmatic use
npm install contextlite

⚡ Auto-Discovery Setup (NEW in v2.0)

# One command setup for all your repositories
contextlite --onboard

# ✅ Finds all Git repositories automatically
# ✅ Preserves existing ContextLite databases
# ✅ Configures optimal settings per project
# ✅ Sets up VS Code integration
# ✅ Ready to use immediately

CLI Usage

# Quick setup (recommended)
contextlite --onboard

# Start specific project
contextlite --port 8080

# Interactive setup with advanced options
contextlite-onboard

# Get help
contextlite --help

Programmatic Usage

import { ContextLiteClient } from 'contextlite';

// Auto-start server and add documents
const client = new ContextLiteClient();

try {
    // Add some documents
    await client.addDocument("The quick brown fox jumps over the lazy dog.", "doc1");
    await client.addDocument("Node.js is a great runtime for server applications.", "doc2");
    await client.addDocument("TypeScript adds type safety to JavaScript development.", "doc3");
    
    // Query for relevant content
    const results = await client.query("server applications");
    console.log(`Found ${results.documents.length} relevant documents`);
    
    for (const doc of results.documents) {
        console.log(`Score: ${doc.score.toFixed(3)} - ${doc.content.slice(0, 50)}...`);
    }
} finally {
    await client.close();
}

With Auto-cleanup

import { withContextLiteClient } from 'contextlite';

await withContextLiteClient({ port: 8080 }, async (client) => {
    await client.addDocument("Hello from Node.js!");
    const results = await client.query("hello");
    console.log(results);
    // Client automatically closed when function exits
});

📋 Features

🆕 v2.0 Auto-Discovery Features

🔍 Intelligent Repository Detection: Automatically finds all Git repositories
⚡ 30-Second Setup: contextlite --onboard configures everything
🏗️ Multi-Project Management: Independent ContextLite instances per project
🔌 Development Tool Integration: Auto-imports from Git, VS Code, Claude Code, Copilot
🛡️ Enterprise Security: Production-ready with comprehensive security hardening

Core Performance

🔥 Ultra-Fast: Native Go binary performance with Node.js convenience
🛠️ Auto-Management: Automatically detects, downloads, and manages ContextLite binary
🔌 Easy Integration: Simple async/await API with TypeScript support
🌍 Cross-Platform: Works on Windows, macOS, and Linux (x64 and ARM64)
📦 Zero Config: Works out of the box with automatic binary detection
🎯 CLI Ready: Global installation provides contextlite command

🏗️ Architecture

This npm package provides Node.js bindings for the high-performance ContextLite engine:

Binary Management: Automatically manages ContextLite binary
Easy Integration: Downloads and configures ContextLite for your platform
Server Management: Handles ContextLite server lifecycle
TypeScript API: Provides fully-typed Node.js interface

📖 API Reference

ContextLiteClient

The main interface for interacting with ContextLite from Node.js.

Constructor

interface ClientOptions {
    host?: string;          // Server host (default: 'localhost')
    port?: number;          // Server port (default: 8080)
    autoStart?: boolean;    // Auto-start server if not running (default: true)
    databasePath?: string;  // Optional database file path
    timeout?: number;       // Request timeout in milliseconds (default: 30000)
}

const client = new ContextLiteClient(options);

Methods

addDocument(content, documentId?, metadata?) - Add a document
query(query, options?) - Search for documents
getDocument(documentId) - Retrieve specific document
deleteDocument(documentId) - Delete a document
getStats() - Get server statistics
isServerRunning() - Check if server is responsive
close() - Stop managed server and cleanup

Types

interface QueryOptions {
    maxResults?: number;
    minScore?: number;
}

interface QueryResult {
    documents: Array<{
        id: string;
        content: string;
        score: number;
        metadata?: Record<string, any>;
    }>;
    totalResults: number;
    queryTime: number;
}

interface Document {
    id: string;
    content: string;
    metadata?: Record<string, any>;
}

Error Handling

import { 
    ContextLiteClient,
    ContextLiteError,
    BinaryNotFoundError,
    ServerError
} from 'contextlite';

try {
    const client = new ContextLiteClient();
    await client.query("test");
} catch (error) {
    if (error instanceof BinaryNotFoundError) {
        console.error('ContextLite binary not found');
    } else if (error instanceof ServerError) {
        console.error('Server error:', error.message);
    } else if (error instanceof ContextLiteError) {
        console.error('ContextLite error:', error.message);
    }
}

🌐 Examples

⚙️ Dependency Note

We currently pin node-fetch to version 2.x to keep the distributed wrapper CommonJS-compatible. Version 3 of node-fetch is pure ESM and causes runtime errors (ERR_REQUIRE_ESM) when required from the transpiled lib/ output that uses CommonJS. A future update will provide dual ESM/CJS builds; at that point this pin can be lifted.

Document Management

import { ContextLiteClient } from 'contextlite';

const client = new ContextLiteClient();

// Add documents with metadata
await client.addDocument(
    "Advanced TypeScript patterns for scalable applications.",
    "ts-patterns-guide",
    {
        category: "programming",
        difficulty: "advanced",
        tags: ["typescript", "patterns", "scalability"]
    }
);

// Query with options
const results = await client.query(
    "typescript patterns",
    { maxResults: 5, minScore: 0.7 }
);

for (const doc of results.documents) {
    console.log(`Document: ${doc.id}`);
    console.log(`Score: ${doc.score.toFixed(3)}`);
    console.log(`Content: ${doc.content.slice(0, 100)}...`);
    console.log(`Metadata:`, doc.metadata);
    console.log('-'.repeat(50));
}

await client.close();

Batch Operations

import { ContextLiteClient } from 'contextlite';

const documents = [
    "React makes building user interfaces simple and declarative.",
    "Vue.js provides an approachable, versatile framework.",
    "Angular offers a comprehensive platform for web applications.",
    "Svelte compiles to vanilla JavaScript for optimal performance."
];

const client = new ContextLiteClient();

// Batch add documents
for (const [index, content] of documents.entries()) {
    await client.addDocument(content, `framework-${index}`);
}

// Search across all documents
const results = await client.query("web framework");

console.log(`Found ${results.documents.length} relevant documents`);
results.documents.forEach(doc => {
    console.log(`• ${doc.content} (Score: ${doc.score.toFixed(3)})`);
});

await client.close();

Custom Configuration

import { ContextLiteClient } from 'contextlite';

// Connect to existing server
const remoteClient = new ContextLiteClient({
    host: 'my-server.com',
    port: 9090,
    autoStart: false  // Don't try to start server
});

// Use custom database location
const localClient = new ContextLiteClient({
    databasePath: '/path/to/my/database.db',
    port: 8081
});

// Custom timeout and options
const client = new ContextLiteClient({
    timeout: 60000,  // 60 second timeout
    autoStart: true
});

Express.js Integration

import express from 'express';
import { ContextLiteClient } from 'contextlite';

const app = express();
const client = new ContextLiteClient({ port: 8081 });

app.use(express.json());

app.post('/documents', async (req, res) => {
    try {
        const { content, metadata } = req.body;
        const result = await client.addDocument(content, undefined, metadata);
        res.json(result);
    } catch (error) {
        res.status(500).json({ error: error.message });
    }
});

app.get('/search', async (req, res) => {
    try {
        const { q, max_results, min_score } = req.query;
        const results = await client.query(q as string, {
            maxResults: max_results ? parseInt(max_results as string) : undefined,
            minScore: min_score ? parseFloat(min_score as string) : undefined
        });
        res.json(results);
    } catch (error) {
        res.status(500).json({ error: error.message });
    }
});

const server = app.listen(3000, () => {
    console.log('Server running on port 3000');
});

// Cleanup on shutdown
process.on('SIGTERM', async () => {
    await client.close();
    server.close();
});

🛠️ Development

Local Development

# Clone the repository
git clone https://github.com/Michael-A-Kuykendall/contextlite.git
cd contextlite/npm-wrapper

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests
npm test

# Link for local testing
npm link

# Test global command
contextlite --help

Testing

# Install jest globally if needed
npm install -g jest

# Run tests with coverage
npm test -- --coverage

# Run specific test file
npm test -- binary-manager.test.ts

Building and Publishing

# Build TypeScript to JavaScript
npm run build

# Check package contents
npm pack

# Publish to npm (requires npm login)
npm publish

🔧 Binary Management

The package handles ContextLite setup automatically:

Installation Process

Platform Detection: Detects your system and architecture
Binary Setup: Downloads and configures ContextLite
Ready to Use: Makes ContextLite available for your application

Manual Installation

You can also install ContextLite binary manually:

# Download from GitHub releases
curl -L https://github.com/Michael-A-Kuykendall/contextlite/releases/latest/download/contextlite_linux_amd64 -o contextlite
chmod +x contextlite
sudo mv contextlite /usr/local/bin/

# Or using npm global install
npm install -g contextlite

📝 Requirements

Node.js: 14.0.0+
Platform: Windows, macOS, Linux (x64/ARM64)
Dependencies: node-fetch, tar
ContextLite Binary: Auto-downloaded or manually installed

🚨 Troubleshooting

Binary Not Found

# Manually download and install
npm run postinstall

# Or set NODE_ENV to avoid automatic download
NODE_ENV=development npm install

Permission Issues

# On Unix systems, ensure binary is executable
chmod +x /path/to/contextlite

# Check PATH variable
echo $PATH

Port Conflicts

// Use a different port
const client = new ContextLiteClient({ port: 9090 });

// Or check if port is in use
netstat -tlnp | grep :8080

📄 License

This npm package is released under the MIT License. The ContextLite binary may have different licensing terms.

🔗 Links

Homepage: https://contextlite.com
Documentation: https://docs.contextlite.com
GitHub: https://github.com/Michael-A-Kuykendall/contextlite
npm: https://www.npmjs.com/package/contextlite
Issues: https://github.com/Michael-A-Kuykendall/contextlite/issues

💬 Support

GitHub Issues: For bug reports and feature requests
Documentation: Comprehensive guides and API reference
npm Community: Package-specific discussions

Built with ❤️ by the ContextLite team. Perfect for Node.js developers who need blazing-fast context retrieval.