bantamkit-mcp 0.35.5 → 0.35.7

package/assets/tools/memory_recall.json

@@ -1,6 +1,6 @@
 {
   "name": "memory_recall",
-  "description": "Search persistent memory. Call BEFORE starting a task that resembles past work. Returns at most k matching facts.",
+  "description": "Search persistent memory. Call BEFORE starting a task that resembles past work. Returns the top word matches, never fewer than the store default of 3 when that many match; a query that is exactly a fact's name returns that fact alone.",
   "surfaces": [
     "agent",
     "mcp"
@@ -18,7 +18,8 @@
       "k": {
         "type": "integer",
         "minimum": 1,
-        "maximum": 5
+        "maximum": 5,
+        "description": "Facts wanted. Raised to the store default of 3 when smaller; never lowered below it."
       }
     }
   },

package/dist/hookadapter.js

@@ -48,8 +48,8 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Memory } from './memory/component.js';
 import { discoverProjectStore, resolveProjectStore } from './memory/layers.js';
-import { DURABLE_TYPES, MemoryStore, pyEqualValue, pyText, tokens } from './memory/store.js';
-import { keptManifest, keptPrefix } from './npminstall.js';
+import { DURABLE_TYPES, MemoryStore, RECALL_MIN_SCORE_RATIO, pyEqualValue, pyText, tokens } from './memory/store.js';
+import { keptCli, keptManifest, keptPrefix } from './npminstall.js';
 import { decide as decideUpdate, KEY as UPDATE_KEY, loadRecord, PROGRAM as UPDATE_PROGRAM, recordPath, STATE_AVAILABLE, } from './updatecheck.js';
 /**
  * The directory `p` names, as the KERNEL names it. `realpathSync.native`, not `realpathSync`.
@@ -227,15 +227,36 @@ function capLines(text, max) {
     }
     return out.join('\n');
 }
+/**
+ * The fact names this CONTEXT has already been shown, `name -> ISO stamp` (job64, J64-2).
+ *
+ * Lives under `ledger.injected[<transcript>]`, beside `reads`, so it inherits the ledger's
+ * reset points: `PostCompact` and `SessionStart source=compact` unlink the file, which is
+ * exactly when the model's window has been rebuilt and a name it was shown is gone again.
+ * The context key is the same one `reads` uses — `transcript_path` when the host sends it,
+ * `session_id` otherwise — because a subagent shares the parent's `session_id` (J64-0, Q3
+ * step 11) and therefore this FILE, while its window has never held what the parent was
+ * shown. A missing or malformed entry is "nothing seen", never an exception, for the reason
+ * `readLedger` gives. Both lookups here answer for OWN keys only (job64, J64-8): the objects
+ * are plain, read back from JSON, and keyed by user data, so a bare `[key]` read would hand
+ * back `Object.prototype`'s members for a key that happens to be one of its names.
+ */
+function injectedSeen(ledger, transcript) {
+    const everyone = ledger.injected;
+    if (!everyone || typeof everyone !== 'object' || Array.isArray(everyone))
+        return {};
+    const mine = Object.hasOwn(everyone, transcript) ? everyone[transcript] : undefined;
+    return mine && typeof mine === 'object' && !Array.isArray(mine) ? mine : {};
+}
 function ledgerPath(run, sessionId) {
     return path.join(run.state, `ledger-${String(sessionId || 'nosession').replace(/[^\w-]/g, '_')}.json`);
 }
 function readLedger(run, sessionId) {
     try {
         const parsed = JSON.parse(fs.readFileSync(ledgerPath(run, sessionId), 'utf8'));
-        if (!parsed || typeof parsed !== 'object')
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
             return { reads: {} };
-        if (!parsed.reads || typeof parsed.reads !== 'object')
+        if (!parsed.reads || typeof parsed.reads !== 'object' || Array.isArray(parsed.reads))
             parsed.reads = {};
         return parsed;
     }
@@ -684,8 +705,15 @@ const UPDATE_LINE_MAX = 500;
  * "then reconnect the host" is measured reason 1 in `selfupdate.py:13-20`: a running server
  * keeps serving the code it loaded at startup, so an updated install does nothing for THIS
  * session.
+ *
+ * THE COMMAND IS THE KEPT INSTALL'S OWN `cli.js`, RUN WITH NODE — not the bare `{program}`
+ * (2026-09-26). `--install` puts `bantamkit-mcp` in `<prefix>/node_modules/.bin`, which is on
+ * nobody's PATH, so the bare word this line used to print answered `command not found` on the
+ * machine it was measured on. `node "<cli>"` is what a host is already told to run
+ * (`npminstall.keptCli`), needs no PATH and no `.cmd` shim on Windows, and the double quotes
+ * hold a home directory with a space in it in zsh, bash, cmd and PowerShell alike.
  */
-const UPDATE_LINE = '[bantamkit] {program} {installed} at {path} is running; the package index has {latest} — run `{program} --update`, then reconnect the host.';
+const UPDATE_LINE = '[bantamkit] {program} {installed} at {path} is running; the package index has {latest} — run `node "{cli}" --update`, then reconnect the host.';
 /** `{name}` substitution. A missing key is left alone rather than rendered `undefined`. */
 function fillLine(template, values) {
     return template.replace(/\{([a-z]+)\}/g, (whole, name) => values[name] ?? whole);
@@ -705,11 +733,12 @@ function fillLine(template, values) {
  * second thing to keep in step with two runtimes. There is no comparator in this file.
  */
 function keptInstall(home) {
-    const manifest = keptManifest(keptPrefix(home));
+    const prefix = keptPrefix(home);
+    const manifest = keptManifest(prefix);
     try {
         const parsed = JSON.parse(fs.readFileSync(manifest, 'utf8'));
         const version = parsed && typeof parsed.version === 'string' ? parsed.version.trim() : '';
-        return version === '' ? null : { path: manifest, version };
+        return version === '' ? null : { path: manifest, cli: keptCli(prefix), version };
     }
     catch {
         return null;
@@ -739,6 +768,7 @@ function updateSignal(run) {
                 program: UPDATE_PROGRAM,
                 installed: kept.version,
                 path: kept.path,
+                cli: kept.cli,
                 latest,
             }), UPDATE_LINE_MAX);
         }
@@ -849,6 +879,21 @@ function sessionStart(run, input) {
             /* none */
         }
     }
+    else if (input.source === 'clear') {
+        // `/clear` empties the window the way a compaction does, and the host MAY keep the
+        // `session_id` across it (the real log cannot settle this: 4 kept, 12 changed, 15 unknown
+        // over 31 clears, with concurrent sessions confounding every count —
+        // `.shiftwork/notes-job64/J64-2.md`). So the names this session was shown are forgotten
+        // here either way; if the id changed there is no ledger and this is a no-op. Only the
+        // seen-set: whether a re-read after `/clear` should still be refused is the read ledger's
+        // own question, and `resume` restores the window, so it resets nothing. No ledger is
+        // created when none exists (job64, J64-2).
+        const ledger = readLedger(run, input.session_id);
+        if ('injected' in ledger) {
+            delete ledger.injected;
+            writeLedger(run, input.session_id, ledger);
+        }
+    }
     // `profileFacts` keeps its old meaning — files in the store — so older records stay
     // comparable; `profileInjected` / `profileDropped` are what the block carried and did
     // not, and `dropRule` is the order the drop followed. The project trio appears only when
@@ -959,7 +1004,12 @@ function userPromptSubmit(run, input) {
         return;
     }
     const m = Memory.layered(input.cwd || process.cwd());
-    const o = m.recallOutcome(prompt, 3);
+    // `stamp = false` (job64, J64-1): an injection is the HOOK reading the store, not the model
+    // asking for a fact, so it must not date `last_recalled`. Before this it did, on every
+    // prompt, for up to three files — and the rules keyed on that date (compaction's
+    // stalest-first, the SessionStart drop rule, the Stop dream's store fingerprint) were
+    // reading this arm's traffic. An explicit `memory_recall` still stamps.
+    const o = m.recallOutcome(prompt, 3, RECALL_MIN_SCORE_RATIO, false);
     if (o.status !== 'answered') {
         log(run, { event: 'UserPromptSubmit', action: 'none', status: o.status, candidates: o.candidates });
         return;
@@ -972,17 +1022,65 @@ function userPromptSubmit(run, input) {
         log(run, { event: 'UserPromptSubmit', action: 'none', reason: 'no-headers' });
         return;
     }
-    const ctx = capLines(`[bantamkit recall — memories that match this prompt; call mcp__bantamkit__memory_recall with {"query":"<name>"} for the body]\n${heads.join('\n')}`, PROMPT_INJECT_MAX);
+    // WHAT THIS CONTEXT HAS ALREADY BEEN SHOWN IS NOT SHOWN AGAIN (job64, J64-2). Measured
+    // 2026-09-25: 333 of 598 injections in a week repeated a name injected earlier in the same
+    // session. The top 3 are still asked for (RB-P1's floor stays) and the seen ones are
+    // DROPPED, not refilled from rank 4 onward: what leaves is always a subset of what the
+    // un-deduped arm would have sent, so its precision can only rise, and a repeated prompt
+    // says nothing rather than walking down the ranking on every repeat. The seen-set is the
+    // session ledger's, so it is forgotten exactly when the window is (compaction, `/clear`).
+    const transcript = String(input.transcript_path || input.session_id || '');
+    const ledger = readLedger(run, input.session_id);
+    const seen = injectedSeen(ledger, transcript);
+    const fresh = [];
+    const suppressed = [];
+    for (const line of heads) {
+        const name = RECALL_HEADER.exec(line)?.[2] ?? '';
+        // OWN keys only (job64, J64-8). `seen` is a plain object read back from JSON, and `in`
+        // walks `Object.prototype` — so `name in seen` was true for a fact named `constructor`
+        // (the one prototype key `NAME_RE` admits) on a context that had been shown nothing, and
+        // the port withheld it on the first prompt while the reference injected it.
+        if (Object.hasOwn(seen, name))
+            suppressed.push(name);
+        else
+            fresh.push(line);
+    }
+    if (fresh.length === 0) {
+        // Everything picked was already in the window. Nothing is emitted, and the record says
+        // WHY with the names, so an audit can count what dedupe withheld.
+        log(run, {
+            event: 'UserPromptSubmit',
+            action: 'suppress',
+            hits: heads.length,
+            source: o.source,
+            session: input.session_id ?? null,
+            prompt: promptFingerprint(prompt),
+            suppressed,
+        });
+        return;
+    }
+    const ctx = capLines(`[bantamkit recall — memories that match this prompt; call mcp__bantamkit__memory_recall with {"query":"<name>"} for the body]\n${fresh.join('\n')}`, PROMPT_INJECT_MAX);
     // `injected` is read back off `ctx`, NOT off `heads`. The byte cap drops whole lines, so a
     // header that `recallOutcome` picked need not have left the process — and roadmap #6 asks
     // "was an INJECTED name later used", a question a name the model never saw would poison.
     // `hits` keeps its old meaning (headers picked, pre-cap) so the 487 records written before
-    // this change stay comparable; `dropped` is the difference the old shape could not show.
+    // this change stay comparable; `dropped` is the difference the old shape could not show,
+    // counted over the unseen headers only, so that `hits == injected + dropped + suppressed`
+    // on every record.
     const queryTokens = tokens(prompt);
     const injected = ctx
         .split('\n')
         .map((l) => scoreHeader(l, queryTokens))
         .filter((x) => x !== null);
+    // Remembered AFTER the cap, off `injected`: a name the cap cut never reached the window and
+    // must be eligible next time.
+    const at = new Date().toISOString();
+    for (const x of injected)
+        seen[x.name] = at;
+    if (!ledger.injected || typeof ledger.injected !== 'object' || Array.isArray(ledger.injected))
+        ledger.injected = {};
+    ledger.injected[transcript] = seen;
+    writeLedger(run, input.session_id, ledger);
     log(run, {
         event: 'UserPromptSubmit',
         action: 'inject',
@@ -994,7 +1092,8 @@ function userPromptSubmit(run, input) {
         session: input.session_id ?? null,
         prompt: promptFingerprint(prompt),
         injected,
-        dropped: heads.length - injected.length,
+        dropped: fresh.length - injected.length,
+        suppressed,
     });
     emit({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: ctx } });
 }
@@ -1730,6 +1829,42 @@ function postCompact(run, input) {
 function samePath(a, b) {
     return realDir(a) === realDir(b);
 }
+/**
+ * sha256 of a fact file with the frontmatter's `last_recalled:` line left out.
+ *
+ * THE DATE IS NOT CONTENT. Every recall rewrites that one line (and the file's mtime), so a
+ * fingerprint that saw it re-armed the dream preview on every `memory_recall` — measured
+ * 2026-09-25 (job64): 103 of 236 previews in a week reported the identical `wouldMerge 14 /
+ * wouldConsume 14`. Name, description, type, created, links and the body all stay in.
+ *
+ * Byte-exact and identical in both runtimes (`_fact_content_digest` in
+ * `runtime-py/src/bantamkit/hookadapter.py`): the buffer is walked as latin1 so every byte
+ * is its own character, the split is on `\n`, a trailing `\r` is ignored only for the two
+ * comparisons (a Windows-written file keeps its bytes in the hash), and only the lines between
+ * the first two `---` fences are frontmatter — a body line that happens to start with
+ * `last_recalled:` is still content.
+ */
+function factContentDigest(data) {
+    const h = createHash('sha256');
+    let fences = 0;
+    for (const line of data.toString('latin1').split('\n')) {
+        const bare = line.endsWith('\r') ? line.slice(0, -1) : line;
+        if (bare === '---' && fences < 2)
+            fences++;
+        else if (fences === 1 && bare.startsWith('last_recalled:'))
+            continue;
+        h.update(line, 'latin1');
+        h.update('\n', 'latin1');
+    }
+    return h.digest('hex');
+}
+/**
+ * One hash over both layers: each root's name, then every `facts/*.md` as name + content
+ * digest. Adding, removing or renaming a fact moves it; editing any field but `last_recalled`
+ * moves it; a recall (which rewrites only that line and the mtime) does not. Neither size nor
+ * mtime is in it any more: J64-0 measured that a same-day re-stamp moves the mtime ALONE, so
+ * no stat field could be kept as a content signal (`.shiftwork/notes-job64/J64-0.md`, Q4).
+ */
 function storeFingerprint(roots) {
     const h = createHash('sha256');
     for (const root of roots) {
@@ -1745,14 +1880,14 @@ function storeFingerprint(roots) {
             /* a layer with no facts/ contributes its name and nothing else */
         }
         for (const n of names) {
-            let st;
+            let data;
             try {
-                st = fs.statSync(path.join(root, 'facts', n));
+                data = fs.readFileSync(path.join(root, 'facts', n));
             }
             catch {
                 continue;
             }
-            h.update(`${n}\u0000${st.size}\u0000${st.mtimeMs}\u0000`);
+            h.update(`${n}\u0000${factContentDigest(data)}\u0000`);
         }
     }
     return h.digest('hex');

package/dist/memory/component.d.ts

@@ -97,6 +97,13 @@ export interface RecallOutcome {
     readonly candidates: number;
     readonly source: string | null;
     readonly unreadable: number;
+    /**
+     * What the exact-name walk decided (job64, J64-4), read off the branch and not off the
+     * reply: `'hit'` when the query WAS a fact's name and that fact alone is the reply, `'miss'`
+     * when the query was shaped like a name, no layer held it, and the reply leads with the line
+     * that says so, `null` for every other query — the walk that has always run, unchanged.
+     */
+    readonly lookup: string | null;
 }
 /**
  * What `dream` DID, beside the sentence it says about it.
@@ -203,8 +210,45 @@ export declare class Memory {
      * raises out of the FIRST layer, which is the writable project store, so it surfaces as
      * the error it is rather than as an `unreadable` count — the read-only-layer `catch`
      * below would otherwise file a caller's bad argument as a corrupt grant.
+     *
+     * `stamp` (job64, J64-1) is whether a hit in the WRITABLE layer gets its `last_recalled`
+     * dated. It defaults to true, which is what every explicit recall — the `memory_recall`
+     * tool, the memory CLI, `Memory.recall` — has always done, and those callers do not pass
+     * it. The one caller that passes false is the hook's `UserPromptSubmit` arm: an automatic
+     * injection is not the model asking for a fact, and dating it as one was measured
+     * (2026-09-25) to stamp 25 of 42 facts in one store as "recalled today", so every rule
+     * keyed on `last_recalled` — compaction's stalest-first, SessionStart's drop rule — was
+     * reading injection traffic instead of model demand. Read-only layers are never stamped
+     * whatever this says.
+     *
+     * THE EXACT-NAME WALK (job64, J64-4) runs first, and only for a query in the name shape
+     * (`isNameShaped`: `pyStrip`ped, `NAME_RE`-valid, and carrying a hyphen — a bare word is a
+     * word search even when a fact is named by it). Measured 2026-09-25 on the operator's own stores: 4 of
+     * 28 `memory_recall` calls whose query was exactly a fact name came back with OTHER facts.
+     * One of those names existed in the PROFILE layer and was never reached, because the
+     * project layer's fuzzy hits filled the budget and the loop below breaks before the next
+     * layer is read — a name lookup is a request for one known fact, and the `k`-floor (RB-P1,
+     * ruled to stay 2026-09-25) has nothing to say about it. So: every layer is asked, in
+     * precedence order, `store.lookup(name)`; the first that holds it answers ALONE, stamped
+     * only if it is the writable layer, and no other layer is read after it. If no layer holds
+     * it, the reply leads with `missLine` and the ordinary walk follows, byte for byte what it
+     * would have said alone. Every query outside the shape never enters this block. The range
+     * check on `minRatio` runs BEFORE the walk for the same reason
+     * it runs before any file is read in `MemoryStore.recall`: a caller's bad argument must
+     * surface as the error it is, not be swallowed by an exact hit.
+     */
+    recallOutcome(query: string, k?: number | null, minRatio?: number, stamp?: boolean): RecallOutcome;
+    /**
+     * The exact-name walk: the first layer holding a fact named `name` answers alone.
+     *
+     * The counters mean what they mean in `recallOutcome`, over the layers this walk READ —
+     * `reached` stops at the layer that answered, `candidates` counts the facts in the layers
+     * up to and including it, and a corrupt read-only layer raises `unreadable` and is skipped
+     * exactly as the scoring walk skips it. `null` means no layer holds the name, and the
+     * caller falls through to the scoring walk with its own, fresh counters: the numbers a miss
+     * logs are the numbers the ordinary walk logs.
      */
-    recallOutcome(query: string, k?: number | null, minRatio?: number): RecallOutcome;
+    private lookupByName;
     /**
      * Archive the stalest facts until a fact as large as the biggest one kept will fit.
      *

package/dist/memory/component.js

@@ -31,8 +31,20 @@ import { BantamError } from '../errors.js';
 import { pyStrip } from './factfile.js';
 import { countFacts, loadGrants, MEMORY_DIR_ENV, PROJECT_STORE, resolveProjectStore, } from './layers.js';
 import { pyHome, pyJoin, pyName, pyParent, pyResolve, PyOSError, PyUnicodeDecodeError } from './pyfs.js';
-import { DEFAULT_INDEX_BUDGET, MemoryBudgetExceeded, MemoryStore, MemoryValidationError, pyHashKey, pyText, RECALL_MIN_SCORE_RATIO, } from './store.js';
+import { DEFAULT_INDEX_BUDGET, MemoryBudgetExceeded, MemoryStore, MemoryValidationError, MIN_RATIO_RANGE, pyHashKey, pyText, RECALL_MIN_SCORE_RATIO, } from './store.js';
 import { dream as runDream, formatFixed3, SUPERSEDED_HEADING } from './dream.js';
+// THE NAME SHAPE (job64, J64-4), spelled once here and once in the reference: a recall query,
+// after `pyStrip` (Python's `str.strip()`), that the store's own `NAME_RE` would accept as a
+// fact name AND that carries a hyphen. Anchored without the reference's trailing-newline
+// quirk, because the strip has already removed one — `_NAME_SHAPE.fullmatch` on the other side
+// is the same set. A query in this shape is looked up BY NAME in every layer before any
+// scoring happens, and a miss on it is said out loud. The hyphen is the whole distinction:
+// `deploy` is a word anyone might search, and stays the word search it has always been even
+// when a fact happens to be named `deploy` (the layered dedupe test pins that);
+// `deploy-command` is a name somebody typed from an index.
+const NAME_SHAPE = /^[a-z0-9][a-z0-9-]*$/;
+const isNameShaped = (query) => query.includes('-') && NAME_SHAPE.test(query);
+const missLine = (name) => `no fact named '${name}' in any layer bound here; matching by words instead:`;
 /**
  * The model's spelling adapted to the store's contract: lowercase, `_`/space -> `-`.
  *
@@ -303,9 +315,46 @@ export class Memory {
      * raises out of the FIRST layer, which is the writable project store, so it surfaces as
      * the error it is rather than as an `unreadable` count — the read-only-layer `catch`
      * below would otherwise file a caller's bad argument as a corrupt grant.
+     *
+     * `stamp` (job64, J64-1) is whether a hit in the WRITABLE layer gets its `last_recalled`
+     * dated. It defaults to true, which is what every explicit recall — the `memory_recall`
+     * tool, the memory CLI, `Memory.recall` — has always done, and those callers do not pass
+     * it. The one caller that passes false is the hook's `UserPromptSubmit` arm: an automatic
+     * injection is not the model asking for a fact, and dating it as one was measured
+     * (2026-09-25) to stamp 25 of 42 facts in one store as "recalled today", so every rule
+     * keyed on `last_recalled` — compaction's stalest-first, SessionStart's drop rule — was
+     * reading injection traffic instead of model demand. Read-only layers are never stamped
+     * whatever this says.
+     *
+     * THE EXACT-NAME WALK (job64, J64-4) runs first, and only for a query in the name shape
+     * (`isNameShaped`: `pyStrip`ped, `NAME_RE`-valid, and carrying a hyphen — a bare word is a
+     * word search even when a fact is named by it). Measured 2026-09-25 on the operator's own stores: 4 of
+     * 28 `memory_recall` calls whose query was exactly a fact name came back with OTHER facts.
+     * One of those names existed in the PROFILE layer and was never reached, because the
+     * project layer's fuzzy hits filled the budget and the loop below breaks before the next
+     * layer is read — a name lookup is a request for one known fact, and the `k`-floor (RB-P1,
+     * ruled to stay 2026-09-25) has nothing to say about it. So: every layer is asked, in
+     * precedence order, `store.lookup(name)`; the first that holds it answers ALONE, stamped
+     * only if it is the writable layer, and no other layer is read after it. If no layer holds
+     * it, the reply leads with `missLine` and the ordinary walk follows, byte for byte what it
+     * would have said alone. Every query outside the shape never enters this block. The range
+     * check on `minRatio` runs BEFORE the walk for the same reason
+     * it runs before any file is read in `MemoryStore.recall`: a caller's bad argument must
+     * surface as the error it is, not be swallowed by an exact hit.
      */
-    recallOutcome(query, k = null, minRatio = RECALL_MIN_SCORE_RATIO) {
+    recallOutcome(query, k = null, minRatio = RECALL_MIN_SCORE_RATIO, stamp = true) {
+        // `not 0.0 <= min_ratio <= 1.0`: NaN fails the same chain on both sides.
+        if (!(minRatio >= 0 && minRatio <= 1))
+            throw new MemoryValidationError(MIN_RATIO_RANGE);
         const budget = k === null ? this.k : Math.max(k, this.k);
+        const name = pyStrip(query);
+        let lookup = null;
+        if (isNameShaped(name)) {
+            const named = this.lookupByName(name, budget, stamp);
+            if (named !== null)
+                return named;
+            lookup = 'miss';
+        }
         const picked = [];
         const seen = new Set();
         let reached = 0;
@@ -317,7 +366,7 @@ export class Memory {
             reached += 1;
             let facts;
             try {
-                facts = store.recall(query, budget, writable, minRatio);
+                facts = store.recall(query, budget, writable && stamp, minRatio);
             }
             catch (e) {
                 if (!(e instanceof BantamError || e instanceof PyOSError || e instanceof PyUnicodeDecodeError)) {
@@ -354,18 +403,74 @@ export class Memory {
             returned: picked.length,
             candidates,
             unreadable,
+            lookup,
         };
+        const lead = lookup === 'miss' ? `${missLine(name)}\n\n` : '';
         if (picked.length === 0) {
             const [status, reply] = this.nothingToReport();
-            return { reply, status, source: null, ...counts };
+            return { reply: lead + reply, status, source: null, ...counts };
         }
         return {
-            reply: picked.map(([label, fact]) => this.format(label, fact)).join('\n\n'),
+            reply: lead + picked.map(([label, fact]) => this.format(label, fact)).join('\n\n'),
             status: 'answered',
             source: picked[0][0].split(':', 1)[0],
             ...counts,
         };
     }
+    /**
+     * The exact-name walk: the first layer holding a fact named `name` answers alone.
+     *
+     * The counters mean what they mean in `recallOutcome`, over the layers this walk READ —
+     * `reached` stops at the layer that answered, `candidates` counts the facts in the layers
+     * up to and including it, and a corrupt read-only layer raises `unreadable` and is skipped
+     * exactly as the scoring walk skips it. `null` means no layer holds the name, and the
+     * caller falls through to the scoring walk with its own, fresh counters: the numbers a miss
+     * logs are the numbers the ordinary walk logs.
+     */
+    lookupByName(name, budget, stamp) {
+        let reached = 0;
+        let unreadable = 0;
+        let candidates = 0;
+        for (const [label, store, writable] of this.layers) {
+            reached += 1;
+            let fact;
+            try {
+                fact = store.lookup(name, writable && stamp);
+            }
+            catch (e) {
+                if (!(e instanceof BantamError || e instanceof PyOSError || e instanceof PyUnicodeDecodeError)) {
+                    throw e;
+                }
+                if (writable)
+                    throw e; // the project layer failing is a real error, as in the scoring walk
+                unreadable += 1;
+                continue;
+            }
+            try {
+                candidates += countFacts(store.root);
+            }
+            catch (e) {
+                // It listed a moment ago; a race must not fail the recall for a log field.
+                if (!(e instanceof PyOSError))
+                    throw e;
+            }
+            if (fact !== null) {
+                return {
+                    reply: this.format(label, fact),
+                    status: 'answered',
+                    source: label.split(':', 1)[0],
+                    budget,
+                    layers: this.layers.length,
+                    reached,
+                    returned: 1,
+                    candidates,
+                    unreadable,
+                    lookup: 'hit',
+                };
+            }
+        }
+        return null;
+    }
     /**
      * Archive the stalest facts until a fact as large as the biggest one kept will fit.
      *

package/dist/memory/store.d.ts

@@ -92,6 +92,7 @@ export declare const VALID_TYPES: readonly ["feedback", "project", "reference",
 export declare const DURABLE_TYPES: readonly ["feedback", "user"];
 export declare const DUPLICATE_JACCARD = 0.5;
 export declare const RECALL_MIN_SCORE_RATIO = 0;
+export declare const MIN_RATIO_RANGE = "recall min-score ratio must be between 0.0 and 1.0";
 /** See the reference's comment: measured against a real store, not chosen. */
 export declare const DEFAULT_INDEX_BUDGET = 24000;
 /**
@@ -356,6 +357,23 @@ export declare class MemoryStore {
      * it is killed on both sides.
      */
     recall(query: string, k?: number | null, stamp?: boolean, minRatio?: number): Fact[];
+    /**
+     * The fact whose `name` field is exactly `name`, or `null`; no scoring, no ranking.
+     *
+     * WHY THIS EXISTS (job64, J64-4): `component.Memory` walks the layers looking for a fact
+     * the model asked for BY NAME, and `recall` cannot answer that question — it scores by
+     * token overlap, ties are broken by name, and every hit inside `k` is stamped, so there is
+     * no `k` that returns "the one named X and dates only that one". This is the public
+     * primitive that keeps `facts()`/`stamp()` private (see `factCount`'s docstring for why
+     * they are) and `internals()` at its one caller.
+     *
+     * `===` against the `name` field as `facts()` resolved it: a hand-edited `name: 7` is a
+     * number here and an `int` in the reference, and neither equals a string, so it is never an
+     * exact hit on either side. Two files claiming one name answer the first in `factPaths`
+     * order, which is the order `recall` breaks a tie in. `stamp` dates the hit through
+     * `stamp()` exactly as `recall` dates its hits; a miss writes nothing.
+     */
+    lookup(name: string, stamp?: boolean): Fact | null;
     /**
      * `len(store._facts())` at the operator CLI, which is the only caller.
      *

package/dist/memory/store.js

@@ -211,7 +211,11 @@ export const RECALL_MIN_SCORE_RATIO = 0.0;
 // Spelled once because both runtimes raise it verbatim. The offending value is NOT
 // interpolated: Python renders `2.0` as `2.0` and JavaScript renders it as `2`, so a
 // sentence carrying the number would be a divergence manufactured by float formatting.
-const MIN_RATIO_RANGE = 'recall min-score ratio must be between 0.0 and 1.0';
+// PUBLIC SINCE J64-4, ON BOTH SIDES, for the same reason `tokens` is: `component.Memory` runs
+// the range check itself now, before an exact-name walk reads a file, and it must throw the
+// store's sentence and not a second spelling of it. The reference spells it `MIN_RATIO_RANGE`
+// beside its private alias.
+export const MIN_RATIO_RANGE = 'recall min-score ratio must be between 0.0 and 1.0';
 /** See the reference's comment: measured against a real store, not chosen. */
 export const DEFAULT_INDEX_BUDGET = 24_000;
 /**
@@ -778,6 +782,32 @@ export class MemoryStore {
                 this.stamp(fact);
         return hits;
     }
+    /**
+     * The fact whose `name` field is exactly `name`, or `null`; no scoring, no ranking.
+     *
+     * WHY THIS EXISTS (job64, J64-4): `component.Memory` walks the layers looking for a fact
+     * the model asked for BY NAME, and `recall` cannot answer that question — it scores by
+     * token overlap, ties are broken by name, and every hit inside `k` is stamped, so there is
+     * no `k` that returns "the one named X and dates only that one". This is the public
+     * primitive that keeps `facts()`/`stamp()` private (see `factCount`'s docstring for why
+     * they are) and `internals()` at its one caller.
+     *
+     * `===` against the `name` field as `facts()` resolved it: a hand-edited `name: 7` is a
+     * number here and an `int` in the reference, and neither equals a string, so it is never an
+     * exact hit on either side. Two files claiming one name answer the first in `factPaths`
+     * order, which is the order `recall` breaks a tie in. `stamp` dates the hit through
+     * `stamp()` exactly as `recall` dates its hits; a miss writes nothing.
+     */
+    lookup(name, stamp = true) {
+        for (const fact of this.facts()) {
+            if (typeof fact.name === 'string' && fact.name === name) {
+                if (stamp)
+                    this.stamp(fact);
+                return fact;
+            }
+        }
+        return null;
+    }
     /**
      * `len(store._facts())` at the operator CLI, which is the only caller.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bantamkit-mcp",
-  "version": "0.35.5",
+  "version": "0.35.7",
   "description": "Memory MCP server for Claude Code, Cursor, VS Code Copilot and Claude Desktop: per-person memory, JSON Schema validation, shift-work tools. Pure Node; install once with npx, run offline.",
   "keywords": [
     "mcp",