bantamkit 0.36.0__tar.gz → 0.37.0b2__tar.gz

{bantamkit-0.36.0 → bantamkit-0.37.0b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bantamkit
-Version: 0.36.0
+Version: 0.37.0b2
 Summary: Persistent memory for coding agents: an MCP server for Claude Code, Claude Desktop, Cursor and VS Code Copilot, 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
@@ -79,7 +79,7 @@ Then restart the host (in Claude Code, open a new session) and ask the agent to
   ([docs/hooks.md](https://github.com/Ink01101011/bantamkit/blob/main/docs/hooks.md)).
 - **More than memory.** JSON Schema validation, a token ledger read off the host's transcripts,
   a skill-catalogue audit, and shift-work tools that plan and hand off multi-step jobs —
-  [the fourteen tools](#-what-it-serves).
+  [the fifteen tools](#-what-it-serves).
 - **Same answers as the Node server.** The two share a memory store on disk, and every surface
   is compared between both runtimes by a conformance suite (`node tools/conformance/run.mjs
   --all` in the repository), so install whichever your host makes easy.
@@ -102,7 +102,7 @@ Then restart the host (in Claude Code, open a new session) and ask the agent to
 | [Configuration](#-configuration) | Every flag and variable, with its default |
 | [Update](#-update) | `--update`, pipx, uv, then restart |
 | [Troubleshooting](#-troubleshooting) | Timeouts, refusals, the wrong store |
-| [What it serves](#-what-it-serves) | 14 tools, one prompt, two resource templates |
+| [What it serves](#-what-it-serves) | 15 tools, one prompt, two resource templates |
 | [Requirements](#-requirements) | Python and dependencies |
 | [The asset pack](#-the-asset-pack) | `--assets-root`, `BANTAMKIT_ASSETS` |
 | [The operator CLI: `python -m bantamkit.memory`](#-the-operator-cli-python--m-bantamkitmemory) | status, lint, compact, archived, archive, restore |
@@ -144,9 +144,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.36.0" -d wheels
+python -m pip download "bantamkit[mcp]==0.37.0b2" -d wheels
 python -m venv <env>
-<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.36.0"
+<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.37.0b2"
 <env>/bin/bantamkit-mcp --install cursor
 ```
 
@@ -327,7 +327,7 @@ you**; a new version with an old `build_id` means an old process.
 
 ## 🧰 What it serves
 
-It serves 14 tools, the `bantamkit_status` prompt and two resource templates
+It serves 15 tools, the `bantamkit_status` prompt and two resource templates
 (`bantamkit://skills/{name}`, `bantamkit://rubrics/{name}`):
 
 | Tool | What it does |
@@ -336,6 +336,7 @@ It serves 14 tools, the `bantamkit_status` prompt and two resource templates
 | `memory_recall` | retrieve facts matching a query |
 | `memory_compact` | archive the stalest facts to fit the index budget |
 | `memory_dream` | consolidate facts the project and profile layers hold under the same name |
+| `memory_queries` | list the facts that have no likely-prompt queries yet, and store the queries written for them; recall matches a prompt against them |
 | `validate_json` | validate a document against a JSON Schema |
 | `skill_audit` | audit a skill catalogue for findings |
 | `shiftwork_clock_in` | open a unit of work and get its brief |
@@ -433,7 +434,7 @@ as a side effect of the package's own imports (`agent`, `assets`, `budget`, `cli
 | `bantamkit.memory` | the memory store | `Memory`, `MemoryStore` |
 | **9 modules** | | **30 values, no `__all__`** |
 
-**This is not the npm package's export surface.** Both runtimes serve the same fourteen MCP
+**This is not the npm package's export surface.** Both runtimes serve the same fifteen MCP
 tools, but what each one exports *to an importer* is a different product: here it is the
 agent/critique/eval library above; there it is the memory store, the asset pack, the event log,
 the shift-work tools and a set of CPython-semantics shims — 141 values behind one entry point. Of

{bantamkit-0.36.0 → bantamkit-0.37.0b2}/README.md

@@ -48,7 +48,7 @@ Then restart the host (in Claude Code, open a new session) and ask the agent to
   ([docs/hooks.md](https://github.com/Ink01101011/bantamkit/blob/main/docs/hooks.md)).
 - **More than memory.** JSON Schema validation, a token ledger read off the host's transcripts,
   a skill-catalogue audit, and shift-work tools that plan and hand off multi-step jobs —
-  [the fourteen tools](#-what-it-serves).
+  [the fifteen tools](#-what-it-serves).
 - **Same answers as the Node server.** The two share a memory store on disk, and every surface
   is compared between both runtimes by a conformance suite (`node tools/conformance/run.mjs
   --all` in the repository), so install whichever your host makes easy.
@@ -71,7 +71,7 @@ Then restart the host (in Claude Code, open a new session) and ask the agent to
 | [Configuration](#-configuration) | Every flag and variable, with its default |
 | [Update](#-update) | `--update`, pipx, uv, then restart |
 | [Troubleshooting](#-troubleshooting) | Timeouts, refusals, the wrong store |
-| [What it serves](#-what-it-serves) | 14 tools, one prompt, two resource templates |
+| [What it serves](#-what-it-serves) | 15 tools, one prompt, two resource templates |
 | [Requirements](#-requirements) | Python and dependencies |
 | [The asset pack](#-the-asset-pack) | `--assets-root`, `BANTAMKIT_ASSETS` |
 | [The operator CLI: `python -m bantamkit.memory`](#-the-operator-cli-python--m-bantamkitmemory) | status, lint, compact, archived, archive, restore |
@@ -113,9 +113,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.36.0" -d wheels
+python -m pip download "bantamkit[mcp]==0.37.0b2" -d wheels
 python -m venv <env>
-<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.36.0"
+<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.37.0b2"
 <env>/bin/bantamkit-mcp --install cursor
 ```
 
@@ -296,7 +296,7 @@ you**; a new version with an old `build_id` means an old process.
 
 ## 🧰 What it serves
 
-It serves 14 tools, the `bantamkit_status` prompt and two resource templates
+It serves 15 tools, the `bantamkit_status` prompt and two resource templates
 (`bantamkit://skills/{name}`, `bantamkit://rubrics/{name}`):
 
 | Tool | What it does |
@@ -305,6 +305,7 @@ It serves 14 tools, the `bantamkit_status` prompt and two resource templates
 | `memory_recall` | retrieve facts matching a query |
 | `memory_compact` | archive the stalest facts to fit the index budget |
 | `memory_dream` | consolidate facts the project and profile layers hold under the same name |
+| `memory_queries` | list the facts that have no likely-prompt queries yet, and store the queries written for them; recall matches a prompt against them |
 | `validate_json` | validate a document against a JSON Schema |
 | `skill_audit` | audit a skill catalogue for findings |
 | `shiftwork_clock_in` | open a unit of work and get its brief |
@@ -402,7 +403,7 @@ as a side effect of the package's own imports (`agent`, `assets`, `budget`, `cli
 | `bantamkit.memory` | the memory store | `Memory`, `MemoryStore` |
 | **9 modules** | | **30 values, no `__all__`** |
 
-**This is not the npm package's export surface.** Both runtimes serve the same fourteen MCP
+**This is not the npm package's export surface.** Both runtimes serve the same fifteen MCP
 tools, but what each one exports *to an importer* is a different product: here it is the
 agent/critique/eval library above; there it is the memory store, the asset pack, the event log,
 the shift-work tools and a set of CPython-semantics shims — 141 values behind one entry point. Of

bantamkit-0.37.0b2/_assets/skills/memory-queries.md

@@ -0,0 +1,12 @@
+# Likely-prompt queries
+
+For each fact, write the prompts a user would type to a coding assistant when this fact is what they need.
+
+- Three in the user's own language and three in English (`queries` holds all six, the user's language first).
+- Short: 5 to 25 words. Vary them: one direct question, one task request, one terse follow-up.
+- Keep technical terms in English where the user would: commands, file names, product names, error codes.
+- Use only what the fact says. Do not invent facts, do not just restate the fact's name, and never copy more than
+  five words of the body verbatim.
+
+Store them with `memory_queries` (`{"facts": [{"name": ..., "layer": ..., "queries": [...]}]}`), or pass
+`queries` to `memory_save` when you save the fact.

{bantamkit-0.36.0 → bantamkit-0.37.0b2}/_assets/skills/memory.md

@@ -22,6 +22,13 @@ past-you would have used. Do this before acting, not after.
 
 Write it to match the future recall QUERY, not to summarize the body.
 Ask: "what words will future-me search with?" Put related memory names in links.
+Fill keywords with the words the user will actually type, in their language — recall matches those too.
+
+## Likely-prompt queries
+
+When you save, also pass `queries`: three prompts in the user's language and three in English that a user would
+type when this fact is what they need. Short and varied, technical terms kept in English, never more than five
+words copied from the body. When `memory_queries` lists facts without queries, write theirs.
 
 ## On "duplicate" replies
 

bantamkit-0.37.0b2/_assets/tools/memory_queries.json

@@ -0,0 +1,58 @@
+{
+  "name": "memory_queries",
+  "title": "Likely-prompt queries for saved facts",
+  "description": "Call with {} to list up to 10 facts that have no likely-prompt queries yet, with what to write for them. Call with {\"facts\": [{\"name\", \"layer\"?, \"queries\"}]} to store queries you wrote. Recall matches a prompt against these queries.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "facts": {
+        "anyOf": [
+          {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string"
+                },
+                "layer": {
+                  "type": "string",
+                  "description": "project, profile, extra:<name> or native; optional: the first layer holding the name"
+                },
+                "queries": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "required": [
+                "name",
+                "queries"
+              ]
+            }
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Omit to list the facts missing queries"
+      }
+    },
+    "title": "memory_queriesArguments",
+    "additionalProperties": false
+  },
+  "output_schema": {
+    "type": "object",
+    "additionalProperties": true,
+    "title": "memory_queriesDictOutput"
+  },
+  "annotations": {
+    "readOnlyHint": false,
+    "destructiveHint": false,
+    "openWorldHint": false
+  }
+}

{bantamkit-0.36.0 → bantamkit-0.37.0b2}/_assets/tools/memory_recall.json

@@ -1,16 +1,14 @@
 {
   "name": "memory_recall",
   "title": "Recall memories",
-  "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.",
+  "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. Pass file instead of query to see the memories linked to a file.",
   "surfaces": [
     "agent",
     "mcp"
   ],
   "parameters": {
     "type": "object",
-    "required": [
-      "query"
-    ],
+    "required": [],
     "properties": {
       "query": {
         "type": "string",
@@ -19,6 +17,15 @@
       "k": {
         "type": "integer",
         "description": "Facts wanted, clamped to 1..5. Raised to the store default of 3 when smaller; never lowered below it."
+      },
+      "include_archived": {
+        "type": "boolean",
+        "default": false,
+        "description": "Also search facts compaction moved to archive/. Archived matches come after the live ones, tagged [archived]."
+      },
+      "file": {
+        "type": "string",
+        "description": "A tracked file, or the shortest unique suffix of one (store.ts, memory/store.ts). Returns the facts linked to it and when it was last touched; query is then ignored."
       }
     },
     "additionalProperties": false

{bantamkit-0.36.0 → bantamkit-0.37.0b2}/_assets/tools/memory_save.json

@@ -43,6 +43,20 @@
           "type": "string"
         },
         "description": "names of related memories"
+      },
+      "keywords": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "Words the user will type when they need this fact, in the user's own language as well as English (e.g. Thai and English terms)"
+      },
+      "queries": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "The prompts a user would type when this fact is what they need: three in the user's language and three in English, at most 8, each at most 200 characters"
       }
     },
     "additionalProperties": false

{bantamkit-0.36.0 → bantamkit-0.37.0b2}/_assets/tools/shiftwork_status.json

@@ -10,6 +10,10 @@
       "checkpoint": {
         "title": "Checkpoint",
         "type": "string"
+      },
+      "search": {
+        "type": "string",
+        "description": "Also search jobs Retention archived under this checkpoint's .shiftwork/archive/: every line holding all the query's words, as {job, file, line}."
       }
     },
     "required": [

{bantamkit-0.36.0 → bantamkit-0.37.0b2}/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.36.0"
+__version__ = "0.37.0b2"

{bantamkit-0.36.0 → bantamkit-0.37.0b2}/src/bantamkit/eventlog.py

@@ -30,12 +30,13 @@ THREE HARD RULES, each with the failure it prevents:
   byte-compares both runtimes' streams; one stray write breaks the wire suite. Nothing
   in this module touches `sys.stderr` or `sys.stdout`.
 * **Metadata only.** Never a tool argument's value, never a memory body, never a
-  validated output, never a query, never a document row. Nine of the fourteen tools take
+  validated output, never a query, never a document row. Nine of the fifteen tools take
   an unbounded string (counted over `assets/tools/`: a `string` parameter with no `enum`
   or `maxLength`, or an array of such; `bantamkit_read` and `repo_map` were two more until
-  job50 I5 retired them from the roster — and `work_plan` is NOT one of them: its `nodes`
-  is an array of objects, not an array of strings, so the rule does not reach the ids
-  inside it) and among those `skill_audit`'s `root`,
+  job50 I5 retired them from the roster — and `work_plan` and `memory_queries` are NOT
+  among them: `nodes` and `facts` are arrays of objects, not arrays of strings, so the
+  rule does not reach the strings inside them; `memory_queries` records its `result`
+  token only) and among those `skill_audit`'s `root`,
   `token_ledger`'s `root` and `prices` and the four shift-work tools' `checkpoint` are
   absolute paths; each record carries counts and tokens from a closed set, never the
   path, never a part name, never a skill id, never a mapped file, never a session id,
@@ -72,6 +73,7 @@ from pathlib import Path
 from typing import Any
 
 from bantamkit.memory.store import bantamkit_dir_for, ensure_bantamkit_gitignore
+from bantamkit.storage.logsegment import LogSegment
 
 #: Environment switch. Unset or `off`/`0`/`false`/`no`/empty -> disabled. `on`/`1`/
 #: `true`/`yes` -> the default file inside the memory store. Anything else is taken as
@@ -135,15 +137,23 @@ def encode_record(epoch_ms: int, tool: str, outcome: str, detail: dict[str, Any]
     module is non-ASCII today; the setting is what keeps that a fact about the data
     rather than a difference between the runtimes if it ever stops being one.
     """
-    record = {
+    text = json.dumps(
+        _record_object(epoch_ms, tool, outcome, detail), ensure_ascii=False, separators=(",", ":")
+    )
+    return text.encode("utf-8") + b"\n"
+
+
+def _record_object(
+    epoch_ms: int, tool: str, outcome: str, detail: dict[str, Any]
+) -> dict[str, Any]:
+    """The record `encode_record` spells, as the object `LogSegment.append` writes."""
+    return {
         "v": SCHEMA_VERSION,
         "ts": format_timestamp(epoch_ms),
         "tool": tool,
         "outcome": outcome,
         "detail": {key: detail[key] for key in sorted(detail)},
     }
-    text = json.dumps(record, ensure_ascii=False, separators=(",", ":"))
-    return text.encode("utf-8") + b"\n"
 
 
 def default_path(store_root: Path) -> Path:
@@ -266,9 +276,10 @@ class EventLog:
         """
         if self.path is None:
             return
-        payload = encode_record(self._clock(), tool, outcome, detail or {})
+        obj = _record_object(self._clock(), tool, outcome, detail or {})
+        payload = json.dumps(obj, ensure_ascii=False, separators=(",", ":")).encode("utf-8") + b"\n"
         try:
-            self._append(payload)
+            self._append(obj, payload)
         except OSError:
             self.write_failed = True
             return
@@ -282,8 +293,15 @@ class EventLog:
         """
         self.record(tool, "raised", {"type": type(exc).__name__})
 
-    def _append(self, payload: bytes) -> None:
-        """Rotate if this record would cross the cap, then append in BINARY mode.
+    def _append(self, obj: dict[str, Any], payload: bytes) -> None:
+        """Rotate if this record would cross the cap, then append through `LogSegment`.
+
+        #204 (J69-4): the line goes through `storage.LogSegment.append` (the shared O_EXCL
+        lock, a newline before a cut last line, the same bytes `encode_record` spells). THE
+        ROTATION RULE BELOW IS NOT `LogSegment.rotate`'s, on purpose: this log keeps exactly
+        one plain `<path>.1` that `--statusline` and `--mcp-report` read in both runtimes, and
+        a 2 MiB ceiling with no retention job behind it; docs/eventlog.md says one rotation
+        rule cannot be right for both this log and the hook log.
 
         Binary, not text: a text-mode write translates `\\n` to `os.linesep`, which is
         `\\r\\n` on Windows, and a Node reader byte-comparing the file would see a
@@ -332,5 +350,5 @@ class EventLog:
             size = 0
         if size and size + len(payload) > self.cap_bytes:
             os.replace(self.path, self.path.with_name(self.path.name + ".1"))
-        with open(self.path, "ab") as handle:
-            handle.write(payload)
+        if not LogSegment(self.path).append(obj):
+            raise OSError("the record could not be appended")  # caught by `record`