MCP tools

All tools run with the connected user's permissions. Use repository names in owner/repository form and file paths relative to the repository root.

You can usually ask your agent to use these tools in ordinary language. The JSON examples show the arguments it sends to Lore; they are not terminal commands. All repository names, claims, and IDs in the examples are fictional.

Tool results are returned through MCP as text containing JSON. Your client may display that JSON directly or summarize it. The examples below show the decoded data, without the outer MCP message.

What you want	Tool	Changes shared memory?
See connected repositories	list_repos	No
Load useful context before working	get_context	No
Find a particular decision or warning	search	No
Save a new piece of knowledge	record	Yes
Retire an existing fact	forget	Yes

list_repos

Lists accessible, enabled repositories with their default branch and active fact count. Takes no arguments.

Ask: “Use Lore to list the repositories I can read.”

Arguments:

{}

Example result:

[
  { "full_name": "acme/service", "default_branch": "main", "facts": 12 }
]

facts is the number of active facts, not the number of files. An empty list means no enabled repository is currently accessible through this connection.

get_context

Reads active repository memory, optionally focused on file paths.

Argument	Meaning
repo	Optional explicit repository name; required when current remotes are ambiguous.
remotes	Current workspace GitHub HTTPS/SSH remotes. Lore normalizes them and checks access.
task	Optional short task description, up to 2,000 characters. Never send the whole chat.
issue	Optional GitHub issue URL, #123, or Linear issue identifier/URL.
paths	Optional array of up to 100 repository-relative paths.
budget	Approximate response-size budget in tokens, 128–16,000; defaults to 1,500.

{ "repo": "acme/service", "paths": ["src/auth/session.ts"], "budget": 1500 }

Ask: “Before editing src/auth/session.ts in acme/service, load the relevant Lore context.”

Example result:

{
  "facts": [
    {
      "id": "70db2106-f135-426d-85f9-c12df5a2b40e",
      "type": "gotcha",
      "claim": "Refresh the token before retrying an expired session.",
      "scope": "src/auth",
      "tags": ["authentication"]
    }
  ],
  "estimatedTokens": 80
}

A token is a rough unit of text used by language models. Lore estimates the size from the serialized response; estimatedTokens is not a measurement from your agent's model. A larger budget can fit more facts but still counts as one successful MCP read. Repository-wide facts and facts whose scope contains the supplied paths are eligible. This is not a source-code download.

Use src/auth/session.ts, not /Users/alex/project/src/auth/session.ts. Absolute paths and paths containing .. are rejected.

search

Searches memory and evidence with full-text and, when configured, semantic ranking.

Argument	Meaning
query	Required search text, 1–1,000 characters.
repo	Optional repository filter. Required to disambiguate multiple organizations.
type	Optional fact type: convention, gotcha, decision, todo, explanation, or noise.
tag	Optional tag filter, up to 100 characters.
limit	1–100 results; defaults to 20.
includeInactive	Includes inactive facts when true; defaults to false.

{ "repo": "acme/service", "query": "token refresh", "limit": 10 }

Ask: “Search Lore for why we refresh tokens before retrying requests in acme/service.”

The result is a list of matching facts, with evidence and ranking information. An empty list means no results matched. limit is a maximum, not a promise to return that many results. Ordinary searches return active facts; use includeInactive when investigating earlier or retired knowledge.

For example, to review earlier decisions tagged authentication:

{
  "repo": "acme/service",
  "query": "session",
  "type": "decision",
  "tag": "authentication",
  "includeInactive": true
}

get_context and search consume the organization's shared read quota.

record

Adds a fact. Requires repository write access.

Argument	Meaning
repo	Repository name; omit only when one repository can be resolved.
claim	Required claim, 6–10,000 characters.
type	Required: convention, gotcha, decision, todo, explanation, or noise.
tags	Optional array of up to 20 tags, each at most 64 characters.
scope	Optional repository-relative scope.
path	Optional repository-relative evidence path.
lines	Optional inclusive [start, end] line numbers; positive integers, start ≤ end.

{
  "repo": "acme/service",
  "type": "gotcha",
  "claim": "Refresh the token before retrying an expired session.",
  "path": "src/auth/session.ts",
  "tags": ["authentication"]
}

Ask: “Record a gotcha in Lore for acme/service: refresh the token before retrying an expired session. Link it to src/auth/session.ts.”

The result contains the saved fact, including its id. Lore can reuse an existing fact when it detects the same or sufficiently similar claim. Recording a fact changes Lore's memory; it does not edit a source file or create a Git commit.

Use scope to say where the fact applies and path to identify supporting code. For example, a convention can apply to the whole src/auth directory while its evidence lives at src/auth/session.ts, lines 12–20:

{
  "repo": "acme/service",
  "type": "convention",
  "claim": "Validate a session before dispatching authenticated commands.",
  "scope": "src/auth",
  "path": "src/auth/session.ts",
  "lines": [12, 20]
}

Do not invent line numbers. Omit lines when you do not know them.

forget

Retires a fact without removing its history. Requires write access to the fact's repository. This changes shared memory; review the target before calling it.

Argument	Meaning
factId	Required fact UUID from a Lore response.
reason	Required explanation, 1–2,000 characters.

{
  "factId": "70db2106-f135-426d-85f9-c12df5a2b40e",
  "reason": "The new session client now refreshes tokens automatically."
}

Replace the example ID with the ID returned by a real search or get_context call. The successful result includes status: "removed". The fact will no longer appear in ordinary retrieval, but its history remains available.

Common tool errors

Message	What it means	What to do
Pass repo as owner/name	Lore cannot choose one repository automatically.	Call list_repos, then supply a full repository name.
Repository write access required	Your account can read, but cannot change that repository's memory.	Ask someone with GitHub write access to make the change.
Use a repository-relative path	The path starts with / or contains ...	Start the path from the project's top-level folder.
Writable fact not found	The fact is missing or you cannot write to its repository.	Check the real fact ID and your GitHub access.
Monthly MCP read quota reached	The organization has used its monthly reads.	Check Billing; wait for the monthly reset or upgrade.

See Plans and usage for what counts as a read.

Task-aware context

Ask: “Add password reset. Use Lore to check token-expiration rules, email conventions, and previous token-reuse fixes before editing.”

{
  "remotes": ["git@github.com:acme/accounts.git"],
  "task": "Add password reset",
  "paths": ["src/auth", "src/email"],
  "issue": "#123",
  "budget": 4000
}

facts include source citations and dates where known. conflicts includes both claims and their evidence; newer ingestion is not treated as proof of correctness. omittedFacts and omittedConflicts indicate response-budget truncation. Increase the budget or narrow the question when necessary. No review or resolution action is required. Omitting task preserves repository/file-based retrieval.

session_briefing

Use once when returning to a repository:

{"remotes":["https://github.com/acme/accounts.git"],"paths":["src/auth"],"budget":3000}

Returns new/changed knowledge and merged PR changes since this agent's previous briefing. The first call provides an initial briefing. Each connected OAuth client and repository has a separate cursor. Path-scoped briefings have separate cursors (the eight most recently used scopes are retained). Undelivered facts remain pending when the budget is too small. Removed fact IDs mean earlier guidance is unavailable; they do not reveal its deleted contents.

retrospective

{"repo":"acme/accounts","topic":"Password reset token reuse incident","budget":5000}

Returns evidence for a draft covering what happened, contributing factors, the fix, affected code, lessons, and missing evidence. The coding agent writes the narrative from these sources. Historical/stale facts may appear as history, not current advice. A resolved issue alone does not prove deployment or production recovery. Unknown start times, impact, or causes must remain explicitly unknown.

related_repositories

{"remotes":["git@github.com:acme/sdk.git"]}

Returns accessible producers and consumers whose scanned dependency declarations match. Initial manifest support covers npm package.json, Composer composer.json, and Go go.mod, including manifests within monorepos. Links identify both declarations. A declared dependency indicates possible impact; the agent must check versions and call sites before claiming that a change will break a consumer. Runtime-only links, unsupported manifests, and inaccessible repositories are not inferred.

diagnose_connection

{"remotes":["git@github.com:acme/accounts.git"]}

Reports configuration/reachability, authentication, repository access, ingestion, and context availability separately with recovery steps. A successful call proves this client can reach Lore. It cannot inspect a broken local configuration that prevents any MCP request. Empty context is different from failed authentication. Diagnostics do not consume read credits.