@fonlan/dsh-gitmemo 0.4.0 → 0.5.0

package/lib/index.js

@@ -23,6 +23,7 @@
 import z from "@deepseek-ai/schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import { GitMemo, GitMemoError, resolveProjectRoot } from "./mem.js";
+import { evaluateGate } from "./systemone.js";
 /** Cordis plugin name. */
 const name = "dsh-gitmemo";
 /** Host services this plugin needs. */
@@ -33,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. */
@@ -40,8 +56,181 @@ const Config = z.object({
     /** Cross-process lock wait timeout in milliseconds. Default 30000. */
     lockTimeoutMs: z.number().default(30000),
     /** Optional explicit project root; defaults to the calling session's cwd. */
-    projectRoot: z.string()
+    projectRoot: z.string(),
+    /**
+     * Optional System-one recall gate. When an endpoint and a credential are
+     * configured, each `mem_search` page is narrowed by a System-one model
+     * (TypeSafe Jev by default) before it reaches the model; when nothing is
+     * configured the gate is a no-op and recall behaves exactly as before.
+     *
+     * `.volatile()` is REQUIRED here, not cosmetic: the settings plane only
+     * exposes a field that sits on or under a volatile node (`volatileForm()`
+     * returns undefined otherwise, and `describe()` then skips this entry
+     * entirely while `write()` throws). Verified against
+     * `@deepseek-ai/dsh-settings`. Note that DSH 0.1.7-alpha.1 ships no client
+     * that auto-generates a page from the schema, so this plugin also ships its
+     * own settings card (see `src/client/`).
+     */
+    systemOne: z.object({
+        /** Master switch. Defaults to true; with no credential the gate stays a no-op. */
+        enabled: z.boolean().default(true).volatile(),
+        /** Endpoint accepting the System-one request contract. */
+        endpoint: z.string().default("https://api.typesafe.ai/v1/systemone").volatile(),
+        /** Model identifier sent in the request body. */
+        model: z.string().default("jev-latest").volatile(),
+        /** Literal API key. Declared secret: redacted on every read, write-only in the form. */
+        apiKey: z.string().role("secret").volatile(),
+        /** Credential reference resolved through the credentials service, then the environment. */
+        apiKeyEnv: z.string().role("credential-ref").default("TYPESAFE_API_KEY").volatile(),
+        /** Question type used to judge each candidate. */
+        mode: z.union(["noul", "score"]).default("noul").volatile(),
+        /** noul mode: keep a candidate when its probability is at least this value. */
+        threshold: z.number().min(0).max(1).default(0.5).volatile(),
+        /** score mode: keep a candidate when its score is at least this value.
+         * Jev's `score` is Σ(level_index × probability) over 0…levels−1, NOT 0–1;
+         * with the default 5 levels the range is 0…4, where 2 = "partially relevant". */
+        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. */
+        maxTaskChars: z.number().step(1).min(1).default(2000).volatile(),
+        /** End-to-end request deadline in milliseconds. */
+        timeoutMs: z.number().step(1).min(1).default(8000).volatile()
+    })
 });
+/**
+ * Read a config node that may be a plain value or a live (`.volatile()`) node.
+ *
+ * A plugin whose Config declares volatile fields receives a reactive config
+ * whose fields expose `get()`, while hand-written config objects and tests pass
+ * plain values. Both shapes are supported here so the same code path serves the
+ * settings page, `cordis.patch.yml`, and the unit tests.
+ */
+function liveValue(node, fallback) {
+    if (node === undefined || node === null)
+        return fallback;
+    const getter = node.get;
+    if (typeof getter === "function") {
+        const value = getter.call(node);
+        return value === undefined ? fallback : value;
+    }
+    return node;
+}
+/** Read the live `systemOne` section in whichever shape the loader supplied. */
+function systemOneSection(config) {
+    const section = liveValue(config?.systemOne, undefined);
+    return (section ?? {});
+}
+/** Project a (possibly reactive) `systemOne` section into plain settings. */
+function readSystemOne(config) {
+    const section = systemOneSection(config);
+    const mode = liveValue(section.mode, "noul");
+    return {
+        enabled: liveValue(section.enabled, true),
+        endpoint: liveValue(section.endpoint, "https://api.typesafe.ai/v1/systemone"),
+        model: liveValue(section.model, "jev-latest"),
+        mode: mode === "score" ? "score" : "noul",
+        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),
+        apiKey: liveValue(section.apiKey, undefined),
+        apiKeyEnv: liveValue(section.apiKeyEnv, "TYPESAFE_API_KEY")
+    };
+}
+/**
+ * Resolve the API key for the configured credential reference: a literal key
+ * from the settings page wins, then the harness credentials service, then the
+ * launching environment. Mirrors the shipped web-search provider's order.
+ */
+async function resolveApiKey(hostCtx, section) {
+    if (typeof section.apiKey === "string" && section.apiKey.length > 0)
+        return section.apiKey;
+    const ref = section.apiKeyEnv;
+    if (typeof ref !== "string" || ref.length === 0)
+        return undefined;
+    try {
+        const get = hostCtx?.get;
+        const credentials = typeof get === "function" ? get.call(hostCtx, "credentials") : undefined;
+        const resolve = credentials?.resolve;
+        if (typeof resolve === "function") {
+            const resolved = await resolve.call(credentials, ref);
+            if (resolved?.value !== undefined && resolved.value.length > 0)
+                return resolved.value;
+        }
+    }
+    catch {
+        // Credentials are optional: fall through to the environment.
+    }
+    const ambient = process.env[ref];
+    return ambient !== undefined && ambient.length > 0 ? ambient : undefined;
+}
+/** One text part's worth of content, whatever shape the message carries. */
+function messageText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return undefined;
+    const parts = content
+        .filter((part) => part?.type === "text")
+        .map((part) => part.text)
+        .filter((text) => typeof text === "string");
+    return parts.length > 0 ? parts.join("\n") : undefined;
+}
+/**
+ * The agent's current task: the most recent user message in the derived
+ * history. Without it the gate would judge candidates against bare keywords,
+ * which is exactly the weak signal the gate is meant to compensate for.
+ */
+function currentTask(exec) {
+    const session = exec?.agent?.session;
+    const derive = session?.deriveMessages;
+    if (typeof derive !== "function")
+        return undefined;
+    let messages;
+    try {
+        messages = derive.call(session);
+    }
+    catch {
+        return undefined;
+    }
+    if (!Array.isArray(messages))
+        return undefined;
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (message?.role !== "user")
+            continue;
+        const text = messageText(message.content);
+        if (text !== undefined && text.trim().length > 0)
+            return text.trim();
+    }
+    return undefined;
+}
 /** The calling agent's session workspace, when it has one. */
 function sessionCwd(exec) {
     return exec.agent?.session?.header?.cwd;
@@ -52,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);
 }
@@ -78,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",
@@ -111,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",
@@ -152,6 +351,33 @@ function formatSearchResults(value) {
     }
     if (value.results.length === 0)
         lines.push("(no matching memories)");
+    if (value.gated !== undefined) {
+        lines.push("gated: mode=" +
+            value.gated.mode +
+            " model=" +
+            value.gated.model +
+            " judged=" +
+            value.gated.judged +
+            // Only surfaced when the page exceeded maxCandidates, so the default
+            // line stays byte-identical to before this field existed.
+            (value.gated.untouched > 0 ? " untouched=" + value.gated.untouched : "") +
+            " kept=" +
+            value.gated.kept +
+            " dropped=" +
+            value.gated.dropped +
+            // A degraded gate explains itself; a floor (every candidate rejected,
+            // minKeep applied) must be just as visible — otherwise `kept=1` reads
+            // as "one candidate genuinely passed".
+            (value.gated.degraded
+                ? " DEGRADED(" + (value.gated.reason ?? "unknown") + ")"
+                : value.gated.reason === undefined
+                    ? ""
+                    : " NOTE(" + value.gated.reason + ")"));
+        if (value.gated.dropped_hashes.length > 0) {
+            lines.push("  dropped by the gate (mem_read one of these short hashes to recover it): " +
+                value.gated.dropped_hashes.join(","));
+        }
+    }
     if (value.warning !== undefined)
         lines.push("warning: " + value.warning);
     for (const diagnostic of value.diagnostics ?? [])
@@ -162,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.",
+        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)."
@@ -193,6 +419,47 @@ function registerMemTools(ctx, config) {
                         type: "array",
                         items: { type: "string" },
                         description: "Malformed commit/file mappings skipped during search."
+                    },
+                    gated: {
+                        type: "object",
+                        additionalProperties: false,
+                        description: "Present only when the System-one recall gate ran: how many candidates it judged (and how many past the cap it left untouched), how many it kept, the short hashes it dropped, and whether it had to fail open.",
+                        properties: {
+                            mode: { type: "string", required: true, description: "Question type used: noul or score." },
+                            model: { type: "string", required: true, description: "System-one model the request named." },
+                            candidates: { type: "number", required: true, description: "Size of the candidate page the gate was handed." },
+                            judged: {
+                                type: "number",
+                                required: true,
+                                description: "Candidates actually sent to the endpoint, i.e. min(maxCandidates, candidates)."
+                            },
+                            untouched: {
+                                type: "number",
+                                required: true,
+                                description: "Candidates past maxCandidates: never evaluated, therefore never dropped. Non-zero only on a page larger than the cap."
+                            },
+                            kept: { type: "number", required: true, description: "Candidates the gate retained." },
+                            dropped: { type: "number", required: true, description: "Candidates the gate removed." },
+                            degraded: {
+                                type: "boolean",
+                                required: true,
+                                description: "True when the gate failed open (endpoint/parse failure); every candidate was kept."
+                            },
+                            reason: {
+                                type: "string",
+                                description: "Why the gate degraded, or that it floored a wholly-rejected page (no candidate cleared the threshold, so minKeep were retained)."
+                            },
+                            input_tokens: {
+                                type: "number",
+                                description: "Input tokens the endpoint billed for the gate request (output tokens are free)."
+                            },
+                            dropped_hashes: {
+                                type: "array",
+                                required: true,
+                                items: { type: "string" },
+                                description: "8-char hashes of dropped candidates. Pass one to mem_read to recover a memory the gate judged irrelevant."
+                            }
+                        }
                     }
                 }
             },
@@ -201,11 +468,76 @@ function registerMemTools(ctx, config) {
         isConcurrencySafe: () => true,
         async execute(args, exec) {
             const memo = await engineFor(exec, config);
-            return await memo.search(args.keywords, {
+            const result = await memo.search(args.keywords, {
                 skip: args.skip ?? 0,
                 snapshot: args.snapshot,
                 mode: args.mode
             });
+            // System-one recall gate: purely subtractive, and only ever reached when
+            // an endpoint credential is configured. No credential => this returns the
+            // untouched engine result, so recall behaves exactly as it did before.
+            if (config.gateFor === undefined || result.results.length === 0)
+                return result;
+            const options = await config.gateFor();
+            if (options === undefined)
+                return result;
+            const task = currentTask(exec) ??
+                (Array.isArray(args.keywords) ? args.keywords.join(" ") : String(args.keywords));
+            const candidates = result.results.map((hit) => ({
+                hash: hit.hash,
+                title: hit.title,
+                summary: hit.summary,
+                keywords: hit.keywords,
+                kind: hit.kind
+            }));
+            const decision = await evaluateGate(task, candidates, options, exec?.signal);
+            // Per-candidate values go to the log (for threshold tuning) rather than
+            // into the model context, which is the very thing the gate is shrinking.
+            config.log?.("mem_search gate" +
+                (decision.degraded ? " DEGRADED" : "") +
+                " mode=" + decision.mode +
+                " model=" + decision.model +
+                " 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=" +
+                decision.verdicts
+                    .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: reranked,
+                gated: {
+                    policy: decision.policy,
+                    ...(decision.bounded ? { bounded: true } : {}),
+                    mode: decision.mode,
+                    model: decision.model,
+                    candidates: candidates.length,
+                    judged: decision.judged,
+                    untouched: decision.untouched,
+                    kept: decision.kept.length,
+                    dropped: decision.dropped.length,
+                    degraded: decision.degraded,
+                    ...(decision.reason === undefined ? {} : { reason: decision.reason }),
+                    ...(decision.usage?.inputTokens === undefined ? {} : { input_tokens: decision.usage.inputTokens }),
+                    dropped_hashes: decision.dropped.map((hash) => hash.slice(0, 8))
+                }
+            };
         },
         presentCall: (args) => ({
             card: "generic",
@@ -472,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 条目时建议展开。",
@@ -489,10 +821,45 @@ function registerPromptSection(ctx) {
  * registration time.
  */
 async function apply(ctx, config = {}) {
+    const log = (message) => {
+        if (typeof ctx.logger.info === "function")
+            ctx.logger.info(message);
+    };
     const resolved = {
         searchLimit: config.searchLimit ?? 20,
+        searchScoring: config.searchScoring ?? "weighted",
         lockTimeoutMs: config.lockTimeoutMs ?? 30000,
-        projectRoot: config.projectRoot
+        projectRoot: config.projectRoot,
+        log,
+        /**
+         * Resolved per search so settings-page edits take effect immediately.
+         * Returns undefined — leaving recall byte-for-byte unchanged — whenever the
+         * gate is switched off or has no usable credential.
+         */
+        gateFor: async () => {
+            const section = readSystemOne(config);
+            if (!section.enabled)
+                return undefined;
+            if (typeof section.endpoint !== "string" || section.endpoint.length === 0)
+                return undefined;
+            const apiKey = await resolveApiKey(ctx, section);
+            if (apiKey === undefined)
+                return undefined;
+            return {
+                endpoint: section.endpoint,
+                model: section.model,
+                mode: section.mode,
+                threshold: section.threshold,
+                scoreMin: section.scoreMin,
+                minKeep: section.minKeep,
+                policy: section.policy,
+                maxDropFraction: section.maxDropFraction,
+                maxCandidates: section.maxCandidates,
+                maxTaskChars: section.maxTaskChars,
+                timeoutMs: section.timeoutMs,
+                apiKey
+            };
+        }
     };
     if (config.branchAlign !== undefined && config.branchAlign !== true) {
         ctx.logger.warn("dsh-gitmemo: `branchAlign` is deprecated and has no effect — .mem always stays on main");

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.
      */