lore-backend

The FastAPI service behind Lore — an engineering team's decision memory. Captures the why behind merged pull requests (via a GitHub App) and answers /why questions with cited, sourced answers.

A LangGraph agent that can go fetch what it doesn't have, over three memory tiers, behind a guardrail that won't ship an uncited answer. Runs entirely on free and self-hosted services.

Companion repos: lore-cli (the npx lore git-hook CLI that captures commit Why: trailers) and lore-vscode-extension.

For the design and the reasoning behind it, see ARCHITECTURE.md and ADR-0001.

Quickstart (self-host)

cp .env.example .env   # works as-is in MOCK mode — no keys required
docker compose up
curl localhost:8000/health

Postgres, Qdrant, the API and the worker, in one command.

• MOCK mode (no GROQ_API_KEY): answers come from token-overlap search over a curated seed corpus. Deterministic, no external calls — good for demos and CI.
• LIVE mode: add GROQ_API_KEY and restart for the agent loop, real retrieval, and real GitHub ingestion.

DATABASE_URL is required in both modes — the control plane and episodic memory live in Postgres regardless.

Install from PyPI

docker compose up stays the recommended way to run Lore — it brings its own Postgres and Qdrant. The package is for embedding the service in an existing deployment, or importing the memory layer directly:

pip install lore-backend
export DATABASE_URL=postgresql://lore:lore@localhost:5432/lore
lore-backend                 # the API server (--host/--port/--reload)
lore-backend-worker          # the background job worker

Both scripts read the same environment as the Docker stack (see .env.example); you supply Postgres and Qdrant yourself. Prompts and migrations ship inside the package, so procedural memory and the migration runner work from an install with no checkout.

Tech stack

No new cloud bill. Nothing here requires an account anywhere.

How an answer gets made

question → agent ─┬─(needs more)→ tools → agent
                  └─(has enough)→ guardrail → answer + citations

The model decides whether the Canon covered the question or whether it needs to go read the PR itself. Capped at 4 hops. Before anything reaches the user, the guardrail checks every citation against what retrieval actually returned — an answer citing a PR that was never retrieved does not ship.

Memory is three tiers, because they answer different questions: procedural (how to behave — prompts/*.md, git-versioned), semantic (durable distilled decisions — vector search), and episodic (dated events and past answers — SQL, ordered by time).

Details in ARCHITECTURE.md.

API

Eval

python -m lore_backend.eval.harness              # score the active path
python -m lore_backend.eval.harness --compare    # v1 pipeline vs v2 agent, same store
python -m lore_backend.eval.harness --judge      # add LLM-as-judge (LIVE only)

A golden question set scored for citation accuracy and relevance. Deterministic in MOCK mode, so tests/test_eval_harness.py holds a hit-rate floor as part of pytest, and the harness itself exits non-zero when the gate fails — run it before merging anything that touches retrieval. The LLM judge is observe-only until its scores have been checked against human reading.

The --compare mode is why the v1 pipeline is still in the tree: the loop has to out-perform something. Note that the agent path is non-deterministic — one run is a sample, not a measurement.

Tracing (optional)

docker compose -f docker-compose.yml -f docker-compose.langfuse.yml up

Open http://localhost:3000, create a project, put its keys in .env as LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY, restart the backend. Until then every trace call is a no-op — nothing in the request path depends on Langfuse being reachable.

Configuration

Everything lives in .env.example with safe defaults. The knobs worth knowing:

Local dev (no Docker)

python -m venv .venv && . .venv/Scripts/activate  # or source .venv/bin/activate
pip install -r requirements.txt
# Needs a reachable Postgres — `docker compose up postgres` or your own.
uvicorn lore_backend.main:app --reload --port 8000
# in another terminal:
python -m lore_backend.jobs.worker

Testing

pytest
ruff check .

Tests need a live Postgres (DATABASE_URL) — they run real migrations and truncate between cases rather than mocking the database. The agent, judge and summarizer are driven by scripted fakes, so the suite makes no network calls and needs no API keys.

tests/test_kafka_ingestion_demo.py needs the demo's own optional dependency (lore_backend/examples/kafka_ingestion/requirements.txt).

Deploying the GitHub App

Point the App's webhook URL at <your-host>/webhook/github and set GITHUB_WEBHOOK_SECRET / GITHUB_APP_ID / GITHUB_APP_PRIVATE_KEY. The payload shapes handled are in lore_backend/ingestion/webhook_handler.py.