@kinqs/brainrouter-mcp-server 0.3.4

package/dist/memory/store/embedding.d.ts

@@ -0,0 +1,16 @@
+import type { EmbeddingServiceConfig } from "@kinqs/brainrouter-types";
+export declare class EmbeddingService {
+    private readonly endpoint;
+    private readonly apiKey;
+    private readonly model;
+    private readonly dimensions;
+    private readonly ready;
+    constructor(config: EmbeddingServiceConfig);
+    getDimensions(): number;
+    isReady(): boolean;
+    /**
+     * Get an embedding for a single text.
+     * Throws if not ready, so always check isReady() first.
+     */
+    embed(text: string): Promise<Float32Array>;
+}

package/dist/memory/store/embedding.js

@@ -0,0 +1,68 @@
+import { fetchWithExternalRetry } from "../retry.js";
+import { acquireLLMSlot } from "../llm-semaphore.js";
+export class EmbeddingService {
+    endpoint;
+    apiKey;
+    model;
+    dimensions;
+    ready;
+    constructor(config) {
+        this.endpoint = config.endpoint ?? "https://api.openai.com/v1/embeddings";
+        this.apiKey = config.apiKey ?? "";
+        this.model = config.model ?? "text-embedding-3-small";
+        this.dimensions = config.dimensions ?? 768;
+        // Graceful fallback: If no API key is provided, we disable the embedding service.
+        this.ready = !!this.apiKey;
+        if (!this.ready) {
+            console.error("[BrainRouter] Embedding API key not set. Vector search will be disabled. Falling back to FTS-only mode.");
+        }
+    }
+    getDimensions() {
+        return this.dimensions;
+    }
+    isReady() {
+        return this.ready;
+    }
+    /**
+     * Get an embedding for a single text.
+     * Throws if not ready, so always check isReady() first.
+     */
+    async embed(text) {
+        if (!this.ready) {
+            throw new Error("EmbeddingService is not ready (missing API key)");
+        }
+        // Same backend as ModelLLMRunner — go through the shared semaphore so
+        // embedding requests count against the concurrency cap. Otherwise a burst
+        // of new cognitive records can fire N embeddings + N LLM calls in
+        // parallel and overwhelm LM Studio just like before.
+        const release = await acquireLLMSlot();
+        try {
+            const res = await fetchWithExternalRetry(this.endpoint, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "Authorization": `Bearer ${this.apiKey}`,
+                },
+                body: JSON.stringify({
+                    input: text,
+                    model: this.model,
+                }),
+            }, {
+                label: "Embedding API",
+            });
+            if (!res.ok) {
+                const err = await res.text().catch(() => "(no body)");
+                throw new Error(`Embedding API failed: HTTP ${res.status} ${res.statusText} - ${err}`);
+            }
+            const data = await res.json();
+            if (!data.data || !data.data[0] || !Array.isArray(data.data[0].embedding)) {
+                throw new Error("Invalid embedding response format");
+            }
+            const vec = data.data[0].embedding;
+            return new Float32Array(vec);
+        }
+        finally {
+            release();
+        }
+    }
+}

package/dist/memory/store/reranker.d.ts

@@ -0,0 +1,24 @@
+import type { RerankerServiceConfig } from "@kinqs/brainrouter-types";
+export interface RankedResult {
+    index: number;
+    relevanceScore: number;
+}
+export declare class RerankerService {
+    private readonly endpoint;
+    private readonly apiKey;
+    private readonly model;
+    private readonly topN;
+    private readonly ready;
+    constructor(config: RerankerServiceConfig);
+    isReady(): boolean;
+    getTopN(): number;
+    /**
+     * Reranks documents against a query using Cohere/vLLM /v1/rerank API.
+     * Throws if not ready, so always check isReady() first.
+     */
+    rerank(params: {
+        query: string;
+        documents: string[];
+        topN?: number;
+    }): Promise<RankedResult[]>;
+}

package/dist/memory/store/reranker.js

@@ -0,0 +1,83 @@
+import { fetchWithExternalRetry } from "../retry.js";
+export class RerankerService {
+    endpoint;
+    apiKey;
+    model;
+    topN;
+    ready;
+    constructor(config) {
+        this.endpoint = config.endpoint ?? "https://api.cohere.com/v1/rerank";
+        this.apiKey = config.apiKey ?? "";
+        this.model = config.model ?? "rerank-english-v3.0";
+        this.topN = config.topN ?? 5;
+        // Graceful fallback: If no API key is provided, disable the reranker service.
+        this.ready = !!this.apiKey;
+        if (!this.ready) {
+            console.error("[BrainRouter] Reranker API key not set. Stage 3 reranking will be disabled. Falling back to RRF-only mode.");
+        }
+    }
+    isReady() {
+        return this.ready;
+    }
+    getTopN() {
+        return this.topN;
+    }
+    /**
+     * Reranks documents against a query using Cohere/vLLM /v1/rerank API.
+     * Throws if not ready, so always check isReady() first.
+     */
+    async rerank(params) {
+        if (!this.ready) {
+            throw new Error("RerankerService is not ready (missing API key)");
+        }
+        if (params.documents.length === 0) {
+            return [];
+        }
+        const requestTopN = params.topN ?? this.topN;
+        // Graceful truncation: Ensure inputs do not exceed typical 512-token context length (approx 2000 chars).
+        // To be absolutely safe and prevent HTTP 400 Bad Request errors from local rerankers
+        // with strict 512-token limits, we limit the query to 200 characters (~50 tokens)
+        // and each document to 700 characters (~180 tokens).
+        const safeDocuments = params.documents.map(doc => doc.length > 700 ? doc.substring(0, 700) + "..." : doc);
+        const safeQuery = params.query.length > 200
+            ? params.query.substring(0, 200) + "..."
+            : params.query;
+        const res = await fetchWithExternalRetry(this.endpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Authorization": `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify({
+                query: safeQuery,
+                documents: safeDocuments,
+                model: this.model,
+                top_n: requestTopN,
+            }),
+        }, {
+            label: "Reranker API",
+        });
+        if (!res.ok) {
+            const err = await res.text().catch(() => "(no body)");
+            throw new Error(`Reranker API failed: HTTP ${res.status} ${res.statusText} - ${err}`);
+        }
+        const data = await res.json();
+        // Example vLLM response:
+        // {
+        //   'id': 'score-940bec41fb803c3f', 
+        //   'model': 'BAAI/bge-reranker-v2-m3', 
+        //   'results': [
+        //      {'index': 0, 'document': {'text': '...'}, 'relevance_score': 0.997682}, 
+        //      {'index': 1, 'document': {'text': '...'}, 'relevance_score': 0.000016}
+        //   ]
+        // }
+        if (!data.results || !Array.isArray(data.results)) {
+            throw new Error("Invalid reranker response format: missing 'results' array");
+        }
+        const rankedResults = data.results.map((r) => ({
+            index: r.index,
+            relevanceScore: r.relevance_score
+        }));
+        return rankedResults;
+    }
+}

package/dist/memory/store/sqlite.d.ts

@@ -0,0 +1,167 @@
+import type { ContradictionRecord, CursorPaginationOptions, EvidenceListFilters, ExtractionStatus, ImportResult, SensoryRecord, CognitiveRecord, CognitiveFtsResult, MemoryEvidence, MemoryExport, MemoryImport, MemoryListFilters, MemoryListItem, MemoryOperation, MemoryStatus, OperationLogFilters, VectorSearchResult, SkillActivationRecord, SkillHintsRecord, ContextualFocusRecord, CoreIdentityRecord, SchedulerState, GraphNode, GraphEdge, StalledExtractionBacklog, UserRecord } from "@kinqs/brainrouter-types";
+import type { IMemoryStore } from "@kinqs/brainrouter-types";
+export declare class SqliteMemoryStore implements IMemoryStore {
+    private db;
+    private stmtSensoryUpsertMeta;
+    private stmtSensoryQueryAfter;
+    private stmtCognitiveUpsertMeta;
+    private stmtCognitiveGetMeta;
+    private stmtCognitiveFtsInsert;
+    private stmtCognitiveFtsSearch;
+    private stmtCognitiveVecInsert?;
+    private stmtCognitiveVecDelete?;
+    private vecLoaded;
+    private vecDimensions;
+    constructor(dbPath: string);
+    init(): void;
+    initVec(dimensions: number): void;
+    isVecAvailable(): boolean;
+    reembedStaleRecords(embedder: (text: string) => Promise<Float32Array>): Promise<number>;
+    getSqliteVersion(): string;
+    private initSchema;
+    upsertSensory(record: SensoryRecord): void;
+    getRecentSensoryMessages(userId: string, sessionKey: string, limit: number, afterIsoTime?: string): SensoryRecord[];
+    getUnextractedSensoryCount(userId: string, sessionKey: string): number;
+    markSensoryExtracted(userId: string, sessionKey: string, recordIds: string[], extractedAt?: string): void;
+    upsertCognitiveBatch(entries: Array<{
+        record: CognitiveRecord;
+        embedding?: Float32Array;
+    }>, options?: {
+        skipAudit?: boolean;
+    }): void;
+    upsertCognitive(record: CognitiveRecord, options?: {
+        skipAudit?: boolean;
+    }): void;
+    invalidateCognitiveRecord(userId: string, recordId: string, supersededById: string): void;
+    getMemoryById(userId: string, recordId: string): CognitiveRecord | null;
+    getMemoriesByFilePath(userId: string, filePath: string, limit: number): CognitiveRecord[];
+    updateCognitiveConfidence(userId: string, recordId: string, confidence: number, status: MemoryStatus): void;
+    insertEvidence(ev: MemoryEvidence): void;
+    getEvidenceByRecord(userId: string, recordId: string): MemoryEvidence[];
+    listEvidence(userId: string, filters?: EvidenceListFilters, pagination?: CursorPaginationOptions<{
+        observedAt: string;
+        id: string;
+    }>): MemoryEvidence[];
+    insertOperation(op: MemoryOperation): void;
+    getOperationLog(userId: string, options?: CursorPaginationOptions<{
+        createdAt: string;
+        id: string;
+    }>, filters?: OperationLogFilters): MemoryOperation[];
+    exportMemories(userId: string): MemoryExport;
+    importMemories(userId: string, data: MemoryImport): ImportResult;
+    hardDeleteMemory(userId: string, recordId: string, reason: string): void;
+    searchCognitiveFts(userId: string, query: string, limit: number): CognitiveFtsResult[];
+    searchCognitiveFtsAsOf(userId: string, query: string, limit: number, asOf: string): CognitiveFtsResult[];
+    upsertCognitiveVec(recordId: string, embedding: Float32Array): void;
+    searchCognitiveVec(userId: string, queryEmbedding: Float32Array, limit: number): VectorSearchResult[];
+    upsertContradiction(data: {
+        id: string;
+        userId: string;
+        recordIdA: string;
+        recordIdB: string;
+        reason: string;
+        confidence: number;
+    }): void;
+    getPendingContradictions(userId: string, pagination?: CursorPaginationOptions<{
+        confidence: number;
+        id: string;
+    }>): ContradictionRecord[];
+    resolveContradiction(id: string, userId: string, status: 'resolved' | 'dismissed'): void;
+    upsertSkillHints(skillName: string, hints: string, sourceFile?: string): void;
+    listSkillHints(): SkillHintsRecord[];
+    upsertContextualFocus(record: ContextualFocusRecord): void;
+    getTopContextualFocus(userId: string, limit?: number, cursor?: {
+        heatScore: number;
+        id: string;
+    }): ContextualFocusRecord[];
+    decayContextualFocusHeatScores(userId: string, decayFactor?: number): void;
+    boostContextualFocusHeatScore(userId: string, sceneName: string, boost?: number): void;
+    getCognitivesByFocus(userId: string, sceneName: string, limit?: number): any[];
+    getContextualFocusCount(userId: string): number;
+    getColdContextualFocus(userId: string, limit: number): ContextualFocusRecord[];
+    deleteContextualFocus(userId: string, sceneIds: string[]): void;
+    getContextualFocusByName(userId: string, sceneName: string): ContextualFocusRecord | null;
+    getDistinctSceneNames(userId: string): string[];
+    renameFocusInCognitiveRecords(userId: string, oldName: string, canonicalName: string): void;
+    upsertCoreIdentity(record: CoreIdentityRecord): void;
+    getCoreIdentity(userId: string): CoreIdentityRecord | null;
+    getIdentityAndInstructionCognitives(userId: string, limit?: number): any[];
+    getSchedulerState(userId: string): SchedulerState;
+    incrementSchedulerCognitiveCount(userId: string, count: number): void;
+    resetSchedulerFocusCount(userId: string): void;
+    resetSchedulerIdentityCount(userId: string): void;
+    recordExtractionFailure(userId: string, message: string): void;
+    resetExtractionFailures(userId: string): void;
+    getExtractionStatus(userId: string): ExtractionStatus;
+    sweepUnextractedBacklog(options: {
+        olderThanMs: number;
+        minUnextracted?: number;
+        maxFailures?: number;
+        limit?: number;
+    }): StalledExtractionBacklog[];
+    getAllGraphNodes(userId: string): GraphNode[];
+    upsertGraphNode(node: GraphNode): void;
+    upsertGraphEdge(edge: GraphEdge): void;
+    getGraphNodeByEntity(userId: string, entity: string): GraphNode | null;
+    getGraphNeighbors(userId: string, entityId: string, skillTag?: string, maxHops?: number): {
+        nodes: GraphNode[];
+        edges: GraphEdge[];
+    };
+    markCited(userId: string, recordIds: string[]): void;
+    incrementNeverCited(userId: string, recordIds: string[]): {
+        recordId: string;
+        neverCitedCount: number;
+    }[];
+    archiveCognitiveRecord(userId: string, recordId: string): void;
+    getRecentSkillContextCognitives(userId: string, limit: number): {
+        skillTag: string;
+        createdTime: string;
+    }[];
+    getSkillHints(skillName: string): string | null;
+    getSkillActivations(userId: string): SkillActivationRecord[];
+    upsertSkillActivations(userId: string, activations: SkillActivationRecord[]): void;
+    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;
+    updateUserPassword(userId: string, passwordHash: 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;
+    }>): MemoryListItem[];
+    getMemoryStats(userId: string): {
+        total: number;
+        archived: number;
+        byType: Record<string, number>;
+        citationRate: number;
+        lastRecallAt: string | null;
+        extraction: ExtractionStatus;
+    };
+    private replaceFileIndex;
+    upsertConnection(userId: string, sourceId: string, targetId: string, weight: number): void;
+    getConnectionsForSource(userId: string, sourceId: string): Array<{
+        targetId: string;
+        weight: number;
+    }>;
+    strengthenConnectionsBatch(userId: string, pairs: Array<{
+        source: string;
+        target: string;
+    }>, delta: number): void;
+    decayConnections(userId: string, decayFactor: number): void;
+    pruneConnections(userId: string, threshold: number): void;
+    getAllConnections(userId: string): Array<{
+        sourceId: string;
+        targetId: string;
+        weight: number;
+        lastActivatedAt: string;
+    }>;
+}