RAGX

A private, local-first RAG engine: your documents in, answers out, with every statement cited back to the page it came from.

RAGX reads your PDFs, Word files, Markdown, text files and images, and answers questions about them. Each answer cites the passages and figures it used, and those citations are checked before you see them. Documents and search stay on your machine; only the question and the passages it found go to the answering model. RAGX works three ways:

• as a page inside ter-manager, a desktop app that hosts plugins, with a library, chat, a live tracker and settings;

• as a command-line tool (npm run rag -- …);

• as an MCP server, so AI coding agents such as Claude Code can search your documents themselves.

It also reads File Fabric / CanvasX canvases (through NoteX). A canvas becomes a document that keeps its layout, so an answer can say where on your canvas something is, not just what it says.

Why this was hard

A demo RAG is about 50 lines: split the text, embed it, find the nearest chunks. RAGX is built for real documents on a modest laptop (8 GB RAM), with no cloud database and almost no dependencies. Most of the work went into these problems:

Related MCP server: terminal_kb

Architecture

flowchart LR
  subgraph Inputs
    F["PDF · DOCX · MD · TXT · images"]
    N["NoteX canvas documents\n(+ files placed on canvases)"]
  end

  subgraph Engine["RAGX engine (Node 24)"]
    X["extract\nblocks + figures"] --> C["chunk\nheading-bounded"]
    C --> E["embed\nOllama embeddinggemma-2"]
    X --> R["read figures\nClaude Haiku"] --> E
    E --> S[("SQLite\nFTS5 + vectors")]
    Q["question"] --> H["hybrid search\nBM25 + vectors → RRF"]
    S --> H
    H --> A["answer\nClaude Code / Antigravity\ncitations checked"]
    T["tracker\nevery call, timed"]
  end

  F --> X
  N --> X
  A --> P["ter-manager page"]
  H --> M["MCP server\nragx_search · ragx_passage\nragx_figure · ragx_place\nragx_documents"]
  M --> AG["AI coding agents"]
  CLI["command line"] --> Engine

Ingest: file → copy → extract → chunk → embed → ready. Each step is recorded, so resume finishes what an interrupted run left half-done.

Ask: question → hybrid search → numbered sources → headless agent (Claude Code or Google Antigravity, on the user's own subscription, with tools off and API keys removed from its environment) → citations checked → answer with clickable sources and figures.

Features

Library

• Add PDF, DOCX, Markdown, text and image files. A file named like an existing document can replace it as a new version.

• Figures (charts, diagrams, pictures, scanned pages) are cropped, stored, read by Claude Haiku and searchable by description.

• File Fabric canvases are kept apart from ordinary files. When a canvas is updated, only its changed places are re-embedded.

• Files placed on a canvas come in as documents that remember where they sit, with an "On " badge and their place shown in every source.

Ask

• Cited answers in conversations. Follow-ups resume the same agent session instead of resending the history.

• Limit a conversation to the documents you tick.

• Cited figures are shown under the answer, full size on click.

For agents (MCP)

If the engine isn't running, the agent's call shows up as a request in the page's Notifications tab; Approve starts the engine.

Tracker

• Every call (from the page, an agent or the CLI) is recorded with its question, its results, and how long embedding, model loading, search and answering each took, plus what the GPU was doing. Updates live.

Settings

• Embedding model (any Ollama model; reembed rebuilds every vector), answering agent and model, figure reading on/off and its model.

Tech stack

• Node.js 24, plain ES modules, no framework

• node:sqlite (built into Node): FTS5 full-text search, BM25 ranking, vectors stored as BLOBs

• Ollama with embeddinggemma-2:440m for text and image embeddings, in one shared space

• Claude Code (headless) and Google Antigravity CLI as answering agents; Claude Haiku as the figure reader

• pdf.js (pdfjs-dist) and @napi-rs/canvas, the only two runtime dependencies

• MCP server written by hand: JSON-RPC 2.0 over stdio

• Plugin page in vanilla HTML/CSS/JS

By the numbers

Getting started

Requirements

• Node.js 24 or newer (for node:sqlite)

• Ollama with the embedding model: ollama pull embeddinggemma-2:440m

• For answers and figure reading: Claude Code logged in, or the Antigravity CLI (agy)

Install and test

npm install
npm test

Command line

# --data-dir is required: you decide where the library lives
npm run rag -- --data-dir ./library ingest report.pdf notes.docx
npm run rag -- --data-dir ./library search "what was the Q3 revenue?"
npm run rag -- --data-dir ./library ask "summarise the findings" --agent claude
npm run rag -- --data-dir ./library list
npm run rag -- --data-dir ./library serve   # the engine on 127.0.0.1:7780, for the page and MCP
npm run rag -- --help          # every command

As a ter-manager plugin

npm run rag -- plugin-setup     # once: tells the page where the engine is

Then register the plugin/ folder in ter-manager. (ter-manager is not public yet; see Runs inside ter-manager below.) The page starts and stops the engine (on 127.0.0.1:7780) itself.

For Claude Code (MCP)

claude mcp add --scope user ragx -- node "<path to this repo>/engine/mcp.js"

Project layout

engine/
  cli.js              command-line tool
  mcp.js              MCP server for coding agents
  lib/
    extract/          PDF, DOCX (own ZIP + XML reader), Markdown, text, images, figure finding
    chunk.js          heading-bounded chunking
    embed.js          Ollama embeddings, model read from /api/show
    db.js, store.js   SQLite schema, migrations, all SQL in one place
    vectors.js        in-memory exact vector search
    search.js         hybrid search with reciprocal rank fusion
    answer.js         cited answers and conversations
    agents/           headless Claude Code and Antigravity, session pool
    reader.js         figure reading with Claude Haiku
    server.js         loopback HTTP server for the page
    tracker.js        call and GPU tracking
    notex.js, place.js  File Fabric canvases from NoteX
plugin/               the ter-manager page
test/                 node:test suites with fake Ollama and fake agents

Runs inside ter-manager

ter-manager is my own terminal and workspace manager that hosts plugins like this one; it is not public yet. Without it, everything still works from the command line: start the engine with serve and use the CLI or the MCP server.

RAGX is a ter-manager plugin. Its page (plugin/) opens in ter-manager's sidebar as RAGX — Ask your files, and ter-manager gives it a data folder of its own. The page starts and stops the engine on 127.0.0.1:7780 itself. It talks to the engine through ter-manager's plugin protocol, and the engine accepts requests only from that page. The command line and the MCP server use the same engine, so the page, the terminal and AI agents all see the same data.

GitX ready

This repository is set up for the GitX workflow, so any AI coding agent that opens it works the same disciplined way:

• AGENTS.md holds the instructions once; CLAUDE.md and GEMINI.md import it, so Claude Code and Google Antigravity both follow it.

• The gitx-workflow skill ships in .claude/skills/ and .agents/skills/, and a hook in .claude/settings.json checks the workflow after every edit and at the end of each turn, when GitX is installed on the machine (without it, the hook stays silent).

• Agents catch up on recorded decisions before changing anything, record new decisions, rejected alternatives and costs as they happen, cite them in code comments by id, and commit with GitX trailers (GitX-Builds-On, GitX-Thoughts, …).

• Each commit message carries its GitX trailers, so the reasoning behind every change travels with the code; the full decision record stays private in .gitx/.

How it was built

Every design decision, rejected alternative and accepted cost is recorded with GitX, my own decision-record workflow, while the work happens. The ids you see in code comments (for example t-c6c48895e7 beside the hybrid search) point to those records. Each commit message explains why the change was made, not only what changed. Run git log to follow the whole design.

Related projects

• NoteX turns File Fabric / CanvasX canvases into documents RAGX can search, and lets agents write on canvases.

• CanvasX is the infinite canvas app itself.

License

Copyright (C) 2026 Paveen Pratheek. RAGX is free software under the GNU Affero General Public License v3 or later. See LICENSE and NOTICE. The name "RAGX" is not licensed for use by modified versions.