.vera

A different approach to RAG.

VERA stands for Vector-Embedded Retrieval Archive. A .vera file is a portable embedded vector database: a self-contained SQLite file containing ready-made text chunks, embeddings, a keyword index, JSON metadata, and optional opaque attachments. Move it, share it, or search it locally without a retrieval service.

The unique core is vera-doc — an embeddable Python library that stores and searches .vera archives. The VERA desktop app is a polished product built on that same foundation. The CLI and MCP server give AI agents and applications the same citation-ready retrieval layer.

Download VERA for Windows · pip install vera-doc to embed it · Read the documentation

Try it in five minutes

Converting and searching documents is fully local and needs no account or API key. You only connect a model provider when you want AI answers.

1. Install VERA. Download the VERA Setup installer from the latest Windows release and run it.
2. Convert your documents.
   • One PDF — open Convert PDF, choose Single PDF, pick a PDF, and select Convert. VERA writes a portable .vera archive beside it.
   • Entire library — choose PDF Directory to batch-convert a folder of PDFs, then use File > Open Folder to activate it. On your first Search or Ask, VERA shows Build library index? — select Build index to make the library fast. The footer reports completed files, total files, the current archive, and indexed chunks as it runs.
3. Connect a model. Go to File > LLM Providers, select a provider, paste your API Key, select Save Key, then Save & Close. Keys are stored encrypted on your machine. Local Ollama and LM Studio servers work too — no key needed.
4. Search. Open Search and query your documents. Hybrid retrieval (semantic + keyword) works entirely offline.
5. Ask and verify. Ask a question, then select a citation to see the highlighted supporting text in the source document.

The desktop app converts with local hashing embeddings; the model provider is only used for Ask responses. Use the CLI when you need a Sentence Transformers embedding model or explicit OCR control. For the complete walkthrough and troubleshooting, see Run the desktop app. Long library inspections report per-archive progress in the same footer used for conversion and indexing.

How it works

During conversion, vera-ingest extracts native PDF text, selectively OCRs image-based pages, and preserves headings, figures, and page coordinates. vera-doc then stores the chunks, embeddings, and keyword index in one validated .vera file. The desktop app, CLI, and MCP server all search that same archive:

At search time, hybrid retrieval in vera-doc fuses semantic and keyword rankings and returns chunks with their source file, page range, and heading path — grounded context for a person or an LLM, with no retrieval service required:

On a 1,038-page stormwater manual (2,442 chunks), hybrid search hits 9/10 real-world regulatory queries at MRR 0.900 — tracked continuously with vera eval.

What’s unique: how VERA is built

The distinctive idea is the portable .vera archive and the vera-doc engine that reads and writes it. The desktop app is a flagship product built on that same stack — not the definition of VERA.

Package	Role
vera-doc	Embeddable storage and search (import vera)
vera-ingest	PDF extraction, OCR, chunking, and conversion into .vera
vera-cli / vera-mcp	Shell and agent frontends
vera-app	Desktop product — a full implementation of the stack

vera-ingest ─┐
vera-cli ─────┼──> vera-doc
vera-app ─────┤
vera-mcp ─────┘

Who installs what

• End users → the desktop app
• Other apps with ready-made chunks → vera-doc only
• PDF pipelines → vera-doc + vera-ingest
• Agents and scripts → CLI / MCP

See Contributing and architecture and the package overview for boundaries and dependency rules.

What VERA gives you

• Portable document archives — each .vera file is self-contained; copy it anywhere and it stays searchable.
• Grounded answers — follow citations to the page, heading, and highlighted source text.
• Libraries that stay fast — a persistent local index makes searching hundreds or even thousands of documents possible; update it as documents change.
• Source-first review — inspect pages and figures, validate archives, and export the original PDF back out at any time.

Build on VERA

Use VERA as a library

Applications with ready-made chunks can use vera-doc directly without installing PDF/OCR dependencies:

python -m pip install "vera-doc>=0.2.2"

from vera import ChunkRecord, VeraDocument

with VeraDocument.create("knowledge.vera") as document:
    document.add([
        ChunkRecord(
            id="chunk-1",
            text="The minimum pipe diameter is 12 inches.",
            metadata={"source": "manual.pdf", "page": 42},
        )
    ])

with VeraDocument.open("knowledge.vera") as document:
    results = document.search(text="minimum pipe size", top_k=5)

Archives record whether stored embeddings are L2-normalized, unnormalized, or unknown. Custom vector pipelines can set embedding_normalization at creation; vera-doc validates vectors when the archive declares L2 normalization.

Convert sources

PDF extraction and chunking live in the separate vera-ingest package and are composed by vera convert:

python -m pip install "vera-cli>=0.2.2"

# Convert a PDF to a portable retrieval archive.
vera convert input.pdf output.vera

# Build a persistent local index for a document library.
vera index build ./library --recursive

# Return grounded results for an application or agent.
vera search ./library "What are the detention requirements?" --top-k 5 --json

CLI, MCP, and Agent Skill

The default hybrid search combines semantic and keyword retrieval. Every result includes its source filename, page range, and heading path. Add --context-chunks, --figures, or --regions when the agent needs nearby text, figure metadata, or page coordinates.

• CLI quick start and recipes
• CLI reference
• Connect an MCP client
• Install the VERA Agent Skill
• Use the Python API
• Agent quick reference
• VERA Agent Skill package (SKILL.md)
• VERA Agent Skill CLI reference

Documentation

Preview the documentation locally with:

uv run --extra docs mkdocs serve

• Desktop app guide
• Convert documents
• Search documents
• Search and index document libraries
• Work with figures and highlight regions
• Troubleshooting
• Current VERA 0.2 format specification
• Legacy VERA 0.1 format specification
• Contributing and architecture

Status and support

VERA is an experimental pre-1.0 project. The desktop installer is available from GitHub Releases and currently targets Windows. The .vera schema and format may change before a stable release.

VERA is licensed under Apache-2.0.