OpenDocuments

OpenDocuments Self-hosted RAG platform for AI document search across GitHub, Notion, Google Drive, Confluence, S3, local files, and web sources

English | 한국어

---

What is OpenDocuments?

OpenDocuments is an open source, self-hosted RAG (Retrieval-Augmented Generation) platform that turns scattered company documents into an AI-searchable knowledge base. It connects to sources like GitHub, Notion, Google Drive, Confluence, S3, Swagger/OpenAPI, local files, and web pages, indexes them with hybrid vector + keyword search, and answers natural-language questions with cited sources.

Use OpenDocuments when you want:

• A self-hosted alternative to enterprise AI search and proprietary knowledge-base search tools
• AI document search with citations for engineering docs, product specs, policies, spreadsheets, API docs, and meeting notes
• A local-first RAG stack that can run with Ollama so sensitive documents stay on your own infrastructure
• A knowledge base for AI coding assistants through MCP, including Claude Code, Cursor, Windsurf, and other MCP clients
• A TypeScript-first RAG platform with a CLI, Web UI, HTTP API, SDK, plugin system, and embeddable widget

npm install -g opendocuments
opendocuments init
opendocuments start

Open http://localhost:3000, index your documents, and ask questions with source citations.

Why OpenDocuments?

Your team's knowledge is trapped in silos:

• Engineering docs live in GitHub READMEs and Wiki pages
• Product specs are scattered across Notion databases
• Budget reports sit in Excel files on Google Drive
• API docs are auto-generated Swagger specs nobody reads
• Meeting notes rot in Confluence spaces
• Onboarding guides are buried in .docx files on S3

When someone asks "How does our auth system work?" or "What was the Q3 budget for the AI team?", they spend 15 minutes hunting through five different tools. OpenDocuments centralizes that search without forcing all of your content into a hosted vendor.

How OpenDocuments Answers Questions

OpenDocuments connects to your document sources, parses and chunks each document, stores metadata in SQLite and vectors in LanceDB, then retrieves, reranks, and generates grounded answers. Every answer can include source citations, confidence scores, and links back to the underlying documents.

In short: OpenDocuments is a private AI search engine for your organization's documents.

Key Features

| Feature | What it means | |---------|---------------| | Self-hosted RAG | Run the full document search stack on your own infrastructure | | Cited AI answers | Ask natural-language questions and see exactly which documents support the answer | | Hybrid retrieval | Combine vector search, FTS5 keyword search, reranking, HyDE, multi-query retrieval, and parent-document recall | | Broad source coverage | Index GitHub, Notion, Google Drive, Confluence, S3/GCS, Swagger/OpenAPI, web pages, web search, uploads, and local files | | Many file formats | Parse Markdown, PDF, DOCX, XLSX, CSV, HTML, Jupyter notebooks, email, code, PPTX, JSON, YAML, TOML, and more | | Local or cloud models | Use Ollama locally or cloud providers such as OpenAI, Anthropic, Google, and xAI | | MCP server | Let Claude Code, Cursor, Windsurf, and other MCP clients search your internal knowledge base | | Team mode | Add API keys, roles, rate limits, PII redaction, audit logs, alerts, OAuth SSO, and workspace isolation | | Extensible plugins | Build custom parsers, connectors, model providers, and middleware in TypeScript |

OpenDocuments vs Alternatives

| If you are comparing... | Choose OpenDocuments when you need... | |-------------------------|----------------------------------------| | OpenDocuments vs hosted enterprise search | A self-hosted, open source AI search platform with control over infrastructure and data flow | | OpenDocuments vs a vector database | A complete RAG application layer: connectors, parsers, chunking, retrieval, chat, citations, auth, CLI, Web UI, and MCP | | OpenDocuments vs a chatbot wrapper | Source-grounded answers over your real document corpus, not a generic chat UI | | OpenDocuments vs building RAG from scratch | A TypeScript monorepo with batteries included, while still keeping plugin-level extensibility | | OpenDocuments vs local-only scripts | A production-oriented system with team mode, API access, syncable connectors, backups, and admin tooling |

Recent Improvements

• RAG accuracy overhaul: Structure-preserving chunking, contextual prefixes, HyDE + multi-query retrieval, parent-document recall, proposition augmentation, reranking, and adaptive context fitting
• Workspace-scoped team mode: Admin/chat/document APIs stay inside the authenticated workspace, with shared conversation links plus session and API-key auth support
• Backup & restore CLI: Snapshot SQLite + LanceDB data and recover an instance with one command
• Plugin hardening: Plugin search/install routes are admin-only and use validated npm argument execution
• One-touch Ollama setup: init auto-detects Ollama, offers to pull missing models
• .env auto-loading: API keys in .env are loaded automatically (no manual export needed)
• Multi-turn conversations: Chat remembers previous context for follow-up questions
• Degraded mode warnings: Clear banners when models aren't configured, with fix instructions
• Enhanced diagnostics: opendocuments doctor checks Ollama connectivity, model availability, and config validity
• Security hardening: FTS5 injection prevention, file upload sanitization, OAuth state limits, workspace isolation

---

Real-World Use Cases

For Engineering Teams

> "How do I authenticate against our internal API?"

OpenDocuments pulls the answer from your GitHub repo's docs/auth.md, links to the relevant Swagger endpoint, and includes a code example from the codebase -- all in one response.

# Index your repo and API docs
opendocuments index ./docs
opendocuments connector sync github
opendocuments ask "How does JWT token refresh work in our API?"

For Operations & HR Teams

> "What's the remote work policy for the Tokyo office?"

OpenDocuments searches across your Confluence HR space, the employee handbook on Google Drive, and the latest policy update email -- even if some documents are in Korean and others in English.

opendocuments ask "도쿄 오피스 원격 근무 정책이 뭐야?" --profile precise
# Cross-lingual search finds both Korean and English documents

For Product Managers

> "Compare the feature specs of v2.0 vs v3.0"

OpenDocuments decomposes the question, searches both versions' specs, and presents a structured comparison table -- citing each source document.

For AI-Assisted Development (MCP)

Use OpenDocuments as a knowledge base for Claude Code, Cursor, or any MCP-compatible AI tool:

{
  "mcpServers": {
    "opendocuments": {
      "command": "opendocuments",
      "args": ["start", "--mcp-only"]
    }
  }
}

Now your AI coding assistant can search your organization's entire document corpus while writing code.

For Self-Hosted Knowledge Bases

Deploy on your own infrastructure. Your data never leaves your network when using a local LLM via Ollama. No cloud dependency, no vendor lock-in, no subscription fees.

docker compose --profile with-ollama up -d
# Everything runs locally: LLM, embeddings, vector search, web UI

---

Quick Start

This is the fastest way to run a local AI document search engine with the OpenDocuments CLI.

1. Install

npm install -g opendocuments

2. Initialize

opendocuments init

The interactive wizard will:

• Detect your hardware (CPU, RAM) and recommend the optimal LLM
• Let you choose between local (Ollama) or cloud (OpenAI, Claude, Gemini, Grok) models
• Auto-detect Ollama and offer to pull missing models automatically
• Validate cloud API keys before saving
• Select a plugin preset: Developer, Enterprise, All, or Custom
• Generate opendocuments.config.ts and .env (API keys loaded automatically)

3. Start

opendocuments start

Open http://localhost:3000 -- you'll see a chat UI, document manager, and admin dashboard.

> First time? If Ollama isn't running, you'll see a clear DEGRADED MODE banner with step-by-step fix instructions. Run opendocuments doctor for full diagnostics.

4. Index Your Documents

# Index a local directory (recursively finds all supported files)
opendocuments index ./docs

# Watch mode: auto-reindex when files change
opendocuments index ./docs --watch

# Or drag-and-drop files in the Web UI

5. Ask Questions

opendocuments ask "What's our deployment process?"

---

How It Works

OpenDocuments uses a standard RAG architecture with practical production pieces around it: source connectors, format parsers, chunking, embeddings, metadata storage, vector storage, retrieval profiles, answer generation, citations, and security controls.

    Your Documents                    OpenDocuments                     You
    ─────────────                    ──────────────                    ───

    GitHub repos ──┐
    Notion pages ──┤                ┌─────────────┐
    Google Drive ──┤  ── Ingest ──► │ Parse        │
    Confluence   ──┤                │ Chunk        │     "How does
    S3 buckets   ──┤                │ Embed        │      auth work?"
    Swagger specs──┤                │ Store        │          │
    Local files  ──┤                └──────┬───────┘          │
    Web pages    ──┘                       │                  ▼
                                    ┌──────┴───────┐  ┌─────────────┐
                                    │  SQLite      │  │ RAG Engine  │
                                    │  (metadata)  │◄─┤ Search      │
                                    │              │  │ Rerank      │
                                    │  LanceDB     │  │ Generate    │
                                    │  (vectors)   │  │ Cite sources│
                                    └──────────────┘  └──────┬──────┘
                                                             │
                                                             ▼
                                                      "Auth uses JWT
                                                       tokens with
                                                       refresh flow.
                                                       [Source: auth.md]"

The RAG Pipeline

1. Intent Classification -- Understands whether you're asking about code, concepts, data, or want a comparison
2. Query Decomposition -- Breaks complex questions into sub-queries for better retrieval
3. Cross-Lingual Search -- Finds documents in both Korean and English regardless of query language
4. Hybrid Search -- Combines dense vector search (semantic) with FTS5 sparse search (keyword) via Reciprocal Rank Fusion
5. Reranking -- Scores results by keyword overlap and model-based relevance
6. Confidence Scoring -- Tells you honestly when it's not sure about an answer
7. Hallucination Guard -- Verifies each sentence is grounded in the retrieved sources
8. 3-Tier Caching -- L1 query cache (5min), L2 embedding cache (24h), L3 web search cache (1h)

---

Supported File Formats

| Format | Extensions | How It's Parsed | |--------|-----------|-----------------| | Markdown | .md, .mdx | Heading hierarchy, code block separation | | Plain Text | .txt | Direct text indexing | | PDF | .pdf | Page-level extraction, OCR fallback for scanned docs | | Word | .docx | HTML conversion with heading detection | | Excel / CSV | .xlsx, .xls, .csv | Sheet-aware table chunking (header + rows) | | HTML | .html, .htm | Structure-preserving extraction, script/nav stripping | | Jupyter Notebook | .ipynb | Markdown cells + code cells with language detection | | Email | .eml | Header parsing (from/to/subject/date) + body extraction | | Source Code | .js, .ts, .py, .java, .go, .rs, .rb, .php, .swift, .kt + more | Function/class-level chunking with import extraction | | PowerPoint | .pptx | Slide-level text extraction | | Structured Data | .json, .yaml, .yml, .toml | Config and schema indexing | | Archive | .zip | Placeholder (full extraction planned) |

Fallback Chains: If a parser fails, the next one tries automatically:

parserFallbacks: {
  '.pdf': ['@opendocuments/parser-pdf', '@opendocuments/parser-ocr'],
}

---

Data Sources

| Source | What It Indexes | Auth | How It Syncs | |--------|----------------|------|-------------| | Local Files | Any supported format on your filesystem | None | File watching (--watch) | | File Upload | Drag-and-drop in Web UI | None | Instant | | GitHub | README, Wiki, code files, Issues | Personal Access Token | Polling / webhook | | Notion | Pages, databases, all block types | Integration Token | Polling | | Google Drive | Docs, Sheets, Slides, uploaded files | OAuth / Service Account | Polling | | Amazon S3 / Google Cloud Storage | Any supported format in buckets | AWS / GCP credentials | Polling | | Confluence | Wiki pages across spaces | API Token + Email | Polling | | Swagger / OpenAPI | API endpoints with parameters and schemas | None (public specs) | Manual | | Web Crawler | Any URL you register | Optional (cookies/headers) | Periodic | | Web Search (Tavily) | Real-time web results merged into answers | Tavily API Key | Query-time |

---

Model Providers

Cloud Providers

| Provider | Models | Embedding | Best For | |----------|--------|-----------|----------| | OpenAI | GPT-5.4, GPT-5.4-mini, GPT-4.1, o3, o4-mini | text-embedding-3-small/large | General purpose, vision, reasoning | | Anthropic | Claude Opus 4.6, Claude Sonnet 4.6, Claude Haiku 4.5 | -- (use separate provider) | Long context (1M), coding, analysis | | Google | Gemini 3.1 Pro, Gemini 3.1 Flash Lite, Gemini 3.0 Deep Think | text-embedding-005 | Multimodal, multilingual | | xAI | Grok 4, Grok 4 Heavy, Grok 4.1 Fast | Grok embedding | Real-time knowledge, code | | DeepSeek | DeepSeek-V3.2, DeepSeek-R1, DeepSeek-V4 (upcoming) | -- (use separate provider) | Cost-efficient reasoning, 164K context | | Mistral | Mistral Small 4 (MoE), Large 2.1, Codestral, Pixtral | mistral-embed (1024) | European data residency, coding, vision | | OpenAI-compatible | Any OpenAI-compatible endpoint | Depends on endpoint | vLLM, LM Studio, Together, Fireworks, Groq, DeepInfra, SiliconFlow, OpenRouter |

Local Models (via Ollama)

| Model | Active Params | Total Params | Vision | Korean | Best For | |-------|-------------|-------------|--------|--------|----------| | Qwen 3.5 27B | 27B (dense) | 27B | Yes | Excellent | General purpose (32GB+ RAM) | | Qwen 3.5 9B | 9B (dense) | 9B | Yes | Excellent | Mid-range (16GB RAM) | | Qwen 3.5-122B-A10B | 10B (MoE) | 122B | Yes | Excellent | High quality, efficient | | Llama 4 Scout | 17B (MoE) | 109B | Yes | Good | 10M context window | | Llama 4 Maverick | 17B (MoE) | 400B | Yes | Good | Top open-source quality | | DeepSeek V3.2 | 37B (MoE) | 671B | No | Good | Coding, reasoning | | Gemma 4 | 27B / 12B / 4B / 1B | dense | Yes | Good | Latest Google open model, 128K context, 140+ languages | | Gemma 3 27B | 27B | 27B | Yes | Good | Lightweight, 140+ languages | | Gemma 3 4B | 4B | 4B | Yes | Good | Low-spec machines (8GB RAM) | | K-EXAONE | 23B (MoE) | 236B | No | Best | Korean-specialized | | EXAONE Deep 32B | 32B | 32B | No | Best | Korean reasoning | | Phi-4 Reasoning Vision | 15B | 15B | Yes | Fair | Comp

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: joungminsung
• Source: joungminsung/OpenDocuments
• License: MIT
• Homepage: https://joungminsung.github.io/OpenDocuments/

Install and usage instructions live in the source repository linked above.