@fonlan/dsh-gitmemo 0.4.1 → 0.5.0

package/README.md

@@ -16,7 +16,7 @@ dependency, and no manual memory commands are ever needed.
 - **Git-only** — no runtime dependency beyond the `git` CLI
 - **Token-efficient** — reuses prior conclusions via `mem_search`; subagents carry neither the workflow rules nor the tool schemas
 - **Immutable entries** — every write creates a new file; corrections use `mem_replace` (one commit deletes the old file and adds the new one), withdrawal uses `mem_delete`
-- **Knowledge freshness** — `mem_replace` is not just for user corrections: work that overrules a stored conclusion actively replaces it; `mem_search` scores hits as distinct matched keywords + a mild recency bonus (≤ +0.5, linearly decaying to 0 over ~180 days), so conflicting stale conclusions lose to their replacements
+- **Knowledge freshness** — `mem_replace` is not just for user corrections: work that overrules a stored conclusion actively replaces it; `mem_search` adds a mild recency bonus (≤ +0.5, linearly decaying to 0 over ~180 days) on top of the match score, so conflicting stale conclusions lose to their replacements
 - **Topic pages (MOC)** — a `kind: "topic"` entry aggregates a topic's "current truth": the summary states the currently-valid conclusions and the page evolves via `mem_replace` (kind is inherited), not per-task rewrites
 - **Wiki links between entries** — content references other entries as `[[<commit-hash>]]`; `mem_read` with `expand: true` resolves those links one hop and automatically follows the `GitMemo-Replaces` chain to a replaced target's active version (dangling links come back with an error)
 - **Structured search** — commit messages carry `GitMemo-*` trailers (keywords, digest, search-text projections); search is `git log --grep --fixed-strings` over commit messages only — entry bodies are never scanned
@@ -28,7 +28,7 @@ dependency, and no manual memory commands are ever needed.
 
 | Piece | Description |
 | --- | --- |
-| `mem_search` | Search memories: `keywords` (array of 1–12, 中英文同义词), `skip` + `snapshot` (stable pagination). Returns up to 20 scored hits with `summary` / `keywords` / `kind` / `matched_keywords` (score = matched keywords + recency bonus) |
+| `mem_search` | Search memories: `keywords` (array of 1–15, 中英文同义词), `skip` + `snapshot` (stable pagination). Returns up to 20 scored hits with `summary` / `keywords` / `kind` / `matched_keywords`. Score = the summed rarity of the matched keywords within the page (default) or the matched count (`searchScoring: count`), plus a recency bonus |
 | `mem_read` | Read one memory entry by create/replace commit hash (full markdown; historical hashes stay readable); returns `kind`; optional `expand: true` resolves `[[hash]]` links one hop |
 | `mem_write` | Store a task outcome: `title` + `summary` + `keywords` (2–12) + `content` (engine generates front matter), optional `kind` (`"task"` default / `"topic"` aggregated page), `related_branches` / `related_paths`. One ADD commit per immutable file |
 | `mem_delete` | Withdraw an obsolete conclusion (requires `commit_hash` + `reason`) |
@@ -63,6 +63,7 @@ The bundle patch ships with sensible defaults; override them in the profile's
 - id: dsh-gitmemo
   config:
     searchLimit: 20        # max hits per mem_search call (page size)
+    searchScoring: weighted  # weighted (default) | count — see "Search scoring"
     lockTimeoutMs: 30000   # cross-process lock wait timeout
     projectRoot: null      # optional explicit project root (defaults to the session cwd)
     systemOne:             # optional System-one recall gate, see below
@@ -70,15 +71,65 @@ The bundle patch ships with sensible defaults; override them in the profile's
       endpoint: https://api.typesafe.ai/v1/systemone
       model: jev-latest
       mode: noul           # noul | score
-      threshold: 0.5       # noul mode: keep a candidate when P(yes) >= this
+      policy: rerank       # rerank (default) | filter — see "System-one Recall Gate"
+      threshold: 0.5       # filter mode: drop a candidate when P(yes) < this
+      maxDropFraction: 0.25  # filter mode: never drop more than this share of a page
 ```
 
+## Search Scoring
+
+`mem_search` matches entries with a fixed-string OR grep over the commit-message
+projections — the title, the summary, and the entry's keywords (bodies are never
+scanned). Two modes decide the *order* of the matched entries; both match exactly
+the same entries:
+
+| `searchScoring` | Score | Trade-off |
+| --- | --- | --- |
+| `weighted` (default) | `Σ` rarity of each matched keyword within the recall page, plus the recency bonus | A distinctive match outranks several common ones. One match can beat two, which the `count` mode never allows. |
+| `count` | number of matched keywords, plus the recency bonus | The previous default arithmetic, kept for exact backwards compatibility. |
+
+Rarity is the BM25-style weight `log(1 + (n − df + 0.5) / (df + 0.5))` over the
+candidate page (`n` candidates, `df` matching the keyword), so it costs no extra
+git call. The recency bonus stays ≤ +0.5, so it only reorders near-equal scores.
+
+**Why this is the default.** On LongMemEval `_S` (500 instances, session
+granularity) the engine reached `recall_all@50 = 0.998` while `ndcg_any@5` was
+only 0.686: evidence was essentially always reachable but ranked badly, because
+a plain match count cannot distinguish a rare keyword from a ubiquitous one.
+Weighting the same matches lifted `recall_all@5` 0.738 → 0.755 and `ndcg@5`
+0.687 → 0.700 on identical ingested data, and `recall_all@50` was unchanged
+(0.998) — matching is untouched by construction.
+`evals/longmemeval/README.md` has the full run and the ablation across scoring,
+granularity and ingestion policy.
+
 ## System-one Recall Gate (optional)
 
 A `mem_search` page can be handed to a **System-one model** (TypeSafe Jev by
 default) for one fast judgement, so memories that are **completely unrelated**
-to the current task are dropped before they are injected. Only genuinely
-reusable entries survive.
+to the current task do not get injected.
+
+**How the judgement is used — `policy`:**
+
+| `policy` | Effect | Context | Measured accuracy |
+| --- | --- | --- | --- |
+| `rerank` (default) | keeps every judged memory and orders the page by the judge's value | unchanged | **0.8020** |
+| `filter` | drops memories below `threshold`, bounded by `maxDropFraction` | **−80 %** | **0.3800** |
+
+Those two figures are LongMemEval `_S` LLM-as-Judge over all 500 questions, with
+the same judge, the same ingested memories and the same per-candidate values —
+only the use made of them differs. The reason is in the judge's own signal: its
+AUC separating evidence from non-evidence is ~0.71–0.75, so **no threshold is
+safe**, while the same value is a perfectly good ordering feature. A hard drop on
+a 0.75-AUC signal took 343 gold memories out of the prompt across 254 of 500
+instances. Full study: `evals/longmemeval/README.md`.
+
+`filter` remains available because dropping memories is the point of a recall
+gate when context budget is the binding constraint — and it is now **bounded**:
+`maxDropFraction` (default 0.25) restores the best-scoring rejects whenever a
+threshold would drop more than that share of a page. An offline sweep held
+`recall_all@5` at 0.8875 with a 20 % cap against 0.6875 uncapped. A memory
+dropped is gone; a memory kept only costs context, so the errors are not
+symmetric and the bound is deliberately tight.
 
 - **Inert by default.** The gate runs only when a usable credential is
   configured (`apiKey`, the credential named by `apiKeyEnv`, or the environment
@@ -87,9 +138,15 @@ reusable entries survive.
 - **Fails open.** A timeout, a non-2xx response, an unparseable body — any
   failure keeps every candidate and reports why in `gated.degraded` +
   `gated.reason`. **A broken endpoint can never hide a memory.**
-- **Never empties a page.** If the model rejects the whole page, at least
-  `minKeep` (default 1) best-ranked candidates are retained, so "the gate removed
-  it" and "there was nothing there" stay distinguishable. The tool's `gated` line
+- **Never empties a page.** Under `filter`, at least `minKeep` (default 1)
+  best-ranked candidates are retained when the whole page is rejected, and
+  `maxDropFraction` (default 0.25) caps how much of a judged page may be removed
+  at all — so "the gate removed it" and "there was nothing there" stay
+  distinguishable, and a mis-calibrated threshold cannot gut a page. Under
+  `rerank` nothing is removed by construction.
+- **Ordering is reported either way.** The decision carries `ordered` (candidate
+  hashes best-first by the judge's value) and each verdict's value, so a caller
+  can log or re-rank from the same judgement without a second call. The tool's `gated` line
   says so out loud — such a page carries a `NOTE(no candidate scored above the
   threshold…)` marker, so a retained floor is never mistaken for a candidate that
   genuinely passed. `judged=` counts only the candidates actually sent to the
@@ -114,6 +171,8 @@ reusable entries survive.
 | `mode` | `noul` | `noul` (yes/no probability) or `score` (graded levels) |
 | `threshold` | `0.5` | `noul` mode: keep when P(yes) ≥ this |
 | `scoreMin` | `2` | `score` mode cutoff. Note Jev's `score` is `Σ(level_index × probability)`, ranging 0…levels−1 (5 levels → 0…4), **not 0–1** |
+| `policy` | `rerank` | `rerank` keeps every judged memory and orders the page by the judge's value; `filter` drops below `threshold` |
+| `maxDropFraction` | `0.25` | `filter` only: never drop more than this share of the judged page, lowest-scoring first |
 | `minKeep` | `1` | Candidates retained when the whole page is rejected |
 | `maxCandidates` | `20` | Candidates judged per request; the remainder is **never judged and never dropped** |
 | `maxTaskChars` | `2000` | Task-text truncation length |
@@ -134,23 +193,6 @@ what writes it (the switch alone is a draft). An absent `enabled` reads as on, s
 an unconfigured section shows the gate as enabled — which is what the host
 default does.
 
-### Known trade-offs
-
-- **English-first.** Jev's primary training language is English; CJK works but
-  the vendor documents lower accuracy. The gate's question wording is English;
-  only the candidate text and task text may be Chinese.
-- **Context ceiling.** 64k tokens per request, of which `state` + the longest
-  single question may use 32k. `maxCandidates` and `maxTaskChars` exist to hold
-  that line.
-- **Latency on the critical path.** Recall runs before every repo task, and the
-  gate adds one network round trip (~0.4s observed), so `timeoutMs` defaults to
-  8s and every failure path fails open.
-- **Data egress.** Memory summaries leave the machine. TypeSafe currently offers
-  **no** zero data retention; point `endpoint` at a self-hosted implementation
-  (e.g. MIT-licensed `jeff`) or a local endpoint to avoid egress entirely.
-- **Billing.** Priced per input token ($0.042 per million input tokens, output
-  free) — not per call.
-
 ## Memory Location & Format
 
 The `.mem` repository lives at the **project root** of the calling session's workspace
@@ -182,7 +224,7 @@ git -C .mem show <commit-hash>
 
 ## Agent Workflow (always-on rules, root agents)
 
-1. **Before work — search.** For repo-related tasks, extract 1–12 中英文关键词 → `mem_search`.
+1. **Before work — search.** For repo-related tasks, extract 1–15 中英文关键词 → `mem_search`.
    Pure chat and general Q&A need no search.
 2. **Preselect results.** Based on `title` / `summary` / `keywords` / `score` /
    `matched_keywords`, `mem_read` at most 5 most relevant memories (`kind: "topic"` entries
@@ -215,6 +257,30 @@ npm run build    # tsc → lib/
 npm test         # build + engine/plugin/migration unit tests (node:test)
 ```
 
+## LongMemEval Evaluation
+
+The engine is benchmarked against [LongMemEval](https://github.com/xiaowu0162/LongMemEval) two
+ways, both runnable from this checkout. See [`evals/longmemeval/README.md`](evals/longmemeval/README.md)
+for the retrieval metrics and [`evals/omnimemeval/README.md`](evals/omnimemeval/README.md) for the
+end-to-end QA pipeline.
+
+```bash
+# official retrieval metrics (recall/NDCG, no LLM needed)
+npm run eval:lme:oracle                  # wiring check
+npm run eval:lme:s                       # all 500 instances of the _S split
+
+# end-to-end QA accuracy through OmniMemEval's 6-step pipeline
+npm run eval:omni:setup                  # clone + adapter + venv + env file
+cd .omnimemeval && ./scripts/run_lme_eval.sh --lib gitmemo \
+  --env ~/.dsh-gitmemo-lme/.env.gitmemo --streaming 1
+```
+
+Headline result on `_S` (500/500 instances, session granularity, zero failures): `recall_all@5`
+**0.736** against **0.870** for a plain BM25 over full session text, but `recall_all@50` **0.998** —
+the loss is ranking precision, not coverage. Holding everything else fixed and letting an LLM
+choose what to write raises `recall_all@5` to **0.842**, which is the point of the benchmark:
+for a keyword-grep memory, what you commit to memory dominates the retrieval algorithm.
+
 ## Layout
 
 ```
@@ -227,7 +293,10 @@ dsh-gitmemo/
 │   ├── migrate.ts        # legacy migration (dry-run/apply, backup refs, CAS swap)
 │   └── cli.ts            # `dsh-gitmemo migrate` CLI entry
 ├── lib/                  # built output (committed; used by file:/git installs)
-└── test/mem.test.mjs     # engine + plugin + migration unit tests
+├── test/mem.test.mjs     # engine + plugin + migration unit tests
+└── evals/
+    ├── longmemeval/      # retrieval harness: official recall/NDCG, no LLM required
+    └── omnimemeval/      # gitmemo as an OmniMemEval memory backend (QA accuracy)
 ```
 
 ## License

package/README.zh.md

@@ -15,7 +15,7 @@
 - **仅依赖 Git** —— 除 `git` CLI 外无任何运行时依赖
 - **省 token** —— 通过 `mem_search` 复用既有结论；子代理既不携带工作流规则也不携带工具 schema
 - **条目不可变** —— 每次写入都创建新文件；更正用 `mem_replace`（一个提交同时删除旧文件、新增新文件），作废用 `mem_delete`
-- **知识保鲜** —— `mem_replace` 不只用于用户更正：本次工作覆盖旧结论时同样主动替换；`mem_search` 评分为「命中关键词数 + 温和的 recency 加成（≤ +0.5，180 天线性衰减到 0）」，新旧结论冲突时自动偏向新条目
+- **知识保鲜** —— `mem_replace` 不只用于用户更正：本次工作覆盖旧结论时同样主动替换；`mem_search` 在匹配分之上叠加温和的 recency 加成（≤ +0.5，180 天线性衰减到 0），新旧结论冲突时自动偏向新条目
 - **主题聚合页（MOC）** —— `kind: "topic"` 条目聚合一个主题的「当前真相」：summary 概括当下有效结论，靠 `mem_replace` 演进（kind 自动继承），不按任务重复新增
 - **条目间 Wiki 链接** —— content 里用 `[[<commit-hash>]]` 引用其他条目；`mem_read` 传 `expand: true` 一跳展开链接目标，并自动跟随 `GitMemo-Replaces` 链到被替换条目的最新版本（悬空链接带 error 返回）
 - **结构化搜索** —— commit message 携带 `GitMemo-*` trailers（keywords、digest、search-text 投影）；搜索只对 commit message 执行 `git log --grep --fixed-strings`，绝不扫描条目正文
@@ -27,7 +27,7 @@
 
 | 内容 | 说明 |
 | --- | --- |
-| `mem_search` | 搜索记忆：`keywords`（1–12 个关键词数组，建议中英文同义词）、`skip` + `snapshot`（稳定分页）。每次最多返回 20 条带 `summary` / `keywords` / `kind` / `matched_keywords` 的评分结果（score = 命中关键词数 + recency 加成） |
+| `mem_search` | 搜索记忆：`keywords`（1–15 个关键词数组，建议中英文同义词）、`skip` + `snapshot`（稳定分页）。每次最多返回 20 条带 `summary` / `keywords` / `kind` / `matched_keywords` 的评分结果。score = 本页内命中关键词的稀有度之和（默认）或命中条数（`searchScoring: count`），再加 recency 加成 |
 | `mem_read` | 按创建/替换提交哈希读取一条记忆的完整 markdown（历史哈希仍可读）；返回 `kind`；可选 `expand: true` 一跳展开条目内的 `[[hash]]` 链接 |
 | `mem_write` | 存储任务结论：`title` + `summary` + `keywords`（2–12）+ `content`（front matter 由引擎生成），可选 `kind`（`"task"` 缺省 / `"topic"` 聚合页）、`related_branches` / `related_paths`。每个不可变文件对应一个 ADD 提交 |
 | `mem_delete` | 作废无替代结论（需要 `commit_hash` + `reason`） |
@@ -61,6 +61,7 @@ bundle patch 自带合理默认值，可在 profile 的 `cordis.patch.yml` 中
 - id: dsh-gitmemo
   config:
     searchLimit: 20        # 每次 mem_search 返回的最大条数（每页大小）
+    searchScoring: weighted  # weighted（默认）| count —— 见「检索评分」
     lockTimeoutMs: 30000   # 跨进程锁等待超时
     projectRoot: null      # 可选：显式项目根目录（默认取会话工作目录）
     systemOne:             # 可选：System-one 召回门控，见下节
@@ -68,11 +69,37 @@ bundle patch 自带合理默认值，可在 profile 的 `cordis.patch.yml` 中
       endpoint: https://api.typesafe.ai/v1/systemone
       model: jev-latest
       mode: noul           # noul | score
-      threshold: 0.5       # noul 模式：概率 ≥ 该值才保留
+      policy: rerank       # rerank（默认）| filter —— 见「System-one 召回门控」
+      threshold: 0.5       # filter 模式：概率 < 该值则丢弃
+      maxDropFraction: 0.25  # filter 模式：单页最多丢弃此比例
 ```
 
+## 检索评分
+
+`mem_search` 用固定字符串 OR grep 在提交消息投影上匹配——即标题、摘要与条目的关键词（正文从不扫描）。两种模式决定**顺序**，匹配到的条目集合完全相同：
+
+| `searchScoring` | 分值 | 取舍 |
+| --- | --- | --- |
+| `weighted`（默认） | 本页内各命中关键词稀有度之和，再加 recency 加成 | 有区分度的命中能压过若干常见命中；一次命中可以胜过两次，这是 `count` 模式不允许的 |
+| `count` | 命中关键词条数，再加 recency 加成 | 此前的默认算法，为完全向后兼容保留 |
+
+稀有度用的是候选页上的 BM25 式权重 `log(1 + (n − df + 0.5) / (df + 0.5))`（`n` 为候选数，`df` 为命中该关键词的候选数），因此不增加额外 git 调用。recency 加成仍 ≤ +0.5，只用于重排近乎同分的条目。
+
+**为什么把它设为默认。** 在 LongMemEval `_S`（500 个实例、会话粒度）上，引擎的 `recall_all@50` 达到 0.998，而 `ndcg_any@5` 只有 0.686：证据基本都能召回，但排不上来——因为纯命中计数分不清罕见词与随处可见的词。在完全相同的入库数据上只改加权，`recall_all@5` 从 0.738 升到 0.755、`ndcg@5` 从 0.687 升到 0.700，而 `recall_all@50` 仍是 0.998（匹配逻辑在构造上未改动）。完整实验与「打分 / 粒度 / 写入策略」三组消融见 `evals/longmemeval/README.md`。
+
 ## System-one 召回门控（可选）
 
+**判定结果怎么用 —— `policy`：**
+
+| `policy` | 作用 | 上下文 | 实测准确率 |
+| --- | --- | --- | --- |
+| `rerank`（默认） | 保留全部被判定的记忆，只按判定分值重排本页 | 不变 | **0.8020** |
+| `filter` | 丢弃低于 `threshold` 的记忆，并由 `maxDropFraction` 兜住上限 | **−80 %** | **0.3800** |
+
+以上是 LongMemEval `_S` 全部 500 题、同一个 judge、同一批已入库记忆、同一组候选分值下的 LLM-as-Judge 结果——**唯一的差别就是怎么用这些分值**。原因在信号本身：judge 区分证据与非证据的 AUC 只有约 0.71–0.75，因此**没有任何阈值是安全的**，但同一个分值作为排序特征是可靠的。在 0.75 AUC 的信号上做硬删，把 343 条 gold 记忆挡在了提示之外，涉及 500 个实例中的 254 个。
+
+`filter` 仍然保留：当上下文预算才是硬约束时，「丢弃」正是召回门控的意义所在。而它现在**有上限**了：`maxDropFraction`（默认 0.25）会在阈值想丢掉超过该比例时，把得分最高的被拒候选恢复回来。离线扫描显示 20% 上限能把 `recall_all@5` 稳在 0.8875，而不设上限只有 0.6875。丢掉的记忆就没了，留下的只是多花点上下文——两类错误并不对称，所以上限刻意收得紧。
+
 `mem_search` 的候选页可以交给一个 **System-one 模型**（默认 [TypeSafe Jev](https://docs.typesafe.ai)）
 做一次快速判断，把与当前任务**完全无关**的记忆从注入内容里剔除，只留下真正可复用的条目。
 
@@ -103,6 +130,8 @@ bundle patch 自带合理默认值，可在 profile 的 `cordis.patch.yml` 中
 | `threshold` | `0.5` | `noul` 模式：概率 ≥ 该值保留 |
 | `scoreMin` | `2` | `score` 模式阈值。注意 Jev 的 `score` 是 `Σ(层级序号 × 概率)`，范围是 0…层级数−1（默认 5 层 → 0…4），**不是 0–1** |
 | `minKeep` | `1` | 整页被拒时至少保留几条 |
+| `policy` | `rerank` | `rerank` 保留全部判定过的记忆并按分值重排；`filter` 丢弃低于 `threshold` 的候选 |
+| `maxDropFraction` | `0.25` | 仅 `filter`：单页最多丢弃此比例，从最低分开始丢 |
 | `maxCandidates` | `20` | 单次请求最多判定多少条；超出部分**不判定、不剔除** |
 | `maxTaskChars` | `2000` | 任务文本截断长度 |
 | `timeoutMs` | `8000` | 请求超时 |
@@ -116,18 +145,6 @@ bundle patch 自带合理默认值，可在 profile 的 `cordis.patch.yml` 中
 开关暂存的是 `systemOne.enabled`：关闭后召回行为与门控存在前逐字节一致；需要点**保存**才会写入
 （只拨开关是草稿）。未配置 `enabled` 时按开启处理，与该字段的宿主默认值一致。
 
-### 已知取舍
-
-- **英文优先。** Jev 的主要训练语言是英文，CJK 文本可用但官方标注准确率较低。门控的提问措辞固定为
-  英文，只有候选正文与任务文本可能是中文。
-- **上下文上限。** 单次请求 64k tokens，其中 `state` + 最长问题合计 32k。`maxCandidates` 与
-  `maxTaskChars` 就是为守住这条线而存在的。
-- **延迟在关键路径上。** 召回发生在每次仓库任务之前，门控会给 `mem_search` 增加一次网络往返
-  （实测约 0.4s 量级），因此 `timeoutMs` 默认 8s 且失败即放行。
-- **数据外发。** 记忆摘要会离开本机。TypeSafe 目前**不提供** zero data retention；若要避免外发，
-  可把 `endpoint` 指向自建实现（如 MIT 许可的 `jeff`）或本地端点。
-- **计费口径。** 按输入 token 计费（$0.042 / 百万输入 token，输出免费），不是按次计费。
-
 ## 记忆存放位置与格式
 
 `.mem` 仓库位于调用会话工作区的**项目根目录**（`git rev-parse --show-toplevel`，找不到时退回
@@ -156,7 +173,7 @@ git -C .mem show <commit-hash>
 
 ## Agent 工作流（常驻规则，仅根 Agent）
 
-1. **开工前 —— 搜索。** 仓库相关任务开始前提取 1–12 个中英文关键词 → `mem_search`。纯闲聊和通用问答无需搜索。
+1. **开工前 —— 搜索。** 仓库相关任务开始前提取 1–15 个中英文关键词 → `mem_search`。纯闲聊和通用问答无需搜索。
 2. **结果预筛。** 根据 `title` / `summary` / `keywords` / `score` / `matched_keywords` 最多
    `mem_read` 5 条最相关记忆（`kind: "topic"` 的条目是该主题的聚合入口，优先读）；用 `skip` + 返回的
    `snapshot` 翻页。

package/lib/index.d.ts

@@ -21,6 +21,7 @@
  * @module dsh-gitmemo
  */
 import z from "@deepseek-ai/schemastery";
+import { type SearchScoring } from "./mem.js";
 /** Cordis plugin name. */
 declare const name = "dsh-gitmemo";
 /** Host services this plugin needs. */
@@ -31,6 +32,21 @@ declare const Config: z<Schemastery.ObjectS<NoInfer<{
     memDirName: z<string, string, "defined">;
     /** Max search hits per mem_search call (page size). Default 20. */
     searchLimit: z<number, number, "defined">;
+    /**
+     * How a matched entry is scored (search order only — matching itself is
+     * identical in both modes).
+     *
+     * - `weighted` (default): sum of per-keyword rarity weights within the
+     *   recall page, so a distinctive match outranks several common ones.
+     * - `count`: the previous default behaviour (one point per matched keyword plus the
+     *   recency bonus), kept for exact backwards compatibility.
+     *
+     * Measured motivation: on LongMemEval `_S` the engine reached
+     * recall_all@50 = 0.998 while ndcg@5 was only 0.686 — evidence was reachable
+     * but ranked poorly, because a saturated-free match count cannot tell a rare
+     * keyword from a ubiquitous one.
+     */
+    searchScoring: z<"count" | "weighted", "count" | "weighted", "defined">;
     /** @deprecated — `.mem` always stays on main; kept for one version, no effect. */
     branchAlign: z<boolean, boolean, "defined">;
     /** @deprecated — session-start recent seeding was removed; kept for one version, no effect. */
@@ -74,6 +90,25 @@ declare const Config: z<Schemastery.ObjectS<NoInfer<{
         scoreMin: z<number, number, "volatile-defined">;
         /** Retain at least this many candidates when the model rejects an entire page. */
         minKeep: z<number, number, "volatile-defined">;
+        /**
+         * What happens to a judged candidate.
+         *
+         * `rerank` (default) keeps every candidate and lets the judge's value order
+         * the page; `filter` drops those below the threshold, bounded by
+         * `maxDropFraction`. Measured end-to-end on LongMemEval `_S` with the same
+         * judge and the same per-candidate values: filtering at the default
+         * threshold scored 0.3800, ordering scored 0.8020. The judge's AUC is
+         * ~0.71-0.75, so no threshold is safe, but the ordering is useful. See
+         * evals/longmemeval/README.md.
+         */
+        policy: z<"filter" | "rerank", "filter" | "rerank", "volatile-defined">;
+        /**
+         * `filter` policy only: never drop more than this share of the judged page,
+         * lowest-scoring first. Caps the damage a mis-calibrated threshold can do —
+         * a memory dropped is gone, a memory kept only costs context. The offline
+         * sweep held recall_all@5 at 0.8875 with a 20 % cap against 0.6875 uncapped.
+         */
+        maxDropFraction: z<number, number, "volatile-defined">;
         /** Never judge more than this many candidates per request. */
         maxCandidates: z<number, number, "volatile-defined">;
         /** Truncate the task text to this many characters before sending it. */
@@ -101,6 +136,25 @@ declare const Config: z<Schemastery.ObjectS<NoInfer<{
         scoreMin: z<number, number, "volatile-defined">;
         /** Retain at least this many candidates when the model rejects an entire page. */
         minKeep: z<number, number, "volatile-defined">;
+        /**
+         * What happens to a judged candidate.
+         *
+         * `rerank` (default) keeps every candidate and lets the judge's value order
+         * the page; `filter` drops those below the threshold, bounded by
+         * `maxDropFraction`. Measured end-to-end on LongMemEval `_S` with the same
+         * judge and the same per-candidate values: filtering at the default
+         * threshold scored 0.3800, ordering scored 0.8020. The judge's AUC is
+         * ~0.71-0.75, so no threshold is safe, but the ordering is useful. See
+         * evals/longmemeval/README.md.
+         */
+        policy: z<"filter" | "rerank", "filter" | "rerank", "volatile-defined">;
+        /**
+         * `filter` policy only: never drop more than this share of the judged page,
+         * lowest-scoring first. Caps the damage a mis-calibrated threshold can do —
+         * a memory dropped is gone, a memory kept only costs context. The offline
+         * sweep held recall_all@5 at 0.8875 with a 20 % cap against 0.6875 uncapped.
+         */
+        maxDropFraction: z<number, number, "volatile-defined">;
         /** Never judge more than this many candidates per request. */
         maxCandidates: z<number, number, "volatile-defined">;
         /** Truncate the task text to this many characters before sending it. */
@@ -113,6 +167,21 @@ declare const Config: z<Schemastery.ObjectS<NoInfer<{
     memDirName: z<string, string, "defined">;
     /** Max search hits per mem_search call (page size). Default 20. */
     searchLimit: z<number, number, "defined">;
+    /**
+     * How a matched entry is scored (search order only — matching itself is
+     * identical in both modes).
+     *
+     * - `weighted` (default): sum of per-keyword rarity weights within the
+     *   recall page, so a distinctive match outranks several common ones.
+     * - `count`: the previous default behaviour (one point per matched keyword plus the
+     *   recency bonus), kept for exact backwards compatibility.
+     *
+     * Measured motivation: on LongMemEval `_S` the engine reached
+     * recall_all@50 = 0.998 while ndcg@5 was only 0.686 — evidence was reachable
+     * but ranked poorly, because a saturated-free match count cannot tell a rare
+     * keyword from a ubiquitous one.
+     */
+    searchScoring: z<"count" | "weighted", "count" | "weighted", "defined">;
     /** @deprecated — `.mem` always stays on main; kept for one version, no effect. */
     branchAlign: z<boolean, boolean, "defined">;
     /** @deprecated — session-start recent seeding was removed; kept for one version, no effect. */
@@ -156,6 +225,25 @@ declare const Config: z<Schemastery.ObjectS<NoInfer<{
         scoreMin: z<number, number, "volatile-defined">;
         /** Retain at least this many candidates when the model rejects an entire page. */
         minKeep: z<number, number, "volatile-defined">;
+        /**
+         * What happens to a judged candidate.
+         *
+         * `rerank` (default) keeps every candidate and lets the judge's value order
+         * the page; `filter` drops those below the threshold, bounded by
+         * `maxDropFraction`. Measured end-to-end on LongMemEval `_S` with the same
+         * judge and the same per-candidate values: filtering at the default
+         * threshold scored 0.3800, ordering scored 0.8020. The judge's AUC is
+         * ~0.71-0.75, so no threshold is safe, but the ordering is useful. See
+         * evals/longmemeval/README.md.
+         */
+        policy: z<"filter" | "rerank", "filter" | "rerank", "volatile-defined">;
+        /**
+         * `filter` policy only: never drop more than this share of the judged page,
+         * lowest-scoring first. Caps the damage a mis-calibrated threshold can do —
+         * a memory dropped is gone, a memory kept only costs context. The offline
+         * sweep held recall_all@5 at 0.8875 with a 20 % cap against 0.6875 uncapped.
+         */
+        maxDropFraction: z<number, number, "volatile-defined">;
         /** Never judge more than this many candidates per request. */
         maxCandidates: z<number, number, "volatile-defined">;
         /** Truncate the task text to this many characters before sending it. */
@@ -183,6 +271,25 @@ declare const Config: z<Schemastery.ObjectS<NoInfer<{
         scoreMin: z<number, number, "volatile-defined">;
         /** Retain at least this many candidates when the model rejects an entire page. */
         minKeep: z<number, number, "volatile-defined">;
+        /**
+         * What happens to a judged candidate.
+         *
+         * `rerank` (default) keeps every candidate and lets the judge's value order
+         * the page; `filter` drops those below the threshold, bounded by
+         * `maxDropFraction`. Measured end-to-end on LongMemEval `_S` with the same
+         * judge and the same per-candidate values: filtering at the default
+         * threshold scored 0.3800, ordering scored 0.8020. The judge's AUC is
+         * ~0.71-0.75, so no threshold is safe, but the ordering is useful. See
+         * evals/longmemeval/README.md.
+         */
+        policy: z<"filter" | "rerank", "filter" | "rerank", "volatile-defined">;
+        /**
+         * `filter` policy only: never drop more than this share of the judged page,
+         * lowest-scoring first. Caps the damage a mis-calibrated threshold can do —
+         * a memory dropped is gone, a memory kept only costs context. The offline
+         * sweep held recall_all@5 at 0.8875 with a 20 % cap against 0.6875 uncapped.
+         */
+        maxDropFraction: z<number, number, "volatile-defined">;
         /** Never judge more than this many candidates per request. */
         maxCandidates: z<number, number, "volatile-defined">;
         /** Truncate the task text to this many characters before sending it. */
@@ -231,6 +338,7 @@ declare function apply(ctx: {
 }, config?: Partial<{
     memDirName?: string;
     searchLimit?: number;
+    searchScoring?: SearchScoring;
     branchAlign?: boolean;
     recentContextLimit?: number;
     lockTimeoutMs?: number;

package/lib/index.js

@@ -34,6 +34,21 @@ const Config = z.object({
     memDirName: z.string().default(".mem"),
     /** Max search hits per mem_search call (page size). Default 20. */
     searchLimit: z.number().default(20),
+    /**
+     * How a matched entry is scored (search order only — matching itself is
+     * identical in both modes).
+     *
+     * - `weighted` (default): sum of per-keyword rarity weights within the
+     *   recall page, so a distinctive match outranks several common ones.
+     * - `count`: the previous default behaviour (one point per matched keyword plus the
+     *   recency bonus), kept for exact backwards compatibility.
+     *
+     * Measured motivation: on LongMemEval `_S` the engine reached
+     * recall_all@50 = 0.998 while ndcg@5 was only 0.686 — evidence was reachable
+     * but ranked poorly, because a saturated-free match count cannot tell a rare
+     * keyword from a ubiquitous one.
+     */
+    searchScoring: z.union(["count", "weighted"]).default("weighted"),
     /** @deprecated — `.mem` always stays on main; kept for one version, no effect. */
     branchAlign: z.boolean().default(true),
     /** @deprecated — session-start recent seeding was removed; kept for one version, no effect. */
@@ -77,6 +92,25 @@ const Config = z.object({
         scoreMin: z.number().default(2).volatile(),
         /** Retain at least this many candidates when the model rejects an entire page. */
         minKeep: z.number().step(1).min(0).default(1).volatile(),
+        /**
+         * What happens to a judged candidate.
+         *
+         * `rerank` (default) keeps every candidate and lets the judge's value order
+         * the page; `filter` drops those below the threshold, bounded by
+         * `maxDropFraction`. Measured end-to-end on LongMemEval `_S` with the same
+         * judge and the same per-candidate values: filtering at the default
+         * threshold scored 0.3800, ordering scored 0.8020. The judge's AUC is
+         * ~0.71-0.75, so no threshold is safe, but the ordering is useful. See
+         * evals/longmemeval/README.md.
+         */
+        policy: z.union(["rerank", "filter"]).default("rerank").volatile(),
+        /**
+         * `filter` policy only: never drop more than this share of the judged page,
+         * lowest-scoring first. Caps the damage a mis-calibrated threshold can do —
+         * a memory dropped is gone, a memory kept only costs context. The offline
+         * sweep held recall_all@5 at 0.8875 with a 20 % cap against 0.6875 uncapped.
+         */
+        maxDropFraction: z.number().min(0).max(1).default(0.25).volatile(),
         /** Never judge more than this many candidates per request. */
         maxCandidates: z.number().step(1).min(1).default(20).volatile(),
         /** Truncate the task text to this many characters before sending it. */
@@ -120,6 +154,8 @@ function readSystemOne(config) {
         threshold: liveValue(section.threshold, 0.5),
         scoreMin: liveValue(section.scoreMin, 2),
         minKeep: liveValue(section.minKeep, 1),
+        policy: liveValue(section.policy, "rerank") === "filter" ? "filter" : "rerank",
+        maxDropFraction: liveValue(section.maxDropFraction, 0.25),
         maxCandidates: liveValue(section.maxCandidates, 20),
         maxTaskChars: liveValue(section.maxTaskChars, 2000),
         timeoutMs: liveValue(section.timeoutMs, 8000),
@@ -205,7 +241,8 @@ async function engineFor(exec, config) {
     const root = config.projectRoot ?? (await resolveProjectRoot(cwd));
     const engineConfig = {
         searchLimit: config.searchLimit,
-        lockTimeoutMs: config.lockTimeoutMs
+        lockTimeoutMs: config.lockTimeoutMs,
+        searchScoring: config.searchScoring
     };
     return new GitMemo(root, engineConfig);
 }
@@ -231,7 +268,9 @@ const SEARCH_HIT = {
         score: {
             type: "number",
             required: true,
-            description: "Relevance: distinct matched keywords + a mild recency bonus (≤ +0.5, decaying to 0 by ~180 days)."
+            description: "Relevance. In the default `weighted` scoring: the summed rarity of the matched keywords within this page " +
+                "(a distinctive match outweighs several common ones) plus a mild recency bonus (≤ +0.5, decaying to 0 by ~180 days). " +
+                "With `searchScoring: count`: distinct matched keywords + the same recency bonus."
         },
         matched_keywords: {
             type: "array",
@@ -264,10 +303,17 @@ const LINK_RESOLUTION = {
         error: { type: "string", description: "Present when the link target could not be resolved (dangling link)." }
     }
 };
+/** Stored-entry keywords (mem_write / mem_replace): 2-12, mirrors MAX_WRITE_KEYWORDS. */
 const KEYWORDS_ARRAY = {
     type: "array",
     items: { type: "string" },
-    description: "1-12 keywords (include 中英文 synonyms when useful)."
+    description: "2-12 keywords (include 中英文 synonyms when useful)."
+};
+/** Query keywords (mem_search): 1-15, mirrors MAX_SEARCH_KEYWORDS. */
+const SEARCH_KEYWORDS_ARRAY = {
+    type: "array",
+    items: { type: "string" },
+    description: "1-15 keywords (include 中英文 synonyms when useful)."
 };
 const RELATED_BRANCHES = {
     type: "array",
@@ -342,9 +388,9 @@ function formatSearchResults(value) {
 function registerMemTools(ctx, config) {
     ctx.tools.register(defineTool({
         name: "mem_search",
-        description: "Search the gitmemo long-term memory (.mem git repo) for past task outcomes. Call BEFORE starting repo-related work: extract 1-12 中英文关键词 from the user request (include synonyms in both languages when useful) and run mem_search; pure chat and general Q&A need no search. Returns a snapshot, total, next_skip and up to 20 scored hits with summary/keywords/kind/matched_keywords — score = distinct matched keywords + a mild recency bonus, so newer entries rank slightly higher and superseded conclusions lose to their replacements. Select at most 5 most relevant hits and mem_read them (prefer kind:\"topic\" hits as topic-page entry points). Paginate by passing skip and the returned snapshot back unchanged; a stale snapshot is rejected explicitly. An optional System-one gate may narrow the page: when the output carries a `gated` block, the entries it removed are listed as 8-char `dropped_hashes` — mem_read one of those if you suspect a relevant memory was filtered out (they stay fully readable). A `NOTE(...)` on the `gated` line means every candidate was judged irrelevant and only a `minKeep` floor was retained, not that one candidate passed.",
+        description: "Search the gitmemo long-term memory (.mem git repo) for past task outcomes. Call BEFORE starting repo-related work: extract 1-15 中英文关键词 from the user request (include synonyms in both languages when useful) and run mem_search; pure chat and general Q&A need no search. Returns a snapshot, total, next_skip and up to 20 scored hits with summary/keywords/kind/matched_keywords — score = distinct matched keywords + a mild recency bonus, so newer entries rank slightly higher and superseded conclusions lose to their replacements. Select at most 5 most relevant hits and mem_read them (prefer kind:\"topic\" hits as topic-page entry points). Paginate by passing skip and the returned snapshot back unchanged; a stale snapshot is rejected explicitly. An optional System-one gate may narrow the page: when the output carries a `gated` block, the entries it removed are listed as 8-char `dropped_hashes` — mem_read one of those if you suspect a relevant memory was filtered out (they stay fully readable). A `NOTE(...)` on the `gated` line means every candidate was judged irrelevant and only a `minKeep` floor was retained, not that one candidate passed.",
         parameters: {
-            keywords: { ...KEYWORDS_ARRAY, required: true },
+            keywords: { ...SEARCH_KEYWORDS_ARRAY, required: true },
             skip: {
                 type: "integer",
                 description: "Pagination offset (default 0)."
@@ -454,8 +500,10 @@ function registerMemTools(ctx, config) {
                 " candidates=" + candidates.length +
                 " judged=" + decision.judged +
                 (decision.untouched === 0 ? "" : " untouched=" + decision.untouched) +
+                " policy=" + decision.policy +
                 " kept=" + decision.kept.length +
                 " dropped=" + decision.dropped.length +
+                (decision.bounded ? " bounded=yes" : "") +
                 (decision.reason === undefined ? "" : " reason=" + decision.reason) +
                 (decision.usage?.inputTokens === undefined ? "" : " input_tokens=" + decision.usage.inputTokens) +
                 " verdicts=" +
@@ -463,10 +511,20 @@ function registerMemTools(ctx, config) {
                     .map((verdict) => verdict.hash.slice(0, 8) + ":" + (verdict.value ?? "na") + ":" + (verdict.keep ? "keep" : "drop"))
                     .join(","));
             const kept = new Set(decision.kept);
+            // `rerank` reorders the page by the judge's value and drops nothing;
+            // `filter` keeps the shipped behaviour, already bounded by
+            // `maxDropFraction` inside `decide`. Both preserve page order for
+            // everything the gate left alone.
+            const surviving = result.results.filter((hit) => kept.has(hit.hash));
+            const reranked = decision.policy === "rerank"
+                ? [...surviving].sort((a, b) => decision.ordered.indexOf(a.hash) - decision.ordered.indexOf(b.hash))
+                : surviving;
             return {
                 ...result,
-                results: result.results.filter((hit) => kept.has(hit.hash)),
+                results: reranked,
                 gated: {
+                    policy: decision.policy,
+                    ...(decision.bounded ? { bounded: true } : {}),
                     mode: decision.mode,
                     model: decision.model,
                     candidates: candidates.length,
@@ -746,10 +804,10 @@ function registerPromptSection(ctx) {
         order: 150,
         text: [
             "This deployment provides gitmemo long-term memory: a local .mem git repository at the project root stores past task outcomes as immutable markdown entries; git is the only dependency. Use the dedicated tools only (mem_search / mem_read / mem_write / mem_delete / mem_replace — all auto-initialize, and legacy-format .mem repos migrate automatically on first use); never shell out to git or read .mem files directly.",
-            "- BEFORE WORK — search: 仓库相关任务开始前提取 1–12 个中英文关键词调用 mem_search（含中英文同义词）；纯闲聊和通用问答无需搜索。",
+            "- BEFORE WORK — search: 仓库相关任务开始前提取 1–15 个中英文关键词调用 mem_search（含中英文同义词；搜索关键词上限高于写入上限，详见 KEYWORD SELECTION）；纯闲聊和通用问答无需搜索。",
             "- RESULT PRESELECT — 根据 title、summary、keywords、score 和 matched keywords 选择最多 5 条执行 mem_read，复用相关结论；kind 为 topic 的条目是该主题的聚合入口，优先读；无相关结果时用返回的 snapshot + skip 翻页。",
             "- END-OF-SESSION CHECKPOINT — the ONLY write path: 会话结束时回顾全程，仅当结论有价值、可复用或用户明确要求记住时 mem_write；纯问答、未完成任务、非仓库工作、纯操作类 git 动作（仅 commit/push）不写；避免语义重复。",
-            "- KEYWORD SELECTION — mem_write/mem_replace 的 keywords 应选择与任务相关但未出现在 title/summary 中的词（中英文同义词皆可）；title/summary 里已有的词本身就能被检索到，重复它们不会提高召回率。",
+            "- KEYWORD SELECTION — mem_write/mem_replace 的 keywords 应选择与任务相关但未出现在 title/summary 中的词（中英文同义词皆可，2–12 个）；mem_search 的查询词上限更高（1–15 个），多给近义词/中英对照可提升召回。title/summary 里已有的词本身就能被检索到，重复它们不会提高召回率。",
             "- KEEP FRESH — 结论保鲜是写路径的一部分，不必等用户指出：用户更正旧结论时，有替代结论用 mem_replace（禁止先 delete 再 write），作废且无替代用带 reason 的 mem_delete；本次会话的工作覆盖/推翻了某条已存结论（被后续实现、重构取代）时，同样主动 mem_replace 或 mem_delete 对应旧条目；检索结果中新旧结论冲突时，优先采信 score 更高/日期更新的条目（score 已含温和的 recency 加成）。",
             "- TOPIC PAGE — 同一主题已积累多条记忆、或需要一个「当前真相」入口时，用 mem_write 写一条 kind:\"topic\" 聚合条目：summary 概括当下仍然有效的结论，content 用 [[<commit-hash>]] 链接各证据条目并各配一句话状态；topic 条目靠 mem_replace 演进（kind 自动继承），不是按任务新增。",
             "- WIKI LINKS — content 中引用其他记忆条目一律写 [[<commit-hash>]]（用 mem_search/mem_read 返回的 hash）；mem_read 传 expand:true 会把链接一跳展开到各条目的最新版本（悬空链接以 error 返回），读 topic 条目时建议展开。",
@@ -769,6 +827,7 @@ async function apply(ctx, config = {}) {
     };
     const resolved = {
         searchLimit: config.searchLimit ?? 20,
+        searchScoring: config.searchScoring ?? "weighted",
         lockTimeoutMs: config.lockTimeoutMs ?? 30000,
         projectRoot: config.projectRoot,
         log,
@@ -793,6 +852,8 @@ async function apply(ctx, config = {}) {
                 threshold: section.threshold,
                 scoreMin: section.scoreMin,
                 minKeep: section.minKeep,
+                policy: section.policy,
+                maxDropFraction: section.maxDropFraction,
                 maxCandidates: section.maxCandidates,
                 maxTaskChars: section.maxTaskChars,
                 timeoutMs: section.timeoutMs,

package/lib/mem.d.ts

@@ -10,6 +10,15 @@ export declare const LOCK_FILE_NAME = ".mem.gitmemo.lock";
 export declare const MIGRATION_JOURNAL_NAME = ".mem.gitmemo-migration.json";
 /** Max entry content size. */
 export declare const MAX_CONTENT_BYTES: number;
+/** Upper bound on stored entry keywords (mem_write / mem_replace). */
+export declare const MAX_WRITE_KEYWORDS = 12;
+/**
+ * Upper bound on query keywords for one mem_search call. Deliberately higher
+ * than the write bound: recall is a fixed-string OR over the query terms, so a
+ * wider (still human-curated) query only widens recall, while every matched
+ * term still contributes to the score and the write side keeps entries tight.
+ */
+export declare const MAX_SEARCH_KEYWORDS = 15;
 /** Error type thrown by every gitmemo operation. */
 export declare class GitMemoError extends Error {
 }
@@ -21,6 +30,17 @@ export interface GitMemoConfig {
     gitTimeoutMs?: number;
     /** Cross-process lock wait timeout in milliseconds. Default 30000. */
     lockTimeoutMs?: number;
+    /**
+     * How `mem_search` scores a matched entry.
+     *
+     * - `weighted` (default): sum of per-keyword rarity weights over the recall
+     *   page. A distinctive match outranks several common ones.
+     * - `count`: the previous default behaviour — one point per matched keyword plus the
+     *   recency bonus. Kept for exact backwards compatibility.
+     *
+     * Both modes match the same entries; only the ordering differs.
+     */
+    searchScoring?: SearchScoring;
     /** @deprecated parsed for compatibility only — the memory dir is fixed at `<projectRoot>/.mem`. */
     memDirName?: string;
     /** @deprecated parsed for compatibility only — `.mem` always stays on main. */
@@ -28,6 +48,10 @@ export interface GitMemoConfig {
     /** @deprecated parsed for compatibility only — session-start recent seeding was removed. */
     recentContextLimit?: number;
 }
+/** Search scoring mode; see {@link GitMemoConfig.searchScoring}. */
+export type SearchScoring = "count" | "weighted";
+/** Accepted `searchScoring` values, for config validation and tool schemas. */
+export declare const SEARCH_SCORING_MODES: readonly SearchScoring[];
 /** One scored search hit. */
 export interface SearchHit {
     hash: string;
@@ -258,6 +282,18 @@ export declare function buildEntryMarkdown(input: ValidatedWriteInput, ctx: Code
  * matched keyword, so freshness only reorders equal-match entries.
  */
 export declare function recencyBonus(committerTime: number, nowMs?: number): number;
+/**
+ * Rarity weight of a keyword matched by `df` of `n` candidates, in the
+ * BM25-style form already used across this project. A term matched by every
+ * candidate is worth almost nothing; a term matched by one candidate out of
+ * many is worth the most.
+ *
+ * Used by `searchScoring: "weighted"` so a distinctive match can outrank a
+ * pile of common ones. The weight is computed over the *recall page*, which
+ * costs no extra git call (the candidate commit messages are already in hand)
+ * and is the pool the ordering actually has to get right.
+ */
+export declare function keywordRarity(df: number, n: number): number;
 /** ADD commit message (plan 4.1). */
 export declare function buildAddMessage(title: string, summary: string, keywords: string[], digest: string, legacy?: boolean, kind?: "task" | "topic"): string;
 /** DELETE commit message (plan 4.2). */
@@ -349,7 +385,7 @@ export declare class GitMemo {
      * messages only, active-entry filtering, field-level matching and scoring,
      * snapshot-stable pagination, in-process LRU.
      *
-     * @param keywords - 1-12 keywords (legacy callers may pass a comma-separated string).
+     * @param keywords - 1-15 keywords (legacy callers may pass a comma-separated string).
      * @param options.skip - pagination offset.
      * @param options.snapshot - pass back the snapshot from the first page.
      */

package/lib/mem.js

@@ -34,9 +34,20 @@ export const LOCK_FILE_NAME = ".mem.gitmemo.lock";
 export const MIGRATION_JOURNAL_NAME = ".mem.gitmemo-migration.json";
 /** Max entry content size. */
 export const MAX_CONTENT_BYTES = 1024 * 1024;
+/** Upper bound on stored entry keywords (mem_write / mem_replace). */
+export const MAX_WRITE_KEYWORDS = 12;
+/**
+ * Upper bound on query keywords for one mem_search call. Deliberately higher
+ * than the write bound: recall is a fixed-string OR over the query terms, so a
+ * wider (still human-curated) query only widens recall, while every matched
+ * term still contributes to the score and the write side keeps entries tight.
+ */
+export const MAX_SEARCH_KEYWORDS = 15;
 /** Error type thrown by every gitmemo operation. */
 export class GitMemoError extends Error {
 }
+/** Accepted `searchScoring` values, for config validation and tool schemas. */
+export const SEARCH_SCORING_MODES = ["count", "weighted"];
 const UNSAFE_CONTROL_RE = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/;
 const TRAILER_INJECT_RE = /^\s*GitMemo-[A-Za-z0-9-]+:/im;
 const COMMIT_RE = /^[0-9a-f]{40}$/;
@@ -256,8 +267,8 @@ export function validateWriteInput(input, legacy = false) {
         throw new GitMemoError("gitmemo: keywords must be an array");
     const rawKeywords = input.keywords.map((k) => (typeof k === "string" ? k.trim() : "")).filter((k) => k.length > 0);
     const minKeywords = legacy ? 0 : 2;
-    if (rawKeywords.length < minKeywords || rawKeywords.length > 12) {
-        throw new GitMemoError(`gitmemo: keywords must contain ${minKeywords === 0 ? "0-12" : "2-12"} entries, got ${rawKeywords.length}`);
+    if (rawKeywords.length < minKeywords || rawKeywords.length > MAX_WRITE_KEYWORDS) {
+        throw new GitMemoError(`gitmemo: keywords must contain ${minKeywords === 0 ? "0" : "2"}-${MAX_WRITE_KEYWORDS} entries, got ${rawKeywords.length}`);
     }
     const keywords = [];
     const seen = new Set();
@@ -271,7 +282,7 @@ export function validateWriteInput(input, legacy = false) {
         keywords.push(kw);
     }
     if (keywords.length < minKeywords) {
-        throw new GitMemoError(`gitmemo: keywords must contain ${minKeywords === 0 ? "0-12" : "2-12"} distinct entries after normalization, got ${keywords.length}`);
+        throw new GitMemoError(`gitmemo: keywords must contain ${minKeywords === 0 ? "0" : "2"}-${MAX_WRITE_KEYWORDS} distinct entries after normalization, got ${keywords.length}`);
     }
     let related_branches = [];
     if (input.related_branches !== undefined) {
@@ -495,6 +506,23 @@ export function recencyBonus(committerTime, nowMs = Date.now()) {
         return 0;
     return Math.round(((0.5 * (180 - ageDays)) / 150) * 100) / 100;
 }
+/**
+ * Rarity weight of a keyword matched by `df` of `n` candidates, in the
+ * BM25-style form already used across this project. A term matched by every
+ * candidate is worth almost nothing; a term matched by one candidate out of
+ * many is worth the most.
+ *
+ * Used by `searchScoring: "weighted"` so a distinctive match can outrank a
+ * pile of common ones. The weight is computed over the *recall page*, which
+ * costs no extra git call (the candidate commit messages are already in hand)
+ * and is the pool the ordering actually has to get right.
+ */
+export function keywordRarity(df, n) {
+    if (n <= 0)
+        return 0;
+    const present = Math.min(Math.max(df, 0), n);
+    return Math.log(1 + (n - present + 0.5) / (present + 0.5));
+}
 /** Commit trailer emitted only for topic pages (absence means "task"). */
 const KIND_TRAILER_TOPIC = "GitMemo-Kind: topic";
 /** ADD commit message (plan 4.1). */
@@ -1248,10 +1276,15 @@ export class GitMemo {
             }
             return value;
         };
+        const scoring = config.searchScoring ?? "weighted";
+        if (!SEARCH_SCORING_MODES.includes(scoring)) {
+            throw new GitMemoError(`gitmemo: searchScoring must be one of ${SEARCH_SCORING_MODES.join(" | ")}, got ${JSON.stringify(config.searchScoring)}`);
+        }
         this.config = {
             searchLimit: positiveInt(config.searchLimit, 20, "searchLimit"),
             gitTimeoutMs: positiveInt(config.gitTimeoutMs, 60000, "gitTimeoutMs"),
-            lockTimeoutMs: positiveInt(config.lockTimeoutMs, 30000, "lockTimeoutMs")
+            lockTimeoutMs: positiveInt(config.lockTimeoutMs, 30000, "lockTimeoutMs"),
+            searchScoring: scoring
         };
         this.memDir = join(this.root, ".mem");
     }
@@ -1299,7 +1332,7 @@ export class GitMemo {
      * messages only, active-entry filtering, field-level matching and scoring,
      * snapshot-stable pagination, in-process LRU.
      *
-     * @param keywords - 1-12 keywords (legacy callers may pass a comma-separated string).
+     * @param keywords - 1-15 keywords (legacy callers may pass a comma-separated string).
      * @param options.skip - pagination offset.
      * @param options.snapshot - pass back the snapshot from the first page.
      */
@@ -1312,7 +1345,7 @@ export class GitMemo {
                 .map((k) => k.trim())
                 .filter((k) => k.length > 0)
                 .map((k) => normalizeKeyword(k));
-            adapterWarning = "gitmemo: deprecation — mem_search.keywords as a comma-separated string; pass an array of 1-12 keywords";
+            adapterWarning = `gitmemo: deprecation — mem_search.keywords as a comma-separated string; pass an array of 1-${MAX_SEARCH_KEYWORDS} keywords`;
         }
         else {
             if (!Array.isArray(keywords))
@@ -1324,8 +1357,8 @@ export class GitMemo {
             adapterWarning = (adapterWarning ? adapterWarning + " " : "") +
                 "gitmemo: deprecation — mem_search.mode is gone; recall is always OR";
         }
-        if (normalized.length < 1 || normalized.length > 12) {
-            throw new GitMemoError("gitmemo: search requires 1-12 non-empty keywords");
+        if (normalized.length < 1 || normalized.length > MAX_SEARCH_KEYWORDS) {
+            throw new GitMemoError(`gitmemo: search requires 1-${MAX_SEARCH_KEYWORDS} non-empty keywords`);
         }
         const skip = options.skip ?? 0;
         if (!Number.isInteger(skip) || skip < 0)
@@ -1348,7 +1381,11 @@ export class GitMemo {
                 : undefined;
             return { ...resolved, blockedNote: note };
         });
-        const cacheKey = this.memDir + "\x00" + snapshot + "\x00" + normalized.join("\x00");
+        // The scoring mode is part of the key: two handles on the SAME repo with
+        // different `searchScoring` must not share a cached ranking. (Omitting it
+        // made an A/B of the two modes return identical results — the second
+        // handle simply read the first one's cached computation.)
+        const cacheKey = this.memDir + "\x00" + snapshot + "\x00" + this.config.searchScoring + "\x00" + normalized.join("\x00");
         let computation = searchCache.get(cacheKey);
         if (computation === undefined) {
             computation = await this.computeSearch(snapshot, normalized, legacy);
@@ -1383,6 +1420,15 @@ export class GitMemo {
         const diagnostics = [...(legacySnapshot?.diagnostics ?? [])];
         const seenFiles = new Set();
         const nowMs = Date.now();
+        // Two passes: collect the matching candidates first, then (in weighted
+        // mode) score each match by how rare its keyword is *within this recall
+        // page*. Saturation-free counting treats a distinctive term like
+        // "biscuit" exactly like a ubiquitous one, which is what the LongMemEval
+        // measurements pinned as the engine's ranking defect: evidence was almost
+        // always reachable (recall_all@50 = 0.998) but ranked poorly
+        // (ndcg_any@5 = 0.686). Rarity re-weights the same matches without
+        // changing which entries match at all, so recall is untouched by design.
+        const scored = [];
         for (const record of candidates) {
             if (record.added.length !== 1) {
                 if (record.added.length > 1)
@@ -1409,6 +1455,24 @@ export class GitMemo {
             }
             if (matched.length === 0)
                 continue;
+            scored.push({ record, matched });
+        }
+        let weights;
+        if (this.config.searchScoring === "weighted" && scored.length > 0) {
+            weights = new Map();
+            for (const kw of kws) {
+                let df = 0;
+                for (const entry of scored) {
+                    if (entry.matched.includes(kw))
+                        df += 1;
+                }
+                weights.set(kw, keywordRarity(df, scored.length));
+            }
+        }
+        for (const { record, matched } of scored) {
+            const base = weights === undefined
+                ? matched.length
+                : matched.reduce((sum, kw) => sum + (weights.get(kw) ?? 0), 0);
             hits.push({
                 hash: record.hash,
                 title: record.message.subject,
@@ -1416,7 +1480,7 @@ export class GitMemo {
                 summary: record.message.summary,
                 keywords: record.message.keywords,
                 kind: record.message.kind,
-                score: Math.round((matched.length + recencyBonus(record.committerTime, nowMs)) * 100) / 100,
+                score: Math.round((base + recencyBonus(record.committerTime, nowMs)) * 100) / 100,
                 matched_keywords: matched
             });
         }

package/lib/systemone.d.ts

@@ -54,6 +54,15 @@ export interface GateOptions {
     scoreMin: number;
     /** Retain at least this many candidates when the model rejects the whole page. */
     minKeep: number;
+    /** What the caller does with the values; see {@link GatePolicy}. */
+    policy?: GatePolicy;
+    /**
+     * `filter` policy only: never drop more than this fraction of the judged page,
+     * lowest-scoring first. Bounds the damage a mis-calibrated threshold can do —
+     * an offline sweep kept recall_all@5 at 0.8875 with a 20 % cap, against 0.6875
+     * uncapped. Default 0.25.
+     */
+    maxDropFraction?: number;
     /** Never send more than this many candidates in one request. */
     maxCandidates: number;
     /** Truncate the task text to this many characters. */
@@ -96,6 +105,16 @@ export interface GateDecision {
     dropped: string[];
     /** Per-candidate verdicts, in candidate order. */
     verdicts: GateVerdict[];
+    /** Policy actually applied; see {@link GatePolicy}. */
+    policy: GatePolicy;
+    /** True when `maxDropFraction` restored candidates a threshold would have removed. */
+    bounded: boolean;
+    /**
+     * Candidate hashes ordered by the judge's value, best first (nulls last and
+     * kept stable). This is what the `rerank` policy applies; in `filter` mode it
+     * is still reported so a caller can log or inspect the judge's ordering.
+     */
+    ordered: string[];
     /** Question type actually used. */
     mode: SystemOneMode;
     /** Model identifier the request named. */
@@ -142,6 +161,23 @@ export declare const NOUL_CRITERIA: {
 };
 /** The judgement asked of the model in `score` mode. */
 export declare const SCORE_INSTRUCTION = "How relevant is the `candidate` memory record to the `task`? Rate how reusable its conclusions, decisions, constraints, or findings are for this exact task.";
+/**
+ * What the caller does with the judge's values.
+ *
+ * - `rerank` (default): keep every judged candidate and let the values reorder
+ *   the page. Cannot lose a memory by construction.
+ * - `filter`: drop candidates below the threshold, then apply `maxDropFraction`.
+ *
+ * Measured on LongMemEval `_S` (500 questions, identical ingested memories): at
+ * threshold 0.5 the filter held 343 gold memories out of the prompt across 254
+ * instances and took LLM-as-Judge from 0.7840 to 0.3800, while the same values
+ * used as a reranker scored 0.8020 on the same context. The judge's AUC is only
+ * ~0.71-0.75, so no threshold can make a hard drop safe; the same signal is a
+ * fine ordering feature. See evals/longmemeval/README.md.
+ */
+export type GatePolicy = "rerank" | "filter";
+/** Accepted `policy` values, for config validation and tool schemas. */
+export declare const GATE_POLICIES: readonly GatePolicy[];
 /**
  * Build the System-one request body: the task is the shared `state`, and each
  * candidate travels inside its own question's structured `instructions`, so
@@ -192,11 +228,12 @@ export declare function parseUsage(payload: unknown): GateUsage | undefined;
  * @param options - resolved gate settings.
  * @returns kept/dropped hash lists and per-candidate verdicts.
  */
-export declare function decide(candidates: readonly GateCandidate[], values: ReadonlyArray<number | undefined>, options: Pick<GateOptions, "mode" | "threshold" | "scoreMin" | "minKeep">): {
+export declare function decide(candidates: readonly GateCandidate[], values: ReadonlyArray<number | undefined>, options: Pick<GateOptions, "mode" | "threshold" | "scoreMin" | "minKeep" | "policy" | "maxDropFraction">): {
     kept: string[];
     dropped: string[];
     verdicts: GateVerdict[];
     floored: boolean;
+    bounded: boolean;
 };
 /**
  * Evaluate the gate for one search page.

package/lib/systemone.js

@@ -52,6 +52,8 @@ export const NOUL_CRITERIA = {
 };
 /** The judgement asked of the model in `score` mode. */
 export const SCORE_INSTRUCTION = "How relevant is the `candidate` memory record to the `task`? Rate how reusable its conclusions, decisions, constraints, or findings are for this exact task.";
+/** Accepted `policy` values, for config validation and tool schemas. */
+export const GATE_POLICIES = ["rerank", "filter"];
 /** Trim a candidate summary before it is sent to the model. */
 function clamp(text, limit) {
     const collapsed = text.replace(/\s+/g, " ").trim();
@@ -153,7 +155,29 @@ export function parseUsage(payload) {
  * @returns kept/dropped hash lists and per-candidate verdicts.
  */
 export function decide(candidates, values, options) {
+    // `decide` is the low-level primitive: with no explicit policy it applies the
+    // literal threshold semantics, and with no explicit bound it applies none. The
+    // product policy (rerank by default, 25 % drop cap) lives in the config layer,
+    // which passes both in explicitly — the same split as `minKeep`.
+    const policy = options.policy ?? "filter";
     const cutoff = options.mode === "noul" ? options.threshold : options.scoreMin;
+    if (policy === "rerank") {
+        // Reordering cannot lose a memory: report every judged candidate as kept and
+        // let `ordered` carry the ranking. The threshold verdict is still visible in
+        // each verdict's `value`.
+        const all = candidates.map((candidate, index) => ({
+            hash: candidate.hash,
+            value: values[index] ?? null,
+            keep: true
+        }));
+        return {
+            kept: candidates.map((c) => c.hash),
+            dropped: [],
+            verdicts: all,
+            floored: false,
+            bounded: false
+        };
+    }
     const verdicts = candidates.map((candidate, index) => {
         const value = values[index];
         if (value === undefined)
@@ -179,12 +203,40 @@ export function decide(candidates, values, options) {
         kept = verdicts.filter((v) => v.keep).map((v) => v.hash);
         floored = true;
     }
+    // Bound the damage: a threshold that rejects most of a page is far more
+    // likely to be mis-calibrated than the page is to be mostly irrelevant, and
+    // the cost of the two errors is not symmetric — a dropped memory is gone,
+    // a kept one only costs context. Restore the best-scoring rejects until the
+    // drop share is within `maxDropFraction`.
+    let bounded = false;
+    const maxDropFraction = options.maxDropFraction ?? 1;
+    if (candidates.length > 0 && maxDropFraction < 1) {
+        const allowedDrops = Math.max(0, Math.floor(candidates.length * Math.max(0, maxDropFraction)));
+        const dropCount = candidates.length - kept.length;
+        if (dropCount > allowedDrops) {
+            const restoreCount = dropCount - allowedDrops;
+            const rejects = verdicts
+                .map((verdict, index) => ({ verdict, index }))
+                .filter((entry) => !entry.verdict.keep)
+                .sort((a, b) => {
+                const av = a.verdict.value ?? Number.NEGATIVE_INFINITY;
+                const bv = b.verdict.value ?? Number.NEGATIVE_INFINITY;
+                return bv - av || a.index - b.index;
+            })
+                .slice(0, restoreCount);
+            for (const entry of rejects)
+                entry.verdict.keep = true;
+            kept = verdicts.filter((v) => v.keep).map((v) => v.hash);
+            bounded = true;
+        }
+    }
     const keptSet = new Set(kept);
     return {
         kept,
         dropped: candidates.map((c) => c.hash).filter((hash) => !keptSet.has(hash)),
         verdicts,
-        floored
+        floored,
+        bounded
     };
 }
 /** Combine a caller signal with a timeout, keeping both cancellation sources. */
@@ -206,12 +258,15 @@ function withTimeout(signal, timeoutMs) {
  */
 export async function evaluateGate(task, candidates, options, signal) {
     const mode = options.mode;
+    const policy = options.policy ?? "rerank";
     const base = {
         mode,
-        model: options.model
+        model: options.model,
+        policy,
+        bounded: false
     };
     if (candidates.length === 0) {
-        return { ...base, kept: [], dropped: [], verdicts: [], judged: 0, untouched: 0, degraded: false };
+        return { ...base, kept: [], dropped: [], verdicts: [], ordered: [], judged: 0, untouched: 0, degraded: false };
     }
     const judged = candidates.slice(0, Math.max(1, options.maxCandidates));
     const untouched = candidates.slice(judged.length);
@@ -220,6 +275,7 @@ export async function evaluateGate(task, candidates, options, signal) {
         kept: candidates.map((c) => c.hash),
         dropped: [],
         verdicts: candidates.map((c) => ({ hash: c.hash, value: null, keep: true })),
+        ordered: candidates.map((c) => c.hash),
         judged: judged.length,
         untouched: untouched.length,
         degraded: true,
@@ -260,24 +316,44 @@ export async function evaluateGate(task, candidates, options, signal) {
         return keepAll("system-one request failed: " + detail);
     }
     const values = parseAnswers(payload, mode, judged.length);
-    const decision = decide(judged, values, options);
+    const decision = decide(judged, values, { ...options, policy });
     // Candidates past `maxCandidates` were never evaluated, so they are never
     // removed: the gate may only drop what it actually judged. Leaving them out
     // of the kept set would silently truncate every page larger than the cap.
     const keptSet = new Set([...decision.kept, ...untouched.map((c) => c.hash)]);
+    const verdicts = [
+        ...decision.verdicts,
+        ...untouched.map((c) => ({ hash: c.hash, value: null, keep: true }))
+    ];
+    // Best value first; nulls (unjudged / unreadable) keep page order at the end.
+    const ordered = candidates
+        .map((candidate, index) => ({ candidate, index, value: verdicts[index]?.value ?? null }))
+        .sort((a, b) => {
+        if (a.value === b.value)
+            return a.index - b.index;
+        if (a.value === null)
+            return 1;
+        if (b.value === null)
+            return -1;
+        return b.value - a.value;
+    })
+        .map((entry) => entry.candidate.hash);
     const usage = parseUsage(payload);
     return {
         ...base,
+        ordered,
+        bounded: decision.bounded,
         kept: [...candidates.map((c) => c.hash).filter((hash) => keptSet.has(hash))],
         dropped: decision.dropped,
-        verdicts: [
-            ...decision.verdicts,
-            ...untouched.map((c) => ({ hash: c.hash, value: null, keep: true }))
-        ],
+        verdicts,
         judged: judged.length,
         untouched: untouched.length,
         degraded: false,
         ...(usage === undefined ? {} : { usage }),
-        ...(decision.floored ? { reason: "no candidate scored above the threshold; retained top " + decision.kept.length } : {})
+        ...(decision.floored
+            ? { reason: "no candidate scored above the threshold; retained top " + decision.kept.length }
+            : decision.bounded
+                ? { reason: "threshold would have dropped more than maxDropFraction; restored the best-scoring rejects" }
+                : {})
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fonlan/dsh-gitmemo",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Git-backed long-term memory for DeepSeek Harness: a local .mem git repo (single main branch, immutable entries, structured commit messages) with mem_search / mem_read / mem_write / mem_delete / mem_replace tools and fully automatic legacy migration (no CLI needed; the CLI remains for explicit control), auto-managed by the root agent with zero manual steps.",
   "author": "fonlan",
   "publishConfig": {
@@ -48,6 +48,10 @@
     "bundle": "tsdown",
     "watch": "tsdown --watch",
     "test": "npm run build && node --test",
+    "eval:lme": "node evals/longmemeval/run_retrieval.mjs",
+    "eval:lme:oracle": "node evals/longmemeval/run_retrieval.mjs --split oracle",
+    "eval:lme:s": "node --max-old-space-size=8192 evals/longmemeval/run_retrieval.mjs --split s --concurrency 8",
+    "eval:omni:setup": "node evals/omnimemeval/setup.mjs",
     "prepublishOnly": "npm run build",
     "release:patch": "npm version patch && git push && git push --tags",
     "release:minor": "npm version minor && git push && git push --tags",