bantamkit 0.35.4__tar.gz → 0.35.6__tar.gz

{bantamkit-0.35.4 → bantamkit-0.35.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bantamkit
-Version: 0.35.4
+Version: 0.35.6
 Summary: Memory MCP server for Claude Code, Cursor, VS Code Copilot and Claude Desktop, plus a Python library that lifts small-model agents. Install once, run offline.
 Project-URL: Homepage, https://github.com/Ink01101011/bantamkit
 Project-URL: Repository, https://github.com/Ink01101011/bantamkit
@@ -103,9 +103,9 @@ CPU architecture and Python minor version** (some wheels, such as `pydantic_core
 one platform only), copy `wheels/` across, and install from it:
 
 ```bash
-python -m pip download "bantamkit[mcp]==0.35.4" -d wheels
+python -m pip download "bantamkit[mcp]==0.35.6" -d wheels
 python -m venv <env>
-<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.35.4"
+<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.35.6"
 <env>/bin/bantamkit-mcp --install cursor
 ```
 

{bantamkit-0.35.4 → bantamkit-0.35.6}/README.md

@@ -74,9 +74,9 @@ CPU architecture and Python minor version** (some wheels, such as `pydantic_core
 one platform only), copy `wheels/` across, and install from it:
 
 ```bash
-python -m pip download "bantamkit[mcp]==0.35.4" -d wheels
+python -m pip download "bantamkit[mcp]==0.35.6" -d wheels
 python -m venv <env>
-<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.35.4"
+<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.35.6"
 <env>/bin/bantamkit-mcp --install cursor
 ```
 

{bantamkit-0.35.4 → bantamkit-0.35.6}/_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."
       }
     }
   },

{bantamkit-0.35.4 → bantamkit-0.35.6}/src/bantamkit/__init__.py

@@ -29,4 +29,4 @@ from bantamkit.structured import StructuredOutputError, extract_json, structured
 # file as its dynamic version source, so the wheel's metadata and the string the MCP
 # server advertises are the same committed bytes, and neither is a function of when
 # someone last ran `pip`.
-__version__ = "0.35.4"
+__version__ = "0.35.6"

{bantamkit-0.35.4 → bantamkit-0.35.6}/src/bantamkit/hookadapter.py

@@ -375,6 +375,25 @@ def _write_ledger(run: HookRun, session_id: Any, ledger: dict[str, Any]) -> None
         fh.write(_dumps(ledger))
 
 
+def _injected_seen(ledger: dict[str, Any], transcript: str) -> dict[str, Any]:
+    """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 `_read_ledger` gives.
+    """
+    everyone = ledger.get("injected")
+    if not isinstance(everyone, dict):
+        return {}
+    mine = everyone.get(transcript)
+    return mine if isinstance(mine, dict) else {}
+
+
 def _write_json_safe(file: str, value: Any) -> None:
     """Best-effort marker write. A marker that cannot be written costs a repeated dream."""
     try:
@@ -909,6 +928,19 @@ def _session_start(run: HookRun, payload: dict[str, Any]) -> None:
             os.unlink(_ledger_path(run, payload.get("session_id")))
         except OSError:
             pass
+    elif payload.get("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).
+        ledger = _read_ledger(run, payload.get("session_id"))
+        if "injected" in ledger:
+            del ledger["injected"]
+            _write_ledger(run, payload.get("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
@@ -1027,7 +1059,12 @@ def _user_prompt_submit(run: HookRun, payload: dict[str, Any]) -> None:
         _log(run, {"event": "UserPromptSubmit", "action": "skip", "reason": "short-or-command"})
         return
     m = Memory.layered(str(payload.get("cwd") or os.getcwd()))
-    o = m.recall_outcome(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.
+    o = m.recall_outcome(prompt, 3, stamp=False)
     if o.status != "answered":
         _log(
             run,
@@ -1046,7 +1083,42 @@ def _user_prompt_submit(run: HookRun, payload: dict[str, Any]) -> None:
     if not heads:
         _log(run, {"event": "UserPromptSubmit", "action": "none", "reason": "no-headers"})
         return
-    joined = "\n".join(heads)
+    # 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`).
+    transcript = _js_str(payload.get("transcript_path") or payload.get("session_id") or "")
+    ledger = _read_ledger(run, payload.get("session_id"))
+    seen = _injected_seen(ledger, transcript)
+    fresh: list[str] = []
+    suppressed: list[str] = []
+    for line in heads:
+        matched = RECALL_HEADER.match(line)
+        name = matched.group(2) if matched else ""
+        if name in seen:
+            suppressed.append(name)
+        else:
+            fresh.append(line)
+    if not fresh:
+        # 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": len(heads),
+                "source": o.source,
+                "session": payload.get("session_id"),
+                "prompt": _prompt_fingerprint(prompt),
+                "suppressed": suppressed,
+            },
+        )
+        return
+    joined = "\n".join(fresh)
     ctx = _cap_lines(
         "[bantamkit recall — memories that match this prompt; call "
         'mcp__bantamkit__memory_recall with {"query":"<name>"} for the body]\n'
@@ -1058,13 +1130,25 @@ def _user_prompt_submit(run: HookRun, payload: dict[str, Any]) -> None:
     # 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.
+    # could not show, counted over the unseen headers only, so that
+    # `hits == injected + dropped + suppressed` on every record.
     query_tokens = tokens(prompt)
     injected = [
         scored
         for scored in (_score_header(line, query_tokens) for line in ctx.split("\n"))
         if scored is not None
     ]
+    # Remembered AFTER the cap, off `injected`: a name the cap cut never reached the window
+    # and must be eligible next time.
+    at = _stamp()
+    for scored in injected:
+        seen[scored["name"]] = at
+    everyone = ledger.get("injected")
+    if not isinstance(everyone, dict):
+        everyone = {}
+        ledger["injected"] = everyone
+    everyone[transcript] = seen
+    _write_ledger(run, payload.get("session_id"), ledger)
     _log(
         run,
         {
@@ -1079,7 +1163,8 @@ def _user_prompt_submit(run: HookRun, payload: dict[str, Any]) -> None:
             "session": payload.get("session_id"),
             "prompt": _prompt_fingerprint(prompt),
             "injected": injected,
-            "dropped": len(heads) - len(injected),
+            "dropped": len(fresh) - len(injected),
+            "suppressed": suppressed,
         },
     )
     _emit({"hookSpecificOutput": {"hookEventName": "UserPromptSubmit", "additionalContext": ctx}})
@@ -1773,7 +1858,40 @@ def _same_path(a: str, b: str) -> bool:
     return _real_dir(a) == _real_dir(b)
 
 
+def _fact_content_digest(data: bytes) -> str:
+    """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 (`factContentDigest` in
+    `runtime-ts/src/hookadapter.ts`): 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.
+    """
+    h = hashlib.sha256()
+    fences = 0
+    for line in data.split(b"\n"):
+        bare = line[:-1] if line.endswith(b"\r") else line
+        if bare == b"---" and fences < 2:
+            fences += 1
+        elif fences == 1 and bare.startswith(b"last_recalled:"):
+            continue
+        h.update(line)
+        h.update(b"\n")
+    return h.hexdigest()
+
+
 def _store_fingerprint(roots: list[str]) -> str:
+    """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).
+    """
     h = hashlib.sha256()
     for root in roots:
         h.update(f"\u0000{root}\u0000".encode())
@@ -1785,10 +1903,11 @@ def _store_fingerprint(roots: list[str]) -> str:
             names = []  # a layer with no facts/ contributes its name and nothing else
         for n in names:
             try:
-                st = os.stat(os.path.join(root, "facts", n))
+                with open(os.path.join(root, "facts", n), "rb") as f:
+                    data = f.read()
             except OSError:
                 continue
-            h.update(f"{n}\u0000{st.st_size}\u0000{_js_number(_mtime_ms(st))}\u0000".encode())
+            h.update(f"{n}\u0000{_fact_content_digest(data)}\u0000".encode())
     return h.hexdigest()
 
 

{bantamkit-0.35.4 → bantamkit-0.35.6}/src/bantamkit/memory/component.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import os
+import re
 from collections.abc import Iterator
 from contextlib import ExitStack, contextmanager
 from dataclasses import dataclass
@@ -23,6 +24,7 @@ from bantamkit.memory.layers import (
 )
 from bantamkit.memory.store import (
     DEFAULT_INDEX_BUDGET,
+    MIN_RATIO_RANGE,
     RECALL_MIN_SCORE_RATIO,
     Fact,
     MemoryBudgetExceeded,
@@ -69,6 +71,12 @@ class RecallOutcome:
     `project`, `extra` or `profile` — deliberately not the layer's full label, because
     `extra:<name>` carries a directory name off the operator's disk and the log this
     feeds is metadata-only.
+
+    `lookup` (job64, J64-4) is what the exact-name walk decided, again 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, `None` for every other query — the walk that has
+    always run, unchanged.
     """
 
     reply: str
@@ -80,6 +88,7 @@ class RecallOutcome:
     candidates: int
     source: str | None = None
     unreadable: int = 0
+    lookup: str | None = None
 
 
 def normalize_name(name: str) -> str:
@@ -96,6 +105,26 @@ def normalize_name(name: str) -> str:
     return name.strip().lower().replace("_", "-").replace(" ", "-")
 
 
+# THE NAME SHAPE (job64, J64-4), spelled once here and once in the port: a recall query,
+# after `str.strip()`, that the store's own `NAME_RE` would accept as a fact name AND that
+# carries a hyphen. `fullmatch` rather than `NAME_RE.match`, because Python's `$` matches
+# before a trailing newline and the strip has already removed one; the port's `pyStrip` +
+# anchored test 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.
+_NAME_SHAPE = re.compile(r"[a-z0-9][a-z0-9-]*")
+
+
+def _is_name_shaped(query: str) -> bool:
+    return "-" in query and _NAME_SHAPE.fullmatch(query) is not None
+
+
+def _miss_line(name: str) -> str:
+    return f"no fact named '{name}' in any layer bound here; matching by words instead:"
+
+
 @dataclass(frozen=True)
 class CompactOutcome:
     """What `compact` DID, beside the sentence it says about it.
@@ -371,6 +400,8 @@ class Memory:
         query: str,
         k: int | None = None,
         min_ratio: float = RECALL_MIN_SCORE_RATIO,
+        *,
+        stamp: bool = True,
     ) -> RecallOutcome:
         """`recall`, carrying the walk it performed as numbers rather than as prose.
 
@@ -398,8 +429,45 @@ class Memory:
         store, so it surfaces as the error it is rather than as an `unreadable` count —
         the read-only-layer `except` 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 (`_is_name_shaped`: `strip()`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 `_miss_line` 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 `min_ratio` 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.
         """
+        if not 0.0 <= min_ratio <= 1.0:
+            raise MemoryValidationError(MIN_RATIO_RANGE)
         budget = self.k if k is None else max(k, self.k)
+        name = query.strip()
+        lookup: str | None = None
+        if _is_name_shaped(name):
+            named = self._lookup_by_name(name, budget, stamp)
+            if named is not None:
+                return named
+            lookup = "miss"
         picked: list[tuple[str, Fact]] = []
         seen: set[str] = set()
         reached = 0
@@ -410,7 +478,7 @@ class Memory:
                 break  # budget spent: later (read-only) layers are never even read
             reached += 1
             try:
-                facts = store.recall(query, budget, stamp=writable, min_ratio=min_ratio)
+                facts = store.recall(query, budget, stamp=writable and stamp, min_ratio=min_ratio)
             except (BantamError, OSError, UnicodeDecodeError):
                 if writable:
                     raise  # the project layer failing is a real error, as in v1
@@ -434,17 +502,60 @@ class Memory:
             "returned": len(picked),
             "candidates": candidates,
             "unreadable": unreadable,
+            "lookup": lookup,
         }
+        lead = f"{_miss_line(name)}\n\n" if lookup == "miss" else ""
         if not picked:
             status, reply = self._nothing_to_report()
-            return RecallOutcome(reply=reply, status=status, **counts)
+            return RecallOutcome(reply=lead + reply, status=status, **counts)
         return RecallOutcome(
-            reply="\n\n".join(self._format(label, fact) for label, fact in picked),
+            reply=lead + "\n\n".join(self._format(label, fact) for label, fact in picked),
             status="answered",
             source=picked[0][0].split(":", 1)[0],
             **counts,
         )
 
+    def _lookup_by_name(self, name: str, budget: int, stamp: bool) -> RecallOutcome | None:
+        """The exact-name walk: the first layer holding a fact named `name` answers alone.
+
+        The counters mean what they mean in `recall_outcome`, 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. `None` 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.
+        """
+        reached = 0
+        unreadable = 0
+        candidates = 0
+        for label, store, writable in self._layers:
+            reached += 1
+            try:
+                fact = store.lookup(name, stamp=writable and stamp)
+            except (BantamError, OSError, UnicodeDecodeError):
+                if writable:
+                    raise  # the project layer failing is a real error, as in the scoring walk
+                unreadable += 1
+                continue
+            try:
+                candidates += count_facts(store.root)
+            except OSError:
+                pass  # it listed a moment ago; a race must not fail the recall for a log field
+            if fact is not None:
+                return RecallOutcome(
+                    reply=self._format(label, fact),
+                    status="answered",
+                    source=label.split(":", 1)[0],
+                    budget=budget,
+                    layers=len(self._layers),
+                    reached=reached,
+                    returned=1,
+                    candidates=candidates,
+                    unreadable=unreadable,
+                    lookup="hit",
+                )
+        return None
+
     def index_accounting(self) -> tuple[int | None, int]:
         """`(index bytes, budget)` for the writable project store; bytes may be `None`.
 

{bantamkit-0.35.4 → bantamkit-0.35.6}/src/bantamkit/memory/store.py

@@ -75,6 +75,10 @@ RECALL_MIN_SCORE_RATIO = 0.0
 # 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.
 _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 raise the
+# store's sentence and not a second spelling of it. The private name is kept as an alias.
+MIN_RATIO_RANGE = _MIN_RATIO_RANGE
 
 # The index is loaded into the prompt every session, so this is a context bill, not a
 # disk limit. It was 4096 and that number was never measured against a real store.
@@ -614,6 +618,36 @@ class MemoryStore:
                 self._stamp(fact)
         return hits
 
+    def lookup(self, name: str, stamp: bool = True) -> Fact | None:
+        """The fact whose `name` field is exactly `name`, or `None`; 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, so the named fact ties with any fact whose name and
+        description happen to contain the same words, the tie is broken by name, and
+        every hit inside `k` is stamped — there is no `k` that returns "the one named X
+        and dates only that one". A caller reaching for `_facts`/`_stamp` instead would be
+        the private-name crossing the `tokens` docstring above spends a paragraph refusing.
+
+        The comparison is `==` against the `name` field as `_facts` resolved it, not against
+        the file name: a hand-edited `name:` that no longer matches its path is found by
+        what it SAYS it is, which is what `recall` and the index line already go by. Two
+        files claiming one name answer the first in `_fact_paths` order, the same order
+        `recall` breaks a tie in. A non-string `name` (`name: 7`) never equals a string, so
+        it is never an exact hit; the port compares with `===` for the same reason.
+
+        `stamp` dates the hit through `_stamp`, exactly as `recall` dates its hits, snapshot
+        semantics included; nothing else on disk is touched, and a miss writes nothing.
+        An unreadable store raises out of `_facts` here as it does out of `recall`, and
+        `component.Memory` treats the two the same way per layer.
+        """
+        for fact in self._snapshot if self._snapshot is not None else self._facts():
+            if fact.name == name:
+                if stamp:
+                    self._stamp(fact)
+                return fact
+        return None
+
     def lint(self) -> None:
         """Every fact parses and carries a valid type, and the index fits its budget.
 

{bantamkit-0.35.4 → bantamkit-0.35.6}/tests/data/served-tool-surface.json

@@ -77,7 +77,7 @@
       }
     },
     "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.",
       "inputSchema": {
         "properties": {
           "query": {
@@ -87,7 +87,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."
           }
         },
         "required": [