@fonlan/dsh-gitmemo 0.4.1 → 0.5.1

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 |
@@ -125,31 +184,21 @@ settings plane to see the entry and apply edits live.
 ### Settings page
 
 The plugin ships a settings card (**Settings → GitMemo**) where the gate can be
-switched on and off and the endpoint, model and API key can be filled in
-directly, applying immediately with no restart. The API key is written through
-the credentials domain — it is **never persisted as a plaintext config value** —
-and the form is write-only. The switch stages `systemOne.enabled`; turning it off
-leaves recall byte-for-byte as it was before the gate existed, and a **Save** is
-what writes it (the switch alone is a draft). An absent `enabled` reads as on, so
-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.
+switched on and off, its `policy` chosen between **Re-rank** and **Filter**, and
+`maxDropFraction`, the endpoint, the model and the API key filled in directly,
+applying immediately with no restart. The API key is written through the
+credentials domain — it is **never persisted as a plaintext config value** — and
+the form is write-only. Every control stages a draft and a **Save** is what
+writes it; turning the gate off leaves recall byte-for-byte as it was before the
+gate existed.
+
+Fields the section does not carry render the value `src/index.ts` declares rather
+than a blank control — an absent `enabled` reads as on, an absent `policy` reads
+as `rerank`, an absent `maxDropFraction` as `0.25` — because a blank control would
+misreport the configuration actually in force. A draft the field does not accept
+(for example a `maxDropFraction` outside 0–1) **blocks the save** instead of being
+silently dropped, and the settings card's defaults are asserted against the host
+schema by `test/form-specs.test.mjs` so the two cannot drift apart.
 
 ## Memory Location & Format
 
@@ -182,7 +231,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 +264,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 +300,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` | 请求超时 |
@@ -111,22 +140,15 @@ bundle patch 自带合理默认值，可在 profile 的 `cordis.patch.yml` 中
 
 ### 设置页
 
-插件自带一个设置卡片（**设置 → GitMemo**），可直接开关召回闸门，并填写端点、模型与 API key，
-改动即时生效、无需重启。API key 通过凭据域写入，**不会作为明文配置项落盘**，表单也只写不回显。
-开关暂存的是 `systemOne.enabled`：关闭后召回行为与门控存在前逐字节一致；需要点**保存**才会写入
-（只拨开关是草稿）。未配置 `enabled` 时按开启处理，与该字段的宿主默认值一致。
-
-### 已知取舍
+插件自带一个设置卡片（**设置 → GitMemo**），可直接开关召回闸门、在**重排**与**过滤**之间选择
+`policy`，并填写 `maxDropFraction`、端点、模型与 API key，保存后立即生效、无需重启。API key 通过凭据
+域写入——**绝不**以明文配置值落盘——且表单为只写。所有控件都只是暂存草稿，点**保存**才真正写入；
+关闭闸门后召回行为与门控存在前逐字节一致。
 
-- **英文优先。** 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，输出免费），不是按次计费。
+节里没有的字段会渲染成 `src/index.ts` 声明的默认值而不是空白控件——`enabled` 缺省即开启、`policy` 缺省
+即 `rerank`、`maxDropFraction` 缺省即 `0.25`——因为空白控件会误报当前实际生效的配置。字段不接受的值
+（例如超出 0–1 的 `maxDropFraction`）会**阻止保存**而不是被静默丢弃；卡片的默认值由
+`test/form-specs.test.mjs` 对着宿主 schema 断言，两者不会漂移。
 
 ## 记忆存放位置与格式
 
@@ -156,7 +178,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/client/form-specs.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The staged settings form's pure field vocabulary: how one section field
+ * converts between its stored value and the draft text the card renders.
+ *
+ * Deliberately a plain TypeScript module with no React, DOM or browser import:
+ * the card needs it and so do the unit tests, which cannot import the browser
+ * bundle. The host tsconfig compiles plain `.ts` files under `src`, so this is
+ * both inlined into the client bundle and emitted for the tests to import.
+ */
+import type { SettingsFieldWrite } from '@deepseek-ai/dsh-client-ui-primitives';
+/** The editable projection of this plugin's settings namespace. */
+export interface GitMemoSettings {
+    /** The System-one recall gate, as `src/index.ts` declares it. */
+    systemOne?: {
+        enabled?: boolean;
+        endpoint?: string;
+        model?: string;
+        apiKey?: string;
+        apiKeyEnv?: string;
+        mode?: 'noul' | 'score';
+        /** How the judge's values are used: order the page, or drop from it. */
+        policy?: 'rerank' | 'filter';
+        /** `filter` only: the share of a judged page that may be dropped. */
+        maxDropFraction?: number;
+        threshold?: number;
+        scoreMin?: number;
+        minKeep?: number;
+        maxCandidates?: number;
+        maxTaskChars?: number;
+        timeoutMs?: number;
+    };
+}
+/** How one section field converts between its stored value and its draft text. */
+export interface PathFieldSpec {
+    /** Key addressing this control inside the card's form. */
+    field: string;
+    /** Path inside the namespace section this control edits. */
+    path: readonly string[];
+    /** Render a stored value as draft text; the empty string when the section carries none. */
+    format: (value: unknown) => string;
+    /** The write this draft text stages, or undefined when the text is not a value this field accepts. */
+    parse: (text: string) => SettingsFieldWrite | undefined;
+}
+/**
+ * A free-text field. An empty draft clears the field, so emptying the control
+ * and saving is the same gesture as resetting it.
+ * @param field - key addressing this control inside the card's form.
+ * @param path - path of the field inside the namespace section.
+ * @returns the field's conversion spec.
+ */
+export declare function pathTextField(field: string, path: readonly string[]): PathFieldSpec;
+/**
+ * A whole-number field. An empty draft clears the field; any other draft that
+ * is not a finite number blocks the save.
+ * @param field - key addressing this control inside the card's form.
+ * @param path - path of the field inside the namespace section.
+ * @returns the field's conversion spec.
+ */
+export declare function pathNumberField(field: string, path: readonly string[]): PathFieldSpec;
+/**
+ * A boolean field, staged as the `'true'`/`'false'` draft the card's switch
+ * renders. An empty draft clears the field (re-inheriting the declared
+ * default); any other draft that is not one of those two words blocks the save.
+ * @param field - key addressing this control inside the card's form.
+ * @param path - path of the field inside the namespace section.
+ * @returns the field's conversion spec.
+ */
+export declare function pathBooleanField(field: string, path: readonly string[]): PathFieldSpec;
+/**
+ * A field restricted to a closed set of strings, rendered with the declared
+ * default when the section carries none. An empty draft clears the field; any
+ * other draft outside the set blocks the save rather than being dropped, so a
+ * typo can never silently reconfigure the gate.
+ * @param field - key addressing this control inside the card's form.
+ * @param path - path of the field inside the namespace section.
+ * @param allowed - the values the field accepts, in contract order.
+ * @param declaredDefault - the value `src/index.ts` declares, shown while absent.
+ * @returns the field's conversion spec.
+ */
+export declare function pathChoiceField(field: string, path: readonly string[], allowed: readonly string[], declaredDefault: string): PathFieldSpec;
+/**
+ * A numeric field bounded to a range, rendered with the declared default when
+ * the section carries none. The bound is enforced here, not by the control, so
+ * an out-of-range draft blocks the save instead of reaching the plane.
+ * @param field - key addressing this control inside the card's form.
+ * @param path - path of the field inside the namespace section.
+ * @param bounds - inclusive range, and the declared default shown while absent.
+ * @returns the field's conversion spec.
+ */
+export declare function pathBoundedNumberField(field: string, path: readonly string[], bounds: {
+    min: number;
+    max: number;
+    declaredDefault: string;
+}): PathFieldSpec;

package/lib/client/form-specs.js

@@ -0,0 +1,144 @@
+/**
+ * The staged settings form's pure field vocabulary: how one section field
+ * converts between its stored value and the draft text the card renders.
+ *
+ * Deliberately a plain TypeScript module with no React, DOM or browser import:
+ * the card needs it and so do the unit tests, which cannot import the browser
+ * bundle. The host tsconfig compiles plain `.ts` files under `src`, so this is
+ * both inlined into the client bundle and emitted for the tests to import.
+ */
+/**
+ * A free-text field. An empty draft clears the field, so emptying the control
+ * and saving is the same gesture as resetting it.
+ * @param field - key addressing this control inside the card's form.
+ * @param path - path of the field inside the namespace section.
+ * @returns the field's conversion spec.
+ */
+export function pathTextField(field, path) {
+    return {
+        field,
+        path,
+        format: (value) => (typeof value === 'string' ? value : ''),
+        parse: (text) => {
+            const trimmed = text.trim();
+            return trimmed === '' ? { kind: 'clear' } : { kind: 'set', value: trimmed };
+        }
+    };
+}
+/**
+ * A whole-number field. An empty draft clears the field; any other draft that
+ * is not a finite number blocks the save.
+ * @param field - key addressing this control inside the card's form.
+ * @param path - path of the field inside the namespace section.
+ * @returns the field's conversion spec.
+ */
+export function pathNumberField(field, path) {
+    return {
+        field,
+        path,
+        format: (value) => (typeof value === 'number' ? String(value) : ''),
+        parse: (text) => {
+            const trimmed = text.trim();
+            if (trimmed === '')
+                return { kind: 'clear' };
+            const parsed = Number(trimmed);
+            return Number.isFinite(parsed) ? { kind: 'set', value: parsed } : undefined;
+        }
+    };
+}
+/**
+ * Draft text a boolean field renders while the section carries no value.
+ *
+ * A missing boolean is not "unknown": `src/index.ts` declares
+ * `systemOne.enabled` with `default(true)` and reads it back through
+ * `liveValue(section.enabled, true)`, so an absent value means ENABLED. Rendering
+ * an absent boolean as the empty string would show a disabled switch for a gate
+ * that is actually running, so the draft is seeded with the declared default.
+ */
+const ABSENT_BOOLEAN_TEXT = 'true';
+/**
+ * A boolean field, staged as the `'true'`/`'false'` draft the card's switch
+ * renders. An empty draft clears the field (re-inheriting the declared
+ * default); any other draft that is not one of those two words blocks the save.
+ * @param field - key addressing this control inside the card's form.
+ * @param path - path of the field inside the namespace section.
+ * @returns the field's conversion spec.
+ */
+export function pathBooleanField(field, path) {
+    return {
+        field,
+        path,
+        format: (value) => (typeof value === 'boolean' ? String(value) : ABSENT_BOOLEAN_TEXT),
+        parse: (text) => {
+            const trimmed = text.trim();
+            if (trimmed === '')
+                return { kind: 'clear' };
+            if (trimmed === 'true')
+                return { kind: 'set', value: true };
+            if (trimmed === 'false')
+                return { kind: 'set', value: false };
+            return undefined;
+        }
+    };
+}
+/**
+ * Draft text for a field the section may not carry, given the default
+ * `src/index.ts` declares for it. A missing value is not "unknown": the schema
+ * declares one, so showing an empty control would misreport the running
+ * configuration — the same reasoning as {@link ABSENT_BOOLEAN_TEXT}.
+ */
+function declaredDefaultText(declaredDefault) {
+    return declaredDefault;
+}
+/**
+ * A field restricted to a closed set of strings, rendered with the declared
+ * default when the section carries none. An empty draft clears the field; any
+ * other draft outside the set blocks the save rather than being dropped, so a
+ * typo can never silently reconfigure the gate.
+ * @param field - key addressing this control inside the card's form.
+ * @param path - path of the field inside the namespace section.
+ * @param allowed - the values the field accepts, in contract order.
+ * @param declaredDefault - the value `src/index.ts` declares, shown while absent.
+ * @returns the field's conversion spec.
+ */
+export function pathChoiceField(field, path, allowed, declaredDefault) {
+    if (!allowed.includes(declaredDefault)) {
+        throw new Error(`dsh-gitmemo settings field ${field}: default ${declaredDefault} is not an accepted value`);
+    }
+    return {
+        field,
+        path,
+        format: (value) => (typeof value === 'string' && allowed.includes(value) ? value : declaredDefaultText(declaredDefault)),
+        parse: (text) => {
+            const trimmed = text.trim();
+            if (trimmed === '')
+                return { kind: 'clear' };
+            return allowed.includes(trimmed) ? { kind: 'set', value: trimmed } : undefined;
+        }
+    };
+}
+/**
+ * A numeric field bounded to a range, rendered with the declared default when
+ * the section carries none. The bound is enforced here, not by the control, so
+ * an out-of-range draft blocks the save instead of reaching the plane.
+ * @param field - key addressing this control inside the card's form.
+ * @param path - path of the field inside the namespace section.
+ * @param bounds - inclusive range, and the declared default shown while absent.
+ * @returns the field's conversion spec.
+ */
+export function pathBoundedNumberField(field, path, bounds) {
+    return {
+        field,
+        path,
+        format: (value) => (typeof value === 'number' ? String(value) : declaredDefaultText(bounds.declaredDefault)),
+        parse: (text) => {
+            const trimmed = text.trim();
+            if (trimmed === '')
+                return { kind: 'clear' };
+            const parsed = Number(trimmed);
+            if (!Number.isFinite(parsed))
+                return undefined;
+            return parsed >= bounds.min && parsed <= bounds.max ? { kind: 'set', value: parsed } : undefined;
+        }
+    };
+}