grepmax 0.21.0 → 0.21.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "grepmax",
       "source": "./plugins/grepmax",
       "description": "Semantic code search for Claude Code. Automatically indexes your project and provides intelligent search capabilities.",
-      "version": "0.21.0",
+      "version": "0.21.1",
       "author": {
         "name": "Robert Owens",
         "email": "robowens@me.com"

package/README.md

@@ -289,6 +289,45 @@ All data lives in `~/.gmax/`:
 }
 ```
 
+### Model Tier
+
+gmax embeds with IBM's Granite r2 code-embedding models. Two tiers are available:
+
+| Tier | Model | Dim | Params |
+| --- | --- | --- | --- |
+| `small` (default) | `granite-embedding-small-english-r2` | 384 | 47M |
+| `standard` | `granite-embedding-english-r2` | 768 | 149M |
+
+**384d is the default — and benchmarking says keep it.** On gmax's own 97-case
+retrieval eval (`pnpm bench:recall`), the larger 768d model scored **~10 points
+*worse* on Recall@10** than 384d, consistently on both the MLX GPU and ONNX CPU
+embedding paths, with and without ColBERT rerank:
+
+| Model | Recall@10 | MRR@10 |
+| --- | --- | --- |
+| `small` / 384d | **0.72** | **0.51** |
+| `standard` / 768d | 0.62 | 0.44 |
+
+<sub>gmax repo, 97 cases, MLX GPU, rerank off (the shipped default). The CPU/q4
+path and the rerank-on path show the same ~0.10 Recall@10 gap, so it isn't a
+quantization artifact — the bigger model just retrieves worse on code here.</sub>
+
+Bigger isn't better for this workload: 768d roughly doubles embedding compute,
+worker RAM, and dense-vector storage while *lowering* recall on code search.
+Unless you have a measured reason to switch (e.g. a recall complaint on a very
+large repo — benchmark it first), stay on 384d.
+
+To change tiers:
+
+```bash
+gmax config --model-tier standard   # a dim change needs a full re-embed
+gmax repair --rebuild               # drops the shared table, re-embeds every project at the new dim
+```
+
+A vector-dimension change can't be applied by a per-project `gmax index --reset`
+— the shared `chunks` table is fixed-width, so `gmax repair --rebuild` is the
+sanctioned path.
+
 ### Ignoring Files
 
 gmax respects `.gitignore` and `.gmaxignore`:
@@ -339,6 +378,8 @@ GMAX_EVAL_RERANK=1 pnpm bench:oss   # toggle ColBERT rerank
 
 The OSS bench requires the fixture repos to be indexed first — see [`docs/known-limitations.md`](docs/known-limitations.md) for the most recent rerank-on-vs-off comparison across 4 datasets / 131 cases.
 
+`pnpm bench:recall` also drives the model-tier comparison behind the 384d default — see [Model Tier](#model-tier) for why the larger 768d model is *not* the default.
+
 ## Attribution
 
 grepmax is built upon the foundation of [mgrep](https://github.com/mixedbread-ai/mgrep) by MixedBread. See the [NOTICE](NOTICE) file for details.

package/dist/commands/config.js

@@ -84,6 +84,7 @@ Examples:
     const newMode = (_c = options.embedMode) !== null && _c !== void 0 ? _c : globalConfig.embedMode;
     const tier = (_d = config_1.MODEL_TIERS[newTier]) !== null && _d !== void 0 ? _d : config_1.MODEL_TIERS.small;
     const tierChanged = newTier !== globalConfig.modelTier;
+    const dimChanged = tier.vectorDim !== globalConfig.vectorDim;
     (0, index_config_1.writeGlobalConfig)({
         modelTier: newTier,
         vectorDim: tier.vectorDim,
@@ -98,7 +99,12 @@ Examples:
     });
     console.log(`Updated: embed-mode=${newMode}, model-tier=${newTier} (${tier.vectorDim}d)`);
     if (tierChanged) {
-        console.log("⚠️  Model tier changed — run `gmax index --reset` to rebuild with new dimensions.");
+        // A dimension change can't be fixed by a per-project `gmax index --reset`:
+        // the shared `chunks` table is fixed-width, so it must be dropped and
+        // rebuilt. A same-dim model swap (future tiers) can use a per-project reset.
+        console.log(dimChanged
+            ? `⚠️  Model tier changed (${globalConfig.vectorDim}d → ${tier.vectorDim}d). The shared vector table is fixed-width — run \`${config_1.REBUILD_COMMAND}\` to drop it and re-embed every project at the new dim.`
+            : "⚠️  Model tier changed — run `gmax index --reset` per project to re-embed with the new model.");
     }
     yield (0, exit_1.gracefulExit)();
 }));

package/dist/lib/utils/stale-hint.js

@@ -104,7 +104,9 @@ function maybeWarnStaleEmbedding(projectRoot, opts) {
             `current_dim=${gap.toDim}`,
             `dim_changed=${gap.dimChanged}`,
             `severity=${gap.severity}`,
-            "fix=gmax index --reset",
+            // A dim change needs the global rebuild (shared table is fixed-width); a
+            // same-dim model swap can use a per-project reset.
+            `fix=${gap.dimChanged ? config_1.REBUILD_COMMAND : "gmax index --reset"}`,
         ].join("\t");
         process.stderr.write(`${fields}\n`);
         return;
@@ -113,7 +115,10 @@ function maybeWarnStaleEmbedding(projectRoot, opts) {
     const detail = gap.dimChanged
         ? `vector dim ${gap.fromDim}→${gap.toDim} (incompatible — scores invalid until re-embed)`
         : `model '${gap.fromModel}'→'${gap.toModel}' (same dim; results mix models until re-embed)`;
-    process.stderr.write(`${label}  gmax: '${name}' indexed with embedding ${detail}. Run 'gmax index --reset'. (silence: GMAX_NO_STALE_HINT=1)\n`);
+    const fix = gap.dimChanged
+        ? `Run '${config_1.REBUILD_COMMAND}'`
+        : "Run 'gmax index --reset'";
+    process.stderr.write(`${label}  gmax: '${name}' indexed with embedding ${detail}. ${fix}. (silence: GMAX_NO_STALE_HINT=1)\n`);
 }
 /**
  * Cross-project guard: when a `--all-projects` / `--projects` search spans

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.21.0",
+  "version": "0.21.1",
   "author": "Robert Owens <78518764+reowens@users.noreply.github.com>",
   "homepage": "https://github.com/reowens/grepmax",
   "bugs": {

package/plugins/grepmax/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.21.0",
+  "version": "0.21.1",
   "description": "Semantic code search for Claude Code. Automatically indexes your project and provides intelligent search capabilities.",
   "author": {
     "name": "Robert Owens",