Start

The problem · What is Lore · How it works · Benchmark · Installation

Use it

Architecture · The eight skills · Obsidian · Documentation

Understand it

Shared invariants · Case studies · Reach · Origin

The problem

You open a session. You explain, again, what the project is for. Which approach you already tried and why you dropped it. Which shortcut cost you an afternoon last month, and which decision you are not reopening.

You explained all of it yesterday. You will explain it again tomorrow.

Meanwhile you keep paying to learn: architectural decisions, production incidents, failed experiments, dozens of "let's never do that again" moments. That is what actually cost you, and none of it survives the session.

It is a loop of re-explanations and mediocre solutions you had already rejected. Lore calls this ephemeral experience: the facts may survive, but the learning never became a reusable structure.

The picture is Groundhog Day. The world resets and the only thing that crosses the reset is what Phil learned — the facts are wiped every February 2nd, the criteria are not. Every session of an agent is a February 2nd.

Traditional documentation solved part of the problem, but it only preserves information. Manuals describe procedures, READMEs explain installs, databases store facts. They rarely capture what actually changes a future decision.

What is Lore

A lightweight, provider-neutral Spec-Driven Development kit for AI agents. Or, in one line: local fine-tuning for your own tasks, and the one doing the training is you.

A fine-tune conditions a model on thousands of examples until it stops answering like a generalist. Lore gets to the same place from the other side: one written constraint per thing that went wrong. No training happens and no weights move, so your criteria stays as plain text you can read, correct in one line, and carry to a different model tomorrow.

A fine-tune stops asking things of you the day it ships. Lore never stops: one distillation, every time something breaks. That is the cost, and it is worth knowing before you install anything.

It provides three things:

  • a simple convention for organizing a project's criteria;
  • eight skills that operate that convention;
  • and a continuous loop for distilling experience into reusable criteria.

Spec-driven is not a label here. The project has one host-selected contract—CLAUDE.md for Claude Code or AGENTS.md for Codex—FASES.md is the state, the roadmap and the task list, and lore/ is the criteria that constrains how any of it gets built. If you use both hosts, Codex can fall back to CLAUDE.md; you still do not need two contracts.

Which contract should you keep? Use CLAUDE.md when Claude Code is your regular host and AGENTS.md when Codex is. For a Claude-first project that occasionally opens in Codex, add project_doc_fallback_filenames = ["CLAUDE.md"] to your Codex config.toml (official reference). Only create a pointer adapter when the other host cannot be configured and you explicitly choose that tradeoff; never keep two copies of the rules.

Unlike documentation, Lore does not try to describe everything. It only preserves what changes future behavior.

A README answers "what is this?". Lore answers something else: What did we learn that we should never have to learn again?

[!IMPORTANT] If a sentence does not constrain a future decision, it is not Lore. That rule is the whole filter, and it is what keeps the system from becoming another graveyard of documents.

How it works

Every solved problem contains two things: the solution, and the reason that solution exists. Documentation keeps the first. Lore keeps the second.

Instead of recording what happened, it distills it into an Invariant Clue: a small constraint that stays useful long after the original context is gone.

Instead of remembering Lore keeps
"The AI wrote a report that was too technical for the reader" "Before drafting, identify who will read it and explain every unfamiliar term in plain language"
"A meeting summary omitted who was responsible for each task" "Every meeting summary ends with each task, its owner and its deadline"

The event is forgotten. The criteria keeps working.

The loop

Every step of the loop passes a threshold: it is proposed, you approve, only then it is written.

Installation

Choose one of the following routes. Claude Code and Codex use different commands; do not mix them.

Claude Code

Run these commands inside Claude Code:

/plugin marketplace add andresanemic/lore-plugin
/plugin install lore@lore-plugin

Or run their CLI equivalents from a terminal:

claude plugin marketplace add andresanemic/lore-plugin
claude plugin install lore@lore-plugin

Codex CLI

Run these commands in your terminal:

codex plugin marketplace add andresanemic/lore-plugin
codex plugin add lore@lore-plugin

Direct install from the repository

Use this provider-neutral route when you prefer a local clone or want to prepare both CLIs. It requires Git and Node.js:

git clone https://github.com/andresanemic/lore-plugin.git
cd lore-plugin
node scripts/lore-plugin.mjs install --target all
codex plugin add lore@personal

Replace all with claude or codex to target only one CLI. The installer configures Claude directly; for Codex it prepares the local personal marketplace and prints the final codex plugin add command.

Then start a new CLI session and type use-lore; the kit points you at the skill you need.

Using another AI tool? Each skill is a Markdown file with a YAML header. Copy the skill folder into that tool's supported skills directory, or use its body as agent instructions. The six-piece architecture and the Area↔Project model are provider-neutral conventions, not code.

What it looks like in practice

You just spent two hours chasing a bug: some dates showed up one day off, but only for some people. You found it. Instead of closing the tab:

› save to lore

  Distilled this:

  [dates] Off-by-one day — dates stored with a local timezone

  Context ······· the server runs in UTC, the users do not
  Root cause ···· each date was saved with the timezone of whoever
                  created it, so the same record read differently
                  depending on who opened it
  Clue ·········· always store dates in UTC. Convert only when
                  displaying, never when saving
  Confidence ···· confirmed — verified in production

  → projects/client-a/lore/dates.md
  → this Clue is generic and confirmed: promote it to the Area,
    so the other 3 projects see it?

  Write it?

Three months later, in another project of the Area, someone adds a calendar. The criteria is already loaded and that bug never happens again.

None of it was written without a human saying yes. The same gate governs all eight skills.

Architecture

The six pieces

Every project organizes its criteria and state through six structural pieces. They are not necessarily six files: thematic modules are one piece implemented by as many focused files as the work earns.

Piece What it holds Where
identidad.md What the project is, its purpose and its quality floor lore/
principios.md Invariant laws, technical and business: prohibitions and imperatives lore/
Thematic modules Technical scars by domain (animation, layout, scroll…) lore/
index.md Navigation map: one line per pattern lore/
FASES.md State and roadmap: current phase, focus root
CLAUDE.md or AGENTS.md One collaboration contract, selected by primary host and slimmed to pointers root

Each has one responsibility. None duplicates another.

Lore is criteria (it persists); FASES.md is state (it advances). They never mix, and FASES.md never lives inside lore/.

The clearest picture of why these are two files and not one is 50 First Dates. Lucy wakes with no memory and watches a video that brings her up to date, and the video works because it hands her both things at once: who she is, and where things stand. It is not her memory — give her everything she ever lived and she could not carry it, give her only the facts and she would not know what to do with them. Here the two halves stay in separate files because they age at different speeds.

The names shown are the Spanish canonical forms; in your language they localize.

The always-on block

The contract is the only artifact both hosts load without being asked, which makes it the kit's always-on channel. Its pointer section is delimited so it can be found and re-stamped without touching anything else:

Why a delimited block and not just a paragraph. One piece loads first, without exception, and only then can the rest be read in any order. It is not a hierarchy of importance: the anchor is what makes everything behind it legible.

<!-- lore:always-on -->
…what Lore governs here · where it lives · where the state lives · when to invoke instead of writing by hand…
<!-- /lore:always-on -->

Four things and no more, under a hard ceiling of 25 lines. It points at lore/, and at FASES.md in one line — criteria and state are stored apart, but the session that receives them cannot read twice, and an agent that has the criteria and not the phase proposes correctly and out of order. It never reproduces a clue. If a variant does not fit, the answer is to move content into lore/, not to raise the ceiling.

Three variants: an area points at its own lore/; a project at its own layer and its mother area's; a bot at canon/ and its routing table — never at the federated Lores one by one, which is why a bot that reaches twenty bodies of criteria still fits.

Stamping is idempotent and belongs to the skills that already write the contract, inside the threshold they already have. transmute-lore UPGRADE adds it to contracts that predate it. Identical content is a no-op that writes nothing; a block edited by hand is a divergence that gets reported, never overwritten. The marker pair is literal and never localizes.

Area → Project inheritance

Lore scales through Areas. An Area is a mother folder with its own Lore, and projects inherit it instead of copying it:

web-development/
│
├── lore/                      ← general criteria lives ONCE
│     identity · principles · index · animation · scroll · layout
│
├── PHASES.md                  ← the Area's project registry
├── CLAUDE.md or AGENTS.md     ← the Area's one host-selected contract
│
└── projects/
    ├── client-a/
    │   └── lore/              ← only its own; the index points at the Area
    ├── client-b/
    │   └── lore/
    └── client-c/
        └── lore/

Fix a generic Clue once, in the Area, and every project sees it. Each project keeps only what belongs to it: the system stays DRY without losing accumulated experience.

The third shape: a bot

Area Project Bot
Holds projects one piece of work a work session
Its Lore governs the domain's method that work how the agent behaves
Opened to see the registry advance that work work on any of several projects

Areas and projects are places; a bot is a lens you carry into them. It is not an Area, because it owns none of the criteria it routes to. An Area that collects criteria it never earned starts receiving promotions that belong somewhere else.

The eight skills

Skill What for When
use-lore Entry point: explains the model and routes you to the right skill first, always
brainstorming-lore Designs changes to Lore artifacts without colliding with general-purpose brainstorming skills before creating or materially restructuring Lore
create-area Creates an Area with its shared Lore opening a new domain
create-project Creates a project that inherits from the Area starting a piece of work
save-to-lore Distills a lesson and decides whether it rises to the Area every day
transmute-lore Migrates, cleans, translates, upgrades, prunes or exports a safe snapshot of Lore inheriting, maintaining, updating or sharing Lore
create-bot One place to open a session and work across several Areas at once once there is Lore worth gathering
obsidian-lore Mines loose notes and routes what survives once the inbox gets heavy

use-lore

2.0 rename: using-lore is now use-lore. Remove the old skill when updating; do not keep both names installed, because duplicate entry-point triggers make routing ambiguous.

The entry point. Explains Lore's model, the six-piece standard, the Area↔Project model, and routes you to the right skill. Read it before invoking any other.

brainstorming-lore

The kit's own design conversation. It is deliberately narrow: it activates for Lore, bots, Areas, projects and phases—not for general ideation—and hands the approved result to the skill that owns the artifact and its threshold.

create-area

Creates a new Area with its own shared Lore: identity + principles, an index.md, one host-selected contract, a PHASES.md acting as project registry, and an empty projects/ folder. It brainstorms the identity before touching disk.

create-project

Creates a project inside an existing Area. The project inherits the Area's criteria instead of duplicating it: it keeps its own identity and principles, plus an index.md that points at the Area's modules by relative path. Folder structure and phases are derived from the project's source documents, not from a generic template.

save-to-lore

The flow you will use every day. You solve something that cost you, and you type:

"save to lore"

The skill extracts the criteria behind the solution, writes it where it belongs, and proposes — never executes — promoting it to the Area if it serves every project.

  • Specific lessons stay inside the project.
  • Generic, confirmed ones are proposed for promotion to the Area.
  • Nothing is promoted automatically.

It has two modes, chosen by where the criteria comes from:

Mode Source What it does
capture (default) lived friction: a bug, a collapse, a client rejection Distills the scar into an Invariant Clue.
transplant imported criteria: a skill, a style guide, a third-party playbook, another kit's governing document Judges it against your project's purpose. Only what survives gets in.

The law of transplant mode: external criteria is not distilled, it is arbitrated.

A skill is criteria already distilled by someone else, under someone else's purpose, and it arrives without declaring where it stops being valid. Copying it into your Lore produces redundant literature wearing the authority of an Invariant Clue: criteria nobody paid for with real experience.

That is why transplant has an exit threshold: the resulting module must record where the source contradicts your standard and loses. No defeats section, no entry — either nothing was arbitrated (it was a copy), or the source carried no criteria at all.

What the source loses is worth more than what it offers: the summary already exists, better written, in the source. The disagreement exists nowhere else.

Why "transplant", and the metaphor is load-bearing. What grew well in another soil does not necessarily take in this one, and a transplant nobody watches is a dead plant with good intentions: you say what took and what did not. It is the exact counterpart of prune — pruning removes what the plant grew on its own, transplanting judges what came from outside. Those are the two passes of a maintained Lore, and having one without the other is why a body of criteria either bloats or ossifies.

Renamed in 2.1.0: through 2.0.9 this mode was called arbitrate. Same law, same four gates.

Two warnings transplant mode will give you:

  • Capacity ≠ criteria. A skill that executes (renders video, crawls, compiles) is used as a dependency: it is not Lore. Only a skill that judges (what is good copy, good design, good SEO) gets arbitrated.
  • No identity, no arbitration. If your identity file is empty you have no yardstick, and facing an authoritative source all you can do is obey it. Identity first, source second.

transmute-lore

Operates existing Lore in six modes:

Mode What it does
add Rescues criteria already scattered around (a bloated CLAUDE.md, a kilometric README, code comments) and crystallizes it into the six-piece architecture.
clean Removes the project's redundant modules that the Area already owns. The criteria does not disappear: it changes owner.
translate Standardizes the language of an existing Lore, translating content and renaming artifacts, without altering structure or meaning.
upgrade Raises a healthy Lore written against an older version of these skills. Sorts every finding into Missing, Superseded, Earned or Stale — what the project paid for with real friction is left alone, and what no longer matches the project's own practice is reported against the repository.
prune Prunes a Lore that decayed by accumulating correct things. Sorts every finding into Deadwood, Crowding, Rooted or Unhealed, and counts apparatus against content. What shrinks is the deliverable, not necessarily the corpus. Nothing comes out without its residue written down.
crystallize Exports a safe, traceable single-Markdown snapshot for a chat or notebook without replacing the live Lore or exposing private material.

Why pruning is its own mode and not part of clean. clean removes duplicates. prune removes weight: criteria that is not duplicated, not wrong and not superseded, and whose only defect is still being there. A Lore in daily use rarely decays by going stale — it decays by growing, and every other mode in this table can only add.

And why weight is not harmless. Tei Shi's Keep Running asks the other person to keep up with who she is now, not with who she was when they met. Criteria that never gets reviewed does not go neutral: it keeps operating, and it operates on someone who already changed. That is the failure prune exists to attack, and it is why the load is on both sides — the burden was never having a memory, it is keeping it current.

create-bot

Lets you work from a single place across several Areas that belong to one project. We call that federating.

Think of a blockchain lab. It has a website, it runs its social media, and it sustains lines of scientific research and technology transfer. Each of those Areas already has its own Lore. A bot routes all of them into one folder: you open the session there and can work on any of them, and make them talk to each other.

It works the other way round too: if you have an Area with several projects — several websites, say — a bot lets you work on one while reading the files of the others. Copying a footer from one site into another stops being an expedition.

A bot does not answer questions about the projects: it works in them.

Its north, and the only test that matters: a short instruction is enough. If the project had to be explained to the bot to get the result, criteria were missing from the load.

Two modes, by where the criteria comes from:

Mode When What it produces
nuevo From zero. No prior Lore to gather. Canon born from a brainstorm + source documents.
federar The criteria already exists, dissolved across several Areas. Canon plus a routing table over those Lore bodies.

The usual starting point is not a tidy set of Lore bodies. It is raw material: folders of documents, a database, a Notion workspace, undistilled code. That cannot be federated yet, and the fix is a chain:

raw folder (no Lore)
   └─ create-area                → creates the Area that will OWN that criteria — clean
        └─ adopt by registration   → the existing folder is listed in FASES.md, by path,
        │                              and stays where it is. Nothing moves.
        └─ transmute-lore (add)    → rescues the criteria already scattered inside it
             └─ create-bot (federar) → the bot routes to that Lore

create-area does not swallow the folder. It creates the Area clean, which is why the second step exists: an already-existing folder is adopted by registration — by path, without moving it. Skipping that link is what makes the chain look like the Area consumes what it is supposed to govern.

The law: the bot never distills into itself. A source with no Lore first gets its Lore in the Area it belongs to. Only then can the bot federate it. Otherwise the bot becomes the sole owner of criteria earned elsewhere, and the Area can no longer act as their source of truth.

create-bot inspects the paths you give it and tells you which already have Lore, which need transmuting first, and which need extracting to text beforehand. A free-note inbox is never federated: it holds no Lore, and it is .md, which is exactly what makes the mistake easy.

A bot holds three bodies of criteria with three different owners. Merging them is the default failure mode, and it is silent: everything still works, and the copy starts outranking its source.

Body What it is Rule
canon/ criteria the bot is — loaded before every decision distilled
lore/ criteria for maintaining the bot the project's own
borrowed criteria the Lore of every project the bot routes to reached by pointer; never authoritative

The test that keeps them apart: would the source be discardable? Distilling produces something smaller that can replace its origin; copying produces something identical that cannot.

Federating is pointing, not copying. Each row of the manifest is an address: the table says which Lore governs the task, and the generated access lets the session reach it where it lives. That criteria keeps one owner and one version, the same DRY rule the whole kit runs on.

And the law that makes routing work:

Route by type of task, not by name of project.

One entity can own several bodies of criteria that should not mix. The usual split is what it does versus how it talks about it. Naming the entity does not tell the bot which body governs the task.

This kit brainstorms to build every artifact it makes, so the artifact it produces does not greet its first user with four fields to fill. If you have a brainstorming skill installed, the bot runs the first use through it; if not, it runs a minimal one itself.

  • It shows what it reaches before asking anything: every federated body, whether its pointer resolves on this machine, what its canon contains, and what remains out of scope. A broken pointer appears there, before it can produce an answer that silently omits part of the criteria.
  • It asks only what changes its behaviour, one question at a time. It infers tone and a nickname from how you write; either can be corrected in one sentence.
  • No closed options for anything that picks a branch. A closed list cannot handle an answer that names two items without discarding one. The bot asks about the condition instead: "does your work fall into more than one of these?" If the answer names two bodies of criteria, it opens both.
  • It closes by separating configuration from criteria. What is configuration is stored. What turned out to be true about the project is proposed to the Lore of whoever paid for it with experience — never kept inside the bot.

Configuring the first use is not the first use. That setup is answered the same way whether the canon is full or empty and whether the paths resolve or not, so passing it proves nothing about the bot. A bot counts as launched when an instruction that does not name the criteria produces a deliverable, and that instruction is recorded verbatim.

All five are asked when the bot is configured for the first time. A bot with none of them is complete: they are seals, not parts.

  • The ecosystem copy (lore-ecosistema/). By default the bot points at each project's Lore where it lives, duplicating nothing. Turning it on only makes sense if whoever will use the bot does not have your folders: there the pointer resolves to nothing, and the copy is the only way that criteria exists on their machine.
  • Packaging it as a shareable plugin. Not created by default. A bot is a folder with its canon and one contract selected by its Area: you open the session there and the criteria is already loaded, with nothing to install. Wrapping it in a skill with its own repository serves one purpose, handing it to a team, and if you are working alone it is scaffolding you still have to maintain.
  • Lore encryption — experimental, see ENCRYPTION.md.
  • Telegram access. Adds a phone channel through a separate Telegram MCP, with an explicit access list. It needs a reachable machine and an open session; it is never implied by creating the bot.
  • A local multi-provider launcher. Uses Lore in the Shell when installed, or builds the smallest local launcher otherwise. It chooses the CLI and model; the criteria still lives in the bot.

Obsidian — the way in

If you already write notes in Obsidian, you already have the raw material. Point the vault at the mother folder of your Areas (Open folder as vault) and the same file tree is both your workspace and your vault. Nothing else gets configured.

Add a notes/ folder inside whatever you are working on — a project, an Area or a bot — and write your notes there. When you want them read:

"review my Obsidian notes and see what belongs in my lore"

obsidian-lore sweeps that inbox, separates criteria from tasks and from noise, tells you which Lore each thing belongs to, and waits for your approval before writing anything. Every mined note gets a mark with date and destination, so the next sweep skips it and the pending debt stays visible. The skill never deletes a note.

And the inbox runs in both directions. Sometimes the one writing into notes/ is the kit: a long prompt, an idea worth executing, work a session ran out of room to do. It goes there instead of into the chat, because a prompt that only lives in a conversation is not delivered — the git status looks clean while the deliverable does not exist. The next session opens the note and runs it.

Work your notes from a bot when you can. A bot carries a routing table with the purpose of every Area and project it federates written down, so a note gets routed against that table instead of guessed. The root of the vault never gets an inbox: a note there has no owner and no table to route it against.

A note is source, never criteria. It answers "what happened"; Lore answers "what changed because of it". Nothing crosses without explicit distillation and a human approving the diff.

Shared invariants

All eight skills follow the same rules:

  • Lore is written in your language.
  • Criteria is never invented. Everything comes from real experience.
  • A note is source, never criteria.
  • Discarded noise is reported, never silently deleted.
  • Every change passes a threshold before being written.
  • Nothing commits automatically. You review the final diff.

Those last two are the whole bet, and they are worth stating against the alternative. A growing class of agent frameworks keeps a memory of its own successes and failures and generates its own reusable skills from the patterns it finds. That is a real capability and it is the opposite choice: there, the agent gets better. Here, the person does. Lore's criteria live in files you own, in your language, and nothing enters them without you approving it with the content in view. If you want a system that learns behind your back, this is not it, and it never will be.

Benchmark

Lore acts as stability infrastructure when the domain changes. The public first-pass result now reports an equal-weight macro-average across two domain families: Web and Editorial (community management plus news writing). This prevents the larger Web cut from hiding the editorial drop. Every run used gpt-5.6-sol with medium reasoning effort; model, prompt and tools were identical between arms.

Lore reached every measured goal within the repair limit, with fewer attempts and less observed time.

The harness, frozen tasks, graders, raw outputs and declared limits are in bench/. These are Codex results, not a universal model claim.

Documentation

This README covers motivation and architecture. Everything else lives in its own document:

Document What it's for
90_SECONDS_en.md Start here. The whole mechanism, short enough to read before deciding whether to install anything.
USAGE_en.md Practical day-to-day usage guide: installation, core loop, and each skill with examples.
REFERENCE_en.md Technical reference: core concepts, the exact spec for each artifact and each skill.
MIGRATION_en.md How to migrate an existing project into Lore using transmute-lore.
ENCRYPTION.md The optional, experimental encryption for a bot's criteria: what it protects and what it does not.
CASES_en.md The eleven case studies, each with its declared boundary.
SPEC_KIT_en.md Using Lore alongside GitHub's spec-kit: which levels should have it at all — an area no, a project the whole cycle, a bot only up to tasks — who governs what, and the constitution that draws the border. Optional — Lore never depends on it.
bench/ The benchmark: Web, Editorial and UPGRADE harnesses; frozen tasks; method; declared limits; and raw results. 
lore-plugin/
  .claude-plugin/
    plugin.json
    marketplace.json

  .codex-plugin/
    plugin.json

  skills/
    use-lore/
    brainstorming-lore/
    create-area/
    create-project/
    create-bot/
      plantillas/        # validar.js · canon.js · sync.js · ecosistema.json
    save-to-lore/
    transmute-lore/
    obsidian-lore/

  README.md
  LICENSE

Case studies

Lore was not designed on a whiteboard: every decision in this kit came from applying it to real projects and watching what broke. Those applications are documented as eleven case studies, each with its own declared boundary. Seven are qualitative, Case 08 is the controlled benchmark summarized above, and Cases 09, 10 and 11 are the ones that turned the kit on itself — Case 10 by using it for a full day against a live Lore, and Case 11 by running two of its own versions head to head with the judging done blind.

Status: these are cases, not proofs. Small n, and all nine come from the same researcher. What they claim constrains how we use the kit; it does not pretend to be a law. The measured claim belongs to Case 08 and its benchmark; the other seven are qualitative evidence.

Read the eleven case studies →

Reach

For forty days the number held at a steady twenty-odd clones a day, well past the launch spike. That steadiness was the interesting part: not a launch bump, just people still arriving. Then August 8th brought 221 clones in a single day, and August 13th brought 225 — two more peaks, each larger than the launch itself. I left them in the data exactly as they arrived. Last capture: August 16th, covering through the 15th.

The daily rate quoted above is the steady one, not the average with those two days folded in. Data comes from GitHub's traffic API, stored in data/traffic/clones.json because the API only keeps 14 days.

This is a reach signal, not a demonstration. Nobody knows what anyone did with their copy: how many installed it, how many distilled anything, how many opened the folder once. It does not count as a case and it does not answer the question the case studies do. Note also that the "unique cloners" the API returns are unique per day, not people, so they cannot be summed into a headcount.

Origin

Lore was born as a distillation of LUS (Lore User System), a research program that studies how a human and an AI accumulate shared criteria over a long-term collaboration.

LUS studies the relationship. Lore is an operational implementation that emerged from that research. Its core principle fits in one idea:

**Experience only creates value when it can part