@andespindola/brainlink 0.1.0-alpha.0

package/dist/application/start-server.js

@@ -0,0 +1,54 @@
+import { createServer } from 'node:http';
+import { indexVault } from './index-vault.js';
+import { startVaultWatcher } from './watch-vault.js';
+import { assertPublicBindAllowed } from './server/host-security.js';
+import { contentTypes, createJsonResponse, isHttpError } from './server/http.js';
+import { route } from './server/routes.js';
+export const startServer = async (input) => {
+    assertPublicBindAllowed(input.host, input.allowPublic);
+    if (input.shouldIndex) {
+        await indexVault(input.vaultPath);
+    }
+    const watcher = input.shouldWatch
+        ? startVaultWatcher({
+            vaultPath: input.vaultPath,
+            onError: (error) => console.error(error)
+        })
+        : null;
+    const server = createServer((request, response) => {
+        const url = new URL(request.url ?? '/', `http://${request.headers.host ?? input.host}`);
+        route(request, url, input.vaultPath)
+            .then((result) => {
+            response.writeHead(result.statusCode, result.headers);
+            response.end(result.body);
+        })
+            .catch((error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            const statusCode = isHttpError(error) ? error.statusCode : 500;
+            response.writeHead(statusCode, { 'content-type': contentTypes['.json'] });
+            response.end(createJsonResponse({ error: message }));
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(input.port, input.host, () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    const port = typeof address === 'object' && address ? address.port : input.port;
+    return {
+        url: `http://${input.host}:${port}`,
+        close: () => new Promise((resolve, reject) => {
+            watcher?.close();
+            server.close((error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            });
+        })
+    };
+};

package/dist/application/watch-vault.js

@@ -0,0 +1,36 @@
+import { watch } from 'node:fs';
+import { indexVault } from './index-vault.js';
+import { resolveVaultPath } from '../infrastructure/file-system-vault.js';
+const shouldIgnore = (filename) => {
+    if (!filename) {
+        return false;
+    }
+    return filename.includes('.brainlink') || !filename.endsWith('.md');
+};
+export const startVaultWatcher = (input) => {
+    const absoluteVaultPath = resolveVaultPath(input.vaultPath);
+    const debounceMs = input.debounceMs ?? 350;
+    let timeout = null;
+    const schedule = (filename) => {
+        if (shouldIgnore(filename)) {
+            return;
+        }
+        if (timeout) {
+            clearTimeout(timeout);
+        }
+        timeout = setTimeout(() => {
+            indexVault(absoluteVaultPath).then(input.onIndex).catch(input.onError);
+        }, debounceMs);
+    };
+    const watcher = watch(absoluteVaultPath, { recursive: true }, (_eventType, filename) => {
+        schedule(filename?.toString() ?? null);
+    });
+    return {
+        close: () => {
+            if (timeout) {
+                clearTimeout(timeout);
+            }
+            watcher.close();
+        }
+    };
+};

package/dist/benchmarks/large-vault.js

@@ -0,0 +1,88 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { indexVault } from '../application/index-vault.js';
+import { searchKnowledge } from '../application/search-knowledge.js';
+import { ensureVault } from '../infrastructure/file-system-vault.js';
+const parsePositiveInteger = (value, fallback) => {
+    const parsed = Number.parseInt(value ?? '', 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+};
+const readStringOption = (args, name) => {
+    const index = args.indexOf(name);
+    const value = index >= 0 ? args[index + 1] : undefined;
+    return value && !value.startsWith('--') ? value : undefined;
+};
+const readOptions = (args) => ({
+    notes: parsePositiveInteger(readStringOption(args, '--notes'), 2000),
+    agent: readStringOption(args, '--agent') ?? 'benchmark-agent',
+    keep: args.includes('--keep')
+});
+const topics = [
+    'authentication jwt token refresh policy',
+    'sqlite graph backlinks markdown vault indexing',
+    'frontend canvas layout graph interaction',
+    'agent memory context retrieval summarization',
+    'security local server vault path allowlist',
+    'operations release npm github actions smoke test',
+    'architecture functional core imperative shell boundaries'
+];
+const formatNote = (index) => {
+    const topic = topics[index % topics.length];
+    const previous = index > 0 ? `[[Benchmark Note ${index - 1}]]` : '';
+    const related = index > 7 ? `[[Benchmark Note ${index - 7}]]` : '';
+    return [
+        `# Benchmark Note ${index}`,
+        '',
+        `This note captures ${topic}.`,
+        `The implementation detail number ${index} repeats ${topic} for semantic retrieval pressure.`,
+        `Related: ${[previous, related].filter(Boolean).join(' ')}`,
+        '',
+        `#benchmark #topic-${index % topics.length}`
+    ].join('\n');
+};
+const writeBenchmarkVault = async (vaultPath, options) => {
+    const agentPath = join(vaultPath, 'agents', options.agent);
+    await mkdir(agentPath, { recursive: true, mode: 0o700 });
+    await Promise.all(Array.from({ length: options.notes }, (_, index) => writeFile(join(agentPath, `benchmark-note-${index}.md`), formatNote(index), { encoding: 'utf8', mode: 0o600 })));
+};
+const timed = async (name, operation) => {
+    const start = performance.now();
+    const result = await operation();
+    return [name, performance.now() - start, result];
+};
+const printMetric = (name, durationMs) => {
+    console.log(`${name}: ${durationMs.toFixed(1)}ms`);
+};
+const main = async () => {
+    const options = readOptions(process.argv.slice(2));
+    const vaultPath = await mkdtemp(join(tmpdir(), 'brainlink-benchmark-'));
+    try {
+        await ensureVault(vaultPath);
+        const [, writeMs] = await timed('write', () => writeBenchmarkVault(vaultPath, options));
+        const [, indexMs, indexResult] = await timed('index', () => indexVault(vaultPath));
+        const [, semanticMs, semanticResults] = await timed('semantic search', () => searchKnowledge(vaultPath, 'authentication token policy', 10, options.agent, 'semantic'));
+        const [, hybridMs, hybridResults] = await timed('hybrid search', () => searchKnowledge(vaultPath, 'graph retrieval indexing', 10, options.agent, 'hybrid'));
+        console.log(`vault: ${vaultPath}`);
+        console.log(`notes: ${options.notes}`);
+        console.log(`documents: ${indexResult.documentCount}`);
+        console.log(`chunks: ${indexResult.chunkCount}`);
+        printMetric('write', writeMs);
+        printMetric('index', indexMs);
+        printMetric('semantic search', semanticMs);
+        printMetric('hybrid search', hybridMs);
+        console.log(`semantic top: ${semanticResults[0]?.title ?? 'none'}`);
+        console.log(`hybrid top: ${hybridResults[0]?.title ?? 'none'}`);
+    }
+    finally {
+        if (!options.keep) {
+            await rm(vaultPath, { recursive: true, force: true });
+        }
+    }
+};
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exitCode = 1;
+});

package/dist/cli/commands/read-commands.js

@@ -0,0 +1,149 @@
+import { getBrokenLinksReport, getOrphansReport, getStats, validateVault } from '../../application/analyze-vault.js';
+import { buildContextPackage } from '../../application/build-context.js';
+import { getGraph } from '../../application/get-graph.js';
+import { listAgents } from '../../application/list-agents.js';
+import { listBacklinks, listLinks } from '../../application/list-links.js';
+import { searchKnowledge } from '../../application/search-knowledge.js';
+import { sanitizeSearchMode } from '../../infrastructure/config.js';
+import { parsePositiveInteger, print, resolveOptions } from '../runtime.js';
+export const registerReadCommands = (program) => {
+    program
+        .command('search')
+        .argument('<query>', 'search query')
+        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('-a, --agent <agent>', 'filter by agent memory namespace')
+        .option('-l, --limit <limit>', 'maximum results', '10')
+        .option('-m, --mode <mode>', 'search mode: fts, semantic or hybrid')
+        .option('--json', 'print machine-readable JSON')
+        .description('search indexed knowledge')
+        .action(async (query, options) => {
+        const resolved = await resolveOptions(options);
+        const limit = parsePositiveInteger(options.limit ?? String(resolved.config.defaultSearchLimit), resolved.config.defaultSearchLimit);
+        const mode = sanitizeSearchMode(options.mode, resolved.config.defaultSearchMode);
+        const results = await searchKnowledge(resolved.vault, query, limit, options.agent, mode);
+        print(options.json, { query, agent: options.agent, limit, mode, results }, () => results
+            .map((result, index) => [`${index + 1}. ${result.title} (${result.path}) score=${result.score.toFixed(3)} mode=${result.searchMode}`, result.content].join('\n'))
+            .join('\n\n'));
+    });
+    program
+        .command('links')
+        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('-a, --agent <agent>', 'filter by agent memory namespace')
+        .option('--json', 'print machine-readable JSON')
+        .description('list indexed wiki links')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const links = await listLinks(resolved.vault, options.agent);
+        print(options.json, { links }, () => links
+            .map((link) => {
+            const target = link.toPath ? `${link.toTitle} (${link.toPath})` : `${link.toTitle} (unresolved)`;
+            return `${link.fromTitle} (${link.fromPath}) -> ${target}`;
+        })
+            .join('\n'));
+    });
+    program
+        .command('backlinks')
+        .argument('<title>', 'target note title')
+        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('-a, --agent <agent>', 'filter by agent memory namespace')
+        .option('--json', 'print machine-readable JSON')
+        .description('list notes linking to a target note')
+        .action(async (title, options) => {
+        const resolved = await resolveOptions(options);
+        const backlinks = await listBacklinks(resolved.vault, title, options.agent);
+        print(options.json, { title, backlinks }, () => backlinks.map((link) => `${link.fromTitle} (${link.fromPath}) -> ${link.toTitle}`).join('\n'));
+    });
+    program
+        .command('context')
+        .argument('<query>', 'context query')
+        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('-a, --agent <agent>', 'filter by agent memory namespace')
+        .option('-l, --limit <limit>', 'maximum search results before context selection', '12')
+        .option('-t, --tokens <tokens>', 'maximum estimated context tokens', '2000')
+        .option('-m, --mode <mode>', 'search mode: fts, semantic or hybrid')
+        .option('--json', 'print machine-readable JSON')
+        .description('build a compact context package for an agent')
+        .action(async (query, options) => {
+        const resolved = await resolveOptions(options);
+        const mode = sanitizeSearchMode(options.mode, resolved.config.defaultSearchMode);
+        const contextPackage = await buildContextPackage(resolved.vault, query, parsePositiveInteger(options.limit ?? '12', 12), parsePositiveInteger(options.tokens ?? String(resolved.config.defaultContextTokens), resolved.config.defaultContextTokens), options.agent, mode);
+        print(options.json, contextPackage, () => contextPackage.content);
+    });
+    program
+        .command('graph')
+        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('-a, --agent <agent>', 'filter by agent memory namespace')
+        .option('--json', 'print machine-readable JSON')
+        .description('print indexed graph data')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const graph = await getGraph(resolved.vault, options.agent);
+        print(options.json, graph, () => JSON.stringify(graph, null, 2));
+    });
+    program
+        .command('agents')
+        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('--json', 'print machine-readable JSON')
+        .description('list indexed agent memory namespaces')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const agents = await listAgents(resolved.vault);
+        print(options.json, { agents }, () => agents.map((agent) => `${agent.id}: ${agent.documentCount} documents`).join('\n'));
+    });
+    program
+        .command('stats')
+        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('-a, --agent <agent>', 'filter by agent memory namespace')
+        .option('--json', 'print machine-readable JSON')
+        .description('print indexed vault statistics')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const stats = await getStats(resolved.vault, options.agent);
+        print(options.json, stats, () => [
+            `Documents: ${stats.documentCount}`,
+            `Links: ${stats.linkCount}`,
+            `Resolved links: ${stats.resolvedLinkCount}`,
+            `Broken links: ${stats.brokenLinkCount}`,
+            `Orphans: ${stats.orphanCount}`,
+            `Tags: ${stats.tagCount}`
+        ].join('\n'));
+    });
+    program
+        .command('broken-links')
+        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('-a, --agent <agent>', 'filter by agent memory namespace')
+        .option('--json', 'print machine-readable JSON')
+        .description('list unresolved wiki links')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const brokenLinks = await getBrokenLinksReport(resolved.vault, options.agent);
+        print(options.json, { brokenLinks }, () => brokenLinks.length === 0
+            ? 'No broken links found'
+            : brokenLinks.map((link) => `${link.fromTitle} (${link.fromPath}) -> ${link.toTitle}`).join('\n'));
+    });
+    program
+        .command('orphans')
+        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('-a, --agent <agent>', 'filter by agent memory namespace')
+        .option('--json', 'print machine-readable JSON')
+        .description('list indexed notes without incoming or outgoing links')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const orphans = await getOrphansReport(resolved.vault, options.agent);
+        print(options.json, { orphans }, () => orphans.length === 0 ? 'No orphan notes found' : orphans.map((node) => `${node.title} (${node.path})`).join('\n'));
+    });
+    program
+        .command('validate')
+        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('-a, --agent <agent>', 'filter by agent memory namespace')
+        .option('--json', 'print machine-readable JSON')
+        .description('validate indexed vault graph health')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const validation = await validateVault(resolved.vault, options.agent);
+        print(options.json, validation, () => validation.ok
+            ? 'Vault validation passed'
+            : `Vault validation failed: ${validation.brokenLinks.length} broken links, ${validation.orphans.length} orphan notes`);
+        process.exitCode = validation.ok ? 0 : 1;
+    });
+};

package/dist/cli/commands/write-commands.js

@@ -0,0 +1,107 @@
+import { addNote } from '../../application/add-note.js';
+import { indexVault } from '../../application/index-vault.js';
+import { startServer } from '../../application/start-server.js';
+import { startVaultWatcher } from '../../application/watch-vault.js';
+import { doctorVault } from '../../application/analyze-vault.js';
+import { loadBrainlinkConfig } from '../../infrastructure/config.js';
+import { assertVaultAllowed, ensureVault } from '../../infrastructure/file-system-vault.js';
+import { parsePositiveInteger, print, resolveOptions } from '../runtime.js';
+export const registerWriteCommands = (program) => {
+    program
+        .command('init')
+        .argument('[vault]', 'vault directory', '.')
+        .option('--json', 'print machine-readable JSON')
+        .description('initialize a Brainlink vault')
+        .action(async (vault, options) => {
+        const config = await loadBrainlinkConfig();
+        const path = await ensureVault(assertVaultAllowed(vault, config.allowedVaults));
+        print(options.json, { path }, () => `Initialized Brainlink vault at ${path}`);
+    });
+    program
+        .command('add')
+        .argument('<title>', 'note title')
+        .requiredOption('-c, --content <content>', 'markdown content')
+        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('-a, --agent <agent>', 'agent memory namespace', 'shared')
+        .option('--allow-sensitive', 'allow writing content that looks like a secret')
+        .option('--json', 'print machine-readable JSON')
+        .description('add a markdown note to the vault')
+        .action(async (title, options) => {
+        const resolved = await resolveOptions(options);
+        const path = await addNote(resolved.vault, title, options.content, options.agent, {
+            allowSensitive: Boolean(options.allowSensitive)
+        });
+        print(options.json, { title, agent: options.agent ?? 'shared', path }, () => `Created note at ${path}`);
+    });
+    program
+        .command('index')
+        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('--json', 'print machine-readable JSON')
+        .description('index markdown notes, links, tags and chunks')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const result = await indexVault(resolved.vault);
+        print(options.json, result, () => `Indexed ${result.documentCount} documents, ${result.chunkCount} chunks and ${result.linkCount} links`);
+    });
+    program
+        .command('doctor')
+        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('--json', 'print machine-readable JSON')
+        .description('run Brainlink environment and vault checks')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const report = await doctorVault(resolved.vault);
+        print(options.json, report, () => report.checks.map((check) => `${check.ok ? 'OK' : 'FAIL'} ${check.name}: ${check.message}`).join('\n'));
+        process.exitCode = report.ok ? 0 : 1;
+    });
+    program
+        .command('watch')
+        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('--json', 'print machine-readable JSON events')
+        .description('watch markdown files and reindex on changes')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const initial = await indexVault(resolved.vault);
+        const watcher = startVaultWatcher({
+            vaultPath: resolved.vault,
+            onIndex: (result) => {
+                print(options.json, { event: 'indexed', result }, () => `Indexed ${result.documentCount} documents, ${result.chunkCount} chunks and ${result.linkCount} links`);
+            },
+            onError: (error) => {
+                const message = error instanceof Error ? error.message : String(error);
+                print(options.json, { event: 'error', message }, () => message);
+            }
+        });
+        print(options.json, { event: 'watching', vault: resolved.vault, initial }, () => `Watching ${resolved.vault}`);
+        process.once('SIGINT', () => {
+            watcher.close();
+            process.exit(0);
+        });
+        process.once('SIGTERM', () => {
+            watcher.close();
+            process.exit(0);
+        });
+    });
+    program
+        .command('server')
+        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('-h, --host <host>', 'server host', '127.0.0.1')
+        .option('-p, --port <port>', 'server port', '4321')
+        .option('--no-index', 'skip indexing before starting the server')
+        .option('-w, --watch', 'watch markdown files and reindex on changes')
+        .option('--allow-public', 'allow binding the server to a non-loopback host')
+        .option('--json', 'print machine-readable JSON')
+        .description('start a local web UI for the knowledge graph')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const server = await startServer({
+            vaultPath: resolved.vault,
+            host: options.host ?? resolved.config.host,
+            port: parsePositiveInteger(options.port ?? String(resolved.config.port), resolved.config.port),
+            shouldIndex: options.index,
+            shouldWatch: Boolean(options.watch),
+            allowPublic: Boolean(options.allowPublic)
+        });
+        print(options.json, { url: server.url, watch: Boolean(options.watch), readonly: true }, () => `Brainlink graph server running at ${server.url}`);
+    });
+};

package/dist/cli/main.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { basename } from 'node:path';
+import { registerReadCommands } from './commands/read-commands.js';
+import { registerWriteCommands } from './commands/write-commands.js';
+const program = new Command();
+const cliName = basename(process.argv[1] ?? 'brainlink');
+const displayName = cliName === 'blink' ? 'blink' : 'brainlink';
+const aliasName = displayName === 'blink' ? 'brainlink' : 'blink';
+program
+    .name(displayName)
+    .alias(aliasName)
+    .description('Local-first knowledge memory for agents')
+    .version('0.1.0');
+registerWriteCommands(program);
+registerReadCommands(program);
+program.parseAsync().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exitCode = 1;
+});

package/dist/cli/runtime.js

@@ -0,0 +1,18 @@
+import { loadBrainlinkConfig } from '../infrastructure/config.js';
+import { assertVaultAllowed } from '../infrastructure/file-system-vault.js';
+export const parsePositiveInteger = (value, fallback) => {
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+};
+export const resolveOptions = async (options) => {
+    const config = await loadBrainlinkConfig();
+    const vault = options.vault ?? config.vault;
+    const allowedVault = assertVaultAllowed(vault, config.allowedVaults);
+    return {
+        config,
+        vault: allowedVault
+    };
+};
+export const print = (json, value, human) => {
+    console.log(json ? JSON.stringify(value, null, 2) : human());
+};

package/dist/cli/types.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/agents.js

@@ -0,0 +1,11 @@
+export const sharedAgentId = 'shared';
+export const sanitizeAgentId = (agentId) => agentId
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, '-')
+    .replace(/^-+|-+$/g, '') || sharedAgentId;
+export const resolveAgentIdFromPath = (path) => {
+    const [scope, agentId] = path.split('/');
+    return scope === 'agents' && agentId ? sanitizeAgentId(agentId) : sharedAgentId;
+};

package/dist/domain/context.js

@@ -0,0 +1,44 @@
+export const selectContextSections = (results, maxTokens) => {
+    const selected = results.reduce((state, result) => {
+        const tokenCost = Math.ceil(result.content.length / 4);
+        if (state.usedTokens + tokenCost > maxTokens || state.seenDocuments.has(result.documentId)) {
+            return state;
+        }
+        return {
+            usedTokens: state.usedTokens + tokenCost,
+            sections: [
+                ...state.sections,
+                {
+                    title: result.title,
+                    path: result.path,
+                    content: result.content,
+                    score: result.score,
+                    searchMode: result.searchMode,
+                    tags: result.tags
+                }
+            ],
+            seenDocuments: new Set([...state.seenDocuments, result.documentId])
+        };
+    }, {
+        usedTokens: 0,
+        sections: [],
+        seenDocuments: new Set()
+    });
+    return selected.sections;
+};
+export const formatContextPackage = (query, sections) => {
+    const body = sections
+        .map((section, index) => [
+        `## ${index + 1}. ${section.title}`,
+        `Source: ${section.path}`,
+        section.tags.length > 0 ? `Tags: ${section.tags.map((tag) => `#${tag}`).join(' ')}` : null,
+        `Score: ${section.score.toFixed(3)}`,
+        `Mode: ${section.searchMode}`,
+        '',
+        section.content
+    ]
+        .filter((value) => value !== null)
+        .join('\n'))
+        .join('\n\n');
+    return [`# Brainlink Context`, `Query: ${query}`, '', body || 'No relevant context found.'].join('\n');
+};

package/dist/domain/embeddings.js

@@ -0,0 +1,117 @@
+const localDimensions = 192;
+const defaultEmbeddingBucketCount = 24;
+const tokenPattern = /[\p{L}\p{N}_-]+/gu;
+const stopWords = new Set([
+    'a',
+    'as',
+    'and',
+    'ao',
+    'aos',
+    'com',
+    'da',
+    'das',
+    'de',
+    'do',
+    'dos',
+    'e',
+    'em',
+    'for',
+    'is',
+    'o',
+    'os',
+    'para',
+    'por',
+    'que',
+    'the',
+    'to',
+    'um',
+    'uma',
+    'use',
+    'uses',
+    'using'
+]);
+const aliases = {
+    ai: ['agent', 'model'],
+    api: ['interface', 'client'],
+    auth: ['authentication', 'authorization', 'identity'],
+    authentication: ['auth', 'identity'],
+    backend: ['server', 'api'],
+    cli: ['terminal', 'command'],
+    context: ['memory', 'knowledge'],
+    db: ['database', 'storage'],
+    frontend: ['ui', 'browser'],
+    jwt: ['token', 'auth', 'authentication'],
+    llm: ['ai', 'agent', 'model'],
+    mcp: ['agent', 'tool', 'integration'],
+    memory: ['context', 'knowledge'],
+    nodejs: ['node', 'runtime'],
+    test: ['tests', 'testing', 'validation'],
+    tests: ['test', 'testing', 'validation'],
+    token: ['jwt', 'auth'],
+    ui: ['frontend', 'browser']
+};
+const normalizeToken = (token) => token
+    .normalize('NFKD')
+    .replace(/\p{Diacritic}/gu, '')
+    .toLowerCase();
+const tokenize = (input) => input
+    .match(tokenPattern)
+    ?.map(normalizeToken)
+    .filter((token) => token.length > 1 && !stopWords.has(token)) ?? [];
+const expandTokens = (tokens) => tokens.flatMap((token) => [token, ...(aliases[token] ?? [])]);
+const hash = (value) => Array.from(value).reduce((state, char) => Math.imul(state ^ char.charCodeAt(0), 16777619), 2166136261) >>> 0;
+const featureHash = (feature) => {
+    const value = hash(feature);
+    const index = value % localDimensions;
+    const sign = value & 1 ? 1 : -1;
+    return [index, sign];
+};
+const normalizeVector = (vector) => {
+    const magnitude = Math.hypot(...vector);
+    return magnitude === 0 ? vector : vector.map((value) => value / magnitude);
+};
+const applyFeature = (vector, feature, weight) => {
+    const [index, sign] = featureHash(feature);
+    vector[index] = (vector[index] ?? 0) + sign * weight;
+    return vector;
+};
+const tokenFeatures = (tokens) => [
+    ...tokens.map((token) => `t:${token}`),
+    ...tokens.slice(0, -1).map((token, index) => `b:${token}:${tokens[index + 1]}`)
+];
+export const createLocalEmbedding = (input) => {
+    const tokens = expandTokens(tokenize(input));
+    const initial = Array.from({ length: localDimensions }, () => 0);
+    const weighted = tokenFeatures(tokens).reduce((vector, feature) => applyFeature(vector, feature, feature.startsWith('b:') ? 0.65 : 1), initial);
+    return normalizeVector(weighted);
+};
+export const cosineSimilarity = (left, right) => {
+    const length = Math.min(left.length, right.length);
+    if (length === 0) {
+        return 0;
+    }
+    const dot = left.slice(0, length).reduce((total, value, index) => total + value * (right[index] ?? 0), 0);
+    const leftMagnitude = Math.hypot(...left.slice(0, length));
+    const rightMagnitude = Math.hypot(...right.slice(0, length));
+    return leftMagnitude === 0 || rightMagnitude === 0 ? 0 : dot / (leftMagnitude * rightMagnitude);
+};
+const bucketKey = (index, value) => `${value >= 0 ? 'p' : 'n'}:${index}`;
+export const createEmbeddingBuckets = (vector, bucketCount = defaultEmbeddingBucketCount) => vector
+    .map((value, index) => ({
+    index,
+    value,
+    weight: Math.abs(value)
+}))
+    .filter((item) => item.weight > 0)
+    .sort((left, right) => right.weight - left.weight || left.index - right.index)
+    .slice(0, bucketCount)
+    .map((item) => bucketKey(item.index, item.value));
+export const createDisabledEmbeddingProvider = () => ({
+    name: 'none',
+    embed: async (input) => input.map(() => [])
+});
+export const createLocalEmbeddingProvider = () => ({
+    name: 'local',
+    embed: async (input) => input.map(createLocalEmbedding)
+});
+export const createEmbeddingProvider = (name) => name === 'local' ? createLocalEmbeddingProvider() : createDisabledEmbeddingProvider();