rag

rag is a CLI tool and MCP server that turns codebases and documentation into a searchable, queryable knowledge base with vector search, RAG, and a structural knowledge graph.

Prerequisites

• Bun runtime
• Ollama running locally with embedding model (auto-pulled if missing)

Minimum hardware

Indexing 5000 chunks: ~25s on RTX 3060, ~3min on CPU-only.

Install

git clone https://github.com/FrameMuse/llm-rag.git
cd llm-rag
bun install

Add shell alias:

alias rag='bun /path/to/llm-rag/scripts/cli.ts'

Quick start

cd my-project
rag init              # create .rag/ project scope
rag index             # chunk, embed, index all files
rag mcp search "..."  # search indexed content
rag mcp graph "..."   # query knowledge graph
rag serve             # start MCP server

Commands

rag mcp tools

Project scope (.rag/)

project/
├── .rag/
│   ├── config.json       # { name, embedModel, ragModel, pattern, chunks, temperature }
│   ├── mcp.json          # MCP config snippet for opencode.json
│   ├── .gitignore        # *
│   ├── data/
│   │   ├── lancedb/      # Vector index (generated by rag index)
│   │   └── graph.json    # Knowledge graph (generated by rag index)
├── *.md
├── src/
└── ...

Each project keeps its index and graph local. rag discovers .rag/ by walking up from current directory (like git).

MCP integration

Register in opencode.json:

{
  "mcp": {
    "my-project": {
      "type": "local",
      "command": ["rag", "serve"],
      "cwd": "/path/to/project",
      "enabled": true
    }
  }
}

The MCP server exposes 8 tools:

Run rag mcp config from project directory to print the snippet with cwd pre-filled.

Architecture

flowchart LR
  MD[.md files] --> Chunker
  MD2[.ts/.js files] --> AST
  AST -->|declarations| Graph
  MD -->|headings + links| Graph
  Chunker -->|heading split| Chunks
  Chunks -->|Ollama embed| Vectors
  Vectors -->|store| LanceDB
  Query -->|embed| LanceDB
  LanceDB -->|search| Results
  Question -->|embed + search| Context
  Context -->|Ollama chat| Answer
  Graph -->|structural context| Answer

• Vector RAG: chunks embedded → vector search → top K → LLM synthesis
• Knowledge graph: TS/JS AST and MD headings/links → nodes + edges → structural queries

Knowledge graph

The knowledge graph extracts structural relationships from TypeScript, JavaScript, and Markdown files:

• TS/JS: functions, classes, interfaces, types, enums, imports, extends, class members
• MD: headings, frontmatter titles, cross-document links

Two-tier design

Free-form — shows everything the graph knows about a topic in one report:

rag mcp graph "render"
→ Matching references + top match detail + connections + community + god rank + surprises

Subcommands — focused queries when you know what you need:

Flags:

• --signature — show declaration signatures (e.g., function render(ctx: CanvasCtx): void)
• --limit N — max results to show (default 10)
• --dir in|out|both — direction for neighbors (default both)
• --type <edgeType> — filter edges by type

Built automatically at the end of each rag index. Incrementally updated during --watch mode.

Vision (image captioning)

Images are captioned via qwen3-vl during index phase 2 (text first, then images in parallel with 4 workers). The caption text is embedded and stored alongside text chunks, making images searchable by description.

Supported: .png .jpg .jpeg .gif .webp .svg (SVG via sharp).

Requires qwen3-vl pulled in Ollama.

Configuration

.rag/config.json:

{
  "name": "my-project",
  "embedModel": "mxbai-embed-large",
  "ragModel": "llama3.2:3b",
  "visionModel": "qwen3-vl",
  "pattern": "",
  "chunks": 8,
  "temperature": 0.3
}

Models auto-pull if missing. --chunks overrides per query.

License

MIT