@memory-river/core 0.2.0

package/dist/cognition/hooks-engine.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Hooks Engine - 記憶鉤子系統 + 實體關係圖譜
+ * memory-lance-v4
+ * * 功能：
+ * 1. LLM 自動生成 hooks（最多 3 個，含權重）
+ * 2. LLM 自動生成 entities（實體關係圖譜）
+ * 3. 搜尋時觸發鉤子（層級 1，權重 > 0.5）
+ * 4. 智慧防呆：可接受字串、陣列或 JSON 格式的 Query
+ * 5. 冷卻時間（1 小時）
+ */
+import { MemoryStore, type MemoryEntry } from "../store/store-v4.js";
+import { Embedder } from "../providers/embedder-v5.js";
+import type { MemoryHook } from "../types.js";
+import type { LlmClient } from "../ports.js";
+import * as lancedb from '@lancedb/lancedb';
+export interface EntityRelation {
+    subject: string;
+    relation: string;
+    object: string;
+}
+export interface HookTriggerResult {
+    triggered: boolean;
+    relatedMemories: {
+        memory: MemoryEntry;
+        score: number;
+        viaHook: string;
+    }[];
+    naturalLanguage: string;
+}
+export interface HookQualityRecord {
+    keyword: string;
+    triggerCount: number;
+    successCount: number;
+    failCount: number;
+    lastTriggeredAt: number | null;
+    currentNumericWeight: number;
+    adjustedNumericWeight: number;
+}
+export declare class HooksEngine {
+    private store;
+    private embedder;
+    private config;
+    private llm?;
+    private _db?;
+    private cooldown;
+    private qualityTracker;
+    private hookEmbeddingCache;
+    private readonly QUALITY_WINDOW;
+    private readonly MAX_QUALITY_TRACKER_SIZE;
+    private readonly SUCCESS_RATE_THRESHOLD;
+    private readonly HIGH_SUCCESS_RATE;
+    private readonly DEGRADE_COOLDOWN;
+    private graphStore;
+    private debounceTimer?;
+    private hardCapTimer?;
+    private isDirty;
+    constructor(store: MemoryStore, embedder: Embedder, config: {
+        enabled?: boolean;
+        maxHooksPerMemory?: number;
+        maxTriggerDepth?: number;
+        minTriggerScore?: number;
+        cooldownMs?: number;
+    }, llm?: LlmClient | undefined, _db?: lancedb.Connection | undefined);
+    /** 注入 GraphStore（由 index.ts 在初始化時呼叫） */
+    setGraphStore(graphStore: any): void;
+    generateHooks(text: string, category: string): Promise<MemoryHook[]>;
+    private getCategoryHint;
+    private buildHookPrompt;
+    generateEntities(text: string): Promise<EntityRelation[]>;
+    private parseEntitiesResponse;
+    private parseHooksResponse;
+    private fallbackHooks;
+    private normalizeWeight;
+    private weightToScore;
+    private isInCooldown;
+    private getAdjustedWeight;
+    private setCooldown;
+    /**
+     * 🛡️ 智慧型 Query 解析器
+     * 處理 OpenClaw 傳入的複雜格式，精準提取純文字
+     */
+    private safelyExtractUserText;
+    triggerHooks(rawQuery: any): Promise<HookTriggerResult>;
+    /**
+     * CRAG 評估後回報 hook 觸發結果（由 Retriever 呼叫）
+     * @param keyword - 觸發的 hook keyword
+     * @param wasRetained - CRAG 評估後該記憶是否被保留
+     */
+    reportHookOutcome(keyword: string, wasRetained: boolean): Promise<void>;
+    private _deleteDBRecord;
+    private extractKeywords;
+    private generateNaturalLanguage;
+    private _setupDebounce;
+    private _registerShutdown;
+    private schedulePersist;
+    flush(): Promise<void>;
+    loadStats(): Promise<void>;
+    persistStats(): Promise<void>;
+}