Guides

Architecture

How the code is organised, what each file is for, and how a request flows through it. The program is about 6,300 lines of standard-library Python (plus a 540-line web page) and about 3,200 lines of tests, with no build step.

The layers

Packages depend only downwards. A test (tests/test_architecture.py) fails if a lower layer imports a higher one, if core imports anything from the command line, HTTP or the browser, or if a root script grows beyond a thin wrapper.

   cli          web          mcpserver        interfaces: each is a way to drive Lore
     \           |           /
      +----------+----------+
       |                     |
   discovery              reviews          infer rules from code / from code review
       \                    /
        +------ core ------+              the domain: what a rule is, how it is stored, chosen and exported

   root scripts (install.py, memorize.py, ...) only call the main() of one interface

• core imports nothing of Lore's own other than itself.
• discovery and reviews import core only.
• cli, web, mcpserver may import all three, and none imports another interface.

The repository at a glance

core/: the domain

discovery/: rules from code

reviews/: rules from code review

The interfaces

How a request flows

get_rules

1. protocol.py reads the line and calls the tool's handler.
2. tools.get_rules finds the project from the paths (projects.find_for_path), registering a new git project if needed (registration).
3. resolver.resolve loads active rules through RuleRepository, drops any with hidden characters, keeps those whose scope (models.Scope.level_for, globs, mapper) covers a path, and, for a long list, ranks them against the task (search.rank), skipping what the session already has.
4. UsageLog.record counts what was sent; tools adds the one-time notes (it may call trust.get and read Ledger), and returns the text.

record_feedback and propose_rules

1. tools works out the project from the files and marks it as one the agent is working on.
2. RuleRepository.add validates the text (sanitize) and tags (risk), compares with existing rules for duplicates and contradictions (textutil), and writes under a lock.
3. tools._activate applies the gate: config (approval mode and limit), the working-project check, trust.get, Rule.risks, contradictions. Passing rules go through set_status(..., auto=True).

Learning from review

1. reviews.service.learn fetches comments through github.py (the only place that runs gh), records the attempt in the ledger, and filters and groups them (cluster, text).
2. It returns proposals. The CLI saves them as pending; the MCP tool turns them into a brief for the agent, which proposes the ones it keeps through propose_rules.

The tests

Design principles

• Standard library only. No dependencies to install, audit or update.
• Deterministic at request time. Serving rules involves no model and no network; the agent's judgement is captured once, as tags.
• One writer per file. RuleRepository owns rules.json, UsageLog owns usage.json, Ledger owns review-ledger.json. Writes are atomic and locked.
• Untrusted text is never trusted. Anything from a repository, a reviewer or an agent passes through sanitize before it is stored or shown, and is refused rather than repaired.
• Interfaces stay thin. Behaviour lives in the layers below, so the CLI, the web UI and the MCP server cannot drift apart.