Lore

Shared context infrastructure for Claude Code.
Org awareness + agent memory + task pipeline in one platform.

---

What is Lore?

Lore is the shared context layer that makes Claude Code organization-aware. Developers open Claude Code and it already knows: org-wide conventions, team-specific patterns, architectural decisions, and current task state — without any manual context loading.

Beyond context, Lore is an agent operating system. It runs background agents that onboard repos, detect documentation gaps, check for spec drift, and review PRs — all producing pull requests that humans review and merge.

Repository layout

apps/        deployable services        floor · lore-api · mcp-server · web-ui · vscode-extension
libs/        shared libraries           shared (@re-cinq/lore-shared) · assembly-lines (@re-cinq/lore-assembly-lines) · server-core (@re-cinq/lore-server-core)
infra/       deploy & runtime           terraform · compose.yaml
specs/       speckit specs (spec/plan/tasks/contracts) — first-class, links into code
adrs/        architecture decision records (MADR)
runbooks/    incident & operational runbooks        teams/  per-team CLAUDE.md
scripts/     install.sh · lore-doctor · task-types.yaml · infra & glue scripts
docs/        guides & longer-form docs

npm workspaces live under apps/* + libs/*; web-ui is a standalone Next.js app (its own lockfile, not a workspace).

The context lifecycle

Context is collected from repos and agent activity, stored in PostgreSQL (vectors + knowledge graph), and pulled on demand into Claude Code. Every session can feed new learnings back in, so the store compounds over time.

flowchart LR
    subgraph collect["1 · Collect / Create"]
        direction TB
        SRC["Repo files<br/>CLAUDE.md · ADRs · runbooks · specs · code"]
        PRH["PR history &amp; outcomes<br/>(merge-check)"]
        SESS["Agent sessions<br/>episodes · tool calls (Stop hook)"]
        MEMW["Explicit memory<br/>lore_write_memory · lore_write_episode"]
    end

    subgraph store["2 · Store — PostgreSQL + pgvector"]
        direction TB
        CHUNKS[("chunks<br/>content + 768-d embeddings<br/>schema-per-team")]
        EPIS[("episodes / memories")]
        FACTS[("facts<br/>temporal validity · confidence")]
        GRAPH[("entities + edges<br/>knowledge graph")]
    end

    subgraph pull["3 · Pull / Retrieve"]
        direction TB
        ASM["lore_assemble_context<br/>one-call, token-budgeted bundle"]
        SEARCH["lore_search_context · lore_search_memory<br/>hybrid: vector + BM25 (RRF)"]
        QG["lore_query_graph"]
    end

    SRC -->|"ingest: chunk + embed"| CHUNKS
    PRH --> EPIS
    SESS --> EPIS
    MEMW --> EPIS
    EPIS -->|"LLM fact extraction"| FACTS
    EPIS -->|"entity extraction"| GRAPH

    CHUNKS --> ASM
    FACTS --> ASM
    GRAPH --> ASM
    CHUNKS --> SEARCH
    FACTS --> SEARCH
    GRAPH --> QG

    ASM --> CC["Claude Code<br/>&amp; background agents"]
    SEARCH --> CC
    QG --> CC
    CC -.->|"new learnings feed back"| MEMW

Loading

Terminology

Lore is modeled as an autonomous software factory ("Dark Factory" is a mode of it). One vocabulary is used everywhere — code, specs, ADRs (see ADR-024):

Term	What it is	Cardinality
Factory	the whole platform — Lore itself	1
Floor	the long-running coordinator runtime: dispatches Agents onto Stations, runs the AssemblyLines, reaps leases	1 → N (per team / cluster / trust tier)
AssemblyLine	a graph of Stations with distinct responsibilities that hand off / wait on each other	per task
Station	the unit that runs exactly one Agent — a Kubernetes Job pod, or a local sandbox/worktree	per task-run
Agent	a single ephemeral run of the Claude CLI/API + a prompt (context + task)	per Station

Hierarchy: Factory ⊃ Floor(s) ⊃ AssemblyLines ⊃ Stations ⊃ Agents.

"Agent" means only the Claude-CLI-plus-prompt run — not the pod that hosts it (a Station) nor the coordinator that dispatches work (the Floor). The coordinator deployment was historically called "Lore Agent"; it is now the Floor (apps/floor, the lore-floor deployment).

How Lore connects to Claude Code (in plain terms)

When you install Lore, Claude Code starts talking to a small Lore program running on your laptop. That program is the only piece that speaks Claude Code's language (a protocol called MCP). It doesn't hold any of the org's knowledge itself — instead it forwards requests to the Lore cloud service over the internet, where the shared database lives.

Why the split?

• The shared knowledge — conventions, memories, history — lives in one place in the cloud, so every developer sees the same thing.
• But some things can only happen on your laptop: knowing which repository you're in, running your project's tests, or doing work on your own Claude subscription. Those stay local.

So the laptop program is a translator and a doorway: Claude Code → local Lore program → Lore cloud. The cloud service itself is a plain authenticated web API — it is deliberately not a second MCP server (see ADR-032 for why).

To keep this fast and resilient, the local program keeps a short-lived cache of recent lookups: repeat questions are answered instantly, and if the cloud is briefly unreachable you still get recent answers (clearly marked as cached). Saving or changing anything always goes straight to the cloud.

For the full list of what Claude can do with Lore, in plain language, see the Lore Tools guide.

Documentation

Pick the guide that matches what you're doing.

Using Lore

• Lore Tools — Plain-Language Guide — what each Lore tool does, and whether it runs in the cloud or on your machine
• Developer Guide — org context in Claude Code, the MCP tool catalog, the local task runner, and GitHub/Slack dispatch
• Product Manager Guide — turn a plain-language idea into a spec and a merged PR
• Platform Engineer Guide — onboard repos, tune settings, monitor the pipeline, analytics, and API security
• Installation & Deployment — deploy the Lore backend on GKE

Building Lore

• Architecture — topology, task lifecycle, scheduling, ingestion, memory, execution modes, and Dark Factory mode
• Scheduled Jobs — the recurring job registry
• Contributing — run the stack locally, project layout, tech stack, and design principles

Quickstart

git clone git@github.com:re-cinq/lore.git
cd lore && scripts/install.sh

This configures the MCP server, skills, hooks, statusline, and agent ID. The MCP server runs locally over stdio but proxies all operations to the GKE backend — so the backend must be deployed first. See docs/INSTALL.md for the complete deployment guide.

Then open Claude Code and type /lore-help — what Lore does, how a session works, every skill, and which one fits the job you're on.

Developing Lore itself

To run the whole stack on your own machine instead of against a deployed backend:

npm install
npm run dev-setup   # one-time: toolchain check + credentials into .env.local
npm start           # Postgres + Dgraph + minikube agents + every service, live reload

This needs Node.js >= 20 plus docker, docker compose v2, minikube, kubectl, helm, and claude on your PATH. Contributing walks through all three steps, the ports, and how to tear it all down and start over.

License

Apache License 2.0 — see LICENSE.