Recall is a self-improving browsing agent: a Next.js UI sends tasks to a Python worker that controls a real browser (Playwright) using the Gemini Live API, while a Hub stores and retrieves learned shortcuts with semantic search (ChromaDB + Gemini embeddings).

• Screenshots from the automated browser are sent to Google’s Gemini APIs as part of the agent and observer flows. Treat tasks and pages as sensitive; do not run against private data you are not allowed to send to a third-party API.
• API keys stay on your machines / host env (e.g. worker/.env, Vercel env). They are not baked into the client.
• The Hub stores shortcut text and metadata locally under worker/data/ (vector DB). It is not encrypted by this repo; protect the worker host if you deploy.
• Sessions are oriented around your browser automation runs; this project does not implement enterprise compliance guarantees—use accordingly.

• Two processes in dev: run the Python worker and the Next.js app separately (uvicorn + npm run dev). The UI proxies to the worker; one alone is not enough.
• Python 3.11+ and Node 20+ are assumed; older versions may break.
• First startup can be slower while embeddings / vector DB warm up (the worker tries a warmup pass on boot).
• Production: if the frontend and worker are on different origins, configure CORS on the worker for your site URL (see deploy section below).
• WebSockets: the live preview uses WS; ensure your host/proxy allows WebSocket upgrades to the worker.

• Built for the Google Gemini API ecosystem (competition / hackathon submission style).
• Questions: open a GitHub issue or reach out via the contact info on your profile.

The browser app calls relative routes such as /api/run-agent; those routes proxy to the worker using WORKER_URL (server) and expose the UI to the worker via NEXT_PUBLIC_WORKER_URL (browser).

• Node.js 20+ (matches Next.js 16)
• Python 3.11+
• Gemini API key — Google AI Studio

Optional:

• Browser Use Cloud API key — remote browser + live preview URL; if unset, the worker uses local headless Chromium.

cd worker
python3 -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt
playwright install chromium

Configuration:

cp .env.example .env

Edit worker/.env:

ChromaDB persists under worker/data/chroma/ (created automatically; listed in worker/.gitignore).

Optional: seed demo shortcuts into the Hub:

python seed_shortcuts.py
# Reset and reseed:
python seed_shortcuts.py --clear

Start the API:

uvicorn main:app --host 0.0.0.0 --port 8000
# or: uvicorn main:app --host 0.0.0.0 --port ${WORKER_PORT:-8000}

Health check: GET http://127.0.0.1:8000/health

cd app
npm install

Create app/.env.local (not committed):

cp .env.example .env.local

Defaults point at http://127.0.0.1:8000. Edit if your worker uses another host or port:

# URL the Next.js server uses when proxying API routes (run-agent, run-ab-test, etc.)
WORKER_URL=http://127.0.0.1:8000

# URL the browser uses for Hub, observer, and WebSocket screenshot stream
NEXT_PUBLIC_WORKER_URL=http://127.0.0.1:8000

For local development, http://127.0.0.1:8000 is correct if the worker listens on that host/port.

npm run dev

Open http://localhost:3000.

Deploy the app/ directory as a Next.js project. Set the same variables in the host’s dashboard:

• WORKER_URL — public base URL of your deployed worker (must be reachable from Vercel’s servers).
• NEXT_PUBLIC_WORKER_URL — same URL, for client-side fetch and WebSocket (ws:// / wss:// is derived in code).

The worker’s CORS is configured for local Next.js by default. For production, add your deployed site origin (e.g. https://your-app.vercel.app) to allow_origins in worker/main.py (or extend the worker to read allowed origins from an environment variable).

With the worker venv activated:

cd worker
pytest tests/

Some tests expect optional dependencies or a running worker; see worker/tests/ for details.

See repository files for license information if present.