🧙 LocalSage

Your local, offline AI assistant that knows your documents.

LocalSage runs a Qwen language model entirely on your machine (via Transformers.js) and answers questions using your own PDF, TXT, and Markdown files. Pure Node.js — no Python, no API keys, no data leaving your computer.

Features

• 🤖 Runs AI locally via Transformers.js (ONNX) — no cloud, no API costs
• 📚 Chat with your PDF, TXT, and MD files
• 🔒 100% private — everything stays on your machine
• 💾 Conversation history saved automatically
• 🔧 Customizable model, knowledge folder, and generation settings
• 📦 Pure Node.js — no Python required

Installation

npm install -g localsage-ai

Quick Start

1. Create a knowledge folder in your working directory and add documents:

mkdir knowledge
cp your-document.pdf knowledge/

2. Start LocalSage:

localsage

The first run downloads the model (~500 MB) to your Hugging Face cache. After that, it works fully offline.

3. Ask questions about your documents!

Commands

• exit — save history and quit
• clear — clear conversation history
• history — show number of stored messages

Options

localsage [options]

  -m, --model <model>      Model to use (default: "onnx-community/Qwen2.5-0.5B-Instruct")
  -k, --knowledge <path>   Knowledge folder path (default: "./knowledge")
  --no-pdf                 Disable PDF support
  --max-tokens <number>    Max tokens for response (default: 200)
  --temperature <number>   Temperature for generation (default: 0.7)
  -h, --help               Show help
  -V, --version            Show version

Important: the model must be a repo that ships ONNX weights, e.g. the onnx-community/... mirrors. Plain Qwen/Qwen2.5-* repos will NOT load in Transformers.js.

Examples

# Use a bigger model
localsage --model onnx-community/Qwen2.5-1.5B-Instruct

# Custom knowledge folder
localsage --knowledge ./my_docs

# Adjust generation
localsage --max-tokens 300 --temperature 0.8

Programmatic Usage

const LocalSage = require('localsage-ai');

async function main() {
  const assistant = new LocalSage({
    model: 'onnx-community/Qwen2.5-0.5B-Instruct',
    knowledgePath: './knowledge',
    maxTokens: 200,
    temperature: 0.7,
  });

  await assistant.initialize();
  const response = await assistant.chat('What is the capital of France?');
  console.log(response);
}

main();

How It Works

1. Knowledge loading — reads all TXT, MD, and PDF files from the knowledge folder (plus an optional knowledge.txt in the working directory)
2. AI processing — runs the Qwen model locally with @huggingface/transformers
3. History — saves the conversation to history.json in the working directory

Requirements

• Node.js 18+
• 4 GB+ RAM recommended
• ~1–2 GB free disk space for model files

Model Storage

Models are cached by Transformers.js on first run. Override the cache location with the LOCALSAGE_MODEL_DIR environment variable.

💼 Open to Work

Built by a developer available for freelance and full-time opportunities. Got a project? Let's talk — 📧 [email protected]

License

MIT