@andespindola/brainlink 0.1.0-beta.42 → 0.1.0-beta.43

package/AGENTS.md

@@ -83,6 +83,8 @@ Use watch mode while editing notes:
 ```bash
 npm run dev -- server --vault ./vault --watch
 npm run dev -- watch --vault ./vault
+npm run dev -- bench --vault ./vault
+npm run dev -- bench --vault ./vault --watch
 ```
 
 Start MCP over stdio:

package/CHANGELOG.md

@@ -38,6 +38,7 @@
 - Improved Linux browser fallback launch stability by auto-applying Chromium compatibility flags (`--ozone-platform=x11`, `--disable-gpu`, `--disable-features=Vulkan,VaapiVideoDecoder`, `--disable-background-networking`) for app-window/browser modes.
 - Improved massive-graph UI responsiveness with stricter render budgets, adaptive heavy-graph frame throttling, reduced interaction hit-test frequency, and URL-first agent selection on initial graph load.
 - Improved 50k+ graph LOD behavior so zoomed-out views render lightweight cluster overviews and progressively reveal nodes/edges only as zoom increases.
+- Added `blink bench` with realtime index phase telemetry and per-run compressed-pack analysis (input/output bytes, ratio, saved space, rebuild reason and duration), including continuous watch mode.
 
 ## 0.1.0-beta.3
 

package/README.md

@@ -760,6 +760,25 @@ blink index --vault ./vault
 
 Rebuilds the local index from Markdown files.
 
+### `bench`
+
+```bash
+blink bench --vault ./vault
+blink bench --vault ./vault --watch
+blink bench --vault ./vault --watch --debounce 500
+blink bench --vault ./vault --json
+```
+
+Runs indexing with realtime phase telemetry (`start`, `scan`, `parse`, `embed`, `persist`, `packs`, `complete`) and prints a benchmark summary at the end of each run.
+
+Summary includes compression behavior for `.blpk` packs when rebuild happens:
+- pack rebuild reason
+- pack count and pack build duration
+- uncompressed input bytes vs compressed output bytes
+- saved percentage
+
+Use `--watch` to keep benchmarking incremental reindex runs after Markdown changes (local filesystem vaults only).
+
 ### `agents`
 
 ```bash

package/dist/application/index-vault.js

@@ -97,12 +97,33 @@ const readChangedDocuments = async (absoluteVaultPath, changedSummaries) => {
     return new Map(parsed.map((document) => [document.path, document]));
 };
 export const indexVault = async (vaultPath) => {
+    return indexVaultWithOptions(vaultPath, {});
+};
+export const indexVaultWithOptions = async (vaultPath, options) => {
+    const startedAt = process.hrtime.bigint();
+    const elapsedMs = () => Number(process.hrtime.bigint() - startedAt) / 1_000_000;
+    const emit = (phase, status, message, details) => {
+        options.onProgress?.({
+            phase,
+            status,
+            message,
+            elapsedMs: elapsedMs(),
+            timestamp: new Date().toISOString(),
+            details
+        });
+    };
+    emit('start', 'start', 'Indexing started');
     const absoluteVaultPath = await ensureVault(vaultPath);
     const config = await loadBrainlinkConfig();
+    emit('scan', 'start', 'Scanning markdown files');
     const [summaries, previousState] = await Promise.all([
         readMarkdownFileSummaries(absoluteVaultPath),
         readIndexState(absoluteVaultPath)
     ]);
+    emit('scan', 'finish', 'Scan complete', {
+        markdownFiles: summaries.length,
+        hasPreviousState: previousState != null
+    });
     const index = openFileIndex(absoluteVaultPath);
     try {
         const existingIndexedDocuments = await index.getIndexedDocuments();
@@ -133,10 +154,28 @@ export const indexVault = async (vaultPath) => {
             !hasDeletes &&
             existingIndexedDocuments.length === summaries.length &&
             previousState != null) {
-            return toIndexResult(existingIndexedDocuments);
+            const result = {
+                ...toIndexResult(existingIndexedDocuments),
+                elapsedMs: elapsedMs(),
+                changedDocumentCount: 0,
+                packs: {
+                    rebuilt: false,
+                    reason: 'No changes detected'
+                }
+            };
+            emit('complete', 'skip', 'Index skipped: no changes detected', {
+                elapsedMs: result.elapsedMs
+            });
+            return result;
         }
         const changedSummaries = summaries.filter((summary) => changedPaths.has(summary.relativePath));
+        emit('parse', 'start', 'Parsing changed markdown files', {
+            changedFiles: changedSummaries.length
+        });
         const changedDocumentsByPath = await readChangedDocuments(absoluteVaultPath, changedSummaries);
+        emit('parse', 'finish', 'Parse complete', {
+            changedDocuments: changedDocumentsByPath.size
+        });
         const documents = summaries.flatMap((summary) => {
             const changed = changedDocumentsByPath.get(summary.relativePath);
             if (changed) {
@@ -146,9 +185,15 @@ export const indexVault = async (vaultPath) => {
             return existing ? [existing.document] : [];
         });
         const titleMaps = createTitleMaps(documents);
+        emit('embed', 'start', 'Embedding changed chunks', {
+            changedDocuments: changedDocumentsByPath.size
+        });
         const changedIndexedDocuments = changedDocumentsByPath.size > 0
             ? await embedIndexedDocuments(Array.from(changedDocumentsByPath.values()).map((document) => createIndexedDocument(document, createScopedTitleResolver(document, titleMaps), config.chunkSize)), config.embeddingProvider)
             : [];
+        emit('embed', changedDocumentsByPath.size > 0 ? 'finish' : 'skip', changedDocumentsByPath.size > 0 ? 'Embedding complete' : 'Embedding skipped', {
+            changedIndexedDocuments: changedIndexedDocuments.length
+        });
         const changedIndexedByPath = new Map(changedIndexedDocuments.map((document) => [document.document.path, document]));
         const needsRelink = settingsChanged || hasDeletes || changedPaths.size > 0;
         const indexedDocuments = documents.map((document) => {
@@ -162,8 +207,12 @@ export const indexVault = async (vaultPath) => {
             }
             return needsRelink ? relinkIndexedDocument(existing, titleMaps) : existing;
         });
+        emit('persist', 'start', 'Persisting index');
         await index.reset();
         await index.saveDocuments(indexedDocuments);
+        emit('persist', 'finish', 'Index persisted', {
+            indexedDocuments: indexedDocuments.length
+        });
         const existingPackManifest = await hasPackManifest(absoluteVaultPath);
         const changedCount = changedPaths.size;
         const documentCount = Math.max(indexedDocuments.length, 1);
@@ -176,21 +225,78 @@ export const indexVault = async (vaultPath) => {
             changedCount >= 400 ||
             changeRatio >= 0.04 ||
             pendingPackChanges >= 1200;
+        let packResult;
+        const packReason = !existingPackManifest
+            ? 'Missing pack manifest'
+            : settingsChanged
+                ? 'Index settings changed'
+                : hasDeletes
+                    ? 'Document deletions detected'
+                    : changedCount >= 400
+                        ? 'Changed file count threshold reached'
+                        : changeRatio >= 0.04
+                            ? 'Change ratio threshold reached'
+                            : pendingPackChanges >= 1200
+                                ? 'Pending pack changes threshold reached'
+                                : 'Pack rebuild skipped';
         if (shouldRebuildPacks) {
+            emit('packs', 'start', 'Rebuilding compressed search packs', {
+                reason: packReason
+            });
             try {
-                await buildSearchPacks(absoluteVaultPath, indexedDocuments);
+                packResult = await buildSearchPacks(absoluteVaultPath, indexedDocuments);
+                emit('packs', 'finish', 'Compressed packs rebuilt', {
+                    reason: packReason,
+                    packCount: packResult.packCount,
+                    recordCount: packResult.recordCount,
+                    durationMs: packResult.durationMs,
+                    compressionRatio: packResult.compression.ratio
+                });
             }
             catch {
                 // Pack generation is best-effort. The JSON index remains the primary path.
+                emit('packs', 'skip', 'Pack rebuild failed; continuing with JSON index', {
+                    reason: packReason
+                });
             }
         }
+        else {
+            emit('packs', 'skip', 'Pack rebuild not required', {
+                reason: packReason
+            });
+        }
+        const packsRebuilt = packResult != null;
+        const packResultReason = shouldRebuildPacks && !packsRebuilt ? `${packReason} (failed)` : packReason;
         await writeIndexState(absoluteVaultPath, {
             chunkSize: config.chunkSize,
             embeddingProvider: config.embeddingProvider,
             files: currentSnapshot,
-            pendingPackChanges: shouldRebuildPacks ? 0 : pendingPackChanges
+            pendingPackChanges: packsRebuilt ? 0 : pendingPackChanges
+        });
+        const result = {
+            ...toIndexResult(indexedDocuments),
+            elapsedMs: elapsedMs(),
+            changedDocumentCount: changedDocumentsByPath.size,
+            packs: {
+                rebuilt: packsRebuilt,
+                reason: packResultReason,
+                ...(packResult
+                    ? {
+                        packCount: packResult.packCount,
+                        recordCount: packResult.recordCount,
+                        durationMs: packResult.durationMs,
+                        compression: packResult.compression
+                    }
+                    : {})
+            }
+        };
+        emit('complete', 'finish', 'Indexing complete', {
+            documentCount: result.documentCount,
+            chunkCount: result.chunkCount,
+            linkCount: result.linkCount,
+            elapsedMs: result.elapsedMs
         });
-        return toIndexResult(indexedDocuments);
+        return result;
     }
     finally {
         index.close();

package/dist/application/watch-vault.js

@@ -1,5 +1,5 @@
 import { watch } from 'node:fs';
-import { indexVault } from './index-vault.js';
+import { indexVaultWithOptions } from './index-vault.js';
 import { isBucketVaultPath, resolveVaultPath } from '../infrastructure/file-system-vault.js';
 const shouldIgnore = (filename) => {
     if (!filename) {
@@ -14,6 +14,27 @@ export const startVaultWatcher = (input) => {
     const absoluteVaultPath = resolveVaultPath(input.vaultPath);
     const debounceMs = input.debounceMs ?? 350;
     let timeout = null;
+    let running = false;
+    let pending = false;
+    const runIndex = () => {
+        if (running) {
+            pending = true;
+            return;
+        }
+        running = true;
+        indexVaultWithOptions(absoluteVaultPath, {
+            onProgress: input.onProgress
+        })
+            .then(input.onIndex)
+            .catch(input.onError)
+            .finally(() => {
+            running = false;
+            if (pending) {
+                pending = false;
+                runIndex();
+            }
+        });
+    };
     const schedule = (filename) => {
         if (shouldIgnore(filename)) {
             return;
@@ -22,7 +43,7 @@ export const startVaultWatcher = (input) => {
             clearTimeout(timeout);
         }
         timeout = setTimeout(() => {
-            indexVault(absoluteVaultPath).then(input.onIndex).catch(input.onError);
+            runIndex();
         }, debounceMs);
     };
     const watcher = watch(absoluteVaultPath, { recursive: true }, (_eventType, filename) => {

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

@@ -7,7 +7,7 @@ import { addNoteWithMetadata } from '../../application/add-note.js';
 import { buildContextPackage } from '../../application/build-context.js';
 import { resolveDuplicateNotes, scanDuplicateNotes } from '../../application/dedupe-notes.js';
 import { importLegacySqliteDatabase } from '../../application/import-legacy-sqlite.js';
-import { indexVault } from '../../application/index-vault.js';
+import { indexVault, indexVaultWithOptions } 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';
@@ -37,6 +37,52 @@ const parseScore = (value, fallback) => {
     }
     return parsed;
 };
+const formatBytes = (bytes) => {
+    if (!Number.isFinite(bytes) || bytes == null) {
+        return 'n/a';
+    }
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ['KB', 'MB', 'GB', 'TB'];
+    let value = bytes / 1024;
+    let unitIndex = 0;
+    while (value >= 1024 && unitIndex < units.length - 1) {
+        value /= 1024;
+        unitIndex += 1;
+    }
+    return `${value.toFixed(value >= 10 ? 1 : 2)} ${units[unitIndex]}`;
+};
+const formatMs = (value) => Number.isFinite(value) && value != null ? `${value.toFixed(value >= 100 ? 0 : 1)}ms` : 'n/a';
+const benchEventLabel = (event) => `${event.phase}:${event.status}`;
+const printBenchRealtimeEvent = (json, event) => {
+    print(json, {
+        event: 'bench-progress',
+        ...event
+    }, () => `[bench] ${benchEventLabel(event)} ${event.message} (${formatMs(event.elapsedMs)})`);
+};
+const printBenchSummary = (json, trigger, vault, result) => {
+    print(json, {
+        event: 'bench-result',
+        trigger,
+        vault,
+        result
+    }, () => {
+        const packs = result.packs;
+        const compression = packs?.compression;
+        const savedPercent = compression && compression.inputBytes > 0
+            ? `${((1 - compression.ratio) * 100).toFixed(1)}%`
+            : 'n/a';
+        return [
+            `[bench] trigger=${trigger}`,
+            `documents=${result.documentCount} chunks=${result.chunkCount} links=${result.linkCount}`,
+            `changedDocuments=${result.changedDocumentCount ?? 0} totalElapsed=${formatMs(result.elapsedMs)}`,
+            `packsRebuilt=${packs?.rebuilt ? 'yes' : 'no'} reason=${packs?.reason ?? 'n/a'}`,
+            packs?.rebuilt
+                ? `packCount=${packs.packCount ?? 0} packDuration=${formatMs(packs.durationMs)} input=${formatBytes(compression?.inputBytes)} output=${formatBytes(compression?.outputBytes)} saved=${savedPercent}`
+                : 'packCompression=n/a'
+        ].join('\n');
+    });
+};
 const spawnDetached = (command, args, envOverrides) => {
     try {
         const child = spawn(command, args, {
@@ -634,6 +680,58 @@ export const registerWriteCommands = (program) => {
         const result = await indexVault(resolved.vault);
         print(options.json, result, () => `Indexed ${result.documentCount} documents, ${result.chunkCount} chunks and ${result.linkCount} links`);
     });
+    program
+        .command('bench')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-w, --watch', 'watch markdown changes and re-run benchmark in realtime')
+        .option('--debounce <ms>', 'watch debounce in milliseconds', '350')
+        .option('--json', 'print machine-readable JSON events')
+        .description('benchmark indexing in realtime, including compressed pack behavior')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const emitProgress = (event) => {
+            printBenchRealtimeEvent(options.json, event);
+        };
+        const printBenchError = (error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            print(options.json, { event: 'bench-error', message }, () => `[bench] error ${message}`);
+        };
+        const runAndPrint = async (trigger) => {
+            const result = await indexVaultWithOptions(resolved.vault, {
+                onProgress: emitProgress
+            });
+            printBenchSummary(options.json, trigger, resolved.vault, result);
+            return result;
+        };
+        if (!options.watch) {
+            await runAndPrint('manual');
+            return;
+        }
+        const debounceMs = parsePositiveInteger(options.debounce ?? '350', 350);
+        await runAndPrint('manual');
+        print(options.json, {
+            event: 'bench-watching',
+            vault: resolved.vault,
+            debounceMs
+        }, () => `[bench] watching ${resolved.vault} (debounce=${debounceMs}ms)`);
+        const watcher = startVaultWatcher({
+            vaultPath: resolved.vault,
+            debounceMs,
+            onProgress: emitProgress,
+            onIndex: (result) => {
+                printBenchSummary(options.json, 'watch', resolved.vault, result);
+            },
+            onError: printBenchError
+        });
+        await new Promise((resolveSignal) => {
+            const shutdown = () => {
+                watcher.close();
+                resolveSignal();
+            };
+            process.once('SIGINT', shutdown);
+            process.once('SIGTERM', shutdown);
+        });
+    });
     program
         .command('doctor')
         .option('-v, --vault <vault>', 'vault directory')

package/dist/infrastructure/search-packs.js

@@ -221,6 +221,7 @@ const sortedPackFiles = async (vaultPath) => {
     }
 };
 const writeRowsAsPrivatePacks = async (vaultPath, rows, clearExisting) => {
+    const startedAt = process.hrtime.bigint();
     const directory = toPackDirectory(vaultPath);
     await mkdir(directory, { recursive: true });
     if (clearExisting) {
@@ -231,6 +232,8 @@ const writeRowsAsPrivatePacks = async (vaultPath, rows, clearExisting) => {
     }
     const chunks = chunkRows(rows, rowChunkSize);
     const packIndex = [];
+    let inputBytes = 0;
+    let outputBytes = 0;
     for (let index = 0; index < chunks.length; index += 1) {
         const chunk = chunks[index];
         const fileName = `pack-${String(index + 1).padStart(4, '0')}.blpk`;
@@ -238,6 +241,8 @@ const writeRowsAsPrivatePacks = async (vaultPath, rows, clearExisting) => {
         const compressed = await encodePrivatePack(vaultPath, Buffer.from(serialized, 'utf8'));
         const tokenBloomB64 = bloomToBase64(bloomFromRows(chunk));
         await writeFile(join(directory, fileName), compressed);
+        inputBytes += Buffer.byteLength(serialized, 'utf8');
+        outputBytes += compressed.byteLength;
         packIndex.push({
             fileName,
             recordCount: chunk.length,
@@ -253,9 +258,19 @@ const writeRowsAsPrivatePacks = async (vaultPath, rows, clearExisting) => {
         format: 'private-v2',
         packIndex
     });
+    const durationMs = Number(process.hrtime.bigint() - startedAt) / 1_000_000;
+    const safeInput = Math.max(inputBytes, 1);
+    const savedBytes = Math.max(inputBytes - outputBytes, 0);
     return {
         packCount: chunks.length,
-        recordCount: rows.length
+        recordCount: rows.length,
+        compression: {
+            inputBytes,
+            outputBytes,
+            ratio: outputBytes / safeInput,
+            savedBytes
+        },
+        durationMs
     };
 };
 const selectCandidatePackFiles = async (vaultPath, tokens, agentId) => {

package/docs/AGENT_USAGE.md

@@ -477,6 +477,24 @@ This scans Markdown files and rebuilds:
 - links
 - full-text search records
 
+### Benchmark Indexing Realtime
+
+```bash
+blink bench --vault ./vault
+blink bench --vault ./vault --watch
+blink bench --vault ./vault --watch --debounce 500
+blink bench --vault ./vault --json
+```
+
+`bench` runs indexing with realtime phase events and prints a run summary with:
+
+- indexed totals (documents, chunks, links)
+- elapsed time and changed document count
+- pack rebuild status and reason
+- pack compression metrics (`inputBytes`, `outputBytes`, ratio/saved percentage)
+
+Use `--watch` for continuous benchmark runs while editing notes. Watch mode is supported only for local filesystem vaults.
+
 ### Search Knowledge
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/brainlink",
-  "version": "0.1.0-beta.42",
+  "version": "0.1.0-beta.43",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",