@lorekit/cli 1.68.0 → 1.70.0

package/src/store/local.mjs

@@ -10,7 +10,8 @@ import path from 'node:path';
 import { serializeEntry, parseEntry, slugify, scopeToDir } from './format.mjs';
 import { normalizeCreatedAt } from './created-at.mjs';
 import { isLive, resolveExpiresAt } from './ttl.mjs';
-import { seenCountOf, withReadFields } from './entry-fields.mjs';
+import { seenCountOf, withReadFields, updatedAtOf } from './entry-fields.mjs';
+import { pickScopeWinner } from '../shared/scope-precedence.mjs';
 
 export function createLocalStore(baseDir) {
   return new LocalStore(baseDir);
@@ -54,6 +55,20 @@ class LocalStore {
     return this._readAll(scope).find((r) => r.entry.key === key) || null;
   }
 
+  // Every LIVE entry carrying `key`, across every scope in this store — the
+  // candidate set for a read that named no scope.
+  //
+  // Walks the whole tree rather than one scope directory, because `_files`
+  // resolves a single scope→directory and there is no directory for "any".
+  // That is more IO than a scoped read, which is exactly why a caller that
+  // knows its scope should still pass it.
+  _findAllByKey(key) {
+    const now = new Date();
+    return this._walkEntries()
+      .map((r) => r.entry)
+      .filter((e) => e && e.key === key && e.scope && isLive(e, now));
+  }
+
   // Raw lookup by scope+key — returns the stored entry regardless of archived
   // state (unlike read(), which hides archived). Synchronous; used by migrate
   // to classify ADD / UPDATE / NOOP without reviving archived entries.
@@ -80,7 +95,14 @@ class LocalStore {
   }
 
   // read({ scope, key }) → { ok, entry } — null when absent, archived, or expired.
+  //
+  // `scope` is OPTIONAL. Without one the key is resolved across every scope in
+  // this store and the winner picked by the shared `scope-precedence` rule —
+  // the SAME rule the hosted MCP and REST surfaces apply, so `lorekit show
+  // <key>` offline and `memory.read { key }` online cannot resolve the same key
+  // to different lessons.
   async read({ scope, key } = {}) {
+    if (!scope) return { ok: true, entry: this._readUnscoped(key) };
     const found = this._findByKey(scope, key);
     return {
       ok: true,
@@ -88,6 +110,34 @@ class LocalStore {
     };
   }
 
+  // The unscoped half of `read`, split out so `TwoTierStore` can reuse the
+  // candidate gathering without re-deciding the precedence rule.
+  _readUnscoped(key) {
+    const winner = pickScopeWinner(this._findAllByKey(key).map(scopeCandidate));
+    return winner ? withReadFields(winner.entry) : null;
+  }
+
+  // readMany(refs) → { ok, entries, missing } — batch lookup for an array of
+  // `{ scope, key }` refs, mirroring the REST/MCP batch read's shape: found
+  // entries in `entries` (same projection `read()` applies), unresolved refs
+  // (absent, archived, or expired) reported as `scope::key` strings in
+  // `missing` rather than silently dropped. A thin loop over `_findByKey` —
+  // this store has no query engine to batch against, so there is no cheaper
+  // shape than one lookup per ref.
+  async readMany(refs = []) {
+    const entries = [];
+    const missing = [];
+    for (const { scope, key } of refs) {
+      const found = this._findByKey(scope, key);
+      if (found && isLive(found.entry)) {
+        entries.push(withReadFields(found.entry));
+      } else {
+        missing.push(`${scope}::${key}`);
+      }
+    }
+    return { ok: true, entries, missing };
+  }
+
   // write(...) → { ok, entry } — upsert by scope+key. Preserves `created` and
   // refreshes `updated`; writing an archived key revives it.
   //
@@ -328,6 +378,19 @@ class LocalStore {
   }
 }
 
+/**
+ * Project a stored entry into the `{ scope, updated_at }` shape
+ * `scope-precedence` compares, keeping the entry itself alongside so the winner
+ * can be returned without a second lookup.
+ *
+ * `updatedAtOf` is what maps the local `updated` spelling onto the `updated_at`
+ * the shared rule expects — without it every local candidate would compare as
+ * having no timestamp and the tie-break would collapse to scope-ascending.
+ */
+function scopeCandidate(entry) {
+  return { scope: entry.scope, updated_at: updatedAtOf(entry), entry };
+}
+
 // A scope string is global when its type segment is `global`.
 function isGlobalScope(scope) {
   return String(scope).split('::')[0] === 'global';
@@ -394,6 +457,23 @@ class TwoTierStore {
   }
 
   async read({ scope, key } = {}) {
+    // Unscoped: precedence has to be decided over BOTH tiers at once, not tier
+    // by tier. Asking the project tier first and taking any hit would let a
+    // `global` lesson in the project tier beat a `repo::…` one in the home
+    // tier — tier order standing in for scope precedence, which is not what it
+    // means. Within ONE scope the project tier still shadows home, exactly as
+    // the scoped path below does.
+    if (!scope) {
+      const tiers = this.projectActive() ? [this.project, this.home] : [this.home];
+      const byScope = new Map();
+      for (const tier of tiers) {
+        for (const entry of tier._findAllByKey(key)) {
+          if (!byScope.has(entry.scope)) byScope.set(entry.scope, entry);
+        }
+      }
+      const winner = pickScopeWinner([...byScope.values()].map(scopeCandidate));
+      return { ok: true, entry: winner ? withReadFields(winner.entry) : null };
+    }
     if (this.projectActive()) {
       const r = await this.project.read({ scope, key });
       if (r.entry) return r;
@@ -401,6 +481,20 @@ class TwoTierStore {
     return this.home.read({ scope, key });
   }
 
+  // readMany(refs) → { ok, entries, missing } — per-ref `read()`, so the same
+  // project-shadows-home precedence applies to every ref individually rather
+  // than to the batch as a whole.
+  async readMany(refs = []) {
+    const entries = [];
+    const missing = [];
+    for (const { scope, key } of refs) {
+      const r = await this.read({ scope, key });
+      if (r.entry) entries.push(r.entry);
+      else missing.push(`${scope}::${key}`);
+    }
+    return { ok: true, entries, missing };
+  }
+
   async write(args = {}) {
     return this.tierFor(args.scope).write(args);
   }

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",