Khoj AI: Deep Dive Tutorial

June 22, 2026 · View on GitHub

Project: Khoj — An open-source, self-hostable AI personal assistant that connects to your notes, documents, and online data.

Why This Track Matters

Khoj AI is increasingly relevant for developers working with modern AI/ML infrastructure. Project: Khoj — An open-source, self-hostable AI personal assistant that connects to your notes, documents, and online data, and this track helps you understand the architecture, key patterns, and production considerations.

This track focuses on:

understanding getting started
understanding architecture overview
understanding data connectors
understanding search & retrieval

What Is Khoj?

Khoj is an open-source AI personal assistant that transforms your scattered notes, documents, and online data into a searchable, conversational knowledge base. It combines semantic search with LLM-backed chat to help you retrieve, synthesize, and act on your personal information. Khoj can be self-hosted for full data privacy or used via the hosted service.

Feature	Description
Semantic Search	Symmetric and asymmetric search with cross-encoder re-ranking over personal data
Multi-Source	Org-mode, Markdown, PDF, GitHub repos, Notion pages, web content
LLM Chat	Conversational AI with context from your knowledge base (OpenAI, Anthropic, Ollama)
Automation	Scheduled tasks, autonomous agents, and tool-use for proactive assistance
Self-Hostable	Full Docker deployment with PostgreSQL, data stays on your infrastructure
Client Integrations	Obsidian plugin, Emacs package, web UI, WhatsApp, and API access

Current Snapshot (auto-updated)

repository: khoj-ai/khoj
stars: about 35.2k
GitHub release reference: 2.0.0-beta.28 (checked 2026-06-22; release metadata on GitHub)

Mental Model

graph TB
    subgraph Clients["Client Layer"]
        WEB[Web UI]
        OBS[Obsidian Plugin]
        EMACS[Emacs Package]
        WHATSAPP[WhatsApp]
        API_CLIENT[REST API]
    end

    subgraph Server["Khoj Server (Django)"]
        API[API Routes]
        SEARCH[Search Engine]
        CHAT[Chat Engine]
        INDEX[Indexer Pipeline]
        AUTO[Automation Engine]
    end

    subgraph Data["Data Connectors"]
        ORG[Org-mode]
        MD[Markdown]
        PDF[PDF / Docx]
        GH[GitHub]
        NOTION[Notion]
        WEB_SRC[Web Content]
    end

    subgraph Storage["Storage Layer"]
        PG[(PostgreSQL)]
        EMBED[(Embeddings)]
        FILES[(File Store)]
    end

    subgraph LLM["LLM Providers"]
        OPENAI[OpenAI]
        ANTHROPIC[Anthropic]
        OLLAMA[Ollama / Local]
    end

    Clients --> Server
    Data --> INDEX
    INDEX --> Storage
    SEARCH --> EMBED
    CHAT --> LLM
    AUTO --> CHAT
    SERVER --> Storage

Chapter Guide

Chapter	Topic	What You'll Learn
1. Getting Started	Setup	Installation, self-hosting, connecting first data sources
2. Architecture Overview	Design	System components, search indexing, LLM integration pipeline
3. Data Connectors	Ingestion	Org-mode, Markdown, PDF, GitHub, Notion connector internals
4. Search & Retrieval	Search	Symmetric/asymmetric search, embeddings, cross-encoder ranking
5. Chat Interface	Conversation	Context management, conversation threads, tool use, citations
6. Automation & Agents	Agents	Scheduled tasks, autonomous actions, tool integration
7. Customization & Plugins	Extensibility	Custom data types, model configuration, extensions
8. Production Deployment	Operations	Docker, scaling, security, monitoring, backup strategies

Tech Stack

Component	Technology
Backend	Python, Django
Database	PostgreSQL
Search	Sentence Transformers embeddings, cross-encoder re-ranking
LLM Providers	OpenAI, Anthropic, Google, Ollama (local)
Frontend	Next.js (web UI)
Clients	Obsidian plugin, Emacs package, WhatsApp bot
Deployment	Docker Compose, systemd
Task Queue	Django Q / APScheduler for automation

Ready to begin? Start with Chapter 1: Getting Started.

Built with insights from the Khoj repository and community documentation.

What You Will Learn

Core architecture and key abstractions
Practical patterns for production use
Integration and extensibility approaches

Full Chapter Map

Source References

Khoj

Generated by AI Codebase Knowledge Builder