@andespindola/brainlink 0.1.0-beta.121 → 0.1.0-beta.123

package/README.md

@@ -84,11 +84,11 @@ Legacy `.jsonl.gz` packs are upgraded to `.blpk` automatically on first search/c
 - Graph renderer optimized for large datasets with viewport-driven node culling and edge lookup by visible nodes.
 - Canvas graph rendering uses the same batched node and edge pipeline for every graph size, reducing per-frame draw calls while keeping selected and hovered items highlighted.
 - WebGL acceleration is used when available for dense node and edge drawing, with Canvas 2D preserved as the interaction and fallback layer.
-- Graph rendering keeps the flat node scene and adds stable hierarchical groups for vaults above 1000 notes, with recursive parent groups when a level itself exceeds 1000 groups.
+- Graph rendering keeps the flat node scene and adds stable hierarchical mesh groups for vaults above 1000 notes, with every visible graph level capped at 1000 nodes and recursive parent groups when a level itself exceeds 1000 groups.
 - 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 a group only after it is framed in the viewport, progressively hiding sibling groups in micro view.
+- Zoomed-out graph LOD renders hierarchy groups as normal mesh 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 framed node into its child graph, micro view renders only that focused subgraph, and zoom-out restores sibling groups
+- large graph LOD keeps a recursive graph-of-graphs mesh model: zoom-out shows one level capped at 1000 group nodes, zoom-in expands the framed node into its child graph capped at 1000 nodes, 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

@@ -4,7 +4,7 @@ const ctx = canvas.getContext('2d')
 const largeGraphNodeThreshold = 4000
 const massiveGraphNodeThreshold = 20000
 const largeGraphEdgeRenderLimit = 120000
-const renderNodeBudget = 900
+const renderNodeBudget = 1000
 const zoomedMassiveRenderNodeBudget = 2200
 const massiveOverviewRenderNodeBudget = 1800
 const massiveOverviewScaleThreshold = 0.065
@@ -1509,7 +1509,8 @@ const buildMeshEdgesForNodes = (nodes, existingEdges) => {
 }
 
 const withMeshEdges = (nodes, edges) => {
-  if (nodes.length === 0 || state.visibleNodes.length <= largeGraphNodeThreshold || state.transform.scale < meshEdgeScaleThreshold) {
+  const isHierarchyGraphLevel = state.groups.length > 0 && (state.visibleNodes.length > 1000 || state.hierarchyFocusGroupId)
+  if (nodes.length === 0 || !isHierarchyGraphLevel || state.transform.scale < meshEdgeScaleThreshold) {
     return edges
   }
 

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,151 @@
+import { getGraphLayout } from './get-graph-layout.js';
+const macroScale = 0.24;
+const microCoverage = 0.72;
+const nodeLimit = 1000;
+const edgeLimit = 5000;
+const meshEdgeLimit = 2500;
+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]);
+const edgePairKey = (left, right) => left < right ? `${left}|${right}` : `${right}|${left}`;
+const meshEdges = (nodes, existingEdges) => {
+    if (nodes.length < 2) {
+        return [];
+    }
+    const existing = new Set(existingEdges.map((edge) => edgePairKey(edge[0], edge[1])));
+    const selected = [];
+    const selectedKeys = new Set();
+    const maxNeighbors = nodes.length > 500 ? 2 : 3;
+    const byX = [...nodes].sort((left, right) => left[2] - right[2] || left[3] - right[3] || left[0].localeCompare(right[0]));
+    for (let index = 0; index < nodes.length && selected.length < meshEdgeLimit; index += 1) {
+        const node = byX[index];
+        const candidates = byX.slice(index + 1, index + 1 + maxNeighbors);
+        candidates.forEach((candidate) => {
+            const key = edgePairKey(node[0], candidate[0]);
+            if (existing.has(key) || selectedKeys.has(key) || selected.length >= meshEdgeLimit) {
+                return;
+            }
+            selectedKeys.add(key);
+            selected.push([node[0], candidate[0], 1, 'low']);
+        });
+    }
+    return selected;
+};
+const withMeshEdges = (nodes, edges) => [...edges, ...meshEdges(nodes, edges)].slice(0, edgeLimit);
+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));
+        const viewNodes = nodes.map(realNode);
+        return {
+            signature,
+            mode: 'flat',
+            nodes: viewNodes,
+            edges: withMeshEdges(viewNodes, 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));
+        const viewNodes = nodes.map(realNode);
+        return {
+            signature,
+            mode: 'micro',
+            nodes: viewNodes,
+            edges: withMeshEdges(viewNodes, 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);
+    const viewNodes = groupsToRender.map(groupNode);
+    return {
+        signature,
+        mode: 'macro',
+        nodes: viewNodes,
+        edges: withMeshEdges(viewNodes, 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, 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.
+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 mesh groups of up to 1000 direct nodes, with recursive parent groups when a level exceeds 1000 groups; zoom-out renders those groups as normal mesh 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.121",
+  "version": "0.1.0-beta.123",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",