@memory-river/core 0.2.0

package/dist/engine.d.ts

@@ -0,0 +1,402 @@
+import { MemoryStore } from './store/store-v4.js';
+import { type HybridSearchResponse } from './retrieval/retriever-v4.js';
+import { type InjectedMemory } from './cognition/causal-attribution.js';
+import { type CleanupState, type StartupRecoveryLimits } from './lifecycle/cleanup-state.js';
+import type { ArchiveSnapshotResult } from './transcript/transcript-archive.js';
+import { type PluginConfig, type ContextMessage, type EnumerationPlan, type MemoryEntry, type MemorySearchResult, type SkillCapsuleV2, type SkillDef, type SkillIndexEntry, type StatusChangeRequest, type StatusChangeResult, type SubsystemEffectivenessEvent } from './types.js';
+import type { EmbeddingProvider, LlmClient, Logger } from './ports.js';
+import { type SessionIdentity } from './util/session-identity.js';
+import { type AsyncCompactRequest } from './pipeline/compact-request.js';
+import { type NightRecoverySource } from './lifecycle/night-recovery.js';
+export interface MemoryRiverEngineDeps {
+    paths: {
+        rerankerCacheDir: string;
+        consolidationLog: string;
+        stateDir: string;
+        walFile: string;
+        sessionSummaryDir: string;
+        trashDir: string;
+        gwmStateFile: string;
+    };
+    transcriptArchive: {
+        archiveSnapshot: any;
+        clearTranscriptCache: () => void;
+    };
+    notifier?: import('./ports.js').Notifier;
+    embedder?: EmbeddingProvider;
+    llm?: LlmClient;
+    logger?: Logger;
+    deriveSessionFile(args: {
+        sessionId?: string;
+        sessionKey?: string;
+    }): string | null;
+    ollamaUrl: string;
+    geminiApiKey: string;
+    deepseekApiKey: string;
+}
+type SessionFileMappingRecord = {
+    trackingKey: string;
+    sessionKey?: string;
+    sessionId?: string;
+    sessionFile: string;
+    updatedAt: number;
+    source: 'maintain' | 'compact' | 'fallback';
+};
+type RecentLlmIdentity = {
+    model: string | null;
+    provider: string | null;
+    updatedAt: number;
+};
+type GwmPendingEpisode = {
+    episodeId: string;
+    injectionOrdinal: number;
+    queryHash: string;
+    similarityAtInjection: number;
+    preInjectDriftRoundCount: number | null;
+    roundsSinceLastInjection: number | null;
+    taskDescriptionHash: string;
+    llmModel: string | null;
+    llmProvider: string | null;
+};
+type GwmSessionEpisodeState = {
+    injectionCount: number;
+    turnIndex: number;
+    lastInjectionTurnIndex: number | null;
+    pendingEpisode: GwmPendingEpisode | null;
+};
+export declare class MemoryRiverEngine {
+    private config;
+    private deps;
+    constructor(config: Required<PluginConfig>, deps: MemoryRiverEngineDeps);
+    configure(config: Required<PluginConfig>, deps: MemoryRiverEngineDeps): void;
+    private activeConcentrator;
+    private retrieverRef;
+    private isAutoRecallEnabled;
+    private gwmRef;
+    private cleanupEngineRef;
+    private nightConsolidatorRef;
+    private memoryStoreRef;
+    private embedderRef;
+    private hooksEngineRef;
+    private graphStoreRef;
+    private inboxWatcherRef;
+    private causalEngineRef;
+    private conflictDetectorRef;
+    private statusManagerRef;
+    private capsuleBridgeRef;
+    private pluginInitPromise;
+    private pluginInitialized;
+    private pluginInitError;
+    private fallbackObserverRegistered;
+    private cleanupEngineInstanceRegistered;
+    private nightTimerId;
+    private nightIntervalId;
+    private nightHealthCheckIntervalId;
+    private nightStartupRecoveryTimerId;
+    private nightConsolidatorIsRunning;
+    private lastNightConsolidatorSuccessfulRunAt;
+    private cleanupTimeoutId;
+    private cleanupIntervalId;
+    private lastCleanupSuccessfulRunAt;
+    private activePluginConfig;
+    initFailedResult(err: any): {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    };
+    recordPluginInitSmokeStat(store: any, outcome: 'succeeded' | 'failed', err?: any): Promise<void>;
+    private sessionTokenWatermark;
+    private sessionCompactWatermark;
+    private sessionFileMappings;
+    private recentlyCompacted;
+    private lastArchivedLineCount;
+    private maintainLocks;
+    private skillLocks;
+    private queuedAsyncCompactKeys;
+    private runningAsyncCompactKeys;
+    private pendingAttribution;
+    private recentLlmIdentityByKey;
+    private gwmSessionState;
+    private lastObservedSessionIdentity;
+    pickNonEmptyString(value: unknown): string | null;
+    addAttributionKey(keys: Set<string>, prefix: string, value: unknown): void;
+    extractAttributionRequestKeyFromArgs(...args: unknown[]): string | null;
+    extractAutoRecallResultsObserverFromArgs(...args: unknown[]): ((event: {
+        query: string;
+        results: MemorySearchResult[];
+    }) => void) | null;
+    attributionKeysFromIdentity(identity: SessionIdentity, requestKey?: string | null): string[];
+    attributionKeysFromLlmOutput(event: any, ctx: any): string[];
+    getRecentLlmIdentityForKeys(keys: string[]): RecentLlmIdentity | null;
+    getOrCreateGwmSessionState(sessionKey: string): GwmSessionEpisodeState;
+    cleanupPendingAttribution(now?: number): void;
+    rememberInjectedMemories(identity: SessionIdentity, injected: InjectedMemory[], requestKey?: string | null): void;
+    takePendingAttribution(keys: string[]): InjectedMemory[];
+    getAsyncCompactConcurrency(): number;
+    countFileLines(filePath: string): Promise<number>;
+    enqueueAsyncCompact(req: AsyncCompactRequest): void;
+    processAsyncCompactRequest(req: AsyncCompactRequest): Promise<void>;
+    get asyncCompactTestHooks(): {
+        enqueue: (req: AsyncCompactRequest) => void;
+        reset: () => void;
+        setInboxPath: (inboxPath: string) => void;
+        isQueued: (trackingKey: string) => boolean;
+    };
+    setWatermark(canonicalKey: string, value: number): void;
+    setCompactWatermark(canonicalKey: string, value: number): void;
+    setSessionFileMapping(canonicalKey: string, record: SessionFileMappingRecord): void;
+    setArchivedLineCount(key: string, sessionId: string | null, lineCount: number): void;
+    resolveArchivedLineCount(store: MemoryStore | null, canonicalKey: string, sessionId: string | null): Promise<{
+        sessionId: string | null;
+        lineCount: number;
+    }>;
+    persistArchivedLineCount(store: MemoryStore | null, canonicalKey: string, sessionId: string | null, lineCount: number): Promise<void>;
+    markRecentlyCompacted(canonicalKey: string): void;
+    wasRecentlyCompacted(canonicalKey: string): boolean;
+    deriveSessionFileFromStaticRule(args: {
+        sessionId?: string;
+        sessionKey?: string;
+    }): string | null;
+    resolveSessionFile(args: {
+        sessionKey?: string;
+        sessionId?: string;
+        session?: any;
+    }): {
+        sessionFile: string | null;
+        source: 'cache' | 'fallback' | 'none';
+    };
+    init(): Promise<void>;
+    clearNightConsolidatorTimers(): void;
+    recordNightConsolidationStat(stat: Parameters<MemoryStore['recordNightConsolidationStat']>[0]): void;
+    getLastSuccessfulNightRunTs(): Promise<number | null>;
+    runNightConsolidatorNow(runId?: `${string}-${string}-${string}-${string}-${string}`, scheduledFor?: number, source?: NightRecoverySource): Promise<void>;
+    tryRunNightConsolidator(source: NightRecoverySource, runId?: `${string}-${string}-${string}-${string}-${string}`, scheduledFor?: number): Promise<void>;
+    scheduleNightConsolidator(): void;
+    clearCleanupEngineTimers(): void;
+    runCleanupEngineNow(source: 'daily-schedule' | 'startup-recovery' | 'session-end'): Promise<void>;
+    recordCleanupSuccess(result: {
+        deleted: number;
+        updated: number;
+    }): void;
+    getStartupRecoveryLimits(): StartupRecoveryLimits;
+    formatHours(hours: number): string;
+    formatCandidateSummary(summary: {
+        count: number;
+        firstId: string | null;
+        lastId: string | null;
+        minCreatedAt: number | null;
+        maxCreatedAt: number | null;
+        createdAtByDay: Record<string, number>;
+    }): string;
+    shouldScheduleStartupRecoveryFromState(state: CleanupState | null, nowMs?: number): import("./lifecycle/cleanup-state.js").StartupRecoveryDecision;
+    runStartupRecoveryWithProtection(): Promise<void>;
+    scheduleCleanupEngine(): void;
+    /** 提取訊息陣列 */
+    extractMessages(...args: any[]): any[];
+    normalizeFrameworkLine(line: string): string;
+    metadataHeadingLength(text: string): number;
+    stripLeadingUntrustedMetadataBlocks(text: string): string;
+    /** 提取最後一則 User 訊息文字 */
+    extractLastUserMessage(msgs: any[]): string;
+    recordHookPromptIncludedEvents(store: any, results: any[], searchResponse: Pick<HybridSearchResponse, "hookOriginIds" | "hookOriginKeywords" | "queryHash"> | null | undefined): void;
+    recordGwmEffectiveness(store: any, event: Partial<SubsystemEffectivenessEvent>): void;
+    executeMemoryRecall(params: any): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+    executeMemoryStore(params: any): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    }>;
+    remember(text: string, opts?: {
+        category?: string;
+        importance?: number;
+        metadata?: object;
+    }): Promise<MemoryEntry>;
+    updateMemory(id: string, updates: Partial<Pick<MemoryEntry, 'text' | 'category' | 'importance' | 'metadata'>>): Promise<boolean>;
+    setMemoryStatus(req: StatusChangeRequest): Promise<StatusChangeResult>;
+    recall(query: string, limit?: number): Promise<MemorySearchResult[]>;
+    enumerate(plan: EnumerationPlan, limit?: number): Promise<MemorySearchResult[]>;
+    searchMemory(query: string, limit?: number): Promise<MemorySearchResult[]>;
+    private withSkillLock;
+    saveSkill(def: SkillDef): Promise<{
+        id: string;
+    }>;
+    searchSkills(query: string, limit?: number): Promise<SkillIndexEntry[]>;
+    loadSkill(name: string): Promise<SkillCapsuleV2 | null>;
+    listSkills(): Promise<SkillIndexEntry[]>;
+    private toSkillCapsuleV2;
+    gwmNotInitializedResult(): {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    };
+    executeGwmOn(params: any): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+    executeGwmOff(): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+    executeGwmStatus(): {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+    };
+    executeGwmUpdate(params: any): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+    get testHooks(): {
+        resetState: () => void;
+        setState: (state: any) => void;
+        getState: () => any;
+        ensurePluginInitialized: (_config?: PluginConfig) => Promise<void>;
+        recordPluginInitSmokeStat: (store: any, outcome: "succeeded" | "failed", err?: any) => Promise<void>;
+        executeMemoryRecall: (params: any, _config?: PluginConfig) => Promise<{
+            content: {
+                type: string;
+                text: string;
+            }[];
+            isError: boolean;
+        } | {
+            content: {
+                type: string;
+                text: string;
+            }[];
+        }>;
+        executeMemoryStore: (params: any) => Promise<{
+            content: {
+                type: string;
+                text: string;
+            }[];
+            isError: boolean;
+        } | {
+            content: {
+                type: string;
+                text: string;
+            }[];
+            isError?: undefined;
+        }>;
+        executeGwmOn: (params: any) => Promise<{
+            content: {
+                type: string;
+                text: string;
+            }[];
+            isError: boolean;
+        } | {
+            content: {
+                type: string;
+                text: string;
+            }[];
+        }>;
+        executeGwmOff: () => Promise<{
+            content: {
+                type: string;
+                text: string;
+            }[];
+            isError: boolean;
+        } | {
+            content: {
+                type: string;
+                text: string;
+            }[];
+        }>;
+        executeGwmStatus: () => {
+            content: {
+                type: string;
+                text: string;
+            }[];
+            isError: boolean;
+        } | {
+            content: {
+                type: string;
+                text: string;
+            }[];
+        };
+        executeGwmUpdate: (params: any) => Promise<{
+            content: {
+                type: string;
+                text: string;
+            }[];
+            isError: boolean;
+        } | {
+            content: {
+                type: string;
+                text: string;
+            }[];
+        }>;
+    };
+    private resetStateForTests;
+    private setStateForTests;
+    private getStateForTests;
+    start(onStateCleared?: () => void): void;
+    stop(): Promise<void>;
+    onSessionCompactBefore(event: any): Promise<void>;
+    onSessionEnd(event: any): void;
+    onLlmOutput(event: any, ctx: any): void;
+    get store(): MemoryStore | null;
+    assemble(...args: any[]): Promise<any>;
+    ingest(...args: any[]): Promise<void>;
+    archiveTranscript(session: {
+        sessionKey?: string;
+        sessionId?: string;
+    }, messages: ContextMessage[]): Promise<ArchiveSnapshotResult>;
+    private archiveSessionFileTail;
+    maintain(params: any): Promise<any>;
+    compact(params: any): Promise<any>;
+}
+export {};