@memory-river/core 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,409 @@
+/**
+ * Unified Types - memory-river
+ * Merged from v4/types.ts + context-river/concentrator.ts
+ */
+export type MemoryCategory = "preference" | "fact" | "decision" | "entity" | "constraint" | "identity" | "business" | "knowledge" | "skill" | "other";
+export declare const MEMORY_CATEGORIES: readonly ["preference", "fact", "decision", "entity", "constraint", "identity", "business", "knowledge", "skill", "other"];
+export declare const PROTECTED_CATEGORIES: MemoryCategory[];
+export type HookWeight = "high" | "medium" | "low";
+export interface MemoryHook {
+    keyword: string;
+    weight: HookWeight;
+    weightScore: number;
+}
+export interface HealthConfig {
+    initialScore: number;
+    decayPerRun: number;
+    decayIntervalMs: number;
+    deleteThreshold: number;
+    coreCategories: string[];
+    coreImportanceThreshold: number;
+    skillDecayFactor: number;
+}
+export interface MemoryHealth {
+    healthScore: number;
+    lastAccessedAt: number;
+    decayCount: number;
+    accessCount: number;
+    lastDecayedAt?: number;
+    /** 記憶生命週期狀態 */
+    status?: 'active' | 'superseded' | 'deprecated' | 'trashed';
+    /** 標記為 deprecated 的時間戳（ms） */
+    deprecatedAt?: number;
+}
+export interface MemoryEntry {
+    id: string;
+    text: string;
+    textTokens?: string;
+    vector: number[];
+    importance: number;
+    category: MemoryCategory;
+    parentId: string | null;
+    metadata?: string;
+    createdAt: number;
+    updatedAt: number;
+    /** Slot key，格式：category:param，例如 "memory:drift_threshold" */
+    slotKey?: string;
+    /** Slot 值（僅 simple value：number | string | boolean） */
+    slotValue?: number | string | boolean;
+    /** 此記錄覆寫了哪些 id（建立更新鏈） */
+    supersedes?: string[];
+    /** LLM結構化抽取可靠性指標（0.0-1.0），未結構化時可省略 */
+    confidence?: number;
+    /** 抽取時的 domain 分類 */
+    extractionDomain?: "technical" | "identity" | "preference" | "free_text";
+    /** Unix ms timestamp of when this memory was last concentrated */
+    lastConcentratedAt?: number;
+    /** Unix ms timestamp of when this memory was last included in retrieval results */
+    lastRecalledAt?: number;
+    /** Number of times this memory has been included in retrieval results */
+    recallCount?: number;
+    /** Which session this was distilled from */
+    sessionId?: string;
+}
+export interface MemorySearchResult {
+    entry: MemoryEntry;
+    /** @deprecated Use rankScore for ranking or rawDistance for distance thresholds. */
+    vectorScore: number;
+    /** Rank-based score used by hybrid retrieval. */
+    rankScore: number;
+    /** Original vector distance. Infinity when no vector result is available. */
+    rawDistance: number;
+    bm25Score: number;
+    fusedScore: number;
+    /** CRAG / reranker 評估後的最終分數 */
+    finalScore?: number;
+}
+export interface EnumerationPlan {
+    anchors: string[];
+    setMode: 'union' | 'intersection' | 'compare';
+    relationText?: string;
+    direction?: 'out' | 'in' | 'both';
+}
+export interface EnumerationAnswer {
+    entity: string;
+    evidenceTriples: import('./store/graph-store.js').GraphTriple[];
+    sourceMemoryIds: string[];
+}
+export interface EnumerationResult {
+    answers: EnumerationAnswer[];
+    truncated: boolean;
+    fallbackUsed: boolean;
+}
+export type SubsystemEffectivenessSubsystem = "causal_chain" | "hooks" | "gwm" | "plugin" | "conflict" | "skill_capsule" | (string & {});
+export interface SubsystemEffectivenessEvent {
+    id?: string;
+    ts?: string;
+    subsystem?: SubsystemEffectivenessSubsystem;
+    event?: string;
+    entityId?: string;
+    relatedId?: string;
+    sessionKey?: string;
+    sessionId?: string;
+    queryHash?: string;
+    outcome?: string;
+    count?: number;
+    score?: number;
+    durationMs?: number;
+    metadata?: string | Record<string, unknown> | null;
+}
+export interface SubsystemEffectivenessRow {
+    id: string;
+    ts: string;
+    subsystem: string;
+    event: string;
+    entityId: string;
+    relatedId: string;
+    sessionKey: string;
+    sessionId: string;
+    queryHash: string;
+    outcome: string;
+    count: number;
+    score: number;
+    durationMs: number;
+    metadata: string;
+}
+export interface SubsystemEffectivenessQueryFilter {
+    subsystem?: string;
+    event?: string;
+    outcome?: string;
+    since?: string;
+    limit?: number;
+}
+/** 記憶生命週期狀態 */
+export type MemoryStatus = 'active' | 'superseded' | 'deprecated' | 'archived' | 'trashed';
+/** 狀態變更原因（audit log 用） */
+export type StatusChangeReason = 'created' | 'slot_supersedes' | 'causal_update' | 'conflict_detected' | 'night_consolidation' | 'cleanup_decay' | 'saveSkill_supersede_rollback' | 'manual';
+/** 狀態變更請求 */
+export interface StatusChangeRequest {
+    memoryId: string;
+    toStatus: MemoryStatus;
+    reason: StatusChangeReason;
+    source: string;
+    supersededBy?: string;
+    meta?: Record<string, unknown>;
+}
+/** 狀態變更結果 */
+export interface StatusChangeResult {
+    ok: boolean;
+    memoryId: string;
+    fromStatus: MemoryStatus | null;
+    toStatus: MemoryStatus;
+    auditRowId: string;
+    error?: string;
+}
+/** 狀態 audit log row（寫入 status_audit_log table） */
+export interface StatusAuditRow {
+    id: string;
+    timestamp: number;
+    memoryId: string;
+    fromStatus: string | null;
+    toStatus: string;
+    reason: string;
+    source: string;
+    supersededBy: string | null;
+    meta: string | null;
+    canonicalKey: string | null;
+    partial: boolean;
+}
+export interface TranscriptWatermarkRow {
+    canonicalKey: string;
+    lineCount: number;
+    updatedAt: number;
+}
+export type ConcentratorProvider = "gemini" | "deepseek" | "all_failed";
+export type ConcentratorStatOutcome = "success" | "partial" | "failure";
+export type ConcentratorFailureReason = "broken_json" | "timeout" | "quota" | "other";
+export interface ConcentratorStat {
+    id: string;
+    canonicalKey: string;
+    sessionId: string | null;
+    provider: ConcentratorProvider;
+    outcome: ConcentratorStatOutcome;
+    attemptedProviders: string;
+    inputTokens: number;
+    outputTokens: number | null;
+    durationMs: number;
+    failureReason: ConcentratorFailureReason | null;
+    createdAt: number;
+}
+export interface ContextMessage {
+    role: "user" | "assistant" | "system";
+    content: string | Array<{
+        type?: string;
+        text?: string;
+        [key: string]: unknown;
+    }>;
+    timestamp?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface RememberOptions {
+    source?: "user" | "system" | "tool" | "capsule";
+    urgency?: "low" | "normal" | "high";
+    category?: string;
+    importance?: number;
+    tags?: string[];
+}
+export interface RecallOptions {
+    limit?: number;
+    categories?: string[];
+}
+export interface MemoryResult {
+    id: string;
+    text: string;
+    source: "short" | "long";
+    relevance: number;
+    category: string;
+    timestamp: number;
+    health: number;
+}
+export interface RouteDecision {
+    targets: ("short" | "long")[];
+    category: string;
+    importance: number;
+    reason: string;
+}
+export interface RoutingContext {
+    text: string;
+    source: "user" | "system" | "tool" | "capsule";
+    urgency: "low" | "normal" | "high";
+    manualCategory?: string;
+}
+export type CapsuleType = "working_memory" | "skill_capsule";
+export interface CapsuleSourceEntryRange {
+    firstEntryId: number;
+    lastEntryId: number;
+    count: number;
+}
+export interface CapsuleMetadata {
+    sourceEntryIds?: number[];
+    sourceEntryRange?: CapsuleSourceEntryRange;
+    lastRecalledAt?: number;
+    recallCount?: number;
+    [key: string]: unknown;
+}
+export interface CapsulePayload {
+    summary: string;
+    mode: "engineering" | "relationship";
+    turnCount: number;
+    truncatedAt: number;
+}
+export interface SkillCapsuleEntry extends MemoryEntry {
+    capsuleType: CapsuleType;
+    skillName: string;
+    triggerConditions: string[];
+    executionSteps: string[];
+    confidence: number;
+    sourcePatterns: number;
+}
+export interface InboxWriteOptions {
+    category: string;
+    importance: number;
+    tags?: string[];
+    metadata?: CapsuleMetadata;
+}
+/**
+ * =============================================================================
+ * 📋 Provider / Model 職責對照表（2026-04 現況）
+ * =============================================================================
+ *
+ * 各模組實際使用的 Embedding Provider / Model 不一致，統一記錄於此，
+ * 避免日後重構時踩到不相容的維度組合（Gemini 3072d vs Qwen 1024d）。
+ *
+ * ┌─────────────────────────┬──────────────┬──────────────────────────────────────────────┬─────────────┐
+ * │ 模組                     │ Provider     │ Model                                       │ 向量維度    │
+ * ├─────────────────────────┼──────────────┼──────────────────────────────────────────────┼─────────────┤
+ * │ embedder-v4.legacy.ts   │ Gemini (硬綁)│ gemini-embedding-001                        │ 3072d       │
+ * │ embedder-v5.ts (目前主力)│ Ollama (本地)│ hf.co/Qwen/Qwen3-Embedding-0.6B-GGUF       │ 1024d ⚠️    │
+ * │ causal-engine.ts        │ (引用 embedder-v5) 同上                                    │ 1024d ⚠️    │
+ * │ concentrator-adapter.ts │ Gemini → DeepSeek（濃縮用，非 embedding）                    │ N/A         │
+ * └─────────────────────────┴──────────────┴──────────────────────────────────────────────┴─────────────┘
+ *
+ * ⚠️ 向量維度不相容：v4 (Gemini 3072d) 和 v5 (Qwen 1024d) 使用不同的 LanceDB 实例。
+ *    types.ts DEFAULT_CONFIG.embedding.provider="minimax" 僅為相容性宣告，
+ *    實際 embedder-v5.ts 使用 Ollama，不受此欄位影響。
+ *
+ * Concentration（濃縮）Provider 順序：
+ *   - 預設：Gemini → DeepSeek
+ *   - Gemini 若連續 3 次 503：冷卻 90 秒，期間直接跳過 Gemini
+ *   - concentrate() 全失敗時仍由 ConcentratorAdapter 走 deterministic fallback capsule
+ *
+ * =============================================================================
+ */
+export interface PluginConfig {
+    embedding: {
+        provider: "gemini" | "openai" | "ollama" | "minimax";
+        apiKey?: string;
+        minimaxApiKey?: string;
+        model: string;
+        dimensions?: number;
+    };
+    dbPath: string;
+    ramDbPath?: string;
+    storageMode?: 'auto' | 'ram' | 'ssd';
+    inboxPath?: string;
+    retrieval?: {
+        vectorWeight?: number;
+        bm25Weight?: number;
+        candidatePoolMultiplier?: number;
+    };
+    cleanup?: {
+        enabled?: boolean;
+        decayDays?: number;
+        deleteBelow?: number;
+        trashRetentionDays?: number;
+    };
+    cleanupEngine?: {
+        enabled?: boolean;
+        decayDays?: number;
+        deleteBelow?: number;
+        trashRetentionDays?: number;
+        coreCategories?: string[];
+        coreImportanceThreshold?: number;
+        skillCapsuleProtection?: boolean;
+        useTrash?: boolean;
+        dryRun?: boolean;
+        maxStartupDelete?: number;
+        maxStartupDecay?: number;
+    };
+    autoRecall?: boolean;
+    driftThreshold?: number;
+    health?: {
+        initialScore?: number;
+        decayPerRun?: number;
+        decayIntervalMs?: number;
+        deleteThreshold?: number;
+        coreCategories?: string[];
+        coreImportanceThreshold?: number;
+        skillDecayFactor?: number;
+    };
+    hooks?: {
+        enabled?: boolean;
+        maxHooksPerMemory?: number;
+        maxTriggerDepth?: number;
+        minTriggerScore?: number;
+        cooldownMs?: number;
+    };
+    causalEngine?: {
+        updateThreshold?: number;
+        causalThreshold?: number;
+        embeddingModel?: string;
+    };
+    concentration?: {
+        model?: string;
+        provider?: 'gemini' | 'deepseek';
+        geminiApiKey?: string;
+        maxTokens?: number;
+        deepseekApiKey?: string;
+        deepseekModel?: string;
+        asyncCompactAfterAssemble?: boolean;
+        asyncCompactConcurrency?: number;
+        asyncCompactRaceGuard?: boolean;
+    };
+}
+export declare const DEFAULT_CONFIG: Omit<Required<PluginConfig>, 'dbPath' | 'ramDbPath' | 'inboxPath'>;
+export declare const CATEGORY_DESCRIPTIONS: Record<MemoryCategory, string>;
+export interface SkillDef {
+    name: string;
+    summary: string;
+    triggers: string[];
+    steps: string[];
+}
+export interface SkillIndexEntry {
+    name: string;
+    triggerConditions: string[];
+    summary: string;
+}
+export interface SkillCapsuleV2 extends SkillIndexEntry {
+    id: string;
+    executionSteps: string[];
+    category: "skill";
+    importance: 0.7;
+    capsuleVersion: 2;
+    usageCount: number;
+    lastUsedAt: number | null;
+    status: "active" | "superseded";
+    createdAt: number;
+    updatedAt: number;
+}
+export interface SkillCapsule {
+    id: string;
+    skillName: string;
+    triggerConditions: string[];
+    executionSteps: string[];
+    summary: string;
+    confidence: number;
+    category: string;
+    createdAt: number;
+    updatedAt: number;
+    usageCount: number;
+    lastUsedAt: number | null;
+    status: "active" | "deprecated" | "trashed";
+}
+export interface HookStats {
+    keyword: string;
+    totalTriggers: number;
+    successfulTriggers: number;
+    failedTriggers: number;
+    lastTriggeredAt: number | null;
+}

package/dist/types.js

@@ -0,0 +1,104 @@
+export const MEMORY_CATEGORIES = [
+    "preference",
+    "fact",
+    "decision",
+    "entity",
+    "constraint",
+    "identity",
+    "business",
+    "knowledge",
+    "skill",
+    "other",
+];
+export const PROTECTED_CATEGORIES = [
+    "constraint",
+    "identity",
+    "business",
+];
+export const DEFAULT_CONFIG = {
+    embedding: {
+        provider: "minimax",
+        model: "hf.co/Qwen/Qwen3-Embedding-0.6B-GGUF",
+        dimensions: 1024,
+        apiKey: "",
+        minimaxApiKey: "",
+    },
+    retrieval: {
+        vectorWeight: 0.7,
+        bm25Weight: 0.3,
+        candidatePoolMultiplier: 2,
+    },
+    cleanup: {
+        enabled: true,
+        decayDays: 30,
+        deleteBelow: 0.1,
+        trashRetentionDays: 7,
+    },
+    cleanupEngine: {
+        enabled: true,
+        decayDays: 30,
+        deleteBelow: 0.1,
+        trashRetentionDays: 7,
+        coreCategories: ["identity", "preference", "constraint", "business", "decision", "core_rule"],
+        coreImportanceThreshold: 0.75,
+        skillCapsuleProtection: true,
+        useTrash: true,
+        dryRun: false,
+        maxStartupDelete: 20,
+        maxStartupDecay: 50,
+    },
+    autoRecall: true,
+    storageMode: 'auto',
+    driftThreshold: 0.78,
+    health: {
+        initialScore: 100,
+        decayPerRun: 5,
+        decayIntervalMs: 24 * 60 * 60 * 1000,
+        deleteThreshold: 0,
+        coreCategories: ["identity", "preference", "constraint", "business", "core_rule"],
+        coreImportanceThreshold: 0.8,
+        skillDecayFactor: 0.25,
+    },
+    hooks: {
+        enabled: true,
+        maxHooksPerMemory: 3,
+        maxTriggerDepth: 1,
+        minTriggerScore: 0.5,
+        cooldownMs: 3600000,
+    },
+    causalEngine: {
+        updateThreshold: 0.28,
+        causalThreshold: 0.32,
+        embeddingModel: "hf.co/Qwen/Qwen3-Embedding-0.6B-GGUF",
+    },
+    concentration: {
+        model: 'gemini-2.5-flash-lite',
+        /**
+         * @deprecated 此欄位已失效。實際 fallback 順序由 concentrator-adapter.ts 內定
+         *             （Gemini → DeepSeek），不受 config 影響。
+         *             保留欄位以避免破壞既有宿主設定，請勿依賴其值。
+         */
+        provider: 'gemini',
+        geminiApiKey: "",
+        maxTokens: 8192,
+        deepseekApiKey: "",
+        deepseekModel: 'deepseek-v4-flash',
+        asyncCompactAfterAssemble: false,
+        asyncCompactConcurrency: 1,
+        asyncCompactRaceGuard: true,
+    },
+};
+export const CATEGORY_DESCRIPTIONS = {
+    preference: "老闆的偏好、習慣、溝通風格",
+    fact: "客觀事實、技術規格、數據",
+    decision: "做過的決定、選擇",
+    entity: "人物、組織、產品等實體",
+    constraint: "鐵律、限制、紅線",
+    identity: "身份認同、個人特徵",
+    business: "商務營運、原創IP",
+    knowledge: "其他知識",
+    skill: "顯式保存的技能流程",
+    other: "其他",
+};
+// ─── Global Working Memory (GWM) ───────────────────────────────────────────
+// GwmState is exported from global-working-memory.ts

package/dist/util/bounded-map.d.ts

@@ -0,0 +1 @@
+export declare function setBoundedMapEntry<K, V>(map: Map<K, V>, key: K, value: V, maxSize: number): void;

package/dist/util/bounded-map.js

@@ -0,0 +1,8 @@
+export function setBoundedMapEntry(map, key, value, maxSize) {
+    if (map.size >= maxSize && !map.has(key)) {
+        const oldest = map.keys().next().value;
+        if (oldest !== undefined)
+            map.delete(oldest);
+    }
+    map.set(key, value);
+}

package/dist/util/rate-limiter.d.ts

@@ -0,0 +1,12 @@
+export declare class LLMRateLimiter {
+    private readonly capacity;
+    private readonly refillWindowMs;
+    private tokens;
+    private lastRefillAt;
+    private queue;
+    constructor(capacity: number, refillWindowMs: number);
+    private refill;
+    private msUntilNextToken;
+    acquire(provider: string): Promise<void>;
+}
+export declare const sharedLLMRateLimiter: LLMRateLimiter;

package/dist/util/rate-limiter.js

@@ -0,0 +1,54 @@
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export class LLMRateLimiter {
+    capacity;
+    refillWindowMs;
+    tokens;
+    lastRefillAt;
+    queue = Promise.resolve();
+    constructor(capacity, refillWindowMs) {
+        this.capacity = capacity;
+        this.refillWindowMs = refillWindowMs;
+        this.tokens = capacity;
+        this.lastRefillAt = Date.now();
+    }
+    refill() {
+        const now = Date.now();
+        const elapsed = now - this.lastRefillAt;
+        if (elapsed <= 0)
+            return;
+        const refillRate = this.capacity / this.refillWindowMs;
+        this.tokens = Math.min(this.capacity, this.tokens + elapsed * refillRate);
+        this.lastRefillAt = now;
+    }
+    msUntilNextToken() {
+        if (this.tokens >= 1)
+            return 0;
+        const refillRate = this.capacity / this.refillWindowMs;
+        const missing = 1 - this.tokens;
+        return Math.ceil(missing / refillRate);
+    }
+    async acquire(provider) {
+        let release;
+        const previous = this.queue;
+        this.queue = new Promise((resolve) => { release = resolve; });
+        await previous;
+        try {
+            while (true) {
+                this.refill();
+                if (this.tokens >= 1) {
+                    this.tokens -= 1;
+                    return;
+                }
+                const waitMs = this.msUntilNextToken();
+                console.log(`[throttle] delaying ${provider} call for ${Math.ceil(waitMs / 1000)}s`);
+                await sleep(waitMs);
+            }
+        }
+        finally {
+            release();
+        }
+    }
+}
+export const sharedLLMRateLimiter = new LLMRateLimiter(6, 60_000);

package/dist/util/session-identity.d.ts

@@ -0,0 +1,65 @@
+/**
+ * session-identity.ts
+ *
+ * 統一的 session 身分解析模組（P0-2）。
+ *
+ * 替代既有 resolveTrackingSessionKey / extractSessionIdentity 雙鏈，把
+ * 「從 payload 抽 session 身分」與「決定對外 canonicalKey」收斂到同一條路徑。
+ *
+ * - 對外只暴露 canonicalKey；所有 in-memory state map / Set 都應該以它為 key。
+ * - canonicalKey 優先序：sessionKey -> session.key -> session.id -> sessionId
+ *   （與磁碟序列化最重的 transcript archive 既有 sessionKey 命名一致）。
+ * - 原始 sessionKey / sessionId 仍保留在 record 裡，給磁碟讀寫拼檔名用。
+ *
+ * 純函式（除 console / fs 觀測點），不可在這裡碰任何 state map。
+ */
+export type SessionIdentitySource = 'sessionKey' | 'session.key' | 'session.id' | 'sessionId' | 'guess' | 'fallback' | 'global';
+export interface SessionIdentity {
+    /** 對外統一識別子，所有 state map key 都用這個 */
+    canonicalKey: string;
+    /** 原始 sessionKey（如果 payload 有） */
+    sessionKey: string | null;
+    /** 原始 sessionId（如果 payload 有） */
+    sessionId: string | null;
+    /** canonicalKey 是從哪個欄位拿到的 */
+    source: SessionIdentitySource;
+    /** 是否走到 'global' fallback（payload 完全沒有 session 身分） */
+    isFallback: boolean;
+}
+export declare const GLOBAL_FALLBACK_KEY = "global";
+export type FallbackObserver = (info: {
+    signature: string;
+    ctx: string;
+}) => void;
+/** 註冊全域 fallback observer；傳 null 取消。 */
+export declare function setFallbackObserver(fn: FallbackObserver | null): void;
+/**
+ * 從單一 payload 解析 sessionIdentity。
+ * 同時拿 sessionKey 與 sessionId 兩個原始欄位（如果存在），以便磁碟讀寫拼檔名。
+ */
+export declare function resolveSessionIdentity(payload: unknown): SessionIdentity;
+/**
+ * 從 variadic args 解析（assemble、register hook 場景）。
+ * 走訪每個 arg，取第一個能解出非 fallback identity 的；若全部 fallback，回傳 global。
+ *
+ * 與 resolveTrackingSessionKey 的 variadic 行為等價，但同步把 sessionKey/sessionId 一起帶出。
+ */
+export declare function resolveSessionIdentityFromArgs(...args: unknown[]): SessionIdentity;
+/**
+ * 已知 canonicalKey 反查 SessionIdentity。
+ * 給 cleanup / scheduler / inbox-watcher 等沒有原始 payload 的場景用。
+ *
+ * source 標 'fallback' 是為了與 'global' 區分：'global' 表示 payload 不帶任何 session
+ * 身分，'fallback' 表示我們已經有 canonicalKey 但沒走過 payload resolve 流程。
+ */
+export declare function makeSessionIdentity(canonicalKey: string, hints?: {
+    sessionKey?: string;
+    sessionId?: string;
+}): SessionIdentity;
+/**
+ * 從磁碟猜當前 session（mtime 最新的 transcript .jsonl）。
+ * 找不到回 null。每次呼叫 log 一條 info，方便觀測有多少流量走這條 fallback。
+ */
+export declare function resolveSessionIdentityByGuess(transcriptsDir: string, ctx?: string): SessionIdentity | null;
+/** 重置 fallback dedupe 狀態，僅供測試使用。 */
+export declare function __resetFallbackDedupeForTests(): void;