# 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](https://bun.sh) runtime
- [Ollama](https://ollama.com) running locally with embedding model (auto-pulled if missing)

### Minimum hardware

| Component | Requirement |
|-----------|-------------|
| RAM | 4 GB (8 GB for larger doc sets) |
| CPU | Any x86-64 or ARM64, 2+ cores |
| GPU | Optional. Any NVIDIA GPU with 2+ GB VRAM. CPU-only fallback is functional but slower |
| Disk | 100 MB for index (scales with doc count) |

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

## Install

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

Add shell alias:

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

## Quick start

```bash
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

| Command | Description |
|---------|-------------|
| `rag init` | Create .rag/ config, mcp.json, .gitignore |
| `rag index` | Chunk files, embed via Ollama, store in LanceDB |
| `rag serve` | Start MCP server (STDIO) for current .rag/ scope |
| `rag graph build` | Build knowledge graph from code and docs |
| `rag mcp <tool>` | One-shot CLI proxy for MCP tools |
| `rag info` | Show index statistics |

### rag mcp tools

| Tool | Usage | Description |
|------|-------|-------------|
| `search` | `rag mcp search "query" [--chunks N] [--limit N]` | Semantic search |
| `graph` | `rag mcp graph "topic" [--signature] [--limit N]` | Knowledge graph query |
| `get-document` | `rag mcp get-document <path>` | Read file content |
| `list-documents` | `rag mcp list-documents` | List indexed files |
| `config` | `rag mcp config` | Print opencode.json snippet |

## 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`:

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

The MCP server exposes 8 tools:

| Tool | Purpose |
|------|---------|
| `search` | Vector search |
| `graph_find` | Search graph nodes |
| `graph_neighbors` | Node connections |
| `graph_god_refs` | Core abstractions |
| `graph_path` | Shortest path |
| `graph_communities` | List communities |
| `list_documents` | List indexed files |
| `get_document` | Read file content |

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

## Architecture

```mermaid
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:

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

**Subcommands** — focused queries when you know what you need:

| Subcommand | Description |
|------------|-------------|
| `rag mcp graph god-refs [--limit N]` | Most connected core abstractions |
| `rag mcp graph communities` | List all directory-based communities |
| `rag mcp graph community <id>` | Show all references in a community |
| `rag mcp graph surprises [--limit N]` | Cross-community surprising connections |
| `rag mcp graph cycles` | Detect circular imports |
| `rag mcp graph neighbors <node>` | Connections for a node |
| `rag mcp graph path <from> <to>` | Shortest path between two nodes |
| `rag mcp graph list` | Reference and edge counts |

**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`:

```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