@andespindola/brainlink 0.1.0-beta.36 → 0.1.0-beta.38

package/CHANGELOG.md

@@ -28,6 +28,8 @@
 - Added cross-platform native desktop GUI auto-open for `blink server` (macOS Swift/WebKit, Windows PowerShell WinForms, Linux Python GTK/WebKit2), with app-window/browser fallback.
 - Changed Linux default UI launch to app-window/browser for lighter startup; Linux native GUI is now opt-in via `BRAINLINK_LINUX_NATIVE_GUI=1`.
 - Added native GUI parent-process monitoring so GUI windows close automatically when `blink server` stops.
+- 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.
 
 ## 0.1.0-beta.3
 

package/COPYRIGHT.md

@@ -1,4 +1,4 @@
-Copyright (c) 2026 Anderson Espindola
+Copyright (c) 2026 Substructa
 
 This project is licensed under the MIT License.
 

package/README.md

@@ -69,6 +69,7 @@ Legacy `.jsonl.gz` packs are upgraded to `.blpk` automatically on first search/c
 - Backlinks, broken-link reports, orphan detection and validation.
 - Full-text, semantic and hybrid retrieval on a local file index.
 - 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.
 - Agent namespaces under `agents/<agent-id>/`.
 - S3-compatible bucket vaults through `s3://bucket/prefix` URIs.
@@ -571,6 +572,7 @@ The graph UI shows:
 - neutral graph nodes with segment/group metadata
 - agent selector (id-only labels) for isolated views
 - graph filter matches title, path, tags and note content
+- graph filter keeps hub context nodes visible (`Memory Hub`/`MOC`/high-degree fallback) to preserve relationship readability
 - realtime refresh while `--watch` is enabled
 - graph controls for zoom in, zoom out, fit visible nodes and reset-to-fit-all
 - wheel zoom (including `cmd+scroll` and `ctrl+scroll`) anchored to cursor position for faster navigation in large graphs
@@ -763,6 +765,7 @@ blink context "question" --vault ./vault --agent coding-agent --mode hybrid --js
 ```
 
 Builds a compact context package for an agent.
+Repeated calls with the same vault, agent, query, mode and token/limit settings are served from a short in-memory cache while the index is unchanged.
 
 ### `links`
 
@@ -1055,7 +1058,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 ## License
 
 MIT. See [LICENSE](LICENSE).
-Copyright (c) 2026 Anderson Espindola. See [COPYRIGHT.md](COPYRIGHT.md).
+Copyright (c) 2026 Substructa. See [COPYRIGHT.md](COPYRIGHT.md).
 
 ### Memory Optimization Loop (1-7)
 

package/dist/application/build-context.js

@@ -1,13 +1,68 @@
+import { stat } from 'node:fs/promises';
 import { formatContextPackage, selectContextSections } from '../domain/context.js';
+import { indexStoragePath } from '../infrastructure/file-index.js';
 import { searchKnowledge } from './search-knowledge.js';
+const contextCacheTtlMs = 45_000;
+const contextCacheMaxEntries = 200;
+const contextCache = new Map();
+const readIndexMtimeMs = async (vaultPath) => {
+    try {
+        return (await stat(indexStoragePath(vaultPath))).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+};
+const toCacheKey = (vaultPath, query, limit, maxTokens, agentId, mode) => JSON.stringify({
+    vaultPath,
+    query: query.trim().toLowerCase(),
+    limit,
+    maxTokens,
+    agentId: agentId?.trim().toLowerCase() ?? '*',
+    mode: mode ?? 'default'
+});
+const contextCacheGet = (key, indexMtimeMs) => {
+    const entry = contextCache.get(key);
+    if (!entry) {
+        return undefined;
+    }
+    const fresh = Date.now() - entry.createdAt <= contextCacheTtlMs && entry.indexMtimeMs === indexMtimeMs;
+    if (!fresh) {
+        contextCache.delete(key);
+        return undefined;
+    }
+    return entry.context;
+};
+const contextCacheSet = (entry) => {
+    contextCache.set(entry.key, entry);
+    if (contextCache.size <= contextCacheMaxEntries) {
+        return;
+    }
+    const overflow = contextCache.size - contextCacheMaxEntries;
+    const keys = Array.from(contextCache.keys()).slice(0, overflow);
+    keys.forEach((key) => contextCache.delete(key));
+};
 export const buildContextPackage = async (vaultPath, query, limit, maxTokens, agentId, mode) => {
+    const cacheKey = toCacheKey(vaultPath, query, limit, maxTokens, agentId, mode);
+    const indexMtimeMs = await readIndexMtimeMs(vaultPath);
+    const cached = contextCacheGet(cacheKey, indexMtimeMs);
+    if (cached) {
+        return cached;
+    }
     const results = await searchKnowledge(vaultPath, query, limit, agentId, mode);
     const sections = selectContextSections(results, maxTokens);
-    return {
+    const context = {
         query,
         sections,
         content: formatContextPackage(query, sections)
     };
+    contextCacheSet({
+        key: cacheKey,
+        createdAt: Date.now(),
+        indexMtimeMs,
+        context
+    });
+    return context;
 };
 export const buildContext = async (vaultPath, query, limit, maxTokens, agentId, mode) => {
     const contextPackage = await buildContextPackage(vaultPath, query, limit, maxTokens, agentId, mode);

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

@@ -46,8 +46,8 @@ export const createClientHtml = () => `<!doctype html>
         <canvas id="graph" aria-label="Brainlink knowledge graph"></canvas>
       </section>
     </main>
-    <footer class="app-footer" aria-label="License notice">
-      <small>MIT License · Copyright © 2026 Anderson Espindola</small>
+    <footer class="app-footer" aria-label="Copyright notice">
+      <small>Copyright © 2026 Substructa</small>
     </footer>
     <dialog id="contentDialog" class="content-dialog" aria-labelledby="contentTitle">
       <article>

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

@@ -99,6 +99,8 @@ const resize = () => {
 }
 
 const normalizeQuery = value => value.trim().toLowerCase()
+const hubNodeRetentionLimit = 2
+const hubNodePattern = /\b(memory\s*hub|knowledge\s*hub|hub|moc|map|memory\s*map|mapa)\b/i
 
 const localFilteredNodes = query =>
   state.nodes.filter(node =>
@@ -107,14 +109,51 @@ const localFilteredNodes = query =>
     node.tags.some(tag => tag.toLowerCase().includes(query))
   )
 
+const rankedHubNodes = () => {
+  if (state.nodes.length === 0) {
+    return []
+  }
+
+  const byTitleAndDegree = [...state.nodes]
+    .filter(node => hubNodePattern.test(node.title) || hubNodePattern.test(node.path) || node.tags.some(tag => hubNodePattern.test(tag)))
+    .sort((left, right) => {
+      const byDegree = (state.nodeDegrees.get(right.id) ?? 0) - (state.nodeDegrees.get(left.id) ?? 0)
+      if (byDegree !== 0) return byDegree
+      return left.title.localeCompare(right.title)
+    })
+
+  if (byTitleAndDegree.length > 0) {
+    return byTitleAndDegree.slice(0, hubNodeRetentionLimit)
+  }
+
+  return [...state.nodes]
+    .sort((left, right) => {
+      const byDegree = (state.nodeDegrees.get(right.id) ?? 0) - (state.nodeDegrees.get(left.id) ?? 0)
+      if (byDegree !== 0) return byDegree
+      return left.title.localeCompare(right.title)
+    })
+    .slice(0, 1)
+}
+
+const withPersistentHubNodes = nodes => {
+  if (nodes.length === 0) {
+    return rankedHubNodes()
+  }
+
+  const ids = new Set(nodes.map(node => node.id))
+  const hubsToKeep = rankedHubNodes().filter(node => !ids.has(node.id))
+  return nodes.concat(hubsToKeep)
+}
+
 const filteredNodes = () => {
   const query = normalizeQuery(state.query)
   if (!query) return state.nodes
   if (state.contentFilter.query === query && state.contentFilter.ids instanceof Set) {
-    return state.nodes.filter(node => state.contentFilter.ids.has(node.id))
+    const matched = state.nodes.filter(node => state.contentFilter.ids.has(node.id))
+    return withPersistentHubNodes(matched)
   }
 
-  return localFilteredNodes(query)
+  return withPersistentHubNodes(localFilteredNodes(query))
 }
 
 const recomputeVisibility = () => {

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

@@ -207,6 +207,10 @@ const commandExists = (command) => {
     }
 };
 const envFlagEnabled = (name) => process.env[name] === '1' || process.env[name] === 'true';
+const spawnAnyDetached = (candidates) => candidates.some(([command, args]) => spawnDetached(command, args));
+const windowsStartCandidates = (program, args = []) => [
+    ['cmd', ['/c', 'start', '', program, ...args]]
+];
 const resolveSwiftExecutable = () => {
     const directSwift = '/usr/bin/swift';
     if (existsSync(directSwift)) {
@@ -295,16 +299,47 @@ const openGraphInAppWindow = (url) => {
     }
     if (platform() === 'win32') {
         const appArgument = `--app=${url}`;
-        return (spawnDetached('cmd', ['/c', 'start', '', 'chrome', appArgument, '--new-window']) ||
-            spawnDetached('cmd', ['/c', 'start', '', 'msedge', appArgument, '--new-window']) ||
-            spawnDetached('cmd', ['/c', 'start', '', 'chromium', appArgument, '--new-window']));
+        return spawnAnyDetached([
+            ...windowsStartCandidates('msedge', [appArgument, '--new-window']),
+            ...windowsStartCandidates('chrome', [appArgument, '--new-window']),
+            ...windowsStartCandidates('chromium', [appArgument, '--new-window']),
+            ...windowsStartCandidates('brave', [appArgument, '--new-window'])
+        ]);
     }
     const appArgument = `--app=${url}`;
-    return (spawnDetached('google-chrome', [appArgument, '--new-window']) ||
-        spawnDetached('chromium-browser', [appArgument, '--new-window']) ||
-        spawnDetached('chromium', [appArgument, '--new-window']) ||
-        spawnDetached('microsoft-edge', [appArgument, '--new-window']) ||
-        spawnDetached('microsoft-edge-stable', [appArgument, '--new-window']));
+    const linuxAppWindowCandidates = [
+        'microsoft-edge',
+        'microsoft-edge-stable',
+        'google-chrome',
+        'google-chrome-stable',
+        'chromium',
+        'chromium-browser',
+        'brave-browser'
+    ].filter((candidate) => commandExists(candidate));
+    return spawnAnyDetached(linuxAppWindowCandidates.map((command) => [command, [appArgument, '--new-window']]));
+};
+const openGraphInDetectedBrowser = (url) => {
+    if (platform() === 'win32') {
+        return spawnAnyDetached([
+            ...windowsStartCandidates('msedge', [url]),
+            ...windowsStartCandidates('chrome', [url]),
+            ...windowsStartCandidates('firefox', ['-new-window', url]),
+            ...windowsStartCandidates('chromium', [url]),
+            ...windowsStartCandidates('brave', [url])
+        ]);
+    }
+    const linuxBrowserCandidates = [
+        ['microsoft-edge', [url]],
+        ['microsoft-edge-stable', [url]],
+        ['google-chrome', [url]],
+        ['google-chrome-stable', [url]],
+        ['chromium', [url]],
+        ['chromium-browser', [url]],
+        ['brave-browser', [url]],
+        ['firefox', ['-new-window', url]]
+    ];
+    const available = linuxBrowserCandidates.filter(([command]) => commandExists(command));
+    return spawnAnyDetached(available);
 };
 const openUrlInUi = (url, parentPid) => {
     const openDisabled = process.env.BRAINLINK_NO_BROWSER === '1' ||
@@ -326,6 +361,9 @@ const openUrlInUi = (url, parentPid) => {
         if (platform() === 'darwin') {
             return { opened: spawnDetached('open', [url]), mode: 'browser' };
         }
+        if (openGraphInDetectedBrowser(url)) {
+            return { opened: true, mode: 'browser' };
+        }
         if (platform() === 'win32') {
             return { opened: spawnDetached('cmd', ['/c', 'start', '', url]), mode: 'browser' };
         }

package/dist/infrastructure/file-index.js

@@ -1,7 +1,9 @@
-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { cosineSimilarity } from '../domain/embeddings.js';
 const queryTokenPattern = /[\p{L}\p{N}_-]+/gu;
+const indexCacheMaxEntries = 16;
+const indexCache = new Map();
 const emptyIndex = () => ({
     version: 1,
     updatedAt: new Date().toISOString(),
@@ -11,18 +13,44 @@ const emptyIndex = () => ({
 });
 export const indexStoragePath = (vaultPath) => join(vaultPath, '.brainlink', 'index.json');
 const readIndex = async (vaultPath) => {
+    const path = indexStoragePath(vaultPath);
+    let stats = null;
     try {
-        const parsed = JSON.parse(await readFile(indexStoragePath(vaultPath), 'utf8'));
-        return {
+        const fileStats = await stat(path);
+        stats = { mtimeMs: fileStats.mtimeMs, size: fileStats.size };
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            indexCache.delete(path);
+            return emptyIndex();
+        }
+        return emptyIndex();
+    }
+    const cached = indexCache.get(path);
+    if (cached && cached.mtimeMs === stats.mtimeMs && cached.size === stats.size) {
+        return cached.index;
+    }
+    try {
+        const parsed = JSON.parse(await readFile(path, 'utf8'));
+        const loaded = {
             version: 1,
             updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : new Date().toISOString(),
             documents: Array.isArray(parsed.documents) ? parsed.documents : [],
             chunks: Array.isArray(parsed.chunks) ? parsed.chunks : [],
             links: Array.isArray(parsed.links) ? parsed.links : []
         };
+        indexCache.set(path, { ...stats, index: loaded });
+        if (indexCache.size > indexCacheMaxEntries) {
+            const oldest = indexCache.keys().next().value;
+            if (typeof oldest === 'string') {
+                indexCache.delete(oldest);
+            }
+        }
+        return loaded;
     }
     catch (error) {
         if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            indexCache.delete(path);
             return emptyIndex();
         }
         return emptyIndex();
@@ -34,6 +62,12 @@ const writeIndex = async (vaultPath, index) => {
     await mkdir(dirname(target), { recursive: true, mode: 0o700 });
     await writeFile(temp, `${JSON.stringify(index)}\n`, { encoding: 'utf8', mode: 0o600 });
     await rename(temp, target);
+    const fileStats = await stat(target);
+    indexCache.set(target, {
+        mtimeMs: fileStats.mtimeMs,
+        size: fileStats.size,
+        index
+    });
 };
 const normalizeToken = (value) => value
     .normalize('NFKD')

package/docs/AGENT_USAGE.md

@@ -555,6 +555,7 @@ Without `--vault`, the graph UI serves `$HOME/.brainlink/vault`.
 The frontend includes an agent selector that shows only the agent id. Selecting an agent calls the same read APIs with `agent=<agent-id>` and renders that namespace instead of merging every agent into one graph.
 
 Graph navigation controls include zoom in, zoom out, fit visible nodes and reset-to-fit-all nodes. Mouse wheel zoom (including `cmd+scroll` and `ctrl+scroll`) is anchored to the cursor. Keyboard shortcuts are `+` (zoom in), `-` (zoom out) and `0` (reset fit). Double-click on canvas zooms in at cursor position. Totals for notes, links and tags stay visible as floating metrics under the Brainlink title, and node details open on click in a modal (tags, outgoing links, backlinks and Markdown content).
+During graph filtering, Brainlink keeps hub context nodes visible (`Memory Hub`/`MOC`/high-degree fallback) so filtered views still show relationship anchors.
 
 The command reindexes by default, then serves:
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@andespindola/brainlink",
-  "version": "0.1.0-beta.36",
+  "version": "0.1.0-beta.38",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",
-  "author": "Anderson Espindola",
+  "author": "Substructa",
   "homepage": "https://github.com/andersonflima/brainlink#readme",
   "repository": {
     "type": "git",