@memory-river/core 0.2.0

package/dist/lifecycle/night-recovery.js

@@ -0,0 +1,107 @@
+import { randomUUID } from 'node:crypto';
+export const NIGHT_RECOVERY_THRESHOLD_MS = 24 * 60 * 60 * 1000;
+export function buildNightRecoveryMetadata(args) {
+    const metadata = { source: args.source };
+    for (const [key, value] of Object.entries(args)) {
+        if (key === 'source')
+            continue;
+        if (value !== undefined && value !== null)
+            metadata[key] = value;
+    }
+    return JSON.stringify(metadata);
+}
+export async function shouldRunNow(args) {
+    if (args.isRunning) {
+        return {
+            shouldRun: false,
+            reason: 'already_running',
+            lastSuccessfulRunTs: args.lastSuccessfulRunTs,
+        };
+    }
+    const lastSuccessfulRunTs = args.lastSuccessfulRunTs;
+    if (!lastSuccessfulRunTs) {
+        return {
+            shouldRun: true,
+            reason: 'no_success_record',
+            lastSuccessfulRunTs: null,
+        };
+    }
+    const nowMs = args.nowMs ?? Date.now();
+    const thresholdMs = args.thresholdMs ?? NIGHT_RECOVERY_THRESHOLD_MS;
+    if (nowMs - lastSuccessfulRunTs < thresholdMs) {
+        return {
+            shouldRun: false,
+            reason: 'recent_run',
+            lastSuccessfulRunTs,
+        };
+    }
+    return {
+        shouldRun: true,
+        reason: 'stale_run',
+        lastSuccessfulRunTs,
+    };
+}
+export async function healthCheck(options) {
+    const now = options.now ?? Date.now;
+    const runIdFactory = options.runIdFactory ?? randomUUID;
+    if (options.isRunning()) {
+        const decision = await shouldRunNow({
+            isRunning: true,
+            lastSuccessfulRunTs: null,
+            nowMs: now(),
+            thresholdMs: options.thresholdMs,
+        });
+        options.recordStat({
+            runId: runIdFactory(),
+            phase: 'recovery_skipped',
+            ts: now(),
+            outcome: 'skipped',
+            metadata: buildNightRecoveryMetadata({
+                source: options.source,
+                reason: 'already_running',
+            }),
+        });
+        return decision;
+    }
+    options.setRunning?.(true);
+    try {
+        const lastSuccessfulRunTs = await options.getLastSuccessfulRunTs();
+        const decision = await shouldRunNow({
+            isRunning: false,
+            lastSuccessfulRunTs,
+            nowMs: now(),
+            thresholdMs: options.thresholdMs,
+        });
+        if (!decision.shouldRun) {
+            options.recordStat({
+                runId: runIdFactory(),
+                phase: 'recovery_skipped',
+                ts: now(),
+                outcome: 'skipped',
+                metadata: buildNightRecoveryMetadata({
+                    source: options.source,
+                    reason: 'recent_run',
+                    lastSuccessfulRunTs,
+                }),
+            });
+            return decision;
+        }
+        if (options.source !== 'scheduled_timer') {
+            options.recordStat({
+                runId: runIdFactory(),
+                phase: 'recovery_triggered',
+                ts: now(),
+                outcome: 'triggered',
+                metadata: buildNightRecoveryMetadata({
+                    source: options.source,
+                    lastSuccessfulRunTs,
+                }),
+            });
+        }
+        await options.runNightConsolidation(options.source);
+        return decision;
+    }
+    finally {
+        options.setRunning?.(false);
+    }
+}

package/dist/paths.d.ts

@@ -0,0 +1,17 @@
+export interface MemoryRiverPaths {
+    dataDir: string;
+    ramDir?: string | null;
+}
+export declare function resolvePaths(p: MemoryRiverPaths): {
+    dbDir: string;
+    ramDbDir: string | null;
+    inboxDir: string;
+    walFile: string;
+    transcriptsDir: string;
+    trashDir: string;
+    stateDir: string;
+    gwmStateFile: string;
+    consolidationLog: string;
+    sessionSummaryDir: string;
+    rerankerCacheDir: string;
+};

package/dist/paths.js

@@ -0,0 +1,16 @@
+import { join } from 'node:path';
+export function resolvePaths(p) {
+    return {
+        dbDir: join(p.dataDir, 'lancedb'),
+        ramDbDir: p.ramDir ?? null,
+        inboxDir: join(p.dataDir, 'inbox'),
+        walFile: join(p.dataDir, 'wal.jsonl'),
+        transcriptsDir: join(p.dataDir, 'transcripts'),
+        trashDir: join(p.dataDir, '.trash'),
+        stateDir: join(p.dataDir, 'state'), // cleanup-state.json
+        gwmStateFile: join(p.dataDir, 'global-working-memory.json'),
+        consolidationLog: join(p.dataDir, 'consolidation-log.jsonl'),
+        sessionSummaryDir: join(p.dataDir, 'session-summaries'),
+        rerankerCacheDir: join(p.dataDir, '.model-cache'), // 原 ~/.cache/huggingface
+    };
+}

package/dist/pipeline/capsule-bridge.d.ts

@@ -0,0 +1,35 @@
+/**
+ * CapsuleBridge — 膠囊統一出口 (無損通道版)
+ *
+ * 原則：
+ * - 所有濃縮膠囊統一經過這裡寫入 shared inbox
+ * - inbox 路徑由 adapter 注入
+ * - 寫入格式：river_capsule_{timestamp}.txt（讓 inbox-watcher 能識別並處理）
+ */
+export interface CapsuleWriteOptions {
+    category?: string;
+    importance?: number;
+    metadata?: Record<string, unknown>;
+    /** 技能膠囊擴展欄位（inbox-watcher 讀取後入庫） */
+    capsuleType?: string;
+    skillName?: string;
+    triggerConditions?: string[];
+    executionSteps?: string[];
+    confidence?: number;
+    health?: number;
+}
+export declare class CapsuleBridge {
+    private inboxPath;
+    constructor(inboxPath: string);
+    /** 寫入濃縮膠囊到 shared inbox */
+    writeToInbox(text: string, opts?: CapsuleWriteOptions): Promise<string>;
+    /**
+     * 直接寫入 inbox JSON item（繞過 inbox-watcher 直接入庫的路徑）
+     * 用於 remember() 的高重要性記憶，直接生成完整 entry
+     */
+    writeInboxItem(text: string, opts: CapsuleWriteOptions): Promise<string>;
+    /** inbox 目前堆積的膠囊數量（除錯用） */
+    getPendingCount(): number;
+    /** inbox 目前堆積的 pending JSON 數量 */
+    getInboxItemCount(): number;
+}

package/dist/pipeline/capsule-bridge.js

@@ -0,0 +1,86 @@
+/**
+ * CapsuleBridge — 膠囊統一出口 (無損通道版)
+ *
+ * 原則：
+ * - 所有濃縮膠囊統一經過這裡寫入 shared inbox
+ * - inbox 路徑由 adapter 注入
+ * - 寫入格式：river_capsule_{timestamp}.txt（讓 inbox-watcher 能識別並處理）
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { randomUUID } from 'crypto';
+export class CapsuleBridge {
+    inboxPath;
+    constructor(inboxPath) {
+        this.inboxPath = inboxPath;
+        if (!fs.existsSync(this.inboxPath)) {
+            fs.mkdirSync(this.inboxPath, { recursive: true, mode: 0o700 });
+        }
+    }
+    /** 寫入濃縮膠囊到 shared inbox */
+    async writeToInbox(text, opts = {}) {
+        if (!fs.existsSync(this.inboxPath)) {
+            fs.mkdirSync(this.inboxPath, { recursive: true, mode: 0o700 });
+        }
+        // 🎯 P0 修復:加隨機後綴防同毫秒並行寫互相覆蓋（對照 writeInboxItem 的做法）
+        const filename = `river_capsule_${Date.now()}_${randomUUID().slice(0, 8)}.txt`;
+        const filePath = path.join(this.inboxPath, filename);
+        // 🎯 核心修復：使用展開運算子 (...opts.metadata) 確保所有基因無損繼承
+        const capsuleMeta = {
+            capsuleType: opts.capsuleType ?? 'working_memory',
+            skillName: opts.skillName,
+            triggerConditions: opts.triggerConditions ?? [],
+            executionSteps: opts.executionSteps ?? [],
+            confidence: opts.confidence ?? 0,
+            category: opts.category ?? 'history',
+            importance: opts.importance ?? 0.5,
+            health: opts.health ?? opts.metadata?.health, // 確保 health 不被遺漏
+            ...opts.metadata, // 將所有客製化標籤 (如 tags, type) 完整打包
+        };
+        // 🛠️ P1-5 修復：序列化完整 capsuleMeta（含 confidence/firstTimestamp/lastTimestamp）
+        const metaHeader = JSON.stringify({ ...capsuleMeta, timestamp: Date.now() });
+        const fileContent = `<!-- CAPSULE_META:${metaHeader} -->\n${text}`;
+        // 🛡️ 'wx' flag：檔案已存在就拒絕覆蓋（配合隨機後綴，理論上不該撞名）
+        await fs.promises.writeFile(filePath, fileContent, { encoding: 'utf-8', flag: 'wx', mode: 0o600 });
+        const logMeta = opts.capsuleType === 'skill_capsule'
+            ? ` [技能膠囊:${opts.skillName ?? ''} conf=${opts.confidence ?? 0}]`
+            : ` [健康度:${capsuleMeta.health ?? '永久'}]`;
+        console.log(`[CapsuleBridge] Capsule written to inbox: ${filename} (${text.length} chars)${logMeta}`);
+        return filePath;
+    }
+    /**
+     * 直接寫入 inbox JSON item（繞過 inbox-watcher 直接入庫的路徑）
+     * 用於 remember() 的高重要性記憶，直接生成完整 entry
+     */
+    async writeInboxItem(text, opts) {
+        if (!fs.existsSync(this.inboxPath)) {
+            fs.mkdirSync(this.inboxPath, { recursive: true, mode: 0o700 });
+        }
+        const filename = `pending_${Date.now()}_${Math.random().toString(36).slice(2, 6)}.json`;
+        const filePath = path.join(this.inboxPath, filename);
+        // 這裡原本寫得很好，有接住 ...opts.metadata
+        const item = {
+            text,
+            category: opts.category ?? 'other',
+            importance: opts.importance ?? 0.5,
+            tags: opts.metadata?.tags ?? [],
+            health: opts.health ?? opts.metadata?.health,
+            ...opts.metadata,
+        };
+        await fs.promises.writeFile(filePath, JSON.stringify(item, null, 2), { encoding: 'utf-8', mode: 0o600 });
+        console.log(`[CapsuleBridge] Inbox item written: ${filename} (category=${item.category}, importance=${item.importance})`);
+        return filePath;
+    }
+    /** inbox 目前堆積的膠囊數量（除錯用） */
+    getPendingCount() {
+        if (!fs.existsSync(this.inboxPath))
+            return 0;
+        return fs.readdirSync(this.inboxPath).filter((f) => f.startsWith('river_capsule_')).length;
+    }
+    /** inbox 目前堆積的 pending JSON 數量 */
+    getInboxItemCount() {
+        if (!fs.existsSync(this.inboxPath))
+            return 0;
+        return fs.readdirSync(this.inboxPath).filter((f) => f.startsWith('pending_') && f.endsWith('.json')).length;
+    }
+}

package/dist/pipeline/compact-request.d.ts

@@ -0,0 +1,30 @@
+export declare const COMPACT_REQUEST_VERSION = 1;
+export declare const COMPACT_REQUEST_FILENAME_PREFIX = "compact_request_";
+export interface AsyncCompactRequest {
+    trackingKey: string;
+    sessionId?: string;
+    sessionKey?: string;
+    originalTokens: number;
+    compressedTokens: number;
+    timestamp: number;
+}
+export interface CompactRequestInboxItem {
+    type: 'compact_request';
+    version: 1;
+    requestId: string;
+    trackingKey: string;
+    sessionId?: string;
+    sessionKey?: string;
+    originalTokens: number;
+    compressedTokens: number;
+    createdAt: number;
+    source: 'asyncCompactAfterAssemble';
+}
+export declare class CompactRequestSchemaError extends Error {
+    constructor(message: string);
+}
+export declare function buildCompactRequestFilename(item: CompactRequestInboxItem): string;
+export declare function isCompactRequestFilename(name: string): boolean;
+export declare function validateCompactRequest(raw: unknown): asserts raw is CompactRequestInboxItem;
+export declare function writeCompactRequest(inboxPath: string, item: CompactRequestInboxItem): Promise<string>;
+export declare function readCompactRequest(filePath: string): Promise<CompactRequestInboxItem>;

package/dist/pipeline/compact-request.js

@@ -0,0 +1,66 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+export const COMPACT_REQUEST_VERSION = 1;
+export const COMPACT_REQUEST_FILENAME_PREFIX = 'compact_request_';
+export class CompactRequestSchemaError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CompactRequestSchemaError';
+    }
+}
+export function buildCompactRequestFilename(item) {
+    return `${COMPACT_REQUEST_FILENAME_PREFIX}${item.createdAt}_${item.requestId}.json`;
+}
+export function isCompactRequestFilename(name) {
+    return name.startsWith(COMPACT_REQUEST_FILENAME_PREFIX) && name.endsWith('.json');
+}
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function assertNonEmptyString(value, field) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new CompactRequestSchemaError(`${field} must be a non-empty string`);
+    }
+}
+export function validateCompactRequest(raw) {
+    if (!raw || typeof raw !== 'object') {
+        throw new CompactRequestSchemaError('compact request must be an object');
+    }
+    const item = raw;
+    if (item.type !== 'compact_request')
+        throw new CompactRequestSchemaError('type must be compact_request');
+    if (item.version !== COMPACT_REQUEST_VERSION)
+        throw new CompactRequestSchemaError('version must be 1');
+    assertNonEmptyString(item.requestId, 'requestId');
+    assertNonEmptyString(item.trackingKey, 'trackingKey');
+    if (!isFiniteNumber(item.originalTokens))
+        throw new CompactRequestSchemaError('originalTokens must be a finite number');
+    if (!isFiniteNumber(item.compressedTokens))
+        throw new CompactRequestSchemaError('compressedTokens must be a finite number');
+    if (!isFiniteNumber(item.createdAt))
+        throw new CompactRequestSchemaError('createdAt must be a finite number');
+    if (item.source !== 'asyncCompactAfterAssemble') {
+        throw new CompactRequestSchemaError('source must be asyncCompactAfterAssemble');
+    }
+    if (item.sessionId !== undefined && typeof item.sessionId !== 'string') {
+        throw new CompactRequestSchemaError('sessionId must be a string when present');
+    }
+    if (item.sessionKey !== undefined && typeof item.sessionKey !== 'string') {
+        throw new CompactRequestSchemaError('sessionKey must be a string when present');
+    }
+}
+export async function writeCompactRequest(inboxPath, item) {
+    validateCompactRequest(item);
+    await fs.mkdir(inboxPath, { recursive: true });
+    const filename = buildCompactRequestFilename(item);
+    const finalPath = path.join(inboxPath, filename);
+    const tmpPath = path.join(inboxPath, `.${item.requestId}.tmp`);
+    await fs.writeFile(tmpPath, JSON.stringify(item, null, 2), 'utf-8');
+    await fs.rename(tmpPath, finalPath);
+    return finalPath;
+}
+export async function readCompactRequest(filePath) {
+    const raw = JSON.parse(await fs.readFile(filePath, 'utf-8'));
+    validateCompactRequest(raw);
+    return raw;
+}

package/dist/pipeline/inbox-watcher.d.ts

@@ -0,0 +1,112 @@
+/**
+ * InboxWatcher - 記憶 inbox 觀察者 + River Capsule 處理器
+ * memory-river
+ * * 改造要點：
+ * - inbox 路徑從構造函數參數傳入（不再 hardcode）
+ * - import 改為來自同目錄的本地模組
+ * - 保留 writeInbox() static 方法給 CapsuleBridge 呼叫
+ * - processRiverCapsule() 方法處理 river_capsule_*.txt 檔
+ */
+import { MemoryStore } from "../store/store-v4.js";
+import { StatusManager } from "../store/status-manager.js";
+import { Embedder } from "../providers/embedder-v5.js";
+import { CausalEngine } from "../cognition/causal-engine.js";
+import { HooksEngine } from "../cognition/hooks-engine.js";
+import { ConflictDetector } from "../cognition/conflict-detector.js";
+import { GraphStore } from "../store/graph-store.js";
+import type { LlmClient } from "../ports.js";
+import { type AsyncCompactRequest } from "./compact-request.js";
+export declare class InboxWatcher {
+    private store;
+    private embedder;
+    private causalEngine;
+    private hooksEngine;
+    private graphStore;
+    private llm;
+    private inboxPath;
+    private pollIntervalMs;
+    private conflictDetector;
+    private statusManager;
+    private compactRequestProcessor;
+    private static readonly RIVER_CAPSULE_FAILURE_THRESHOLD;
+    private static readonly RIVER_CAPSULE_FAILURE_LRU_MAX;
+    private intervalId;
+    private isProcessing;
+    private processingStartedAt;
+    private started;
+    private fatalErrorCount;
+    private riverCapsuleFailureCounts;
+    private parentIdLocks;
+    private withParentLock;
+    private parseMetadata;
+    constructor(store: MemoryStore, embedder: Embedder, causalEngine: CausalEngine, hooksEngine: HooksEngine | null, graphStore: GraphStore | null, llm: LlmClient, inboxPath: string, pollIntervalMs: number | undefined, conflictDetector: ConflictDetector | undefined, statusManager: StatusManager, compactRequestProcessor: (req: AsyncCompactRequest) => Promise<void>);
+    setDependencies(hooksEngine: HooksEngine, graphStore: GraphStore): void;
+    private countPendingFiles;
+    private runProcessInbox;
+    private recordFatalError;
+    private setRiverCapsuleFailureCount;
+    private classifyRiverCapsuleReason;
+    private recordRiverCapsuleStat;
+    private moveRiverCapsuleToError;
+    /**
+     * 從 river capsule meta 推導 stat / failure counter 用的 key。
+     *
+     * 與 sessionIdentity 主鏈不同：river capsule 的 metadata 可能巢狀
+     * （capsuleMeta.metadata.sessionKey），且最後保底是 filename，不是 'global'。
+     * 因此先把巢狀欄位攤平成標準 payload，再交給 sessionIdentity 解析；
+     * 若 isFallback（payload 完全沒有 session 身分）才退到 filename。
+     */
+    private getRiverCapsuleSessionKey;
+    start(): void;
+    stop(): void;
+    private processCompactRequest;
+    private executeCompactRequest;
+    private processInbox;
+    processRiverCapsule(filePath: string): Promise<{
+        ok: boolean;
+        reason?: string;
+        sessionKey?: string;
+    }>;
+    private processFile;
+    /**
+     * _processMemoryEntry — 濃縮膠囊寫入記憶庫的核心 pipeline
+     * 不處理檔案狀態（由 processFile 統一管理 rename/delete）
+     */
+    private _processMemoryEntry;
+    static writeInbox(inboxPath: string, item: {
+        text: string;
+        category: string;
+        importance?: number;
+        parentId?: string;
+        capsuleType?: string;
+        skillName?: string;
+        triggerConditions?: string[];
+        executionSteps?: string[];
+        confidence?: number;
+        metadata?: Record<string, unknown>;
+        tool_result?: Record<string, unknown> | null;
+    }): Promise<string>;
+    /**
+     * 從記憶文字萃取技能名稱（簡單關鍵詞法，fallback）
+     */
+    private extractSkillNameFromText;
+    /**
+     * 從記憶文字抽取觸發關鍵詞（簡單枚舉法）
+     */
+    private extractTriggersFromText;
+    /**
+     * extractSlot — LLM 結構化抽取
+     * 輸入文字 → 判斷是否可結構化 → 輸出 slotKey / slotValue / confidence / extractionDomain
+     *
+     * confidence 等級：
+     * >= 0.8：高可信，建立 Slot，自動 supersedes 檢查
+     * 0.5–0.8：中可信，寫入待審核池（Night Consolidation 處理）
+     * < 0.5：低可信，純 free-text，不建 Slot
+     */
+    private extractSlot;
+    /**
+     * checkSupersedes — 查詢同 slotKey 的所有 active 舊版本
+     * @returns 被取代的舊 entry id 清單
+     */
+    private checkSupersedes;
+}