* Khoj Emacs 🦅
  [[https://stable.melpa.org/#/khoj][file:https://stable.melpa.org/packages/khoj-badge.svg]] [[https://melpa.org/#/khoj][file:https://melpa.org/packages/khoj-badge.svg]] [[https://github.com/debanjum/khoj/actions/workflows/build_khoj_el.yml][https://github.com/debanjum/khoj/actions/workflows/build_khoj_el.yml/badge.svg?]]  [[https://github.com/debanjum/khoj/actions/workflows/test_khoj_el.yml][https://github.com/debanjum/khoj/actions/workflows/test_khoj_el.yml/badge.svg?]]

  /Natural, Incremental Search for your Second Brain/

** Table of Contents
  - [[https://github.com/debanjum/khoj/tree/master/src/interface/emacs#features][Features]]
  - [[https://github.com/debanjum/khoj/tree/master/src/interface/emacs#Interface][Interface]]
  - [[https://github.com/debanjum/khoj/tree/master/src/interface/emacs#Setup][Setup]]
    - [[https://github.com/debanjum/khoj/tree/master/src/interface/emacs#1-Setup-Backend][Setup Backend]]
    - [[https://github.com/debanjum/khoj/tree/master/src/interface/emacs#2-Install-Khojel][Install Khoj.el]]
  - [[https://github.com/debanjum/khoj/tree/master/src/interface/emacs#Use][Use]]
    - [[https://github.com/debanjum/khoj/tree/master/src/interface/emacs#Search][Search]]
    - [[https://github.com/debanjum/khoj/tree/master/src/interface/emacs#Find-similar-entries][Find Similar Entries]]
    - [[https://github.com/debanjum/khoj/tree/master/src/interface/emacs#Advanced-usage][Advanced Usage]]
    - [[https://github.com/debanjum/khoj/tree/master/src/interface/emacs#Khoj-menu][Khoj Menu]]
  - [[https://github.com/debanjum/khoj/tree/master/src/interface/emacs#Upgrade][Upgrade]]
    - [[https://github.com/debanjum/khoj/tree/master/src/interface/emacs#Upgrade-Khoj-Backend][Upgrade Backend]]
    - [[https://github.com/debanjum/khoj/tree/master/src/interface/emacs#Upgrade-Khojel][Upgrade Khoj.el]]

** Features
  - *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

** Interface
  [[/docs/khoj_on_emacs.png]]

** Setup
*** 1. Setup Backend
  #+begin_src shell
    pip install khoj-assistant && khoj
  #+end_src

*** 2. Install Khoj.el
**** Using MELPA
  #+begin_src elisp
    M-x package-install khoj
  #+end_src elisp

  Add below snippet to your Emacs config file
  #+begin_src elisp
    ;; Install Khoj Package from MELPA Stable
    (use-package khoj
      :ensure t
      :pin melpa-stable
      :bind ("C-c s" . 'khoj))
  #+end_src

  Note: Install ~khoj.el~ from MELPA (instead of MELPA Stable) if you installed the pre-release version of khoj
  - That is, use ~:pin melpa~ to install khoj.el in above snippet if khoj was installed with ~pip install --pre khoj-assistant~
  - Else use ~:pin melpa-stable~ to install khoj.el in above snippet if khoj was installed with ~pip install khoj-assistant~
  - This ensures both khoj.el and khoj app are from the same version (tagged or latest)

**** Using [[https://github.com/raxod502/straight.el][Straight.el]]
  Add below snippet to your Emacs config file
  #+begin_src elisp
    ;; Install Khoj Package using Straight.el
    (use-package khoj
      :after org
      :straight (khoj :type git :host github :repo "debanjum/khoj" :files (:defaults "src/interface/emacs/khoj.el"))
      :bind ("C-c s" . 'khoj))
  #+end_src

** Use
*** Search
  1. Hit ~C-c s s~ (or ~M-x khoj RET s~) to open khoj search

  2. Enter your query in natural language

    e.g "What is the meaning of life?", "My life goals for 2023"

*** Find Similar Entries
  This feature finds entries similar to the one you are currently on.
  1. Move cursor to the org-mode entry, markdown section or text paragraph you want to find similar entries for
  2. Hit ~C-c s f~ (or ~M-x khoj RET f~) to find similar entries

*** Advanced Usage
  - Add [[https://github.com/debanjum/khoj/#query-filters][query filters]] during search to narrow down results further

    e.g `What is the meaning of life? -"god" +"none" dt>"last week"`

  - Use ~C-c C-o 2~ to open the current result at cursor in its source org file

    - This calls ~M-x org-open-at-point~ on the current entry and opens the second link in the entry.
    - The second link is the entries [[https://orgmode.org/manual/Handling-Links.html#FOOT28][org-id]], if set, or the heading text.
      The first link is the line number of the entry in the source file. This link is less robust to file changes.
    - Note: If you have [[https://orgmode.org/manual/Speed-Keys.html][speed keys]] enabled, ~o 2~ will also work

*** Khoj Menu
  [[/docs/khoj_emacs_menu.png]]
  Hit ~C-c s~ (or ~M-x khoj~) to open the khoj menu above. Then:
  - Hit ~t~ until you preferred content type is selected in the khoj menu

    ~Content Type~ specifies the content to perform ~Search~, ~Update~ or ~Find Similar~ actions on
  - Hit ~n~ twice and then enter number of results you want to see

    ~Results Count~ is used by the ~Search~ and ~Find Similar~ actions
  - Hit ~-f u~ to ~force~ update the khoj content index

    The ~Force Update~ switch is only used by the ~Update~ action

** Upgrade
*** Upgrade Khoj Backend
  #+begin_src shell
    pip install --upgrade khoj-assistant
  #+end_src

*** Upgrade Khoj.el
  Use your Emacs package manager to upgrade ~khoj.el~

  - For ~khoj.el~ from MELPA
    - Method 1
      - Run ~M-x package-list-packages~ to list all packages
      - Press ~U~ on ~khoj~ to mark it for upgrade
      - Press ~x~ to execute the marked actions
    - Method 2
      - Run ~M-x package-refresh-content~
      - Run ~M-x package-reinstall khoj~

  - For ~khoj.el~ from Straight
    - Run ~M-x straight-pull-package khoj~
