Skip to main content

Knowledge-Base RAG

Nox's product knowledge comes from the nox-knowledge-base repo — markdown files ingested by ms-ai's KnoxDocumentService into a pgvector store and retrieved with reranking.

Source: nox-knowledge-base​

A markdown repo of ~60+ files across 15 category dirs (platform, widget, communication, ai-agents, sessions, identity-graph, leads-and-scoring, bookings, integrations, billing, settings, agency, desktop, data-model, nox-self), indexed by INDEX.md.

Each file carries frontmatter that drives retrieval:

title: <human-readable>
content_type: feature_guide | how_to | troubleshooting | policy | api_reference |
  faq | concept | screen_guide | setting | workflow | ...
product_area: dashboard | chat | voice | visitors | settings | integrations |
  widget | analytics | billing | knox | identity-graph | ...
plan_scope: all | starter | growth | pro | enterprise
tags: [keywords]
related_urls: [/settings/integrations/*, ...] # enables URL-filtered retrieval

Ingestion pipeline (KnoxDocumentService)​

markdown file
  → save as KnoxKnowledgeDocument
  → semantic chunking (split on H2/H3 headings)
  → per chunk: contextual prefix (section hierarchy) + AI summary
  → dual embeddings (OpenAI text-embedding-3-small, 1536-dim):
       embedding          = contextual_prefix + content_text
       summary_embedding  = intent-level matching
  → store in knox_knowledge_chunks (Postgres + pgvector, HNSW index)
  → organized under KnoxKnowledgeCollection

Re-ingestion (POST /knowledge/ingest, knoxDocumentQueue) soft-replaces prior chunks for the same source (is_active=false) rather than deleting.

Retrieval (3-prong + rerank)​

For a query, retrieval combines:

  1. URL-filtered search — chunks whose related_urls match the admin's current page rank higher.
  2. Global vector search over embedding (HNSW).
  3. Summary embedding search over summary_embedding.

Candidates are then reranked with Cohere rerank and the top-K injected into the Nox prompt. (If COHERE_API_KEY is unset, it falls back to vector order.)

Authoring workflow​

  1. Write markdown with the required frontmatter.
  2. Use H2/H3 headings (the chunk split boundary); lead each section with the canonical feature/object name; prefer fact lists and tables over prose (~200–800 words/file).
  3. Cross-reference related files; add an entry to INDEX.md.
  4. POST /knowledge/ingest to re-ingest — the soft-replace handles stale chunks.
  • The same pgvector approach backs Knox admin memory (operator-specific context) — see Nox Assistant.
  • Company website/FAQ/PDF content is separately embedded for the AI chat agent (scraping/embedding/PDF queues in ms-ai), distinct from the Nox product KB.