@scotthuang/engram 0.1.0

package/src/__tests__/bm25.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from "vitest";
+import { BM25Index } from "../bm25.js";
+
+describe("BM25Index", () => {
+  describe("tokenize (via search)", () => {
+    const index = new BM25Index();
+
+    it("finds Chinese bigram matches", () => {
+      index.addEntry({ text: "在体育西吃了潮汕牛肉火锅", date: "2026-03-15", category: "饮食", filePath: "/test" });
+      index.addEntry({ text: "讨论了记忆系统方案", date: "2026-03-15", category: "技术", filePath: "/test" });
+
+      const results = index.search("牛肉火锅", 2);
+      expect(results).toHaveLength(1);
+      expect(results[0].entry.category).toBe("饮食");
+    });
+
+    it("finds English word matches", () => {
+      index.addEntry({ text: "installed node modules successfully", date: "2026-03-15", category: "技术", filePath: "/test" });
+      index.addEntry({ text: "天气很好适合出门", date: "2026-03-15", category: "随聊", filePath: "/test" });
+
+      const results = index.search("node modules", 2);
+      expect(results).toHaveLength(1);
+      expect(results[0].entry.category).toBe("技术");
+    });
+
+    it("returns empty for no matches", () => {
+      index.addEntry({ text: "今天天气很好", date: "2026-03-15", category: "随聊", filePath: "/test" });
+
+      const results = index.search("量子力学", 3);
+      expect(results).toHaveLength(0);
+    });
+  });
+
+  describe("search", () => {
+    it("returns results sorted by score", () => {
+      const index = new BM25Index();
+      index.addEntry({ text: "牛肉火锅牛肉火锅牛肉火锅", date: "2026-03-15", category: "饮食", filePath: "/test" });
+      index.addEntry({ text: "吃过一次牛肉火锅", date: "2026-03-15", category: "饮食", filePath: "/test" });
+      index.addEntry({ text: "今天去跑步了", date: "2026-03-15", category: "健康", filePath: "/test" });
+
+      const results = index.search("牛肉火锅", 3);
+      expect(results.length).toBeGreaterThanOrEqual(2);
+      // 更高频率的应排在前面
+      expect(results[0].score).toBeGreaterThanOrEqual(results[1].score);
+    });
+
+    it("respects topK limit", () => {
+      const index = new BM25Index();
+      for (let i = 0; i < 10; i++) {
+        index.addEntry({ text: `测试条目${i} 包含关键词`, date: "2026-03-15", category: "测试", filePath: "/test" });
+      }
+
+      const results = index.search("关键词", 3);
+      expect(results.length).toBeLessThanOrEqual(3);
+    });
+  });
+
+  describe("addEntry", () => {
+    it("updates index size", () => {
+      const index = new BM25Index();
+      expect(index.size).toBe(0);
+
+      index.addEntry({ text: "test entry", date: "2026-03-15", category: "测试", filePath: "/test" });
+      expect(index.size).toBe(1);
+
+      index.addEntry({ text: "another entry", date: "2026-03-15", category: "测试", filePath: "/test" });
+      expect(index.size).toBe(2);
+    });
+  });
+
+  describe("parseEntries", () => {
+    it("parses structured format correctly", async () => {
+      const index = new BM25Index();
+      // buildFromDirectory 会调用 parseEntries
+      // 直接测试 search 验证解析结果
+      const mockContent = `# 2026-03-15
+
+### 19:30 [饮食]
+在体育西吃了潮汕牛肉火锅，胸口捞很好吃
+
+### 14:00 [技术]
+讨论了记忆系统方案，确定三层架构
+
+### 10:00 [随聊]
+聊了股票
+`;
+      // 使用 addEntry 模拟解析后的结果
+      index.addEntry({ text: "在体育西吃了潮汕牛肉火锅，胸口捞很好吃", date: "2026-03-15", category: "饮食", filePath: "/test" });
+      index.addEntry({ text: "讨论了记忆系统方案，确定三层架构", date: "2026-03-15", category: "技术", filePath: "/test" });
+
+      // 搜饮食
+      const foodResults = index.search("牛肉火锅", 1);
+      expect(foodResults).toHaveLength(1);
+      expect(foodResults[0].entry.category).toBe("饮食");
+
+      // 搜技术
+      const techResults = index.search("记忆系统", 1);
+      expect(techResults).toHaveLength(1);
+      expect(techResults[0].entry.category).toBe("技术");
+    });
+  });
+});

package/src/__tests__/config.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect } from "vitest";
+import { parseConfig, DEFAULTS } from "../config.js";
+
+describe("parseConfig", () => {
+  it("returns defaults when no config provided", () => {
+    const config = parseConfig();
+    expect(config.shortTermDays).toBe(DEFAULTS.shortTermDays);
+    expect(config.halfLifeDays).toBe(DEFAULTS.halfLifeDays);
+    expect(config.recallTopK).toBe(DEFAULTS.recallTopK);
+    expect(config.minScore).toBe(DEFAULTS.minScore);
+    expect(config.vectorWeight).toBe(DEFAULTS.vectorWeight);
+    expect(config.textWeight).toBe(DEFAULTS.textWeight);
+  });
+
+  it("returns defaults when empty object provided", () => {
+    const config = parseConfig({});
+    expect(config.shortTermDays).toBe(7);
+    expect(config.halfLifeDays).toBe(30);
+  });
+
+  it("overrides defaults with provided values", () => {
+    const config = parseConfig({ shortTermDays: 14, minScore: 0.5 });
+    expect(config.shortTermDays).toBe(14);
+    expect(config.minScore).toBe(0.5);
+    // 其他值保持默认
+    expect(config.halfLifeDays).toBe(DEFAULTS.halfLifeDays);
+  });
+
+  it("ignores invalid types and uses defaults", () => {
+    const config = parseConfig({ shortTermDays: "abc" as any, halfLifeDays: null as any });
+    expect(config.shortTermDays).toBe(DEFAULTS.shortTermDays);
+    expect(config.halfLifeDays).toBe(DEFAULTS.halfLifeDays);
+  });
+});

package/src/__tests__/profile.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { ProfileManager, EMPTY_PROFILE } from "../profile.js";
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+describe("ProfileManager", () => {
+  let manager: ProfileManager;
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = join(tmpdir(), `engram-test-${Date.now()}`);
+    await fs.mkdir(tempDir, { recursive: true });
+    manager = new ProfileManager(tempDir);
+  });
+
+  describe("load", () => {
+    it("returns empty profile when no file exists", async () => {
+      const profile = await manager.load();
+      expect(profile.summary).toBe("");
+      expect(profile.coreTags).toEqual([]);
+      expect(profile.tags).toEqual({});
+    });
+
+    it("loads existing profile from file", async () => {
+      const profileDir = join(tempDir, "memory", "profile");
+      await fs.mkdir(profileDir, { recursive: true });
+      const saved = { ...EMPTY_PROFILE, summary: "test summary", coreTags: ["tag1"] };
+      await fs.writeFile(join(profileDir, "semantic_profile.json"), JSON.stringify(saved));
+
+      // 创建新的 manager 实例测试从文件加载
+      const manager2 = new ProfileManager(tempDir);
+      const loaded = await manager2.load();
+      expect(loaded.summary).toBe("test summary");
+      expect(loaded.coreTags).toEqual(["tag1"]);
+    });
+  });
+
+  describe("addTag", () => {
+    it("adds a new tag to a new dimension", async () => {
+      const profile = { ...EMPTY_PROFILE };
+      const result = manager.addTag(profile, "口味偏好", "喜欢辣");
+      expect(result.tags["口味偏好"]).toHaveLength(1);
+      expect(result.tags["口味偏好"][0].value).toBe("喜欢辣");
+      expect(result.tags["口味偏好"][0].confidence).toBe(0.7);
+    });
+
+    it("increases confidence for existing tag", async () => {
+      const profile: any = {
+        ...EMPTY_PROFILE,
+        tags: { 口味偏好: [{ value: "喜欢辣", confidence: 0.5, lastSeen: "2026-01-01" }] },
+      };
+      const result = manager.addTag(profile, "口味偏好", "喜欢辣");
+      expect(result.tags["口味偏好"]).toHaveLength(1);
+      expect(result.tags["口味偏好"][0].confidence).toBeCloseTo(0.6);
+    });
+
+    it("adds multiple tags to same dimension", async () => {
+      const profile = { ...EMPTY_PROFILE };
+      manager.addTag(profile, "口味偏好", "喜欢辣");
+      manager.addTag(profile, "口味偏好", "不吃香菜");
+      expect(profile.tags["口味偏好"]).toHaveLength(2);
+    });
+  });
+
+  describe("decayTags", () => {
+    it("reduces confidence of all tags", () => {
+      const profile: any = {
+        ...EMPTY_PROFILE,
+        tags: {
+          口味偏好: [
+            { value: "喜欢辣", confidence: 0.9, lastSeen: "2026-03-17" },
+          ],
+        },
+      };
+      const result = manager.decayTags(profile, 0.5);
+      expect(result.tags["口味偏好"][0].confidence).toBeCloseTo(0.45);
+    });
+
+    it("removes tags below threshold", () => {
+      const profile: any = {
+        ...EMPTY_PROFILE,
+        tags: {
+          过时: [{ value: "旧标签", confidence: 0.15, lastSeen: "2026-01-01" }],
+        },
+      };
+      const result = manager.decayTags(profile, 1.0);
+      expect(result.tags["过时"]).toBeUndefined();
+    });
+
+    it("removes empty dimensions after filtering", () => {
+      const profile: any = {
+        ...EMPTY_PROFILE,
+        tags: {
+          空维度: [{ value: "很低", confidence: 0.1, lastSeen: "2026-01-01" }],
+        },
+      };
+      const result = manager.decayTags(profile, 1.0);
+      expect("空维度" in result.tags).toBe(false);
+    });
+  });
+
+  describe("getRecallContext", () => {
+    it("returns empty string for empty profile", () => {
+      const ctx = manager.getRecallContext(EMPTY_PROFILE);
+      expect(ctx).toBe("");
+    });
+
+    it("returns summary and core tags", () => {
+      const profile = { ...EMPTY_PROFILE, summary: "辣味中餐爱好者", coreTags: ["辣味中餐", "天河"] };
+      const ctx = manager.getRecallContext(profile);
+      expect(ctx).toContain("辣味中餐爱好者");
+      expect(ctx).toContain("辣味中餐");
+      expect(ctx).toContain("天河");
+    });
+
+    it("works with only core tags", () => {
+      const profile = { ...EMPTY_PROFILE, summary: "", coreTags: ["标签1"] };
+      const ctx = manager.getRecallContext(profile);
+      expect(ctx).toContain("标签1");
+    });
+  });
+
+  describe("save", () => {
+    it("saves profile to file", async () => {
+      const profile = { ...EMPTY_PROFILE, summary: "test" };
+      await manager.save(profile);
+
+      const raw = await fs.readFile(join(tempDir, "memory", "profile", "semantic_profile.json"), "utf-8");
+      const loaded = JSON.parse(raw);
+      expect(loaded.summary).toBe("test");
+    });
+
+    it("updates updatedAt on save", async () => {
+      const profile = { ...EMPTY_PROFILE };
+      const before = new Date();
+      await manager.save(profile);
+      const after = new Date();
+
+      const raw = await fs.readFile(join(tempDir, "memory", "profile", "semantic_profile.json"), "utf-8");
+      const loaded = JSON.parse(raw);
+      const updated = new Date(loaded.updatedAt);
+      expect(updated.getTime()).toBeGreaterThanOrEqual(before.getTime());
+      expect(updated.getTime()).toBeLessThanOrEqual(after.getTime());
+    });
+  });
+});

package/src/__tests__/recall.test.ts

@@ -0,0 +1,186 @@
+import { describe, it, expect } from "vitest";
+
+// 纯函数测试，不依赖外部模块
+describe("Recall helpers", () => {
+  describe("temporalDecay", () => {
+    function temporalDecay(score: number, ageInDays: number, halfLifeDays: number): number {
+      if (ageInDays <= 0) return score;
+      const lambda = Math.log(2) / halfLifeDays;
+      return score * Math.exp(-lambda * ageInDays);
+    }
+
+    it("returns original score for 0 days", () => {
+      expect(temporalDecay(1.0, 0, 30)).toBeCloseTo(1.0);
+    });
+
+    it("returns ~50% at half-life", () => {
+      expect(temporalDecay(1.0, 30, 30)).toBeCloseTo(0.5, 1);
+    });
+
+    it("returns ~84% at 7 days with 30-day half-life", () => {
+      expect(temporalDecay(1.0, 7, 30)).toBeCloseTo(0.846, 2);
+    });
+
+    it("returns ~12.5% at 90 days with 30-day half-life", () => {
+      expect(temporalDecay(1.0, 90, 30)).toBeCloseTo(0.125, 2);
+    });
+
+    it("shorter half-life decays faster", () => {
+      const short = temporalDecay(1.0, 7, 7);
+      const long = temporalDecay(1.0, 7, 30);
+      expect(short).toBeLessThan(long);
+    });
+  });
+
+  describe("jaccard", () => {
+    function jaccard(a: string, b: string): number {
+      const setA = new Set(a.split(""));
+      const setB = new Set(b.split(""));
+      const intersection = new Set([...setA].filter(x => setB.has(x)));
+      const union = new Set([...setA, ...setB]);
+      return union.size === 0 ? 0 : intersection.size / union.size;
+    }
+
+    it("returns 1.0 for identical strings", () => {
+      expect(jaccard("abc", "abc")).toBeCloseTo(1.0);
+    });
+
+    it("returns 0.0 for completely different strings", () => {
+      expect(jaccard("abc", "xyz")).toBeCloseTo(0.0);
+    });
+
+    it("returns partial similarity for overlapping strings", () => {
+      const sim = jaccard("abc", "abd");
+      expect(sim).toBeGreaterThan(0);
+      expect(sim).toBeLessThan(1);
+    });
+
+    it("handles empty strings", () => {
+      expect(jaccard("", "")).toBe(0);
+      expect(jaccard("abc", "")).toBe(0);
+    });
+  });
+
+  describe("MMR rerank", () => {
+    function mmrRerank(
+      candidates: Array<{ text: string; finalScore: number }>,
+      lambda: number = 0.7
+    ): Array<{ text: string; finalScore: number }> {
+      if (candidates.length <= 1) return candidates;
+
+      const jaccard = (a: string, b: string): number => {
+        const setA = new Set(a.split(""));
+        const setB = new Set(b.split(""));
+        const intersection = new Set([...setA].filter(x => setB.has(x)));
+        const union = new Set([...setA, ...setB]);
+        return union.size === 0 ? 0 : intersection.size / union.size;
+      };
+
+      const selected: typeof candidates = [];
+      const remaining = [...candidates];
+
+      remaining.sort((a, b) => b.finalScore - a.finalScore);
+      selected.push(remaining.shift()!);
+
+      while (remaining.length > 0) {
+        let bestIdx = -1;
+        let bestMmr = -Infinity;
+        for (let i = 0; i < remaining.length; i++) {
+          const relevance = remaining[i].finalScore;
+          const maxSim = Math.max(...selected.map(s => jaccard(remaining[i].text, s.text)));
+          const mmrScore = lambda * relevance - (1 - lambda) * maxSim;
+          if (mmrScore > bestMmr) {
+            bestMmr = mmrScore;
+            bestIdx = i;
+          }
+        }
+        if (bestIdx >= 0) {
+          selected.push(remaining.splice(bestIdx, 1)[0]);
+        } else break;
+      }
+      return selected;
+    }
+
+    it("returns single item as-is", () => {
+      const candidates = [{ text: "hello", finalScore: 0.9 }];
+      expect(mmrRerank(candidates)).toHaveLength(1);
+    });
+
+    it("returns empty for empty input", () => {
+      expect(mmrRerank([])).toHaveLength(0);
+    });
+
+    it("promotes diverse results over duplicates", () => {
+      const candidates = [
+        { text: "在体育西吃了潮汕牛肉火锅", finalScore: 0.92 },
+        { text: "在天河吃了潮汕牛肉火锅", finalScore: 0.89 },
+        { text: "在越秀吃了日本料理", finalScore: 0.70 },
+      ];
+
+      const reranked = mmrRerank(candidates, 0.7);
+      expect(reranked).toHaveLength(3);
+      // 第一条应该还是分数最高的
+      expect(reranked[0].finalScore).toBe(0.92);
+    });
+
+    it("lambda=1.0 is pure relevance (no diversity)", () => {
+      const candidates = [
+        { text: "aaa", finalScore: 0.9 },
+        { text: "aaa", finalScore: 0.8 },
+        { text: "bbb", finalScore: 0.5 },
+      ];
+
+      const reranked = mmrRerank(candidates, 1.0);
+      expect(reranked.map(r => r.finalScore)).toEqual([0.9, 0.8, 0.5]);
+    });
+  });
+
+  describe("dedup", () => {
+    function jaccard(a: string, b: string): number {
+      const setA = new Set(a.split(""));
+      const setB = new Set(b.split(""));
+      const intersection = new Set([...setA].filter(x => setB.has(x)));
+      const union = new Set([...setA, ...setB]);
+      return union.size === 0 ? 0 : intersection.size / union.size;
+    }
+
+    function dedup(results: Array<{ text: string; score: number }>): Array<{ text: string; score: number }> {
+      const sorted = [...results].sort((a, b) => b.score - a.score);
+      const unique: typeof results = [];
+      for (const item of sorted) {
+        const isDup = unique.some(u => jaccard(item.text, u.text) > 0.7);
+        if (!isDup) unique.push(item);
+      }
+      return unique;
+    }
+
+    it("removes near-duplicates", () => {
+      const results = [
+        { text: "在体育西吃了潮汕牛肉火锅", score: 0.92 },
+        { text: "在体育西吃潮汕牛肉火锅", score: 0.85 },
+        { text: "在天河城看到特斯拉展厅", score: 0.70 },
+      ];
+      const deduped = dedup(results);
+      expect(deduped.length).toBeLessThan(3);
+    });
+
+    it("keeps distinct results", () => {
+      const results = [
+        { text: "今天天气很好", score: 0.9 },
+        { text: "股票涨了", score: 0.8 },
+        { text: "新开了家餐厅", score: 0.7 },
+      ];
+      expect(dedup(results)).toHaveLength(3);
+    });
+
+    it("keeps higher-scored duplicate", () => {
+      const results = [
+        { text: "abcde fghij", score: 0.9 },
+        { text: "abcde fghij", score: 0.7 },
+      ];
+      const deduped = dedup(results);
+      expect(deduped).toHaveLength(1);
+      expect(deduped[0].score).toBe(0.9);
+    });
+  });
+});

package/src/bm25.ts

@@ -0,0 +1,202 @@
+/**
+ * Memory System Plugin - BM25 Short-term Memory Index
+ * 
+ * 短期记忆的 BM25 索引构建与搜索
+ * 纯 TypeScript 实现，不依赖外部 BM25 库
+ */
+
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+
+export type ShortTermEntry = {
+  text: string;
+  date: string;       // ISO date
+  category: string;   // 饮食、工作、家庭、技术、决策、健康等
+  filePath: string;   // 源文件路径
+};
+
+type BM25Doc = {
+  tokens: string[];
+  entry: ShortTermEntry;
+};
+
+/**
+ * 简单中文分词：按字符 bigram + 单字
+ * 生产环境可替换为 jieba
+ */
+function tokenize(text: string): string[] {
+  // 去除标点符号，转为小写
+  const cleaned = text.toLowerCase().replace(/[^\w\u4e00-\u9fff]/g, " ");
+  const tokens: string[] = [];
+  // 中文 bigram
+  const chinese = cleaned.match(/[\u4e00-\u9fff]+/g) || [];
+  for (const segment of chinese) {
+    for (let i = 0; i < segment.length - 1; i++) {
+      tokens.push(segment.substring(i, i + 2));
+    }
+    // 也保留单字
+    for (const char of segment) {
+      tokens.push(char);
+    }
+  }
+  // 英文按空格分
+  const english = cleaned.replace(/[\u4e00-\u9fff]/g, " ").split(/\s+/).filter(Boolean);
+  tokens.push(...english);
+  return tokens;
+}
+
+export class BM25Index {
+  private docs: BM25Doc[] = [];
+  private idf: Map<string, number> = new Map();
+  private avgDl = 0;
+
+  /**
+   * 从短期记忆文件构建索引
+   */
+  async buildFromDirectory(dir: string, maxAgeDays: number = 7): Promise<void> {
+    this.docs = [];
+    const cutoff = new Date();
+    cutoff.setDate(cutoff.getDate() - maxAgeDays);
+
+    try {
+      const files = await fs.readdir(dir);
+      for (const file of files.sort().reverse()) { // 最新的优先
+        if (!file.endsWith(".md")) continue;
+        const filePath = join(dir, file);
+        const stat = await fs.stat(filePath);
+        if (stat.mtime < cutoff) continue;
+
+        const content = await fs.readFile(filePath, "utf-8");
+        const entries = this.parseEntries(content, filePath, file);
+        this.docs.push(...entries);
+      }
+    } catch {
+      // 目录不存在时忽略
+    }
+
+    this.buildIDF();
+  }
+
+  /**
+   * 解析结构化的短期记忆文件
+   * 格式：### HH:MM [分类标签]\n摘要内容
+   */
+  private parseEntries(content: string, filePath: string, fileName: string): BM25Doc[] {
+    const entries: BM25Doc[] = [];
+    const lines = content.split("\n");
+    const dateMatch = fileName.match(/(\d{4}-\d{2}-\d{2})/);
+    const date = dateMatch ? dateMatch[1] : new Date().toISOString().split("T")[0];
+
+    let currentCategory = "随聊";
+    let currentText = "";
+
+    for (const line of lines) {
+      const headerMatch = line.match(/^###\s+\d{2}:\d{2}\s+\[(\w+)\]/);
+      if (headerMatch) {
+        // 保存上一条
+        if (currentText.trim()) {
+          const entry: ShortTermEntry = {
+            text: currentText.trim(),
+            date,
+            category: currentCategory,
+            filePath,
+          };
+          entries.push({ tokens: tokenize(entry.text), entry });
+        }
+        currentCategory = headerMatch[1];
+        currentText = "";
+      } else if (line.startsWith("#") || line.startsWith("---") || line.startsWith("```")) {
+        continue;
+      } else {
+        currentText += line + " ";
+      }
+    }
+
+    // 最后一条
+    if (currentText.trim()) {
+      const entry: ShortTermEntry = {
+        text: currentText.trim(),
+        date,
+        category: currentCategory,
+        filePath,
+      };
+      entries.push({ tokens: tokenize(entry.text), entry });
+    }
+
+    return entries;
+  }
+
+  /**
+   * 构建 IDF（逆文档频率）
+   */
+  private buildIDF(): void {
+    const df: Map<string, number> = new Map(); // 文档频率
+    let totalLen = 0;
+
+    for (const doc of this.docs) {
+      const unique = new Set(doc.tokens);
+      for (const t of unique) {
+        df.set(t, (df.get(t) || 0) + 1);
+      }
+      totalLen += doc.tokens.length;
+    }
+
+    this.avgDl = this.docs.length > 0 ? totalLen / this.docs.length : 1;
+
+    const N = this.docs.length;
+    for (const [term, freq] of df) {
+      // IDF = log((N - df + 0.5) / (df + 0.5) + 1)
+      this.idf.set(term, Math.log((N - freq + 0.5) / (freq + 0.5) + 1));
+    }
+  }
+
+  /**
+   * BM25 搜索
+   * @returns 带分数的结果列表
+   */
+  search(query: string, topK: number = 3): Array<{ entry: ShortTermEntry; score: number }> {
+    const queryTokens = tokenize(query);
+    const k1 = 1.5; // 词频饱和参数
+    const b = 0.75; // 文档长度归一化参数
+
+    const scores: Array<{ entry: ShortTermEntry; score: number }> = [];
+
+    for (const doc of this.docs) {
+      let score = 0;
+      for (const token of queryTokens) {
+        const idf = this.idf.get(token) || 0;
+        if (idf === 0) continue;
+
+        // 词频
+        const tf = doc.tokens.filter(t => t === token).length;
+        const dl = doc.tokens.length;
+
+        // BM25 分数
+        const tfComponent = (tf * (k1 + 1)) / (tf + k1 * (1 - b + b * (dl / this.avgDl)));
+        score += idf * tfComponent;
+      }
+
+      if (score > 0) {
+        scores.push({ entry: doc.entry, score });
+      }
+    }
+
+    scores.sort((a, b) => b.score - a.score);
+    return scores.slice(0, topK);
+  }
+
+  /**
+   * 添加单条记录（用于实时写入后的即时索引）
+   */
+  addEntry(entry: ShortTermEntry): void {
+    this.docs.push({
+      tokens: tokenize(entry.text),
+      entry,
+    });
+    this.buildIDF(); // 简单处理：重建 IDF
+  }
+
+  get size(): number {
+    return this.docs.length;
+  }
+}