@kinqs/brainrouter-mcp-server 0.3.4

package/dist/memory/engine.d.ts

@@ -0,0 +1,203 @@
+import type { CursorPaginationOptions, DiagnosticsBundle, EvidenceListFilters, IMemoryStore, MemoryListFilters, OperationLogFilters } from "@kinqs/brainrouter-types";
+import { MemoryRecallPipeline } from "./recall.js";
+import "dotenv/config";
+import type { CognitiveRecord, MemoryEvidence, MemoryImport, MemoryOperation, MemoryStatus, MemoryType, UserRecord } from "@kinqs/brainrouter-types";
+export declare class MemoryEngine {
+    readonly store: IMemoryStore;
+    private capturePipeline;
+    private recallPipeline;
+    private extractionRunner;
+    private synthesisRunner;
+    private sweeperTimer?;
+    /**
+     * Reentrancy guard: setInterval doesn't wait for the previous callback to
+     * finish before firing the next tick. If a sweep takes longer than the
+     * configured interval (very common when LLM calls queue behind the
+     * concurrency semaphore), ticks pile up and each one tries to extract
+     * the SAME backlog rows. The guard ensures at most one sweep is in flight
+     * at any time; later ticks become no-ops while a previous one runs.
+     */
+    private sweepInProgress;
+    private personaCache;
+    private readonly PERSONA_CACHE_TTL_MS;
+    constructor(storeOrDbPath?: IMemoryStore | string);
+    private ensureSeedAdminUser;
+    get capture(): (params: {
+        userId: string;
+        sessionKey: string;
+        sessionId?: string;
+        messages: {
+            role: string;
+            content: string;
+            timestamp: number;
+        }[];
+        activeSkill?: string;
+        skillHints?: string;
+    }) => Promise<import("@kinqs/brainrouter-types").CaptureResult>;
+    capturePassiveL0(params: {
+        userId: string;
+        sessionKey: string;
+        sessionId?: string;
+        role: string;
+        content: string;
+        timestamp?: number;
+        skillTag?: string;
+    }): {
+        id: string;
+        userId: string;
+        sessionKey: string;
+        sessionId: string;
+        role: string;
+        messageText: string;
+        recordedAt: string;
+        timestamp: number;
+        skillTag: string;
+    };
+    explainRecall(params: Parameters<MemoryRecallPipeline['recall']>[0]): Promise<import("@kinqs/brainrouter-types").RecallResult>;
+    get recall(): (params: Parameters<MemoryRecallPipeline["recall"]>[0]) => Promise<import("@kinqs/brainrouter-types").RecallResult>;
+    getPendingContradictions(userId: string, pagination?: CursorPaginationOptions<{
+        confidence: number;
+        id: string;
+    }>): import("@kinqs/brainrouter-types").ContradictionRecord[];
+    resolveContradiction(id: string, userId: string, status: 'resolved' | 'dismissed'): void;
+    registerSkillHints(skillName: string, hints: string, sourceFile?: string): void;
+    listSkillHints(): import("@kinqs/brainrouter-types").SkillHintsRecord[];
+    spikeSkill(userId: string, skillName: string): {
+        skillName: string;
+        potential: number;
+        lastDecayTime: string;
+    } | null;
+    getSkillActivations(userId: string): {
+        skillName: string;
+        potential: number;
+        lastDecayTime: string;
+    }[];
+    autoScanSkillHints(skillsDirs: string[]): void;
+    /** On-demand Focus Scene distillation — groups cognitives by scene and summarizes via LLM. */
+    distillScenes(userId: string): Promise<{
+        focusDistilled: number;
+        sceneNames: string[];
+    }>;
+    /** On-demand Core Identity distillation — cross-session synthesis of persona+instruction cognitives. */
+    distillPersona(userId: string): Promise<{
+        success: boolean;
+        personaMd?: string;
+    }>;
+    /** Get the current Core Identity for a user, using prompt-level in-memory cache. */
+    getPersona(userId: string): import("@kinqs/brainrouter-types").CoreIdentityRecord | {
+        personaMd: string;
+    } | null;
+    /** Get the top N active focus scenes for a user (ordered by heat score). */
+    getTopScenes(userId: string, limit?: number, cursor?: {
+        heatScore: number;
+        id: string;
+    }): import("@kinqs/brainrouter-types").ContextualFocusRecord[];
+    /** Expose the ability to query the knowledge graph for a user/entity. */
+    queryGraph(userId: string, entity: string, skillTag?: string, maxHops?: number): {
+        nodes: import("@kinqs/brainrouter-types").GraphNode[];
+        edges: import("@kinqs/brainrouter-types").GraphEdge[];
+    };
+    createUser(userId: string, apiKey: string, displayName?: string, isAdmin?: boolean): UserRecord;
+    getUserByApiKey(apiKey: string): UserRecord | null;
+    getUserByEmail(email: string): UserRecord | null;
+    getUserById(userId: string): UserRecord | null;
+    updatePassword(userId: string, hash: string): void;
+    updateUserEmail(userId: string, email: string): void;
+    updateUserDisplayName(userId: string, displayName: string): void;
+    updateUserStatus(userId: string, status: "active" | "disabled"): void;
+    updateUserApiKey(userId: string, apiKey: string): void;
+    listUsers(pagination?: CursorPaginationOptions<{
+        createdAt: string;
+        userId: string;
+    }>): UserRecord[];
+    deleteUser(userId: string): void;
+    listMemories(userId: string, filters?: MemoryListFilters, pagination?: CursorPaginationOptions<{
+        createdTime: string;
+        recordId: string;
+    }>): import("@kinqs/brainrouter-types").MemoryListItem[];
+    deleteMemory(userId: string, recordId: string): void;
+    getMemoryById(userId: string, recordId: string): {
+        memory: CognitiveRecord;
+        evidence: MemoryEvidence[];
+    } | null;
+    upsertEngineeringMemory(params: {
+        userId: string;
+        sessionKey?: string;
+        sessionId?: string;
+        type: MemoryType;
+        content: string;
+        priority?: number;
+        activeSkill?: string;
+        confidence?: number;
+        sourceKind?: CognitiveRecord["sourceKind"];
+        verificationStatus?: CognitiveRecord["verificationStatus"];
+        repoPaths?: string[];
+        filePaths?: string[];
+        commands?: string[];
+        metadata?: Record<string, unknown>;
+    }): CognitiveRecord;
+    getMemoriesByFilePath(userId: string, filePath: string, limit?: number): CognitiveRecord[];
+    searchMemoryRecords(userId: string, query: string, limit?: number): import("@kinqs/brainrouter-types").CognitiveFtsResult[];
+    updateMemory(userId: string, recordId: string, updates: {
+        content?: string;
+        status?: MemoryStatus;
+        confidence?: number;
+        verificationStatus?: CognitiveRecord["verificationStatus"];
+        note?: string;
+    }): {
+        memory: CognitiveRecord;
+        evidence: MemoryEvidence[];
+    } | null;
+    updateMemoryStatus(userId: string, recordId: string, confidence: number, status: MemoryStatus): {
+        memory: CognitiveRecord;
+        evidence: MemoryEvidence[];
+    } | null;
+    addEvidence(userId: string, recordId: string, evidence: Omit<MemoryEvidence, "id" | "userId" | "recordId" | "observedAt"> & {
+        id?: string;
+        observedAt?: string;
+    }): MemoryEvidence;
+    getEvidence(userId: string, recordId: string): MemoryEvidence[];
+    listEvidence(userId: string, filters?: EvidenceListFilters, pagination?: CursorPaginationOptions<{
+        observedAt: string;
+        id: string;
+    }>): MemoryEvidence[];
+    exportMemories(userId: string): import("@kinqs/brainrouter-types").MemoryExport;
+    importMemories(userId: string, data: MemoryImport): import("@kinqs/brainrouter-types").ImportResult;
+    governanceDelete(userId: string, recordId: string, reason: string): void;
+    getOperationLog(userId: string, pagination?: CursorPaginationOptions<{
+        createdAt: string;
+        id: string;
+    }>, filters?: OperationLogFilters): MemoryOperation[];
+    getStats(userId: string): {
+        total: number;
+        archived: number;
+        byType: Record<string, number>;
+        citationRate: number;
+        lastRecallAt: string | null;
+        extraction: import("@kinqs/brainrouter-types").ExtractionStatus;
+    };
+    getDiagnostics(userId: string): DiagnosticsBundle;
+    private startExtractionSweeper;
+    sweepUnextractedBacklog(): Promise<{
+        candidates: number;
+        processed: number;
+        extracted: number;
+    }>;
+    private readonly ACE_ARCHIVE_THRESHOLD;
+    markCited(userId: string, citedRecordIds: string[], allRecalledRecordIds: string[]): {
+        cited: number;
+        nonCited: number;
+        archiveThreshold: number;
+    };
+    searchAsOf(userId: string, query: string, asOf: string, limit?: number): {
+        memories: Array<{
+            recordId: string;
+            content: string;
+            type: string;
+            score: number;
+        }>;
+        asOf: string;
+        count: number;
+    };
+}
+export declare const memoryEngine: MemoryEngine;