@andespindola/brainlink 0.1.0-beta.120 → 0.1.0-beta.122

package/README.md

@@ -88,7 +88,7 @@ Legacy `.jsonl.gz` packs are upgraded to `.blpk` automatically on first search/c
 - Large graph layout API automatically uses compact payload encoding with link-coverage-aware edge selection to reduce initial client load without hiding major relationships.
 - Large-segment layout spacing now grows logarithmically to keep initial visual density consistent between medium and very large vaults (for example, ~1k vs ~50k notes).
 - Graph coordinates are visually compacted across graph sizes so reset starts from a stable fitted scene and zoom-in progressively reveals local detail.
-- Zoomed-out graph LOD renders hierarchy groups as normal graph nodes and expands the focused group into child nodes progressively as zoom increases.
+- Zoomed-out graph LOD renders hierarchy groups as normal graph nodes and expands a group only after it is framed in the viewport, progressively hiding sibling groups in micro view.
 - Graph reset fits the full graph scene instead of starting in a separate macro overview mode.
 - Graph filtering runs in a dedicated browser worker to keep the UI thread responsive during heavy datasets.
 - Edge rendering budgets adapt to zoom level to prevent frame spikes on large graph panoramas.
@@ -535,6 +535,8 @@ Available tools:
 - `brainlink_resolve_duplicate`: resolve duplicate pairs (`merge`, `link`, `ignore`) with connectivity-safe fallback edges.
 - `brainlink_add_note`: write durable Markdown memory and reindex.
 - `brainlink_add_file`: ingest a local file as a note and reindex.
+- `brainlink_volatile_add`: write temporary agent-decided memory with TTL; volatile sections are included in context and never create durable graph edges.
+- `brainlink_volatile_clear`: clear temporary memory for the current vault/agent namespace.
 - `brainlink_index`: rebuild the vault index.
 - `brainlink_stats`: read indexed vault statistics.
 - `brainlink_validate`: validate broken links and orphan notes.
@@ -604,7 +606,7 @@ The graph UI shows:
 - graph rendering safeguards (batched canvas drawing across graph sizes, edge draw caps, lower redraw rate, zoom-aware interaction)
 - adaptive CPU safeguards for large graphs: idle frame pacing, throttled background physics updates and cached viewport dimensions to reduce redraw/layout overhead while preserving interaction responsiveness
 - WebGL node and edge acceleration when supported, falling back to Canvas 2D without changing graph behavior
-- large graph LOD keeps a recursive graph-of-graphs model: zoom-out shows one level of group nodes, zoom-in expands the focused node into its child graph, and deeper zoom repeats the same visual rule without a background glow layer
+- large graph LOD keeps a recursive graph-of-graphs model: zoom-out shows one level of group nodes, zoom-in expands the framed node into its child graph, micro view renders only that focused subgraph, and zoom-out restores sibling groups
 
 The server indexes before starting by default. Use `--no-index` to skip that step:
 
@@ -623,6 +625,7 @@ Routes:
 - `GET /api/agents`
 - `GET /api/graph`
 - `GET /api/graph-layout`
+- `GET /api/graph-view?x=<x>&y=<y>&w=<width>&h=<height>&scale=<scale>`
 - `GET /api/graph-node?id=<node-id>`
 - `GET /api/search?q=<query>&limit=10&mode=hybrid`
 - `GET /api/context?q=<query>&limit=12&tokens=2000&mode=hybrid`

package/dist/application/build-context.js

@@ -1,18 +1,21 @@
 import { stat } from 'node:fs/promises';
 import { formatContextPackage, selectContextSections } from '../domain/context.js';
 import { indexStoragePath } from '../infrastructure/file-index.js';
+import { searchVolatileMemory, volatileMemoryStoragePath } from '../infrastructure/volatile-memory.js';
 import { searchKnowledge } from './search-knowledge.js';
 const contextCacheTtlMs = 45_000;
 const contextCacheMaxEntries = 200;
 const contextCache = new Map();
-const readIndexMtimeMs = async (vaultPath) => {
+const readFileSignature = async (path) => {
     try {
-        return (await stat(indexStoragePath(vaultPath))).mtimeMs;
+        const info = await stat(path);
+        return `${Math.floor(info.mtimeMs)}:${info.size}`;
     }
     catch {
-        return 0;
+        return '0:0';
     }
 };
+const readContextDataSignature = async (vaultPath) => `${await readFileSignature(indexStoragePath(vaultPath))}|${await readFileSignature(volatileMemoryStoragePath(vaultPath))}`;
 const toCacheKey = (vaultPath, query, limit, maxTokens, agentId, mode) => JSON.stringify({
     vaultPath,
     query: query.trim().toLowerCase(),
@@ -21,12 +24,12 @@ const toCacheKey = (vaultPath, query, limit, maxTokens, agentId, mode) => JSON.s
     agentId: agentId?.trim().toLowerCase() ?? '*',
     mode: mode ?? 'default'
 });
-const contextCacheGet = (key, indexMtimeMs) => {
+const contextCacheGet = (key, dataSignature) => {
     const entry = contextCache.get(key);
     if (!entry) {
         return undefined;
     }
-    const fresh = Date.now() - entry.createdAt <= contextCacheTtlMs && entry.indexMtimeMs === indexMtimeMs;
+    const fresh = Date.now() - entry.createdAt <= contextCacheTtlMs && entry.dataSignature === dataSignature;
     if (!fresh) {
         contextCache.delete(key);
         return undefined;
@@ -44,22 +47,25 @@ const contextCacheSet = (entry) => {
 };
 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);
+    const dataSignature = await readContextDataSignature(vaultPath);
+    const cached = contextCacheGet(cacheKey, dataSignature);
     if (cached) {
         return cached;
     }
     const results = await searchKnowledge(vaultPath, query, limit, agentId, mode);
-    const sections = selectContextSections(results, maxTokens);
+    const durableSections = selectContextSections(results, maxTokens);
+    const volatileSections = await searchVolatileMemory(vaultPath, query, Math.min(3, limit), agentId, mode ?? 'hybrid');
+    const sections = [...volatileSections, ...durableSections];
     const context = {
         query,
         sections,
-        content: formatContextPackage(query, sections)
+        content: formatContextPackage(query, sections),
+        ...(volatileSections.length > 0 ? { volatileSections } : {})
     };
     contextCacheSet({
         key: cacheKey,
         createdAt: Date.now(),
-        indexMtimeMs,
+        dataSignature,
         context
     });
     return context;

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

@@ -13,7 +13,10 @@ const massiveSegmentRepresentativeBudget = 760
 const massiveAutoFitMacroScale = 0.018
 const hierarchyGroupScaleThreshold = 0.62
 const hierarchyExpansionStartScale = 0.18
-const hierarchyExpansionEndScale = 0.62
+const hierarchyMicroEnterCoverage = 0.72
+const hierarchyMicroExitCoverage = 0.52
+const hierarchyMicroEnterScale = 0.24
+const hierarchyMicroExitScale = 0.16
 const minNodePixelRadius = 2.3
 const viewportPaddingPx = 280
 const worldCoordinateLimit = 5_000_000
@@ -81,6 +84,7 @@ const state = {
   lastHoverHitAt: 0,
   lastManualZoomAt: 0,
   lastZoomFocus: { x: 0, y: 0, at: 0 },
+  hierarchyFocusGroupId: null,
   zoomTransition: {
     active: false,
     source: 'generic',
@@ -1199,12 +1203,9 @@ const focusedGroup = () => {
 
 const groupRenderNodeId = group => 'group:' + group.id
 
-const hierarchyExpansionProgress = () => {
-  const scale = state.transform.scale
-  if (scale <= hierarchyExpansionStartScale) return 0
-  if (scale >= hierarchyExpansionEndScale) return 1
-  const progress = (scale - hierarchyExpansionStartScale) / (hierarchyExpansionEndScale - hierarchyExpansionStartScale)
-  return progress * progress * (3 - 2 * progress)
+const smoothProgress = value => {
+  const bounded = Math.max(0, Math.min(1, value))
+  return bounded * bounded * (3 - 2 * bounded)
 }
 
 const groupRenderRadius = group => {
@@ -1249,6 +1250,60 @@ const hierarchyGroupsForScale = () => {
   return state.leafGroups
 }
 
+const groupViewportCoverage = (group, viewport) => {
+  const viewportWidth = Math.max(viewport.maxX - viewport.minX, 1)
+  const viewportHeight = Math.max(viewport.maxY - viewport.minY, 1)
+  const viewportRadius = Math.max(viewportWidth, viewportHeight) / 2
+  const centerX = (viewport.minX + viewport.maxX) / 2
+  const centerY = (viewport.minY + viewport.maxY) / 2
+  const centerDistance = Math.hypot(group.x - centerX, group.y - centerY)
+  const fitCoverage = Math.min(1, group.radius / Math.max(viewportRadius, 1))
+  const centerCoverage = 1 - Math.min(1, centerDistance / Math.max(viewportRadius, 1))
+
+  return fitCoverage * 0.72 + centerCoverage * 0.28
+}
+
+const groupWithCoverage = (group, viewport) => ({
+  group,
+  coverage: groupViewportCoverage(group, viewport)
+})
+
+const updateHierarchyFocusGroup = (groups, viewport) => {
+  const current = state.hierarchyFocusGroupId ? state.groupById.get(state.hierarchyFocusGroupId) : null
+  const currentCoverage = current ? groupViewportCoverage(current, viewport) : 0
+
+  if (
+    current &&
+    state.transform.scale >= hierarchyMicroExitScale &&
+    currentCoverage >= hierarchyMicroExitCoverage
+  ) {
+    return current
+  }
+
+  const candidate = groups
+    .map(group => groupWithCoverage(group, viewport))
+    .sort((left, right) => right.coverage - left.coverage)[0]
+
+  if (
+    candidate &&
+    state.transform.scale >= hierarchyMicroEnterScale &&
+    candidate.coverage >= hierarchyMicroEnterCoverage
+  ) {
+    state.hierarchyFocusGroupId = candidate.group.id
+    return candidate.group
+  }
+
+  state.hierarchyFocusGroupId = null
+  return null
+}
+
+const hierarchyViewportProgress = (group, viewport) => {
+  const coverage = groupViewportCoverage(group, viewport)
+  const coverageProgress = (coverage - hierarchyMicroExitCoverage) / (hierarchyMicroEnterCoverage - hierarchyMicroExitCoverage)
+  const scaleProgress = (state.transform.scale - hierarchyMicroExitScale) / (hierarchyMicroEnterScale - hierarchyMicroExitScale)
+  return smoothProgress(Math.min(coverageProgress, scaleProgress))
+}
+
 const groupEdgesForRenderedGroups = (groupNodes) => {
   if (groupNodes.length <= 1) {
     return []
@@ -1298,11 +1353,10 @@ const groupEdgesForRenderedGroups = (groupNodes) => {
 
 const computeHierarchyRenderVisibility = (viewport) => {
   if (state.groups.length === 0 || state.visibleNodes.length <= 1000 || state.transform.scale >= hierarchyGroupScaleThreshold) {
+    state.hierarchyFocusGroupId = null
     return false
   }
 
-  const progress = hierarchyExpansionProgress()
-  const focus = focusedGroup()
   const groups = hierarchyGroupsForScale()
     .filter(group =>
       group.x + group.radius >= viewport.minX &&
@@ -1311,9 +1365,11 @@ const computeHierarchyRenderVisibility = (viewport) => {
       group.y - group.radius <= viewport.maxY
     )
     .slice(0, renderNodeBudget)
+  const focus = updateHierarchyFocusGroup(groups, viewport)
+  const progress = focus ? hierarchyViewportProgress(focus, viewport) : 0
   const groupNodes = groups.map(createGroupRenderNode)
 
-  if (progress <= 0.02 || !focus) {
+  if (!focus || progress <= 0.02) {
     state.renderNodes = groupNodes
     state.renderEdges = groupEdgesForRenderedGroups(groupNodes)
     return true
@@ -1327,8 +1383,11 @@ const computeHierarchyRenderVisibility = (viewport) => {
   ).map(node => interpolateNodeFromGroup(node, focus, progress))
   const childIds = new Set(childNodes.map(node => node.id))
   const childById = new Map(childNodes.map(node => [node.id, node]))
-  const visibleGroupNodes = groupNodes.filter(node => node.groupId !== focus.id || progress < 0.92)
-  const groupEdges = groupEdgesForRenderedGroups(visibleGroupNodes)
+  const isMicroView = progress >= 0.72
+  const visibleGroupNodes = isMicroView
+    ? []
+    : groupNodes.filter(node => node.groupId !== focus.id || progress < 0.92)
+  const groupEdges = isMicroView ? [] : groupEdgesForRenderedGroups(visibleGroupNodes)
   const childEdges = progress > 0.32
     ? collectVisibleEdgesForNodes(childIds).map(edge => ({
       ...edge,
@@ -2785,6 +2844,7 @@ const selectNode = (node, options = { openContent: false }) => {
       targetScale
     }
     state.lastZoomFocus = { x: node.x, y: node.y, at: performance.now() }
+    state.hierarchyFocusGroupId = node.groupId
     markRenderDirty()
     return
   }
@@ -3089,6 +3149,7 @@ const loadGraph = async (options = { reset: false }) => {
   state.graph = graph
   state.nodes = layout.nodes
   state.groups = layout.groups
+  state.hierarchyFocusGroupId = null
   state.groupById = new Map(state.groups.map(group => [group.id, group]))
   state.leafGroups = state.groups.filter(group => group.nodeIds.length > 0)
   state.nodeLeafGroupById = new Map(state.leafGroups.flatMap(group => group.nodeIds.map(nodeId => [nodeId, group])))

package/dist/application/get-graph-layout.js

@@ -1,9 +1,27 @@
 import { createHash } from 'node:crypto';
-import { stat } from 'node:fs/promises';
+import { mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
 import { createCauliflowerGraphLayout } from '../domain/graph-layout.js';
 import { indexStoragePath } from '../infrastructure/file-index.js';
 import { getGraphSummary } from './get-graph-summary.js';
 const graphLayoutCache = new Map();
+const graphLayoutStoragePath = (vaultPath, agentId) => join(vaultPath, '.brainlink', `graph-layout-${agentId?.replace(/[^a-zA-Z0-9_-]/g, '_') ?? 'all'}.json`);
+const readPersistedLayout = async (vaultPath, databaseSignature, agentId) => {
+    try {
+        const parsed = JSON.parse(await readFile(graphLayoutStoragePath(vaultPath, agentId), 'utf8'));
+        return parsed.databaseSignature === databaseSignature ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+};
+const writePersistedLayout = async (vaultPath, agentId, cached) => {
+    const target = graphLayoutStoragePath(vaultPath, agentId);
+    const temp = `${target}.tmp`;
+    await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+    await writeFile(temp, `${JSON.stringify(cached)}\n`, { encoding: 'utf8', mode: 0o600 });
+    await rename(temp, target);
+};
 const readDatabaseSignature = async (vaultPath) => {
     try {
         const info = await stat(indexStoragePath(vaultPath));
@@ -32,10 +50,24 @@ export const getGraphLayout = async (vaultPath, agentId) => {
             layout: cached.layout
         };
     }
+    const persisted = await readPersistedLayout(vaultPath, databaseSignature, agentId);
+    if (persisted) {
+        graphLayoutCache.set(cacheKey, persisted);
+        return {
+            signature: persisted.signature,
+            layout: persisted.layout
+        };
+    }
     const graph = await getGraphSummary(vaultPath, agentId);
     const signature = createGraphSignature(graph);
-    const layout = createCauliflowerGraphLayout(graph);
-    graphLayoutCache.set(cacheKey, { databaseSignature, signature, layout });
+    const rawLayout = createCauliflowerGraphLayout(graph);
+    const layout = {
+        ...rawLayout,
+        nodes: rawLayout.nodes.map((node) => ({ ...node, content: '' }))
+    };
+    const nextCache = { databaseSignature, signature, layout };
+    graphLayoutCache.set(cacheKey, nextCache);
+    await writePersistedLayout(vaultPath, agentId, nextCache);
     return {
         signature,
         layout

package/dist/application/get-graph-view.js

@@ -0,0 +1,122 @@
+import { getGraphLayout } from './get-graph-layout.js';
+const macroScale = 0.24;
+const microCoverage = 0.72;
+const nodeLimit = 1200;
+const edgeLimit = 5000;
+const inViewport = (item, input) => {
+    const radius = item.radius ?? 48;
+    return (item.x + radius >= input.x &&
+        item.x - radius <= input.x + input.width &&
+        item.y + radius >= input.y &&
+        item.y - radius <= input.y + input.height);
+};
+const groupCoverage = (group, input) => {
+    const viewportRadius = Math.max(input.width, input.height) / 2;
+    const centerX = input.x + input.width / 2;
+    const centerY = input.y + input.height / 2;
+    const centerDistance = Math.hypot(group.x - centerX, group.y - centerY);
+    const fitCoverage = Math.min(1, group.radius / Math.max(viewportRadius, 1));
+    const centerCoverage = 1 - Math.min(1, centerDistance / Math.max(viewportRadius, 1));
+    return fitCoverage * 0.72 + centerCoverage * 0.28;
+};
+const groupNode = (group) => [
+    `group:${group.id}`,
+    group.title,
+    group.x,
+    group.y,
+    group.group,
+    group.segment,
+    'group'
+];
+const realNode = (node) => [
+    node.id,
+    node.title,
+    node.x,
+    node.y,
+    node.group,
+    node.segment,
+    'node'
+];
+const descendants = (group, groupById) => group.nodeIds.length > 0
+    ? group.nodeIds
+    : group.childGroupIds.flatMap((childId) => {
+        const child = groupById.get(childId);
+        return child ? descendants(child, groupById) : [];
+    });
+const aggregateGroupEdges = (groups, edges, groupById) => {
+    const groupNodeByNodeId = new Map();
+    groups.forEach((group) => {
+        descendants(group, groupById).forEach((nodeId) => groupNodeByNodeId.set(nodeId, `group:${group.id}`));
+    });
+    const selected = new Map();
+    edges.forEach((edge) => {
+        if (!edge.target)
+            return;
+        const source = groupNodeByNodeId.get(edge.source);
+        const target = groupNodeByNodeId.get(edge.target);
+        if (!source || !target || source === target)
+            return;
+        const key = source < target ? `${source}|${target}` : `${target}|${source}`;
+        const current = selected.get(key);
+        if (current && current[2] >= edge.weight)
+            return;
+        selected.set(key, [source, target, edge.weight, edge.priority]);
+    });
+    return Array.from(selected.values()).slice(0, edgeLimit);
+};
+const realEdges = (edges, nodeIds) => edges
+    .filter((edge) => Boolean(edge.target && nodeIds.has(edge.source) && nodeIds.has(edge.target)))
+    .slice(0, edgeLimit)
+    .map((edge) => [edge.source, edge.target, edge.weight, edge.priority]);
+export const getGraphView = async (vaultPath, input) => {
+    const { signature, layout } = await getGraphLayout(vaultPath, input.agentId);
+    const groups = layout.groups ?? [];
+    const groupById = new Map(groups.map((group) => [group.id, group]));
+    if (groups.length === 0) {
+        const nodes = layout.nodes.filter((node) => inViewport(node, input)).slice(0, nodeLimit);
+        const nodeIds = new Set(nodes.map((node) => node.id));
+        return {
+            signature,
+            mode: 'flat',
+            nodes: nodes.map(realNode),
+            edges: realEdges(layout.edges, nodeIds),
+            totals: {
+                nodes: layout.nodes.length,
+                edges: layout.edges.length
+            }
+        };
+    }
+    const visibleGroups = groups.filter((group) => group.parentId === null && inViewport(group, input));
+    const focused = groups
+        .filter((group) => group.nodeIds.length > 0 && inViewport(group, input))
+        .map((group) => ({ group, coverage: groupCoverage(group, input) }))
+        .sort((left, right) => right.coverage - left.coverage)[0];
+    if (focused && input.scale >= macroScale && focused.coverage >= microCoverage) {
+        const nodeIds = new Set(focused.group.nodeIds);
+        const nodes = layout.nodes
+            .filter((node) => nodeIds.has(node.id) && inViewport(node, input))
+            .slice(0, nodeLimit);
+        const visibleNodeIds = new Set(nodes.map((node) => node.id));
+        return {
+            signature,
+            mode: 'micro',
+            nodes: nodes.map(realNode),
+            edges: realEdges(layout.edges, visibleNodeIds),
+            totals: {
+                nodes: layout.nodes.length,
+                edges: layout.edges.length
+            }
+        };
+    }
+    const groupsToRender = (visibleGroups.length > 0 ? visibleGroups : groups.filter((group) => group.parentId === null)).slice(0, nodeLimit);
+    return {
+        signature,
+        mode: 'macro',
+        nodes: groupsToRender.map(groupNode),
+        edges: aggregateGroupEdges(groupsToRender, layout.edges, groupById),
+        totals: {
+            nodes: layout.nodes.length,
+            edges: layout.edges.length
+        }
+    };
+};

package/dist/application/server/routes.js

@@ -3,6 +3,7 @@ import { buildContextPackage } from '../build-context.js';
 import { getGraph } from '../get-graph.js';
 import { getGraphNode } from '../get-graph-node.js';
 import { getGraphLayout } from '../get-graph-layout.js';
+import { getGraphView } from '../get-graph-view.js';
 import { listAgents } from '../list-agents.js';
 import { listBacklinks, listLinks } from '../list-links.js';
 import { searchGraphNodeIds } from '../search-graph-node-ids.js';
@@ -52,6 +53,10 @@ const sameEntityTag = (candidate, signature) => {
     return decodeEntityTag(candidate) === signature;
 };
 const readAgentQuery = (url) => url.searchParams.get('agent') ?? undefined;
+const parseNumber = (value, fallback) => {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : fallback;
+};
 const compactGraphLayoutThreshold = 12_000;
 const compactGraphLayoutEdgeLimit = 60_000;
 const compactGraphLayoutEdgeLimitFor = (nodeCount) => {
@@ -182,6 +187,16 @@ export const route = async (request, url, vaultPath) => {
             }
         };
     }
+    if (isReadMethod(request) && url.pathname === '/api/graph-view') {
+        return createResponse(createJsonResponse(await getGraphView(vaultPath, {
+            x: parseNumber(url.searchParams.get('x'), -1000),
+            y: parseNumber(url.searchParams.get('y'), -1000),
+            width: parseNumber(url.searchParams.get('w'), 2000),
+            height: parseNumber(url.searchParams.get('h'), 2000),
+            scale: parseNumber(url.searchParams.get('scale'), 1),
+            agentId: readAgentQuery(url)
+        })), 200, contentTypes['.json']);
+    }
     if (isReadMethod(request) && url.pathname === '/api/graph-node') {
         const id = url.searchParams.get('id')?.trim() ?? '';
         if (!id) {

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

@@ -17,6 +17,7 @@ import { defaultBrainlinkConfig, sanitizeSearchMode } from '../../infrastructure
 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 { addVolatileMemory, clearVolatileMemory } from '../../infrastructure/volatile-memory.js';
 import { installAgentIntegration } from './agent-commands.js';
 import { parsePositiveInteger, print, resolveOptions } from '../runtime.js';
 const resolveAddContent = (options) => {
@@ -729,6 +730,29 @@ export const registerWriteCommands = (program) => {
             return `${summary}${indexMessage}${dryRunMessage}`;
         });
     });
+    program
+        .command('volatile')
+        .option('-c, --content <content>', 'temporary memory content to add')
+        .option('--ttl <minutes>', 'time-to-live in minutes', '240')
+        .option('--tag <tag...>', 'volatile memory tag')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('--clear', 'clear volatile memory for the current agent namespace')
+        .option('--json', 'print machine-readable JSON')
+        .description('add or clear temporary agent-decided memory')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        if (options.clear) {
+            const cleared = await clearVolatileMemory(resolved.vault, resolved.agent);
+            print(options.json, { cleared, agent: resolved.agent ?? 'shared' }, () => `Cleared ${cleared} volatile memories.`);
+            return;
+        }
+        if (!options.content || options.content.trim().length === 0) {
+            throw new Error('Use --content to add volatile memory, or --clear to remove it.');
+        }
+        const entry = await addVolatileMemory(resolved.vault, options.content, resolved.agent ?? 'shared', parsePositiveInteger(options.ttl ?? '240', 240), options.tag ?? []);
+        print(options.json, { entry }, () => `Stored volatile memory until ${entry.expiresAt}.`);
+    });
     program
         .command('add')
         .argument('<title>', 'note title')

package/dist/domain/context.js

@@ -76,6 +76,7 @@ export const formatContextPackage = (query, sections) => {
         section.tags.length > 0 ? `Tags: ${section.tags.map((tag) => `#${tag}`).join(' ')}` : null,
         `Score: ${section.score.toFixed(3)}`,
         `Mode: ${section.searchMode}`,
+        section.volatile ? `Volatile: true${section.expiresAt ? `, expires ${section.expiresAt}` : ''}` : null,
         '',
         section.content
     ]

package/dist/infrastructure/volatile-memory.js

@@ -0,0 +1,100 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+export const volatileMemoryStoragePath = (vaultPath) => join(vaultPath, '.brainlink', 'volatile.json');
+const emptyStore = () => ({
+    version: 1,
+    entries: []
+});
+const normalizeToken = (value) => value
+    .normalize('NFKD')
+    .replace(/\p{Diacritic}/gu, '')
+    .toLowerCase();
+const tokens = (value) => value
+    .match(/[\p{L}\p{N}_-]+/gu)
+    ?.map(normalizeToken)
+    .filter((token) => token.length > 1) ?? [];
+const readStore = async (vaultPath) => {
+    try {
+        const parsed = JSON.parse(await readFile(volatileMemoryStoragePath(vaultPath), 'utf8'));
+        return {
+            version: 1,
+            entries: Array.isArray(parsed.entries) ? parsed.entries.filter(isEntry) : []
+        };
+    }
+    catch {
+        return emptyStore();
+    }
+};
+const writeStore = async (vaultPath, store) => {
+    const target = volatileMemoryStoragePath(vaultPath);
+    const temp = `${target}.tmp`;
+    await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+    await writeFile(temp, `${JSON.stringify(store, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    await rename(temp, target);
+};
+const isEntry = (value) => {
+    const record = value;
+    return Boolean(record &&
+        typeof record.id === 'string' &&
+        typeof record.agentId === 'string' &&
+        typeof record.content === 'string' &&
+        typeof record.createdAt === 'string' &&
+        typeof record.expiresAt === 'string' &&
+        Array.isArray(record.tags));
+};
+const activeEntries = (entries, now = Date.now()) => entries.filter((entry) => Date.parse(entry.expiresAt) > now);
+const scoreEntry = (entry, query) => {
+    const queryTokens = tokens(query);
+    if (queryTokens.length === 0) {
+        return 1;
+    }
+    const haystack = normalizeToken([entry.content, entry.tags.join(' ')].join(' '));
+    return queryTokens.reduce((score, token) => score + (haystack.includes(token) ? 1 : 0), 0);
+};
+export const addVolatileMemory = async (vaultPath, content, agentId = 'shared', ttlMinutes = 240, tags = []) => {
+    const now = new Date();
+    const entry = {
+        id: `volatile-${now.getTime()}-${Math.random().toString(36).slice(2, 10)}`,
+        agentId,
+        content,
+        createdAt: now.toISOString(),
+        expiresAt: new Date(now.getTime() + Math.max(1, ttlMinutes) * 60_000).toISOString(),
+        source: 'agent',
+        tags
+    };
+    const store = await readStore(vaultPath);
+    await writeStore(vaultPath, {
+        version: 1,
+        entries: [...activeEntries(store.entries), entry]
+    });
+    return entry;
+};
+export const searchVolatileMemory = async (vaultPath, query, limit, agentId, mode = 'hybrid') => {
+    const store = await readStore(vaultPath);
+    const entries = activeEntries(store.entries)
+        .filter((entry) => (agentId ? entry.agentId === agentId : true))
+        .map((entry) => ({ entry, score: scoreEntry(entry, query) }))
+        .filter(({ score }) => score > 0)
+        .sort((left, right) => right.score - left.score || right.entry.createdAt.localeCompare(left.entry.createdAt))
+        .slice(0, Math.max(0, limit));
+    if (entries.length !== store.entries.length) {
+        await writeStore(vaultPath, { version: 1, entries: activeEntries(store.entries) });
+    }
+    return entries.map(({ entry, score }) => ({
+        title: 'Volatile Memory',
+        path: `volatile://${entry.id}`,
+        content: entry.content,
+        score,
+        searchMode: mode,
+        tags: ['volatile', ...entry.tags],
+        volatile: true,
+        expiresAt: entry.expiresAt
+    }));
+};
+export const clearVolatileMemory = async (vaultPath, agentId) => {
+    const store = await readStore(vaultPath);
+    const active = activeEntries(store.entries);
+    const kept = agentId ? active.filter((entry) => entry.agentId !== agentId) : [];
+    await writeStore(vaultPath, { version: 1, entries: kept });
+    return active.length - kept.length;
+};

package/dist/mcp/server.js

@@ -2,7 +2,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { addNoteInputSchema, addFileInputSchema, addFileTool, addNoteTool, dedupeInputSchema, dedupeResolveInputSchema, dedupeResolveTool, dedupeTool, brokenLinksInputSchema, brokenLinksTool, bootstrapInputSchema, bootstrapTool, contextInputSchema, contextTool, graphInputSchema, graphTool, indexInputSchema, indexTool, orphansInputSchema, orphansTool, policyInputSchema, policyTool, recommendationsInputSchema, recommendationsTool, searchInputSchema, searchTool, statsInputSchema, statsTool, syncInputSchema, syncTool, validateInputSchema, validateTool } from './tools.js';
+import { addNoteInputSchema, addFileInputSchema, addFileTool, addNoteTool, volatileAddInputSchema, volatileAddTool, volatileClearInputSchema, volatileClearTool, dedupeInputSchema, dedupeResolveInputSchema, dedupeResolveTool, dedupeTool, brokenLinksInputSchema, brokenLinksTool, bootstrapInputSchema, bootstrapTool, contextInputSchema, contextTool, graphInputSchema, graphTool, indexInputSchema, indexTool, orphansInputSchema, orphansTool, policyInputSchema, policyTool, recommendationsInputSchema, recommendationsTool, searchInputSchema, searchTool, statsInputSchema, statsTool, syncInputSchema, syncTool, validateInputSchema, validateTool } from './tools.js';
 const readPackageVersion = () => {
     const packagePath = join(dirname(fileURLToPath(import.meta.url)), '../../package.json');
     const metadata = JSON.parse(readFileSync(packagePath, 'utf8'));
@@ -55,6 +55,16 @@ export const createBrainlinkMcpServer = () => {
         description: 'Write durable Markdown memory, then reindex the vault. Include explicit [[wiki links]] for connected graph memory. Add priority markers near links, such as priority: high, #important or #critical, when a relationship should be weighted higher.',
         inputSchema: addNoteInputSchema
     }, addNoteTool);
+    server.registerTool('brainlink_volatile_add', {
+        title: 'Add Volatile Brainlink Memory',
+        description: 'Write temporary agent-decided memory with TTL. Use for transient task state without polluting durable Markdown memory.',
+        inputSchema: volatileAddInputSchema
+    }, volatileAddTool);
+    server.registerTool('brainlink_volatile_clear', {
+        title: 'Clear Volatile Brainlink Memory',
+        description: 'Clear active volatile memory for the current vault/agent namespace.',
+        inputSchema: volatileClearInputSchema
+    }, volatileClearTool);
     server.registerTool('brainlink_add_file', {
         title: 'Ingest Markdown File',
         description: 'Read a local markdown/text file and ingest it as a Brainlink note. Reindex defaults to true.',

package/dist/mcp/tools.js

@@ -11,6 +11,7 @@ import { searchKnowledge } from '../application/search-knowledge.js';
 import { resolveAgentRuntimeDefaults, sanitizeSearchMode } from '../infrastructure/config.js';
 import { loadBrainlinkConfig } from '../infrastructure/config.js';
 import { assertVaultAllowed } from '../infrastructure/file-system-vault.js';
+import { addVolatileMemory, clearVolatileMemory } from '../infrastructure/volatile-memory.js';
 import { getBootstrapPolicy, getBootstrapSessionStatus, getContextSessionStatus, setBootstrapPolicy, touchBootstrapSession, touchContextSession } from '../infrastructure/session-state.js';
 const positiveInteger = (fallback) => z
     .number()
@@ -237,6 +238,20 @@ export const addNoteInputSchema = {
     allowSensitive: z.boolean().optional().default(false).describe('Allow content that looks like a secret.'),
     autoIndex: z.boolean().optional().default(true).describe('Reindex vault after writing note.')
 };
+export const volatileAddInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    content: z
+        .string()
+        .min(1)
+        .describe('Temporary agent-decided memory. Use for current task state, hypotheses, transient user preferences and unconfirmed findings.'),
+    ttlMinutes: optionalPositiveInteger().describe('Minutes before this volatile memory expires. Defaults to 240.'),
+    tags: z.array(z.string()).optional().default([]).describe('Optional tags for volatile retrieval.')
+};
+export const volatileClearInputSchema = {
+    ...vaultInput,
+    ...agentInput
+};
 export const addFileInputSchema = {
     ...vaultInput,
     ...agentInput,
@@ -401,6 +416,25 @@ export const addNoteTool = async (input) => {
         ...(index ? { index } : {})
     });
 };
+export const volatileAddTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const entry = await addVolatileMemory(context.vault, input.content, context.agent ?? 'shared', input.ttlMinutes ?? 240, input.tags);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        volatile: true,
+        entry
+    });
+};
+export const volatileClearTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const cleared = await clearVolatileMemory(context.vault, context.agent);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        cleared
+    });
+};
 export const addFileTool = async (input) => {
     const context = await resolveExecutionContext(input);
     const content = await readFile(input.filePath, 'utf8');

package/docs/AGENT_USAGE.md

@@ -607,7 +607,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). Vaults above 1000 notes also expose stable hierarchy groups of up to 1000 direct nodes, with recursive parent groups when a level exceeds 1000 groups; zoom-out renders those groups as normal graph nodes, and zoom-in expands the focused group into its child graph without drawing a background glow layer.
+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). Vaults above 1000 notes also expose stable hierarchy groups of up to 1000 direct nodes, with recursive parent groups when a level exceeds 1000 groups; zoom-out renders those groups as normal graph nodes, zoom-in expands a group only after it is framed in the viewport, and micro view renders only the focused subgraph until zoom-out restores sibling groups.
 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:
@@ -670,6 +670,8 @@ Available MCP tools:
 - `brainlink_resolve_duplicate`
 - `brainlink_add_note`
 - `brainlink_add_file`
+- `brainlink_volatile_add`
+- `brainlink_volatile_clear`
 - `brainlink_index`
 - `brainlink_stats`
 - `brainlink_validate`
@@ -689,6 +691,7 @@ MCP clients can pass `vault` and `agent` arguments per tool call. Set `BRAINLINK
 
 `brainlink_graph` returns weighted edges. Agents should prefer higher `weight` and stronger `priority` when deciding which related notes matter most.
 `brainlink_add_note` and `brainlink_add_file` return `writeConnectivity` metadata and guarantee at least one edge for new notes.
+Agents should use `brainlink_volatile_add` for temporary task state, hypotheses, local execution details and unconfirmed findings. Volatile memory is included in `brainlink_context` with `Volatile: true`, expires by TTL and does not create durable Markdown notes or graph edges.
 
 ```bash
 export BRAINLINK_ALLOWED_VAULTS="/absolute/path/to/project-vault"
@@ -699,6 +702,7 @@ export BRAINLINK_ALLOWED_VAULTS="/absolute/path/to/project-vault"
 ```txt
 GET  /api/graph
 GET  /api/graph-layout
+GET  /api/graph-view?x=<x>&y=<y>&w=<width>&h=<height>&scale=<scale>
 GET  /api/graph-node?id=<node-id>
 GET  /api/graph-filter?q=<query>&limit=<n>
 GET  /api/search?q=<query>&limit=10&mode=hybrid

package/package.json

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