How it works

Automatic mode

After install.py, you do not operate Lore. This page lists what it does by itself, what limits each step, and how to undo or switch off any of it.

The timeline

1. You run install.py once It adds the MCP server to Claude Code and Copilot CLI. See install.py.
2. An agent session starts When the client connects, Lore sends its instructions (about 300 tokens). The wording follows the approval setting, so the agent never claims a waiting rule is active.
3. The agent asks for rules Before editing, it calls get_rules with the files and one sentence about the change. If the project is new, Lore registers it first.
4. Lore adds one-time notes to the reply In a repository that is yours: set the project up, tag untagged rules, read review feedback. Each note appears once per session. See setting a project up.
5. The agent saves rules From your corrections (record_feedback) or after judging candidates (propose_rules).
6. Lore screens each one Passing rules are activated and marked; the others wait. The agent tells you in one line which is which.

Registering projects

The first time a tool is asked about files in a git repository Lore does not know, it registers the repository: the name is the folder's name (with a short suffix if another folder already uses it), and the map is built. This is switched off by "auto_register": false.

• Only git projects. A folder counts when it, or a folder above it, contains .git. Whether it is yours is decided separately by asking git (see trust), and a folder git does not recognise as a repository counts as not yours.
• Never the wrong places. It never registers your home folder, /, a system folder (/usr, /etc, /var, /opt, /home and so on) or ~/.lore.
• No imports from a repository it has just met. AGENTS.md, CLAUDE.md and Copilot instruction files are not turned into rules: the agent's own client already loads them, and a freshly cloned repository is not trusted to write rules. (memorize.py still imports them, as pending rules, when you ask.)

Setting a project up

The first reply for a newly registered project, in a repository that is yours, tells the agent to:

1. call discover_conventions and keep the conventions a new contributor should follow;
2. if the repository is on GitHub and gh works, call learn_from_reviews and do the same with the review feedback;
3. save what it kept with propose_rules, including a title, trigger words and always for each, and tell you in one line.

Later sessions add two more notes, once each per session:

• Untagged rules. If rules covering the files have no tags yet, the agent is asked to run organize_rules and tag_rules and tell you which rules it marked always.
• Review feedback. If review comments have not been read for 14 days, the agent is asked to read them. A failed attempt (for example gh not logged in) counts as an attempt, so the agent is not sent to retry it in every session.

In a repository that is not yours, Lore only says that it will not learn rules there by itself.

Screening and activation

Every rule the agent saves goes through the same gate. It is activated at once unless one of these holds, checked in this order. The first match decides, and the reply tells the agent why.

1. Approval is manual. Setting approval to manual makes every proposed rule wait.
2. Wrong project. The project is not one the agent is working on, meaning one it has asked get_rules about or recorded feedback for, or the one the session was started in.
3. Not your repository. See trust.
4. Risky wording. The text matches a pattern for an attack on the agent: a download piped into a shell, "ignore previous instructions", a fake system message, a request for the system prompt, key files such as ~/.ssh, a web address, a dangerous command, "skip review", or a long encoded blob.
5. Contradiction. It reverses the meaning of a similar rule in the same scope ("tabs" against "spaces", "do" against "do not", "max 80" against "max 120").
6. Session limit. The session has already activated auto_limit rules (25 by default).

Rules with hidden characters, HTML comments or more than 500 characters never get this far: they are refused outright.

Trust

Lore only activates rules by itself in repositories that are yours. It decides per project and remembers the answer for a week in trust.json:

Override the answer by hand and the web UI shows the result next to the project's name:

python3 review.py --name myapp trust          # always treat it as yours
python3 review.py --name myapp untrust        # never activate rules here by themselves
python3 review.py --name myapp trust --reset  # let the check decide again

Why it matters: anyone can publish a repository whose own review comments say anything. If you clone one and ask an agent to edit a file, Lore must not let that repository teach your agent rules.

Who may teach it

Review comments count only when GitHub says their author is an owner, member or collaborator of the repository (author_association). Anyone can comment on a public repository, so outsiders cannot teach Lore anything. learn.py --include-external lifts this for a run.

Which project a call is about

Every tool works out the project in the same order: the files in paths, then a folder in path, then a project name (reading tools only), and last the folder the agent was started in. The tools that save rules (propose_rules, tag_rules, record_feedback) never accept a project name, and paths outside the project are left out, so a rule cannot be aimed at a project the agent is not in. If a call mixes files from two projects, Lore serves the first and says that some paths belong elsewhere.

Seeing and undoing what it did

• The agent reports each activation in one line, with the command that undoes it.
• python3 review.py --name myapp list --auto lists everything Lore activated itself; the web UI marks those rules auto-activated.
• python3 review.py --name myapp reject <id> deletes a rule. unapprove <id> puts it back to pending.
• Approving a rule yourself clears its automatic mark.

Settings

Optional, in ~/.lore/config.json. A missing file, an unreadable file or a bad value falls back to the default for that setting.

{ "approval": "auto", "auto_register": true, "auto_limit": 25 }

The instruction text the agent receives changes with approval, so switch it with install.py --approval …, which also rewrites the Copilot instruction block.

What stays manual by design

The scripts you run yourself still save pending rules: discover.py, learn.py and the instruction files memorize.py imports. You are not behind an agent there to judge them, so you approve them. Rules you add yourself with review.py add or in the UI, and rules trained from your own documents, are active at once because you chose them.