@lorekit/cli 1.67.0 → 1.69.0

package/src/store/remote.mjs

@@ -22,8 +22,19 @@ import { restFetch, mcpToRestBase } from '../shared/mcp.mjs';
 import { rememberAccountId } from '../telemetry/telemetry-identity.mjs';
 import { getActiveTraceparent } from '../telemetry/telemetry.mjs';
 import { withReadFields } from './entry-fields.mjs';
+import { pickScopeWinner } from '../shared/scope-precedence.mjs';
 import { normalizeCreatedAt } from './created-at.mjs';
 
+/**
+ * How many same-key rows an UNSCOPED read fetches before picking a winner.
+ *
+ * Deliberately the same number the hosted `memory.read` caps its own candidate
+ * fan-out at, so a key living in a pathological number of scopes truncates at
+ * the same point on both surfaces instead of the two considering different
+ * candidate sets and disagreeing about the winner.
+ */
+const UNSCOPED_READ_CANDIDATE_LIMIT = 50;
+
 // Drop undefined/null args so JSON payloads stay tidy.
 function stripUndefined(obj) {
   const out = {};
@@ -249,12 +260,24 @@ class RemoteStore {
     };
   }
 
+  // read({ scope, key }) → { ok, entry } — `scope` is OPTIONAL.
+  //
+  // Without one the key can match once per scope holding it, so the precedence
+  // pick happens HERE rather than server-side: `GET /memories` is a LIST route,
+  // and narrowing it to a single winner would change what every other caller of
+  // it gets back. The rule is the shared `scope-precedence` one, so this
+  // resolves identically to MCP's `memory.read` (which picks server-side
+  // because it must answer with one lesson) and to the offline store.
   async read({ scope, key } = {}) {
     const p = new URLSearchParams();
     if (scope) p.set('scope', scope);
     if (key) p.set('key', key);
-    // scope+key is unique, so one row is all there can be — don't pull the default page of 50.
-    p.set('limit', '1');
+    // With a scope, `scope`+`key` is unique and one row is all there can be —
+    // don't pull the default page of 50. Without one, fetch the candidates the
+    // precedence pick needs; the cap matches the hosted read's own so the two
+    // surfaces truncate a pathological key at the same point rather than
+    // disagreeing about which lessons were even considered.
+    p.set('limit', scope ? '1' : String(UNSCOPED_READ_CANDIDATE_LIMIT));
     const res = await this._rest(`/memories?${p}`);
     // `unusable` is passed through: `_rest` short-circuits an unconfigured
     // store with that flag and NOTHING else, so a caller that drops it is left
@@ -275,9 +298,43 @@ class RemoteStore {
       };
     }
     const entries = res.data?.entries ?? [];
+    // `key` is an EXACT filter server-side, so every row here carries the key
+    // that was asked for; precedence only has to choose among their scopes. A
+    // scoped read has at most one candidate, so the pick is a no-op there.
+    const winner = pickScopeWinner(entries);
     // Same projection as list/search — a single read must not answer with a
     // different shape than the listing the caller found the key in.
-    return { ok: true, entry: entries[0] ? withReadFields(entries[0]) : null };
+    return { ok: true, entry: winner ? withReadFields(winner) : null };
+  }
+
+  // readMany(refs) → { ok, entries, missing } — `POST /memories/read`, one
+  // round-trip for the whole batch (the server groups by scope and issues one
+  // `.in('key', …)` query per distinct scope — see `handlers/read.ts`). `refs`
+  // is an array of `{ scope, key }`; this transport joins each into the
+  // `scope::key` wire form the route's `ReadMemoriesBodySchema` expects. An
+  // empty/absent list short-circuits locally rather than making a request the
+  // server would just 400 on (`refs` has `.min(1)`).
+  async readMany(refs) {
+    const list = Array.isArray(refs) ? refs.filter(Boolean) : [];
+    if (!list.length) return { ok: true, entries: [], missing: [] };
+    const body = { refs: list.map((r) => `${r.scope}::${r.key}`) };
+    const res = await this._rest('/memories/read', { method: 'POST', body });
+    if (!res.ok) {
+      return {
+        ok: false,
+        error: res.error ?? null,
+        httpStatus: res.httpStatus ?? null,
+        retryAfter: res.retryAfter ?? null,
+        networkError: res.networkError ?? null,
+        unusable: res.unusable ?? false,
+      };
+    }
+    const data = res.data ?? {};
+    return {
+      ok: true,
+      entries: (data.entries ?? []).map(withReadFields),
+      missing: data.missing ?? [],
+    };
   }
 
   async write(args = {}) {

package/src/surfaces.generated.mjs

@@ -160,37 +160,37 @@ export const MCP_TOOL_DEFS = [
   },
   {
     "name": "memory.read",
-    "description": "Read a lesson by scope and key",
+    "description": "Read one lesson by `key`, or several at once by `refs`. Pass exactly one of those two shapes: `key` (optionally narrowed with `scope`), or `refs` alone — a call carrying both is rejected, and so is one carrying neither. `scope` is optional: omit it and the key is resolved across every scope you can see, preferring the most specific one.",
     "inputSchema": {
       "type": "object",
-      "required": [
-        "scope",
-        "key"
-      ],
       "properties": {
         "scope": {
           "type": "string",
-          "description": "Canonical scope string, e.g. `repo::mthines/lorekit`."
+          "description": "Canonical scope string, e.g. `repo::mthines/lorekit`. OPTIONAL — omit it to search every scope you can see."
         },
         "key": {
           "type": "string",
           "description": "Lesson identifier, unique within the scope. Max 512 characters."
+        },
+        "refs": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Batch mode: one or more `scope::key` references, fetched in a single call. Cannot be combined with `scope`/`key`. Each entry is parsed by the same reference grammar `memory.write`'s `cited` field uses (`scope::key`, verbatim scope — never lowercased). Silently truncated past 32 entries."
         }
       }
     }
   },
   {
     "name": "memory.list",
-    "description": "List lessons for a scope",
+    "description": "List lessons, for one scope or across every scope you can see",
     "inputSchema": {
       "type": "object",
-      "required": [
-        "scope"
-      ],
       "properties": {
         "scope": {
           "type": "string",
-          "description": "Canonical scope string, e.g. `repo::mthines/lorekit`."
+          "description": "Canonical scope string, e.g. `repo::mthines/lorekit`. OPTIONAL — omit it to search every scope you can see."
         },
         "tags": {
           "type": "array",
@@ -338,7 +338,7 @@ export const MCP_TOOL_DEFS = [
   },
   {
     "name": "memory.scopes",
-    "description": "List every scope in the store with how many active memories it holds and when it was last written to — the inventory to consult when you do not already know which scope to read. Takes no arguments and is store-wide, NOT limited to any working directory. Every other read tool requires a scope up front, so this is the one that answers \"what is there?\".",
+    "description": "List every scope in the store with how many active memories it holds and when it was last written to — the inventory to consult when you do not already know which scope to read. Takes no arguments and is store-wide, NOT limited to any working directory. The other read tools answer questions about lore; this one answers \"what is there?\" — reach for it when you want to NAME a scope, to narrow a list or to decide where a write belongs.",
     "inputSchema": {
       "type": "object",
       "properties": {}
@@ -346,16 +346,13 @@ export const MCP_TOOL_DEFS = [
   },
   {
     "name": "memory.list_archived",
-    "description": "List archived (soft-deleted) lessons for a scope",
+    "description": "List archived (soft-deleted) lessons, for one scope or across every scope you can see",
     "inputSchema": {
       "type": "object",
-      "required": [
-        "scope"
-      ],
       "properties": {
         "scope": {
           "type": "string",
-          "description": "Canonical scope string, e.g. `repo::mthines/lorekit`."
+          "description": "Canonical scope string, e.g. `repo::mthines/lorekit`. OPTIONAL — omit it to search every scope you can see."
         },
         "limit": {
           "type": "integer",