Quickstart

Default Setup
Embedded Setup

This walks the production path: PostgreSQL + pgvector + Neo4j with the default VectorCypher engine. For embedded options (SQLite + LanceDB), see Configuration.

Install Khora

uv init khora-quickstart 
cd khora-quickstart
uv add khora

The Khora library requires Python version 3.13+

Setup databases

As Khora is meant to be used as a library, it has no built-in server and is made to work with existing databases.For local development, the Khora repo ships a compose.yaml that get’s you up and running with our recommended stack: Postgres (with pgvector) and Neo4j

git clone https://github.com/DeytaHQ/khora
cd khora
make dev

Then export connection URLs via environment variables in .env

KHORA_DATABASE_URL=postgresql://khora:khora@localhost:5434/khora
KHORA_NEO4J_URL=bolt://neo4j:pleaseletmein@localhost:7688
OPENAI_API_KEY=sk-...

Run migrations

Khora ships its schema as Alembic migrations. Run them once per database:

uv run alembic upgrade head

Or instantiate Khora(..., run_migrations=True) to apply on connect under an advisory lock, useful for single-process apps and tests.

Store a memory

import asyncio
from khora import Khora

async def main() -> None:
    async with Khora() as kb:  # reads KHORA_DATABASE_URL / KHORA_NEO4J_URL
        ns = await kb.create_namespace()
        await kb.remember(
            "Marie Curie won the Nobel Prize in Physics in 1903.",
            namespace=ns.namespace_id,
            entity_types=["PERSON", "ORGANIZATION", "CONCEPT", "LOCATION", "EVENT"],
            relationship_types=["RELATES_TO", "PART_OF", "MENTIONS"],
        )
        result = await kb.recall(
            "What did Curie win?",
            namespace=ns.namespace_id,
        )
        for chunk in result.chunks:
            print(chunk.content, chunk.score)

asyncio.run(main())

remember() runs the 3-phase ingestion pipeline (stage → enrich → expand). recall() returns a RecallResult projection with chunks (typed RecallChunk), entities, relationships, and documents (deduplicated source documents). Build prompt context by iterating result.chunks. Each carries .content, .score, .id, and .document_id.

Batch ingestion (optional)

For higher throughput, stage documents and let a background processor pick them up:

async with Khora() as kb:
    kb.start_pending_processor()   # opt-in; write-path services only
    handle = await kb.submit_batch(
        [{"content": "doc 1"}, {"content": "doc 2"}],
        on_result=lambda completed, total, result: print(result),
        namespace=ns.namespace_id,
        entity_types=["PERSON", "ORGANIZATION", "CONCEPT", "LOCATION", "EVENT"],
        relationship_types=["RELATES_TO", "PART_OF", "MENTIONS"],
    )
    await handle.wait()

The processor is opt-in. Read-only services don’t need it.

This walks the embedded path: SQLite + LanceDB, in-process, no external services. Use it for demos and evaluation. For the scale ceiling and known gaps, see Configuration.

Install Khora

uv init khora-quickstart 
cd khora-quickstart
uv add khora[embedded] python-dotenv

The embedded extra pulls in aiosqlite, lancedb, and pyarrow. python-dotenv is included so the script can load .env itself (more on that in step 3). Requires Python 3.13+.

Configure storage

Point Khora at the embedded backend via .env:

KHORA_STORAGE_BACKEND=sqlite_lance
KHORA_STORAGE_SQLITE_LANCE_DB_PATH=./khora.db
OPENAI_API_KEY=sk-...

The LanceDB directory defaults to a sibling .lance folder next to the SQLite file. Override with KHORA_STORAGE_SQLITE_LANCE_LANCE_PATH if you want vectors on different storage.

Store a memory

Two things to know before the snippet. First, uv run does not auto-load .env, and Khora’s settings class does not point at one either, so the script calls load_dotenv() explicitly. Second, Khora() defaults to run_migrations=False. Pass run_migrations=True so connect builds the SQLite schema on first run.

import asyncio
from dotenv import load_dotenv
from khora import Khora

load_dotenv()

async def main() -> None:
    async with Khora(run_migrations=True) as kb:
        ns = await kb.create_namespace()
        await kb.remember(
            "Marie Curie won the Nobel Prize in Physics in 1903.",
            namespace=ns.namespace_id,
            entity_types=["PERSON", "ORGANIZATION", "CONCEPT", "LOCATION", "EVENT"],
            relationship_types=["RELATES_TO", "PART_OF", "MENTIONS"],
        )
        result = await kb.recall(
            "What did Curie win?",
            namespace=ns.namespace_id,
        )
        for chunk in result.chunks:
            print(chunk.content, chunk.score)

asyncio.run(main())

Run it with uv run main.py. The remember() / recall() surface is identical to the Postgres + Neo4j stack. Switching backends later is a config change, not a code change.If you’d rather not add python-dotenv, drop load_dotenv() and run uv run --env-file .env main.py instead.

Pre-fetch the reranker model. Reranking is on by default, so the first recall() that runs it downloads the cross-encoder BAAI/bge-reranker-v2-m3 from Hugging Face (a couple of gigabytes). Pre-fetch it so that first query doesn’t pay the download cost, using the hf CLI:

pip install -U "huggingface_hub"   # provides the hf CLI
hf auth login                      # optional: authenticated, rate-limit-free downloads
hf download BAAI/bge-reranker-v2-m3

Pin a different model with KHORA_QUERY_RERANKING_MODEL, or turn reranking off with KHORA_QUERY_ENABLE_RERANKING=false.

Next steps

Configuration

Every KHORA_* knob: storage, LLM, pipeline, query, telemetry.

VectorCypher

How the retrieval engine fuses vector, graph, and keyword search with query routing and RRF.

Getting started

Concepts

Operations

Experimental Features

Integrations

Reference

Examples

Next steps

Configuration

VectorCypher

​Next steps

Configuration

VectorCypher

Next steps