@fonlan/dsh-gitmemo 0.4.1 → 0.5.1

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.