feiyu-memory 0.0.0-stage → 4.0.0

package/src/core/privacy.mjs

@@ -0,0 +1,252 @@
+/**
+ * 隐私层：落盘前的最后一道闸。
+ *
+ * 分三类，处理方式完全不同：
+ *
+ *  1. format —— 强确定性的可识别格式（手机号/证件/卡号/邮箱）
+ *     只要开了第三方泛化就一律处理。误伤概率极低。
+ *
+ *  2. secret —— 密钥。**硬阻断**，永远处理，没有开关。
+ *     命中即替换，绝不入档、绝不进日志。
+ *
+ *  3. name / amount —— 弱信号。**只认高置信标记**。
+ *     人名只认称谓（王总/李老师）、小X/老X、"叫X"三种明确写法；
+ *     金额只处理超过门槛的数（保住"3 块钱的包子"这种生活细节）。
+ *
+ * 设计原则：**宁可少泛化，不要过度泛化**。
+ * 糊成一团"某人和某人在某地发生了某事"的日记，既没有隐私价值也没有记忆价值，
+ * 用户会直接关掉这个功能 —— 那就等于没有隐私保护。
+ */
+
+/** 永远处理：密钥。命中的文本块直接丢弃。 */
+const SECRET_RULES = [
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, '私钥'],
+  [/\bsk-[A-Za-z0-9_-]{16,}\b/g, 'API Key'],
+  [/\bgh[pousr]_[A-Za-z0-9]{20,}\b/g, 'GitHub Token'],
+  [/\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, 'GitHub Token'],
+  [/\bAKIA[0-9A-Z]{16}\b/g, 'AWS Key'],
+  [/\bAIza[0-9A-Za-z_-]{35}\b/g, 'Google Key'],
+  [/\bxox[baprs]-[0-9A-Za-z-]{10,}\b/g, 'Slack Token'],
+  [/\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, 'JWT'],
+  [/\bBearer\s+[A-Za-z0-9._~+/-]{20,}=*/g, 'Bearer Token'],
+  [
+    /\b(?:pass(?:wo?r?d)?|pwd|secret|token|api[_-]?key|apikey|access[_-]?key|private[_-]?key)\b\s*(?::|=|\bis\b|是|为)\s*["']?[^\s"',;]{6,}["']?/gi,
+    '凭据',
+  ],
+  // ── 中文键名 ──
+  //
+  // 审计报告（F2，P2）：上面那条只认英文键名，而这是个中文插件 ——
+  // README 承诺"密码……被替换成 [已拦截]"，可是这些写法全都放行：
+  //
+  //   服务器 root 密码是 Zx9!kq2#Lm7$Pw
+  //   WiFi 密码：hunter2pass2026
+  //   数据库口令 Hunter2pass
+  //   阿里云 AccessKey Secret 是 wJalrXUtn...
+  //   my password is Hunter2pass
+  //
+  // 中文没有 \b 词边界，所以单独一条规则，分隔符接受 : ： = 是 为 is。
+  [/(?:密码|口令|密钥|秘钥|验证码)\s*(?::|：|=|是|为|\bis\b)?\s*["']?[^\s"',;，。]{6,}["']?/g, '凭据'],
+  // 只写冒号、没有连接词的那种（"密码：xxx" 上面已覆盖，这条兜 Union 场景）
+  [/(?:密码|口令|密钥|秘钥)\s*[:：]\s*\S{6,}/g, '凭据'],
+  // ── URL 里内嵌的凭据 ──
+  //
+  // postgres://admin:Hunter2pass@db.internal:5432/app
+  //
+  // 原来这条"碰巧"被邮箱规则吃掉了（Hunter2pass@db.internal 像个邮箱），
+  // 换个 scheme 或者密码里没 @ 就漏。单独成规则才稳。
+  [/\/\/[^\/\s:@]+:[^@\s/]{4,}@/g, '凭据'],
+  // ── 长数字 ──
+  //
+  // 社区报告（2026-10-24）：一串 13 位数字 `123456789012` 原样进了
+  // relationship.json 的 evidence 字段。手机号规则只认 11 位大陆号，
+  // 11 位以上的一律放行。
+  //
+  // **门槛是 12 位，不是 11** —— 11 位是手机号，那个由上面 `RULES` 里的手机号
+  // 而且用户明确表示过"露着吧"。11 位以上基本只有电话号码和身份证号。
+  [/\b\d{12,}\b/g, '长数字'],
+];
+
+const SECRET_PLACEHOLDER = '[已拦截]';
+
+/**
+ * @typedef {'format'|'name'|'amount'} RuleGroup
+ * @typedef {object} Rule
+ * @property {RegExp} re
+ * @property {string | ((...m: string[]) => string)} replace
+ * @property {string} label
+ * @property {RuleGroup} group
+ */
+
+/** @type {Rule[]} */
+const RULES = [
+  { group: 'format', label: '手机号', re: /(?<!\d)1[3-9]\d{9}(?!\d)/g, replace: '[手机号]' },
+  { group: 'format', label: '证件号', re: /(?<!\d)\d{17}[\dXx](?!\d)/g, replace: '[证件号]' },
+  { group: 'format', label: '卡号', re: /(?<!\d)\d{16,19}(?!\d)/g, replace: '[卡号]' },
+  {
+    group: 'format',
+    label: '邮箱',
+    re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+    replace: '[邮箱]',
+  },
+
+  // 称谓式人名：姓氏表 + 称谓。高置信，误伤极小。
+  {
+    group: 'name',
+    label: '称谓式人名',
+    re: /[\u5f20\u738b\u674e\u8d75\u5218\u9648\u6768\u9ec4\u5468\u5434\u5f90\u5b59\u9a6c\u6731\u80e1\u6797\u90ed\u4f55\u9ad8\u7f57\u90d1\u6881\u8c22\u5b8b\u5510\u8bb8\u97e9\u51af\u9093\u66f9\u5f6d\u66fe\u8096\u7530\u8463\u6f58\u8881\u8521\u848b\u4f59\u4e8e\u675c\u53f6\u7a0b\u82cf\u9b4f\u5415\u4e01\u4efb\u6c88\u59da\u5362\u59dc\u5d14\u949f\u8c2d\u9646\u6c6a\u8303\u91d1\u77f3\u5ed6\u8d3e\u590f\u97e6\u4ed8\u65b9\u767d\u90b9\u5b5f\u718a\u79e6\u90b1\u6c5f\u5c39\u859b\u95eb\u6bb5\u96f7\u4faf\u9f99\u53f2\u9676\u9ece\u8d3a\u987e\u6bdb\u90dd\u9f9a\u90b5\u4e07\u94b1\u4e25\u8983\u6b66\u6234\u83ab\u5b54\u5411\u6c64][\u603b\u8001\u5e08\u533b\u751f\u7ecf\u7406\u4e3b\u4efb\u54e5\u59d0\u53d4\u59e8\u5de5]/g,
+    replace: '[某人]',
+  },
+  // 小X / 老X
+  {
+    group: 'name',
+    label: '小X/老X',
+    re: /[\u5c0f\u8001][\u5f20\u738b\u674e\u8d75\u5218\u9648\u6768\u9ec4\u5468\u5434\u5f90\u5b59\u9a6c\u6731\u80e1\u6797\u90ed\u4f55\u9ad8\u7f57\u90d1\u6881\u8c22\u5b8b\u5510\u8bb8\u97e9\u51af\u9093\u66f9]/g,
+    replace: '[某人]',
+  },
+  // 明确引入的名字："叫X" / "名叫X" / "名字是X"
+  {
+    group: 'name',
+    label: '明确指名的名字',
+    re: /(叫|名叫|名字是)([\u4e00-\u9fa5]{2,4})(?=[\s\uff0c\u3002\uff01\uff1f,]|$)/g,
+    replace: (_m, lead) => `${lead}[某人]`,
+  },
+];
+
+/** 金额门槛：低于此值的金额不动 */
+export const DEFAULT_AMOUNT_THRESHOLD = 100;
+
+/** 带单位的金额（元/块/万/亿…），要读数字，所以单独处理 */
+const AMOUNT_UNIT_RE = /(?<![\d.])(\d[\d,]*(?:\.\d+)?)\s*(万元|万块|亿元|万|亿|元|块钱|块)(?![\d])/g;
+/** 带币种符号的金额 */
+const AMOUNT_SYMBOL_RE = /(?:¥|￥|\$)\s?(\d[\d,]*(?:\.\d+)?)/g;
+
+/**
+ * @typedef {object} PrivacyOptions
+ * @property {boolean} [thirdParty]      总开关：泛化第三方信息（默认 true）
+ * @property {boolean} [redactNames]     处理人名的弱信号规则（默认随 thirdParty）
+ * @property {boolean} [amounts]         泛化大额金额（默认随 thirdParty）
+ * @property {number}  [amountThreshold] 金额门槛（默认 100）
+ */
+
+/**
+ * 清洗一段文本。幂等 —— 占位符不会再次命中规则，重复调用结果稳定。
+ *
+ * @param {string} text
+ * @param {PrivacyOptions} [options]
+ * @returns {{text: string, hits: Array<{kind: string, label: string, count: number}>, blocked: boolean}}
+ */
+export function scrub(text, options = {}) {
+  if (typeof text !== 'string' || text.length === 0) {
+    return { text: typeof text === 'string' ? text : '', hits: [], blocked: false };
+  }
+
+  const thirdParty = options.thirdParty !== false;
+  const redactNames = options.redactNames !== false && thirdParty;
+  const doAmounts = options.amounts !== false && thirdParty;
+  const threshold = Number.isFinite(options.amountThreshold)
+    ? options.amountThreshold
+    : DEFAULT_AMOUNT_THRESHOLD;
+
+  const tally = new Map();
+  const bump = (kind, label, n = 1) => {
+    const key = `${kind}\u0000${label}`;
+    const cur = tally.get(key) ?? { kind, label, count: 0 };
+    cur.count += n;
+    tally.set(key, cur);
+  };
+
+  let out = text;
+
+  // 1) 密钥先做，且无条件做。后面任何一步出错，密钥都已经没了。
+  let blocked = false;
+  for (const [re, label] of SECRET_RULES) {
+    if (!re.test(out)) continue;
+    re.lastIndex = 0;
+    out = out.replace(re, () => {
+      blocked = true;
+      bump('secret', label);
+      return SECRET_PLACEHOLDER;
+    });
+  }
+
+  // 2) 格式类 / 人名类
+  if (thirdParty) {
+    for (const rule of RULES) {
+      if (rule.group === 'name' && !redactNames) continue;
+      out = out.replace(rule.re, (...args) => {
+        bump('thirdParty', rule.label);
+        return typeof rule.replace === 'function' ? rule.replace(...args) : rule.replace;
+      });
+    }
+  }
+
+  // 3) 金额（带门槛）
+  if (doAmounts) {
+    const overThreshold = (digits) => {
+      const v = Number(String(digits).replace(/,/g, ''));
+      return Number.isFinite(v) && v >= threshold;
+    };
+    out = out.replace(AMOUNT_UNIT_RE, (match, digits) => {
+      if (!overThreshold(digits)) return match;
+      bump('thirdParty', '金额');
+      return '一笔钱';
+    });
+    out = out.replace(AMOUNT_SYMBOL_RE, (match, digits) => {
+      if (!overThreshold(digits)) return match;
+      bump('thirdParty', '金额');
+      return '一笔钱';
+    });
+  }
+
+  return { text: out, hits: [...tally.values()], blocked };
+}
+
+/**
+ * 批量清洗，合并命中统计。
+ * @param {string[]} texts
+ * @param {PrivacyOptions} [options]
+ */
+export function scrubAll(texts, options = {}) {
+  const merged = new Map();
+  let blocked = false;
+  const out = texts.map((t) => {
+    const r = scrub(t, options);
+    blocked ||= r.blocked;
+    for (const h of r.hits) {
+      const key = `${h.kind}\u0000${h.label}`;
+      const cur = merged.get(key) ?? { kind: h.kind, label: h.label, count: 0 };
+      cur.count += h.count;
+      merged.set(key, cur);
+    }
+    return r.text;
+  });
+  return { texts: out, hits: [...merged.values()], blocked };
+}
+
+/**
+ * 给用户看的一句提示。刻意短，不弹窗、不说教 —— 像鱼，不像系统。
+ * @param {Array<{kind: string, label: string, count: number}>} hits
+ * @returns {string} 无命中时返回空串
+ */
+export function noticeFor(hits) {
+  if (!hits || hits.length === 0) return '';
+  const sum = (kind) =>
+    hits.filter((h) => (kind === 'secret' ? h.kind === 'secret' : h.kind !== 'secret'))
+      .reduce((s, h) => s + h.count, 0);
+  const parts = [];
+  const secrets = sum('secret');
+  const others = sum('other');
+  if (secrets > 0) parts.push(`拦下 ${secrets} 处密钥`);
+  if (others > 0) parts.push(`模糊了 ${others} 处别人家的信息`);
+  return parts.length > 0 ? parts.join('，') + '。' : '';
+}
+
+/**
+ * 预设：给"我就想让它记住我女朋友名字"的用户。
+ * 注意密钥与格式类仍然生效 —— 那两类没有关闭的理由。
+ */
+export const PRESET_REMEMBER_NAMES = Object.freeze({
+  thirdParty: true,
+  redactNames: false,
+  amounts: false,
+});

package/src/core/recall.mjs

@@ -0,0 +1,384 @@
+/**
+ * 记忆召回 —— 完全本地、零模型 token。
+ *
+ * 为什么不用 SQLite / 向量库：
+ *  - 向量库要下载模型 + 占几百 MB，还得开 GPU 之外的线程池，与"轻到不像插件"背道而驰
+ *  - SQLite 要么引原生依赖（插件装不上），要么赌运行时有 `node:sqlite`
+ *  - 倒排索引对我们这个量级（十年日记 ≈ 几千条）是**毫秒级**的，
+ *    而且索引是纯派生的 —— 每次加载重建，不需要存盘，文件坏了也不影响档案本体
+ *
+ * 打分 = a·文本相似度 + b·salience + c·新鲜度 − d·最近刚提过的惩罚
+ *
+ * 分流刻意保留随机性：人本来就是"联想到什么说什么"，
+ * 每次都精准翻出最相关的那条，是数据库，不是鱼。
+ */
+
+import { tokenize } from './keywords.mjs';
+
+/** IDF 平滑，避免 df=0 时除零 */
+const IDF_SMOOTH = 1;
+
+/**
+ * 建倒排索引。纯派生数据，随用随建。
+ *
+ * ── 2026-10-28：索引的数据源从「keywords + 正文」换成 **summary** ──
+ *
+ * 原来一条日记存两份提炼：`keywords`（12 个词，机器从正文切的）和
+ * `summary`（一句，模型写的）。倒排索引吃前者，大保底（recall）吃后者。
+ *
+ * 而 summary 本来就比 keywords 更适合字面匹配 ——
+ * 它带别名（「边缘行者2 / 续集 / 那部动画」），keywords 只取正文里出现过的词。
+ * 一份数据喂两个地方，另一份就是纯多余的。
+ *
+ * 所以现在：**一条日记只有一个"检索表示"。**
+ *   小保底（每轮自动注入）  字面匹配 summary —— 便宜
+ *   大保底（她主动查）      模型读 summary   —— 准
+ *
+ * 没有 summary 的用正文兜底（老条目在回填完之前就是这样）。
+ *
+ * @param {Array<{id: string, summary?: string, text?: string}>} entries
+ * @returns {{postings: Map<string, Map<string, number>>, df: Map<string, number>, lengths: Map<string, number>, N: number}}
+ */
+export function buildIndex(entries) {
+  const postings = new Map();
+  const df = new Map();
+  const lengths = new Map();
+  const list = Array.isArray(entries) ? entries : [];
+
+  for (const entry of list) {
+    const hasSummary = typeof entry.summary === 'string' && entry.summary !== '';
+    const tokens = tokenize(hasSummary ? entry.summary : (entry.text ?? ''));
+    if (tokens.length === 0) continue;
+
+    const tf = new Map();
+    for (const t of tokens) tf.set(t, (tf.get(t) ?? 0) + 1);
+
+    for (const [t, n] of tf) {
+      let bucket = postings.get(t);
+      if (bucket === undefined) {
+        bucket = new Map();
+        postings.set(t, bucket);
+      }
+      bucket.set(entry.id, n);
+      df.set(t, (df.get(t) ?? 0) + 1);
+    }
+    lengths.set(entry.id, tokens.length);
+  }
+
+  return { postings, df, lengths, N: lengths.size };
+}
+
+/**
+ * BM25-lite 检索，分数映射到 0~1（便于设阈值）。
+ *
+ * 归一化方式经过一次返工：最初用"命中证据 / 查询全部 token 的 idf 之和"，
+ * 结果**永远匹配不上** —— 中文 bigram 会产生大量噪声 token（"序算""法还"），
+ * 它们把分母顶得很大，一条明显相关的日记只能拿到 0.10 分。
+ *
+ * 现在改用**饱和函数**：只看命中了多少有区分度的证据，与查询长度解耦。
+ *
+ *     sim = 1 − exp(−Σgain / saturation)
+ *
+ * 好处：分数含义稳定 —— 命中 1 个实词约 0.4，命中 2 个约 0.67，完全无关是 0。
+ * 阈值因此可以说人话，也不会因为用户多打几个字就掉到阈值以下。
+ *
+ * @param {ReturnType<typeof buildIndex>} index
+ * @param {string} query
+ * @param {{limit?: number, saturation?: number}} [options]
+ * @returns {Map<string, number>} id → 相似度 0~1（未命中的条目不会出现在 map 里）
+ */
+
+/**
+ * 虚词 / 语气词 / 高频代词的单字表。
+ *
+ * **只用来判断"这句话是不是压根没内容"，不用来做分词。**
+ * 一个字都不在这张表里，这句话就算有实词。
+ *
+ * 「好」「哈」也在里面 —— 它们单看是实词，但夹在「你好」「哈哈」这种两字里
+ * 就是纯寒暄。宁可漏判（多翻一次记忆），也别把「你上次说的那个公园」挡掉：
+ * **这张表只影响"整句全是这些字"的情况**。
+ */
+const FILLER_CHARS = new Set(
+  '的了吗呢啊吧呀哦嗯么嘛唉诶哟哇啦咯喽呗呐嗨好哈呵嘿嘻是了在有我你他她它您这那哪个就都也还又很太不要能会可说对于把被给让跟和与或但而所以如果因然后先再才刚正啥什怎样多少点些一儿'.split(
+    '',
+  ),
+);
+
+/**
+ * 这句话有没有内容？没内容就别去翻记忆。
+ *
+ * ── 为什么要有这道门 ──
+ *
+ * 「嗯」「好」「在吗」「然后呢」这种话，字面上什么实词都没有 ——
+ * 拿它去检索，最好的情况是**空手而归白跑一趟**，最坏的情况是
+ * 命中一堆"他今天说了嗯"之类的噪声，然后被当成"突然想起来"塞进注入。
+ *
+ * 所以：**没内容的话，这一轮不翻记忆。**
+ *
+ * 注意这道门**只管自动召回**（`renderFor` 里那一栏）——
+ * 不管 `feiyu_recall` 工具。工具是它自己发起去查的，那是它要的，不该拦。
+ *
+ * 判据很土但够用：去掉标点空白后，**至少有一个字不在这张虚词表里**。
+ * 不做模型判断 —— 这一层要是花一次模型调用，就为了判断"嗯"要不要查，
+ * 那比它省下来的还贵。
+ *
+ * @param {unknown} query 用户这一轮说的话
+ * @returns {boolean} true = 有内容，可以翻记忆
+ */
+export function queryHasSubstance(query) {
+  // 只认字符串。`String({})` 会变成 "[object Object]"，那里面当然"有实词"——
+  // 这种输入本来就该当成没内容，不是当成有话要说。
+  if (typeof query !== 'string') return false;
+  const s = query.replace(/[\s\p{P}\p{S}]/gu, '');
+  if (s.length < 2) return false;
+  for (const ch of s) if (!FILLER_CHARS.has(ch)) return true;
+  return false;
+}
+
+/**
+ * 「这一轮像不像在干活」的本地信号。
+ *
+ * 每一条都是**具体形状**，不是"技术话题"这种模糊判断 —— 宁可判成干活
+ * （干活时不打扰），也别在人家正查报错的时候突然插一句旧事。
+ */
+const WORK_SIGNALS = [
+  /```/, // 代码块
+  /`[^`\n]{2,}`/, // 行内代码
+  /\b[\w.-]+\.(?:mjs|js|ts|tsx|jsx|json|yml|yaml|md|py|sh|ps1|cmd|exe|toml)\b/i, // 文件名
+  /[A-Za-z]:[\\/]/, // Windows 绝对路径
+  /(?:^|\s)\/(?:home|usr|tmp|var|opt|etc)\//, // POSIX 绝对路径
+  /\b(?:npm|pnpm|npx|node|git|dsh|yarn|bun)\s+\S+/, // 命令行
+  /\b(?:err|error|exception|stack|traceback|segfault|epipe|eacces)\b/i, // 报错
+  /报错|错误|异常|崩溃|编译|打包|装不上|跑不起来|不生效|报了个|栈溢出/,
+  /\bv?\d+\.\d+\.\d+\b/, // 版本号
+  /\b[A-Za-z_$][\w$]*\(\)/, // 函数调用
+];
+
+/**
+ * 这一轮像不像在工作。**给"要不要自动翻记忆"用，不是给内容分类用。**
+ *
+ * 判据是**形状**：有代码块、有路径、有命令、有报错、有版本号、有函数调用 ——
+ * 命中任何一条就算干活。
+ *
+ * 故意偏保守（宁可判成干活）：工作时不打扰只是少一条旧事，
+ * 而在他正查报错时插一句"前两天你说过……"是实打实的讨厌。
+ *
+ * 注意：**这只挡自动那一栏，不挡 `feiyu_recall` 工具** ——
+ * 干活时真需要旧事，它自己会去查。
+ *
+ * @param {unknown} text 用户这一轮说的话
+ * @returns {boolean} true = 像在干活
+ */
+export function looksLikeWork(text) {
+  if (typeof text !== 'string' || text === '') return false;
+  return WORK_SIGNALS.some((re) => re.test(text));
+}
+
+/**
+ * BM25-lite 检索，分数映射到 0~1（便于设阈值）。
+ *
+ * @param {ReturnType<typeof buildIndex>} index
+ * @param {string} query
+ * @param {{limit?: number, saturation?: number}} [options]
+ * @returns {Map<string, number>} id → 相似度 0~1（未命中的条目不会出现在 map 里）
+ */
+export function searchScores(index, query, options = {}) {
+  const limit = options.limit ?? 50;
+  const saturation = Number.isFinite(options.saturation) && options.saturation > 0
+    ? options.saturation
+    : 2;
+  const scores = new Map();
+  if (index.N === 0) return scores;
+
+  // 查询侧去重：bigram 噪声里重复 token 不该重复计分
+  const qTokens = [...new Set(tokenize(query))];
+  if (qTokens.length === 0) return scores;
+
+  const idf = (t) => Math.log(1 + (index.N + IDF_SMOOTH) / ((index.df.get(t) ?? 0) + IDF_SMOOTH));
+
+  const k1 = 1.2;
+  const b = 0.75;
+  const avgLen =
+    [...index.lengths.values()].reduce((s, n) => s + n, 0) / Math.max(1, index.lengths.size);
+
+  const raw = new Map();
+  for (const t of qTokens) {
+    const bucket = index.postings.get(t);
+    if (bucket === undefined) continue;
+    const w = idf(t);
+    for (const [id, tf] of bucket) {
+      const len = index.lengths.get(id) ?? avgLen;
+      const norm = 1 - b + (b * len) / Math.max(1, avgLen);
+      const gain = (w * (tf * (k1 + 1))) / (tf + k1 * norm);
+      raw.set(id, (raw.get(id) ?? 0) + gain);
+    }
+  }
+
+  for (const [id, r] of raw) scores.set(id, Math.min(1, 1 - Math.exp(-r / saturation)));
+
+  if (scores.size > limit) {
+    const kept = [...scores.entries()].sort((a, b2) => b2[1] - a[1]).slice(0, limit);
+    return new Map(kept);
+  }
+  return scores;
+}
+
+/** 新鲜度：指数衰减 */
+function recencyFactor(createdAt, now, halfLifeDays) {
+  if (!Number.isFinite(createdAt)) return 0.5;
+  const ageDays = Math.max(0, (now - createdAt) / 86400000);
+  return Math.pow(0.5, ageDays / Math.max(0.5, halfLifeDays));
+}
+
+/**
+ * @typedef {object} RecallOptions
+ * @property {number} [highSim]        高相似必触发（默认 0.5 ≈ 共享 2 个以上实词）
+ * @property {number} [midSim]         中相似进随机池（默认 0.25 ≈ 共享 1 个实词）
+ * @property {number} [minSalience]    进入随机池的最低 salience（默认 0.5）
+ * @property {number} [saturation]     相似度饱和尺度（默认 2）
+ * @property {number} [a]              相似度权重（默认 1）
+ * @property {number} [b]              salience 权重（默认 0.45）
+ * @property {number} [c]              新鲜度权重（默认 0.2）
+ * @property {number} [d]              最近刚提过的惩罚（默认 0.8）
+ * @property {number} [temperature]    softmax 温度（默认 0.15）
+ * @property {number} [cooldownTurns]  同一条的冷却轮数（默认 20）
+ * @property {number} [maxShow]        每轮最多露几条（默认 1）
+ * @property {number} [wanderChance]   没有强匹配时"走神"随机想起一条的概率（默认 0.08）
+ * @property {number} [halfLifeDays]   新鲜度半衰期（默认 45）
+ * @property {number} [now]            当前时间戳
+ * @property {() => number} [rng]      注入随机源（测试用）
+ */
+
+export const DEFAULT_RECALL_OPTIONS = Object.freeze({
+  highSim: 0.5,
+  midSim: 0.25,
+  minSalience: 0.5,
+  saturation: 2,
+  a: 1,
+  b: 0.45,
+  c: 0.2,
+  d: 0.8,
+  temperature: 0.15,
+  cooldownTurns: 20,
+  maxShow: 1,
+  wanderChance: 0.08,
+  halfLifeDays: 45,
+});
+
+/**
+ * @typedef {object} RecallState
+ * @property {Map<string, number>} [lastShownTurn]  条目 → 上次露出的轮次
+ */
+
+/**
+ * 挑出这一轮要提起的记忆。
+ *
+ * @param {Array<object>} entries 全部日记条目
+ * @param {ReturnType<typeof buildIndex>} index
+ * @param {string} query 本轮用户消息
+ * @param {RecallState} state
+ * @param {number} turn 当前轮次
+ * @param {RecallOptions} [options]
+ * @returns {{chosen: Array<{entry: object, score: number, sim: number, why: string}>, considered: number}}
+ */
+export function selectMemories(entries, index, query, state, turn, options = {}) {
+  const opts = { ...DEFAULT_RECALL_OPTIONS, ...options };
+  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+  const rng = typeof opts.rng === 'function' ? opts.rng : Math.random;
+  const lastShownTurn = state?.lastShownTurn ?? new Map();
+
+  const sims = searchScores(index, query, { saturation: opts.saturation });
+  /** @type {Array<{entry: object, score: number, sim: number, why: string}>} */
+  const scored = [];
+
+  for (const entry of entries) {
+    const sim = sims.get(entry.id) ?? 0;
+    const salience = Number.isFinite(entry.salience) ? entry.salience : 0.5;
+
+    // 冷却：刚提过就别再提
+    const last = lastShownTurn.get(entry.id);
+    if (Number.isFinite(last) && turn - last < opts.cooldownTurns) continue;
+
+    const fresh = recencyFactor(entry.created_at, now, opts.halfLifeDays);
+    const score =
+      opts.a * sim + opts.b * salience + opts.c * fresh - (Number.isFinite(last) ? opts.d : 0);
+
+    if (sim < opts.midSim && salience < opts.minSalience) continue;
+    scored.push({ entry, score, sim, why: '' });
+  }
+
+  // 未解决的失败记忆：稍微加权，因为它们最该被主动提起
+  const addWhy = (c, reason) => {
+    c.why = c.why ? `${c.why} + ${reason}` : reason;
+  };
+  for (const c of scored) {
+    if (c.entry.kind === 'failure' && c.entry.resolved !== true) {
+      c.score += 0.15;
+      addWhy(c, '未解决');
+    }
+  }
+
+  scored.sort((x, y) => y.score - x.score);
+
+  const strong = scored.filter((c) => c.sim >= opts.highSim);
+  const chosen = [];
+
+  // 1) 强匹配：必触发
+  for (const c of strong.slice(0, opts.maxShow)) {
+    addWhy(c, '强匹配');
+    chosen.push(c);
+  }
+
+  // 2) 还不够，且允许走神：从中等候选里按 softmax 随机抽
+  if (chosen.length < opts.maxShow) {
+    const pool = scored.filter(
+      (c) => !chosen.includes(c) && c.sim >= opts.midSim && (c.entry.salience ?? 0) >= opts.minSalience,
+    );
+    if (pool.length > 0) {
+      const picked = softmaxPick(pool, opts.temperature, rng);
+      if (picked !== undefined) {
+        addWhy(picked, '想起来一点');
+        chosen.push(picked);
+      }
+    }
+  }
+
+  // 3) 走神：完全没匹配上时，小概率随机想起一条旧事。这条纯粹为了像人。
+  if (chosen.length === 0 && rng() < opts.wanderChance) {
+    const pool = scored.filter((c) => (c.entry.salience ?? 0) >= opts.minSalience);
+    if (pool.length > 0) {
+      const picked = pool[Math.floor(rng() * pool.length)];
+      addWhy(picked, '走神想起来的');
+      chosen.push(picked);
+    }
+  }
+
+  // 记下露出时间，供冷却使用
+  for (const c of chosen) lastShownTurn.set(c.entry.id, turn);
+
+  return { chosen, considered: scored.length };
+}
+
+/**
+ * 按 softmax 概率抽一个。温度越低越接近"取最高分"。
+ * @template T
+ * @param {T[]} items 必须已按 score 降序，且每项有 .score
+ * @param {number} temperature
+ * @param {() => number} rng
+ * @returns {T | undefined}
+ */
+export function softmaxPick(items, temperature, rng) {
+  if (items.length === 0) return undefined;
+  if (items.length === 1) return items[0];
+  const t = Math.max(1e-6, temperature);
+  const max = items[0].score;
+  const exps = items.map((it) => Math.exp((it.score - max) / t));
+  const sum = exps.reduce((s, e) => s + e, 0);
+  if (!(sum > 0)) return items[0];
+  let r = rng() * sum;
+  for (let i = 0; i < items.length; i++) {
+    r -= exps[i];
+    if (r <= 0) return items[i];
+  }
+  return items[items.length - 1];
+}