@memory-river/core 0.2.0

package/dist/skills/validate.d.ts

@@ -0,0 +1,6 @@
+import type { SkillDef } from '../types.js';
+export declare class SkillValidationError extends Error {
+    readonly violations: string[];
+    constructor(violations: string[]);
+}
+export declare function validateSkillDef(def: SkillDef): void;

package/dist/skills/validate.js

@@ -0,0 +1,69 @@
+const SKILL_NAME_RE = /^[\p{L}\p{N}_-]{1,50}$/u;
+function charLength(value) {
+    return Array.from(value).length;
+}
+function received(value) {
+    return JSON.stringify(value) ?? String(value);
+}
+export class SkillValidationError extends Error {
+    violations;
+    constructor(violations) {
+        super(`skill_save rejected (${violations.length} violations):\n`
+            + violations.map((violation, index) => `${index + 1}. ${violation}`).join('\n'));
+        this.violations = violations;
+        this.name = 'SkillValidationError';
+    }
+}
+export function validateSkillDef(def) {
+    const violations = [];
+    if (typeof def?.name !== 'string' || !SKILL_NAME_RE.test(def.name)) {
+        violations.push(`skillName: 不符 /^[\\p{L}\\p{N}_-]{1,50}$/u（收到 ${received(def?.name)}）`);
+    }
+    if (typeof def?.summary !== 'string') {
+        violations.push(`summary: 需為字串（收到 ${received(def?.summary)}）`);
+    }
+    else if (charLength(def.summary) < 1 || charLength(def.summary) > 200) {
+        violations.push(`summary: 需 1–200 chars（收到 ${charLength(def.summary)}）`);
+    }
+    if (!Array.isArray(def?.triggers)) {
+        violations.push(`triggerConditions: 需 1–5 條（收到 ${received(def?.triggers)}）`);
+    }
+    else {
+        if (def.triggers.length < 1 || def.triggers.length > 5) {
+            violations.push(`triggerConditions: 需 1–5 條（收到 ${def.triggers.length}）`);
+        }
+        const seen = new Set();
+        def.triggers.forEach((trigger, index) => {
+            if (typeof trigger !== 'string') {
+                violations.push(`triggerConditions[${index}]: 需為字串（收到 ${received(trigger)}）`);
+                return;
+            }
+            if (charLength(trigger) > 100) {
+                violations.push(`triggerConditions[${index}]: 超過 100 chars（收到 ${charLength(trigger)}）`);
+            }
+            if (seen.has(trigger)) {
+                violations.push(`triggerConditions[${index}]: 不得重複（收到 ${received(trigger)}）`);
+            }
+            seen.add(trigger);
+        });
+    }
+    if (!Array.isArray(def?.steps)) {
+        violations.push(`executionSteps: 需 2–15 步（收到 ${received(def?.steps)}）`);
+    }
+    else {
+        if (def.steps.length < 2 || def.steps.length > 15) {
+            violations.push(`executionSteps: 需 2–15 步（收到 ${def.steps.length}）`);
+        }
+        def.steps.forEach((step, index) => {
+            if (typeof step !== 'string') {
+                violations.push(`executionSteps[${index}]: 需為字串（收到 ${received(step)}）`);
+            }
+            else if (charLength(step) > 300) {
+                violations.push(`executionSteps[${index}]: 超過 300 chars（收到 ${charLength(step)}）`);
+            }
+        });
+    }
+    if (violations.length > 0) {
+        throw new SkillValidationError(violations);
+    }
+}

package/dist/storage.d.ts

@@ -0,0 +1,19 @@
+export type StorageMode = 'auto' | 'ram' | 'ssd';
+export declare const MIN_RAM_DB_BYTES: number;
+export interface RamDbPathResolutionOptions {
+    dbPath: string;
+    ramDbPath: string;
+    storageMode?: StorageMode;
+    getShmFreeBytes?: () => number;
+    getDbSizeBytes?: (dbPath: string) => number;
+    log?: (message: string) => void;
+}
+export interface RamDbPathResolution {
+    ramDbPath: string;
+    mode: 'ram' | 'ssd-fallback';
+    requiredBytes?: number;
+    availableBytes?: number;
+    reason?: string;
+}
+export declare function getDevShmFreeBytes(): number;
+export declare function resolveRamDbPath(options: RamDbPathResolutionOptions): RamDbPathResolution;

package/dist/storage.js

@@ -0,0 +1,54 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export const MIN_RAM_DB_BYTES = 512 * 1024 * 1024;
+function directorySizeBytes(dir) {
+    try {
+        const metadata = fs.statSync(dir);
+        if (metadata.isFile())
+            return metadata.size;
+        let total = 0;
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const entryPath = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                total += directorySizeBytes(entryPath);
+            else if (entry.isFile())
+                total += fs.statSync(entryPath).size;
+        }
+        return total;
+    }
+    catch {
+        return 0;
+    }
+}
+export function getDevShmFreeBytes() {
+    try {
+        const stats = fs.statfsSync('/dev/shm');
+        return Number(stats.bavail) * Number(stats.bsize);
+    }
+    catch {
+        return 0;
+    }
+}
+export function resolveRamDbPath(options) {
+    const storageMode = options.storageMode ?? 'auto';
+    if (storageMode === 'ram')
+        return { ramDbPath: options.ramDbPath, mode: 'ram' };
+    if (storageMode === 'ssd') {
+        return { ramDbPath: options.dbPath, mode: 'ssd-fallback', reason: 'storageMode=ssd' };
+    }
+    const existingDbBytes = (options.getDbSizeBytes ?? directorySizeBytes)(options.dbPath);
+    const requiredBytes = Math.max(MIN_RAM_DB_BYTES, existingDbBytes * 2);
+    const availableBytes = (options.getShmFreeBytes ?? getDevShmFreeBytes)();
+    if (availableBytes >= requiredBytes) {
+        return { ramDbPath: options.ramDbPath, mode: 'ram', requiredBytes, availableBytes };
+    }
+    const reason = `/dev/shm has ${availableBytes} bytes free; ${requiredBytes} bytes required`;
+    (options.log ?? console.warn)(`[memory-river] RAM storage disabled: ${reason}. Using SSD fallback; set storageMode=ram to override.`);
+    return {
+        ramDbPath: options.dbPath,
+        mode: 'ssd-fallback',
+        requiredBytes,
+        availableBytes,
+        reason,
+    };
+}

package/dist/store/aux-table-maintenance.d.ts

@@ -0,0 +1,5 @@
+export declare const AUX_TABLE_WRITE_MAINTENANCE_INTERVAL = 500;
+export declare const AUX_TABLE_VERSION_RETENTION_MS: number;
+export declare function optimizeAuxTable(table: any, label: string, cleanupAgeMs?: number): Promise<void>;
+export declare function recordAuxTableWrite(table: any, label: string, cleanupAgeMs?: number): Promise<void>;
+export declare function optimizeAuxTablesInConnection(db: any, label: string): Promise<void>;

package/dist/store/aux-table-maintenance.js

@@ -0,0 +1,64 @@
+export const AUX_TABLE_WRITE_MAINTENANCE_INTERVAL = 500;
+export const AUX_TABLE_VERSION_RETENTION_MS = 60 * 60 * 1000;
+const writeCounts = new WeakMap();
+const maintenanceInFlight = new WeakMap();
+export async function optimizeAuxTable(table, label, cleanupAgeMs = AUX_TABLE_VERSION_RETENTION_MS) {
+    if (!table)
+        return;
+    const existing = maintenanceInFlight.get(table);
+    if (existing) {
+        await existing;
+        return;
+    }
+    const maintenance = (async () => {
+        try {
+            await table.optimize({
+                cleanupOlderThan: new Date(Date.now() - cleanupAgeMs),
+            });
+        }
+        catch (err) {
+            console.warn(`[AuxTableMaintenance] ${label} optimize failed (non-fatal):`, err?.message ?? err);
+        }
+    })();
+    maintenanceInFlight.set(table, maintenance);
+    try {
+        await maintenance;
+    }
+    finally {
+        maintenanceInFlight.delete(table);
+    }
+}
+export async function recordAuxTableWrite(table, label, cleanupAgeMs = AUX_TABLE_VERSION_RETENTION_MS) {
+    if (!table || (typeof table !== "object" && typeof table !== "function"))
+        return;
+    const next = (writeCounts.get(table) ?? 0) + 1;
+    if (next < AUX_TABLE_WRITE_MAINTENANCE_INTERVAL) {
+        writeCounts.set(table, next);
+        return;
+    }
+    writeCounts.set(table, 0);
+    await optimizeAuxTable(table, label, cleanupAgeMs);
+}
+export async function optimizeAuxTablesInConnection(db, label) {
+    if (!db)
+        return;
+    let tableNames;
+    try {
+        tableNames = await db.tableNames();
+    }
+    catch (err) {
+        console.warn(`[AuxTableMaintenance] ${label} table listing failed (non-fatal):`, err?.message ?? err);
+        return;
+    }
+    for (const tableName of tableNames) {
+        if (tableName === "memories")
+            continue;
+        try {
+            const table = await db.openTable(tableName);
+            await optimizeAuxTable(table, `${label}:${tableName}`);
+        }
+        catch (err) {
+            console.warn(`[AuxTableMaintenance] ${label}:${tableName} maintenance failed (non-fatal):`, err?.message ?? err);
+        }
+    }
+}

package/dist/store/graph-enumerator.d.ts

@@ -0,0 +1,21 @@
+import type { EnumerationPlan, EnumerationResult } from '../types.js';
+import type { EmbeddingProvider } from '../ports.js';
+import type { GraphStore } from './graph-store.js';
+type GraphEnumeratorOptions = {
+    relationThreshold?: number;
+    fallbackPerRelationLimit?: number;
+};
+export declare class GraphEnumerator {
+    private readonly graphStore;
+    private readonly embedder;
+    readonly relationThreshold: number;
+    readonly fallbackPerRelationLimit: number;
+    constructor(graphStore: Pick<GraphStore, 'findTriplesByEntity' | 'findRelatedEntities'>, embedder: Pick<EmbeddingProvider, 'embed'>, options?: GraphEnumeratorOptions);
+    enumerate(plan: EnumerationPlan, limit?: number): Promise<EnumerationResult>;
+    private collectAnchorTriples;
+    private applyRelationFilter;
+    private fallbackTriples;
+    private projectAnswers;
+    private mergeAnswer;
+}
+export {};

package/dist/store/graph-enumerator.js

@@ -0,0 +1,185 @@
+function normalizeEntity(entity) {
+    return entity.trim().toLocaleLowerCase();
+}
+function cosineSimilarity(a, b) {
+    let dot = 0;
+    let aNorm = 0;
+    let bNorm = 0;
+    const length = Math.min(a.length, b.length);
+    for (let i = 0; i < length; i++) {
+        dot += a[i] * b[i];
+        aNorm += a[i] * a[i];
+        bNorm += b[i] * b[i];
+    }
+    if (aNorm === 0 || bNorm === 0)
+        return 0;
+    return dot / (Math.sqrt(aNorm) * Math.sqrt(bNorm));
+}
+function stableTripleCompare(a, b) {
+    return a.relation.localeCompare(b.relation)
+        || a.object.localeCompare(b.object)
+        || a.subject.localeCompare(b.subject)
+        || a.id.localeCompare(b.id);
+}
+export class GraphEnumerator {
+    graphStore;
+    embedder;
+    relationThreshold;
+    fallbackPerRelationLimit;
+    constructor(graphStore, embedder, options = {}) {
+        this.graphStore = graphStore;
+        this.embedder = embedder;
+        const envThreshold = Number(process.env.MR_ENUM_RELATION_THRESHOLD);
+        this.relationThreshold = options.relationThreshold
+            ?? (Number.isFinite(envThreshold) ? envThreshold : 0.5);
+        this.fallbackPerRelationLimit = options.fallbackPerRelationLimit ?? 50;
+    }
+    async enumerate(plan, limit = 1000) {
+        const anchors = [...new Set(plan.anchors.map(anchor => anchor.trim()).filter(Boolean))];
+        if (anchors.length === 0 || limit <= 0) {
+            return { answers: [], truncated: false, fallbackUsed: false };
+        }
+        const direction = plan.direction ?? 'both';
+        const perAnchor = new Map();
+        let fallbackUsed = false;
+        for (const anchor of anchors) {
+            const seededTriples = await this.collectAnchorTriples(anchor, direction, limit);
+            const filtered = await this.applyRelationFilter(seededTriples, plan.relationText);
+            fallbackUsed ||= filtered.fallbackUsed;
+            perAnchor.set(anchor, this.projectAnswers(direction, filtered.triples));
+        }
+        const requiredAnchors = anchors.length;
+        const merged = new Map();
+        for (const answers of perAnchor.values()) {
+            for (const [normalizedEntity, answer] of answers) {
+                const existing = merged.get(normalizedEntity);
+                if (!existing) {
+                    merged.set(normalizedEntity, { ...answer, anchorCount: 1 });
+                    continue;
+                }
+                existing.anchorCount++;
+                this.mergeAnswer(existing, answer);
+            }
+        }
+        const keepAll = plan.setMode === 'union';
+        const answers = Array.from(merged.values())
+            .filter(answer => keepAll || answer.anchorCount === requiredAnchors)
+            .map(({ anchorCount: _anchorCount, ...answer }) => answer)
+            .sort((a, b) => a.entity.localeCompare(b.entity));
+        const truncated = answers.length > limit;
+        return {
+            answers: answers.slice(0, limit),
+            truncated,
+            fallbackUsed,
+        };
+    }
+    async collectAnchorTriples(anchor, direction, limit) {
+        const bySeedAndId = new Map();
+        const add = (seed, triples) => {
+            for (const triple of triples) {
+                bySeedAndId.set(`${normalizeEntity(seed)}\0${triple.id}`, { seed, triple });
+            }
+        };
+        add(anchor, await this.graphStore.findTriplesByEntity(anchor, direction, limit));
+        const related = await this.graphStore.findRelatedEntities(anchor);
+        const aliases = new Set();
+        for (const triple of related) {
+            if (triple.subject.trim())
+                aliases.add(triple.subject);
+            if (triple.object.trim())
+                aliases.add(triple.object);
+        }
+        for (const alias of aliases) {
+            add(alias, await this.graphStore.findTriplesByEntity(alias, direction, limit));
+        }
+        return Array.from(bySeedAndId.values());
+    }
+    async applyRelationFilter(seededTriples, relationText) {
+        const triples = seededTriples.map(item => item.triple);
+        if (triples.length === 0)
+            return { triples: [], fallbackUsed: false };
+        if (!relationText || relationText.trim() === '') {
+            return { triples: this.fallbackTriples(seededTriples), fallbackUsed: true };
+        }
+        try {
+            const queryVector = await this.embedder.embed(relationText, 'query');
+            const relationVectors = new Map();
+            const filtered = [];
+            for (const item of seededTriples) {
+                const triple = item.triple;
+                let relationVector = relationVectors.get(triple.relation);
+                if (!relationVector) {
+                    relationVector = await this.embedder.embed(triple.relation, 'query');
+                    relationVectors.set(triple.relation, relationVector);
+                }
+                if (cosineSimilarity(queryVector, relationVector) >= this.relationThreshold) {
+                    filtered.push(item);
+                }
+            }
+            if (filtered.length > 0)
+                return { triples: filtered, fallbackUsed: false };
+        }
+        catch {
+            // Fall through to deterministic fallback on embedding failures.
+        }
+        return { triples: this.fallbackTriples(seededTriples), fallbackUsed: true };
+    }
+    fallbackTriples(seededTriples) {
+        const byRelation = new Map();
+        for (const item of [...seededTriples].sort((a, b) => stableTripleCompare(a.triple, b.triple))) {
+            const triple = item.triple;
+            const group = byRelation.get(triple.relation) ?? [];
+            if (group.length < this.fallbackPerRelationLimit) {
+                group.push(item);
+                byRelation.set(triple.relation, group);
+            }
+        }
+        return Array.from(byRelation.keys())
+            .sort()
+            .flatMap(relation => byRelation.get(relation) ?? []);
+    }
+    projectAnswers(direction, seededTriples) {
+        const projected = [];
+        for (const item of seededTriples) {
+            const triple = item.triple;
+            const normalizedSeed = normalizeEntity(item.seed);
+            const subjectMatches = normalizeEntity(triple.subject) === normalizedSeed;
+            const objectMatches = normalizeEntity(triple.object) === normalizedSeed;
+            if ((direction === 'out' || direction === 'both') && subjectMatches) {
+                projected.push({ entity: triple.object, normalizedEntity: normalizeEntity(triple.object), triple });
+            }
+            if ((direction === 'in' || direction === 'both') && objectMatches) {
+                projected.push({ entity: triple.subject, normalizedEntity: normalizeEntity(triple.subject), triple });
+            }
+        }
+        const answers = new Map();
+        for (const item of projected) {
+            if (!item.normalizedEntity)
+                continue;
+            const answer = answers.get(item.normalizedEntity) ?? {
+                entity: item.entity,
+                evidenceTriples: [],
+                sourceMemoryIds: [],
+            };
+            if (!answer.evidenceTriples.some(triple => triple.id === item.triple.id)) {
+                answer.evidenceTriples.push(item.triple);
+            }
+            if (item.triple.sourceMemoryId && !answer.sourceMemoryIds.includes(item.triple.sourceMemoryId)) {
+                answer.sourceMemoryIds.push(item.triple.sourceMemoryId);
+            }
+            answers.set(item.normalizedEntity, answer);
+        }
+        return answers;
+    }
+    mergeAnswer(target, source) {
+        for (const triple of source.evidenceTriples) {
+            if (!target.evidenceTriples.some(existing => existing.id === triple.id)) {
+                target.evidenceTriples.push(triple);
+            }
+        }
+        for (const id of source.sourceMemoryIds) {
+            if (!target.sourceMemoryIds.includes(id))
+                target.sourceMemoryIds.push(id);
+        }
+    }
+}

package/dist/store/graph-store.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Graph Store Engine — 知識圖譜三元組儲存
+ * memory-river
+ *
+ * 在 LanceDB 中建立獨立的 `graph_triples` table，儲存實體關係三元組。
+ * 使用 ANN 向量搜尋支援圖譜語意查詢。
+ *
+ * 設計原則：
+ * - 與 MemoryStore 共用同一組 LanceDB 連線（SSD 持久化 + RAM 加速）
+ * - 寫入時同步 embed 三元組文字（subject + relation + object）
+ * - 查詢時用 findRelatedEntities 做 ANN 相似度搜尋，擴展 Hook trigger
+ */
+export interface Triple {
+    subject: string;
+    relation: string;
+    object: string;
+}
+export interface GraphTriple extends Triple {
+    id: string;
+    sourceMemoryId: string;
+    createdAt: number;
+}
+export declare class GraphStore {
+    private readonly ssdRecoveryProbeIntervalMs;
+    private ramDb;
+    private ramTable;
+    private ssdDb;
+    private ssdTable;
+    private initPromise;
+    private embedder;
+    private ssdAvailable;
+    private ssdConsecutiveFailures;
+    private ssdRecoveryProbeTimer;
+    private ssdRecoveryProbeInFlight;
+    private vectorDim;
+    /**
+     * @param ramDb  RAM LanceDB 連接（由 MemoryStore 提供，透過 store.db）
+     * @param ssdDb  SSD LanceDB 連接（由 MemoryStore 提供，透過 store.ssd）
+     *
+     * ⚠️ Connections owned by MemoryStore — do not close.
+     * ⚠️ GraphStore MUST be constructed AFTER store.ensureInitialized().
+     */
+    constructor(ramDb: any, ssdDb: any, embedder: {
+        embed(text: string): Promise<number[]>;
+    }, vectorDim?: number, ssdRecoveryProbeIntervalMs?: number);
+    private handleSsdSuccess;
+    private handleSsdError;
+    private startSsdRecoveryProbe;
+    private probeSsdRecovery;
+    private stopSsdRecoveryProbe;
+    private ensureInitialized;
+    private doInitialize;
+    private initTable;
+    /**
+     * 將三元組文字 Embedding 化（用於 ANN 搜尋）
+     * 拼接方式：subject + relation + object
+     */
+    private embedTriple;
+    /**
+     * 寫入單筆三元組
+     */
+    addTriple(triple: Triple, sourceMemoryId: string): Promise<GraphTriple>;
+    /**
+     * 批量寫入三元組
+     */
+    addTriples(triples: Triple[], sourceMemoryId: string): Promise<GraphTriple[]>;
+    /**
+     * 用 Query 文字找相關實體（ANN 相似度搜尋）
+     * @param queryText 查詢文字
+     * @param limit 回傳上限
+     */
+    findRelatedEntities(queryText: string, limit?: number): Promise<GraphTriple[]>;
+    /**
+     * 找某實體的所有三元組（subject 匹配）
+     */
+    findTriplesBySubject(subject: string, limit?: number): Promise<GraphTriple[]>;
+    /**
+     * 找某實體的所有三元組（object 匹配）
+     */
+    findTriplesByObject(object: string, limit?: number): Promise<GraphTriple[]>;
+    findTriplesByEntity(entity: string, direction?: 'out' | 'in' | 'both', limit?: number): Promise<GraphTriple[]>;
+    /**
+     * 查詢與某記憶 ID 關聯的所有三元組
+     */
+    findTriplesByMemoryId(memoryId: string): Promise<GraphTriple[]>;
+    /**
+     * 圖譜語意擴展：給定 Query，回傳 subject/object 關鍵詞列表
+     * 用於 Hook trigger 時擴展 keyword matching 範圍
+     *
+     * @param queryText 原始 query
+     * @param limit 回傳數量上限
+     * @returns 擴展後的關鍵詞列表
+     */
+    expandQueryKeywords(queryText: string, limit?: number): Promise<string[]>;
+    /**
+     * 圖譜語意擴展（完整版）：回傳相關三元組 + 擴展後關鍵詞
+     * 供 Hook trigger 時使用
+     */
+    semanticExpand(queryText: string, limit?: number): Promise<{
+        triples: GraphTriple[];
+        expandedKeywords: string[];
+    }>;
+    /** 取得目前圖譜大小（除錯用） */
+    count(): Promise<number>;
+    /** Graceful shutdown — connections owned by MemoryStore, do not close here */
+    shutdown(): Promise<void>;
+}