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/        services      lore-api · stations · mcp-server · web-ui
             images/tools  lore-code-trace (Go binary) · 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 (the `lore-platform` umbrella chart) · compose.yaml · chart-ci-values
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 · infra & glue scripts
docs/        guides & longer-form docs

npm workspaces are libs/* plus each Node app listed explicitly in the root package.json. Two apps sit outside them: web-ui (standalone Next.js, its own lockfile) and lore-code-trace (Go, no package.json).

Every app and library documents itself in its own README — the shared code starts at libs/shared, libs/assembly-lines, and libs/server-core; the deployables are linked from the table below.

Deployables

Five workloads ship as one umbrella Helm chart, lore-platform, which spans a namespace per subchart. Each owns one thing, and the boundaries are enforced by credentials rather than convention.

Deployable	Namespace	What it owns
lore-api (apps/lore-api)	lore-api	The remote REST backend (/api/*) — hybrid search, agent memory, task CRUD, ingest (ADR-032), and the door for GitHub's webhooks (POST /api/webhook/github; the public /api/events URL is rewritten onto it), which it writes to pipeline.events itself (ADR-044). No MCP.
stations (apps/stations)	lore-stations	Service stations, reached by name over POST /api/stations/{name}. Also the scheduler: it emits the cron.*.tick events and answers them, drains the PR-lifecycle events, and hosts Lore's stations for the external floor.
lore-mcp gateway (apps/mcp-server)	lore-api	The same MCP adapter served over HTTP, so agent pods get live scoped Lore access for a whole run instead of a one-shot hydration. Also serves the agent-skills registry.
web-ui (apps/web-ui)	lore-ui	The Next.js dashboard. Holds no database pool — it reads through lore-api. Its chart also runs the ordered SQL migrations hook on every deploy.
lore-db (charts/lore-db-helm)	lore-db	PostgreSQL + pgvector via CloudNativePG. Schema-per-team isolation.

The assembly-line engine is not one of them: every line runs on the external floor (re-cinq/floor, ADR-049), deployed beside the umbrella and reached only through its client. Lore's own Floor (apps/floor) was deleted on 2026-10-02.

Dgraph — the spec-traceability graph — is deployed alongside the umbrella from terraform rather than as a subchart. apps/mcp-server also runs on each developer's laptop over stdio; apps/lore-code-trace is a binary, not a service.

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: drains the event bus, walks AssemblyRuns, dispatches Stations, reaps leases	1 → N (per team / cluster / trust tier)
AssemblyLine	the authored blueprint — a graph of Stations with distinct responsibilities that hand off / wait on each other	per task type
AssemblyRun	one execution of an AssemblyLine, which clones the blueprint at start and reads the clone thereafter, so an edit cannot change the graph under a walk in flight	per attempt
Station	the unit that runs exactly one piece of work — an Agent pod, a station of the stations service, a human station whose worker is a person (it names the page they act on), or a service station reached by name over HTTP	per node
StationRun	one visit to a Station within an AssemblyRun — a revisit under iteration_max is a new StationRun	per visit
Agent	a single ephemeral run of the Claude CLI/API + a prompt (context + task)	per Station

Hierarchy: Factory ⊃ Floor(s) ⊃ AssemblyRuns ⊃ StationRuns ⊃ Agents — blueprint-side, AssemblyLine ⊃ Stations.

"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).

Issue Triage Flow

Lore automates bug triage through a dedicated assembly line that verifies, diagnoses, and routes incoming issues before they reach a human maintainer. When an issue is labeled triage: needs-triage (or lore:triage), the following automated flow occurs:

1. Bug Reproduction: A sandboxed agent attempts to reproduce the bug by running the provided reproduction repository.
2. Root Cause Diagnosis & Spec Verification: If reproduced, an agent traces the error to pinpoint the root cause and cross-references it with existing documentation and specifications to ensure it is a genuine bug.
3. Obsolete/Large Issue Detection: Issues describing problems already solved are automatically closed as obsolete. Complex, multi-part issues are decomposed into smaller, linked tasks.
4. Human-Gated Handoff: Once verified and diagnosed, the issue pauses for human review. A maintainer can then apply the lore:implementation label to transition it to the implementation loop.

Triage Label Taxonomy

The triage flow is tracked via the triage:* label taxonomy:

• triage: needs-triage — Initial state; triggers the automated assembly line.
• triage: needs-reproduction — Applied if the reproduction step fails due to missing information.
• triage: reproduced — Applied after the agent successfully reproduces the bug.
• triage: unable-to-reproduce — Applied if the agent fails to reproduce the bug.
• triage: diagnosed — Applied after successful root cause diagnosis and verification against specs.
• triage: skipped — Applied if execution is skipped due to environment constraints (e.g., missing hardware or external services).
• triage: not-actionable — Applied if the issue is deemed invalid, intended behavior, or noise.
• triage: failed — Applied if the triage pipeline crashes or exhausts its retries.

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, and execution modes
• 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.