dsh-layered-memory 0.5.3

package/dist/store/scenes.js

@@ -0,0 +1,150 @@
+/**
+ * L2 场景块存储：Markdown 文件（含 META 块）+ 场景导航。
+ * 命名规范移植自 MemoryCore；LLM 输出 [DELETED] 时由工程侧**删除文件**（硬删除），
+ * list() 对仍含该标记的遗留文件容错跳过。
+ *
+ * 分族隔离：目录为 scenes/<family>/；init() 把旧布局（scenes/ 根下散文件）
+ * 一次性迁入 scenes/chat/（历史数据由 chat 档蒸馏产出）。
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { atomicWriteText, ensureDir, readTextIfExists } from './io.js';
+import { NAV_HEADER } from './persona.js';
+const META_START = '-----META-START-----';
+const META_END = '-----META-END-----';
+const DELETED_MARKER = '[DELETED]';
+export class SceneStore {
+    logger;
+    dir;
+    family;
+    constructor(dataDir, family, logger) {
+        this.logger = logger;
+        this.family = family;
+        this.dir = path.join(dataDir, 'scenes', family);
+    }
+    async init() {
+        await ensureDir(this.dir);
+        await this.migrateLegacyLayout();
+    }
+    /** 旧布局迁移：scenes/ 根下的 .md 移入本族目录。仅 chat 族执行（历史数据归属 chat）。 */
+    async migrateLegacyLayout() {
+        if (this.family !== 'chat')
+            return;
+        const legacyDir = path.dirname(this.dir);
+        let files;
+        try {
+            files = await fs.readdir(legacyDir);
+        }
+        catch {
+            return;
+        }
+        let moved = 0;
+        for (const f of files) {
+            if (!f.endsWith('.md'))
+                continue;
+            const from = path.join(legacyDir, f);
+            const to = path.join(this.dir, f);
+            try {
+                await fs.rename(from, to);
+                moved++;
+            }
+            catch {
+                /* 单文件失败跳过（可能被占用），下次启动重试 */
+            }
+        }
+        if (moved > 0)
+            this.logger?.info(`[memory] 场景目录迁移：${moved} 个文件 scenes/ → scenes/chat/`);
+    }
+    listFiles() {
+        return fs.readdir(this.dir).catch(() => []);
+    }
+    /** 列出场景摘要（解析 META 块）。 */
+    async list() {
+        const files = await this.listFiles();
+        const out = [];
+        for (const f of files.sort()) {
+            if (!f.endsWith('.md'))
+                continue;
+            const content = await readTextIfExists(path.join(this.dir, f));
+            if (!content || content.trim() === DELETED_MARKER)
+                continue;
+            out.push(parseMeta(content, f));
+        }
+        return out;
+    }
+    async read(name) {
+        const safe = sanitizeFilename(name);
+        if (!safe)
+            return undefined;
+        return readTextIfExists(path.join(this.dir, safe));
+    }
+    /**
+     * 写入/重写场景文件。content 为 [DELETED] 时删除该文件（LLM 的 delete 操作）。
+     * 文件名自动归一化（空格→短横线、剔除非法字符），非法则抛错。
+     */
+    async write(name, content) {
+        const safe = sanitizeFilename(name);
+        if (!safe)
+            throw new Error(`非法的场景文件名: ${name}`);
+        const file = path.join(this.dir, safe);
+        if (content.trim() === DELETED_MARKER) {
+            await fs.unlink(file).catch(() => undefined);
+            return safe;
+        }
+        await atomicWriteText(file, content);
+        return safe;
+    }
+    /** 场景导航索引（召回注入用）。 */
+    async navigation() {
+        const scenes = await this.list();
+        if (scenes.length === 0)
+            return '';
+        const lines = [
+            NAV_HEADER,
+            '*以下是当前场景记忆索引，可使用 memory_read_scene 读取详细内容。*',
+            '',
+        ];
+        for (const s of scenes) {
+            lines.push(`- \`${s.path}\` — ${s.summary || '(无摘要)'}`);
+        }
+        return lines.join('\n');
+    }
+}
+function parseMeta(content, name) {
+    const s = { path: name, created: '', updated: '', summary: '', heat: 0 };
+    const start = content.indexOf(META_START);
+    const end = content.indexOf(META_END);
+    if (start !== -1 && end !== -1) {
+        const meta = content.slice(start + META_START.length, end);
+        for (const line of meta.split('\n')) {
+            const m = /^\s*([a-zA-Z_]+)\s*:\s*(.*)$/.exec(line);
+            if (!m)
+                continue;
+            const key = m[1].toLowerCase();
+            const value = m[2].trim();
+            if (key === 'created')
+                s.created = value;
+            else if (key === 'updated')
+                s.updated = value;
+            else if (key === 'summary')
+                s.summary = value;
+            else if (key === 'heat')
+                s.heat = Number.parseInt(value, 10) || 0;
+        }
+    }
+    return s;
+}
+/** 文件名归一化：只允许字母数字 CJK - _ .，以 .md 结尾，去空格/标点。 */
+export function sanitizeFilename(name) {
+    let n = name.trim();
+    if (!n.toLowerCase().endsWith('.md'))
+        n = `${n}.md`;
+    n = n
+        .replace(/[^\w\u3400-\u9fff\uf900-\ufaff.\-_]/g, '-')
+        .replace(/-{2,}/g, '-')
+        .replace(/-+\.md$/i, '.md')
+        .replace(/^-+|-+$/g, '');
+    if (!n || !/^[\w\u3400-\u9fff\uf900-\ufaff.\-_]+\.md$/i.test(n))
+        return '';
+    return n;
+}

package/dist/store/search-utils.d.ts

@@ -0,0 +1,22 @@
+/** 标准 RRF 常数（原论文值）；k 越大越偏向低排名项（分布更平滑）。 */
+export declare const RRF_K = 60;
+/**
+ * RRF 融合多个已排序列表：每项得分 = 各列表 1/(k + rank + 1) 之和。
+ * 出现在多个列表的项得分累加，按得分降序返回（附 rrfScore）。
+ */
+export declare function rrfMerge<T>(lists: T[][], getId: (item: T) => string, k?: number): Array<T & {
+    rrfScore: number;
+}>;
+/** FTS5 bm25 rank（负值=更相关）转 0~1 分数（照搬 MemoryCore 公式）。 */
+export declare function bm25RankToScore(rank: number): number;
+/**
+ * 把自然语言查询构造成 FTS5 MATCH 表达式：token 引号化后 OR 连接，
+ * 命中任一 token 即返回，BM25 自然把命中多 token 的文档排前——
+ * 长查询与纯 FTS 模式（无向量）下召回率显著优于整句匹配。
+ */
+export declare function buildFtsQuery(raw: string): string | null;
+/**
+ * 写入侧分词：tokenize 后空格连接，交给 FTS5 unicode61 切词建索引。
+ * 与 buildFtsQuery 用同一分词器，保证查询 token 在索引中可命中。
+ */
+export declare function tokenizeForFts(raw: string): string;

package/dist/store/search-utils.js

@@ -0,0 +1,71 @@
+/**
+ * 检索工具（移植 MemoryCore search-utils + sqlite FTS helpers）：
+ * - rrfMerge：RRF（Reciprocal Rank Fusion，k=60）多路结果融合，hybrid 检索用；
+ * - bm25RankToScore：FTS5 bm25 rank（负值=更相关）转 0~1 分数；
+ * - buildFtsQuery / tokenizeForFts：FTS5 查询构造与写入侧分词。
+ *   官方用 jieba 分词；这里用项目自带的 CJK 二元组 + 英文词分词（util/text.ts），
+ *   读写两侧共用同一分词器，保证查询 token 与索引 token 对齐，且零原生依赖。
+ */
+import { tokenize } from '../util/text.js';
+/** 标准 RRF 常数（原论文值）；k 越大越偏向低排名项（分布更平滑）。 */
+export const RRF_K = 60;
+/**
+ * RRF 融合多个已排序列表：每项得分 = 各列表 1/(k + rank + 1) 之和。
+ * 出现在多个列表的项得分累加，按得分降序返回（附 rrfScore）。
+ */
+export function rrfMerge(lists, getId, k = RRF_K) {
+    const map = new Map();
+    for (const list of lists) {
+        for (let rank = 0; rank < list.length; rank++) {
+            const item = list[rank];
+            const id = getId(item);
+            const score = 1 / (k + rank + 1);
+            const existing = map.get(id);
+            if (existing) {
+                existing.rrfScore += score;
+            }
+            else {
+                map.set(id, { item, rrfScore: score });
+            }
+        }
+    }
+    return [...map.values()]
+        .sort((a, b) => b.rrfScore - a.rrfScore)
+        .map(({ item, rrfScore }) => ({ ...item, rrfScore }));
+}
+/** FTS5 bm25 rank（负值=更相关）转 0~1 分数（照搬 MemoryCore 公式）。 */
+export function bm25RankToScore(rank) {
+    if (!Number.isFinite(rank))
+        return 1 / (1 + 999);
+    if (rank < 0) {
+        const relevance = -rank;
+        return relevance / (1 + relevance);
+    }
+    return 1 / (1 + rank);
+}
+/** 高频中文虚词，进 FTS 查询只添噪声（沿用官方小表）。 */
+const ZH_STOP_WORDS = new Set([
+    '的', '了', '在', '是', '我', '有', '和', '就', '不', '人', '都', '一',
+    '一个', '上', '也', '很', '到', '说', '要', '去', '你', '会', '着',
+    '没有', '看', '好', '自己', '这', '他', '她', '它', '们', '那',
+    '吗', '吧', '呢', '啊', '呀', '哦', '嗯',
+]);
+/**
+ * 把自然语言查询构造成 FTS5 MATCH 表达式：token 引号化后 OR 连接，
+ * 命中任一 token 即返回，BM25 自然把命中多 token 的文档排前——
+ * 长查询与纯 FTS 模式（无向量）下召回率显著优于整句匹配。
+ */
+export function buildFtsQuery(raw) {
+    const tokens = [...new Set(tokenize(raw).filter((t) => !ZH_STOP_WORDS.has(t)))];
+    if (tokens.length === 0)
+        return null;
+    const quoted = tokens.map((t) => `"${t.replaceAll('"', '')}"`);
+    return quoted.join(' OR ');
+}
+/**
+ * 写入侧分词：tokenize 后空格连接，交给 FTS5 unicode61 切词建索引。
+ * 与 buildFtsQuery 用同一分词器，保证查询 token 在索引中可命中。
+ */
+export function tokenizeForFts(raw) {
+    return tokenize(raw).join(' ');
+}

package/dist/store/session-modes.d.ts

@@ -0,0 +1,24 @@
+import type { MemoryLogger, MemoryMode } from '../types.js';
+export declare function isMemoryMode(v: unknown): v is MemoryMode;
+export declare class SessionModeStore {
+    private readonly defaultMode;
+    private readonly logger?;
+    private readonly file;
+    private readonly entries;
+    private readonly loaded;
+    private persistFailed;
+    /** 串行化持久化写（避免并发原子写撞临时文件名）。 */
+    private writeChain;
+    constructor(dataDir: string, defaultMode: Extract<MemoryMode, 'auto' | 'chat' | 'work'>, logger?: MemoryLogger | undefined);
+    /** 载入持久化映射（index.ts 启动时 await；失败降级内存态）。 */
+    init(): Promise<void>;
+    get default(): MemoryMode;
+    /** 同步读取：未设置过的会话返回默认档。 */
+    get(sessionId: string): MemoryMode;
+    /** 设置会话档位（写穿持久化；持久化失败保持内存态生效）。 */
+    set(sessionId: string, mode: MemoryMode): void;
+    /** 等待在途持久化写完成（测试/停机用）。 */
+    flush(): Promise<void>;
+    private persist;
+    private serialize;
+}

package/dist/store/session-modes.js

@@ -0,0 +1,102 @@
+/**
+ * 会话记忆档位存储：sessionId → MemoryMode 的持久化映射。
+ * 热路径（捕获 turn/end、召回 pre-step、工具 execute）需要同步读取，
+ * 因此 init() 一次性载入内存 Map，set() 写穿。
+ * 存储失败只降级为内存态（warn 不崩），与插件的存储降级不变量一致。
+ */
+import * as path from 'node:path';
+import { atomicWriteJson, ensureDir, readJsonIfExists } from './io.js';
+const MODES = ['auto', 'chat', 'work', 'off'];
+const PRUNE_MS = 90 * 24 * 3600_000;
+const MAX_ENTRIES = 500;
+export function isMemoryMode(v) {
+    return typeof v === 'string' && MODES.includes(v);
+}
+export class SessionModeStore {
+    defaultMode;
+    logger;
+    file;
+    entries = new Map();
+    loaded;
+    persistFailed = false;
+    /** 串行化持久化写（避免并发原子写撞临时文件名）。 */
+    writeChain = Promise.resolve();
+    constructor(dataDir, defaultMode, logger) {
+        this.defaultMode = defaultMode;
+        this.logger = logger;
+        this.file = path.join(dataDir, 'session-modes.json');
+        this.loaded = defaultMode;
+    }
+    /** 载入持久化映射（index.ts 启动时 await；失败降级内存态）。 */
+    async init() {
+        const data = await readJsonIfExists(this.file);
+        if (!data?.sessions || typeof data.sessions !== 'object')
+            return;
+        const now = Date.now();
+        let count = 0;
+        for (const [sid, entry] of Object.entries(data.sessions)) {
+            if (!isMemoryMode(entry?.mode))
+                continue;
+            if (now - (entry.updatedAt ?? 0) > PRUNE_MS)
+                continue;
+            this.entries.set(sid, { mode: entry.mode, updatedAt: entry.updatedAt ?? now });
+            count++;
+        }
+        if (count > 0)
+            this.logger?.info(`[memory] 会话档位载入 ${count} 条（默认档=${this.defaultMode}）`);
+    }
+    get default() {
+        return this.loaded;
+    }
+    /** 同步读取：未设置过的会话返回默认档。 */
+    get(sessionId) {
+        return this.entries.get(sessionId)?.mode ?? this.loaded;
+    }
+    /** 设置会话档位（写穿持久化；持久化失败保持内存态生效）。 */
+    set(sessionId, mode) {
+        this.entries.set(sessionId, { mode, updatedAt: Date.now() });
+        this.writeChain = this.writeChain.then(() => this.persist());
+    }
+    /** 等待在途持久化写完成（测试/停机用）。 */
+    flush() {
+        return this.writeChain;
+    }
+    async persist() {
+        try {
+            await ensureDir(path.dirname(this.file));
+            await atomicWriteJson(this.file, this.serialize());
+            this.persistFailed = false;
+        }
+        catch (err) {
+            if (!this.persistFailed) {
+                this.persistFailed = true;
+                this.logger?.warn(`[memory] 会话档位持久化失败（降级内存态）: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    serialize() {
+        const now = Date.now();
+        // 超期清理 + 条数上限（按 updatedAt 淘汰最旧）
+        for (const [sid, e] of this.entries) {
+            if (now - e.updatedAt > PRUNE_MS)
+                this.entries.delete(sid);
+        }
+        while (this.entries.size > MAX_ENTRIES) {
+            let oldest;
+            let oldestAt = Infinity;
+            for (const [sid, e] of this.entries) {
+                if (e.updatedAt < oldestAt) {
+                    oldest = sid;
+                    oldestAt = e.updatedAt;
+                }
+            }
+            if (oldest === undefined)
+                break;
+            this.entries.delete(oldest);
+        }
+        const sessions = {};
+        for (const [sid, e] of this.entries)
+            sessions[sid] = e;
+        return { version: 1, sessions };
+    }
+}

package/dist/store/sqlite.d.ts

@@ -0,0 +1,121 @@
+import type { EmbeddingProviderInfo } from './embedding.js';
+import type { L0MessageRecord, MemoryFamily, MemoryLogger, MemoryRecord } from '../types.js';
+export interface StoreInitResult {
+    /** embedding 配置（provider/model/维度）变化，需要后台全量重嵌入。 */
+    needsReindex: boolean;
+    reason?: string;
+}
+export interface StoreCapabilities {
+    ftsSearch: boolean;
+    vectorSearch: boolean;
+}
+/** L1 检索命中（含 BM25/余弦归一分数）。 */
+export interface L1SearchHit {
+    id: string;
+    content: string;
+    type: string;
+    priority: number;
+    scene_name: string;
+    score: number;
+    family: MemoryFamily;
+}
+/** L0 检索命中。 */
+export interface L0SearchHit extends L0MessageRecord {
+    score: number;
+}
+export declare class MemoryDb {
+    private db;
+    private degraded;
+    private ftsAvailable;
+    private vecLoaded;
+    private readonly dimensions;
+    private readonly logger?;
+    private stmtUpsertL1;
+    private stmtGetL1;
+    private stmtDeleteL1Meta;
+    private stmtDeleteL1Vec?;
+    private stmtInsertL1Vec?;
+    private stmtSearchL1Vec?;
+    private stmtL1FtsInsert;
+    private stmtL1FtsDelete;
+    private stmtL1FtsSearch;
+    private stmtL1FtsSearchFamily;
+    private stmtUpsertL0;
+    private stmtDeleteL0Vec?;
+    private stmtInsertL0Vec?;
+    private stmtSearchL0Vec?;
+    private stmtL0FtsInsert;
+    private stmtL0FtsDelete;
+    private stmtL0FtsSearch;
+    constructor(dbPath: string, dimensions: number, logger?: MemoryLogger);
+    isDegraded(): boolean;
+    getCapabilities(): StoreCapabilities;
+    /**
+     * 加载 sqlite-vec 扩展并建 schema。构造后必须调用一次。
+     * providerInfo 变化（provider/model/维度）时 drop 向量表并返回 needsReindex。
+     */
+    init(providerInfo?: EmbeddingProviderInfo): StoreInitResult;
+    private initSchema;
+    private prepareL1VecStatements;
+    private prepareL0VecStatements;
+    private dropVectorTables;
+    private tableExists;
+    private hasColumn;
+    /** 重建后的 l1_fts 从 l1_records 全量回灌（仅在 drop 重建时调用）。 */
+    private backfillL1Fts;
+    private readEmbeddingMeta;
+    private writeEmbeddingMeta;
+    /**
+     * 标记当前向量与 embedding 配置同步完成（持久化 meta）。
+     * 只应在重嵌入成功（或空库无历史向量）后调用——过早写入会让下次启动
+     * 比对通过而跳过补齐，向量表永远空着（review P7）。
+     */
+    markEmbeddingSynced(info: EmbeddingProviderInfo): void;
+    /** upsert 一条 L1（元数据 + FTS 同步；embedding 非零时写向量）。失败返回 false 不抛。 */
+    upsertL1(record: MemoryRecord, embedding?: Float32Array): boolean;
+    /** 批量删除 L1（元数据 + 向量 + FTS），返回删除条数。 */
+    deleteL1Batch(ids: string[]): number;
+    countL1(): number;
+    /** 全量读取（调试/迁移/重嵌入用；检索请走 FTS/向量）。 */
+    getAllL1(): MemoryRecord[];
+    getL1ByIds(ids: string[]): MemoryRecord[];
+    /** 浏览列表（UI 用）：按更新时间倒序，支持类型/场景/族过滤与分页。失败返回空。 */
+    listL1(opts: {
+        type?: string;
+        scene?: string;
+        family?: string;
+        limit: number;
+        offset: number;
+    }): {
+        items: MemoryRecord[];
+        total: number;
+    };
+    /** 场景名去重列表（UI 筛选器数据源）。失败返回空。 */
+    distinctL1Scenes(): string[];
+    /** FTS5 BM25 检索（family 缺省不过滤）。失败返回空数组（调用方降级）。 */
+    searchL1Fts(query: string, limit: number, family?: string): L1SearchHit[];
+    /** vec0 余弦 KNN 检索（score = 1 - cosine distance；family 过滤走过度召回 + 回查过滤，vec0 无法 WHERE）。失败返回空数组。 */
+    searchL1Vector(embedding: Float32Array, topK: number, family?: string): L1SearchHit[];
+    /** 批量 upsert L0 消息（元数据 + FTS；embeddings 与 records 等长，可省略）。 */
+    upsertL0Batch(records: L0MessageRecord[], embeddings?: Array<Float32Array | undefined>): boolean;
+    countL0(): number;
+    /** 统计 recorded_at >= iso 的消息数（状态面板"今日捕获"用）。 */
+    countL0Since(iso: string): number;
+    /** 向量表行数（backfill 判据：与元数据行数的差值即缺失向量数；不可用时返回 -1）。 */
+    countL1Vec(): number;
+    countL0Vec(): number;
+    searchL0Fts(query: string, limit: number): L0SearchHit[];
+    searchL0Vector(embedding: Float32Array, topK: number): L0SearchHit[];
+    getL1ForReindex(): Array<{
+        id: string;
+        content: string;
+    }>;
+    getL0ForReindex(): Array<{
+        id: string;
+        text: string;
+    }>;
+    /** 只更新向量行（重嵌入用）。 */
+    updateL1Vec(id: string, embedding: Float32Array): boolean;
+    updateL0Vec(id: string, embedding: Float32Array, recordedAt: string): boolean;
+    close(): void;
+}