@memory-river/core 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { createMemoryRiver, type MemoryRiver, type MemoryRiverConfig, type MemoryRiverDeps, type MemoryUpdate, type RehydrateRequest, type SessionHint, } from './api.js';
+export type { EmbeddingProvider, LlmClient, Logger, Notifier, SessionFileAccess, } from './ports.js';
+export type { ContextMessage, EnumerationPlan, MemoryEntry, MemorySearchResult, MemoryCategory, MemoryStatus, SkillCapsuleV2, SkillDef, SkillIndexEntry, StatusChangeRequest, StatusChangeResult, } from './types.js';
+export { Embedder as OllamaEmbedding } from './providers/embedder-v5.js';
+export { getDevShmFreeBytes, resolveRamDbPath, MIN_RAM_DB_BYTES } from './storage.js';
+export type { StorageMode } from './storage.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createMemoryRiver, } from './api.js';
+export { Embedder as OllamaEmbedding } from './providers/embedder-v5.js';
+export { getDevShmFreeBytes, resolveRamDbPath, MIN_RAM_DB_BYTES } from './storage.js';

package/dist/lifecycle/cleanup-engine.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Cleanup - 記憶代謝 (V4 升級版)
+ * memory-lance-v4
+ * * 核心原則：
+ * - 廢棄舊版扣減 importance 的邏輯
+ * - 統一轉交由 store-v4.ts 內的 decayMemories 執行 (基於 Health 系統)
+ * - 管理員指令直接與 V4 健康度生態系掛鉤
+ * - 刪除的記憶進入注入的回收桶，N 天後自動清除
+ */
+import { MemoryStore } from "../store/store-v4.js";
+export interface CleanupEngineConfig {
+    enabled: boolean;
+    decayDays: number;
+    deleteBelow: number;
+    coreCategories?: string[];
+    coreImportanceThreshold?: number;
+    skillCapsuleProtection?: boolean;
+    useTrash?: boolean;
+    dryRun?: boolean;
+    /** 回收桶路徑 */
+    trashPath: string;
+    /** 回收桶保留天數（預設 7 天） */
+    trashRetentionDays?: number;
+    /** 是否啟用回收桶自動清除（預設 true） */
+    enableTrashAutoPurge?: boolean;
+}
+export interface CleanupRunOptions {
+    dryRunOverride?: boolean;
+    maxDelete?: number;
+    maxDecay?: number;
+}
+export interface CleanupRunResult {
+    deleted: number;
+    updated: number;
+    wouldDelete: number;
+    wouldDecay: number;
+    deferredDelete: number;
+    deferredDecay: number;
+    deleteCandidateSummary: {
+        count: number;
+        firstId: string | null;
+        lastId: string | null;
+        minCreatedAt: number | null;
+        maxCreatedAt: number | null;
+        createdAtByDay: Record<string, number>;
+    };
+    dryRun: boolean;
+}
+export declare class CleanupEngine {
+    private store;
+    private config;
+    private static _instance;
+    private readonly trashPath;
+    private readonly trashRetentionDays;
+    private readonly enableTrashAutoPurge;
+    private readonly useTrash;
+    private readonly dryRun;
+    constructor(store: MemoryStore, config: CleanupEngineConfig);
+    static getInstance(): CleanupEngine;
+    static setInstance(inst: CleanupEngine): void;
+    /**
+     * Session 結束鉤子 — 由 index.ts 的 session:end hook 觸發。
+     * 非同步、不阻塞：以 fire-and-forget 方式驅動健康度衰退。
+     */
+    onSessionEnd(sessionId: string, _messages: unknown[], source?: string): void;
+    /**
+     * 執行智能清理 (調用 V4 核心代謝引擎)
+     */
+    runSmartCleanup(source?: string, options?: CleanupRunOptions): Promise<CleanupRunResult>;
+    /**
+     * 刪除記憶：先搬到回收桶，再從 LanceDB 移除。
+     * 檔名格式：{id}_{timestamp}.json（含完整 entry 內容）
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * 掃描回收桶，自動清除超過 retention 天數的檔案。
+     * Idempotent：多次呼叫不會重複處理。
+     */
+    purgeExpiredTrash(): Promise<number>;
+}

package/dist/lifecycle/cleanup-engine.js

@@ -0,0 +1,162 @@
+/**
+ * Cleanup - 記憶代謝 (V4 升級版)
+ * memory-lance-v4
+ * * 核心原則：
+ * - 廢棄舊版扣減 importance 的邏輯
+ * - 統一轉交由 store-v4.ts 內的 decayMemories 執行 (基於 Health 系統)
+ * - 管理員指令直接與 V4 健康度生態系掛鉤
+ * - 刪除的記憶進入注入的回收桶，N 天後自動清除
+ */
+import * as fs from "fs";
+import * as path from "path";
+export class CleanupEngine {
+    store;
+    config;
+    static _instance = null;
+    trashPath;
+    trashRetentionDays;
+    enableTrashAutoPurge;
+    useTrash;
+    dryRun;
+    constructor(store, config) {
+        this.store = store;
+        this.config = config;
+        this.trashPath = config.trashPath;
+        this.trashRetentionDays = config.trashRetentionDays ?? 7;
+        this.enableTrashAutoPurge = config.enableTrashAutoPurge ?? true;
+        this.useTrash = config.useTrash ?? true;
+        this.dryRun = config.dryRun ?? false;
+        // 確保 trash 目錄存在（idempotent）
+        if (!fs.existsSync(this.trashPath)) {
+            fs.mkdirSync(this.trashPath, { recursive: true });
+        }
+    }
+    static getInstance() {
+        if (!CleanupEngine._instance) {
+            throw new Error('[CleanupEngine] getInstance() called before initialize(). Call CleanupEngine.getInstance() only after register() has instantiated it.');
+        }
+        return CleanupEngine._instance;
+    }
+    static setInstance(inst) {
+        CleanupEngine._instance = inst;
+    }
+    /**
+     * Session 結束鉤子 — 由 index.ts 的 session:end hook 觸發。
+     * 非同步、不阻塞：以 fire-and-forget 方式驅動健康度衰退。
+     */
+    onSessionEnd(sessionId, _messages, source = 'session-end') {
+        console.log(`[CleanupEngine] session_end triggered, sessionId=${sessionId}, source=${source}`);
+        void this.runSmartCleanup(source).catch((err) => console.warn(`[CleanupEngine] onSessionEnd cleanup failed for ${sessionId}:`, err));
+    }
+    /**
+     * 執行智能清理 (調用 V4 核心代謝引擎)
+     */
+    async runSmartCleanup(source = 'manual', options = {}) {
+        if (!this.config.enabled) {
+            return {
+                deleted: 0,
+                updated: 0,
+                wouldDelete: 0,
+                wouldDecay: 0,
+                deferredDelete: 0,
+                deferredDecay: 0,
+                deleteCandidateSummary: { count: 0, firstId: null, lastId: null, minCreatedAt: null, maxCreatedAt: null, createdAtByDay: {} },
+                dryRun: true,
+            };
+        }
+        const effectiveDryRun = options.dryRunOverride ?? this.dryRun;
+        const result = await this.store.decayMemories(5, this.config.deleteBelow, {
+            coreCategories: this.config.coreCategories,
+            coreImportanceThreshold: this.config.coreImportanceThreshold,
+            skillCapsuleProtection: this.config.skillCapsuleProtection ?? true,
+            dryRun: effectiveDryRun,
+            deleteWith: this.useTrash ? this.delete.bind(this) : undefined,
+            maxDelete: options.maxDelete,
+            maxDecay: options.maxDecay,
+        });
+        console.log(`[CleanupEngine] decayMemories: protected=${result.coreProtected} wouldDecay=${result.wouldDecay} wouldDelete=${result.wouldDelete}, source=${source}`);
+        if (effectiveDryRun) {
+            console.log(`[CleanupEngine] dry-run summary: would decay ${result.wouldDecay}, would delete ${result.wouldDelete}, source=${source}`);
+        }
+        else {
+            console.log(`[CleanupEngine] decayed ${result.decayed} memories, deleted ${result.deleted} memories (dryRun=false), source=${source}`);
+            if (result.deferredDelete > 0 || result.deferredDecay > 0) {
+                console.log(`[CleanupEngine] ${source}: hit limit, deferred ${result.deferredDelete} delete candidates and ${result.deferredDecay} decay candidates to next run`);
+            }
+        }
+        // 順便執行回收桶 auto-purge（idempotent）
+        if (!effectiveDryRun && this.enableTrashAutoPurge) {
+            await this.purgeExpiredTrash();
+        }
+        return {
+            deleted: result.deleted,
+            updated: result.decayed,
+            wouldDelete: result.wouldDelete,
+            wouldDecay: result.wouldDecay,
+            deferredDelete: result.deferredDelete,
+            deferredDecay: result.deferredDecay,
+            deleteCandidateSummary: result.deleteCandidateSummary,
+            dryRun: effectiveDryRun,
+        };
+    }
+    // ═══════════════════════════════════════════════════════════
+    // 回收桶（Trash）管理
+    // ═══════════════════════════════════════════════════════════
+    /**
+     * 刪除記憶：先搬到回收桶，再從 LanceDB 移除。
+     * 檔名格式：{id}_{timestamp}.json（含完整 entry 內容）
+     */
+    async delete(id) {
+        const entry = await this.store.getById(id, true);
+        if (!entry)
+            return false;
+        // 把完整 entry 寫入 trash
+        const timestamp = Date.now();
+        const trashFilename = `${id}_${timestamp}.json`;
+        const trashFilePath = path.join(this.trashPath, trashFilename);
+        fs.writeFileSync(trashFilePath, JSON.stringify(entry, null, 2), "utf-8");
+        console.log(`[Cleanup] Memory ${id.slice(0, 8)} moved to trash: ${trashFilename} (retained for ${this.trashRetentionDays} days)`);
+        // 從 LanceDB 真正刪除
+        await this.store.delete(id);
+        return true;
+    }
+    /**
+     * 掃描回收桶，自動清除超過 retention 天數的檔案。
+     * Idempotent：多次呼叫不會重複處理。
+     */
+    async purgeExpiredTrash() {
+        if (!fs.existsSync(this.trashPath)) {
+            return 0;
+        }
+        const now = Date.now();
+        const retentionMs = this.trashRetentionDays * 24 * 60 * 60 * 1000;
+        const cutoff = now - retentionMs;
+        let purgedCount = 0;
+        let processedFiles = new Set();
+        const files = fs.readdirSync(this.trashPath);
+        for (const file of files) {
+            // 只處理格式正確的 trash 檔案
+            if (!file.endsWith(".json"))
+                continue;
+            const filePath = path.join(this.trashPath, file);
+            const stat = fs.statSync(filePath);
+            // 只刪除超期檔案
+            if (stat.mtimeMs < cutoff) {
+                // Idempotent check：已處理過同樣時間戳的檔案則跳過（不重複）
+                const timestampFromName = file.split("_").pop()?.replace(".json", "");
+                if (timestampFromName && processedFiles.has(timestampFromName)) {
+                    continue;
+                }
+                if (timestampFromName)
+                    processedFiles.add(timestampFromName);
+                fs.unlinkSync(filePath);
+                console.log(`[Cleanup] Automatically purged trash file: ${file} (retained for more than ${this.trashRetentionDays} days)`);
+                purgedCount++;
+            }
+        }
+        if (purgedCount > 0) {
+            console.log(`[Cleanup] Trash purge complete: ${purgedCount} expired files permanently deleted`);
+        }
+        return purgedCount;
+    }
+}

package/dist/lifecycle/cleanup-state.d.ts

@@ -0,0 +1,34 @@
+export declare const CLEANUP_RECOVERY_INTERVAL_MS: number;
+export interface CleanupState {
+    lastSuccessfulRunAt: number;
+    lastDeleteCount: number;
+    lastDecayCount: number;
+}
+export interface StartupRecoveryLimits {
+    maxStartupDelete: number;
+    maxStartupDecay: number;
+}
+export type StartupRecoveryDecision = {
+    shouldRun: true;
+    reason: 'missing-state' | 'stale-state';
+    hoursSinceLastSuccess: number | null;
+} | {
+    shouldRun: false;
+    reason: 'recent-success';
+    hoursSinceLastSuccess: number;
+};
+export type StartupRecoveryMode = {
+    dryRunOnly: true;
+    maxDelete: number;
+    maxDecay: number;
+    reason: 'backlog-too-large';
+} | {
+    dryRunOnly: false;
+    maxDelete: number;
+    maxDecay: number;
+    reason: 'normal' | 'capped';
+};
+export declare function readCleanupState(filePath: string): CleanupState | null;
+export declare function writeCleanupState(state: CleanupState, filePath: string): void;
+export declare function shouldRunStartupRecovery(state: CleanupState | null, nowMs?: number): StartupRecoveryDecision;
+export declare function chooseStartupRecoveryMode(estimatedDelete: number, limits: StartupRecoveryLimits): StartupRecoveryMode;

package/dist/lifecycle/cleanup-state.js

@@ -0,0 +1,50 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export const CLEANUP_RECOVERY_INTERVAL_MS = 25 * 60 * 60 * 1000;
+export function readCleanupState(filePath) {
+    try {
+        if (!fs.existsSync(filePath))
+            return null;
+        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+        if (typeof parsed.lastSuccessfulRunAt !== 'number')
+            return null;
+        return {
+            lastSuccessfulRunAt: parsed.lastSuccessfulRunAt,
+            lastDeleteCount: typeof parsed.lastDeleteCount === 'number' ? parsed.lastDeleteCount : 0,
+            lastDecayCount: typeof parsed.lastDecayCount === 'number' ? parsed.lastDecayCount : 0,
+        };
+    }
+    catch (err) {
+        console.warn('[CleanupEngine] cleanup-state read failed:', err?.message ?? err);
+        return null;
+    }
+}
+export function writeCleanupState(state, filePath) {
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(filePath, `${JSON.stringify(state, null, 2)}\n`, 'utf-8');
+}
+export function shouldRunStartupRecovery(state, nowMs = Date.now()) {
+    if (!state) {
+        return { shouldRun: true, reason: 'missing-state', hoursSinceLastSuccess: null };
+    }
+    const elapsedMs = nowMs - state.lastSuccessfulRunAt;
+    const hoursSinceLastSuccess = Math.max(0, elapsedMs / (60 * 60 * 1000));
+    if (elapsedMs < CLEANUP_RECOVERY_INTERVAL_MS) {
+        return { shouldRun: false, reason: 'recent-success', hoursSinceLastSuccess };
+    }
+    return { shouldRun: true, reason: 'stale-state', hoursSinceLastSuccess };
+}
+export function chooseStartupRecoveryMode(estimatedDelete, limits) {
+    const maxDelete = Math.max(0, Math.floor(limits.maxStartupDelete));
+    const maxDecay = Math.max(0, Math.floor(limits.maxStartupDecay));
+    if (estimatedDelete > maxDelete * 2) {
+        return { dryRunOnly: true, maxDelete, maxDecay, reason: 'backlog-too-large' };
+    }
+    return {
+        dryRunOnly: false,
+        maxDelete,
+        maxDecay,
+        reason: estimatedDelete > maxDelete ? 'capped' : 'normal',
+    };
+}

package/dist/lifecycle/night-consolidation.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Night Consolidation — 記憶夜間整理模組
+ *
+ * 每天凌晨（或手動觸發）自動執行：
+ * 1. 取出當日所有新寫入的記憶
+ * 2. 依 slotKey 分組，找出重覆/碎片記憶
+ * 3. 丟 MiniMax M2.7 (thinking=high) 做品質把關決策
+ * 4. 執行：合併、刪除、更新 confidence/category
+ * 5. 寫入 consolidation 日誌
+ */
+import type { MemoryEntry, MemoryCategory } from '../types.js';
+import type { StatusManager } from '../store/status-manager.js';
+import { type NightRecoverySource } from './night-recovery.js';
+import type { LlmClient, Notifier } from '../ports.js';
+export interface ConsolidationDecision {
+    action: 'merge' | 'delete' | 'update' | 'keep' | 'deprecated';
+    memoryId: string;
+    reason: string;
+    mergeIntoId?: string;
+    newCategory?: MemoryCategory;
+    newConfidence?: number;
+    newSlotKey?: string;
+    newText?: string;
+}
+export interface ConsolidationPlan {
+    decisions: ConsolidationDecision[];
+    summary: string;
+    processedCount: number;
+    mergedCount: number;
+    deletedCount: number;
+    updatedCount: number;
+    keptCount: number;
+}
+export interface ConsolidationResult {
+    plan: ConsolidationPlan;
+    executedAt: number;
+    durationMs: number;
+    errors: string[];
+}
+export declare class NightConsolidator {
+    private store;
+    private _options;
+    private logPath;
+    constructor(store: {
+        queryAll(limit?: number): Promise<MemoryEntry[]>;
+        getById(id: string, includeAllStatus?: boolean): Promise<MemoryEntry | null>;
+        update(id: string, updates: Partial<MemoryEntry>): Promise<boolean>;
+        delete(id: string): Promise<boolean>;
+        searchBySlotKey(slotKey: string): Promise<MemoryEntry[]>;
+        recordNightConsolidationStat?(record: {
+            runId: string;
+            phase: string;
+            ts?: number;
+            outcome?: string | null;
+            durationMs?: number | null;
+            candidateCount?: number | null;
+            scannedCount?: number | null;
+            decisionCount?: number | null;
+            mergeCount?: number | null;
+            deleteCount?: number | null;
+            deprecatedCount?: number | null;
+            updateCount?: number | null;
+            keepCount?: number | null;
+            attemptedCount?: number | null;
+            failedCount?: number | null;
+            batchIndex?: number | null;
+            batchSize?: number | null;
+            driftMs?: number | null;
+            scheduledFor?: number | null;
+            errorMessage?: string | null;
+            metadata?: string | Record<string, unknown> | null;
+        }): Promise<void>;
+    }, _options: {
+        concentrator?: LlmClient;
+        statusManager: StatusManager;
+        notifier?: Notifier;
+    }, consolidationLog: string);
+    private recordStat;
+    private statMetadata;
+    private _broadcast;
+    /**
+     * 執行夜間整理（當日記憶）
+     */
+    consolidateToday(runId?: `${string}-${string}-${string}-${string}-${string}`, source?: NightRecoverySource): Promise<ConsolidationResult>;
+    /**
+     * 執行夜間整理（指定時間範圍）
+     * @param range 'today' | 'yesterday' | number (days ago)
+     */
+    consolidateRange(range: 'today' | 'yesterday' | number, runId?: `${string}-${string}-${string}-${string}-${string}`, source?: NightRecoverySource): Promise<ConsolidationResult>;
+    private llmDecide;
+    private _llmDecideBatch;
+    private callAgent;
+    private executePlan;
+    private parseMeta;
+    /**
+     * checkSupersedes — 查詢同 slotKey 的所有 active 舊版本
+     * @returns 被取代的舊 entry id 清單
+     */
+    private checkSupersedes;
+    private extractJson;
+    private writeLog;
+}