dsh-layered-memory 0.5.3

package/dist/store/l0.js

@@ -0,0 +1,148 @@
+/**
+ * L0 原始对话存储（双写架构，目录布局对齐 MemoryCore l0-recorder）：
+ * - conversations/YYYY-MM-DD.jsonl：追加式事实源；
+ * - MemoryDb（SQLite）：主检索引擎——检索不再按天扫文件、现建内存索引。
+ */
+import { existsSync, promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { EmbedHelper, NoopEmbeddingService } from './embedding.js';
+import { appendJsonl, dayKey, ensureDir, nowIso, readJsonl } from './io.js';
+import { rrfMerge } from './search-utils.js';
+/** 官方过度召回倍数（conversation-search：limit × 3）。 */
+const CANDIDATE_MULTIPLIER = 3;
+export class L0Store {
+    db;
+    dir;
+    legacyDir;
+    helper;
+    embedSvc;
+    logger;
+    constructor(dataDir, db, embed = new NoopEmbeddingService(), logger) {
+        this.db = db;
+        this.dir = path.join(dataDir, 'conversations');
+        this.legacyDir = path.join(dataDir, 'l0');
+        this.embedSvc = embed;
+        this.helper = new EmbedHelper(embed, logger);
+        this.logger = logger;
+    }
+    async init() {
+        await ensureDir(this.dir);
+        await this.importLegacy();
+    }
+    /** 旧版 l0/*.jsonl 一次性导入检索库，成功后目录改名 l0.imported/。 */
+    async importLegacy() {
+        if (!existsSync(this.legacyDir))
+            return;
+        try {
+            const files = await fs.readdir(this.legacyDir).catch(() => []);
+            let imported = 0;
+            let total = 0;
+            for (const f of files.sort()) {
+                if (!f.endsWith('.jsonl'))
+                    continue;
+                const records = await readJsonl(path.join(this.legacyDir, f));
+                if (records.length > 0) {
+                    total += records.length;
+                    if (this.db.upsertL0Batch(records))
+                        imported += records.length;
+                }
+            }
+            // 只有全部批次入库成功（或目录为空）才改名，避免数据被改名带走
+            if (imported === total) {
+                const renamed = await fs
+                    .rename(this.legacyDir, `${this.legacyDir}.imported`)
+                    .then(() => true, () => false);
+                if (renamed) {
+                    this.logger?.info(`[memory] 旧版 L0 数据已导入检索库 ${imported} 条（l0/ → l0.imported/）`);
+                }
+                else {
+                    this.logger?.warn('[memory] 旧版 L0 导入完成但改名失败（l0.imported/ 已存在？），下次启动会重复导入（幂等，无害）');
+                }
+            }
+            else {
+                this.logger?.warn(`[memory] 旧版 L0 导入不完整（${imported}/${total}），保留原目录下次重试`);
+            }
+        }
+        catch (err) {
+            this.logger?.warn(`[memory] 旧版 L0 数据导入失败: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    async append(sessionId, messages) {
+        if (messages.length === 0)
+            return;
+        const records = messages.map((m) => ({
+            sessionId,
+            recordedAt: nowIso(),
+            id: m.id,
+            role: m.role,
+            content: m.content,
+            timestamp: m.timestamp,
+        }));
+        // 事实源：按天追加
+        const byDay = new Map();
+        for (const r of records) {
+            const k = dayKey(r.timestamp);
+            const arr = byDay.get(k) ?? [];
+            arr.push(r);
+            byDay.set(k, arr);
+        }
+        for (const [day, list] of byDay) {
+            await appendJsonl(path.join(this.dir, `${day}.jsonl`), list);
+        }
+        // 检索引擎：DB + 向量（嵌入失败只跳过向量，不影响元数据/FTS，backfill 补齐）
+        const vecs = await this.helper.batch(records.map((r) => r.content));
+        this.db.upsertL0Batch(records, vecs);
+    }
+    /** 今日已捕获消息数（SQL 计数，不再读整文件）。 */
+    async countToday() {
+        const d = new Date();
+        return this.db.countL0Since(new Date(d.getFullYear(), d.getMonth(), d.getDate()).toISOString());
+    }
+    /** 检索：FTS + 向量 hybrid（RRF 融合），返回按相关性排序的消息。 */
+    async search(query, limit) {
+        const caps = this.db.getCapabilities();
+        if (!caps.ftsSearch && !caps.vectorSearch)
+            return [];
+        const candidateK = limit * CANDIDATE_MULTIPLIER;
+        if (caps.vectorSearch && this.helper.vectorReady()) {
+            const [ftsRaw, vec] = await Promise.all([
+                Promise.resolve(this.db.searchL0Fts(query, candidateK)),
+                this.helper.query(query),
+            ]);
+            const vecList = vec ? this.db.searchL0Vector(vec, candidateK) : [];
+            const merged = rrfMerge([ftsRaw, vecList], (h) => h.id);
+            return merged.map(({ rrfScore: _rrf, ...r }) => r).slice(0, limit);
+        }
+        return this.db.searchL0Fts(query, limit).map(({ score: _score, ...r }) => r);
+    }
+    /**
+     * 全量重嵌入（embedding 启用 / 周期性补齐用）。
+     * 返回写入数与失败数——failed > 0 时调用方不应标记 meta 同步完成。
+     */
+    async reindex() {
+        if (!this.helper.vectorReady())
+            return { written: 0, failed: 0 };
+        const items = this.db.getL0ForReindex();
+        let written = 0;
+        let failed = 0;
+        const CHUNK = 32;
+        for (let i = 0; i < items.length; i += CHUNK) {
+            const chunk = items.slice(i, i + CHUNK);
+            let vecs;
+            try {
+                vecs = await this.embedSvc.embedBatch(chunk.map((c) => c.text));
+            }
+            catch {
+                failed += chunk.length;
+                continue;
+            }
+            chunk.forEach((c, j) => {
+                if (this.db.updateL0Vec(c.id, vecs[j], ''))
+                    written++;
+                else
+                    failed++;
+            });
+        }
+        return { written, failed };
+    }
+}

package/dist/store/l1.d.ts

@@ -0,0 +1,70 @@
+import type { L1Hit, MemoryFamily, MemoryLogger, MemoryRecord } from '../types.js';
+import { type EmbeddingService } from './embedding.js';
+import type { MemoryDb } from './sqlite.js';
+export type RecallStrategy = 'keyword' | 'embedding' | 'hybrid';
+export interface L1SearchOptions {
+    /** 按记忆类型精确过滤（后置过滤，官方做法）。 */
+    type?: string;
+    /** 按族过滤（undefined = 不过滤，即 auto 档与浏览路径；检索唯一缝的族语义）。 */
+    family?: MemoryFamily;
+    /** 分数阈值（仅召回路径传；keyword/embedding 策略生效，FTS 含小语料例外；
+     *  hybrid 按官方语义在 RRF 融合前不过滤）。 */
+    scoreThreshold?: number;
+}
+export declare class L1Store {
+    private readonly db;
+    private readonly strategy;
+    private readonly recordsDir;
+    private readonly legacyFile;
+    private readonly helper;
+    private readonly embedSvc;
+    private readonly logger?;
+    constructor(dataDir: string, db: MemoryDb, embed?: EmbeddingService, strategy?: RecallStrategy, logger?: MemoryLogger);
+    init(): Promise<void>;
+    /** 旧版单文件 records.jsonl 一次性导入检索库，成功后改名 .imported。 */
+    private importLegacy;
+    get size(): number;
+    /** 全量读取（调试/迁移用；检索请走 search）。 */
+    all(): MemoryRecord[];
+    /** 按 id 精确取记录（去重决策的版本号查询用，避免全表扫描）。 */
+    getByIds(ids: string[]): MemoryRecord[];
+    /** 新记忆落盘：JSONL 按天追加（事实源）+ 检索库 upsert + 向量。 */
+    appendNew(records: MemoryRecord[]): Promise<void>;
+    /** 去重 update/merge 产出的记录：只更新检索库（JSONL 事实源不改写，官方语义）。 */
+    upsert(record: MemoryRecord): Promise<void>;
+    deleteBatch(ids: string[]): Promise<void>;
+    /**
+     * 三策略检索（自动召回与 memory_search 工具共用接缝）。
+     * embedding 不可用时自动降级 keyword；type 后置过滤；
+     * scoreThreshold 仅对 keyword/embedding 单路策略生效——hybrid 按官方语义
+     * 融合完整列表（融合分已归一化 0~1，可直接用于展示/过滤）。
+     */
+    search(query: string, limit: number, opts?: L1SearchOptions): Promise<L1Hit[]>;
+    /** 浏览列表（UI 用）：无关键词时按更新时间倒序分页。 */
+    list(opts: {
+        type?: string;
+        scene?: string;
+        family?: string;
+        limit: number;
+        offset: number;
+    }): {
+        items: MemoryRecord[];
+        total: number;
+    };
+    /** 场景名去重列表（UI 筛选器数据源）。 */
+    distinctScenes(): string[];
+    /**
+     * 去重候选召回（官方 3 级）：空库跳过 → 向量优先 → FTS 兜底。
+     * 传入 family 时只在同族记录里召回（去重永不跨族）。
+     */
+    searchCandidates(query: string, limit: number, family?: MemoryFamily): Promise<MemoryRecord[]>;
+    /**
+     * 全量重嵌入（embedding 配置变化 / 周期性补齐用）。
+     * 返回写入数与失败数——failed > 0 时调用方不应标记 meta 同步完成。
+     */
+    reindex(): Promise<{
+        written: number;
+        failed: number;
+    }>;
+    private postProcess;
+}

package/dist/store/l1.js

@@ -0,0 +1,239 @@
+/**
+ * L1 原子记忆存储（双写架构，移植 MemoryCore l1-writer 语义）：
+ * - records/YYYY-MM-DD.jsonl：追加式事实源（只增不改，备份/恢复用）；
+ * - MemoryDb（SQLite）：主检索引擎，upsert/delete 只动这里；
+ * - 检索三策略：keyword（FTS5 BM25）/ embedding（vec0 余弦）/ hybrid（双路 + RRF k=60）。
+ *
+ * 去重/合并的更新记录走 upsert（新 record id + 版本递增），不再全量重写文件。
+ */
+import { existsSync, promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { familyForType } from '../types.js';
+import { EmbedHelper, NoopEmbeddingService } from './embedding.js';
+import { appendJsonl, dayKey, ensureDir, readJsonl } from './io.js';
+import { RRF_K, rrfMerge } from './search-utils.js';
+/** 官方过度召回倍数：候选池 = limit × 3（官方 tool 路径同款）。 */
+const CANDIDATE_MULTIPLIER = 3;
+export class L1Store {
+    db;
+    strategy;
+    recordsDir;
+    legacyFile;
+    helper;
+    embedSvc;
+    logger;
+    constructor(dataDir, db, embed = new NoopEmbeddingService(), strategy = 'hybrid', logger) {
+        this.db = db;
+        this.strategy = strategy;
+        this.recordsDir = path.join(dataDir, 'records');
+        this.legacyFile = path.join(dataDir, 'l1', 'records.jsonl');
+        this.embedSvc = embed;
+        this.helper = new EmbedHelper(embed, logger);
+        this.logger = logger;
+    }
+    async init() {
+        await ensureDir(this.recordsDir);
+        await this.importLegacy();
+    }
+    /** 旧版单文件 records.jsonl 一次性导入检索库，成功后改名 .imported。 */
+    async importLegacy() {
+        if (!existsSync(this.legacyFile))
+            return;
+        try {
+            const records = await readJsonl(this.legacyFile);
+            let n = 0;
+            for (const r of records) {
+                if (r && typeof r.id === 'string' && r.content) {
+                    if (this.db.upsertL1(r))
+                        n++;
+                }
+            }
+            // 只有确实导入成功（或文件为空）才改名，避免把未入库的数据改名带走
+            if (n === records.length) {
+                const renamed = await fs
+                    .rename(this.legacyFile, `${this.legacyFile}.imported`)
+                    .then(() => true, () => false);
+                if (renamed) {
+                    this.logger?.info(`[memory] 旧版 L1 数据已导入检索库 ${n} 条（l1/records.jsonl → .imported）`);
+                }
+                else {
+                    this.logger?.warn('[memory] 旧版 L1 导入完成但改名失败，下次启动会重复导入（upsert 幂等，无害）');
+                }
+            }
+            else {
+                this.logger?.warn(`[memory] 旧版 L1 导入不完整（${n}/${records.length}），保留原文件下次重试`);
+            }
+        }
+        catch (err) {
+            this.logger?.warn(`[memory] 旧版 L1 数据导入失败: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    get size() {
+        return this.db.countL1();
+    }
+    /** 全量读取（调试/迁移用；检索请走 search）。 */
+    all() {
+        return this.db.getAllL1();
+    }
+    /** 按 id 精确取记录（去重决策的版本号查询用，避免全表扫描）。 */
+    getByIds(ids) {
+        return this.db.getL1ByIds(ids);
+    }
+    /** 新记忆落盘：JSONL 按天追加（事实源）+ 检索库 upsert + 向量。 */
+    async appendNew(records) {
+        if (records.length === 0)
+            return;
+        for (const r of records) {
+            if (!r.family)
+                r.family = familyForType(r.type);
+        }
+        const byDay = new Map();
+        for (const r of records) {
+            const k = dayKey(r.createdAt || Date.now());
+            const arr = byDay.get(k) ?? [];
+            arr.push(r);
+            byDay.set(k, arr);
+        }
+        for (const [day, list] of byDay) {
+            await appendJsonl(path.join(this.recordsDir, `${day}.jsonl`), list);
+        }
+        const vecs = await this.helper.batch(records.map((r) => r.content));
+        for (let i = 0; i < records.length; i++) {
+            this.db.upsertL1(records[i], vecs[i]);
+        }
+    }
+    /** 去重 update/merge 产出的记录：只更新检索库（JSONL 事实源不改写，官方语义）。 */
+    async upsert(record) {
+        if (!record.family)
+            record.family = familyForType(record.type);
+        const vec = (await this.helper.batch([record.content]))[0];
+        this.db.upsertL1(record, vec);
+    }
+    async deleteBatch(ids) {
+        this.db.deleteL1Batch(ids);
+    }
+    /**
+     * 三策略检索（自动召回与 memory_search 工具共用接缝）。
+     * embedding 不可用时自动降级 keyword；type 后置过滤；
+     * scoreThreshold 仅对 keyword/embedding 单路策略生效——hybrid 按官方语义
+     * 融合完整列表（融合分已归一化 0~1，可直接用于展示/过滤）。
+     */
+    async search(query, limit, opts) {
+        const caps = this.db.getCapabilities();
+        const canVec = caps.vectorSearch && this.helper.vectorReady();
+        let strategy = this.strategy;
+        if (strategy !== 'keyword' && !canVec)
+            strategy = caps.ftsSearch ? 'keyword' : 'none';
+        const candidateK = limit * CANDIDATE_MULTIPLIER;
+        const threshold = opts?.scoreThreshold ?? 0;
+        if (strategy === 'none')
+            return [];
+        if (strategy === 'keyword') {
+            const fts = this.db.searchL1Fts(query, candidateK, opts?.family);
+            return this.postProcess(applyFtsThreshold(fts, threshold, limit), opts?.type, limit);
+        }
+        if (strategy === 'embedding') {
+            const vec = await this.helper.query(query);
+            if (!vec) {
+                // embedding 调用失败：降级 FTS，不阻断
+                const fts = this.db.searchL1Fts(query, candidateK, opts?.family);
+                return this.postProcess(applyFtsThreshold(fts, threshold, limit), opts?.type, limit);
+            }
+            const vecHits = this.db.searchL1Vector(vec, candidateK, opts?.family);
+            return this.postProcess(filterScore(vecHits, threshold), opts?.type, limit);
+        }
+        // hybrid（官方语义）：双路并行 → 完整列表 RRF 融合（融合前不过滤阈值）
+        // → 融合分归一化：rank1 双列表命中 = 1.0，单列表命中 ≤ 0.5，保持 0~1 语义
+        const [ftsList, vecRaw] = await Promise.all([
+            Promise.resolve(this.db.searchL1Fts(query, candidateK, opts?.family)),
+            this.helper.query(query),
+        ]);
+        const vecList = vecRaw ? this.db.searchL1Vector(vecRaw, candidateK, opts?.family) : [];
+        const merged = rrfMerge([ftsList, vecList], (h) => h.id);
+        return this.postProcess(merged.map(({ rrfScore, ...h }) => ({ ...h, score: normalizeRrf(rrfScore) })), opts?.type, limit);
+    }
+    /** 浏览列表（UI 用）：无关键词时按更新时间倒序分页。 */
+    list(opts) {
+        return this.db.listL1(opts);
+    }
+    /** 场景名去重列表（UI 筛选器数据源）。 */
+    distinctScenes() {
+        return this.db.distinctL1Scenes();
+    }
+    /**
+     * 去重候选召回（官方 3 级）：空库跳过 → 向量优先 → FTS 兜底。
+     * 传入 family 时只在同族记录里召回（去重永不跨族）。
+     */
+    async searchCandidates(query, limit, family) {
+        if (this.db.countL1() === 0)
+            return [];
+        const caps = this.db.getCapabilities();
+        if (caps.vectorSearch && this.helper.vectorReady()) {
+            try {
+                const vec = await this.helper.query(query);
+                if (vec) {
+                    const hits = this.db.searchL1Vector(vec, limit, family);
+                    if (hits.length > 0)
+                        return this.db.getL1ByIds(hits.map((h) => h.id));
+                }
+            }
+            catch (err) {
+                this.logger?.warn(`[memory] 向量候选召回失败，降级 FTS: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        const fts = this.db.searchL1Fts(query, limit * 2, family);
+        return this.db.getL1ByIds(fts.map((h) => h.id));
+    }
+    /**
+     * 全量重嵌入（embedding 配置变化 / 周期性补齐用）。
+     * 返回写入数与失败数——failed > 0 时调用方不应标记 meta 同步完成。
+     */
+    async reindex() {
+        if (!this.helper.vectorReady())
+            return { written: 0, failed: 0 };
+        const items = this.db.getL1ForReindex();
+        let written = 0;
+        let failed = 0;
+        const CHUNK = 16;
+        for (let i = 0; i < items.length; i += CHUNK) {
+            const chunk = items.slice(i, i + CHUNK);
+            let vecs;
+            try {
+                vecs = await this.embedSvc.embedBatch(chunk.map((c) => c.content));
+            }
+            catch {
+                failed += chunk.length;
+                continue;
+            }
+            chunk.forEach((c, j) => {
+                if (this.db.updateL1Vec(c.id, vecs[j]))
+                    written++;
+                else
+                    failed++;
+            });
+        }
+        return { written, failed };
+    }
+    postProcess(hits, type, limit) {
+        const filtered = type ? hits.filter((h) => h.type === type) : hits;
+        return filtered.slice(0, limit);
+    }
+}
+/** RRF 原始分归一化到 0~1：双列表 rank1 命中 = 2/(k+1) → 1.0。 */
+function normalizeRrf(rrfScore) {
+    return (rrfScore * (RRF_K + 1)) / 2;
+}
+/** FTS 阈值过滤（含官方小语料例外：全部低于阈值但结果数 ≤ maxResults 时保留）。 */
+function applyFtsThreshold(hits, threshold, maxResults) {
+    if (threshold <= 0)
+        return hits;
+    const filtered = hits.filter((h) => h.score >= threshold);
+    if (filtered.length === 0 && hits.length > 0 && hits.length <= maxResults)
+        return hits;
+    return filtered;
+}
+function filterScore(hits, threshold) {
+    if (threshold <= 0)
+        return hits;
+    return hits.filter((h) => h.score >= threshold);
+}

package/dist/store/persona.d.ts

@@ -0,0 +1,15 @@
+import type { MemoryFamily, MemoryLogger } from '../types.js';
+export declare const NAV_HEADER = "## \uD83D\uDDFA\uFE0F Scene Navigation";
+export declare class PersonaStore {
+    private readonly logger?;
+    private readonly file;
+    private readonly family;
+    constructor(dataDir: string, family: MemoryFamily, logger?: MemoryLogger | undefined);
+    /** 旧布局迁移：persona.md → persona-chat.md（幂等，仅 chat 族执行）。 */
+    init(): Promise<void>;
+    /** 读取正文（剥离场景导航部分）。 */
+    read(): Promise<string | undefined>;
+    /** 写入正文（保留已有导航段则拼回尾部）。 */
+    write(body: string): Promise<void>;
+}
+export declare function stripSceneNavigation(content: string): string;

package/dist/store/persona.js

@@ -0,0 +1,60 @@
+/**
+ * L3 画像存储：persona-<family>.md（chat 族=用户画像 / work 族=Team Operating Doctrine）。
+ * 场景导航由工程侧自动追加/剥离（移植 MemoryCore stripSceneNavigation 语义）。
+ * init() 把旧布局的 persona.md 一次性改名为 persona-chat.md（历史数据归属 chat 档）。
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { atomicWriteText, readTextIfExists } from './io.js';
+export const NAV_HEADER = '## 🗺️ Scene Navigation';
+export class PersonaStore {
+    logger;
+    file;
+    family;
+    constructor(dataDir, family, logger) {
+        this.logger = logger;
+        this.family = family;
+        this.file = path.join(dataDir, `persona-${family}.md`);
+    }
+    /** 旧布局迁移：persona.md → persona-chat.md（幂等，仅 chat 族执行）。 */
+    async init() {
+        if (this.family !== 'chat')
+            return;
+        const dataDir = path.dirname(this.file);
+        const legacy = path.join(dataDir, 'persona.md');
+        try {
+            await fs.access(legacy);
+            await fs.rename(legacy, this.file);
+            this.logger?.info('[memory] 画像文件迁移：persona.md → persona-chat.md');
+        }
+        catch {
+            /* 无旧文件或已迁移 */
+        }
+    }
+    /** 读取正文（剥离场景导航部分）。 */
+    async read() {
+        const raw = await readTextIfExists(this.file);
+        if (!raw)
+            return undefined;
+        return stripSceneNavigation(raw).trim() || undefined;
+    }
+    /** 写入正文（保留已有导航段则拼回尾部）。 */
+    async write(body) {
+        const raw = await readTextIfExists(this.file);
+        const nav = raw ? extractSceneNavigation(raw) : undefined;
+        const content = nav ? `${body.trim()}\n\n${nav}\n` : `${body.trim()}\n`;
+        await atomicWriteText(this.file, content);
+    }
+}
+export function stripSceneNavigation(content) {
+    const idx = content.indexOf(NAV_HEADER);
+    if (idx === -1)
+        return content;
+    return content.slice(0, idx).trimEnd();
+}
+function extractSceneNavigation(content) {
+    const idx = content.indexOf(NAV_HEADER);
+    if (idx === -1)
+        return undefined;
+    return content.slice(idx).trim();
+}

package/dist/store/scenes.d.ts

@@ -0,0 +1,23 @@
+import type { MemoryFamily, MemoryLogger, SceneSummary } from '../types.js';
+export declare class SceneStore {
+    private readonly logger?;
+    private readonly dir;
+    private readonly family;
+    constructor(dataDir: string, family: MemoryFamily, logger?: MemoryLogger | undefined);
+    init(): Promise<void>;
+    /** 旧布局迁移：scenes/ 根下的 .md 移入本族目录。仅 chat 族执行（历史数据归属 chat）。 */
+    private migrateLegacyLayout;
+    listFiles(): Promise<string[]>;
+    /** 列出场景摘要（解析 META 块）。 */
+    list(): Promise<SceneSummary[]>;
+    read(name: string): Promise<string | undefined>;
+    /**
+     * 写入/重写场景文件。content 为 [DELETED] 时删除该文件（LLM 的 delete 操作）。
+     * 文件名自动归一化（空格→短横线、剔除非法字符），非法则抛错。
+     */
+    write(name: string, content: string): Promise<string>;
+    /** 场景导航索引（召回注入用）。 */
+    navigation(): Promise<string>;
+}
+/** 文件名归一化：只允许字母数字 CJK - _ .，以 .md 结尾，去空格/标点。 */
+export declare function sanitizeFilename(name: string): string;