CongraphRAG

CongraphRAG is a graph-based Retrieval-Augmented Generation (RAG) framework. It stores documents, entities and communities in an embedded graph database (congraphdb 0.2.1) and answers questions with one of six retrieval engines. Each engine is built from reusable operators: keyword search over the graph, personalised PageRank, weighted paths, Louvain communities, and a validator that checks answers against the graph. There are no embeddings.

Features

• Six engines: PathRAG, HippoRAG, LightRAG, MS-GraphRAG, RAPTOR and Think-on-Graph (ToG), behind one interface.
• Works without an LLM: ingest, index and retrieval run without one. Answers and extraction need one.
• Streaming that matches batch answers: query() and queryStream() retrieve once and use the same context.
• Graph validation: GraphValidator checks claims in an answer against the stored graph.
• Providers: OpenAI and OpenAI-compatible endpoints, Azure OpenAI, and Ollama.

Repository layout

congraph-rag/
├── src/
│   ├── core/           # Types, interfaces, shared text helpers, runtime config
│   ├── llm/            # OpenAI, Azure and Ollama clients
│   ├── storage/        # congraphdb storage (schema, writes, reads)
│   ├── operators/      # Retrieval building blocks and index builders
│   ├── engines/        # The six engines and their registry
│   ├── orchestrator/   # Source reading, chunking, ingest
│   ├── benchmark/      # Retrieval benchmark over the bundled datasets
│   ├── server/         # Fastify HTTP API
│   ├── dashboard/      # React prototype with mock data (not connected to the server)
│   └── cli/            # Command-line interface
├── docs/               # Architecture, engines, engine limits
└── scripts/            # Build helpers and the congraphdb limits repro

Documentation

• Architecture: pipeline, storage schema, community detection, server and CLI.
• Engines: what each engine does, its options, and whether it needs an LLM.
• congraphdb limits: engine bugs and limits that shaped the storage layer, with repro cases.
• Operators, Evaluation, Dashboard (prototype).

Prerequisites

• Node.js 20 or later
• npm 10 or later (the lock file is npm's)

congraphdb ships as a prebuilt native package from npm. No separate database install is needed.

Installation

npm install
npm run build   # tsup bundles the JavaScript into dist/, tsc writes the .d.ts files
npm test        # vitest

Configuration

Settings come from environment variables. The CLI and the server read the same ones. Neither accepts a storage path or an LLM endpoint from a request.

Variable	Default	Purpose
CONGRAPH_DB_PATH	./data/congraph.cgraph	Database file. --db on the CLI overrides it.
CONGRAPH_LLM_PROVIDER	(unset)	openai, azure or ollama. Unset means no LLM.
CONGRAPH_LLM_MODEL	(unset)	Model or deployment name. Required with a provider.
CONGRAPH_LLM_BASE_URL	(unset)	OpenAI-compatible base URL (OpenAI provider).
OPENAI_API_KEY	(unset)	Key for the OpenAI provider.
AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_VERSION	(unset)	Azure provider.
OLLAMA_HOST	http://localhost:11434	Ollama provider.
CONGRAPH_API_KEY	(unset)	Shared secret for the HTTP API, sent as X-API-Key. Without it, protected routes answer 503.
CONGRAPH_CORS_ORIGINS	(empty)	Comma-separated browser origins allowed by CORS.
CONGRAPH_HOST	127.0.0.1	Server bind address.
CONGRAPH_PORT	3000	Server port.
CONGRAPH_LOG_LEVEL	info	Library progress messages, written to stderr. debug, info, warn, error or silent.

Usage

Command line

# Store a document. Chunks are always stored; entities and relations need an LLM.
npx tsx src/cli/bin.ts ingest notes.md

# Build communities and summaries (needs an LLM). Add --tree for the RAPTOR tree.
npx tsx src/cli/bin.ts index --tree

# Ask a question with one engine.
npx tsx src/cli/bin.ts query "How are entity X and entity Y related?" --engine path

Run npx tsx src/cli/bin.ts --help for all options.

HTTP API

CONGRAPH_API_KEY=change-me npm run server:start

curl -X POST http://127.0.0.1:3000/query \
  -H 'X-API-Key: change-me' -H 'Content-Type: application/json' \
  -d '{"query": "Who painted the Mona Lisa?", "engine": "light", "mode": "hybrid"}'

POST /query takes query, engine (default path), stream, mode and level. GET /health needs no key.

Library

import { ConGraphDBStorage } from 'congraph-rag/storage';
import { createEngine } from 'congraph-rag/engines';
import { createLLM } from 'congraph-rag/llm';

const storage = new ConGraphDBStorage('./data/congraph.cgraph');
const llm = createLLM({ provider: 'openai', model: 'gpt-4o', apiKey: process.env.OPENAI_API_KEY });
const engine = createEngine('hippo', storage, llm);

const answer = await engine.query('What did Newton study?');
console.log(answer.content);
await storage.close();

Benchmark

src/benchmark runs the engines over the bundled datasets (Da Vinci, Newton, Tesla).

npx tsx src/benchmark/index.ts davinci        # one dataset
npx tsx src/benchmark/index.ts --all          # all three
BENCH_MODE=real npx tsx src/benchmark/index.ts davinci   # with an LLM configured

• Mock mode (default, no LLM): measures retrieval recall, the share of expected facts found in the retrieved context. Nothing is extracted, so the graph engines (path, hippo, light, graph) have no entities to start from and retrieve nothing. ToG is skipped. This checks the pipeline and what is retrievable without an LLM. It is not a measure of answer quality.
• Real mode (BENCH_MODE=real, LLM configured): also scores answers and the validator.

Expected facts are never written into the graph. A fact is found only if the engine retrieves the text that states it.

Status

Working and tested: ingest, index, the six engines, the CLI, the HTTP API, and the storage layer on congraphdb 0.2.1. The test suite passes (31 files, 193 tests). Real-LLM answer quality has not been measured.

Known gaps:

• The dashboard is a prototype with hard-coded data. See docs/DASHBOARD.md.
• The congraphdb engine bugs in docs/CONGRAPHDB_LIMITS.md are worked around, not fixed.
• The declaration build uses tsc (tsconfig.build.json). Consumers get .d.ts files per module, not one bundled file.

Roadmap

• Operator-based retrieval units (VDB, PPR, Louvain, weighted paths, validator)
• Six engines behind one registry, with a shared retrieve-then-answer base
• Native congraphdb storage with a single node and link schema
• Graph-based claim validation (GraphValidator)
• Retrieval benchmark over three datasets, without injected facts
• Incremental indexing for HippoRAG and RAPTOR, without full rebuilds
• Dynamic engine routing based on query intent
• Streaming operator pipeline with parallel retrieval
• Anthropic provider

---

Contributing

See CONTRIBUTING.md.

License and disclaimer

Licensed under the MIT License. See LICENSE. Read DISCLAIMER.md for the notice on AI-generated content.