A natural language search engine for your personal notes, transactions and images

Supported Plugins

• Features
• Demos
  • Khoj in Obsidian
  • Khoj in Emacs, Browser
  • Interfaces
• Architecture
• Setup
  • Install
  • Run
  • Configure
  • Install Plugins
• Use
  • Khoj Search
  • Khoj Chat
• Upgrade
  • Khoj Server
  • Khoj.el
  • Khoj Obsidian
• Uninstall
• Troubleshoot
• Advanced Usage
  • Access Khoj on Mobile
  • Use OpenAI Models for Search
  • Search across Different Languages
• Miscellaneous
  • Setup OpenAI API key in Khoj
  • GPT API
• Performance
  • Query Performance
  • Indexing Performance
  • Miscellaneous
• Development
  • Visualize Codebase
  • Setup
    • Using Pip
    • Using Docker
    • Using Conda
  • Validate
• Credits

• Natural: Advanced natural language understanding using Transformer based ML Models
• Local: Your personal data stays local. All search, indexing is done on your machine*
• Incremental: Incremental search for a fast, search-as-you-type experience
• Pluggable: Modular architecture makes it easy to plug in new data sources, frontends and ML models
• Multiple Sources: Search your Org-mode and Markdown notes, Beancount transactions and Photos
• Multiple Interfaces: Search from your Web Browser, Emacs or Obsidian

These are the general setup instructions for Khoj.

• Make sure python and pip are installed on your machine
• Check the Khoj.el Readme to setup Khoj with Emacs
• Check the Khoj Obsidian Readme to setup Khoj with Obsidian
  Its simpler as it can skip the configure step below.

pip install khoj-assistant

khoj

Note: To start Khoj automatically in the background use Task scheduler on Windows or Cron on Mac, Linux (e.g with @reboot khoj)

1. Enable content types and point to files to search in the First Run Screen that pops up on app start
2. Click Configure and wait. The app will download ML models and index the content for search

Khoj exposes a web interface by default.
The optional steps below allow using Khoj from within an existing application like Obsidian or Emacs.

• Khoj Obsidian:
  Install the Khoj Obsidian plugin

• Khoj Emacs:
  Install khoj.el

• Khoj via Obsidian
  • Click the Khoj search icon 🔎 on the Ribbon or Search for Khoj: Search in the Command Palette
• Khoj via Emacs
  • Run M-x khoj <user-query>
• Khoj via Web
  • Open https://localhost:8000/ via desktop interface or directly
• Khoj via API
  • See the Khoj FastAPI Swagger Docs, ReDocs

• Creates a personal assistant for you to inquire and engage with your notes
• Uses ChatGPT and Khoj search
• Supports multi-turn conversations with the relevant notes for context
• Shows reference notes used to generate a response
• Note: Your query and top notes from khoj search will be sent to OpenAI for processing

• Setup your OpenAI API key in Khoj

1. Open /chat¹
2. Type your queries and see response by Khoj from your notes

1. Your query is used to retrieve the most relevant notes, if any, using Khoj search
2. These notes, the last few messages and associated metadata is passed to ChatGPT along with your query for a response

pip install --upgrade khoj-assistant

Note: To upgrade to the latest pre-release version of the khoj server run below command

# Maps to the latest commit on the master branch
pip install --upgrade --pre khoj-assistant

• Use your Emacs Package Manager to Upgrade
• See khoj.el readme for details

• Upgrade via the Community plugins tab on the settings pane in the Obsidian app
• See the khoj plugin readme for details

1. (Optional) Hit Ctrl-C in the terminal running the khoj server to stop it
2. Delete the khoj directory in your home folder (i.e ~/.khoj on Linux, Mac or C:\Users\<your-username>\.khoj on Windows)
3. Uninstall the khoj server with pip uninstall khoj-assistant
4. (Optional) Uninstall khoj.el or the khoj obsidian plugin in the standard way on Emacs, Obsidian

• Details: pip install khoj-assistant fails while building the tokenizers dependency. Complains about Rust.
• Fix: Install Rust to build the tokenizers package. For example on Mac run:

  brew install rustup
  rustup-init
  source ~/.cargo/env

• Refer: Issue with Fix for more details

• Fix: Open /api/update?force=true¹ in browser to regenerate index from scratch
• Note: This is a fix for when you percieve the search results have degraded. Not if you think they've always given wonky results

• Fix: Increase RAM available to Docker Containers in Docker Settings
• Refer: StackOverflow Solution, Configure Resources on Docker for Mac

• Mitigation: Disable image search using the desktop GUI

1. Setup Khoj on your personal server. This can be any always-on machine, i.e an old computer, RaspberryPi(?) etc
2. Install Tailscale on your personal server and phone
3. Open the Khoj web interface of the server from your phone browser.
   It should be https://tailscale-ip-of-server:8000 or https://name-of-server:8000 if you've setup MagicDNS
4. Click the Add to Homescreen button
5. Enjoy exploring your notes, transactions and images from your phone!

1. Set encoder-type, encoder and model-directory under asymmetric and/or symmetric search-type in your khoj.yml²:

      asymmetric:
   -    encoder: "sentence-transformers/multi-qa-MiniLM-L6-cos-v1"
   +    encoder: text-embedding-ada-002
   +    encoder-type: src.khoj.utils.models.OpenAI
        cross-encoder: "cross-encoder/ms-marco-MiniLM-L-6-v2"
   -    encoder-type: sentence_transformers.SentenceTransformer
   -    model_directory: "~/.khoj/search/asymmetric/"
   +    model-directory: null

2. Setup your OpenAI API key in Khoj
3. Restart Khoj server to generate embeddings. It will take longer than with offline models.

This configuration uses an online model

• It will send all notes to OpenAI to generate embeddings
• All queries will be sent to OpenAI when you search with Khoj
• You will be charged by OpenAI based on the total tokens processed
• It requires an active internet connection to search and index

To search for notes in multiple, different languages, you can use a multi-lingual model.
For example, the paraphrase-multilingual-MiniLM-L12-v2 supports 50+ languages, has good search quality and speed. To use it:

1. Manually update search-type > asymmetric > encoder to sentence-transformer/paraphrase-multilingual-MiniLM-L12-v2 in your ~/.khoj/khoj.yml file for now. See diff of khoj.yml below for illustration:

 asymmetric:
- encoder: "sentence-transformers/multi-qa-MiniLM-L6-cos-vi"
+ encoder: "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
   cross-encoder: "cross-encoder/ms-marco-MiniLM-L-6-v2"
   model_directory: "~/.khoj/search/asymmetric/"

2. Regenerate your content index. For example, by opening <khoj-url>/api/update?t=force

If you want, Khoj can be configured to use OpenAI for search and chat.
Add your OpenAI API to Khoj by using either of the two options below:

• Open the Khoj desktop GUI, add your OpenAI API key and click Configure Ensure khoj is started without the --no-gui flag. Check your system tray to see if Khoj 🦅 is minimized there.
• Set openai-api-key field under processor.conversation section in your khoj.yml² to your OpenAI API key and restart khoj:

  processor:
    conversation:
  -    openai-api-key: # "YOUR_OPENAI_API_KEY"
  +    openai-api-key: sk-aaaaaaaaaaaaaaaaaaaaaaaahhhhhhhhhhhhhhhhhhhhhhhh
      model: "text-davinci-003"
      conversation-logfile: "~/.khoj/processor/conversation/conversation_logs.json"

Warning: This will enable Khoj to send your query and note(s) to OpenAI for processing

• The chat, answer and search API endpoints use OpenAI API
• They are disabled by default
• To use them:
  1. Setup your OpenAI API key in Khoj
  2. Interact with them from the Khoj Swagger docs¹

• Semantic search using the bi-encoder is fairly fast at <50 ms
• Reranking using the cross-encoder is slower at <2s on 15 results. Tweak top_k to tradeoff speed for accuracy of results
• Filters in query (e.g by file, word or date) usually add <20ms to query latency

• Indexing is more strongly impacted by the size of the source data
• Indexing 100K+ line corpus of notes takes about 10 minutes
• Indexing 4000+ images takes about 15 minutes and more than 8Gb of RAM
• Note: It should only take this long on the first run as the index is incrementally updated

• Testing done on a Mac M1 and a >100K line corpus of notes
• Search, indexing on a GPU has not been tested yet

Interactive Visualization

# Get Khoj Code
git clone https://github.com/debanjum/khoj && cd khoj

# Create, Activate Virtual Environment
python3 -m venv .venv && source .venv/bin/activate

# Install Khoj for Development
pip install -e .[dev]

1. Start Khoj

   khoj -vv

2. Configure Khoj
   • Via GUI: Add files, directories to index in the GUI window that pops up on starting Khoj, then Click Configure
   • Manually:
     • Copy the config/khoj_sample.yml to ~/.khoj/khoj.yml
     • Set input-files or input-filter in each relevant content-type section of ~/.khoj/khoj.yml
       • Set input-directories field in image content-type section
     • Delete content-type and processor sub-section(s) irrelevant for your use-case
     • Restart khoj

Note: Wait after configuration for khoj to Load ML model, generate embeddings and expose API to query notes, images, transactions etc specified in config YAML

git clone https://github.com/debanjum/khoj && cd khoj

• Required: Update docker-compose.yml to mount your images, (org-mode or markdown) notes and beancount directories
• Optional: Edit application configuration in khoj_docker.yml

docker-compose up -d

Note: The first run will take time. Let it run, it's mostly not hung, just generating embeddings

docker-compose build --pull

• Install Conda

git clone https://github.com/debanjum/khoj && cd khoj
conda env create -f config/environment.yml
conda activate khoj
python3 -m pip install pyqt6  # As conda does not support pyqt6 yet

• Copy the config/khoj_sample.yml to ~/.khoj/khoj.yml
• Set input-files or input-filter in each relevant content-type section of ~/.khoj/khoj.yml
  • Set input-directories field in image content-type section
• Delete content-type, processor sub-sections irrelevant for your use-case

python3 -m src.khoj.main -vv

Load ML model, generate embeddings and expose API to query notes, images, transactions etc specified in config YAML

cd khoj
git pull origin master
conda deactivate khoj
conda env update -f config/environment.yml
conda activate khoj

1. Install Git Hooks for Validation

   pre-commit install -t pre-push -t pre-commit

   • This ensures standard code formatting fixes and other checks run automatically on every commit and push
   • Note 1: If pre-commit didn't already get installed, install it via pip install pre-commit
   • Note 2: To run the pre-commit changes manually, use pre-commit run --hook-stage manual --all before creating PR

1. Run Tests

   pytest

2. Run MyPy to check types

   mypy --config-file pyproject.toml

• Automated validation workflows run for every PR.

  Ensure any issues seen by them our fixed

• Test the python packge created for a PR

  1. Download and extract the zipped .whl artifact generated from the pypi workflow run for the PR.
  2. Install (in your virtualenv) with pip install /path/to/download*.whl>
  3. Start and use the application to see if it works fine

• Multi-QA MiniLM Model, All MiniLM Model for Text Search. See SBert Documentation
• OpenAI CLIP Model for Image Search. See SBert Documentation
• Charles Cave for OrgNode Parser
• Org.js to render Org-mode results on the Web interface
• Markdown-it to render Markdown results on the Web interface