@kinqs/brainrouter-mcp-server 0.3.4

package/dist/memory/recall.js

@@ -0,0 +1,427 @@
+import { expandRecallWithGraph } from "./pipeline/graph-recall.js";
+import { detectPrewarmSkills, buildPrewarmBlock } from "./pipeline/skill-prewarm.js";
+import { detectTaskIntent, extractFilePathHints, getMemoryTypeConfig } from "./memory-type-config.js";
+import { randomUUID } from "node:crypto";
+import { NeuralSparkEngine } from "./pipeline/neural-spark.js";
+function effectivePriority(memory) {
+    const halfLife = getMemoryTypeConfig(memory.type).halfLifeDays;
+    const ageMs = Date.now() - new Date(memory.created_time).getTime();
+    const ageDays = ageMs / 86_400_000;
+    let base = memory.priority;
+    if (halfLife) {
+        const decayFactor = Math.pow(0.5, ageDays / halfLife);
+        base = memory.priority * decayFactor;
+    }
+    const citationBoost = Math.min((memory.citation_count ?? 0) * 0.05, 0.30);
+    // Freshness boost: anything captured in the last 24h gets a small lift so
+    // brand-new facts surface even before they've been cited. Linear ramp from
+    // 1.15× at age 0 to 1.0× at age 1d.
+    const freshness = ageDays <= 1 ? 1 + 0.15 * (1 - ageDays) : 1;
+    return base * (1 + citationBoost) * freshness;
+}
+function applyFilters(records, filters) {
+    if (!filters)
+        return records;
+    const afterMs = filters.capturedAfter ? new Date(filters.capturedAfter).getTime() : undefined;
+    const beforeMs = filters.capturedBefore ? new Date(filters.capturedBefore).getTime() : undefined;
+    const types = filters.types && filters.types.length > 0 ? new Set(filters.types) : undefined;
+    const scenes = filters.scenes && filters.scenes.length > 0 ? new Set(filters.scenes) : undefined;
+    return records.filter((r) => {
+        if (types && !types.has(r.type))
+            return false;
+        if (scenes && (!r.scene_name || !scenes.has(r.scene_name)))
+            return false;
+        if (filters.skillTag && r.skill_tag !== filters.skillTag)
+            return false;
+        if (filters.minPriority !== undefined && r.priority < filters.minPriority)
+            return false;
+        if (afterMs !== undefined || beforeMs !== undefined) {
+            const created = r.created_time ? new Date(r.created_time).getTime() : NaN;
+            if (Number.isNaN(created))
+                return false;
+            if (afterMs !== undefined && created < afterMs)
+                return false;
+            if (beforeMs !== undefined && created > beforeMs)
+                return false;
+        }
+        return true;
+    });
+}
+export class MemoryRecallPipeline {
+    store;
+    embeddingService;
+    rerankerService;
+    constructor(store, embeddingService, rerankerService) {
+        this.store = store;
+        this.embeddingService = embeddingService;
+        this.rerankerService = rerankerService;
+    }
+    async recall(params) {
+        const startTime = Date.now();
+        const { userId, sessionKey, query, activeSkill, filters } = params;
+        const intent = detectTaskIntent(query);
+        // 1. FTS5 BM25 search (Top 15)
+        const ftsResultsRaw = this.store.searchCognitiveFts(userId, query, 15);
+        const filePathResultsRaw = this.expandWithFilePathMatches(userId, query);
+        // 2. Vector search (Top 15, if enabled)
+        let vecResultsRaw = [];
+        if (this.embeddingService.isReady()) {
+            try {
+                const queryVec = await this.embeddingService.embed(query);
+                vecResultsRaw = this.store.searchCognitiveVec(userId, queryVec, 15);
+            }
+            catch (e) {
+                console.error("[BrainRouter] Vector search skipped during recall:", e.message);
+            }
+        }
+        // Filter the three candidate streams BEFORE RRF so the rank is computed
+        // on the actually-relevant pool, not a filtered subset of an unfiltered
+        // rank (which would bias scores toward records that happen to be in the
+        // top-15 globally even if irrelevant to the filter).
+        const ftsResults = applyFilters(ftsResultsRaw, filters);
+        const vecResults = applyFilters(vecResultsRaw, filters);
+        const filePathResults = applyFilters(filePathResultsRaw, filters);
+        if (ftsResults.length === 0 && vecResults.length === 0 && filePathResults.length === 0) {
+            const emptyStrategy = this.embeddingService.isReady() ? "hybrid-empty" : "keyword-empty";
+            const durationMs = Date.now() - startTime;
+            const recallExplanation = {
+                ftsHits: 0,
+                vecHits: 0,
+                filePathHits: 0,
+                rrfTopScore: 0,
+                intentDetected: intent,
+                typeBoosts: {},
+                skillBoostApplied: false,
+                rerankerUsed: false,
+                graphExpansion: false,
+                citationBoosts: {},
+                durationMs,
+                rerankerCandidates: 0,
+                scoredRecords: [],
+            };
+            if (!params.explain) {
+                this.writeRecallOp(userId, sessionKey, query, emptyStrategy, 0, durationMs, recallExplanation);
+            }
+            return { recallStrategy: emptyStrategy, recallExplanation };
+        }
+        // 3. RRF Merge (Reciprocal Rank Fusion)
+        const rrfMap = new Map();
+        ftsResults.forEach((r, idx) => {
+            const rank = idx + 1;
+            rrfMap.set(r.record_id, { record: r, rrfScore: 1 / (60 + rank) });
+        });
+        vecResults.forEach((r, idx) => {
+            const rank = idx + 1;
+            const existing = rrfMap.get(r.record_id);
+            if (existing) {
+                existing.rrfScore += 1 / (60 + rank);
+            }
+            else {
+                rrfMap.set(r.record_id, { record: r, rrfScore: 1 / (60 + rank) });
+            }
+        });
+        filePathResults.forEach((r, idx) => {
+            const existing = rrfMap.get(r.record_id);
+            const filePathScore = 1 / (45 + idx + 1);
+            if (existing) {
+                existing.rrfScore += filePathScore;
+            }
+            else {
+                rrfMap.set(r.record_id, { record: r, rrfScore: filePathScore });
+            }
+        });
+        const rrfValues = Array.from(rrfMap.values()).map(v => v.rrfScore);
+        const rrfTopScore = rrfValues.length > 0 ? Math.max(...rrfValues) : 0;
+        // 4. Combine RRF with Decay + Skill boost
+        const typeBoosts = {};
+        const citationBoosts = {};
+        let skillBoostApplied = false;
+        const scoredResults = Array.from(rrfMap.values()).map(({ record, rrfScore }) => {
+            const baseScore = rrfScore * 30;
+            const priorityScore = (effectivePriority(record) / 100);
+            let finalScore = (baseScore * 0.7) + (priorityScore * 0.3);
+            if (activeSkill && record.skill_tag === activeSkill) {
+                finalScore *= 1.2;
+                skillBoostApplied = true;
+            }
+            const intentMultiplier = getMemoryTypeConfig(record.type).intentAffinity[intent] ?? 1;
+            if (intentMultiplier !== 1) {
+                typeBoosts[record.type] = intentMultiplier;
+            }
+            finalScore *= intentMultiplier;
+            const citationCount = record.citation_count ?? 0;
+            const citBoost = Math.min(citationCount * 0.05, 0.30);
+            if (citBoost > 0) {
+                citationBoosts[record.record_id] = citBoost;
+            }
+            return { record, score: finalScore };
+        });
+        // --- Neural Sparks & Spreading Activation ---
+        const maxScore = scoredResults.length > 0 ? Math.max(...scoredResults.map(r => r.score)) : 1.0;
+        const initialNodes = scoredResults.map(r => ({
+            id: r.record.record_id,
+            potential: maxScore > 0 ? r.score / maxScore : 0.0,
+            fired: false
+        }));
+        const sparkEngine = new NeuralSparkEngine(this.store);
+        const propagatedNodes = sparkEngine.propagateSparks(userId, initialNodes);
+        const propagatedMap = new Map(propagatedNodes.map(n => [n.id, n]));
+        const existingIds = new Set(scoredResults.map(r => r.record.record_id));
+        // Carry the full {id, potential, fired, type, preview, sceneName} so the
+        // UI can render a human-friendly label instead of the opaque record id.
+        // Track seen ids so we don't double-list a node that appears as both a
+        // seed and a propagation target.
+        const sparkedNodes = [];
+        const sparkedSeen = new Set();
+        const previewFromContent = (content) => {
+            const text = (content ?? "").toString().trim();
+            if (!text)
+                return undefined;
+            const oneLine = text.replace(/\s+/g, " ");
+            // Keep the preview short — the UI renders a compact pill, anything
+            // longer than ~70 chars wraps awkwardly even with ellipsis fallback.
+            return oneLine.length > 70 ? `${oneLine.slice(0, 67)}…` : oneLine;
+        };
+        const pushNode = (node, meta) => {
+            if (!node.id || sparkedSeen.has(node.id))
+                return;
+            sparkedSeen.add(node.id);
+            sparkedNodes.push({
+                id: node.id,
+                potential: Math.max(0, Math.min(1, Number(node.potential) || 0)),
+                fired: Boolean(node.fired),
+                type: meta?.type,
+                preview: meta?.preview,
+                sceneName: meta?.sceneName,
+            });
+        };
+        const sparkScoredResults = [];
+        for (const scored of scoredResults) {
+            const propNode = propagatedMap.get(scored.record.record_id);
+            if (propNode) {
+                const newScore = Math.max(scored.score, propNode.potential * maxScore);
+                // Every initial-seed node belongs in the trace, fired or not — the
+                // sub-threshold pills carry useful "we considered this but it didn't
+                // spread" signal.
+                pushNode(propNode, {
+                    type: scored.record.type,
+                    preview: previewFromContent(scored.record.content),
+                    sceneName: scored.record.scene_name,
+                });
+                sparkScoredResults.push({
+                    record: scored.record,
+                    score: propNode.fired ? newScore * 1.5 : newScore,
+                    fired: propNode.fired
+                });
+            }
+            else {
+                sparkScoredResults.push(scored);
+            }
+        }
+        // Pull in connected memories that were excited above the firing threshold
+        for (const propNode of propagatedNodes) {
+            if (propNode.fired && !existingIds.has(propNode.id)) {
+                const record = this.store.getMemoryById(userId, propNode.id);
+                if (record) {
+                    pushNode(propNode, {
+                        type: record.type,
+                        preview: previewFromContent(record.content),
+                        sceneName: record.sceneName,
+                    });
+                    const formattedRecord = {
+                        record_id: record.id,
+                        user_id: record.userId,
+                        content: record.content,
+                        type: record.type,
+                        priority: record.priority,
+                        scene_name: record.sceneName,
+                        skill_tag: record.skillTag,
+                        session_key: record.sessionKey,
+                        timestamp_str: record.timestampStr,
+                        created_time: record.createdTime,
+                        citation_count: record.citationCount
+                    };
+                    const baseScore = propNode.potential * maxScore;
+                    sparkScoredResults.push({
+                        record: formattedRecord,
+                        score: baseScore * 1.5,
+                        fired: true
+                    });
+                }
+            }
+        }
+        sparkScoredResults.sort((a, b) => b.score - a.score);
+        let topResults = sparkScoredResults.slice(0, 5);
+        // Stage 3 — Reranker (Top 20 from RRF + Sparks)
+        const rerankCandidates = sparkScoredResults.slice(0, 20);
+        let usedReranker = false;
+        if (this.rerankerService.isReady()) {
+            try {
+                const documents = rerankCandidates.map(r => r.record.content);
+                const ranked = await this.rerankerService.rerank({
+                    query,
+                    documents,
+                    topN: this.rerankerService.getTopN()
+                });
+                topResults = ranked.map(r => rerankCandidates[r.index]);
+                usedReranker = true;
+            }
+            catch (e) {
+                console.error("[BrainRouter] Reranker failed during recall, falling back to RRF:", e.message);
+            }
+        }
+        // 5. Format for context
+        const memoryLines = topResults.map(({ record }) => {
+            const tag = record.scene_name ? `${record.type}|${record.scene_name}` : record.type;
+            let line = `- [${tag}] ${record.content}`;
+            if (record.skill_tag) {
+                line += ` (skill: ${record.skill_tag})`;
+            }
+            return line;
+        });
+        const prependContext = `<relevant-memories>\n  The following memories are relevant to this query. Reference only if helpful:\n\n  ${memoryLines.join("\n  ")}\n</relevant-memories>`;
+        // Build appendSystemContext with Contextual Focus Navigation + tools guide
+        const topScenes = this.store.getTopContextualFocus(userId, 3);
+        let appendSystemContext = "";
+        if (topScenes.length > 0) {
+            const sceneNav = topScenes
+                .map(s => `  - ${s.sceneName} (heat: ${s.heatScore.toFixed(0)})`)
+                .join("\n");
+            appendSystemContext += `<scene-navigation>\n  Recent focus scenes:\n${sceneNav}\n</scene-navigation>\n\n`;
+        }
+        appendSystemContext += `<memory-tools-guide>
+  Use memory_search to retrieve more specific memories.
+  Use memory_contradictions to review unresolved conflicts.
+  Max 3 memory tool calls per turn.
+</memory-tools-guide>`;
+        // Graph context expansion (2-hop BFS from matched entities)
+        const graphContext = expandRecallWithGraph({
+            topCognitiveResults: topResults.map(r => r.record),
+            query,
+            userId,
+            activeSkill,
+            store: this.store
+        });
+        const hasGraphExpansion = !!graphContext;
+        if (graphContext) {
+            appendSystemContext += `\n${graphContext}`;
+        }
+        if (process.env.BRAINROUTER_PREWARM_ENABLED === "true") {
+            try {
+                const prewarmResults = detectPrewarmSkills({
+                    userId,
+                    store: this.store,
+                    excludeSkill: activeSkill,
+                });
+                const prewarmBlock = buildPrewarmBlock(prewarmResults);
+                if (prewarmBlock) {
+                    appendSystemContext += `\n${prewarmBlock}`;
+                }
+            }
+            catch (e) {
+                console.error("[BrainRouter] Skill pre-warming skipped:", e.message);
+            }
+        }
+        const recalledCognitiveMemories = topResults.map(r => ({
+            content: r.record.content,
+            score: r.score,
+            type: r.record.type,
+            recordId: r.record.record_id,
+            skillTag: r.record.skill_tag
+        }));
+        const recallStrategy = vecResults.length > 0
+            ? (usedReranker ? "hybrid+rerank" : "hybrid")
+            : (usedReranker ? "keyword+rerank" : (filePathResults.length > 0 ? "keyword+file" : "keyword"));
+        const durationMs = Date.now() - startTime;
+        const recallExplanation = {
+            ftsHits: ftsResults.length,
+            vecHits: vecResults.length,
+            filePathHits: filePathResults.length,
+            rrfTopScore,
+            intentDetected: intent,
+            typeBoosts,
+            skillBoostApplied,
+            rerankerUsed: usedReranker,
+            graphExpansion: hasGraphExpansion,
+            citationBoosts,
+            durationMs,
+            rerankerCandidates: rerankCandidates.length,
+            scoredRecords: topResults.map(r => ({
+                recordId: r.record.record_id,
+                finalScore: r.score,
+                type: r.record.type,
+            })),
+            sparkedNodes,
+        };
+        if (!params.explain) {
+            this.writeRecallOp(userId, sessionKey, query, recallStrategy, topResults.length, durationMs, recallExplanation);
+        }
+        return {
+            prependContext,
+            appendSystemContext,
+            recalledCognitiveMemories,
+            recallStrategy,
+            activeFocusName: topScenes[0]?.sceneName,
+            recallExplanation,
+        };
+    }
+    async explainRecall(params) {
+        return this.recall({ ...params, explain: true });
+    }
+    writeRecallOp(userId, sessionKey, query, strategy, hitCount, durationMs, explanation) {
+        try {
+            this.store.insertOperation({
+                id: randomUUID(),
+                userId,
+                recordId: null,
+                operation: "recall",
+                actor: "agent",
+                sessionKey,
+                reason: "",
+                createdAt: new Date().toISOString(),
+                metadata: {
+                    query: query.slice(0, 500),
+                    strategy,
+                    hitCount,
+                    durationMs,
+                    ftsHits: explanation?.ftsHits ?? 0,
+                    vecHits: explanation?.vecHits ?? 0,
+                    intentDetected: explanation?.intentDetected ?? "none",
+                    rerankerUsed: explanation?.rerankerUsed ?? false,
+                },
+            });
+        }
+        catch {
+            // Audit writes are best-effort
+        }
+    }
+    expandWithFilePathMatches(userId, query) {
+        const filePaths = extractFilePathHints(query);
+        if (filePaths.length === 0)
+            return [];
+        const records = new Map();
+        for (const filePath of filePaths) {
+            for (const record of this.store.getMemoriesByFilePath(userId, filePath, 10)) {
+                records.set(record.id, record);
+            }
+        }
+        return Array.from(records.values()).map((record) => ({
+            record_id: record.id,
+            user_id: record.userId,
+            content: record.content,
+            type: record.type,
+            priority: record.priority,
+            scene_name: record.sceneName,
+            skill_tag: record.skillTag,
+            score: 1,
+            timestamp_str: record.timestampStr,
+            timestamp_start: record.timestampStart,
+            timestamp_end: record.timestampEnd,
+            session_key: record.sessionKey,
+            session_id: record.sessionId,
+            metadata_json: JSON.stringify(record.metadata),
+            created_time: record.createdTime,
+            citation_count: record.citationCount,
+        }));
+    }
+}

package/dist/memory/redaction.d.ts

@@ -0,0 +1 @@
+export declare function redactSensitiveMemoryText(text: string): string;

package/dist/memory/redaction.js

@@ -0,0 +1,24 @@
+// Each pattern targets a specific secret format.
+// All patterns use the /g flag so String.replace replaces all occurrences per call.
+// The array is module-level (not re-created per call) — safe because .replace() does
+// not mutate lastIndex on string arguments.
+const REDACTION_PATTERNS = [
+    // HTTP Authorization: Bearer <token>
+    [/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, "[REDACTED]"],
+    // OpenAI-style secret keys (sk-...)
+    [/\bsk-[A-Za-z0-9_-]{8,}\b/g, "[REDACTED]"],
+    // GitHub personal access tokens (ghp_...)
+    [/\bghp_[A-Za-z0-9_]{8,}\b/g, "[REDACTED]"],
+    // PEM private key blocks
+    [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, "[REDACTED]"],
+    // Database connection strings (Postgres, MongoDB, MySQL, Redis, SQLite).
+    [/\b(?:postgres|postgresql|mongodb|mysql|mongodb\+srv|redis|sqlite):\/\/[^:\s]+:[^@\s]+@[^\s]+\b/gi, "[REDACTED_CONN_STR]"],
+    // IPv4 addresses can expose infrastructure details.
+    [/\b(?:\d{1,3}\.){3}\d{1,3}\b/g, "[REDACTED_IP]"],
+    // .env-style assignments: API_KEY=... SECRET=... — require ≥6 chars in value to
+    // avoid over-redacting innocuous env vars like RETRY_COUNT=3 or LOG_LEVEL=info.
+    [/^[ \t]*[A-Z0-9_]*(?:API_KEY|TOKEN|SECRET|PASSWORD)[A-Z0-9_]*[ \t]*=[ \t]*\S{6,}.*$/gim, "[REDACTED]"],
+];
+export function redactSensitiveMemoryText(text) {
+    return REDACTION_PATTERNS.reduce((value, [pattern, replacement]) => value.replace(pattern, replacement), text);
+}

package/dist/memory/retry.d.ts

@@ -0,0 +1,13 @@
+export interface ExternalApiRetryOptions {
+    label: string;
+    maxRetries?: number;
+    baseDelayMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare class ExternalApiError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+export declare function isRetryableExternalError(error: unknown): boolean;
+export declare function retryExternalCall<T>(operation: () => Promise<T>, options: ExternalApiRetryOptions): Promise<T>;
+export declare function fetchWithExternalRetry(input: string | URL | Request, init: RequestInit, options: ExternalApiRetryOptions): Promise<Response>;

package/dist/memory/retry.js

@@ -0,0 +1,53 @@
+export class ExternalApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "ExternalApiError";
+    }
+}
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_BASE_DELAY_MS = 2_000;
+const RETRYABLE_HTTP_STATUSES = new Set([429, 503]);
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function isRetryableExternalError(error) {
+    if (error instanceof ExternalApiError) {
+        return error.status !== undefined && RETRYABLE_HTTP_STATUSES.has(error.status);
+    }
+    if (error instanceof TypeError) {
+        return true;
+    }
+    return false;
+}
+export async function retryExternalCall(operation, options) {
+    const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const baseDelayMs = options.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+    const sleep = options.sleep ?? defaultSleep;
+    let attempt = 0;
+    while (true) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            if (attempt >= maxRetries || !isRetryableExternalError(error)) {
+                throw error;
+            }
+            const delayMs = baseDelayMs * (2 ** attempt);
+            attempt += 1;
+            console.error(`[BrainRouter] ${options.label} failed with a retryable error. Retrying in ${delayMs}ms (attempt ${attempt}/${maxRetries}).`);
+            await sleep(delayMs);
+        }
+    }
+}
+export async function fetchWithExternalRetry(input, init, options) {
+    return retryExternalCall(async () => {
+        const response = await fetch(input, init);
+        if (RETRYABLE_HTTP_STATUSES.has(response.status)) {
+            response.body?.cancel().catch(() => undefined);
+            throw new ExternalApiError(`${options.label} failed with HTTP ${response.status} ${response.statusText}`, response.status);
+        }
+        return response;
+    }, options);
+}

package/dist/memory/scheduler.d.ts

@@ -0,0 +1,9 @@
+/** Focus distillation fires every N new Cognitive extractions per user (default: 10). */
+export declare const FOCUS_TRIGGER_EVERY_N: number;
+/** Identity distillation fires every N new Cognitive extractions per user (default: 50). */
+export declare const IDENTITY_TRIGGER_EVERY_N: number;
+/** Focus auto-merge max scenes threshold (default: 20). */
+export declare const MAX_FOCUS_SCENES: number;
+import type { SchedulerState } from "@kinqs/brainrouter-types";
+export declare function shouldRunFocusDistill(state: SchedulerState): boolean;
+export declare function shouldRunIdentityDistill(state: SchedulerState): boolean;

package/dist/memory/scheduler.js

@@ -0,0 +1,16 @@
+// ============================
+// Scheduler — N-turn trigger evaluator
+// ============================
+// Stateless logic only. State is persisted in the DB via SqliteMemoryStore.
+/** Focus distillation fires every N new Cognitive extractions per user (default: 10). */
+export const FOCUS_TRIGGER_EVERY_N = parseInt(process.env.BRAINROUTER_FOCUS_TRIGGER_N ?? "10", 10);
+/** Identity distillation fires every N new Cognitive extractions per user (default: 50). */
+export const IDENTITY_TRIGGER_EVERY_N = parseInt(process.env.BRAINROUTER_IDENTITY_TRIGGER_N ?? "50", 10);
+/** Focus auto-merge max scenes threshold (default: 20). */
+export const MAX_FOCUS_SCENES = parseInt(process.env.BRAINROUTER_MAX_FOCUS_SCENES ?? "20", 10);
+export function shouldRunFocusDistill(state) {
+    return state.cognitiveCountSinceLastFocus >= FOCUS_TRIGGER_EVERY_N;
+}
+export function shouldRunIdentityDistill(state) {
+    return state.cognitiveCountSinceLastIdentity >= IDENTITY_TRIGGER_EVERY_N;
+}

package/dist/memory/skill-hints-loader.d.ts

@@ -0,0 +1,30 @@
+export interface SkillFrontmatter {
+    name?: string;
+    description?: string;
+    memory_hints?: string;
+    [key: string]: unknown;
+}
+/**
+ * Parse YAML frontmatter from a SKILL.md file.
+ * Uses a simple, zero-dependency regex parser that handles the common
+ * key: value and key: | (block scalar) patterns used in BrainRouter skills.
+ */
+export declare function parseSkillFrontmatter(content: string): SkillFrontmatter;
+/**
+ * Load memory_hints from a SKILL.md file.
+ * Returns null if the file doesn't exist or has no memory_hints field.
+ */
+export declare function loadSkillHints(skillMdPath: string): {
+    name: string;
+    hints: string;
+} | null;
+/**
+ * Scan a directory tree for SKILL.md files that contain memory_hints.
+ * Returns an array of { skillDir, name, hints } for each skill found.
+ */
+export declare function scanSkillsForHints(rootDir: string): Array<{
+    skillDir: string;
+    name: string;
+    hints: string;
+    filePath: string;
+}>;

package/dist/memory/skill-hints-loader.js

@@ -0,0 +1,100 @@
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+/**
+ * Parse YAML frontmatter from a SKILL.md file.
+ * Uses a simple, zero-dependency regex parser that handles the common
+ * key: value and key: | (block scalar) patterns used in BrainRouter skills.
+ */
+export function parseSkillFrontmatter(content) {
+    const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!fmMatch)
+        return {};
+    const yaml = fmMatch[1];
+    const result = {};
+    // Parse block scalars (key: |\n  line1\n  line2) and simple key: value lines
+    const lines = yaml.split(/\r?\n/);
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        // Detect block scalar: "key: |"
+        const blockMatch = line.match(/^(\w[\w_-]*):\s*\|(.*)$/);
+        if (blockMatch) {
+            const key = blockMatch[0].split(":")[0].trim();
+            const blockLines = [];
+            i++;
+            // Collect indented lines
+            while (i < lines.length && (lines[i].startsWith("  ") || lines[i].startsWith("\t") || lines[i] === "")) {
+                blockLines.push(lines[i].replace(/^  /, "").replace(/^\t/, ""));
+                i++;
+            }
+            result[key] = blockLines.join("\n").trimEnd();
+            continue;
+        }
+        // Simple key: value
+        const kvMatch = line.match(/^(\w[\w_-]*):\s*(.*)$/);
+        if (kvMatch) {
+            const key = kvMatch[1];
+            const val = kvMatch[2].trim().replace(/^["']|["']$/g, ""); // strip optional quotes
+            result[key] = val;
+        }
+        i++;
+    }
+    return result;
+}
+/**
+ * Load memory_hints from a SKILL.md file.
+ * Returns null if the file doesn't exist or has no memory_hints field.
+ */
+export function loadSkillHints(skillMdPath) {
+    if (!existsSync(skillMdPath))
+        return null;
+    let content;
+    try {
+        content = readFileSync(skillMdPath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+    const fm = parseSkillFrontmatter(content);
+    if (!fm.memory_hints || typeof fm.memory_hints !== "string" || !fm.memory_hints.trim()) {
+        return null;
+    }
+    const skillName = typeof fm.name === "string" ? fm.name : "";
+    return {
+        name: skillName,
+        hints: fm.memory_hints.trim()
+    };
+}
+/**
+ * Scan a directory tree for SKILL.md files that contain memory_hints.
+ * Returns an array of { skillDir, name, hints } for each skill found.
+ */
+export function scanSkillsForHints(rootDir) {
+    const results = [];
+    function walk(dir) {
+        try {
+            const entries = readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    walk(`${dir}/${entry.name}`);
+                }
+                else if (entry.name === "SKILL.md") {
+                    const filePath = `${dir}/${entry.name}`;
+                    const loaded = loadSkillHints(filePath);
+                    if (loaded) {
+                        results.push({
+                            skillDir: dir,
+                            name: loaded.name,
+                            hints: loaded.hints,
+                            filePath
+                        });
+                    }
+                }
+            }
+        }
+        catch {
+            return;
+        }
+    }
+    walk(rootDir);
+    return results;
+}