@andespindola/brainlink 0.1.0-beta.3 → 0.1.0-beta.30

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

@@ -1,4 +1,4 @@
-import { getBrokenLinksReport, getOrphansReport, getStats, validateVault } from '../../application/analyze-vault.js';
+import { getBrokenLinksReport, getExtendedStats, 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';
@@ -12,14 +12,14 @@ export const registerReadCommands = (program) => {
         .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('-l, --limit <limit>', 'maximum results')
         .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 limit = parsePositiveInteger(options.limit ?? String(resolved.defaults.defaultSearchLimit), resolved.defaults.defaultSearchLimit);
+        const mode = sanitizeSearchMode(options.mode, resolved.defaults.defaultSearchMode);
         const results = await searchKnowledge(resolved.vault, query, limit, resolved.agent, mode);
         print(options.json, { query, agent: resolved.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'))
@@ -58,15 +58,15 @@ export const registerReadCommands = (program) => {
         .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('-l, --limit <limit>', 'maximum search results before context selection')
+        .option('-t, --tokens <tokens>', 'maximum estimated context tokens')
         .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), resolved.agent, mode);
+        const mode = sanitizeSearchMode(options.mode, resolved.defaults.defaultSearchMode);
+        const contextPackage = await buildContextPackage(resolved.vault, query, parsePositiveInteger(options.limit ?? String(resolved.defaults.defaultSearchLimit), resolved.defaults.defaultSearchLimit), parsePositiveInteger(options.tokens ?? String(resolved.defaults.defaultContextTokens), resolved.defaults.defaultContextTokens), resolved.agent, mode);
         print(options.json, contextPackage, () => contextPackage.content);
     });
     program
@@ -94,10 +94,27 @@ export const registerReadCommands = (program) => {
         .command('stats')
         .option('-v, --vault <vault>', 'vault directory')
         .option('-a, --agent <agent>', 'filter by agent memory namespace')
+        .option('--extended', 'include storage, quality and latency observability probes')
         .option('--json', 'print machine-readable JSON')
         .description('print indexed vault statistics')
         .action(async (options) => {
         const resolved = await resolveOptions(options);
+        if (options.extended) {
+            const stats = await getExtendedStats(resolved.vault, resolved.agent);
+            print(options.json, stats, () => [
+                `Documents: ${stats.stats.documentCount}`,
+                `Links: ${stats.stats.linkCount}`,
+                `Resolved links: ${stats.stats.resolvedLinkCount}`,
+                `Broken links: ${stats.stats.brokenLinkCount}`,
+                `Orphans: ${stats.stats.orphanCount}`,
+                `Tags: ${stats.stats.tagCount}`,
+                `Total files: ${stats.storage.totalFileCount}`,
+                `Markdown files: ${stats.storage.markdownFileCount}`,
+                `Vault bytes: ${stats.storage.totalBytes}`,
+                `Latency index/search/context (ms): ${stats.observability.latenciesMs.index}/${stats.observability.latenciesMs.search}/${stats.observability.latenciesMs.context}`
+            ].join('\n'));
+            return;
+        }
         const stats = await getStats(resolved.vault, resolved.agent);
         print(options.json, stats, () => [
             `Documents: ${stats.documentCount}`,

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

@@ -1,11 +1,19 @@
 import { readFileSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, relative, resolve } from 'node:path';
 import { addNote } from '../../application/add-note.js';
+import { buildContextPackage } from '../../application/build-context.js';
+import { importLegacySqliteDatabase } from '../../application/import-legacy-sqlite.js';
 import { indexVault } from '../../application/index-vault.js';
+import { migrateVaultContent, planVaultMigration, previewVaultMigration, shouldMigrateDefaultVault } from '../../application/migrate-vault.js';
 import { startServer } from '../../application/start-server.js';
 import { startVaultWatcher } from '../../application/watch-vault.js';
-import { doctorVault } from '../../application/analyze-vault.js';
+import { doctorVault, getStats, validateVault } from '../../application/analyze-vault.js';
+import { defaultBrainlinkConfig, sanitizeSearchMode } from '../../infrastructure/config.js';
 import { loadBrainlinkConfig } from '../../infrastructure/config.js';
 import { assertVaultAllowed, ensureVault } from '../../infrastructure/file-system-vault.js';
+import { getBootstrapPolicy, getBootstrapSessionStatus, touchBootstrapSession } from '../../infrastructure/session-state.js';
+import { installAgentIntegration } from './agent-commands.js';
 import { parsePositiveInteger, print, resolveOptions } from '../runtime.js';
 const resolveAddContent = (options) => {
     if (options.content != null && options.content.trim().length > 0) {
@@ -20,12 +28,108 @@ export const registerWriteCommands = (program) => {
     program
         .command('init')
         .argument('[vault]', 'vault directory')
+        .option('--migrate-from <vault>', 'copy existing vault content into the initialized vault')
+        .option('--no-migrate-existing', 'skip automatic migration from the default Brainlink vault into an empty custom vault')
         .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.vault, config.allowedVaults));
-        print(options.json, { path }, () => `Initialized Brainlink vault at ${path}`);
+        const targetVault = assertVaultAllowed(vault ?? config.vault, config.allowedVaults);
+        const path = await ensureVault(targetVault);
+        const explicitSource = options.migrateFrom ? assertVaultAllowed(options.migrateFrom, config.allowedVaults) : undefined;
+        const shouldAutoMigrate = explicitSource === undefined &&
+            options.migrateExisting !== false &&
+            (await shouldMigrateDefaultVault(defaultBrainlinkConfig.vault, targetVault));
+        const migration = explicitSource || shouldAutoMigrate ? await migrateVaultContent(explicitSource ?? defaultBrainlinkConfig.vault, targetVault) : undefined;
+        const index = migration && migration.copied + migration.conflicted > 0 ? await indexVault(targetVault) : undefined;
+        print(options.json, { path, ...(migration ? { migration } : {}), ...(index ? { index } : {}) }, () => {
+            const migrated = migration
+                ? ` Migrated ${migration.copied} files, preserved ${migration.conflicted} conflicts and kept ${migration.unchanged} unchanged files.`
+                : '';
+            return `Initialized Brainlink vault at ${path}.${migrated}`;
+        });
+    });
+    program
+        .command('migrate-vault')
+        .option('--from <vault>', 'source vault path')
+        .option('--to <vault>', 'target vault path')
+        .option('--dry-run', 'preview migration without writing files')
+        .option('--report <path>', 'write detailed per-file migration report to JSON file')
+        .option('--no-index', 'skip reindexing target vault after migration')
+        .option('--json', 'print machine-readable JSON')
+        .description('copy markdown memory from one vault to another with conflict preservation')
+        .action(async (options) => {
+        const config = await loadBrainlinkConfig();
+        const sourceVault = assertVaultAllowed(options.from ?? config.vault, config.allowedVaults);
+        const targetVault = assertVaultAllowed(options.to ?? defaultBrainlinkConfig.vault, config.allowedVaults);
+        const sourceRoot = await ensureVault(sourceVault);
+        const targetRoot = await ensureVault(targetVault);
+        const preview = await previewVaultMigration(sourceVault, targetVault);
+        const actions = await planVaultMigration(sourceRoot, targetRoot);
+        const reportEntries = actions.map((action) => ({
+            kind: action.kind,
+            sourcePath: action.sourcePath,
+            sourceRelativePath: relative(sourceRoot, action.sourcePath),
+            targetPath: action.targetPath,
+            targetRelativePath: relative(targetRoot, action.targetPath)
+        }));
+        const writeReport = async () => {
+            if (!options.report) {
+                return null;
+            }
+            const reportPath = resolve(options.report);
+            await mkdir(dirname(reportPath), { recursive: true });
+            await writeFile(reportPath, `${JSON.stringify({ source: sourceVault, target: targetVault, summary: preview, entries: reportEntries }, null, 2)}\n`, 'utf8');
+            return reportPath;
+        };
+        if (options.dryRun) {
+            const reportPath = await writeReport();
+            print(options.json, { dryRun: true, ...preview, entries: reportEntries, ...(reportPath ? { reportPath } : {}) }, () => `Dry run migration ${preview.source} -> ${preview.target}: copy=${preview.copied}, conflicts=${preview.conflicted}, unchanged=${preview.unchanged}${reportPath ? ` report=${reportPath}` : ''}`);
+            return;
+        }
+        const migration = await migrateVaultContent(sourceVault, targetVault);
+        const shouldIndex = options.index !== false && migration.copied + migration.conflicted > 0;
+        const index = shouldIndex ? await indexVault(targetVault) : undefined;
+        const reportPath = await writeReport();
+        print(options.json, { dryRun: false, ...migration, entries: reportEntries, ...(index ? { index } : {}), ...(reportPath ? { reportPath } : {}) }, () => {
+            const summary = `Migrated ${migration.copied} files, preserved ${migration.conflicted} conflicts and kept ${migration.unchanged} unchanged files.`;
+            const indexMessage = index
+                ? ` Indexed ${index.documentCount} documents, ${index.chunkCount} chunks and ${index.linkCount} links.`
+                : '';
+            const reportMessage = reportPath ? ` Report written to ${reportPath}.` : '';
+            return `${summary}${indexMessage}${reportMessage}`;
+        });
+    });
+    program
+        .command('db-import')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('--db <path>', 'legacy SQLite database path (default: <vault>/.brainlink/brainlink.db)')
+        .option('--table <name>', 'legacy table name override')
+        .option('-a, --agent <agent>', 'force imported notes into a target agent namespace')
+        .option('-l, --limit <limit>', 'maximum number of rows to import')
+        .option('--dry-run', 'preview import without writing Markdown files')
+        .option('--no-index', 'skip reindexing after import')
+        .option('--json', 'print machine-readable JSON')
+        .description('import legacy SQLite memory into Markdown vault and current index model')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const result = await importLegacySqliteDatabase(resolved.vault, {
+            dbPath: options.db,
+            table: options.table,
+            agentOverride: options.agent ? resolved.agent : undefined,
+            limit: options.limit ? parsePositiveInteger(options.limit, 100_000) : undefined,
+            dryRun: Boolean(options.dryRun)
+        });
+        const shouldIndex = options.index !== false && !result.dryRun && result.imported > 0;
+        const index = shouldIndex ? await indexVault(resolved.vault) : undefined;
+        print(options.json, { ...result, ...(index ? { index } : {}) }, () => {
+            const summary = `Imported ${result.imported}/${result.rowsRead} rows from ${result.table} (skipped ${result.skipped}).`;
+            const indexMessage = index
+                ? ` Indexed ${index.documentCount} documents, ${index.chunkCount} chunks and ${index.linkCount} links.`
+                : '';
+            const dryRunMessage = result.dryRun ? ' Dry run only; no files were written.' : '';
+            return `${summary}${indexMessage}${dryRunMessage}`;
+        });
     });
     program
         .command('add')
@@ -66,7 +170,13 @@ export const registerWriteCommands = (program) => {
         .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'));
+        print(options.json, report, () => {
+            const checks = report.checks.map((check) => `${check.ok ? 'OK' : 'FAIL'} ${check.name}: ${check.message}`).join('\n');
+            const recommendations = report.recommendations && report.recommendations.length > 0
+                ? `\n\nRecommended next steps:\n${report.recommendations.map((step) => `- ${step}`).join('\n')}`
+                : '';
+            return `${checks}${recommendations}`;
+        });
         process.exitCode = report.ok ? 0 : 1;
     });
     program
@@ -117,4 +227,95 @@ export const registerWriteCommands = (program) => {
         });
         print(options.json, { url: server.url, watch: Boolean(options.watch), readonly: true }, () => `Brainlink graph server running at ${server.url}`);
     });
+    program
+        .command('quickstart')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('--query <query>', 'optional task query to return immediate grounded context')
+        .option('--mode <mode>', 'search mode for context (fts|semantic|hybrid)')
+        .option('--limit <limit>', 'maximum context sections')
+        .option('--tokens <tokens>', 'maximum context token budget')
+        .option('--no-install-agent', 'skip agent MCP/plugin installation and upgrade automation')
+        .option('--mcp-only', 'when installing agent integration, only configure MCP section')
+        .option('--plugin-path <path>', 'custom source path for Brainlink plugin files')
+        .option('--allowed-vaults <paths>', 'comma separated vault allowlist to inject in MCP env')
+        .option('--brainlink-home <path>', 'BRAINLINK_HOME value to inject in MCP env')
+        .option('--json', 'print machine-readable JSON')
+        .description('run plug-and-play setup for vault, MCP integration and bootstrap readiness')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const limit = parsePositiveInteger(options.limit ?? String(resolved.defaults.defaultSearchLimit), resolved.defaults.defaultSearchLimit);
+        const tokens = parsePositiveInteger(options.tokens ?? String(resolved.defaults.defaultContextTokens), resolved.defaults.defaultContextTokens);
+        const mode = sanitizeSearchMode(options.mode, resolved.defaults.defaultSearchMode);
+        const index = await indexVault(resolved.vault);
+        const stats = await getStats(resolved.vault, resolved.agent);
+        const validation = await validateVault(resolved.vault, resolved.agent);
+        const doctor = await doctorVault(resolved.vault);
+        const session = await touchBootstrapSession(resolved.vault, resolved.agent);
+        const policy = await getBootstrapPolicy();
+        const bootstrapStatus = await getBootstrapSessionStatus(resolved.vault, resolved.agent);
+        const context = options.query
+            ? await buildContextPackage(resolved.vault, options.query, limit, tokens, resolved.agent, mode)
+            : null;
+        const agentIntegration = options.installAgent === false
+            ? null
+            : await installAgentIntegration({
+                mcpOnly: options.mcpOnly,
+                pluginPath: options.pluginPath,
+                allowedVaults: options.allowedVaults,
+                brainlinkHome: options.brainlinkHome,
+                selfTest: true
+            });
+        const nextActions = stats.documentCount === 0
+            ? [
+                {
+                    priority: 'required',
+                    command: `blink add "Architecture" --vault "${resolved.vault}" --content "Durable memory with [[Links]] and #tags."`,
+                    reason: 'Seed your vault with at least one durable Markdown note.'
+                },
+                {
+                    priority: 'required',
+                    command: `blink index --vault "${resolved.vault}"`,
+                    reason: 'Rebuild index after adding notes so retrieval can find new memory.'
+                }
+            ]
+            : options.query
+                ? [
+                    {
+                        priority: 'recommended',
+                        command: `blink add "Task Update" --vault "${resolved.vault}" --agent "${resolved.agent ?? 'shared'}" --content "<durable memory>"`,
+                        reason: 'Persist important findings as Markdown notes after using the returned context.'
+                    }
+                ]
+                : [
+                    {
+                        priority: 'recommended',
+                        command: `blink context "<task>" --vault "${resolved.vault}" --agent "${resolved.agent ?? 'shared'}" --mode ${mode}`,
+                        reason: 'Retrieve grounded context for each task before responding.'
+                    }
+                ];
+        print(options.json, {
+            vault: resolved.vault,
+            agent: resolved.agent ?? 'shared',
+            mode,
+            index,
+            stats,
+            validation,
+            doctor,
+            policy,
+            bootstrapStatus,
+            session,
+            context,
+            agentIntegration,
+            nextActions
+        }, () => [
+            `quickstart vault=${resolved.vault}`,
+            `agent=${resolved.agent ?? 'shared'}`,
+            `documents=${stats.documentCount}`,
+            `links=${stats.linkCount}`,
+            `bootstrapReady=${bootstrapStatus.ready}`,
+            ...(agentIntegration?.selfTest ? [`agentIntegrationSelfTest=${agentIntegration.selfTest.ok}`] : []),
+            ...(nextActions.length > 0 ? ['Next actions:', ...nextActions.map((step) => `- ${step.command}`)] : [])
+        ].join('\n'));
+    });
 };

package/dist/cli/main.js

@@ -3,6 +3,8 @@ import { Command } from 'commander';
 import { readFileSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { registerAgentCommands } from './commands/agent-commands.js';
+import { registerConfigCommands } from './commands/config-commands.js';
 import { registerReadCommands } from './commands/read-commands.js';
 import { registerWriteCommands } from './commands/write-commands.js';
 const readPackageVersion = () => {
@@ -21,6 +23,8 @@ program
     .version(readPackageVersion());
 registerWriteCommands(program);
 registerReadCommands(program);
+registerConfigCommands(program);
+registerAgentCommands(program);
 program.parseAsync().catch((error) => {
     const message = error instanceof Error ? error.message : String(error);
     console.error(message);

package/dist/cli/runtime.js

@@ -1,4 +1,4 @@
-import { loadBrainlinkConfig } from '../infrastructure/config.js';
+import { loadBrainlinkConfig, resolveAgentRuntimeDefaults } from '../infrastructure/config.js';
 import { assertVaultAllowed } from '../infrastructure/file-system-vault.js';
 export const parsePositiveInteger = (value, fallback) => {
     const parsed = Number.parseInt(value, 10);
@@ -8,10 +8,13 @@ export const resolveOptions = async (options) => {
     const config = await loadBrainlinkConfig();
     const vault = options.vault ?? config.vault;
     const allowedVault = assertVaultAllowed(vault, config.allowedVaults);
+    const agent = options.agent ?? config.defaultAgent;
+    const defaults = resolveAgentRuntimeDefaults(config, agent);
     return {
         config,
         vault: allowedVault,
-        agent: options.agent ?? config.defaultAgent
+        agent,
+        defaults
     };
 };
 export const print = (json, value, human) => {

package/dist/domain/context.js

@@ -1,13 +1,50 @@
+import { middleOutIndices } from './middle-out.js';
+const maxSectionsPerDocument = 3;
+const byScore = (left, right) => right.score - left.score || left.title.localeCompare(right.title);
+const byOrdinal = (left, right) => (left.chunkOrdinal ?? Number.MAX_SAFE_INTEGER) - (right.chunkOrdinal ?? Number.MAX_SAFE_INTEGER);
+const middleOutDocumentResults = (results) => {
+    if (results.length <= 1) {
+        return results;
+    }
+    const sortedByOrdinal = [...results].sort(byOrdinal);
+    const pivotChunkId = [...results].sort(byScore)[0]?.chunkId;
+    const pivotIndex = sortedByOrdinal.findIndex((result) => result.chunkId === pivotChunkId);
+    if (pivotIndex < 0) {
+        return [...results].sort(byScore);
+    }
+    return middleOutIndices(sortedByOrdinal.length, pivotIndex).map((index) => sortedByOrdinal[index]);
+};
 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;
+    const grouped = results.reduce((state, result) => {
+        const current = state.get(result.documentId) ?? [];
+        state.set(result.documentId, [...current, result]);
+        return state;
+    }, new Map());
+    const documentOrder = Array.from(results.reduce((state, result) => {
+        if (!state.has(result.documentId)) {
+            state.set(result.documentId, result.score);
         }
-        return {
-            usedTokens: state.usedTokens + tokenCost,
-            sections: [
-                ...state.sections,
+        return state;
+    }, new Map()).entries())
+        .sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]))
+        .map(([documentId]) => documentId);
+    const selected = documentOrder.reduce((state, documentId) => {
+        const ordered = middleOutDocumentResults(grouped.get(documentId) ?? []);
+        let usedTokens = state.usedTokens;
+        let sections = state.sections;
+        let seenChunks = state.seenChunks;
+        for (let index = 0; index < ordered.length && index < maxSectionsPerDocument; index += 1) {
+            const result = ordered[index];
+            if (seenChunks.has(result.chunkId)) {
+                continue;
+            }
+            const tokenCost = Math.ceil(result.content.length / 4);
+            if (usedTokens + tokenCost > maxTokens) {
+                break;
+            }
+            usedTokens += tokenCost;
+            sections = [
+                ...sections,
                 {
                     title: result.title,
                     path: result.path,
@@ -16,13 +53,18 @@ export const selectContextSections = (results, maxTokens) => {
                     searchMode: result.searchMode,
                     tags: result.tags
                 }
-            ],
-            seenDocuments: new Set([...state.seenDocuments, result.documentId])
+            ];
+            seenChunks = new Set([...seenChunks, result.chunkId]);
+        }
+        return {
+            usedTokens,
+            sections,
+            seenChunks
         };
     }, {
         usedTokens: 0,
         sections: [],
-        seenDocuments: new Set()
+        seenChunks: new Set()
     });
     return selected.sections;
 };

package/dist/domain/embeddings.js

@@ -58,7 +58,8 @@ 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 getAliasesForToken = (token) => Object.hasOwn(aliases, token) ? aliases[token] ?? [] : [];
+const expandTokens = (tokens) => tokens.flatMap((token) => [token, ...getAliasesForToken(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);

package/dist/domain/graph-layout.js

@@ -45,20 +45,17 @@ const countDegrees = (edges) => edges.reduce((degrees, edge) => {
         ? incrementDegreeBy(incrementDegreeBy(degrees, edge.source, weight), edge.target, weight)
         : incrementDegreeBy(degrees, edge.source, weight);
 }, new Map());
-const uniqueIds = (ids) => Array.from(new Set(ids));
 const createAdjacency = (nodes, edges) => {
     const nodeIds = new Set(nodes.map((node) => node.id));
-    const emptyAdjacency = new Map(nodes.map((node) => [node.id, []]));
-    return edges.reduce((adjacency, edge) => {
+    const adjacency = new Map(nodes.map((node) => [node.id, new Set()]));
+    edges.forEach((edge) => {
         if (!edge.target || !nodeIds.has(edge.source) || !nodeIds.has(edge.target)) {
-            return adjacency;
+            return;
         }
-        return new Map([
-            ...adjacency,
-            [edge.source, uniqueIds([...(adjacency.get(edge.source) ?? []), edge.target])],
-            [edge.target, uniqueIds([...(adjacency.get(edge.target) ?? []), edge.source])]
-        ]);
-    }, emptyAdjacency);
+        adjacency.get(edge.source)?.add(edge.target);
+        adjacency.get(edge.target)?.add(edge.source);
+    });
+    return new Map(Array.from(adjacency.entries(), ([id, neighbors]) => [id, Array.from(neighbors)]));
 };
 const byTitle = (left, right) => left.title.localeCompare(right.title);
 const byDegreeThenTitle = (degrees) => (left, right) => {
@@ -117,10 +114,19 @@ const assignSegments = (nodes, edges, degrees) => {
     }
     return new Map(nodes.map((node) => [node.id, assignments.get(node.id) ?? groupLabel(groupKey(node))]));
 };
-const groupNodesBySegment = (nodes, segments) => nodes.reduce((groups, node) => {
-    const segment = segments.get(node.id) ?? groupLabel(groupKey(node));
-    return new Map([...groups, [segment, [...(groups.get(segment) ?? []), node]]]);
-}, new Map());
+const groupNodesBySegment = (nodes, segments) => {
+    const groups = new Map();
+    nodes.forEach((node) => {
+        const segment = segments.get(node.id) ?? groupLabel(groupKey(node));
+        const bucket = groups.get(segment);
+        if (bucket) {
+            bucket.push(node);
+            return;
+        }
+        groups.set(segment, [node]);
+    });
+    return new Map(groups);
+};
 const segmentAngle = (segment, index, count) => segmentAngles[segment] ?? (Math.PI * 2 * index) / Math.max(count, 1) - Math.PI / 2;
 const createSegmentNodes = (segments, degrees, segmentCount) => ([segment, nodes], segmentIndex) => {
     const sortedNodes = [...nodes].sort(byDegreeThenTitle(degrees));

package/dist/domain/markdown.js

@@ -77,11 +77,13 @@ export const extractWikiLinkReferences = (content) => visibleMarkdownLines(conte
     }));
 });
 const priorityFromWeight = (weight) => weight >= 8 ? 'critical' : weight >= 4 ? 'high' : 'normal';
+const normalizeAccumulatedWeight = (weight) => Math.max(1, Math.min(12, weight));
 export const extractWikiLinkWeights = (content) => {
     const weights = extractWikiLinkReferences(content).reduce((state, reference) => {
         const titleKey = reference.title.toLowerCase();
         const current = state.get(titleKey);
-        const weight = (current?.weight ?? 0) + reference.weight;
+        const rawWeight = (current?.weight ?? 0) + reference.weight;
+        const weight = normalizeAccumulatedWeight(rawWeight);
         const explicitPriority = reference.priority
             ? maxPriority(current?.priority ?? reference.priority, reference.priority)
             : current?.priority;
@@ -116,10 +118,38 @@ const normalizeChunkContent = (content) => content
     .join('\n')
     .replace(/\n{3,}/g, '\n\n')
     .trim();
+const splitLongParagraph = (paragraph, maxCharacters) => {
+    if (paragraph.length <= maxCharacters) {
+        return [paragraph];
+    }
+    const sentences = paragraph
+        .split(/(?<=[.!?])\s+/)
+        .map((sentence) => sentence.trim())
+        .filter(Boolean);
+    if (sentences.length <= 1) {
+        const chunks = [];
+        for (let index = 0; index < paragraph.length; index += maxCharacters) {
+            chunks.push(paragraph.slice(index, index + maxCharacters).trim());
+        }
+        return chunks.filter(Boolean);
+    }
+    return sentences.reduce((state, sentence) => {
+        const last = state.at(-1);
+        if (!last) {
+            return [sentence];
+        }
+        const merged = `${last} ${sentence}`;
+        if (merged.length <= maxCharacters) {
+            return [...state.slice(0, -1), merged];
+        }
+        return [...state, sentence];
+    }, []);
+};
 export const splitIntoChunks = (documentId, content, maxCharacters = 1200) => {
     const paragraphs = normalizeChunkContent(stripFrontmatter(content))
         .split(/\n{2,}/)
-        .filter(Boolean);
+        .filter(Boolean)
+        .flatMap((paragraph) => splitLongParagraph(paragraph, maxCharacters));
     const chunks = paragraphs.reduce((state, paragraph) => {
         const lastChunk = state.at(-1);
         if (!lastChunk) {
@@ -162,13 +192,15 @@ export const parseMarkdownDocument = (input) => {
 export const createIndexedDocument = (document, titleToDocumentId, maxChunkCharacters = 1200) => {
     const chunks = splitIntoChunks(document.id, document.content, maxChunkCharacters);
     const linkWeights = new Map(extractWikiLinkWeights(document.content).map((link) => [link.title.toLowerCase(), link]));
-    const links = document.links.map((toTitle) => ({
+    const links = document.links
+        .map((toTitle) => ({
         fromDocumentId: document.id,
         toTitle,
         toDocumentId: titleToDocumentId.get(toTitle.toLowerCase()) ?? null,
         weight: linkWeights.get(toTitle.toLowerCase())?.weight ?? 1,
         priority: linkWeights.get(toTitle.toLowerCase())?.priority ?? 'normal'
-    }));
+    }))
+        .filter((link) => link.toDocumentId !== document.id);
     return {
         document,
         chunks,

package/dist/domain/middle-out.js

@@ -0,0 +1,18 @@
+export const middleOutIndices = (size, pivotIndex) => {
+    if (!Number.isFinite(size) || size <= 0) {
+        return [];
+    }
+    const clampedPivot = Math.max(0, Math.min(Math.floor(pivotIndex), size - 1));
+    const indices = [clampedPivot];
+    for (let offset = 1; indices.length < size; offset += 1) {
+        const left = clampedPivot - offset;
+        const right = clampedPivot + offset;
+        if (left >= 0) {
+            indices.push(left);
+        }
+        if (right < size) {
+            indices.push(right);
+        }
+    }
+    return indices;
+};