@andespindola/brainlink 0.1.0-beta.99 → 1.0.0

package/dist/application/build-context.js

@@ -1,37 +1,50 @@
 import { stat } from 'node:fs/promises';
+import { performance } from 'node:perf_hooks';
 import { formatContextPackage, selectContextSections } from '../domain/context.js';
+import { readContextPack, writeContextPack } from '../infrastructure/context-packs.js';
 import { indexStoragePath } from '../infrastructure/file-index.js';
+import { searchVolatileMemory, volatileMemoryStoragePath } from '../infrastructure/volatile-memory.js';
 import { searchKnowledge } from './search-knowledge.js';
-const contextCacheTtlMs = 45_000;
 const contextCacheMaxEntries = 200;
 const contextCache = new Map();
-const readIndexMtimeMs = async (vaultPath) => {
+const readFileSignature = async (path) => {
     try {
-        return (await stat(indexStoragePath(vaultPath))).mtimeMs;
+        const info = await stat(path);
+        return `${Math.floor(info.mtimeMs)}:${info.size}`;
     }
     catch {
-        return 0;
+        return '0:0';
     }
 };
-const toCacheKey = (vaultPath, query, limit, maxTokens, agentId, mode) => JSON.stringify({
+export const readContextDataSignature = async (vaultPath) => `${await readFileSignature(indexStoragePath(vaultPath))}|${await readFileSignature(volatileMemoryStoragePath(vaultPath))}`;
+const toCacheKey = (vaultPath, query, limit, maxTokens, agentId, mode, strategy) => JSON.stringify({
     vaultPath,
     query: query.trim().toLowerCase(),
     limit,
     maxTokens,
     agentId: agentId?.trim().toLowerCase() ?? '*',
-    mode: mode ?? 'default'
+    mode: mode ?? 'default',
+    strategy
 });
-const contextCacheGet = (key, indexMtimeMs) => {
+const withCacheMetadata = (context, cache) => ({
+    ...context,
+    cache
+});
+const contextCacheGet = (key, dataSignature, contextCacheTtlMs) => {
     const entry = contextCache.get(key);
     if (!entry) {
         return undefined;
     }
-    const fresh = Date.now() - entry.createdAt <= contextCacheTtlMs && entry.indexMtimeMs === indexMtimeMs;
+    const fresh = Date.now() - entry.createdAt <= contextCacheTtlMs && entry.dataSignature === dataSignature;
     if (!fresh) {
         contextCache.delete(key);
         return undefined;
     }
-    return entry.context;
+    return withCacheMetadata(entry.context, {
+        storage: 'memory',
+        status: 'hit',
+        dataSignature
+    });
 };
 const contextCacheSet = (entry) => {
     contextCache.set(entry.key, entry);
@@ -42,29 +55,115 @@ const contextCacheSet = (entry) => {
     const keys = Array.from(contextCache.keys()).slice(0, overflow);
     keys.forEach((key) => contextCache.delete(key));
 };
-export const buildContextPackage = async (vaultPath, query, limit, maxTokens, agentId, mode) => {
-    const cacheKey = toCacheKey(vaultPath, query, limit, maxTokens, agentId, mode);
-    const indexMtimeMs = await readIndexMtimeMs(vaultPath);
-    const cached = contextCacheGet(cacheKey, indexMtimeMs);
+const elapsedMs = (start) => Math.round((performance.now() - start) * 1000) / 1000;
+const estimateSectionTokens = (context) => Math.ceil(context.content.length / 4);
+const emptyMetrics = (context, totalMs, overrides = {}) => ({
+    totalMs,
+    packReadMs: 0,
+    searchMs: 0,
+    selectionMs: 0,
+    volatileMs: 0,
+    packWriteMs: 0,
+    sectionCount: context.sections.length,
+    volatileSectionCount: context.volatileSections?.length ?? 0,
+    estimatedTokens: estimateSectionTokens(context),
+    ...overrides
+});
+export const buildContextPackage = async (vaultPath, query, limit, maxTokens, agentId, mode, strategy = 'rag', contextCacheTtlMs = 120_000) => {
+    const totalStart = performance.now();
+    const cacheKey = toCacheKey(vaultPath, query, limit, maxTokens, agentId, mode, strategy);
+    const dataSignature = await readContextDataSignature(vaultPath);
+    const cached = contextCacheGet(cacheKey, dataSignature, contextCacheTtlMs);
     if (cached) {
         return cached;
     }
+    const shouldUseContextPack = strategy === 'cag' || strategy === 'auto';
+    let packReadMs = 0;
+    if (shouldUseContextPack) {
+        const packReadStart = performance.now();
+        const pack = await readContextPack(vaultPath, { query, limit, maxTokens, agentId, mode }, dataSignature);
+        packReadMs = elapsedMs(packReadStart);
+        if (pack.status === 'hit') {
+            const contextFromPack = {
+                ...pack.context,
+                strategy: 'cag',
+                requestedStrategy: strategy,
+                recommendedStrategy: {
+                    strategy: 'cag',
+                    reason: strategy === 'auto'
+                        ? 'A fresh context pack exists, so auto selected CAG.'
+                        : 'The requested CAG context pack is fresh.'
+                },
+                metrics: emptyMetrics(pack.context, elapsedMs(totalStart), { packReadMs })
+            };
+            contextCacheSet({
+                key: cacheKey,
+                createdAt: Date.now(),
+                dataSignature,
+                strategy,
+                context: contextFromPack
+            });
+            return contextFromPack;
+        }
+    }
+    const searchStart = performance.now();
     const results = await searchKnowledge(vaultPath, query, limit, agentId, mode);
-    const sections = selectContextSections(results, maxTokens);
+    const searchMs = elapsedMs(searchStart);
+    const selectionStart = performance.now();
+    const durableSections = selectContextSections(results, maxTokens);
+    const selectionMs = elapsedMs(selectionStart);
+    const volatileStart = performance.now();
+    const volatileSections = await searchVolatileMemory(vaultPath, query, Math.min(3, limit), agentId, mode ?? 'hybrid');
+    const volatileMs = elapsedMs(volatileStart);
+    const sections = [...volatileSections, ...durableSections];
+    const effectiveStrategy = strategy === 'cag' ? 'cag' : 'rag';
     const context = {
         query,
         sections,
-        content: formatContextPackage(query, sections)
+        content: formatContextPackage(query, sections),
+        ...(volatileSections.length > 0 ? { volatileSections } : {}),
+        strategy: effectiveStrategy,
+        requestedStrategy: strategy,
+        recommendedStrategy: {
+            strategy: effectiveStrategy,
+            reason: strategy === 'auto'
+                ? 'No fresh context pack was available, so auto selected fresh RAG assembly and refreshed a pack for future reuse.'
+                : effectiveStrategy === 'cag'
+                    ? 'CAG was requested; Brainlink refreshed the context pack from current retrieval results.'
+                    : 'RAG was requested; Brainlink assembled context directly from current retrieval results.'
+        }
+    };
+    const packWriteStart = performance.now();
+    const packPath = shouldUseContextPack
+        ? await writeContextPack(vaultPath, { query, limit, maxTokens, agentId, mode }, dataSignature, context)
+        : undefined;
+    const packWriteMs = packPath ? elapsedMs(packWriteStart) : 0;
+    const contextWithMetadata = withCacheMetadata(context, {
+        storage: shouldUseContextPack ? 'context-pack' : 'memory',
+        status: shouldUseContextPack ? 'refresh' : 'miss',
+        dataSignature,
+        ...(packPath ? { path: packPath } : {})
+    });
+    const contextWithMetrics = {
+        ...contextWithMetadata,
+        metrics: emptyMetrics(contextWithMetadata, elapsedMs(totalStart), {
+            packReadMs,
+            searchMs,
+            selectionMs,
+            volatileMs,
+            packWriteMs
+        })
     };
     contextCacheSet({
         key: cacheKey,
         createdAt: Date.now(),
-        indexMtimeMs,
-        context
+        dataSignature,
+        strategy,
+        context: contextWithMetrics
     });
-    return context;
+    return contextWithMetrics;
 };
-export const buildContext = async (vaultPath, query, limit, maxTokens, agentId, mode) => {
-    const contextPackage = await buildContextPackage(vaultPath, query, limit, maxTokens, agentId, mode);
+export const buildContext = async (vaultPath, query, limit, maxTokens, agentId, mode, strategy, contextCacheTtlMs = 120_000) => {
+    const contextPackage = await buildContextPackage(vaultPath, query, limit, maxTokens, agentId, mode, strategy, contextCacheTtlMs);
     return contextPackage.content;
 };

package/dist/application/canonical-context-links.js

@@ -0,0 +1,209 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { inferVisualGraphContext } from '../domain/graph-contexts.js';
+import { sanitizeAgentId, sharedAgentId } from '../domain/agents.js';
+import { extractContextLinkWeights, parseMarkdownDocument } from '../domain/markdown.js';
+import { ensureVault, readMarkdownFileSummaries, writeMarkdownFile } from '../infrastructure/file-system-vault.js';
+const canonicalPriority = 'high';
+const slugify = (title) => title
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+export const hubTitleForContext = (contextTitle) => `${contextTitle} Hub`;
+const hubPathForContext = (contextTitle, agentId) => {
+    if (contextTitle === 'GitHub Repositories')
+        return 'github-repos/github-repositories-hub.md';
+    if (contextTitle === 'GitHub Organizations')
+        return 'github-org-repos/github-organizations-hub.md';
+    if (contextTitle === 'Machine Configuration')
+        return 'machine-config/machine-configuration-hub.md';
+    return join('agents', sanitizeAgentId(agentId), `${slugify(hubTitleForContext(contextTitle))}.md`).replaceAll('\\', '/');
+};
+const normalizeTitle = (title) => title.trim().replace(/\.md$/i, '').toLowerCase();
+const hasCanonicalLink = (content, hubTitle) => extractContextLinkWeights(content).some((link) => normalizeTitle(link.title) === normalizeTitle(hubTitle));
+const linkLine = (hubTitle) => `- [[${hubTitle}]] priority: ${canonicalPriority}`;
+const contextLinksHeading = (line) => line.match(/^(#{2,6})\s+(Context Links|Links de Contexto)\s*$/i);
+export const upsertCanonicalContextLink = (content, hubTitle) => {
+    if (hasCanonicalLink(content, hubTitle)) {
+        return content;
+    }
+    const lines = content.replace(/\s+$/u, '').split('\n');
+    const headingIndex = lines.findIndex((line) => contextLinksHeading(line.trim()));
+    if (headingIndex === -1) {
+        return `${lines.join('\n')}\n\n## Context Links\n\n${linkLine(hubTitle)}\n`;
+    }
+    const heading = contextLinksHeading(lines[headingIndex].trim());
+    const headingDepth = heading?.[1]?.length ?? 2;
+    const insertIndex = lines.findIndex((line, index) => {
+        if (index <= headingIndex)
+            return false;
+        const candidate = line.match(/^(#{2,6})\s+/);
+        return Boolean(candidate && candidate[1].length <= headingDepth);
+    });
+    const targetIndex = insertIndex === -1 ? lines.length : insertIndex;
+    const before = lines.slice(0, targetIndex);
+    const after = lines.slice(targetIndex);
+    const needsSpacer = before[before.length - 1]?.trim() !== '';
+    const nextLines = [...before, ...(needsSpacer ? [''] : []), linkLine(hubTitle), ...after];
+    return `${nextLines.join('\n').replace(/\s+$/u, '')}\n`;
+};
+const buildHubContent = (hubTitle, contextTitle, agentId) => [
+    '---',
+    `title: "${hubTitle.replaceAll('"', '\\"')}"`,
+    `agent: "${sanitizeAgentId(agentId)}"`,
+    '---',
+    '',
+    `# ${hubTitle}`,
+    '',
+    `Canonical hub for the ${contextTitle} context. #memory #hub`,
+    ''
+].join('\n');
+const readNotes = async (vaultPath) => {
+    const absoluteVaultPath = await ensureVault(vaultPath);
+    const summaries = await readMarkdownFileSummaries(absoluteVaultPath);
+    return Promise.all(summaries.map(async (summary) => {
+        const content = await readFile(summary.absolutePath, 'utf8');
+        const document = parseMarkdownDocument({
+            absolutePath: summary.absolutePath,
+            vaultPath: absoluteVaultPath,
+            content,
+            createdAt: summary.createdAt,
+            updatedAt: summary.updatedAt
+        });
+        return {
+            summary,
+            content,
+            document
+        };
+    }));
+};
+export const ensureCanonicalContextHub = async (vaultPath, contextTitle, agentId = sharedAgentId) => {
+    const hubTitle = hubTitleForContext(contextTitle);
+    const notes = await readNotes(vaultPath);
+    const existing = notes.find((note) => normalizeTitle(note.document.title) === normalizeTitle(hubTitle));
+    const hubPath = existing?.summary.relativePath ?? hubPathForContext(contextTitle, agentId);
+    if (existing) {
+        return {
+            created: false,
+            title: hubTitle,
+            path: hubPath
+        };
+    }
+    const path = await writeMarkdownFile(vaultPath, hubPath, buildHubContent(hubTitle, contextTitle, agentId));
+    return {
+        created: true,
+        title: hubTitle,
+        path
+    };
+};
+export const canonicalizeContextLinks = async (vaultPath, options = {}) => {
+    const agentId = options.agentId ? sanitizeAgentId(options.agentId) : undefined;
+    const createMissingHubs = options.createMissingHubs !== false;
+    const notes = await readNotes(vaultPath);
+    const scopedNotes = agentId ? notes.filter((note) => note.document.agentId === agentId) : notes;
+    const knownTitles = new Set(notes.map((note) => normalizeTitle(note.document.title)));
+    const entries = [];
+    const ensureHub = async (contextTitle, hubTitle, targetAgentId) => {
+        if (knownTitles.has(normalizeTitle(hubTitle))) {
+            return true;
+        }
+        const path = hubPathForContext(contextTitle, targetAgentId);
+        if (!createMissingHubs) {
+            entries.push({
+                path,
+                title: hubTitle,
+                context: contextTitle,
+                hubTitle,
+                changed: false,
+                reason: 'missing-hub'
+            });
+            return false;
+        }
+        knownTitles.add(normalizeTitle(hubTitle));
+        if (!options.dryRun) {
+            await writeMarkdownFile(vaultPath, path, buildHubContent(hubTitle, contextTitle, targetAgentId));
+        }
+        entries.push({
+            path,
+            title: hubTitle,
+            context: contextTitle,
+            hubTitle,
+            changed: true,
+            reason: 'created-hub'
+        });
+        return true;
+    };
+    for (const note of scopedNotes) {
+        const context = inferVisualGraphContext(note.document);
+        const hubTitle = hubTitleForContext(context.title);
+        const isHub = normalizeTitle(note.document.title) === normalizeTitle(hubTitle);
+        if (isHub) {
+            entries.push({
+                path: note.summary.relativePath,
+                title: note.document.title,
+                context: context.title,
+                hubTitle,
+                changed: false,
+                reason: 'hub-note'
+            });
+            continue;
+        }
+        const hubAvailable = await ensureHub(context.title, hubTitle, note.document.agentId || sharedAgentId);
+        if (!hubAvailable) {
+            continue;
+        }
+        if (hasCanonicalLink(note.content, hubTitle)) {
+            entries.push({
+                path: note.summary.relativePath,
+                title: note.document.title,
+                context: context.title,
+                hubTitle,
+                changed: false,
+                reason: 'already-linked'
+            });
+            continue;
+        }
+        const nextContent = upsertCanonicalContextLink(note.content, hubTitle);
+        if (!options.dryRun) {
+            await writeMarkdownFile(vaultPath, note.summary.relativePath, nextContent);
+        }
+        entries.push({
+            path: note.summary.relativePath,
+            title: note.document.title,
+            context: context.title,
+            hubTitle,
+            changed: true,
+            reason: 'added-context-link'
+        });
+    }
+    const changed = entries.filter((entry) => entry.changed).length;
+    const createdHubs = entries.filter((entry) => entry.reason === 'created-hub' && entry.changed).length;
+    return {
+        dryRun: options.dryRun === true,
+        scanned: scopedNotes.length,
+        changed,
+        createdHubs,
+        skipped: entries.length - changed,
+        entries
+    };
+};
+export const addCanonicalContextLinkToContent = (title, content) => {
+    const context = inferVisualGraphContext({
+        id: '',
+        agentId: sharedAgentId,
+        title,
+        path: '',
+        content,
+        tags: [],
+    });
+    const hubTitle = hubTitleForContext(context.title);
+    const nextContent = normalizeTitle(title) === normalizeTitle(hubTitle) ? content : upsertCanonicalContextLink(content, hubTitle);
+    return {
+        content: nextContent,
+        context: context.title,
+        hubTitle,
+        changed: nextContent !== content
+    };
+};