What is VelociRAG AGENTS.md?

Project instructions describing VelociRAG, a Python tool that finds relevant information in documents for AI agents. It explains the project’s structure, search approach, command-line tool, tests, and available connection methods.

Use it when working on VelociRAG’s Python modules, document search, command-line interface, tests, or agent connections.

It gives a coding agent the context needed to understand the repository before making changes.

How HaseebKhalid1507/VelociRAG configures Codex and OpenCode

Reuse

Borrowing it

Nothing to install: this file belongs to HaseebKhalid1507/VelociRAG. Take a copy, put it at the same path in your own repository, and replace the rules that are about this project with yours.

Copy the file

curl -O https://raw.githubusercontent.com/HaseebKhalid1507/VelociRAG/main/AGENTS.md

Clone the repo

git clone --depth 1 https://github.com/HaseebKhalid1507/VelociRAG

Made for: Codex, OpenCode.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/instructions/haseebkhalid1507/velocirag/agents-md.svg)](https://agentmods.dev/instructions/haseebkhalid1507/velocirag/agents-md)

Your own site

<a href="https://agentmods.dev/instructions/haseebkhalid1507/velocirag/agents-md"><img src="https://agentmods.dev/badge/instructions/haseebkhalid1507/velocirag/agents-md.svg" alt="Measured on agentmods" height="20"></a>

Per session 2,908 This file is loaded in full into every session.

When invoked 2,908 The same file — it is already loaded in full.

Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5.1	$0.02908	$0.02908
Opus 5	$0.01454	$0.01454
Sonnet 5	$0.00582	$0.00582
Haiku 4.5	$0.00291	$0.00291

Measured 7d ago against content hash ba7fd9f62cea, method: parsed. Prices are Anthropic first-party input rates as of 2026-09-07, from the pricing page.

Security

Grade A, and why

VelociRAG AGENTS.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 7d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

AGENTS.md · 229 lines

How it starts

The opening of the file, as written. The whole thing — 229 lines — stays where its author put it; the contents beside it link to each section on GitHub.

AGENTS.md — VelociRAG for AI Coding Agents

Machine-readable project context for AI coding assistants (Claude Code, Cursor, Copilot, etc.)

What Is This?

VelociRAG is lightning-fast RAG for AI agents. Pure retrieval engine powered by ONNX Runtime with 4-layer fusion, 3ms warm embeddings, MCP server, and Unix socket daemon.

Language: Python 3.10+
Backend: ONNX Runtime (no PyTorch)
Source: src/velocirag/ (18 modules, ~12K lines)
Tests: tests/ (18 test files)
CLI: velocirag (click-based)
License: MIT

Architecture

markdown files → chunk → embed (ONNX) → store (SQLite + FAISS)
                                            ↓
                                      4-layer search:
                                        vector (FAISS cosine, 384d MiniLM-L6-v2)
                                      + keyword (BM25 via SQLite FTS5)
                                      + graph (knowledge graph traversal)
                                      + metadata (structured SQL filters)
                                            ↓
                                      RRF fusion → cross-encoder rerank → results

Three ways to query:

MCP server (velocirag mcp) — for AI agents via Model Context Protocol
Daemon (velocirag serve) — warm engine over Unix socket for CLI users
Direct (velocirag search) — cold search, no daemon needed

Module Map

Module	Lines	Purpose
`cli.py`	1595	Click CLI — index, search, serve, stop, status, mcp, health, query, reindex. Cascading delete orchestration on file cleanup.
`analyzers.py`	1568	7 graph analyzers + FAISS semantic (128-token truncation, skip <50 char docs) + sampled centrality.
`pipeline.py`	1275	10-stage graph build. Incremental updates with file-centric provenance. `final_nodes`/`final_edges` in all return paths.
`store.py`	1197	Vector storage — SQLite + FAISS + FTS5. Batched rebuild. Cascading deletes with conn passthrough. Empty FAISS persistence.
`graph.py`	1116	Knowledge graph — Node/Edge models, GraphStore (SQLite), GraphQuerier. `remove_by_source_file()` with orphan pruning.
`unified.py`	901	4-layer fusion search — vector + keyword + metadata + graph → RRF. Filename cache. Exact-match promotion.
`metadata.py`	744	Metadata store — frontmatter, tags, cross-refs, usage tracking. `remove_document()` with orphan tag pruning.
`searcher.py`	688	High-level search — query variants, batch FAISS, RRF fusion, consistency validation
`embedder.py`	541	ONNX Runtime embeddings (all-MiniLM-L6-v2, 384d). 3ms warm, 184ms cold.
`mcp_server.py`	499	FastMCP server — 5 tools. Thread-safe init, `threading.Event`.
`daemon.py`	462	Unix socket search daemon — warm engine, bounded queue, auto-detected by CLI
`tracker.py`	305	Usage tracking — search hits, reads, access patterns
`reranker.py`	235	Cross-encoder reranking (TinyBERT via ONNX). Lazy init.
`variants.py`	217	Query variant generation + acronym registry + question rewrite
`chunker.py`	177	Markdown chunking by headers with parent context preservation
`frontmatter.py`	172	YAML frontmatter parser, tag extraction, wiki-link extraction
`rrf.py`	144	Reciprocal Rank Fusion — shallow copy in hot path

Read the full file on GitHub · 229 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

7d ago First seen · 229 lines · 2,908 tokens per session scan A ba7fd9f62cea

Subscribe to this mod's changes

VelociRAG AGENTS.md is an instructions file published in the GitHub repository HaseebKhalid1507/VelociRAG (11 stars, last pushed 5mo ago), licensed MIT. It adds 2,908 tokens to every session, about $0.0145 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Data and AI LLM RAG and vectors ai-agents bm25 faiss knowledge-graph mcp

codex AGENTS.md

AGENTS.md instructions for openai/codex, covering rust/codex-rs, the codex-core crate, code review rules, crate api surface and model visible context.

openai/codex · 5,182 tokens

vscode buildNext.instructions.md

Working notes and architecture documentation for the new esbuild-based build system in build/next. Use when making changes to the new build pipeline (transpile/bundle commands, NLS plugin, source-map handling, resource copying, or self-hosting watch tasks).

microsoft/vscode · 6,785 tokens

VelociRAG: Instructions file for Codex