FAQ
Frequently asked questions.
Deployment, supported formats, authentication, and privacy.
Supported formats and limits
QuestionAnswer
What document formats are supported?PDF, DOCX, PPTX, TXT, Markdown, and HTML. DOCX is converted to Markdown before chunking. PPTX decks are flattened to Markdown in slide order as
## Slide N headings with speaker notes. HTML is cleaned via Readability to extract article content.What does connector sync support?Same formats as upload: .pdf, .docx, .pptx, .txt, .md, .html. Images, spreadsheets, source code, and other binary formats are skipped.
What is the document type vocabulary?
spec, plan, transcript, minutes, design, api-doc, code-summary, test, status, contract, user-story, textbook, reference, decision, action-item, other. Required on every upload. No automatic classification — always user-selected.How are tags normalized?Lowercase kebab-case (
Mobile Auth → mobile-auth), max 10 per file, 32 characters each, deduplicated case-insensitively.What are the system requirements?Docker Compose v2, 2 GB RAM minimum (4 GB+ recommended), 1 GB disk (5 GB+ recommended), PostgreSQL 16.x. The embedding model (~90 MB) downloads automatically.
Does ContextHarbor support visual enrichment for PDFs?Yes, opt-in. Pass
--visual on the CLI or visual: true on MCP ingest to run SmolVLM or Qwen2.5-VL captioning on figure pages. Disabled by default.Retrieval and search
QuestionAnswer
How does hybrid retrieval work?Semantic vector search + keyword (FTS) matching fused via Reciprocal Rank Fusion (RRF). Exact terms like error codes and class names rank higher. Optional cross-encoder reranking and docType boosts refine ordering.
What are the embedding task prefixes?
search_document (store), search_query (query), clustering (Max-Min chunking only — never stored). Nomic asymmetric retrieval.What is the search result limit?1–20 results per query (default 10). Scores are ascending distance (lower = better). Results include filePath, chunkIndex, text, score, and fileTitle.
Can I restrict search to part of my corpus?Yes. Use
scope — one absolute path prefix or a list. Results are restricted to chunks whose file path equals or sits under a prefix.What are Knowledge Briefs?A hierarchical knowledge tree (domains, modules, submodules) with consolidated, source-cited briefs. An agent can read a structured area brief instead of forty raw paragraphs. Reachable via
get_project_structure, get_area_brief, get_knowledge_item, and search_area MCP tools.What observability is available?Prometheus metrics at
GET /metrics, aggregate status at GET /status, per-project usage rollups, per-client/tool attribution, and an admin Observability page covering clients, errors, retrieval freshness, evals, and access.Authentication and access
QuestionAnswer
What is the difference between REST JWT and MCP bearer?REST uses JWT tokens (email/password login). Streamable HTTP MCP uses separate bearer API keys —
acl (scoped to user's project memberships) or all_projects (admin). JWTs are not accepted on MCP routes; MCP keys are not accepted on REST routes.How does RBAC work?Global roles: admin, project_manager (label), user. Per-project memberships: manager (upload/index), viewer (search/read). MCP key ACLs follow the same model.
Is file encryption supported?Yes, optionally. AES-256-GCM protects newly uploaded files at rest when configured. Not enabled by default.
How are project names validated?Must start with a letter, contain only letters/digits/hyphens/underscores, 1–64 characters. Globally unique. Changing embedding provider or dimensions forces reindex.
What your team provides for an evaluation
Knowledge owner One person who owns the document collection and can confirm source quality.
Representative users The people who will actually ask questions — not just evaluators.
Infrastructure contact Someone who can deploy Docker, configure networking, and manage credentials.
Selected documents A controlled collection with clear boundaries — not the entire organization's document estate.
Representative questions A realistic evaluation set agreed before configuration begins.
ContextHarbor
Have a question not answered here?
Tell us about your use case and we will respond with specifics.
Pricing depends on deployment, integration, and support requirements.