@andespindola/brainlink 0.1.0-beta.40 → 0.1.0-beta.41

package/CHANGELOG.md

@@ -31,6 +31,8 @@
 - Improved non-mac browser detection fallback to try installed Edge/Chrome/Firefox/Chromium candidates before system default open.
 - Improved graph filter rendering to keep hub anchor nodes visible (`Memory Hub`/`MOC`/high-degree fallback) for coherent relationship context.
 - Fixed graph modal content loading by correcting agent query parameter composition for `/api/graph-node` and `/api/graph-filter` requests.
+- Improved 50k+ graph rendering performance with viewport-aware spatial node culling, cached render visibility, and node-adjacent edge selection to avoid full graph scans every frame.
+- Added incremental vault indexing with file snapshots to reuse unchanged documents/chunks/embeddings, plus adaptive search-pack rebuild thresholds to avoid full re-compression on small edits.
 
 ## 0.1.0-beta.3
 

package/README.md

@@ -71,6 +71,8 @@ Legacy `.jsonl.gz` packs are upgraded to `.blpk` automatically on first search/c
 - Middle-out context assembly around the strongest chunk per document.
 - In-process index and context caching with automatic invalidation on index updates.
 - Compressed-space prefiltering for `.blpk` packs before decryption and scan.
+- Incremental indexing that reprocesses only changed markdown files and reuses existing chunks/embeddings for unchanged notes.
+- Adaptive compressed-pack rebuild policy to keep indexing fast during small edit batches.
 - Agent namespaces under `agents/<agent-id>/`.
 - S3-compatible bucket vaults through `s3://bucket/prefix` URIs.
 - CLI with machine-readable `--json` output.
@@ -78,6 +80,7 @@ Legacy `.jsonl.gz` packs are upgraded to `.blpk` automatically on first search/c
 - Built-in MCP stdio server for agent tool integration.
 - Local HTTP API.
 - Realtime graph UI with agent selector and colored knowledge groups.
+- Graph renderer optimized for large datasets with viewport-driven node culling and edge lookup by visible nodes.
 
 ## Install
 

package/dist/application/frontend/client-js.js

@@ -3,6 +3,7 @@ const ctx = canvas.getContext('2d')
 const largeGraphNodeThreshold = 4000
 const largeGraphEdgeRenderLimit = 16000
 const renderNodeBudget = 1800
+const renderEdgeBudget = 5200
 const minNodePixelRadius = 1.8
 const viewportPaddingPx = 280
 const worldCoordinateLimit = 5_000_000
@@ -30,7 +31,11 @@ const state = {
   graphStatus: '',
   last: performance.now(),
   offscreenFrameCount: 0,
-  recoveringViewport: false
+  recoveringViewport: false,
+  renderVisibilityDirty: true,
+  lastViewportKey: '',
+  visibleNodeSpatial: { cellSize: 220, minX: 0, minY: 0, maxX: 0, maxY: 0, buckets: new Map() },
+  visibleEdgeByNode: new Map()
 }
 
 const byId = id => document.getElementById(id)
@@ -96,6 +101,7 @@ const resize = () => {
   canvas.width = Math.floor(width * ratio)
   canvas.height = Math.floor(height * ratio)
   ctx.setTransform(ratio, 0, 0, ratio, 0, 0)
+  markRenderDirty()
 }
 
 const normalizeQuery = value => value.trim().toLowerCase()
@@ -168,9 +174,158 @@ const recomputeVisibility = () => {
 
   state.visibleNodes = nodes
   state.visibleEdges = limitedEdges
+  state.visibleNodeSpatial = createSpatialIndex(nodes)
+  state.visibleEdgeByNode = createVisibleEdgeLookup(limitedEdges)
+  markRenderDirty()
 }
 
 const edgeWeight = edge => Number.isFinite(edge.weight) ? Math.max(1, edge.weight) : 1
+const markRenderDirty = () => {
+  state.renderVisibilityDirty = true
+}
+
+const createSpatialIndex = nodes => {
+  if (nodes.length === 0) {
+    return { cellSize: 220, minX: 0, minY: 0, maxX: 0, maxY: 0, buckets: new Map() }
+  }
+
+  const bounds = graphBounds(nodes)
+  if (!bounds) {
+    return { cellSize: 220, minX: 0, minY: 0, maxX: 0, maxY: 0, buckets: new Map() }
+  }
+
+  const targetNodesPerCell = 18
+  const approximateCellArea = Math.max((bounds.width * bounds.height) / Math.max(nodes.length / targetNodesPerCell, 1), 1)
+  const cellSize = Math.max(90, Math.min(2200, Math.sqrt(approximateCellArea)))
+  const buckets = new Map()
+
+  for (let index = 0; index < nodes.length; index += 1) {
+    const node = nodes[index]
+    const cellX = Math.floor((node.x - bounds.minX) / cellSize)
+    const cellY = Math.floor((node.y - bounds.minY) / cellSize)
+    const key = cellX + ':' + cellY
+    const bucket = buckets.get(key)
+    if (bucket) {
+      bucket.push(node)
+      continue
+    }
+    buckets.set(key, [node])
+  }
+
+  return {
+    cellSize,
+    minX: bounds.minX,
+    minY: bounds.minY,
+    maxX: bounds.maxX,
+    maxY: bounds.maxY,
+    buckets
+  }
+}
+
+const viewportNodesFromSpatialIndex = viewport => {
+  if (state.visibleNodes.length <= 2500) {
+    return state.visibleNodes.filter(node => isNodeInViewport(node, viewport))
+  }
+
+  const spatial = state.visibleNodeSpatial
+  if (!spatial || spatial.buckets.size === 0) {
+    return state.visibleNodes.filter(node => isNodeInViewport(node, viewport))
+  }
+
+  const minCellX = Math.floor((viewport.minX - spatial.minX) / spatial.cellSize)
+  const maxCellX = Math.floor((viewport.maxX - spatial.minX) / spatial.cellSize)
+  const minCellY = Math.floor((viewport.minY - spatial.minY) / spatial.cellSize)
+  const maxCellY = Math.floor((viewport.maxY - spatial.minY) / spatial.cellSize)
+  const nodes = []
+
+  for (let cellX = minCellX; cellX <= maxCellX; cellX += 1) {
+    for (let cellY = minCellY; cellY <= maxCellY; cellY += 1) {
+      const bucket = spatial.buckets.get(cellX + ':' + cellY)
+      if (!bucket) continue
+
+      for (let index = 0; index < bucket.length; index += 1) {
+        const node = bucket[index]
+        if (isNodeInViewport(node, viewport)) {
+          nodes.push(node)
+        }
+      }
+    }
+  }
+
+  return nodes
+}
+
+const createVisibleEdgeLookup = edges => {
+  const lookup = new Map()
+
+  for (let index = 0; index < edges.length; index += 1) {
+    const edge = edges[index]
+    if (!edge.target) continue
+
+    const sourceList = lookup.get(edge.source)
+    if (sourceList) {
+      sourceList.push(edge)
+    } else {
+      lookup.set(edge.source, [edge])
+    }
+
+    const targetList = lookup.get(edge.target)
+    if (targetList) {
+      targetList.push(edge)
+    } else {
+      lookup.set(edge.target, [edge])
+    }
+  }
+
+  return lookup
+}
+
+const collectVisibleEdgesForNodes = nodeIds => {
+  if (nodeIds.size === 0) {
+    return []
+  }
+
+  const seen = new Set()
+  const collected = []
+
+  nodeIds.forEach(nodeId => {
+    const candidateEdges = state.visibleEdgeByNode.get(nodeId) ?? []
+    for (let index = 0; index < candidateEdges.length; index += 1) {
+      const edge = candidateEdges[index]
+      if (!edge.target || !nodeIds.has(edge.source) || !nodeIds.has(edge.target)) {
+        continue
+      }
+      const key = edge.source < edge.target
+        ? edge.source + '|' + edge.target + '|' + edge.targetTitle
+        : edge.target + '|' + edge.source + '|' + edge.targetTitle
+      if (seen.has(key)) continue
+
+      seen.add(key)
+      collected.push(edge)
+      if (collected.length >= renderEdgeBudget) {
+        return
+      }
+    }
+  })
+
+  return collected
+}
+
+const fallbackViewportNodes = () => {
+  const nodes = []
+  const maxNodes = Math.min(renderNodeBudget, 220)
+  const step = Math.max(1, Math.ceil(state.visibleNodes.length / maxNodes))
+
+  for (let index = 0; index < state.visibleNodes.length && nodes.length < maxNodes; index += step) {
+    nodes.push(state.visibleNodes[index])
+  }
+
+  if (state.selected && !nodes.find(node => node.id === state.selected.id)) {
+    nodes.push(state.selected)
+  }
+
+  return nodes
+}
 
 const clampScale = value => Math.max(zoomRange.min, Math.min(zoomRange.max, value))
 const isFiniteNumber = value => Number.isFinite(value)
@@ -232,6 +387,7 @@ const fitView = (options = { useFiltered: true }) => {
 
   if (!bounds) {
     state.transform = { x: width / 2, y: height / 2, scale: 1 }
+    markRenderDirty()
     return
   }
 
@@ -259,6 +415,7 @@ const fitView = (options = { useFiltered: true }) => {
     y: height / 2 - centerY * scale,
     scale
   }
+  markRenderDirty()
 }
 
 const resetView = () => fitView({ useFiltered: false })
@@ -429,6 +586,7 @@ const worldPoint = event => {
 }
 
 const hitNode = point => {
+  computeRenderVisibility()
   if (state.nodes.length > largeGraphNodeThreshold && state.transform.scale < 0.55) {
     return null
   }
@@ -491,22 +649,33 @@ const viewportNodeStride = () => {
 }
 
 const computeRenderVisibility = () => {
+  const viewport = worldViewportBounds()
+  const viewportKey =
+    Math.round(viewport.minX * 10) + ':' +
+    Math.round(viewport.maxX * 10) + ':' +
+    Math.round(viewport.minY * 10) + ':' +
+    Math.round(viewport.maxY * 10) + ':' +
+    Math.round(state.transform.scale * 1000)
+
+  if (!state.renderVisibilityDirty && viewportKey === state.lastViewportKey) {
+    return
+  }
+  state.lastViewportKey = viewportKey
+  state.renderVisibilityDirty = false
+
   if (state.visibleNodes.length <= 2000) {
     state.renderNodes = state.visibleNodes
     const ids = new Set(state.renderNodes.map((node) => node.id))
-    state.renderEdges = state.visibleEdges.filter((edge) => ids.has(edge.source) && edge.target && ids.has(edge.target))
+    state.renderEdges = collectVisibleEdgesForNodes(ids)
     return
   }
 
-  const viewport = worldViewportBounds()
+  const viewportNodes = viewportNodesFromSpatialIndex(viewport)
   const stride = viewportNodeStride()
   const picked = []
 
-  for (let index = 0; index < state.visibleNodes.length; index += 1) {
-    const node = state.visibleNodes[index]
-    if (!isNodeInViewport(node, viewport)) {
-      continue
-    }
+  for (let index = 0; index < viewportNodes.length; index += 1) {
+    const node = viewportNodes[index]
 
     const isPriority =
       node.id === state.selected?.id ||
@@ -521,26 +690,15 @@ const computeRenderVisibility = () => {
     ? picked.slice(0, renderNodeBudget)
     : picked
   if (nodes.length === 0 && state.visibleNodes.length > 0) {
-    const centerX = (viewport.minX + viewport.maxX) / 2
-    const centerY = (viewport.minY + viewport.maxY) / 2
-    const closest = [...state.visibleNodes]
-      .sort((left, right) => {
-        const leftDistance = (left.x - centerX) ** 2 + (left.y - centerY) ** 2
-        const rightDistance = (right.x - centerX) ** 2 + (right.y - centerY) ** 2
-        return leftDistance - rightDistance
-      })
-      .slice(0, Math.min(renderNodeBudget, 180))
-    const closestIds = new Set(closest.map((node) => node.id))
-
-    state.renderNodes = closest
-    state.renderEdges = state.visibleEdges.filter(
-      (edge) => closestIds.has(edge.source) && edge.target && closestIds.has(edge.target)
-    )
+    const fallbackNodes = fallbackViewportNodes()
+    const fallbackIds = new Set(fallbackNodes.map((node) => node.id))
+    state.renderNodes = fallbackNodes
+    state.renderEdges = collectVisibleEdgesForNodes(fallbackIds)
     return
   }
 
   const nodeIds = new Set(nodes.map((node) => node.id))
-  const edges = state.visibleEdges.filter((edge) => nodeIds.has(edge.source) && edge.target && nodeIds.has(edge.target))
+  const edges = collectVisibleEdgesForNodes(nodeIds)
 
   state.renderNodes = nodes
   state.renderEdges = edges
@@ -767,6 +925,7 @@ const zoomAtPoint = (screenX, screenY, factor) => {
   state.transform.scale = nextScale
   state.transform.x = screenX - worldX * nextScale
   state.transform.y = screenY - worldY * nextScale
+  markRenderDirty()
 }
 
 const wheelZoomFactor = event => {
@@ -869,6 +1028,7 @@ const bindEvents = () => {
     if (node) {
       node.x = point.x
       node.y = point.y
+      markRenderDirty()
     }
     canvas.setPointerCapture(event.pointerId)
   })
@@ -885,10 +1045,12 @@ const bindEvents = () => {
     if (state.pointer.dragNode) {
       state.pointer.dragNode.x = point.x
       state.pointer.dragNode.y = point.y
+      markRenderDirty()
       return
     }
     state.transform.x += dx
     state.transform.y += dy
+    markRenderDirty()
   })
   canvas.addEventListener('pointerup', event => {
     if (state.pointer.dragNode && !state.pointer.moved) selectNode(state.pointer.dragNode, { openContent: true })

package/dist/application/index-vault.js

@@ -1,8 +1,11 @@
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
 import { createIndexedDocument, parseMarkdownDocument } from '../domain/markdown.js';
 import { sharedAgentId } from '../domain/agents.js';
 import { createEmbeddingProvider } from '../domain/embeddings.js';
 import { loadBrainlinkConfig } from '../infrastructure/config.js';
-import { ensureVault, readMarkdownFiles } from '../infrastructure/file-system-vault.js';
+import { ensureVault, readMarkdownFileSummaries } from '../infrastructure/file-system-vault.js';
+import { readIndexState, writeIndexState } from '../infrastructure/index-state.js';
 import { buildSearchPacks } from '../infrastructure/search-packs.js';
 import { openFileIndex } from '../infrastructure/file-index.js';
 const toTitleKey = (title) => title.toLowerCase();
@@ -34,6 +37,9 @@ const createScopedTitleResolver = (document, titleMaps) => ({
     get: (title) => titleMaps.byAgent.get(document.agentId)?.get(title)?.id ?? titleMaps.shared.get(title)?.id
 });
 const embedIndexedDocuments = async (documents, providerName) => {
+    if (documents.length === 0) {
+        return documents;
+    }
     const provider = createEmbeddingProvider(providerName);
     const chunks = documents.flatMap((document) => document.chunks);
     const embeddings = await provider.embed(chunks.map((chunk) => chunk.content));
@@ -47,34 +53,144 @@ const embedIndexedDocuments = async (documents, providerName) => {
         }))
     }));
 };
+const relinkIndexedDocument = (indexedDocument, titleMaps) => {
+    const resolver = createScopedTitleResolver(indexedDocument.document, titleMaps);
+    return {
+        ...indexedDocument,
+        links: indexedDocument.links
+            .map((link) => ({
+            ...link,
+            toDocumentId: resolver.get(link.toTitle.toLowerCase()) ?? null
+        }))
+            .filter((link) => link.toDocumentId !== indexedDocument.document.id)
+    };
+};
+const toIndexResult = (documents) => ({
+    documentCount: documents.length,
+    chunkCount: documents.reduce((total, document) => total + document.chunks.length, 0),
+    linkCount: documents.reduce((total, document) => total + document.links.length, 0)
+});
+const toSnapshot = (summaries) => summaries.map((summary) => ({
+    path: summary.relativePath,
+    mtimeMs: summary.updatedAt.getTime(),
+    size: summary.size
+}));
+const createSnapshotMap = (snapshot) => new Map(snapshot.map((entry) => [entry.path, entry]));
+const packManifestPath = (vaultPath) => join(vaultPath, '.brainlink', 'search-packs', 'manifest.json');
+const hasPackManifest = async (vaultPath) => {
+    try {
+        await stat(packManifestPath(vaultPath));
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const readChangedDocuments = async (absoluteVaultPath, changedSummaries) => {
+    const parsed = await Promise.all(changedSummaries.map(async (summary) => parseMarkdownDocument({
+        absolutePath: summary.absolutePath,
+        vaultPath: absoluteVaultPath,
+        content: await readFile(summary.absolutePath, 'utf8'),
+        createdAt: summary.createdAt,
+        updatedAt: summary.updatedAt
+    })));
+    return new Map(parsed.map((document) => [document.path, document]));
+};
 export const indexVault = async (vaultPath) => {
     const absoluteVaultPath = await ensureVault(vaultPath);
     const config = await loadBrainlinkConfig();
-    const files = await readMarkdownFiles(absoluteVaultPath);
-    const documents = files.map((file) => parseMarkdownDocument({
-        absolutePath: file.absolutePath,
-        vaultPath: absoluteVaultPath,
-        content: file.content,
-        createdAt: file.createdAt,
-        updatedAt: file.updatedAt
-    }));
-    const titleMaps = createTitleMaps(documents);
-    const indexedDocuments = await embedIndexedDocuments(documents.map((document) => createIndexedDocument(document, createScopedTitleResolver(document, titleMaps), config.chunkSize)), config.embeddingProvider);
+    const [summaries, previousState] = await Promise.all([
+        readMarkdownFileSummaries(absoluteVaultPath),
+        readIndexState(absoluteVaultPath)
+    ]);
     const index = openFileIndex(absoluteVaultPath);
     try {
+        const existingIndexedDocuments = await index.getIndexedDocuments();
+        const existingByPath = new Map(existingIndexedDocuments.map((document) => [document.document.path, document]));
+        const currentSnapshot = toSnapshot(summaries);
+        const currentSnapshotMap = createSnapshotMap(currentSnapshot);
+        const previousSnapshotMap = createSnapshotMap(previousState?.files ?? []);
+        const settingsChanged = previousState == null ||
+            previousState.chunkSize !== config.chunkSize ||
+            previousState.embeddingProvider !== config.embeddingProvider;
+        const changedPaths = new Set();
+        for (let index = 0; index < summaries.length; index += 1) {
+            const summary = summaries[index];
+            const previous = previousSnapshotMap.get(summary.relativePath);
+            const changed = settingsChanged ||
+                previous == null ||
+                previous.mtimeMs !== summary.updatedAt.getTime() ||
+                previous.size !== summary.size ||
+                !existingByPath.has(summary.relativePath);
+            if (changed) {
+                changedPaths.add(summary.relativePath);
+            }
+        }
+        const hasDeletes = previousState
+            ? previousState.files.some((entry) => !currentSnapshotMap.has(entry.path))
+            : false;
+        if (changedPaths.size === 0 &&
+            !hasDeletes &&
+            existingIndexedDocuments.length === summaries.length &&
+            previousState != null) {
+            return toIndexResult(existingIndexedDocuments);
+        }
+        const changedSummaries = summaries.filter((summary) => changedPaths.has(summary.relativePath));
+        const changedDocumentsByPath = await readChangedDocuments(absoluteVaultPath, changedSummaries);
+        const documents = summaries.flatMap((summary) => {
+            const changed = changedDocumentsByPath.get(summary.relativePath);
+            if (changed) {
+                return [changed];
+            }
+            const existing = existingByPath.get(summary.relativePath);
+            return existing ? [existing.document] : [];
+        });
+        const titleMaps = createTitleMaps(documents);
+        const changedIndexedDocuments = changedDocumentsByPath.size > 0
+            ? await embedIndexedDocuments(Array.from(changedDocumentsByPath.values()).map((document) => createIndexedDocument(document, createScopedTitleResolver(document, titleMaps), config.chunkSize)), config.embeddingProvider)
+            : [];
+        const changedIndexedByPath = new Map(changedIndexedDocuments.map((document) => [document.document.path, document]));
+        const needsRelink = settingsChanged || hasDeletes || changedPaths.size > 0;
+        const indexedDocuments = documents.map((document) => {
+            const changed = changedIndexedByPath.get(document.path);
+            if (changed) {
+                return changed;
+            }
+            const existing = existingByPath.get(document.path);
+            if (!existing) {
+                return createIndexedDocument(document, createScopedTitleResolver(document, titleMaps), config.chunkSize);
+            }
+            return needsRelink ? relinkIndexedDocument(existing, titleMaps) : existing;
+        });
         await index.reset();
         await index.saveDocuments(indexedDocuments);
-        try {
-            await buildSearchPacks(absoluteVaultPath, indexedDocuments);
+        const existingPackManifest = await hasPackManifest(absoluteVaultPath);
+        const changedCount = changedPaths.size;
+        const documentCount = Math.max(indexedDocuments.length, 1);
+        const changeRatio = changedCount / documentCount;
+        const previousPendingPackChanges = previousState?.pendingPackChanges ?? 0;
+        const pendingPackChanges = previousPendingPackChanges + changedCount;
+        const shouldRebuildPacks = !existingPackManifest ||
+            settingsChanged ||
+            hasDeletes ||
+            changedCount >= 400 ||
+            changeRatio >= 0.04 ||
+            pendingPackChanges >= 1200;
+        if (shouldRebuildPacks) {
+            try {
+                await buildSearchPacks(absoluteVaultPath, indexedDocuments);
+            }
+            catch {
+                // Pack generation is best-effort. The JSON index remains the primary path.
+            }
         }
-        catch {
-            // Pack generation is best-effort. The JSON index remains the primary path.
-        }
-        return {
-            documentCount: indexedDocuments.length,
-            chunkCount: indexedDocuments.reduce((total, document) => total + document.chunks.length, 0),
-            linkCount: indexedDocuments.reduce((total, document) => total + document.links.length, 0)
-        };
+        await writeIndexState(absoluteVaultPath, {
+            chunkSize: config.chunkSize,
+            embeddingProvider: config.embeddingProvider,
+            files: currentSnapshot,
+            pendingPackChanges: shouldRebuildPacks ? 0 : pendingPackChanges
+        });
+        return toIndexResult(indexedDocuments);
     }
     finally {
         index.close();

package/dist/infrastructure/file-index.js

@@ -155,6 +155,36 @@ export const openFileIndex = (vaultPath) => {
                 links
             });
         },
+        getIndexedDocuments: async (agentId) => {
+            const index = await load();
+            const documents = agentId ? index.documents.filter((document) => document.agentId === agentId) : index.documents;
+            const selectedDocumentIds = new Set(documents.map((document) => document.id));
+            const chunksByDocumentId = index.chunks.reduce((state, chunk) => {
+                if (!selectedDocumentIds.has(chunk.documentId)) {
+                    return state;
+                }
+                const current = state.get(chunk.documentId) ?? [];
+                current.push(chunk);
+                state.set(chunk.documentId, current);
+                return state;
+            }, new Map());
+            const linksByDocumentId = index.links.reduce((state, link) => {
+                if (!selectedDocumentIds.has(link.fromDocumentId)) {
+                    return state;
+                }
+                const current = state.get(link.fromDocumentId) ?? [];
+                current.push(link);
+                state.set(link.fromDocumentId, current);
+                return state;
+            }, new Map());
+            return documents
+                .map((document) => ({
+                document,
+                chunks: [...(chunksByDocumentId.get(document.id) ?? [])].sort((left, right) => left.ordinal - right.ordinal),
+                links: linksByDocumentId.get(document.id) ?? []
+            }))
+                .sort((left, right) => left.document.path.localeCompare(right.document.path));
+        },
         search: async (query, limit, agentId, mode = 'hybrid', queryEmbedding = []) => {
             const index = await load();
             const documentsById = new Map(index.documents.map((document) => [document.id, document]));

package/dist/infrastructure/file-system-vault.js

@@ -76,6 +76,21 @@ export const readMarkdownFiles = async (vaultPath) => {
         };
     }));
 };
+export const readMarkdownFileSummaries = async (vaultPath) => {
+    const absoluteVaultPath = await ensureVault(vaultPath);
+    const paths = await walkMarkdownFiles(absoluteVaultPath);
+    const summaries = await Promise.all(paths.map(async (absolutePath) => {
+        const fileStats = await stat(absolutePath);
+        return {
+            absolutePath,
+            relativePath: relative(absoluteVaultPath, absolutePath),
+            createdAt: fileStats.birthtime,
+            updatedAt: fileStats.mtime,
+            size: fileStats.size
+        };
+    }));
+    return summaries.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+};
 export const listVaultFiles = async (vaultPath) => {
     const absoluteVaultPath = await ensureVault(vaultPath);
     return walkVaultFiles(absoluteVaultPath);

package/dist/infrastructure/index-state.js

@@ -0,0 +1,50 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const indexStateFileName = 'index-state.json';
+const toIndexStatePath = (vaultPath) => join(vaultPath, '.brainlink', indexStateFileName);
+export const readIndexState = async (vaultPath) => {
+    try {
+        const parsed = JSON.parse(await readFile(toIndexStatePath(vaultPath), 'utf8'));
+        if (parsed.version !== 1 || !Array.isArray(parsed.files)) {
+            return null;
+        }
+        const files = parsed.files.flatMap((entry) => {
+            if (!entry || typeof entry !== 'object') {
+                return [];
+            }
+            const row = entry;
+            if (typeof row.path !== 'string' || typeof row.mtimeMs !== 'number' || typeof row.size !== 'number') {
+                return [];
+            }
+            return [
+                {
+                    path: row.path,
+                    mtimeMs: row.mtimeMs,
+                    size: row.size
+                }
+            ];
+        });
+        return {
+            version: 1,
+            updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : new Date().toISOString(),
+            chunkSize: typeof parsed.chunkSize === 'number' ? parsed.chunkSize : 1200,
+            embeddingProvider: typeof parsed.embeddingProvider === 'string' ? parsed.embeddingProvider : 'none',
+            files,
+            pendingPackChanges: typeof parsed.pendingPackChanges === 'number' && parsed.pendingPackChanges >= 0 ? parsed.pendingPackChanges : 0
+        };
+    }
+    catch {
+        return null;
+    }
+};
+export const writeIndexState = async (vaultPath, state) => {
+    const payload = {
+        version: 1,
+        updatedAt: new Date().toISOString(),
+        chunkSize: state.chunkSize,
+        embeddingProvider: state.embeddingProvider,
+        files: [...state.files].sort((left, right) => left.path.localeCompare(right.path)),
+        pendingPackChanges: Math.max(0, Math.floor(state.pendingPackChanges))
+    };
+    await writeFile(toIndexStatePath(vaultPath), `${JSON.stringify(payload)}\n`, 'utf8');
+};

package/package.json

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