@scotthuang/engram 0.5.9 → 0.6.0

package/dist/src/bm25.js

@@ -0,0 +1,271 @@
+/**
+ * Memory System Plugin - BM25 Short-term Memory Index
+ *
+ * 短期记忆的 BM25 索引构建与搜索
+ * 纯 TypeScript 实现，不依赖外部 BM25 库
+ */
+import { promises as fs } from "node:fs";
+import { logger } from "./logger.js";
+import { join } from "node:path";
+/**
+ * 获取本地日期字符串 (YYYY-MM-DD)
+ */
+function getLocalDateString() {
+    const now = new Date();
+    const year = now.getFullYear();
+    const month = String(now.getMonth() + 1).padStart(2, "0");
+    const day = String(now.getDate()).padStart(2, "0");
+    return `${year}-${month}-${day}`;
+}
+let jiebaInstance = null;
+// 轻量停用词：优先过滤中文口语噪声、助词和标点
+const STOPWORDS = new Set([
+    "的", "地", "得", "了", "着", "过",
+    "我", "你", "他", "她", "它", "我们", "你们", "他们",
+    "这", "那", "这个", "那个", "这里", "那里",
+    "是", "有", "在", "和", "与", "及", "并", "或", "而", "但",
+    "不", "没", "没有", "很", "也", "都", "就", "还", "又",
+    "吗", "呢", "啊", "呀", "吧", "哦", "嗯",
+    "什么", "怎么", "为何", "为什么", "怎样", "是否",
+    "", "，", "。", "！", "？", "、", "：", "；", "（", "）", "《", "》",
+    ",", ".", "!", "?", ":", ";", "(", ")",
+]);
+function isMeaningfulToken(token) {
+    const t = token.trim().toLowerCase();
+    if (!t)
+        return false;
+    if (STOPWORDS.has(t))
+        return false;
+    // 过滤纯标点 / 符号
+    if (/^[\p{P}\p{S}]+$/u.test(t))
+        return false;
+    return true;
+}
+export async function initJieba() {
+    if (!jiebaInstance) {
+        const mod = await import("jieba-wasm");
+        jiebaInstance = await mod.default;
+    }
+}
+export function tokenize(text) {
+    if (jiebaInstance) {
+        const tokens = jiebaInstance.cut(text);
+        return tokens.map((t) => t.trim()).filter(isMeaningfulToken);
+    }
+    // fallback: 英文按空格分
+    return text
+        .toLowerCase()
+        .replace(/[^\w\u4e00-\u9fff]/g, " ")
+        .split(/\s+/)
+        .map((t) => t.trim())
+        .filter(isMeaningfulToken);
+}
+export class BM25Index {
+    docs = [];
+    idf = new Map();
+    avgDl = 0;
+    /**
+     * 从短期记忆文件构建索引
+     * v0.5: 全量索引所有 .md 文件（不再按 maxAgeDays 截断）
+     * maxAgeDays 参数保留但仅用于向下兼容（不再生效）
+     */
+    async buildFromDirectory(dir, _maxAgeDays = 7) {
+        await initJieba();
+        this.docs = [];
+        // 设计初心：只读取 memory/short-term/
+        const shortTermDir = join(dir, "short-term");
+        try {
+            const files = await fs.readdir(shortTermDir);
+            let mdFiles = 0;
+            for (const file of files.sort().reverse()) { // 最新的优先
+                if (!file.endsWith(".md"))
+                    continue;
+                const filePath = join(shortTermDir, file);
+                const content = await fs.readFile(filePath, "utf-8");
+                const entries = this.parseEntries(content, filePath, file);
+                this.docs.push(...entries);
+                mdFiles++;
+            }
+            logger.info(`[engram:bm25] Scanned ${mdFiles} MD files (full scan, no expiry cutoff)`);
+        }
+        catch {
+            logger.info(`[engram:bm25] short-term directory not found at ${shortTermDir}, 0 entries`);
+        }
+        logger.info(`[engram:bm25] Built index: ${this.docs.length} entries from ${shortTermDir}`);
+        this.buildIDF();
+    }
+    /**
+     * 解析结构化的短期记忆文件
+     * 格式：### HH:MM [分类标签]\n摘要内容
+     *
+     * 特殊处理 [对话记录]: 按 Scott / Shadow 切分每一轮对话
+     * 支持两种格式：
+     *   - 旧格式: Scott: / Shadow:
+     *   - 新格式: Scott [MM-DD HH:MM]: / Shadow [MM-DD HH:MM]:
+     * 每一轮单独做一个 BM25 文档，精准召回不浪费
+     */
+    parseEntries(content, filePath, fileName) {
+        const entries = [];
+        const lines = content.split("\n");
+        const dateMatch = fileName.match(/(\d{4}-\d{2}-\d{2})/);
+        const date = dateMatch ? dateMatch[1] : getLocalDateString();
+        let currentCategory = "随聊";
+        let currentText = "";
+        // 正则匹配 Scott 或 Shadow 开头，可选带时间戳
+        // 匹配: "Scott:" / "Shadow:" / "Scott [03-13 12:34]:" / "Shadow [03-13 12:34]:"
+        const speakerSplitRegex = /(?=^(?:Scott|Shadow)(?:\s*\[[^\]]+\])?:)/m;
+        // 精简格式检测：主题词 | 关键实体 | 摘要
+        const condensedLineRegex = /^.+\s*\|\s*.+\s*\|\s*.+$/;
+        for (const line of lines) {
+            const headerMatch = line.match(/^###\s+\d{2}:\d{2}\s+\[([^\]]+)\]/);
+            if (headerMatch) {
+                // 保存上一个分类块
+                if (currentText.trim()) {
+                    this.processTextBlock(entries, currentText, currentCategory, date, filePath, speakerSplitRegex, condensedLineRegex);
+                }
+                currentCategory = headerMatch[1];
+                currentText = "";
+            }
+            else if (line.startsWith("#") || line.startsWith("---") || line.startsWith("```")) {
+                continue;
+            }
+            else {
+                currentText += line + "\n";
+            }
+        }
+        // 最后一个分类块
+        if (currentText.trim()) {
+            this.processTextBlock(entries, currentText, currentCategory, date, filePath, speakerSplitRegex, condensedLineRegex);
+        }
+        return entries;
+    }
+    /**
+     * 处理文本块，支持三种格式：
+     * 1. 精简格式（每行 | 分隔）
+     * 2. 对话记录（Scott/Shadow 切分）
+     * 3. 普通文本（整块索引）
+     */
+    processTextBlock(entries, text, category, date, filePath, speakerSplitRegex, condensedLineRegex) {
+        const trimmed = text.trim();
+        if (!trimmed)
+            return;
+        const lines = trimmed.split("\n").filter(l => l.trim());
+        // 检测是否为精简格式（超过一半的行匹配 | 分隔格式）
+        const condensedLines = lines.filter(l => condensedLineRegex.test(l));
+        const isCondensedFormat = condensedLines.length > lines.length * 0.5;
+        if (isCondensedFormat) {
+            // 精简格式：每行单独作为一个文档，关键词密度高
+            for (const line of condensedLines) {
+                if (line.length < 10)
+                    continue;
+                // 将 | 分隔的内容合并，所有关键词都参与索引
+                const parts = line.split("|").map(p => p.trim());
+                const fullText = parts.join(" "); // 合并所有部分用于分词
+                const entry = {
+                    text: line, // 原始格式保留，用于展示
+                    date,
+                    category: "精简记录",
+                    filePath,
+                };
+                entries.push({ tokens: tokenize(fullText), entry });
+            }
+        }
+        else if (category === "对话记录" || category === "对话") {
+            // 对话记录分类：按 speaker 切分每一轮
+            const turns = trimmed.split(speakerSplitRegex);
+            for (const turn of turns) {
+                const t = turn.trim();
+                if (!t || t.length < 10)
+                    continue;
+                const entry = {
+                    text: t,
+                    date,
+                    category,
+                    filePath,
+                };
+                entries.push({ tokens: tokenize(entry.text), entry });
+            }
+        }
+        else {
+            // 普通分类：整个块作为一个文档
+            const entry = {
+                text: trimmed,
+                date,
+                category,
+                filePath,
+            };
+            entries.push({ tokens: tokenize(entry.text), entry });
+        }
+    }
+    /**
+     * 构建 IDF（逆文档频率）
+     */
+    buildIDF() {
+        const df = 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));
+        }
+        logger.info(`[engram:bm25] buildIDF: ${N} docs, ${df.size} unique terms, avgDl=${this.avgDl.toFixed(1)}`);
+    }
+    /**
+     * BM25 搜索
+     * @returns 带分数的结果列表
+     */
+    async search(query, topK = 3) {
+        await initJieba();
+        const queryTokens = tokenize(query);
+        const k1 = 1.5; // 词频饱和参数
+        const b = 0.75; // 文档长度归一化参数
+        logger.info(`[engram:bm25] search: query="${query.slice(0, 80)}" tokens=[${queryTokens.join(", ")}] topK=${topK} docs=${this.docs.length} avgDl=${this.avgDl.toFixed(1)}`);
+        const scores = [];
+        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);
+        const result = scores.slice(0, topK);
+        logger.info(`[engram:bm25] search: ${scores.length} docs matched, returning top ${result.length}`);
+        return result;
+    }
+    /**
+     * 添加单条记录（用于实时写入后的即时索引）
+     */
+    async addEntry(entry) {
+        await initJieba();
+        const tokens = tokenize(entry.text);
+        this.docs.push({
+            tokens,
+            entry,
+        });
+        logger.info(`[engram:bm25] addEntry: "${entry.text.slice(0, 60)}" → ${tokens.length} tokens, total docs=${this.docs.length}`);
+        this.buildIDF();
+    }
+    get size() {
+        return this.docs.length;
+    }
+}
+//# sourceMappingURL=bm25.js.map

package/dist/src/bm25.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bm25.js","sourceRoot":"","sources":["../../src/bm25.ts"],"names":[],"mappings":"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"}

package/dist/src/config.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Memory System Plugin - Configuration
+ */
+export type MemorySystemConfig = {
+    shortTermDays: number;
+    halfLifeDays: number;
+    recallTopK: number;
+    minScore: number;
+    vectorWeight: number;
+    textWeight: number;
+    settleModel: string;
+    embeddingModel: string;
+    /** Embedding API 配置 */
+    embedding: {
+        model: string;
+        apiKey: string;
+        baseUrl: string;
+        dimensions: number;
+    };
+    /** 精简 LLM API 配置（Anthropic Messages 格式）*/
+    condense: {
+        apiKey: string;
+        baseUrl: string;
+        model: string;
+    };
+    /** 查询重写配置 */
+    queryRewrite: {
+        /** 是否启用查询重写，默认 false */
+        enabled: boolean;
+        /** LLM API Key（留空则 fallback 到 condense.apiKey） */
+        apiKey?: string;
+        /** LLM API Base URL（留空则 fallback 到 condense.baseUrl） */
+        baseUrl?: string;
+        /** LLM 模型名（留空则 fallback 到 condense.model） */
+        model?: string;
+        /** LLM 调用超时（毫秒），默认 10000 */
+        timeoutMs: number;
+    };
+    /** 日志父目录路径，传入后在此目录下创建 engram/ 子目录按天写日志文件。不传则仅 console 输出 */
+    logDir?: string;
+    /** LanceDB 路径 */
+    lancedbDir?: string;
+    /** 是否保存中间文件（staging）供调试，默认 true */
+    saveStagingFile?: boolean;
+};
+export declare const DEFAULTS: MemorySystemConfig;
+export declare function parseConfig(raw?: Record<string, unknown>): MemorySystemConfig;

package/dist/src/config.js

@@ -0,0 +1,83 @@
+/**
+ * Memory System Plugin - Configuration
+ */
+import { logger } from "./logger.js";
+export const DEFAULTS = {
+    shortTermDays: 14,
+    halfLifeDays: 30,
+    recallTopK: 3,
+    minScore: 0.01,
+    vectorWeight: 0.7,
+    textWeight: 0.3,
+    settleModel: "MiniMax-M2.7-highspeed",
+    embeddingModel: "text-embedding-v3",
+    embedding: {
+        model: "text-embedding-v3",
+        apiKey: "",
+        baseUrl: "",
+        dimensions: 1024,
+    },
+    condense: {
+        apiKey: "",
+        baseUrl: "https://api.minimaxi.com/anthropic",
+        model: "MiniMax-M2.7-highspeed",
+    },
+    queryRewrite: {
+        enabled: false,
+        timeoutMs: 10000,
+    },
+};
+export function parseConfig(raw) {
+    if (!raw) {
+        logger.info(`[engram:config] No raw config provided, using defaults`);
+        return { ...DEFAULTS };
+    }
+    logger.info(`[engram:config] Parsing config, keys=[${Object.keys(raw).join(", ")}]`);
+    const embedding = typeof raw.embedding === "object" && raw.embedding !== null
+        ? {
+            model: typeof raw.embedding.model === "string" ? raw.embedding.model : DEFAULTS.embedding.model,
+            apiKey: typeof raw.embedding.apiKey === "string" ? raw.embedding.apiKey : DEFAULTS.embedding.apiKey,
+            baseUrl: typeof raw.embedding.baseUrl === "string" ? raw.embedding.baseUrl : DEFAULTS.embedding.baseUrl,
+            dimensions: typeof raw.embedding.dimensions === "number" ? raw.embedding.dimensions : DEFAULTS.embedding.dimensions,
+        }
+        : DEFAULTS.embedding;
+    const condense = typeof raw.condense === "object" && raw.condense !== null
+        ? {
+            apiKey: typeof raw.condense.apiKey === "string" ? raw.condense.apiKey : DEFAULTS.condense.apiKey,
+            baseUrl: typeof raw.condense.baseUrl === "string" ? raw.condense.baseUrl : DEFAULTS.condense.baseUrl,
+            model: typeof raw.condense.model === "string" ? raw.condense.model : DEFAULTS.condense.model,
+        }
+        : DEFAULTS.condense;
+    const queryRewrite = typeof raw.queryRewrite === "object" && raw.queryRewrite !== null
+        ? {
+            enabled: typeof raw.queryRewrite.enabled === "boolean" ? raw.queryRewrite.enabled : DEFAULTS.queryRewrite.enabled,
+            apiKey: typeof raw.queryRewrite.apiKey === "string" ? raw.queryRewrite.apiKey : undefined,
+            baseUrl: typeof raw.queryRewrite.baseUrl === "string" ? raw.queryRewrite.baseUrl : undefined,
+            model: typeof raw.queryRewrite.model === "string" ? raw.queryRewrite.model : undefined,
+            timeoutMs: typeof raw.queryRewrite.timeoutMs === "number" ? raw.queryRewrite.timeoutMs : DEFAULTS.queryRewrite.timeoutMs,
+        }
+        : DEFAULTS.queryRewrite;
+    const config = {
+        shortTermDays: typeof raw.shortTermDays === "number" ? raw.shortTermDays : DEFAULTS.shortTermDays,
+        halfLifeDays: typeof raw.halfLifeDays === "number" ? raw.halfLifeDays : DEFAULTS.halfLifeDays,
+        recallTopK: typeof raw.recallTopK === "number" ? raw.recallTopK : DEFAULTS.recallTopK,
+        minScore: typeof raw.minScore === "number" ? raw.minScore : DEFAULTS.minScore,
+        vectorWeight: typeof raw.vectorWeight === "number" ? raw.vectorWeight : DEFAULTS.vectorWeight,
+        textWeight: typeof raw.textWeight === "number" ? raw.textWeight : DEFAULTS.textWeight,
+        settleModel: typeof raw.settleModel === "string" ? raw.settleModel : DEFAULTS.settleModel,
+        embeddingModel: typeof raw.embeddingModel === "string" ? raw.embeddingModel : DEFAULTS.embeddingModel,
+        embedding,
+        condense,
+        queryRewrite,
+        lancedbDir: typeof raw.lancedbDir === "string" ? raw.lancedbDir : undefined,
+        logDir: typeof raw.logDir === "string" ? raw.logDir : undefined,
+        saveStagingFile: typeof raw.saveStagingFile === "boolean" ? raw.saveStagingFile : true,
+    };
+    logger.info(`[engram:config] Parsed: shortTermDays=${config.shortTermDays} halfLifeDays=${config.halfLifeDays} recallTopK=${config.recallTopK} minScore=${config.minScore} vectorWeight=${config.vectorWeight} textWeight=${config.textWeight}`);
+    logger.info(`[engram:config] Embedding: model=${config.embedding.model} dims=${config.embedding.dimensions} hasApiKey=${!!config.embedding.apiKey} baseUrl=${config.embedding.baseUrl.slice(0, 40)}`);
+    logger.info(`[engram:config] Condense: model=${config.condense.model} hasApiKey=${!!config.condense.apiKey}`);
+    logger.info(`[engram:config] QueryRewrite: enabled=${config.queryRewrite.enabled} timeoutMs=${config.queryRewrite.timeoutMs}`);
+    logger.info(`[engram:config] LogDir: ${config.logDir || "(none, console only)"}`);
+    return config;
+}
+//# sourceMappingURL=config.js.map

package/dist/src/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"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"}

package/dist/src/image-store.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Image Store - 图片本地持久化存储
+ *
+ * 将图片从临时路径（如微信下发的 /tmp 目录）copy 到持久化目录，
+ * 按日期归档，配套生成元数据 JSON 文件，支持 SHA-256 去重。
+ *
+ * 存储结构：
+ *   memory-engram/images/YYYY-MM/DD/
+ *     ├── YYYYMMDD_HHmmss_{hash6}.jpg      ← 原图
+ *     └── YYYYMMDD_HHmmss_{hash6}.json     ← 元数据
+ */
+export interface ImageMetadata {
+    /** 原始文件路径 */
+    originalPath: string;
+    /** 持久化后的绝对路径 */
+    storedPath: string;
+    /** 相对于 memory-engram/ 的路径（用于记忆引用） */
+    relativePath: string;
+    /** 存储时间戳（毫秒） */
+    timestamp: number;
+    /** 来源渠道 */
+    source: string;
+    /** 图片文件 SHA-256 hash */
+    imageHash: string;
+    /** 文件大小（字节） */
+    fileSize: number;
+    /** 图片描述（由 3.1.2 图片理解填写） */
+    description: string;
+    /** 识别到的实体（由 3.1.2 图片理解填写） */
+    entities: string[];
+    /** 人脸识别结果（由 3.2 人脸识别填写） */
+    faces: Array<{
+        personId: string | null;
+        name: string;
+        confidence: number;
+        bbox: number[];
+    }>;
+}
+export interface ImageStoreResult {
+    /** 持久化后的绝对路径 */
+    storedPath: string;
+    /** 相对于 memory-engram/ 的路径（用于记忆引用） */
+    relativePath: string;
+    /** 完整元数据 */
+    metadata: ImageMetadata;
+    /** 是否为重复图片（已存在相同 hash） */
+    isDuplicate: boolean;
+}
+/**
+ * 图片持久化存储管理器
+ */
+export declare class ImageStore {
+    private workspaceDir;
+    /** hash → relativePath 的去重索引 */
+    private hashIndex;
+    constructor(workspaceDir: string);
+    /** memory-engram 根目录 */
+    private get engramDir();
+    /** images 根目录 */
+    private get imagesDir();
+    /** hash 索引文件绝对路径 */
+    private get hashIndexPath();
+    /**
+     * 计算文件的 SHA-256 hash
+     */
+    private computeFileHash;
+    /**
+     * 加载 hash 去重索引
+     */
+    private loadHashIndex;
+    /**
+     * 保存 hash 去重索引
+     */
+    private saveHashIndex;
+    /**
+     * 生成本地时间相关的路径组件
+     */
+    private getTimeParts;
+    /**
+     * 存储图片到持久化目录
+     *
+     * @param originalPath 图片的原始路径（如 /tmp/wechat_xxx.jpg）
+     * @param options.source 来源渠道（默认 "unknown"）
+     * @returns 存储结果，包含新路径和元数据
+     * @throws 如果文件不存在或扩展名不支持
+     */
+    storeImage(originalPath: string, options?: {
+        source?: string;
+    }): Promise<ImageStoreResult>;
+    /**
+     * 更新图片元数据（用于 3.1.2 填写 description/entities，3.2 填写 faces）
+     *
+     * @param relativePath 相对于 memory-engram/ 的图片路径
+     * @param updates 要更新的字段
+     */
+    updateMetadata(relativePath: string, updates: Partial<Pick<ImageMetadata, "description" | "entities" | "faces">>): Promise<ImageMetadata | null>;
+    /**
+     * 根据 hash 查找已存储的图片
+     */
+    findByHash(imageHash: string): Promise<ImageMetadata | null>;
+    /**
+     * 列出某天的所有图片
+     *
+     * @param date 日期字符串 YYYY-MM-DD
+     */
+    listByDate(date: string): Promise<ImageMetadata[]>;
+    /**
+     * 获取图片存储统计
+     */
+    getStats(): Promise<{
+        totalImages: number;
+        totalSizeBytes: number;
+    }>;
+    /**
+     * 构建元数据对象
+     */
+    private buildMetadata;
+    /**
+     * 遍历 images/ 目录，加载所有图片元数据 JSON
+     */
+    private loadAllMetadata;
+    /**
+     * 文本检索图片：jieba 分词 + BM25 打分
+     *
+     * @param query 搜索关键词（如 "微信合照"）
+     * @param limit 返回数量上限
+     * @returns 按相关性排序的图片列表
+     */
+    searchByText(query: string, limit?: number): Promise<ImageSearchResult[]>;
+}
+export interface ImageSearchResult {
+    /** 相对于 memory-engram/ 的路径 */
+    relativePath: string;
+    /** 绝对路径 */
+    storedPath: string;
+    /** 存储日期 YYYY-MM-DD */
+    date: string;
+    /** 描述摘要（前 200 字） */
+    description: string;
+    /** 实体关键词 */
+    entities: string[];
+    /** 来源渠道 */
+    source: string;
+    /** BM25 相关性分数 */
+    score: number;
+}