How khoj-ai/khoj works
Khoj is a self-hostable personal AI application. Users enter through web, desktop, Obsidian, phone, or messaging clients to chat with models, search personal documents and the web, create agents, or schedule research automations. The backend exposes API capabilities, processes and indexes multiple content formats, retrieves relevant entries, and combines them with model/tool execution. The README documents the product branches; sampled source supports several internal links, while unsampled router wiring is left unverified.
Main entry points: main.py Application server · text_search.py Text search · research.py Research orchestration · api_chat.py Chat endpoints
Components 23
User Interfaces
- Web app
src/interface/web/app - Desktop app
src/interface/desktop/main.js - Obsidian plugin
src/interface/obsidian/src/main.ts - Android app
src/interface/android/app/src/main/java/dev/khoj/app/LauncherActivity.java
API Services
- Application server
src/khoj/main.py - Chat endpoints
src/khoj/routers/api_chat.py - Agent endpoints
src/khoj/routers/api_agents.py - Automation endpoints
src/khoj/routers/api_automation.py - Research orchestration
src/khoj/routers/research.py - Content endpoints
src/khoj/routers/api_content.py
Knowledge Retrieval
- Content extraction
src/khoj/processor/content - Text search
src/khoj/search_type/text_search.py - Search filters
src/khoj/search_filter - Embedding models
src/khoj/processor/embeddings.py
AI Capabilities
- Conversation models
src/khoj/processor/conversation - Online search
src/khoj/processor/tools/online_search.py - Agent tools
src/khoj/processor/operator - Image generation
src/khoj/processor/image/generate.py - Speech output
src/khoj/processor/speech/text_to_speech.py
Application Data
- Data adapters
src/khoj/database/adapters/__init__.py - Database models
src/khoj/database/models/__init__.py - Runtime state
src/khoj/utils/state.py
Other components
- User
Connections 33
- User → Web app: uses
README.md - User → Desktop app: uses
README.md - User → Obsidian plugin: uses
README.md - User → Android app: uses
README.md - Web app → Application server: API requests
- Desktop app → Application server: API requests
- Obsidian plugin → Application server: API requests
- Android app → Application server: API requests
- Application server → Chat endpoints: dispatches
- Application server → Agent endpoints: dispatches
- Application server → Automation endpoints: dispatches
- Application server → Content endpoints: dispatches
- Chat endpoints → Conversation models: uses
- Content endpoints → Content extraction: processes content
- Content extraction → Text search: creates entries
src/khoj/search_type/text_search.py - Text search → Data adapters: queries
src/khoj/search_type/text_search.py - Text search → Database models: loads models
src/khoj/search_type/text_search.py - Text search → Content extraction: invokes setup
src/khoj/search_type/text_search.py - Text search → Runtime state: reads runtime state
src/khoj/search_type/text_search.py - Embedding models → Database models: uses models
src/khoj/processor/embeddings.py - Embedding models → Runtime state: uses state
src/khoj/utils/state.py - Research orchestration → Online search: invokes tool
src/khoj/routers/research.py - Research orchestration → Agent tools: uses agents
src/khoj/routers/research.py - Research orchestration → Database models: queries data
src/khoj/routers/research.py - Research orchestration → Conversation models: uses prompts
src/khoj/routers/research.py - Data adapters → Database models: persists records
src/khoj/database/adapters/__init__.py - Application server → Runtime state: configures
src/khoj/main.py - Application server → Data adapters: initializes data
src/khoj/main.py - Agent endpoints → Agent tools: configures agents
- Chat endpoints → Image generation: supports generation
- Chat endpoints → Speech output: supports speech
- Text search → Search filters: applies filters
- Automation endpoints → Research orchestration: schedules research