🧙 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

Quick Start

1. Go to any folder that contains your documents (PDF, TXT, MD) — or create a knowledge subfolder for them:

cd my-documents

2. Start LocalSage right there:

localsage

LocalSage picks the knowledge source automatically:

1. the path you pass with -k / --knowledge, if given
2. otherwise a knowledge/ subfolder in the current directory, if it exists
3. otherwise the current directory itself — so you can just cd into your docs folder and run 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

• /knowledge — list all loaded knowledge files as a tree
• history — show number of stored messages
• clear — clear conversation history
• exit — save history and quit

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 if it
                           exists, else the current directory)
  --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');

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 — recursively reads all TXT, MD, and PDF files from the resolved knowledge folder (explicit -k path → ./knowledge subfolder → current directory), including subfolders, while skipping node_modules, .git, and other junk directories
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