# Project pack: Khoj @ ae229ca

Facts about **Khoj** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v4.md). Pinned to one version; never changes after publication.

> Khoj is an AI assistant that reads your own notes and files (PDFs, Word, Markdown, Obsidian, Notion) and answers questions about them, alongside fresh results from the web. You can make custom helpers with their own personality, schedule regular research emails, and reach it from the browser, Obsidian, Emacs, the desktop or your phone. It works with local models through Ollama or with cloud models such as ChatGPT, Claude and Gemini.

## Setup path (checked 2026-11-03)
- **Needs Docker.** Tell the person before any setup work; no light non-Docker route is documented upstream. A pip install exists but needs Postgres with pgvector; judged too heavy for a one-sitting non-technical setup. Docker Desktop on Windows may need a computer restart and an admin-only Windows feature (virtualisation); say so and let the person decide.
- Verdict source: https://docs.khoj.dev/get-started/setup
- You may be unable to download source archives or run commands in this session. The person downloads and runs things; if you cannot fetch something, give any changed file in full in chat with its path.

## Version and source
- Repository: https://github.com/khoj-ai/khoj
- Pinned commit: `ae229ca894c0b80ad84664afcfdde523b5e87057`. Use exactly this version.
- Zip the person can download in a browser: https://github.com/khoj-ai/khoj/archive/ae229ca894c0b80ad84664afcfdde523b5e87057.zip
- Fresh checkout (only if you have a shell and git): use the commands below in an empty folder. If this exact source is already checked out, keep your branch and use the development command; do not clone again or reset local changes.
- Official docs: https://docs.khoj.dev
- Licence: **AGPL-3.0-or-later**. Free to use and change. If you run a changed version that other people use over the internet (not just your own household), you must offer them your source code under the same licence. Private use has no extra obligations.

## Commands from the pinned source
- Developer commands (they may use Docker):

  ```sh
  git clone https://github.com/khoj-ai/khoj bespoke-khoj
  cd bespoke-khoj
  git checkout --detach ae229ca894c0b80ad84664afcfdde523b5e87057
  # Prepare development requirements and local configuration first.
  # Setup notes: needs a local Postgres with pgvector; see documentation/docs/contributing/development.mdx
  uv sync --all-extras && (cd src/interface/web && bun install && bun export) && khoj -vv --anonymous-mode
  ```

- Separate trial of the current upstream release (not your changes; sample data and a separate data directory only):

  ```sh
  mkdir ~/.khoj && cd ~/.khoj
  wget https://raw.githubusercontent.com/khoj-ai/khoj/ae229ca894c0b80ad84664afcfdde523b5e87057/docker-compose.yml
  # edit docker-compose.yml: set KHOJ_ADMIN_PASSWORD and KHOJ_DJANGO_SECRET_KEY, and an AI key (or OPENAI_BASE_URL for Ollama)
  docker compose up
  # wait for "Khoj is ready to engage", then open http://localhost:42110 (admin panel at /server/admin)
  ```
- Tools these commands use: Docker with Docker Compose (on Windows, WSL2), 8 GB RAM or more is comfortable; a GPU helps for local models, For development, Python 3.10–3.12 with uv, Postgres with pgvector, and bun for the web app
- Develop: `uv sync --all-extras && (cd src/interface/web && bun install && bun export) && khoj -vv --anonymous-mode   # needs a local Postgres with pgvector; see documentation/docs/contributing/development.mdx`
- Test: `pytest`
- Check/lint: `mypy`
- Stack: python, typescript (Django, FastAPI, Next.js, React, Tailwind CSS, sentence-transformers). Difficulty for a non-developer with an AI: **advanced**. A Python (Django + FastAPI) server with a Next.js web app, plus Obsidian, Emacs, desktop and Android clients in the same repo. Models, agents and search providers are set in the admin panel or compose file. Code changes need Python 3.10–3.12, Postgres with pgvector, uv and bun, and the web app must be exported into the server before testing.
Personal data: **yes**. Stored in: Notes, document text, embeddings, chats, agents and automations in PostgreSQL with pgvector (khoj_db volume). Downloaded search models in khoj_models; settings in khoj_config. Secrets are entered by the person, never in chat.

---
Later, only when a step needs it: [reference.md](https://handoff.bespokeai.software/p/khoj/ae229ca/r3/reference.md) (customisation points, must-keep-working, data and costs, coding conventions) · [hosting.md](https://handoff.bespokeai.software/p/khoj/ae229ca/r3/hosting.md) (long-term hosting; hosts are paid third parties) · [bespoke.yaml](https://handoff.bespokeai.software/p/khoj/ae229ca/r3/bespoke.yaml) · [SKILL.md](https://handoff.bespokeai.software/p/khoj/ae229ca/r3/SKILL.md)