vela

Vela - Knowledge Explorer & Graph Builder

A high-performance, privacy-first knowledge graph builder for codebases, documentation, and technical content. Built in Go with pluggable LLM providers (local or remote) for graph extraction and analysis.

Why Vela?

• Privacy-First: Run entirely locally, no data sent to cloud by default
• Flexible LLM: Pluggable providers (Ollama, llama.cpp, Anthropic Claude, OpenAI GPT-4o)
• High Performance: Go-native AST parsing, graph construction, and clustering
• Beautiful TUI: Interactive Bubbletea UI with real-time extraction progress
• Microservice Mapping: Perfect for understanding multi-repo architectures
• Zero Token Waste: Use local 8B models for free graph extraction

Features

• Code Extraction: Tree-sitter AST parsing for 22 languages (Go, Python, TypeScript, Rust, Java, etc.)
• Doc Extraction: LLM-powered Named Entity Recognition & Relationship Extraction from markdown, PDFs, and comments
• Graph Building: Automatic construction of knowledge graph with gonum
• Community Detection: Leiden clustering (via graspologic Python wrapper) to find logical groupings
• Interactive TUI: Real-time progress tracking, estimated time, extraction percentage
• Multiple Outputs: graph.json (queryable), graph.html (interactive), GRAPH_REPORT.md (human-readable)
• Caching: SHA256-based incremental updates
• Pluggable LLMs: Use local models (Ollama, llama.cpp) or remote APIs (Claude, GPT-4o)

Quick Start

# Build Vela
go build -o vela ./cmd/vela

# Run the local PR quality gate
make verify

# Extract knowledge graph from a folder
./vela extract ./my-repo

# Query an extracted graph
vela search --graph "./examples/wallet-service/.vela/graph.json" "explain Transaction"
vela search --graph "./examples/wallet-service/.vela/graph.json" "who uses Transaction"
vela search --graph "./examples/api-service/.vela/graph.json" "impact of OrderStatusDto"
vela search --graph "./examples/mobile-app/.vela/graph.json" "who uses OrderListScreen"

# Start interactive TUI to monitor extraction
./vela extract ./my-repo --tui

# Configure LLM provider
VELA_LLM_PROVIDER=local ./vela extract ./my-repo
VELA_LLM_MODEL=llama2 ./vela extract ./my-repo
VELA_LLM_ENDPOINT=http://localhost:11434 ./vela extract ./my-repo

Installation

What Vela is for

Vela is the graph extraction and retrieval layer.

Use Vela when you want to:

• extract a graph from a repo or workspace
• query graph structure with MCP tools
• run Vela by itself without Ancora

Do not use Vela as your durable memory database. That is Ancora's job.

Install from source

git clone https://github.com/Syfra3/vela.git
cd vela
go build -o vela ./cmd/vela

# Optional: move it somewhere in PATH
sudo mv vela /usr/local/bin/

# Verify
vela --help

Local quality gate

Use the same gate locally that CI runs on pull requests:

make verify

Install repository-managed hooks to catch issues before push:

make hooks-install

Notes:

• make lint bootstraps the pinned golangci-lint version automatically.
• make verify uses gotestsum when available and falls back to go test -v.
• Vela intentionally scopes automated tests to ./cmd/... ./internal/... ./pkg/... because tests/fixtures/detect/** contains fixture files that are expected to break raw go test ./... analysis.

MCP usage

Vela now exposes a real stdio MCP server.

# Start Vela as an MCP server over stdio
vela serve

That command is for MCP clients. It does not print a normal terminal UI.

If you want the old HTTP server for debugging or legacy use:

vela serve --http --port 7700

Three simple ways to use Vela

1. Vela only

Use this if you only want graph extraction and graph retrieval.

# Build graph
vela extract ./my-repo

# Let an MCP client talk to Vela
vela serve

2. Ancora + Vela

Use this if you want:

• Ancora for long-term memory
• Vela for graph retrieval
• one primary MCP surface from Ancora

In this setup:

• Ancora stays the main MCP server
• Vela runs behind Ancora for vela_* graph tools
• memory writes still belong to Ancora

3. Local CLI only

Use this if you just want to generate and inspect graphs yourself.

vela extract ./my-repo
vela query "nodes"
vela path AuthService Database
vela explain AuthService

How To Use vela search

vela search is a structural graph query command over graph.json. It is not a free-text, grep-style, or bag-of-words search tool.

Use it when you already know the exact node label, file path, type, interface, DTO, or module you want to inspect.

If you do not know the exact node yet, use vela lookup <term> first.

vela lookup --graph "./examples/wallet-service/.vela/graph.json" "transaction"

Valid query forms:

• who uses X
• what uses X
• where is X used?
• what does X depend on
• dependencies of X
• impact of X
• what breaks if X changes?
• path A -> B
• path from A to B
• how does A reach B?
• explain X

Examples:

vela search --graph "./examples/wallet-service/.vela/graph.json" "explain Transaction"
vela search --graph "./examples/wallet-service/.vela/graph.json" "who uses Transaction"
vela search --graph "./examples/wallet-service/.vela/graph.json" "what does Transaction depend on"
vela search --graph "./examples/wallet-service/.vela/graph.json" "impact of MovementStatusDto"
vela search --graph "./examples/wallet-service/.vela/graph.json" "path TransactionController -> TransactionMapper"

Bad examples:

vela search --graph "./examples/wallet-service/.vela/graph.json" "movement status mobile app dto contract"
vela search --graph "./examples/wallet-service/.vela/graph.json" "billing"
vela search --graph "./examples/wallet-service/.vela/graph.json" "print the movement extract"

Those fail because search only accepts structural query forms. Broad feature requests need discovery first.

Feature Planning Workflow

For product prompts like "add movement status to the mobile app" or "change the card contract", do not call vela search with the whole feature description.

Use this workflow instead:

1. Discover the concrete repos, files, DTOs, types, mappers, controllers, or screens involved.
2. If the exact node is still unclear, run vela lookup <term> to get candidates.
3. Pick the most specific real node labels available in each graph.
4. Run vela search on those exact nodes.
5. Build the plan from producer, contract, consumer, and rollout risk.

Example workflow for a feature:

1. Find candidate nodes such as Transaction, TransactionMapper, MovementStatusDto, or MovementListScreen.
2. Then run structural queries like:

vela search --graph "./examples/wallet-service/.vela/graph.json" "explain Transaction"
vela search --graph "./examples/wallet-service/.vela/graph.json" "who uses Transaction"
vela search --graph "./examples/wallet-service/.vela/graph.json" "impact of MovementStatusDto"
vela search --graph "./examples/wallet-service/.vela/graph.json" "who uses MovementListScreen"

This tells you:

• where the data shape lives
• who maps it
• who consumes it
• what is affected by a contract change

Agent Rule Of Thumb

Agents should treat vela search as a graph-truth relationship tool.

• Do not pass bag-of-words or full feature prompts into vela search.
• Do not guess generic node names like movement or transaction unless the exact node is already known.
• For broad planning questions, discover exact node candidates first, then query the graph with those exact labels.

See docs/VELA_LOOKUP_AND_AMBIGUITY_SPEC.md for the proposed vela lookup discovery command and safe ambiguity handling rules.

Example MCP config

If you want to register Vela directly as its own MCP server:

Claude Code

Create ~/.claude/mcp/vela.json:

{
  "command": "vela",
  "args": ["serve"]
}

OpenCode

Add to ~/.config/opencode/mcp_settings.json:

{
  "mcpServers": {
    "vela": {
      "command": "vela",
      "args": ["serve"]
    }
  }
}

Which tool should I install?

• Install Ancora only if you want memory.
• Install Vela only if you want graph extraction and graph retrieval.
• Install both if you want memory + graph retrieval together.

Architecture

Hybrid Go + Python Design

Go Layer (90%):

• CLI/TUI (Bubbletea)
• File detection & traversal
• Tree-sitter AST parsing (via go-tree-sitter)
• Graph construction (via gonum/graph)
• Export to JSON/HTML/Obsidian
• LLM client management
• Progress tracking & worker pools

Python Layer (10%):

• Community detection (Leiden via graspologic when available, NetworkX modularity fallback otherwise)
• Specialized extractors (if needed)
• Runs as subprocess, called only when necessary

Install the baseline clustering dependency explicitly if you want community detection to run reliably across Python versions:

python3 -m venv .venv
.venv/bin/pip install -r requirements-clustering.txt

That installs the NetworkX fallback backend used by scripts/leiden.py when Leiden is unavailable.

If you specifically want the Leiden backend, install graspologic into that same virtualenv when it supports your Python version:

.venv/bin/pip install -r requirements-clustering-leiden.txt

Pluggable LLM Interface

type LLMProvider interface {
    ExtractGraph(ctx context.Context, text string) (Nodes, Edges, error)
    Health(ctx context.Context) error
}

Providers:

• Local: Ollama or llama.cpp (0 tokens, 0 cost)
• Remote: Anthropic Claude (flexible, powerful)
• Remote: OpenAI GPT-4o (expensive, excellent quality)

Configuration

Create ~/.vela/config.yaml:

llm:
  provider: "local"  # local | anthropic | openai
  model: "llama2"    # depends on provider
  endpoint: "http://localhost:11434"  # for local providers
  api_key: ""        # for remote providers

extraction:
  code_languages: ["go", "python", "typescript", "rust"]
  include_docs: true
  include_images: true
  chunk_size: 8000   # tokens per chunk for large docs

ui:
  theme: "dark"
  show_progress: true

Repository Structure

vela/
├── cmd/vela/
│   └── main.go                 # CLI entry point
├── internal/
│   ├── detect/
│   │   └── detect.go           # File collection & filtering
│   ├── extract/
│   │   ├── extract.go          # Dispatcher
│   │   ├── code.go             # Tree-sitter AST extraction
│   │   ├── doc.go              # LLM-based doc extraction
│   │   ├── pdf.go              # PDF text extraction
│   │   └── schema.go           # Extraction result types
│   ├── graph/
│   │   ├── build.go            # Graph construction (gonum)
│   │   ├── cluster.go          # Community detection wrapper
│   │   ├── analyze.go          # God nodes + surprises
│   │   └── types.go            # Graph node/edge types
│   ├── llm/
│   │   ├── client.go           # LLM interface
│   │   ├── local.go            # Ollama/llama.cpp provider
│   │   ├── anthropic.go        # Claude provider
│   │   └── openai.go           # GPT-4o provider
│   ├── tui/
│   │   ├── app.go              # Bubbletea app
│   │   ├── progress.go         # Progress tracking component
│   │   └── styles.go           # UI styling
│   ├── report/
│   │   └── report.go           # GRAPH_REPORT.md generation
│   ├── export/
│   │   ├── json.go             # graph.json export
│   │   ├── html.go             # Interactive visualization
│   │   └── obsidian.go         # Obsidian vault export
│   ├── cache/
│   │   └── cache.go            # SHA256-based caching
│   └── security/
│       └── security.go         # Input validation
├── pkg/
│   └── types/
│       └── types.go            # Shared types
├── tests/
│   └── fixtures/               # Test data
├── go.mod
├── go.sum
├── LICENSE
└── README.md

License

MIT