recap: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents - and humans - working in the RECAP repository. This is the single source of truth for how to set up, run, test, and change this project; tool-specific files (CLAUDE.md, etc.) import it. The human-facing overview is in README.md; the security policy is in SECURITY.md.

What RECAP is

RECAP is a local-first Chrome extension (Manifest V3) plus a local Python (FastAPI) RAG backend. It passively indexes the pages a user actually reads and lets them search their browsing history in natural language. Everything runs on the user's machine; page content only leaves the device when the user asks a question - and only the retrieved snippets, sent to the LLM provider the user configured.

Setup & run

Requires Docker (recommended) or Python 3.11+, plus Chrome. Three paths, all of which install spaCy + the en_core_web_sm model (so the knowledge graph works as soon as you opt in):

# Docker - recommended: reproducible, one command. Serves http://127.0.0.1:8000 (loopback only).
docker compose up --build

# uv - fast, reproducible local dev. `uv sync` installs deps + the spaCy model.
uv sync && uv run python main.py

# pip - simple fallback.
pip install -r requirements.txt && python main.py

pyproject.toml (+ uv.lock) is the canonical dependency set for uv/Docker; requirements.txt mirrors it for the pip path - keep the two in sync when changing versions. torch is pinned to the CPU wheel (tool.uv.sources) so images stay small and it runs anywhere; GPU users override it.

• Copy .env.example → .env and set at least one LLM key (or point at a local Ollama). See LLM & embeddings below.
• Docker + a host Ollama: the container can't see the host's localhost - set LLM_BASE_URL/EMBEDDING_BASE_URL to http://host.docker.internal:11434/v1 (compose already maps host.docker.internal).
• Load the extension: chrome://extensions → enable Developer mode → Load unpacked → select the extension/ folder.
• Knowledge graph: off by default - retrieval runs BM25 + dense vectors only. Opt in from the extension Options page toggle (calls POST /settings/kg; takes effect immediately, persisted in DB meta so it survives backend restarts and overrides .env), or set ENABLE_KG=true in .env for a config-only setup. The master switch gates both ingestion NER and the KG retrieval leg; a request's use_kg can never override it on. After enabling, backfill already-indexed pages without re-browsing via POST /maintenance/rebuild_kg (re-runs NER over stored text; SQLite is the source of truth). Entities need spaCy (installed by default).