Knowa – Open-Source LLM Context Optimizer

Knowa has released an open-source hybrid retrieval library and knowledge base server that reduces LLM context costs by 90-99% by indexing documents as vector chunks, full-text pages, and a named-entity graph, then extracting only relevant chunks per query. The tool, which ingests from local directories, Notion, and Confluence, aims to solve the problem of sending millions of tokens per request at high cost — a 1,000-page knowledge base can cost tens of thousands of dollars monthly at scale. Knowa's precision retrieval approach, which includes optional LLM entity enrichment for domain-specific terms, is positioned as critical for scaling AI from prototype to company-wide infrastructure without breaking budgets.

The naive approach to building AI-powered apps is to load your documents into the prompt and let the LLM figure it out. It works in demos. It breaks in production. A 1,000-page knowledge base is roughly 2–4 million tokens. At current API pricing, sending that on every request costs dollars per query. At 10,000 queries a day that is tens of thousands of dollars a month — for context that is 95% irrelevant to the question being asked. As AI usage scales across teams and products, this becomes the dominant cost line. Knowa's core job is to solve this. It indexes your documents once — as vector chunks, full-text pages, and a named-entity graph — then for each question extracts only the handful of chunks that are actually relevant, typically 1,000–3,000 tokens out of a large corpus. At scale that is a 90–99% reduction in context sent to the LLM, with no loss in answer quality. Every query response includes a measured token savings figure so you can track this in production. Savings are corpus-size dependent — see Understanding token savings understanding-token-savings for what to expect at different scales. This matters now and will matter much more as AI usage goes from prototype to product to company-wide infrastructure. Precision retrieval is not a nice-to-have — it is the difference between an AI feature that scales and one that breaks your budget. Knowa is a hybrid retrieval library and knowledge base server. It ingests documents from local directories, Notion, Confluence, and any custom source you connect — storing them as vector chunks and full-text pages in PostgreSQL, and as a named-entity knowledge graph in PostgreSQL default , Neo4j, or Kuzu. For each question it retrieves only the most relevant context across all three representations and returns it ready to inject into any LLM or AI pipeline you choose. The knowledge graph is built during indexing and gives retrieval a structural dimension that pure vector search misses — connecting people, products, organisations, and concepts across your entire document corpus so entity-centric questions "what teams work on X?", "which pages mention both Y and Z?" get precise, targeted answers. How the graph is populated depends on how much coverage you need: - spaCy NER default — runs locally at indexing time with zero API cost. Recognises standard entity types people, organisations, locations, dates, and more . You can swap the model to improve accuracy or target a specific domain: en core web trf transformer-based, better on ambiguous names , scispaCy models for scientific or biomedical text, or any spaCy-compatible model. - LLM entity enrichment opt-in — an additive second pass using any OpenAI-compatible model gpt-4o-mini, Qwen3, Kimi2, and others . The LLM extracts domain-specific entities that a general NER model misses: product features, internal codenames, technical standards, abstract concepts — anything with meaning in your organisation's language. Runs concurrently across pages to keep indexing fast at scale, and costs roughly $0.30 per 1,000 pages with gpt-4o-mini. - Python 3.11+ Docker https://docs.docker.com/get-docker/ for PostgreSQL - OpenAI API key docker compose up -d This starts a PostgreSQL 16 instance with pgvector pre-installed, exposed on localhost:5432 . Data is persisted in a Docker volume across restarts. python -m venv .venv source .venv/bin/activate Windows: .venv\Scripts\activate OR - if you have miniconda installed conda create -n knowa python=3.12 conda activate knowa pip install -r requirements.txt python -m spacy download en core web sm pip install -e . registers the knowa CLI command cp .env.example .env Edit .env and fill in the required values: | Variable | Required | Notes | |---|---|---| DATABASE URL | Yes | Pre-filled to match docker compose — no change needed | OPENAI API KEY | Yes | Your OpenAI API key | OPENAI MODEL | Yes | e.g. gpt-5.4 | API KEY | Yes | Any random secret — used to protect the REST API | NOTION API KEY | No | Required only for Notion sources | CONFLUENCE | No | All four vars required for Confluence sources | SPACY MODEL | No | NER model for graph extraction default: en core web sm | ENTITY LLM MODEL | No | Enable LLM entity enrichment, e.g. gpt-4o-mini see below | Generate a strong API key: python python3 -c "import secrets; print secrets.token urlsafe 32 " knowa index /path/to/docs --name "My Docs" Migrations run automatically on the first command. Supported file types: .md , .txt , .pdf , .docx knowa chat "What would you like to know?" uvicorn knowa.api.main:app --reload --port 8000 Open http://localhost:8000/admin/ui — search, browse sources, and trigger rebuilds from the browser. As a Python library — embed Knowa directly in your app. You own the LLM call; Knowa handles indexing, retrieval, and context formatting. Works with Anthropic, OpenAI, Gemini, local models, LangChain, LlamaIndex, or any other framework. As a REST API — run the FastAPI server and hit /query to get complete answers with citations from any language or tool, no Python required. As a CLI tool — use the knowa command to index directories and chat with your knowledge base directly from the terminal, no server or code required. Up to 90–99% token reduction at scale — three-path hybrid retrieval vector search, full-text search, property graph surgically extracts only what is relevant; every query reports measured token savings so you can track efficiency in production. See Understanding token savings understanding-token-savings for realistic expectations at different corpus sizes. Hierarchical chunking — documents are split into small child chunks for precise vector search, then expanded to larger parent chunks for full context — maximising relevance without losing surrounding information Pluggable embedders — OpenAIEmbedder default or SentenceTransformerEmbedder fully local, no API key needed at query time ; implement the Embedder protocol to add your own Multiple sources — Notion, Confluence Cloud, and local directories .md , .txt , .pdf , .docx Incremental sync — only re-processes files changed since the last run Zero LLM calls at index time by default — spaCy handles entity extraction; no OpenAI spend during indexing regardless of knowledge base size. For richer entity coverage, an optional LLM enrichment pass can be enabled see Graph entity extraction graph-entity-extraction Admin UI — per-source sync/rebuild controls, query interface, token savings tracking, and interactive entity graph visualization CLI — full index and chat management without running the server The token savings figure shown after each query measures how much of your indexed corpus Knowa avoided sending to the LLM: savings % = 1 − tokens retrieved by this query / all parent-chunk tokens in the DB This is a corpus-size-relative metric . With a small corpus, retrieval may cover most of it on every query — and savings will be near 0%. That is expected and correct; it is not a bug or a misconfiguration. By default Knowa retrieves the top 5 child chunks by vector similarity TOP K CHUNKS=5 , then expands each to its parent chunk ~2,048 tokens . That means roughly 10,000 tokens of context per query, regardless of corpus size. Savings only accumulate once your total indexed content significantly exceeds that window. The estimates below assume: Default settings — TOP K CHUNKS=5 , parent chunk size ~2,048 tokens Typical document sizes — wiki pages, Notion pages, Confluence pages: 500–3,000 words → 1–4 parent chunks each. Short README-style files under 500 words may produce a single chunk; long PDFs or DOCX files 5,000+ words may produce 5–15 chunks each. Mixed file types shift the breakpoints: a corpus of 10 long PDFs can behave like 50+ short markdown files in terms of total chunk count. | Corpus | Approx. parent chunks | Expected savings | |---|---|---| | 5 short docs | 5–10 | 0–10% — retrieval covers most of the corpus | | 20–30 substantial pages | 30–50 | 40–60% | | 100+ pages | 100–200 | 70–85% | | 500+ pages | 500+ | 85–95% | | Large wiki 1,000+ pages | 1,000+ | 90–99% | A 0% savings reading does not mean retrieval is broken or that Knowa is not helping. It means your corpus is small enough that the retrieval window covers essentially all of it — which is the correct behaviour. The answer quality benefit finding the right pages and synthesising a coherent answer is present at any corpus size. The savings badge becomes a useful production monitoring signal once your knowledge base grows large enough that retrieval is genuinely selective — typically 20–30 substantial documents or more. If you have a large corpus but still see low savings, consider reducing TOP K CHUNKS in your .env . The default of 5 is conservative; dropping to 3 roughly halves retrieved context and increases savings, at the cost of slightly lower recall on broad questions. The CLI connects directly to the database — no server needed. Index a directory — incremental by default, full rebuild on first run knowa index /path/to/docs knowa index /path/to/docs --name "Engineering Docs" attach a friendly label knowa index /path/to/docs --full force full rebuild knowa index /path/to/docs --workers 4 parallel indexing 4 threads See all indexed sources with page/chunk counts and labels knowa list Chat with the index knowa chat interactive REPL knowa chat "What is our refund policy?" single-shot knowa chat --source "Engineering Docs" scoped to one source knowa chat --debug show retrieval path before each answer knowa chat --no-index /path/to/docs bypass index, read docs directly Inspect graph backend entity/edge counts knowa debug Benchmark questions with and without index knowa bench questions.json Clear index for a source knowa clear /path/to/docs knowa clear --source-id <notion-workspace-id knowa clear --source-id company.atlassian.net/ENG knowa clear --all Supported file types: .md , .txt , .pdf , .docx To quickly populate the knowledge base for testing the graph visualization: python scripts/fetch sample docs.py --out /tmp/knowa sample docs knowa index /tmp/knowa sample docs --name "Knowa Sample Docs" This downloads ~20 Wikipedia articles AI companies and researchers and indexes them. python from knowa import KnowledgeBase Create once at app startup — reuse across requests kb = KnowledgeBase kb.index "/path/to/docs", label="Engineering Docs" Get formatted context ready to inject into any LLM context = kb.get context "What is our deployment process?" python import anthropic from knowa import KnowledgeBase kb = KnowledgeBase client = anthropic.Anthropic def answer question: str - str: context = kb.get context question message = client.messages.create model="claude-opus-4-7", max tokens=1024, system=f"Answer using only this context:\n\n{context}", messages= {"role": "user", "content": question} , return message.content 0 .text retrieve gives you structured results before synthesis — filter, rerank, or log them: python from knowa import KnowledgeBase, RetrievedChunk kb = KnowledgeBase chunks: list RetrievedChunk = kb.retrieve "What is our SLA?" for c in chunks: print f" {c.retrieval type} score={c.score:.3f} | {c.page title}" Filter by confidence, then format filtered = c for c in chunks if c.score = 0.3 or c.retrieval type == "fts" context = kb.format context filtered pip install "knowa st " python from knowa import KnowledgeBase from knowa.embedders.sentence transformers import SentenceTransformerEmbedder Set EMBEDDING DIMENSIONS=384 in .env before the first index run embedder = SentenceTransformerEmbedder "all-MiniLM-L6-v2" kb = KnowledgeBase embedder=embedder kb.index "/path/to/docs", full=True context = kb.get context "What is our refund policy?" no OpenAI calls kb.index "/docs/engineering", label="Engineering" kb.index "/docs/legal", label="Legal" eng context = kb.get context "deployment process", source id="Engineering" legal context = kb.get context "compliance requirements", source id="Legal" Manage history in your application and pass only the retrieved context to each turn: python from knowa import KnowledgeBase kb = KnowledgeBase history: list dict = def chat user message: str - str: context = kb.get context user message messages = history -10: + {"role": "user", "content": user message} response = your llm system=f"Answer using this context:\n\n{context}", messages=messages history.append {"role": "user", "content": user message} history.append {"role": "assistant", "content": response.text} return response.text Retrieval is synchronous. Wrap with asyncio.to thread to avoid blocking the event loop: python import asyncio from knowa import KnowledgeBase kb = KnowledgeBase async def handle request question: str, source: str | None = None - str: context = await asyncio.to thread kb.get context, question, source async with your async llm client as client: return await client.complete context, question python from functools import lru cache from fastapi import Depends, FastAPI from knowa import KnowledgeBase app = FastAPI @lru cache maxsize=1 def get kb - KnowledgeBase: return KnowledgeBase @app.post "/ask" async def ask question: str, source: str | None = None, kb: KnowledgeBase = Depends get kb : import asyncio chunks = await asyncio.to thread kb.retrieve, question, source context = kb.format context chunks answer = await your llm context, question return {"answer": answer, "citations": {"title": c.page title, "url": c.url} for c in chunks if c.page title } KnowledgeBase database url=None, embedder=None — database url falls back to DATABASE URL env var; embedder defaults to OpenAIEmbedder . The embedder must match what was used when the index was built. | Method | Returns | Description | |---|---|---| index path, label=None, full=False | dict | Index a local directory. Returns {"indexed": N, "deleted": N, "errors": N} . | retrieve question, source id=None | list RetrievedChunk | Hybrid retrieval — no LLM calls. | format context chunks | str | Format chunks into Title \n--- blocks for LLM injection. | get context question, source id=None | str | retrieve + format context + graph relationships in one call. | RetrievedChunk fields: content , score , page id , page title , source id , source type , url , retrieval type "vector" or "fts" . | Concern | Guidance | |---|---| Embedder reuse | Create one KnowledgeBase per process and reuse it. Re-creating per request is wasteful. | Dimension consistency | Set EMBEDDING DIMENSIONS before the first index call. Changing the embedder later requires a full rebuild — mixing dimensions returns wrong results silently. | Thread safety | KnowledgeBase is safe to call from multiple threads — the psycopg2 pool is thread-safe. | Async blocking | Use asyncio.to thread kb.retrieve, ... in async frameworks. | Context size | get context returns all retrieved chunks untruncated. For small context windows, filter by score and pass format context filtered . | Re-indexing | Call kb.index path on a schedule for directories that change. Each call runs incrementally. | Error handling | index returns {"errors": N} . Check this value and alert if non-zero. | curl -X POST "http://localhost:8000/query" \ -H "X-API-Key: <key " \ -H "Content-Type: application/json" \ -d '{"question": "What is our refund policy?", "response mode": "with citations"}' Response modes: answer only · with citations · full includes raw retrieved chunks Knowa builds a property graph from your documents by extracting named entities during indexing. Two mechanisms are available and can be used together. Runs entirely locally, zero API cost, no latency added. Recognises standard entity types: people, organisations, locations, dates, and 14 others from the OntoNotes scheme. SPACY MODEL=en core web sm default — fast, lightweight SPACY MODEL=en core web trf transformer-based, better accuracy on ambiguous names SPACY MODEL=en core sci lg scientific text pip install scispacy + model SPACY MODEL=en ner bc5cdr md biomedical pip install scispacy + model After changing the model, install it: python -m spacy download en core web trf or for scispaCy models follow https://allenai.github.io/scispacy/ An optional second pass that runs after spaCy and adds domain-specific entities spaCy misses — products, technologies, frameworks, abstract concepts, and any entity type relevant to your domain. Runs concurrently across pages configurable parallelism so it does not serialize indexing. Supports any OpenAI-compatible provider. Examples: gpt-4o-mini ~$0.30 per 1,000 pages ENTITY LLM MODEL=gpt-4o-mini ENTITY LLM API KEY=sk-... optional — falls back to OPENAI API KEY Qwen3 via Dashscope ENTITY LLM MODEL=qwen3-7b ENTITY LLM API KEY=sk-... ENTITY LLM BASE URL=https://dashscope.aliyuncs.com/compatible-mode/v1 Kimi2 Moonshot ENTITY LLM MODEL=moonshot-v1-8k ENTITY LLM API KEY=sk-... ENTITY LLM BASE URL=https://api.moonshot.cn/v1 Concurrency is controlled by ENTITY LLM CONCURRENCY default 5 . Leave ENTITY LLM MODEL blank to keep the default zero-LLM-at-index-time behaviour. Two-phase indexing: when you combine --workers with ENTITY LLM MODEL , the two phases run sequentially — Phase 1 OCR, chunking, embedding, spaCy completes across all pages first, then Phase 2 LLM enrichment runs concurrently at ENTITY LLM CONCURRENCY parallelism. The two concurrency settings are independent: --workers controls how many files are read and embedded at once; ENTITY LLM CONCURRENCY controls how many LLM API calls fire in the enrichment pass. | Domain | Recommended model | Install | What it adds over en core web sm | |---|---|---|---| | General wikis, internal docs, HR, support | en core web sm | built-in | — baseline | | Same domains, higher accuracy | en core web trf | python -m spacy download en core web trf | Transformer-based; better on ambiguous names and abbreviations | | Scientific papers, research reports | en core sci lg | pip install scispacy + model | Chemicals, genes, proteins, species, experimental methods | | Biomedical / clinical | en ner bc5cdr md | pip install scispacy + model | Diseases, drugs, adverse drug reactions BC5CDR corpus | | Legal case law, UK | en blackstone proto | pip install blackstone | Legal concepts, case references, court names — UK-focused, not actively maintained | | Finance, engineering, security | any of the above | — | General models catch orgs, people, dates well; domain-specific terms need LLM enrichment see below | Note:scispaCy models must be downloaded separately after pip install scispacy . See allenai.github.io/scispacy for the full model list and download URLs. spaCy extracts what it was trained on. LLM enrichment fills the gaps — domain-specific terms, internal jargon, and relationship types that no pre-trained NER model knows about. | Domain | spaCy alone | Add LLM enrichment when… | |---|---|---| General wikis / internal docs | Good — people, orgs, locations covered | You need product names, team names, internal codenames, or project-specific concepts indexed as graph nodes | Legal | Partial — parties, orgs, dates caught; clause types and regulatory citations missed | Almost always — contract clause types Indemnification, Force Majeure , party roles Licensor, Licensee , regulation references GDPR Art. 17, SOX §404 require LLM extraction | Finance | Partial — companies, dates, monetary values caught; financial instruments and risk terms missed | When indexing analyst reports, earnings calls, or contracts — extracts instruments CDO, SPAC , risk categories, regulatory filings 10-K, 8-K | Biomedical / clinical | Good with scispaCy — diseases, drugs, genes covered | When you need treatment protocols, trial phases, or mechanism-of-action relationships beyond standard NER types | Engineering / code docs | Weak — standard NER misses most technical entities | Almost always — APIs, services, error codes, config flags, version numbers, and dependency names are invisible to general NER models | Security / infosec | Weak — CVE IDs and threat actors are not standard NER types | Almost always — CVEs, attack techniques MITRE ATT&CK , threat actors, vulnerability classes, affected products | HR / people ops | Good — people and org names covered | When role titles, skill taxonomies, or org-structure concepts matter for graph traversal | Customer support | Partial — product names and people caught; issue categories and feature areas missed | When support tickets reference internal product areas, error messages, or workflow steps that aren't in any NER vocabulary | Rule of thumb: if the entities that matter most in your domain are not people, organisations, locations, or dates — add LLM enrichment. The cost is low gpt-4o-mini runs at roughly $0.30 per 1,000 pages and the graph coverage improvement is substantial for technical and domain-specific corpora. - Go to notion.so/my-integrations https://www.notion.so/my-integrations → New integration → give it a name → copy the Internal Integration Token starts with secret - Set NOTION API KEY=secret ... in your .env - In Notion, open each root page you want indexed → ⋯ → Connections → Add connection → select your integration . Sub-pages inherit the connection automatically. - Trigger an initial full index: curl -X POST "http://localhost:8000/admin/rebuild?full=true" -H "X-API-Key: <key " Sub-pages are indexed recursively. Container pages no body content, only child pages produce 0 chunks — their children are indexed normally. For a 5,000-page workspace the initial index takes 30–90 minutes depending on Notion API rate limits. - Create an Atlassian API token at id.atlassian.com/manage-profile/security/api-tokens https://id.atlassian.com/manage-profile/security/api-tokens - Find your space key in the Confluence URL: https://yourcompany.atlassian.net/wiki/spaces/ ENG /pages/... - Add to .env : CONFLUENCE BASE URL=https://yourcompany.atlassian.net CONFLUENCE USERNAME=you@yourcompany.com CONFLUENCE API TOKEN=<token from step 1 CONFLUENCE SPACE KEY=ENG - Trigger an initial full index: curl -X POST "http://localhost:8000/admin/rebuild?full=true" -H "X-API-Key: <key " All four vars must be set to enable the connector — leaving any blank disables it without error. Large spaces 1,000+ pages may take 10–30 minutes. Knowa is a single Docker container + PostgreSQL. docker build -t knowa . docker run -d --env-file .env -p 8000:8000 knowa docker logs -f knowa pgvector must be available. All major providers support it: | Provider | Notes | |---|---| AWS RDS / Aurora | Enable pgvector in Parameter Groups, then CREATE EXTENSION IF NOT EXISTS vector; | Google Cloud SQL | Enable the pgvector database flag, then CREATE EXTENSION IF NOT EXISTS vector; | Azure Database for PostgreSQL | Built-in extension — run CREATE EXTENSION IF NOT EXISTS vector; | Supabase | pgvector pre-installed; run CREATE EXTENSION IF NOT EXISTS vector; from the SQL editor | Neon | pgvector pre-installed; run CREATE EXTENSION IF NOT EXISTS vector; from the console | Render / Railway | Create a PostgreSQL service; connect via psql and run the extension command | After provisioning, set DATABASE URL in your environment. The app exposes port 8000 and reads all config from environment variables: | Provider | Approach | |---|---| AWS ECS / Fargate | Push to ECR, create a Fargate task, inject env vars via Secrets Manager | Google Cloud Run | Push to Artifact Registry, deploy as a Cloud Run service --port 8000 | Azure Container Apps | Push to ACR, deploy as a Container App, configure env vars in the portal | Render | Connect GitHub repo, set Runtime to Docker, set Port to 8000 | Railway | Connect GitHub repo or push a Docker image, add env vars in the dashboard | Fly.io | fly launch auto-detects the Dockerfile; set secrets with fly secrets set | sudo apt update && sudo apt install -y docker.io git clone <your-repo && cd knowa cp .env.example .env && nano .env docker build -t knowa . docker run -d --env-file .env -p 8000:8000 --restart unless-stopped knowa Three layers — run in order. pip install pytest pytest tests/unit/ -v Expected: 99 passed, 21 skipped Unlock full coverage: python -m spacy download en core web sm +8 spaCy graph extractor tests pip install markdownify requests +13 Confluence connector tests Full install: 120 passed, 0 skipped Tests the full ingestion pipeline with fixture markdown files. No Notion API or OpenAI calls — embeddings use deterministic fake vectors. createdb knowa test psql knowa test -c "CREATE EXTENSION IF NOT EXISTS vector;" TEST DATABASE URL=postgresql://postgres:postgres@localhost:5432/knowa test \ OPENAI API KEY=sk-anything API KEY=test \ pytest tests/integration/ -v Tests the full system end-to-end against real Notion pages with deterministic content. One-time setup: - Create three pages in your Notion workspace with exact content from tests/e2e/notion test pages.md : Knowa Test — FAQ Knowa Test — Pricing Knowa Test — Handbook - Connect your integration to each page ⋯ → Connections - Copy the 32-char hex ID from each page's URL strip dashes and page title - Create .env.test : TEST DATABASE URL=postgresql://postgres:postgres@localhost:5432/knowa test TEST NOTION FAQ PAGE ID=<32-char id TEST NOTION PRICING PAGE ID=<32-char id TEST NOTION HANDBOOK PAGE ID=<32-char id Run: export $ cat .env.test | xargs pytest tests/e2e/ -v -s E2E tests auto-skip if any required env var is missing — they will not break CI runs without Notion credentials. Each full run costs ~$0.05 in OpenAI API calls. Use after schema changes, embedding model updates, or suspected index corruption: curl -X POST "http://localhost:8000/admin/rebuild?full=true" -H "X-API-Key: <key " or via CLI no server needed : knowa index /path/to/docs --full SELECT source id, source type, label, last synced at FROM sync state; SELECT relname AS table, pg size pretty pg total relation size relid AS total size FROM pg catalog.pg statio user tables ORDER BY pg total relation size relid DESC; SELECT source id, COALESCE label, source id AS name, last synced at, NOW - last synced at AS age FROM sync state ORDER BY last synced at ASC; At least one cloud connector must be fully configured: either NOTION API KEY or all four CONFLUENCE vars. This error does not apply to local directory sources — use knowa index <dir for those. Verify env vars are loaded: docker exec knowa env | grep -E 'NOTION|CONFLUENCE' Run knowa debug to check raw node/edge counts. If nodes = 0: spaCy model not installed — run python -m spacy download en core web sm then trigger a full rebuild Purely technical content — code files, configs, and API references have few named entities. Graph works best with prose containing people, organisations, and places. Consider adding LLM entity enrichment llm-entity-enrichment-opt-in for technical domains. Indexed before graph extraction was set up — trigger a full rebuild from the Admin tab to re-run extraction on all pages. SELECT COUNT FROM chunks WHERE chunk type = 'child'; If 0, run a full rebuild. If non-zero, check for OpenAI API errors in the server logs — the query embedding may be failing. Embedding requests are batched at 100 texts per call knowa/indexing/embedder.py . If hitting rate limits, reduce the batch size to 50 or request a rate limit increase from OpenAI. The Notion integration must be explicitly connected to each page: ⋯ → Connections → Add connection . Sub-pages inherit the connection automatically, but top-level pages do not. CREATE EXTENSION IF NOT EXISTS vector; On AWS RDS, ensure pgvector is in your Parameter Group's shared preload libraries before creating the extension. The IVFFlat index needs at least lists × 3 rows to be useful. With lists=100 that is ~300 child chunks. This warning appears on small initial datasets and resolves automatically as the index grows. No built-in metrics endpoint yet. Recommended additions for production: Structured logging — replace logging.basicConfig with structlog for JSON logs Rebuild alerts — if stats "errors" 0 after a rebuild, send a Slack/email notification Query latency — add a FastAPI middleware timer and log P95 latency Index freshness — alert if last synced at is older than your sync interval the Operations query above makes a good health check For full architecture documentation, schema, API spec, cost model, and extension points see DESIGN.md /zzorphcreator/knowa/blob/master/DESIGN.md . PostgreSQL + pgvector · FastAPI · OpenAI embeddings + completions · spaCy configurable NER model · tiktoken · Neo4j / Kuzu optional graph backends · any OpenAI-compatible LLM for entity enrichment gpt-4o-mini, Qwen3, Kimi2, etc.