bantamkit 0.36.2__tar.gz → 0.37.0__tar.gz

{bantamkit-0.36.2 → bantamkit-0.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.5
+Metadata-Version: 2.4
 Name: bantamkit
-Version: 0.36.2
+Version: 0.37.0
 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
@@ -74,13 +74,12 @@ Then restart the host (in Claude Code, open a new session) and ask the agent to
 - **Offline after one install.** `--install` records the venv's console script by absolute path,
   so no launch needs the network or your shell's PATH.
 - **Claude Code hooks, if you want them.** `--install-hooks` puts the memory index in front of
-  each new session, surfaces matching facts on each prompt, mirrors each fact Claude Code writes
-  into its own auto-memory into the project store (one way, new writes only), and nudges a save at
-  the end of a long session that saved nothing
+  each new session, surfaces matching facts on each prompt, and nudges a save at the end of a
+  long session that saved nothing
   ([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.
@@ -103,10 +102,10 @@ 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, three prompts, 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, list, candidates, merge |
+| [The operator CLI: `python -m bantamkit.memory`](#-the-operator-cli-python--m-bantamkitmemory) | status, lint, compact, archived, archive, restore |
 | [Where the Python and Node servers differ](#-where-the-python-and-node-servers-differ) | One store; pdf/.doc/.rtf, CLI name, `build_id`, YAML only PyYAML reads |
 | [Module API](#-module-api) | `import bantamkit`: the library half, measured from the wheel |
 | [Development](#-development) | Clone, test, lint, conformance |
@@ -145,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.2" -d wheels
+python -m pip download "bantamkit[mcp]==0.37.0" -d wheels
 python -m venv <env>
-<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.36.2"
+<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.37.0"
 <env>/bin/bantamkit-mcp --install cursor
 ```
 
@@ -279,6 +278,7 @@ Flags go in the entry's `args`; environment variables in its `env` block (or
 | `--k K` | Default recall budget | `3` | `"--k", "5"` |
 | `--index-budget BYTES` | Memory index byte budget | `24000` | `"--index-budget", "32000"` |
 | `BANTAMKIT_EVENT_LOG` | Logs tool outcomes as JSONL | off; `on` → `<store>/events/mcp.jsonl`; other values are a path | `"env": {"BANTAMKIT_EVENT_LOG": "on"}` |
+| `BANTAMKIT_SKILL_AUTO` | Skills from experience (#206): lets the daily run install a skill it mined, make low-risk edits to installed skills and promote a much-used one to a native link on its own. Off, the same work waits for you as proposals in the `skill_propose` prompt | **off** in 0.37.0; `on` (or `1`/`true`/`yes`) opts in | `"env": {"BANTAMKIT_SKILL_AUTO": "on"}` |
 | `BANTAMKIT_ASSETS` | Your own asset pack (skills, rubrics, schemas) | the pack inside the package | `"env": {"BANTAMKIT_ASSETS": "/abs/my-assets"}` |
 | `BANTAMKIT_HOST_LOG_ROOT` | Where `--mcp-report` finds the host's MCP logs | macOS `~/Library/Caches/claude-cli-nodejs`; elsewhere unset | `BANTAMKIT_HOST_LOG_ROOT=/abs/logs bantamkit-mcp --mcp-report` |
 | `BANTAMKIT_PRICES` | Price table for the token ledger | `pricing/default.json` in the asset pack | `"env": {"BANTAMKIT_PRICES": "/abs/prices.json"}` |
@@ -328,7 +328,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, three prompts (`bantamkit_status`, `skill_audit` and `skill_propose`) and two resource templates
 (`bantamkit://skills/{name}`, `bantamkit://rubrics/{name}`):
 
 | Tool | What it does |
@@ -337,6 +337,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 |
@@ -374,13 +375,9 @@ python -m bantamkit.memory compact    # archive the stalest facts
 python -m bantamkit.memory archived   # list what compaction has moved out
 python -m bantamkit.memory archive <name>
 python -m bantamkit.memory restore <name>
-python -m bantamkit.memory list [--type T] [--outcome error|success] [--status active|done]
-python -m bantamkit.memory candidates [--older-than DAYS] [--apply]
-python -m bantamkit.memory merge --names A B --name NEW --type T --description D --body TEXT [--apply]
 ```
 
-`archive` moves a fact out without deleting it; `restore` brings it back by name. `candidates`
-and `merge` are dry runs unless `--apply` is given.
+`archive` moves a fact out without deleting it; `restore` brings it back by name.
 Full reference: [docs/memory.md → The operator CLI](https://github.com/Ink01101011/bantamkit/blob/main/docs/memory.md#the-operator-cli).
 
 ## 🔀 Where the Python and Node servers differ
@@ -438,7 +435,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.2 → bantamkit-0.37.0}/README.md

@@ -43,13 +43,12 @@ Then restart the host (in Claude Code, open a new session) and ask the agent to
 - **Offline after one install.** `--install` records the venv's console script by absolute path,
   so no launch needs the network or your shell's PATH.
 - **Claude Code hooks, if you want them.** `--install-hooks` puts the memory index in front of
-  each new session, surfaces matching facts on each prompt, mirrors each fact Claude Code writes
-  into its own auto-memory into the project store (one way, new writes only), and nudges a save at
-  the end of a long session that saved nothing
+  each new session, surfaces matching facts on each prompt, and nudges a save at the end of a
+  long session that saved nothing
   ([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.
@@ -72,10 +71,10 @@ 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, three prompts, 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, list, candidates, merge |
+| [The operator CLI: `python -m bantamkit.memory`](#-the-operator-cli-python--m-bantamkitmemory) | status, lint, compact, archived, archive, restore |
 | [Where the Python and Node servers differ](#-where-the-python-and-node-servers-differ) | One store; pdf/.doc/.rtf, CLI name, `build_id`, YAML only PyYAML reads |
 | [Module API](#-module-api) | `import bantamkit`: the library half, measured from the wheel |
 | [Development](#-development) | Clone, test, lint, conformance |
@@ -114,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.2" -d wheels
+python -m pip download "bantamkit[mcp]==0.37.0" -d wheels
 python -m venv <env>
-<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.36.2"
+<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.37.0"
 <env>/bin/bantamkit-mcp --install cursor
 ```
 
@@ -248,6 +247,7 @@ Flags go in the entry's `args`; environment variables in its `env` block (or
 | `--k K` | Default recall budget | `3` | `"--k", "5"` |
 | `--index-budget BYTES` | Memory index byte budget | `24000` | `"--index-budget", "32000"` |
 | `BANTAMKIT_EVENT_LOG` | Logs tool outcomes as JSONL | off; `on` → `<store>/events/mcp.jsonl`; other values are a path | `"env": {"BANTAMKIT_EVENT_LOG": "on"}` |
+| `BANTAMKIT_SKILL_AUTO` | Skills from experience (#206): lets the daily run install a skill it mined, make low-risk edits to installed skills and promote a much-used one to a native link on its own. Off, the same work waits for you as proposals in the `skill_propose` prompt | **off** in 0.37.0; `on` (or `1`/`true`/`yes`) opts in | `"env": {"BANTAMKIT_SKILL_AUTO": "on"}` |
 | `BANTAMKIT_ASSETS` | Your own asset pack (skills, rubrics, schemas) | the pack inside the package | `"env": {"BANTAMKIT_ASSETS": "/abs/my-assets"}` |
 | `BANTAMKIT_HOST_LOG_ROOT` | Where `--mcp-report` finds the host's MCP logs | macOS `~/Library/Caches/claude-cli-nodejs`; elsewhere unset | `BANTAMKIT_HOST_LOG_ROOT=/abs/logs bantamkit-mcp --mcp-report` |
 | `BANTAMKIT_PRICES` | Price table for the token ledger | `pricing/default.json` in the asset pack | `"env": {"BANTAMKIT_PRICES": "/abs/prices.json"}` |
@@ -297,7 +297,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, three prompts (`bantamkit_status`, `skill_audit` and `skill_propose`) and two resource templates
 (`bantamkit://skills/{name}`, `bantamkit://rubrics/{name}`):
 
 | Tool | What it does |
@@ -306,6 +306,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 |
@@ -343,13 +344,9 @@ python -m bantamkit.memory compact    # archive the stalest facts
 python -m bantamkit.memory archived   # list what compaction has moved out
 python -m bantamkit.memory archive <name>
 python -m bantamkit.memory restore <name>
-python -m bantamkit.memory list [--type T] [--outcome error|success] [--status active|done]
-python -m bantamkit.memory candidates [--older-than DAYS] [--apply]
-python -m bantamkit.memory merge --names A B --name NEW --type T --description D --body TEXT [--apply]
 ```
 
-`archive` moves a fact out without deleting it; `restore` brings it back by name. `candidates`
-and `merge` are dry runs unless `--apply` is given.
+`archive` moves a fact out without deleting it; `restore` brings it back by name.
 Full reference: [docs/memory.md → The operator CLI](https://github.com/Ink01101011/bantamkit/blob/main/docs/memory.md#the-operator-cli).
 
 ## 🔀 Where the Python and Node servers differ
@@ -407,7 +404,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.0/_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.2 → bantamkit-0.37.0}/_assets/skills/memory.md

@@ -23,6 +23,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.36.2 → bantamkit-0.37.0}/_assets/tools/memory_compact.json

@@ -1,7 +1,7 @@
 {
   "name": "memory_compact",
   "title": "Compact the memory store",
-  "description": "Free room in persistent memory when `memory_save` was refused for budget. Archives the stalest facts of the writable project store until a fact as large as the biggest one kept will fit, and returns what moved — every archived name with its type and description. Nothing is deleted: archived facts leave the index but stay on disk under archive/, and bringing one back is an operator action rather than a tool — `bantamkit-memory restore <name>` (Node) or `python -m bantamkit.memory restore <name>` (Python) on the store; no tool deletes a fact. Read-only grants and the profile layer are never touched. Call it after a budget refusal, then retry the save; calling it under budget archives nothing and says so. It is not the pass for two copies of one name across layers — that is memory_dream.",
+  "description": "Free room in persistent memory when `memory_save` was refused for budget. Archives the stalest facts of the writable project store until a fact as large as the biggest one kept will fit, and returns what moved — every archived name with its type and description. Nothing is deleted: archived facts leave the index but stay on disk under archive/, memory_recall with `include_archived` still finds them, and bringing one back is an operator action rather than a tool — `bantamkit-memory restore <name>` (Node) or `python -m bantamkit.memory restore <name>` (Python) on the store; no tool deletes a fact. Read-only grants and the profile layer are never touched. Call it after a budget refusal, then retry the save; calling it under budget archives nothing and says so. It is not the pass for two copies of one name across layers — that is memory_dream.",
   "surfaces": [
     "agent",
     "mcp"

bantamkit-0.37.0/_assets/tools/memory_queries.json

@@ -0,0 +1,92 @@
+{
+  "name": "memory_queries",
+  "title": "Likely-prompt queries for saved facts",
+  "description": "Write, or list the facts that still lack, the likely-prompt queries recall matches a user's prompt against — for each fact, the prompts a user would type when that fact is what they need. Call it with {} at the end of a session that saved facts, or when bantamkit_status reports `queries: n of m facts` with n below m: it answers up to 10 facts with no queries yet (layer, name, description, a body excerpt), the writing instructions, and `remaining`. Then call it with {\"facts\": [{name, layer?, queries}]} to store what you wrote. Every item is checked before anything is written and the first bad one refuses the whole call — an unknown name or layer, more than 8 queries, one over 200 characters; `queries: []` removes a fact's entry. No fact file changes: queries live in a per-layer sidecar under ~/.bantamkit/queries/, keyed to the fact's content, so a fact edited later is listed as missing again. memory_save takes `queries` directly for a fact you are saving now; this tool is for facts already on disk.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "facts": {
+        "anyOf": [
+          {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "description": "The fact's exact name (its slug)."
+                },
+                "layer": {
+                  "type": "string",
+                  "description": "project, profile, extra:<name> or native; optional: the first layer holding the name"
+                },
+                "queries": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Up to 8 prompts, each at most 200 characters, in the user's language and in English; [] removes the fact's entry."
+                }
+              },
+              "required": [
+                "name",
+                "queries"
+              ]
+            }
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Omit to list the facts missing queries"
+      }
+    },
+    "title": "memory_queriesArguments",
+    "additionalProperties": false
+  },
+  "output_schema": {
+    "type": "object",
+    "properties": {
+      "result": {
+        "type": "string",
+        "description": "`missing` for the list call, `written` for the store call, `error` with `reason` when refused."
+      },
+      "facts": {
+        "type": "array",
+        "items": {
+          "type": "object"
+        },
+        "description": "With `missing`: up to 10 {layer, name, description, body} still without queries."
+      },
+      "remaining": {
+        "type": "integer",
+        "description": "How many facts across the readable layers still have no queries after this call."
+      },
+      "instructions": {
+        "type": "string",
+        "description": "With `missing`: how to write good queries."
+      },
+      "written": {
+        "type": "integer",
+        "description": "With `written`: how many items were stored."
+      },
+      "reason": {
+        "type": "string",
+        "description": "With result `error`: one sentence saying why the call was refused."
+      }
+    },
+    "required": [
+      "result"
+    ],
+    "additionalProperties": true,
+    "title": "memory_queriesDictOutput"
+  },
+  "annotations": {
+    "readOnlyHint": false,
+    "destructiveHint": false,
+    "openWorldHint": false
+  }
+}

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

@@ -1,16 +1,14 @@
 {
   "name": "memory_recall",
   "title": "Recall memories",
-  "description": "Search persistent memory for facts a past session saved. Call it BEFORE starting a task that resembles past work, and when the user refers to something decided earlier; use memory_save to add a fact, and memory_compact or memory_dream only to tidy the store — this tool never changes what a fact says. Reads every layer in order — the project store, any read-only grants in .bantamkit/config.yaml, then the machine-wide profile — and 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. Why it is not read-only: every hit is appended to the usage ledger (~/.bantamkit/usage/<store-id>.jsonl) as a recall event — the staleness order memory_compact archives by — and a project fact file still in the 0.35.x format is rewritten once into the current one; both are best-effort and never fail a recall. A fact file that cannot be read is named in the reply, never silently skipped. Pass outcome: error to see only recorded failures.",
+  "description": "Search persistent memory for facts a past session saved. Call it BEFORE starting a task that resembles past work, and when the user refers to something decided earlier; use memory_save to add a fact, and memory_compact or memory_dream only to tidy the store — this tool never changes what a fact says. Reads every layer in order — the project store, any read-only grants in .bantamkit/config.yaml, then the machine-wide profile — and 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 facts linked to a file. Why it is not read-only: every hit is appended to the usage ledger (~/.bantamkit/usage/<store-id>.jsonl) as a recall event — the staleness order memory_compact archives by — and a project fact file still in the 0.35.x format is rewritten once into the current one; both are best-effort and never fail a recall. A fact file that cannot be read is named in the reply, never silently skipped. Pass outcome: error to see only recorded failures.",
   "surfaces": [
     "agent",
     "mcp"
   ],
   "parameters": {
     "type": "object",
-    "required": [
-      "query"
-    ],
+    "required": [],
     "properties": {
       "query": {
         "type": "string",
@@ -20,6 +18,15 @@
         "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."
+      },
       "outcome": {
         "type": "string",
         "enum": [

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

@@ -45,6 +45,20 @@
         },
         "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"
+      },
       "outcome": {
         "type": "string",
         "enum": [

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

@@ -1,7 +1,7 @@
 {
   "name": "shiftwork_status",
   "title": "Shift work: status",
-  "description": "Shift-work status: where ONE checkpoint file stands — units counted by status, the unit plan.cursor points at, how many handoff.open_questions are waiting, and the last history entry. Call it first when resuming a job or answering 'where is job X'; it is the cheap read before any clock-in. It does not say WHICH units may run now — that is shiftwork_plan, the dependency batches — and it says nothing about the server itself, which is bantamkit_status. Every fact is read from the checkpoint on this call, nothing is cached, and a checkpoint that is missing, not valid JSON or failing the checkpoint schema answers {\"result\": \"error\", \"reason\": \"<sentence>\"} instead of a partial summary — the same refusals shiftwork_plan and shiftwork_clock_in give for that file. Opens only the checkpoint; writes nothing, not even the log shiftwork_clock_in appends to.",
+  "description": "Shift-work status: where ONE checkpoint file stands — units counted by status, the unit plan.cursor points at, how many handoff.open_questions are waiting, and the last history entry. Call it first when resuming a job or answering 'where is job X'; it is the cheap read before any clock-in. It does not say WHICH units may run now — that is shiftwork_plan, the dependency batches — and it says nothing about the server itself, which is bantamkit_status. Every fact is read from the checkpoint on this call, nothing is cached, and a checkpoint that is missing, not valid JSON or failing the checkpoint schema answers {\"result\": \"error\", \"reason\": \"<sentence>\"} instead of a partial summary — the same refusals shiftwork_plan and shiftwork_clock_in give for that file. With `search`, it also returns the lines of jobs Retention archived under the checkpoint's .shiftwork/archive/ that hold every word of the query. Opens only the checkpoint (and that archive directory when `search` is given); writes nothing, not even the log shiftwork_clock_in appends to.",
   "surfaces": [
     "mcp"
   ],
@@ -11,6 +11,10 @@
         "title": "Checkpoint",
         "type": "string",
         "description": "Path to the shift-work checkpoint JSON file (by convention .shiftwork/checkpoint.json in the repo the job works on), absolute or relative to the server's working directory. The same file shiftwork_plan, shiftwork_clock_in and shiftwork_clock_out take; it must validate against assets/schemas/shiftwork-checkpoint.json."
+      },
+      "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": [
@@ -53,6 +57,27 @@
         ],
         "description": "The newest entry of the 5-entry history ring ({unit, outcome, notes?, ...}), or null when the ring is empty."
       },
+      "search": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "job": {
+              "type": "string",
+              "description": "The archived job the line belongs to."
+            },
+            "file": {
+              "type": "string",
+              "description": "Path of the archived file, relative to the job."
+            },
+            "line": {
+              "type": "integer",
+              "description": "1-based line number within that file."
+            }
+          }
+        },
+        "description": "Only when `search` was given: every archived line holding all its words, as {job, file, line}."
+      },
       "reason": {
         "type": "string",
         "description": "With result `error`: one sentence saying why the call was refused."

{bantamkit-0.36.2 → bantamkit-0.37.0}/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.2"
+__version__ = "0.37.0"

{bantamkit-0.36.2 → bantamkit-0.37.0}/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`