Installation

Khiip is two parts: the daemon (khiipd, the background service that captures, stores, and recalls) and the surface you drive it from — the CLI, an agent over MCP or REST, or the Obsidian plugin. This page installs the daemon; every surface talks to the same one on 127.0.0.1:8478.

Requirements

Python 3.10+ (the substrate is tested on CPython; the bundled embedder ships as ONNX)
~80MB free for the one-time MiniLM-L6 model fetch on first khiipd serve
Optional per-source credentials (see below) for sources that require your identity

Install

uv tool install khiip      # recommended — isolated, on your PATH
# or
pipx install khiip         # same isolation, via pipx
# or
pip install khiip          # into the current environment

This installs the khiipd CLI and the khiip-mcp-server console script.

Install from source instead

git clone https://github.com/KhiipAI/khiip.git ~/projects/khiip
cd ~/projects/khiip
pip install -e ".[dev]"

Default paths

Purpose	Path	Override
Config	`~/.config/khiip/`	`XDG_CONFIG_HOME`
Data (SQLite index)	`~/.local/share/khiip/`	`XDG_DATA_HOME`
Vault (Markdown captures)	`~/khiip-vault/`	`[daemon] vault_path`

See Configuration for the full picture, including the KHIIP_HOME test-only knob and why you should not set it in your shell rc.

Per-source credentials

Khiip plumbs between your upstream accounts and your local vault — it never holds upstream credentials of its own. Most sources work with no setup (X via fxtwitter, generic web via trafilatura, Wikipedia, Reddit via old.reddit HTML). A few accept your own platform credentials so requests go through your identity and your rate-limit budget for higher fidelity.

Reddit (optional — capture works credential-free)

Reddit captures work out of the box via the credential-free old.reddit.com HTML channel (live threads + full comment trees, self-hosted on your own IP). Configuring your own Reddit app is an optional upgrade: it adds cleaner deep-comment pagination plus a 60 req/min headroom and is tried first when present.

Visit https://www.reddit.com/prefs/apps → create another app… → choose script type → name it (e.g. khiip), set redirect uri http://localhost:8478/ (unused but required by the form) → create app.
Copy the client ID (the short string under the app name) and client secret.
Add them to ~/.config/khiip/config.toml:
```
[extractors.reddit]
client_id = "your-reddit-client-id"
client_secret = "your-reddit-client-secret"
```
…or set KHIIP_REDDIT_CLIENT_ID and KHIIP_REDDIT_CLIENT_SECRET before khiipd serve.

If a configured app is missing or expired, capture transparently falls back to the HTML channel rather than failing. The HTML channel is self-host-only by design (a datacenter IP would hit Reddit’s WAF and robots.txt).

YouTube (optional; widens the fallback chain)

Set a free Google Data API v3 key to add a third fallback source for metadata resilience when yt-dlp and youtube-transcript-api both fail:

[extractors.youtube]
api_key = "your-google-data-api-v3-key"

Verify

khiipd version
khiipd serve &
khiipd capture https://en.wikipedia.org/wiki/Quipu
khiipd recall "Inca knot record system"

If the capture lands in ~/khiip-vault/ and recall returns it, you’re set. Next: capture guides, wire up the MCP server or the Obsidian plugin, or turn on Khiip Plus for styled renders and deeper capture.