Guides
Troubleshooting
Symptoms, the likely cause, and what to do. Start with "Is it connected?" if nothing seems to happen.
Is it connected?
- Does the server answer?
printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' | python3 mcp_server.py
You should get one line of JSON that lists eight tools. If not, the problem is Python or the path, not your client.
- Does the client see it?
claude mcp list (Claude Code) or copilot mcp list (Copilot CLI). The entry should say connected.
- Did the agent call it? Look for a
get_rules tool call in the chat. The agent calls Lore because its instructions say to; that is a request, not enforcement.
The agent and the tools
| Symptom | Cause and fix |
|---|
The agent never calls get_rules | The instructions are not loaded. Start a new session after installing. For Copilot CLI check the marked block in ~/.copilot/copilot-instructions.md; for VS Code add the instruction file by hand and use agent mode. Ask the agent which tools it has. |
| "No lore project matches these paths" | The files are not in a git repository Lore can register, or the agent passed relative paths from another folder. Use absolute paths, or register the folder with memorize.py --path <project>. For a repository, check auto_register is not false in ~/.lore/config.json. |
| The project did not register itself | It needs a .git entry in the folder or above it. Your home folder, /, system folders and ~/.lore are never registered. |
| The server entry is missing in Copilot CLI | Wrong file or key. The CLI uses ~/.copilot/mcp-config.json with mcpServers and "type": "local"; VS Code uses servers and "type": "stdio". |
| I changed Lore's code and nothing changed | The running server is the old process. Start a new agent session or reconnect the server. Rules, in contrast, are read from disk on every call. |
| The agent says it already has the rules but seems to have forgotten them | Its context was reset or compacted. It should pass refresh=true; ask it to call get_rules again with that. |
Rules that do not behave
| Symptom | Cause and fix |
|---|
| A rule was saved but is not applied | It is probably pending. review.py list --status pending, then approve. In a repository that is not yours, or in manual mode, rules always wait. |
| "Not saved" with hidden characters, an HTML comment, or "keep a rule under 500" | The text failed the hygiene checks. Remove the invisible characters or shorten it. See hygiene. |
A rule is shown with <U+XXXX> | It was stored with hidden characters. It is never served or exported. Edit it (review.py edit) or reject it. |
| Rules the agent proposed keep waiting for me | Look at the reason in its reply: manual mode, a risky pattern, a possible contradiction, a repository that is not yours (review.py trust if it is), a project the agent is not working on, or the per-session limit. |
| "not your repository" in the UI, but it is mine | Lore could not confirm you can push (no gh, logged out, or a non-GitHub host). Fix gh auth login, or settle it: review.py --name myapp trust. |
| A rule I need was not sent for a task | Matching is by keywords. Look at the title list in the reply and ask for it with include; or review.py pin <id>; or ask the agent to organise the rules so the triggers include your vocabulary. Check with review.py resolve <file> --task "…". |
| A rule is sent every time and I don't want that | It is marked always. review.py unpin <id>. |
| The agent keeps being told to tag rules | Some rules covering the files have no tags. The note appears once per session; ask the agent to "organise my Lore rules" once. review.py list says how many are untagged. |
| Something was activated that I don't want | review.py list --auto, then review.py reject <id>. For tighter control: python3 install.py --approval manual. |
The scripts
| Symptom | Cause and fix |
|---|
discover.py proposes nothing | Fewer than 5 files of evidence, or no convention reaches 90%. Try --min-ratio 0.8 --min-files 3. |
learn.py: "gh is not installed" or "gh auth login" | Install the GitHub CLI and log in. Lore uses your existing session. |
learn.py finds comments but proposes nothing | Nothing actionable (praise, questions, already-proposed comments), or the comments are from people outside the repository's team. Try a longer --since, --include-seen, --include-external, or --repo owner/name if the git remote is not the repository you review. |
| A proposal I rejected came back | Only with --include-seen, or after deleting the project's review-ledger.json. |
| The agent is reminded to read review feedback but it fails | A failed attempt is recorded and stops the reminder for 14 days. Fix gh and run learn.py once to clear it. |
review.py approve --all says "nothing approved" | You answered no, or there was no input. Add --yes, or answer y. |
A section rule is missing from sync output | The section is not in the map. Re-run memorize.py. |
install.py: "not a JSON object" | ~/.copilot/mcp-config.json is malformed. Fix or remove it, then run again. |
install.py: "claude mcp add failed" | Run the printed command yourself to see Claude Code's own message. You can also add the server by hand (Claude Code). |
The web UI
| Symptom | Cause and fix |
|---|
| "Open the address printed by serve.py" | You opened the bare address. Use the full link with ?t=<token> from the terminal. The token changes every run. |
| "bad Host header" or the page refuses to load | You used localhost. Use 127.0.0.1, exactly as printed. |
| "cannot listen on 127.0.0.1:8765" | The port is taken. serve.py --port 9000. |
| A change to the Python code has no effect | Restart serve.py. Changes to web/index.html show on a reload. |
Still stuck?
Run the whole test suite from the Lore folder (python3 -m unittest discover -s tests); failures there point at the environment. Then open an issue with the command you ran, the exact message, your Python version (python3 --version) and the agent you use. For a security problem, follow the private route instead.