Open-source multi-agent RAG over a knowledge graph. Instead of guessing answers from text similarity, Vedana agents navigate a typed graph step by step — issuing Cypher queries, running vector search, verifying sources, and assembling answers from real data.

Quickstart · Documentation · Concepts · Discussions

Classic RAG works well for summarization and vague questions, but breaks the moment you need completeness, structure, or logic:

• "How many contracts expire this quarter?" — classic RAG guesses from top-K, not from the dataset.
• "All documents regulating category X" — top-K returns a sample. Missed items are invisible.
• "Which products in category X are regulated by which documents?" — that's a graph traversal, not a similarity match.

These failures are structural — better embeddings, larger context windows, and bigger top-K don't fix them.

Vedana takes a different path. It treats the LLM as an interpreter, not a source of truth: an explicit data model is loaded into a knowledge graph + vector store, and agents query it through tools (Cypher, vector search, document lookup). Every answer is traceable — you can see exactly which nodes, edges, and chunks contributed to it.

Read more: What is Vedana · Why Classic RAG Fails · Semantic RAG Overview.

1. Copy and fill the environment file:

   cp apps/vedana/.env.example apps/vedana/.env
   # edit apps/vedana/.env — at minimum, set OPENAI_API_KEY

2. Bring up the stack:

   docker-compose -f apps/vedana/docker-compose.yml up --build -d

3. Open the backoffice at http://localhost:3000 and ask your first question.

Full walkthrough: Quick Start. For development on Vedana itself (native Python with uv, infra in Docker), see Local Development.

vedana/
├── apps/
│   ├── vedana/              # Main Vedana deployment (Docker, Reflex backoffice, ETL)
│   └── jims-demo/           # Minimal JIMS demo (a CLI-style agent on the JIMS framework)
├── libs/
│   ├── jims-core/           # Thread/event/pipeline framework (the substrate Vedana runs on)
│   ├── jims-api/            # FastAPI HTTP API over JIMS threads
│   ├── jims-backoffice/     # Backoffice primitives for JIMS-based apps
│   ├── jims-telegram/       # Telegram adapter for JIMS
│   ├── jims-tui/            # Terminal UI for testing JIMS pipelines
│   ├── jims-widget/         # Embeddable chat widget for JIMS
│   ├── vedana-core/         # The RAG pipeline: data-model filtering, Cypher generation, vector search, answer synthesis
│   ├── vedana-backoffice/   # Reflex admin UI for Vedana (chat, ETL runner, metrics, prompt tuning)
│   └── vedana-etl/          # Datapipe-based incremental ETL: Grist → Memgraph + pgvector
├── docs/                    # Documentation — built and published to vedana.tech
└── pyproject.toml           # uv workspace root

The repository is a uv workspace. For a one-shot setup of all dependencies:

uv sync

For architecture in depth — see docs/architecture/overview.md.

JIMS — Just an Integrated Multiagent System. A framework for running conversational agents with persistent threads, typed events, and pluggable pipelines. Vedana itself is just one JIMS pipeline; apps/jims-demo is a minimal one.

Vedana Core — the Semantic RAG pipeline: receives a user message, optionally filters the data model, lets the LLM generate Cypher / vector-search tool calls, retrieves results, and synthesizes a sourced answer.

Vedana ETL — an incremental Datapipe pipeline that pulls the data model and the data itself from Grist and loads them into Memgraph (knowledge graph) and pgvector (embeddings).

Vedana Backoffice — a Reflex admin UI for running ETL, chatting with the assistant, viewing metrics, and tuning prompts.

• Python 3.12
• PostgreSQL with the pgvector extension
• Memgraph
• Grist (the default data-model/data source — ETL can be extended to other sources)
• An LLM provider — OpenAI, OpenRouter, or anything supported by LiteLLM

Note on pgvector: some hosted Postgres providers (Supabase, Neon, etc.) manage extensions on their own. Set CREATE_PGVECTOR_EXTENSION=false in .env to skip the CREATE EXTENSION step. See Configuration for the full env reference.

Browsable documentation lives at vedana.tech/docs and is built from the docs/ folder in this repository.

Highlights:

• Getting Started — Quick Start, Local Development, Configuration.
• Concepts — what Vedana is, why classic RAG fails, Semantic RAG overview, data model, playbook.
• Architecture — JIMS Core, Vedana Core, ETL, Backoffice, Storage Model, Observability.
• Data Model — anchors, attributes, links, queries, prompts.
• Data Ingestion — documents, structured data, FAQ, custom ETL.
• Guides — adding anchors / attributes / links / documents / custom tools, tuning embeddings, multi-tenancy.
• API Reference — HTTP, Widget, Telegram, Python, env-vars.
• Operations — Deployment, Monitoring, Troubleshooting, Costs, Security.
• Product — Use Cases, Comparison with classic RAG, Evaluation, Limitations, FAQ.

OpenTelemetry traces, Prometheus metrics, and optional Sentry integration are wired into every pipeline run. See Observability and Monitoring.

We welcome contributions — bug reports, feature requests, docs fixes, and code. Start here:

• CONTRIBUTING.md — dev setup, code style, commit conventions, PR process.
• Repository Structure — where things live and why.
• Code Style — ruff, mypy, formatting rules.
• Testing — running the test suite, integration tests, fixtures.
• Code of Conduct — Contributor Covenant v2.1.

Security issues: see SECURITY.md.

Vedana is distributed under the Apache License 2.0 — free for commercial and non-commercial use, including modification and redistribution, with attribution and a notice of changes.

Vedana stands on the shoulders of:

• Memgraph — the knowledge graph backend.
• pgvector — vector search inside Postgres.
• Grist — the spreadsheet-as-a-database that drives the data model and ingestion.
• Datapipe — the incremental-ETL engine behind vedana-etl.
• LiteLLM — uniform access to dozens of LLM providers.
• Reflex — the Python framework powering the backoffice.

Built by Epoch8.