6 ms·

Lore – Give your coding agent the decisions your team made

47 points by tcballard 3mo ago

fishonbike 3mo ago
[flagged]
tcballard 3mo ago
Author here! Coding agents kept reworking decisions we'd already settled - reviving an approach we ruled out in an ADR, redoing something a requirement already pinned. The context was in the repo; the agent had no current view of it. Lore serves your team's durable knowledge - requirements, decisions, designs, roadmaps, prompts - all as typed Markdown, read-only to Claude Code / Cursor over MCP, so the agent cites your decisions instead of contradicting them. The bet: retrieval is deterministic. No embeddings, no vector store, no model call to pick what's relevant — same query, same bytes, same result, offline. It's not a RAG competitor; it composes — recall fuzzily, then verify the EXACT, CURRENT decision in Lore (it declines the ones you've superseded). Runs in CI (rac validate / rac gate) too. pipx install rac-core rac quickstart claude mcp add lore -- rac mcp What it isn't: a search index, a memory layer, or an AI feature — the engine makes no LLM calls, no telemetry unless you opt in. Early, and my corpus is small, so I'd like to hear where deterministic grounding breaks down for you vs. where fuzzy recall is enough. (Lore is the product; the engine under it is RAC — Requirements as Code, the `rac` package.) Apache-2.0, typed.
- vlindhol 3mo ago
  Hi! What I'm not quite getting from a cursory overview of the docs is how does RAC overlay overlapping decisions over each other? My mental model is a Docker overlay filesystem where RAC somehow manages to construct a cohesive view of the entire set of decisions over time, but how does that happen deterministically? Let's say ADR 1 specifies users are unique by e-mail and should be soft-deleted, and ADR 2 says users are unique by username. Will RAC pick up on the fact that users still need to be soft-deleted? Is there a lot of manual "reference ADR 1 from ADR 2" to help with determinism?
  - tcballard 3mo ago
    So rac doesn’t merge ADRs or infer that soft-deletes survive… supercession is managed by the status on one ADR saying Superseeded, and the other saying Supersedes. This is enforced by the CI pipelines you can use (GitHub, etc) I think your example is a bit more of a modelling question, and if soft-delete must outlive the uniqueness decision it should be its own requirement that’s persisted as RAC guarantees the graph stays consistent and current; it doesn’t guess which clause survives — that’s the users call.
    - vlindhol 3mo ago
      Gooot it, I was thinking there would be some merging happening, but that would be the task for an LLM I suppose :D Mental model fixed!
      - tcballard 3mo ago
        No worries, clearly better documentation would help!
alexmartos 3mo ago
How does this compare to CLAUDE.md and other Rules you can put in markdown?
- etoxin 3mo ago
  Or spec-driven AI development.
  - tcballard 3mo ago
    Good questions! Lore isn't really competing with CLAUDE.md, it sits under it. A CLAUDE.md (or AGENTS.md, etc) is typically hand-written, untyped, and never checked. Nothing stops it from still telling the agent to do something you reversed six months ago, and nobody validates it in CI. Lore keeps the actual decisions/requirements/designs as typed Markdown in your repo, and rac export --agent-rules generates those rules files from the decisions that are currently Accepted — superseded ones drop out automatically. So the rules file becomes a build artifact of your knowledge base instead of something you hand-maintain and hope stays current. (Note that in dogfooding Lore that its repo does exactly that: its CLAUDE.md is a ~20-line router into the validated corpus) The part that makes it more than markdown-with-a-schema is write-time enforcement. rac validate / rac gate run in CI and fail the merge if an artifact is malformed, a link is broken or ambiguous, or anything points at a superseded decision. At serve time it's a read-only MCP server doing deterministic retrieval — the exact current decision by ID, not similarity-ranked guesses. No RAG, no embeddings, no model call to decide what's relevant. On spec-driven dev (Spec Kit, OpenSpec, Kiro): those drive a change — proposal → design → tasks → implementation, usually archived when the feature ships. Lore holds the durable why that outlives any single change and gets served to the agent on every session. It's the layer above SDD, not a replacement — you'd point a spec tool at the decisions Lore is enforcing.
    - kkkuuuuuu 3mo ago
      everyone in ur life hates when you send them this claude output garbage or am i the naive one, replying to a claudebot instance like its a human with thoughts and feelings that might care
cisrockandroll 3mo ago
Bad timing either way epic games release
- tcballard 3mo ago
  Different beast — Epic's is version control, this grounds your agent in your team's decisions. Installs as rac either way, so the name's not load-bearing. But yeah, timing's a coincidence... just thought the name was cooler :D
  - slopinthebag 3mo ago
    LLM generated comments go against site guidelines.
    - tcballard 3mo ago
      I wrote this, I just spend enough time with LLMs to sound like one
      - watermarkhu 3mo ago
        Yeah every same human would use m-dashes in their sentences — it just makes sense
        tcballard 3mo ago
        Regardless - the emdash predated LLMs … but that’s going way off topic!
        croon 3mo ago
        > Regardless - the emdash predated LLMs … but that’s going way off topic! I'm too OCD to not point out this time it was a minus.
        LoganDark 3mo ago
brainless 3mo ago
I started building an app with similar goals but with the very different approach. I work on my own coding agent, https://github.com/brainless/nocodo https://github.com/brainless/nocodo, where I have been trying to build a provenance based engine that will generate or modify prompts to point to the decisions that a team has made. That work is in the branch: feature/praxis_agent_runtime While working on this I figured what if I build a proxy for coding agents - Claude Code, opencode, Codex, etc. support a proxy. This proxy would edit prompts and tool_calls and feed context from an internal index it will maintain. That index will contain git logs, GitHub/JIRA/etc tickets/epics, PRD or other documents, tech stack setup. It is just an idea and may not work but working at the proxy layer means this can be deployed at a team level, needs no MCP install and can re-shape prompts for everyone depending on the project. Wild idea perhaps.
- tcballard 3mo ago
  I think the proxy angle is genuinely appealing for the reasons you give: team-level, no per-dev install, reshape every agent's context from one place. We went down that exact fork and chose against it (wrote up the reasoning as an ADR if you want it). Instead of intercepting and rewriting prompts/tool_calls, Lore does context-supply + post-edit enforcement. Two things drove it: One, a proxy that silently rewrites what the agent sees is hard to audit so you can't review an injection that never lands anywhere, and when it misfires you're debugging an invisible middle layer. We wanted the injected context to be a file in the PR diff (a generated CLAUDE.md/rules file) and the rest to be explicit read tools the agent chooses to call. Two, and this is the part I'd flag for your index, the hard problem isn't delivery, it's knowing which decision is still current. An index built from git logs + tickets + PRDs is mostly stale or contradictory text; if a call got reversed six months ago, a fuzzy index will happily re-inject the old one. So that's where we spend the complexity budget: typed, human-reviewed decisions where "superseded" is enforced in CI, so the agent never gets handed a ruling you already overturned. Which is why I think these compose rather than compete. Your proxy is a delivery mechanism; it still needs a trustworthy source for "the decisions this team made." That's what Lore is, and it exports for exactly this — rac export --documents (JSONL) or --graph to feed an index, --agent-rules for the injection layer. Stay fuzzy and convenient at recall, point back at a deterministic source for the part that has to be exactly right. Keen to see where praxis_agent_runtime goes — provenance-first is the right instinct.
philbo 3mo ago
1. Write ADRs (or get agents to write them) 2. Commit ADRs to git 3. Mention ADRs in AGENTS.md
- deleted 3mo ago
  [deleted]
- tcballard 3mo ago
  I agree, that method might work if you are working solo or in a small team - but for organisations the ability to centrally manage and gate this sort of ruleset avoids drift.
  - Cthulhu_ 3mo ago
    You can manage ADRs centrally too, but you'll quickly need a dedicated sub-team / community / tribe / whatever to manage these thing.
  - eddd-ddde 3mo ago
    It's a good day to work in a monorepo :)
- mzhaase 3mo ago
  I have been doing this to great effect and it's maybe five lines instructions total.
- bitlad 3mo ago
  Yup. This works.
- hahahaa 3mo ago
  ADR means https://martinfowler.com/bliki/ArchitectureDecisionRecord.html https://martinfowler.com/bliki/ArchitectureDecisionRecord.ht...
tangweigang 3mo ago
[flagged]
messh 3mo ago
Seems a bit similar to spec driven development. How does it differ?
- tcballard 3mo ago
  So the line shifts, but I see it as SDD manages the change (spec → tasks → ship, then archive it); Lore holds the durable decisions that every change after it has to respect. think of it as a layer above SDD and not a competitor, so basically you point your spec tool at the constraints Lore enforces.
kkapelon 3mo ago
What exactly does rac validate do? How is it deterministic? Is there an example somewhere?
- tcballard 3mo ago
  [flagged]
c3z_ 3mo ago
great approach with dogfooding! the failure I hit most is not that the agent forgets, it is that it re-opens things the team already closed. So treating ruled-out paths as first-class is the right instinct quick question why mcp instead of cli tool? I'm mostly building the latter (less context burden), but help me understand your own ADR regarding this why not both? also after quick review on your doc I don't see where is ADR portal for humans? some plans for UX or this is inside git repo?
- tcballard 3mo ago
  thanks! the mcp is a wrapper around the cli! You can run “rac explorer” if you have installed the extra: pip install 'rac-core[explorer]' in terms of UX, working on a couple of improvements there but wanted to validate the idea first and get the integrations with common platforms like GitHub sorted first!
  - c3z_ 3mo ago
    my 3 cents as I'm working on agentic CRM add rac steward to check and validate "quality" of ADR (freshness, completness, clarity, brewity, etc.) so expect your tool to help clean it's own database ;)
    - tcballard 3mo ago
      hilarious, I literally did this today as part of the satellite repo “rac-ci” which has these in
vshulcz 3mo ago
[flagged]
bredren 3mo ago
Interesting approach. I am curious how this information stacks up over time and how efficient it is at incorporating decision knowledge into active context. I have taken a different approach: allow team members to sync all of their Claude Code and Codex transcripts on a project and give them a skill that lets them ask their AI why decisions were made. The skill I've built, /total-recall is backed by a Swift-based CLI that provides efficient query tooling that coding agents can use however they see fit to arrive at the answer. The corpus of data contextify queries is a SQL database managed by macOS and Linux clients. These clients ingest the jsonl files in realtime and optionally can sync transcript data through either a hosted or self-hosted server. This allows any team member to simply invoke the skill: "Why did we switch over to allauth from aws cognito? /total-recall." My experience is that Claude Code and Codex don't just land "near" a decision, but can assemble it from what is sometimes a winding pathway of research, benchmarking and experimentation. Rather than codify requirements into a separate spec, Contextify lets agents pair the state of the code with the conversational record. I have just released the free personal and source available self-hosted version of Contextify, I'd be glad for feedback. https://contextify.sh/teams/ https://contextify.sh/teams/, https://contextify.sh/self-hosted/ https://contextify.sh/self-hosted/
- tcballard 3mo ago
  So it seems to work quite well, as it’s been dogfooding itself for the past month… but only time will tell!
ChrisArchitect 3mo ago
Not to be confused with: Lore - Epic Games' open source version control system designed for scalability https://news.ycombinator.com/item?id=48571081 https://news.ycombinator.com/item?id=48571081
- tcballard 3mo ago
  Yeah, naming clash clearly an issue but fundamentally different products. Epic just have the recognition over someone building OSS for the first time
wek 3mo ago
[dead]
felixlu2026 3mo ago
[flagged]
madikz 3mo ago
[flagged]

47 points by tcballard 3mo ago

[flagged]

Author here! Coding agents kept reworking decisions we'd already settled - reviving an approach we ruled out in an ADR, redoing something a requirement already pinned. The context was in the repo; the agent had no current view of it. Lore serves your team's durable knowledge - requirements, decisions, designs, roadmaps, prompts - all as typed Markdown, read-only to Claude Code / Cursor over MCP, so the agent cites your decisions instead of contradicting them. The bet: retrieval is deterministic. No embeddings, no vector store, no model call to pick what's relevant — same query, same bytes, same result, offline. It's not a RAG competitor; it composes — recall fuzzily, then verify the EXACT, CURRENT decision in Lore (it declines the ones you've superseded). Runs in CI (rac validate / rac gate) too. pipx install rac-core rac quickstart claude mcp add lore -- rac mcp What it isn't: a search index, a memory layer, or an AI feature — the engine makes no LLM calls, no telemetry unless you opt in. Early, and my corpus is small, so I'd like to hear where deterministic grounding breaks down for you vs. where fuzzy recall is enough. (Lore is the product; the engine under it is RAC — Requirements as Code, the `rac` package.) Apache-2.0, typed.

vlindhol 3mo ago
Hi! What I'm not quite getting from a cursory overview of the docs is how does RAC overlay overlapping decisions over each other? My mental model is a Docker overlay filesystem where RAC somehow manages to construct a cohesive view of the entire set of decisions over time, but how does that happen deterministically? Let's say ADR 1 specifies users are unique by e-mail and should be soft-deleted, and ADR 2 says users are unique by username. Will RAC pick up on the fact that users still need to be soft-deleted? Is there a lot of manual "reference ADR 1 from ADR 2" to help with determinism?
- tcballard 3mo ago
  So rac doesn’t merge ADRs or infer that soft-deletes survive… supercession is managed by the status on one ADR saying Superseeded, and the other saying Supersedes. This is enforced by the CI pipelines you can use (GitHub, etc) I think your example is a bit more of a modelling question, and if soft-delete must outlive the uniqueness decision it should be its own requirement that’s persisted as RAC guarantees the graph stays consistent and current; it doesn’t guess which clause survives — that’s the users call.
  - vlindhol 3mo ago
    Gooot it, I was thinking there would be some merging happening, but that would be the task for an LLM I suppose :D Mental model fixed!
    - tcballard 3mo ago
      No worries, clearly better documentation would help!

alexmartos 3mo ago

How does this compare to CLAUDE.md and other Rules you can put in markdown?

etoxin 3mo ago
Or spec-driven AI development.
- tcballard 3mo ago
  Good questions! Lore isn't really competing with CLAUDE.md, it sits under it. A CLAUDE.md (or AGENTS.md, etc) is typically hand-written, untyped, and never checked. Nothing stops it from still telling the agent to do something you reversed six months ago, and nobody validates it in CI. Lore keeps the actual decisions/requirements/designs as typed Markdown in your repo, and rac export --agent-rules generates those rules files from the decisions that are currently Accepted — superseded ones drop out automatically. So the rules file becomes a build artifact of your knowledge base instead of something you hand-maintain and hope stays current. (Note that in dogfooding Lore that its repo does exactly that: its CLAUDE.md is a ~20-line router into the validated corpus) The part that makes it more than markdown-with-a-schema is write-time enforcement. rac validate / rac gate run in CI and fail the merge if an artifact is malformed, a link is broken or ambiguous, or anything points at a superseded decision. At serve time it's a read-only MCP server doing deterministic retrieval — the exact current decision by ID, not similarity-ranked guesses. No RAG, no embeddings, no model call to decide what's relevant. On spec-driven dev (Spec Kit, OpenSpec, Kiro): those drive a change — proposal → design → tasks → implementation, usually archived when the feature ships. Lore holds the durable why that outlives any single change and gets served to the agent on every session. It's the layer above SDD, not a replacement — you'd point a spec tool at the decisions Lore is enforcing.
  - kkkuuuuuu 3mo ago
    everyone in ur life hates when you send them this claude output garbage or am i the naive one, replying to a claudebot instance like its a human with thoughts and feelings that might care

cisrockandroll 3mo ago

Bad timing either way epic games release

tcballard 3mo ago
Different beast — Epic's is version control, this grounds your agent in your team's decisions. Installs as rac either way, so the name's not load-bearing. But yeah, timing's a coincidence... just thought the name was cooler :D
- slopinthebag 3mo ago
  LLM generated comments go against site guidelines.
  - tcballard 3mo ago
    I wrote this, I just spend enough time with LLMs to sound like one
    - watermarkhu 3mo ago
      Yeah every same human would use m-dashes in their sentences — it just makes sense
      - tcballard 3mo ago
        Regardless - the emdash predated LLMs … but that’s going way off topic!
        croon 3mo ago
        > Regardless - the emdash predated LLMs … but that’s going way off topic! I'm too OCD to not point out this time it was a minus.
      - LoganDark 3mo ago

brainless 3mo ago

I started building an app with similar goals but with the very different approach. I work on my own coding agent, https://github.com/brainless/nocodo https://github.com/brainless/nocodo, where I have been trying to build a provenance based engine that will generate or modify prompts to point to the decisions that a team has made. That work is in the branch: feature/praxis_agent_runtime While working on this I figured what if I build a proxy for coding agents - Claude Code, opencode, Codex, etc. support a proxy. This proxy would edit prompts and tool_calls and feed context from an internal index it will maintain. That index will contain git logs, GitHub/JIRA/etc tickets/epics, PRD or other documents, tech stack setup. It is just an idea and may not work but working at the proxy layer means this can be deployed at a team level, needs no MCP install and can re-shape prompts for everyone depending on the project. Wild idea perhaps.

tcballard 3mo ago
I think the proxy angle is genuinely appealing for the reasons you give: team-level, no per-dev install, reshape every agent's context from one place. We went down that exact fork and chose against it (wrote up the reasoning as an ADR if you want it). Instead of intercepting and rewriting prompts/tool_calls, Lore does context-supply + post-edit enforcement. Two things drove it: One, a proxy that silently rewrites what the agent sees is hard to audit so you can't review an injection that never lands anywhere, and when it misfires you're debugging an invisible middle layer. We wanted the injected context to be a file in the PR diff (a generated CLAUDE.md/rules file) and the rest to be explicit read tools the agent chooses to call. Two, and this is the part I'd flag for your index, the hard problem isn't delivery, it's knowing which decision is still current. An index built from git logs + tickets + PRDs is mostly stale or contradictory text; if a call got reversed six months ago, a fuzzy index will happily re-inject the old one. So that's where we spend the complexity budget: typed, human-reviewed decisions where "superseded" is enforced in CI, so the agent never gets handed a ruling you already overturned. Which is why I think these compose rather than compete. Your proxy is a delivery mechanism; it still needs a trustworthy source for "the decisions this team made." That's what Lore is, and it exports for exactly this — rac export --documents (JSONL) or --graph to feed an index, --agent-rules for the injection layer. Stay fuzzy and convenient at recall, point back at a deterministic source for the part that has to be exactly right. Keen to see where praxis_agent_runtime goes — provenance-first is the right instinct.

philbo 3mo ago

1. Write ADRs (or get agents to write them) 2. Commit ADRs to git 3. Mention ADRs in AGENTS.md

deleted 3mo ago
[deleted]
tcballard 3mo ago
I agree, that method might work if you are working solo or in a small team - but for organisations the ability to centrally manage and gate this sort of ruleset avoids drift.
- Cthulhu_ 3mo ago
  You can manage ADRs centrally too, but you'll quickly need a dedicated sub-team / community / tribe / whatever to manage these thing.
- eddd-ddde 3mo ago
  It's a good day to work in a monorepo :)
mzhaase 3mo ago
I have been doing this to great effect and it's maybe five lines instructions total.
bitlad 3mo ago
Yup. This works.
hahahaa 3mo ago
ADR means https://martinfowler.com/bliki/ArchitectureDecisionRecord.html https://martinfowler.com/bliki/ArchitectureDecisionRecord.ht...

tangweigang 3mo ago

[flagged]

messh 3mo ago

Seems a bit similar to spec driven development. How does it differ?

tcballard 3mo ago
So the line shifts, but I see it as SDD manages the change (spec → tasks → ship, then archive it); Lore holds the durable decisions that every change after it has to respect. think of it as a layer above SDD and not a competitor, so basically you point your spec tool at the constraints Lore enforces.

kkapelon 3mo ago

What exactly does rac validate do? How is it deterministic? Is there an example somewhere?

tcballard 3mo ago
[flagged]

c3z_ 3mo ago

great approach with dogfooding! the failure I hit most is not that the agent forgets, it is that it re-opens things the team already closed. So treating ruled-out paths as first-class is the right instinct quick question why mcp instead of cli tool? I'm mostly building the latter (less context burden), but help me understand your own ADR regarding this why not both? also after quick review on your doc I don't see where is ADR portal for humans? some plans for UX or this is inside git repo?

tcballard 3mo ago
thanks! the mcp is a wrapper around the cli! You can run “rac explorer” if you have installed the extra: pip install 'rac-core[explorer]' in terms of UX, working on a couple of improvements there but wanted to validate the idea first and get the integrations with common platforms like GitHub sorted first!
- c3z_ 3mo ago
  my 3 cents as I'm working on agentic CRM add rac steward to check and validate "quality" of ADR (freshness, completness, clarity, brewity, etc.) so expect your tool to help clean it's own database ;)
  - tcballard 3mo ago
    hilarious, I literally did this today as part of the satellite repo “rac-ci” which has these in

vshulcz 3mo ago

[flagged]

bredren 3mo ago

Interesting approach. I am curious how this information stacks up over time and how efficient it is at incorporating decision knowledge into active context. I have taken a different approach: allow team members to sync all of their Claude Code and Codex transcripts on a project and give them a skill that lets them ask their AI why decisions were made. The skill I've built, /total-recall is backed by a Swift-based CLI that provides efficient query tooling that coding agents can use however they see fit to arrive at the answer. The corpus of data contextify queries is a SQL database managed by macOS and Linux clients. These clients ingest the jsonl files in realtime and optionally can sync transcript data through either a hosted or self-hosted server. This allows any team member to simply invoke the skill: "Why did we switch over to allauth from aws cognito? /total-recall." My experience is that Claude Code and Codex don't just land "near" a decision, but can assemble it from what is sometimes a winding pathway of research, benchmarking and experimentation. Rather than codify requirements into a separate spec, Contextify lets agents pair the state of the code with the conversational record. I have just released the free personal and source available self-hosted version of Contextify, I'd be glad for feedback. https://contextify.sh/teams/ https://contextify.sh/teams/, https://contextify.sh/self-hosted/ https://contextify.sh/self-hosted/

tcballard 3mo ago
So it seems to work quite well, as it’s been dogfooding itself for the past month… but only time will tell!

ChrisArchitect 3mo ago

Not to be confused with: Lore - Epic Games' open source version control system designed for scalability https://news.ycombinator.com/item?id=48571081 https://news.ycombinator.com/item?id=48571081

tcballard 3mo ago
Yeah, naming clash clearly an issue but fundamentally different products. Epic just have the recognition over someone building OSS for the first time

wek 3mo ago

[dead]

felixlu2026 3mo ago

[flagged]

madikz 3mo ago

[flagged]