@andespindola/brainlink 0.1.0-beta.163 → 0.1.0-beta.165

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

@@ -369,28 +369,28 @@ const parseColor = (hex) => {
 }
 
 const graphTheme = {
-  node: parseColor('#4c8eda'),
-  nodeCluster: parseColor('#2f6fb4'),
-  nodeHighlight: parseColor('#f2b441'),
-  nodeSelected: parseColor('#172033'),
+  node: parseColor('#5aa8ff'),
+  nodeCluster: parseColor('#3f7fbd'),
+  nodeHighlight: parseColor('#ffcb67'),
+  nodeSelected: parseColor('#edf4ff'),
   nodePalette: [
-    parseColor('#4c8eda'),
-    parseColor('#65b96e'),
-    parseColor('#f0a33a'),
-    parseColor('#d95f8d'),
-    parseColor('#8d72d9'),
-    parseColor('#55bfc4'),
-    parseColor('#ec6b56'),
-    parseColor('#9aa6b2'),
-    parseColor('#b78255'),
-    parseColor('#6f9fd8')
+    parseColor('#5aa8ff'),
+    parseColor('#5ecf92'),
+    parseColor('#ffb65c'),
+    parseColor('#ff7dac'),
+    parseColor('#a88fff'),
+    parseColor('#59d0dd'),
+    parseColor('#ff8f6a'),
+    parseColor('#a4b3c3'),
+    parseColor('#c9945f'),
+    parseColor('#7cb6ff')
   ],
-  edge: [0.23, 0.31, 0.42, 0.18],
-  edgeHeavy: [0.23, 0.31, 0.42, 0.34],
-  clear: parseColor('#f6f8fb')
+  edge: [0.59, 0.71, 0.83, 0.14],
+  edgeHeavy: [0.59, 0.71, 0.83, 0.3],
+  clear: parseColor('#08131d')
 }
 
-const segmentPalette = ['#4c8eda', '#65b96e', '#f0a33a', '#d95f8d', '#8d72d9', '#55bfc4', '#ec6b56', '#9aa6b2', '#b78255', '#6f9fd8']
+const segmentPalette = ['#5aa8ff', '#5ecf92', '#ffb65c', '#ff7dac', '#a88fff', '#59d0dd', '#ff8f6a', '#a4b3c3', '#c9945f', '#7cb6ff']
 
 const segmentColorIndex = (segment) => {
   const value = String(segment || '')
@@ -402,6 +402,8 @@ const segmentColorIndex = (segment) => {
 }
 
 const segmentColor = (segment) => segmentPalette[segmentColorIndex(segment)] || segmentPalette[0]
+const nodeKind = (node) => node?.[6] === 'cluster' ? 'cluster' : 'node'
+const isRealGraphNode = (node) => nodeKind(node) === 'node'
 
 const clampScale = (scale) => Math.max(zoomRange.min, Math.min(zoomRange.max, scale))
 
@@ -543,7 +545,7 @@ const drawFallback = () => {
   canvas.width = Math.floor(width * ratio)
   canvas.height = Math.floor(height * ratio)
   ctx2dFallback.setTransform(ratio, 0, 0, ratio, 0, 0)
-  ctx2dFallback.fillStyle = '#f6f8fb'
+  ctx2dFallback.fillStyle = '#08131d'
   ctx2dFallback.fillRect(0, 0, width, height)
 
   const nodes = Array.isArray(state.chunk.nodes) ? state.chunk.nodes : []
@@ -553,7 +555,7 @@ const drawFallback = () => {
     nodeById.set(nodes[i][0], nodes[i])
   }
 
-  ctx2dFallback.strokeStyle = 'rgba(59,79,108,0.18)'
+  ctx2dFallback.strokeStyle = 'rgba(151,181,212,0.18)'
   ctx2dFallback.lineWidth = 1
   for (let i = 0; i < edges.length; i += 1) {
     const edge = edges[i]
@@ -576,12 +578,12 @@ const drawFallback = () => {
     const radius = Math.max(2.4, Math.min(14, 4 + node[7] * 0.55))
 
     ctx2dFallback.beginPath()
-    ctx2dFallback.fillStyle = selected ? '#ffffff' : color
+    ctx2dFallback.fillStyle = selected ? '#edf4ff' : color
     ctx2dFallback.arc(p.x, p.y, radius, 0, Math.PI * 2)
     ctx2dFallback.fill()
   }
 
-  ctx2dFallback.fillStyle = '#172033'
+  ctx2dFallback.fillStyle = '#97a9bd'
   ctx2dFallback.font = '12px Inter, system-ui, sans-serif'
   ctx2dFallback.textAlign = 'center'
   ctx2dFallback.fillText('Fallback canvas mode', Math.max(width, 320) / 2, 24)
@@ -670,6 +672,28 @@ const updateNodePositionInChunk = (nodeId, x, y) => {
   updateGraphOverlays()
 }
 
+const focusNodeInViewport = (nodeId, nextScale = null) => {
+  const node = nodeByIdFromChunk().get(nodeId)
+  if (!node) {
+    return false
+  }
+
+  const x = Number(node[2])
+  const y = Number(node[3])
+  if (!Number.isFinite(x) || !Number.isFinite(y)) {
+    return false
+  }
+
+  if (Number.isFinite(nextScale)) {
+    state.camera.scale = clampScale(Number(nextScale))
+  }
+  state.camera.x = state.viewport.width / 2 - x * state.camera.scale
+  state.camera.y = state.viewport.height / 2 - y * state.camera.scale
+  updateWorkerCamera()
+  scheduleChunkFetch()
+  return true
+}
+
 const showTooltip = (node, pointer) => {
   if (!elements.tooltip || !node) {
     return
@@ -743,7 +767,7 @@ const drawMiniMap = () => {
   miniMap.height = Math.floor(height * ratio)
   ctx.setTransform(ratio, 0, 0, ratio, 0, 0)
   ctx.clearRect(0, 0, width, height)
-  ctx.fillStyle = 'rgba(255, 255, 255, 0.88)'
+  ctx.fillStyle = 'rgba(8, 19, 29, 0.88)'
   ctx.fillRect(0, 0, width, height)
 
   const xs = nodes.map((node) => Number(node[2])).filter(Number.isFinite)
@@ -763,7 +787,7 @@ const drawMiniMap = () => {
   })
   state.miniMapView = { minX, minY, scale, offsetX, offsetY, width, height }
 
-  ctx.fillStyle = 'rgba(76, 142, 218, 0.62)'
+  ctx.fillStyle = 'rgba(90, 168, 255, 0.62)'
   nodes.forEach((node) => {
     const point = toMini(Number(node[2]), Number(node[3]))
     ctx.fillRect(point.x - 1, point.y - 1, 2, 2)
@@ -773,7 +797,7 @@ const drawMiniMap = () => {
   const worldBottomRight = screenToWorld(state.viewport.width, state.viewport.height)
   const topLeft = toMini(Math.min(worldTopLeft.x, worldBottomRight.x), Math.min(worldTopLeft.y, worldBottomRight.y))
   const bottomRight = toMini(Math.max(worldTopLeft.x, worldBottomRight.x), Math.max(worldTopLeft.y, worldBottomRight.y))
-  ctx.strokeStyle = 'rgba(11, 111, 203, 0.86)'
+  ctx.strokeStyle = 'rgba(90, 168, 255, 0.86)'
   ctx.lineWidth = 1
   ctx.strokeRect(topLeft.x, topLeft.y, Math.max(3, bottomRight.x - topLeft.x), Math.max(3, bottomRight.y - topLeft.y))
 }
@@ -1128,11 +1152,28 @@ const pickFallbackNodeId = (screenX, screenY) => {
   return typeof node?.[0] === 'string' ? node[0] : ''
 }
 
+const handlePickedNode = (node) => {
+  const nodeId = typeof node?.id === 'string' ? node.id : typeof node?.[0] === 'string' ? node[0] : ''
+  if (!nodeId) {
+    return
+  }
+
+  const kind = typeof node?.kind === 'string' ? node.kind : nodeKind(node)
+  if (kind === 'cluster') {
+    const currentScale = state.camera.scale
+    const targetScale = currentScale < 0.22 ? 0.28 : Math.min(1.1, currentScale * 1.6)
+    focusNodeInViewport(nodeId, targetScale)
+    return
+  }
+
+  loadNodeDetails(nodeId).catch((error) => console.error(error))
+}
+
 const pickAt = (screenX, screenY) => {
   if (state.rendererMode === 'fallback') {
-    const nodeId = pickFallbackNodeId(screenX, screenY)
-    if (nodeId) {
-      loadNodeDetails(nodeId).catch((error) => console.error(error))
+    const node = pickFallbackNode(screenX, screenY)
+    if (node) {
+      handlePickedNode(node)
     }
     return
   }
@@ -1170,6 +1211,19 @@ const resolvePointer = (event) => {
 
 const setupInput = () => {
   const dragActivationDistance = 6
+  const resetPointerState = (pointerId = null) => {
+    state.pointer.down = false
+    state.pointer.dragging = false
+    state.pointer.dragNodeId = ''
+    canvas.classList.remove('is-node-dragging')
+    if (pointerId !== null) {
+      try {
+        if (canvas.hasPointerCapture(pointerId)) {
+          canvas.releasePointerCapture(pointerId)
+        }
+      } catch {}
+    }
+  }
 
   canvas.addEventListener('wheel', (event) => {
     event.preventDefault()
@@ -1180,9 +1234,10 @@ const setupInput = () => {
   }, { passive: false })
 
   canvas.addEventListener('pointerdown', (event) => {
+    event.preventDefault()
     const pointer = resolvePointer(event)
     const candidateNode = pickFallbackNode(pointer.x, pointer.y)
-    const candidateNodeId = candidateNode?.[6] === 'node' && typeof candidateNode?.[0] === 'string' ? candidateNode[0] : ''
+    const candidateNodeId = isRealGraphNode(candidateNode) && typeof candidateNode?.[0] === 'string' ? candidateNode[0] : ''
     const candidateX = Number(candidateNode?.[2])
     const candidateY = Number(candidateNode?.[3])
     const world = screenToWorld(pointer.x, pointer.y)
@@ -1200,10 +1255,15 @@ const setupInput = () => {
     state.pointer.nodeStartY = candidateNodeId && Number.isFinite(candidateY) ? candidateY : 0
     state.pointer.worldAnchorX = world.x
     state.pointer.worldAnchorY = world.y
-    canvas.setPointerCapture(event.pointerId)
+    try {
+      canvas.setPointerCapture(event.pointerId)
+    } catch {}
   })
 
   canvas.addEventListener('pointermove', (event) => {
+    if (state.pointer.down) {
+      event.preventDefault()
+    }
     const pointer = resolvePointer(event)
 
     if (state.pointer.down) {
@@ -1241,7 +1301,7 @@ const setupInput = () => {
     }
 
     const hovered = pickFallbackNode(pointer.x, pointer.y)
-    const hoveredId = hovered?.[6] === 'node' && typeof hovered?.[0] === 'string' ? hovered[0] : ''
+    const hoveredId = isRealGraphNode(hovered) && typeof hovered?.[0] === 'string' ? hovered[0] : ''
     if (state.hoveredNodeId !== hoveredId) {
       state.hoveredNodeId = hoveredId
       canvas.classList.toggle('is-node-hover', Boolean(hoveredId))
@@ -1260,11 +1320,7 @@ const setupInput = () => {
     const shouldPick = !state.pointer.dragging && distanceFromStart < dragActivationDistance
     const shouldRefreshAfterDrag = state.pointer.dragging
     const shouldPersistNodePosition = state.pointer.dragging && Boolean(state.pointer.dragNodeId)
-    state.pointer.down = false
-    state.pointer.dragging = false
-    canvas.classList.remove('is-node-dragging')
-    state.pointer.dragNodeId = ''
-    canvas.releasePointerCapture(event.pointerId)
+    resetPointerState(event.pointerId)
 
     if (shouldPick) {
       pickAt(pointer.x, pointer.y)
@@ -1287,6 +1343,16 @@ const setupInput = () => {
     updateGraphOverlays()
   })
 
+  canvas.addEventListener('pointercancel', (event) => {
+    resetPointerState(event.pointerId)
+    hideTooltip()
+    updateGraphOverlays()
+  })
+
+  canvas.addEventListener('lostpointercapture', () => {
+    resetPointerState()
+  })
+
   elements.miniMap.addEventListener('click', (event) => {
     if (!state.miniMapView) {
       return
@@ -1507,7 +1573,7 @@ const setupRenderWorker = () => {
 
       if (payload.type === 'pick-result') {
         if (payload.node && typeof payload.node.id === 'string' && payload.node.id.length > 0) {
-          loadNodeDetails(payload.node.id).catch((error) => console.error(error))
+          handlePickedNode(payload.node)
         }
         return
       }

package/dist/application/server/routes.js

@@ -11,7 +11,7 @@ import { listAgents } from '../list-agents.js';
 import { listBacklinks, listLinks } from '../list-links.js';
 import { searchGraphNodeIds } from '../search-graph-node-ids.js';
 import { searchKnowledge } from '../search-knowledge.js';
-import { loadBrainlinkConfig, sanitizeSearchMode } from '../../infrastructure/config.js';
+import { loadBrainlinkConfig, resolveAgentRuntimeDefaults, sanitizeContextStrategy, sanitizeSearchMode } from '../../infrastructure/config.js';
 import { createClientCss } from '../frontend/client-css.js';
 import { createClientHtml } from '../frontend/client-html.js';
 import { createClientJs } from '../frontend/client-js.js';
@@ -20,12 +20,22 @@ import { createClientRenderWorkerJs } from '../frontend/client-render-worker-js.
 import { contentTypes, createJsonResponse, isReadMethod, parsePositiveInteger } from './http.js';
 const readSearchMode = async (url) => {
     const config = await loadBrainlinkConfig();
-    return sanitizeSearchMode(url.searchParams.get('mode'), config.defaultSearchMode);
+    const defaults = resolveAgentRuntimeDefaults(config, readAgentQuery(url));
+    return sanitizeSearchMode(url.searchParams.get('mode'), defaults.defaultSearchMode);
+};
+const readContextStrategy = async (url) => {
+    const config = await loadBrainlinkConfig();
+    const defaults = resolveAgentRuntimeDefaults(config, readAgentQuery(url));
+    return sanitizeContextStrategy(url.searchParams.get('strategy'), defaults.defaultContextStrategy);
 };
 const hasInvalidSearchMode = (url) => {
     const mode = url.searchParams.get('mode');
     return mode !== null && !['fts', 'semantic', 'hybrid'].includes(mode);
 };
+const hasInvalidContextStrategy = (url) => {
+    const strategy = url.searchParams.get('strategy');
+    return strategy !== null && !['rag', 'cag', 'auto'].includes(strategy);
+};
 const createResponse = (body, statusCode = 200, contentType = 'text/plain; charset=utf-8') => ({
     body,
     statusCode,
@@ -370,10 +380,14 @@ export const route = async (request, url, vaultPath) => {
         const limit = parsePositiveInteger(url.searchParams.get('limit'), 12);
         const tokens = parsePositiveInteger(url.searchParams.get('tokens'), 2000);
         const mode = await readSearchMode(url);
+        const strategy = await readContextStrategy(url);
         if (hasInvalidSearchMode(url)) {
             return createResponse(createJsonResponse({ error: 'Invalid mode. Use fts, semantic or hybrid.' }), 400, contentTypes['.json']);
         }
-        return createResponse(createJsonResponse(await buildContextPackage(vaultPath, query, limit, tokens, readAgentQuery(url), mode)), 200, contentTypes['.json']);
+        if (hasInvalidContextStrategy(url)) {
+            return createResponse(createJsonResponse({ error: 'Invalid strategy. Use rag, cag or auto.' }), 400, contentTypes['.json']);
+        }
+        return createResponse(createJsonResponse(await buildContextPackage(vaultPath, query, limit, tokens, readAgentQuery(url), mode, strategy)), 200, contentTypes['.json']);
     }
     if (isReadMethod(request) && url.pathname === '/api/links') {
         return createResponse(createJsonResponse({ links: await listLinks(vaultPath, readAgentQuery(url)) }), 200, contentTypes['.json']);

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

@@ -1,10 +1,11 @@
 import { getBrokenLinksReport, getExtendedStats, getOrphansReport, getStats, validateVault } from '../../application/analyze-vault.js';
-import { buildContextPackage } from '../../application/build-context.js';
+import { buildContextPackage, readContextDataSignature } from '../../application/build-context.js';
 import { getGraph } from '../../application/get-graph.js';
 import { listAgents } from '../../application/list-agents.js';
 import { listBacklinks, listLinks } from '../../application/list-links.js';
 import { searchKnowledge } from '../../application/search-knowledge.js';
-import { sanitizeSearchMode } from '../../infrastructure/config.js';
+import { sanitizeContextStrategy, sanitizeSearchMode } from '../../infrastructure/config.js';
+import { clearContextPacks, listContextPacks } from '../../infrastructure/context-packs.js';
 import { parsePositiveInteger, print, resolveOptions } from '../runtime.js';
 export const registerReadCommands = (program) => {
     program
@@ -61,14 +62,49 @@ export const registerReadCommands = (program) => {
         .option('-l, --limit <limit>', 'maximum search results before context selection')
         .option('-t, --tokens <tokens>', 'maximum estimated context tokens')
         .option('-m, --mode <mode>', 'search mode: fts, semantic or hybrid')
+        .option('--strategy <strategy>', 'context strategy: rag, cag or auto')
         .option('--json', 'print machine-readable JSON')
         .description('build a compact context package for an agent')
         .action(async (query, options) => {
         const resolved = await resolveOptions(options);
         const mode = sanitizeSearchMode(options.mode, resolved.defaults.defaultSearchMode);
-        const contextPackage = await buildContextPackage(resolved.vault, query, parsePositiveInteger(options.limit ?? String(resolved.defaults.defaultSearchLimit), resolved.defaults.defaultSearchLimit), parsePositiveInteger(options.tokens ?? String(resolved.defaults.defaultContextTokens), resolved.defaults.defaultContextTokens), resolved.agent, mode);
+        const strategy = sanitizeContextStrategy(options.strategy, resolved.defaults.defaultContextStrategy);
+        const contextPackage = await buildContextPackage(resolved.vault, query, parsePositiveInteger(options.limit ?? String(resolved.defaults.defaultSearchLimit), resolved.defaults.defaultSearchLimit), parsePositiveInteger(options.tokens ?? String(resolved.defaults.defaultContextTokens), resolved.defaults.defaultContextTokens), resolved.agent, mode, strategy);
         print(options.json, contextPackage, () => contextPackage.content);
     });
+    program
+        .command('context-packs')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'accepted for consistency; context packs are already keyed by agent')
+        .option('--stale', 'operate only on packs stale for the current index and volatile-memory signature')
+        .option('--clear', 'remove context packs instead of listing them')
+        .option('--json', 'print machine-readable JSON')
+        .description('list or clear persisted CAG context packs')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const dataSignature = await readContextDataSignature(resolved.vault);
+        if (options.clear) {
+            const result = await clearContextPacks(resolved.vault, {
+                staleOnly: options.stale === true,
+                dataSignature
+            });
+            print(options.json, { vault: resolved.vault, dataSignature, ...result }, () => [
+                `Removed context packs: ${result.removed.length}`,
+                `Kept context packs: ${result.kept.length}`
+            ].join('\n'));
+            return;
+        }
+        const packs = await listContextPacks(resolved.vault, dataSignature);
+        const visiblePacks = options.stale ? packs.filter((pack) => pack.stale) : packs;
+        print(options.json, { vault: resolved.vault, dataSignature, packs: visiblePacks }, () => visiblePacks.length === 0
+            ? 'No context packs found.'
+            : visiblePacks
+                .map((pack) => [
+                `${pack.filename} ${pack.stale ? 'stale' : 'fresh'} ${pack.sizeBytes} bytes`,
+                pack.key ? `query="${pack.key.query}" agent=${pack.key.agentId ?? '*'} mode=${pack.key.mode ?? 'default'} limit=${pack.key.limit} tokens=${pack.key.maxTokens}` : 'unreadable pack'
+            ].join('\n'))
+                .join('\n\n'));
+    });
     program
         .command('graph')
         .option('-v, --vault <vault>', 'vault directory')

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

@@ -15,7 +15,7 @@ import { createOfflinePackBackup } from '../../application/offline-pack-backup.j
 import { startServer } from '../../application/start-server.js';
 import { startVaultWatcher } from '../../application/watch-vault.js';
 import { doctorVault, getStats, validateVault } from '../../application/analyze-vault.js';
-import { defaultBrainlinkConfig, sanitizeSearchMode } from '../../infrastructure/config.js';
+import { defaultBrainlinkConfig, sanitizeContextStrategy, sanitizeSearchMode } from '../../infrastructure/config.js';
 import { loadBrainlinkConfig } from '../../infrastructure/config.js';
 import { assertVaultAllowed, ensureVault, isBucketVaultPath } from '../../infrastructure/file-system-vault.js';
 import { getBootstrapPolicy, getBootstrapSessionStatus, touchBootstrapSession } from '../../infrastructure/session-state.js';
@@ -1111,6 +1111,7 @@ export const registerWriteCommands = (program) => {
         .option('-a, --agent <agent>', 'agent memory namespace')
         .option('--query <query>', 'optional task query to return immediate grounded context')
         .option('--mode <mode>', 'search mode for context (fts|semantic|hybrid)')
+        .option('--strategy <strategy>', 'context strategy for context (rag|cag|auto)')
         .option('--limit <limit>', 'maximum context sections')
         .option('--tokens <tokens>', 'maximum context token budget')
         .option('--no-install-agent', 'skip agent MCP/plugin installation and upgrade automation')
@@ -1125,6 +1126,7 @@ export const registerWriteCommands = (program) => {
         const limit = parsePositiveInteger(options.limit ?? String(resolved.defaults.defaultSearchLimit), resolved.defaults.defaultSearchLimit);
         const tokens = parsePositiveInteger(options.tokens ?? String(resolved.defaults.defaultContextTokens), resolved.defaults.defaultContextTokens);
         const mode = sanitizeSearchMode(options.mode, resolved.defaults.defaultSearchMode);
+        const strategy = sanitizeContextStrategy(options.strategy, resolved.defaults.defaultContextStrategy);
         const index = await indexVault(resolved.vault);
         const stats = await getStats(resolved.vault, resolved.agent);
         const validation = await validateVault(resolved.vault, resolved.agent);
@@ -1133,7 +1135,7 @@ export const registerWriteCommands = (program) => {
         const policy = await getBootstrapPolicy();
         const bootstrapStatus = await getBootstrapSessionStatus(resolved.vault, resolved.agent);
         const context = options.query
-            ? await buildContextPackage(resolved.vault, options.query, limit, tokens, resolved.agent, mode)
+            ? await buildContextPackage(resolved.vault, options.query, limit, tokens, resolved.agent, mode, strategy)
             : null;
         const agentIntegration = options.installAgent === false
             ? null

package/dist/infrastructure/config.js

@@ -13,6 +13,7 @@ export const defaultBrainlinkConfig = {
     autoCanonicalContextLinks: true,
     defaultSearchLimit: 10,
     defaultContextTokens: 2000,
+    defaultContextStrategy: 'rag',
     embeddingProvider: 'local',
     defaultSearchMode: 'hybrid',
     chunkSize: 1200,
@@ -41,8 +42,10 @@ const safeCwd = () => {
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 const embeddingProviders = new Set(['none', 'local']);
 const searchModes = new Set(['fts', 'semantic', 'hybrid']);
+const contextStrategies = new Set(['rag', 'cag', 'auto']);
 const sanitizeEmbeddingProvider = (value) => typeof value === 'string' && embeddingProviders.has(value) ? value : defaultBrainlinkConfig.embeddingProvider;
 export const sanitizeSearchMode = (value, fallback = defaultBrainlinkConfig.defaultSearchMode) => typeof value === 'string' && searchModes.has(value) ? value : fallback;
+export const sanitizeContextStrategy = (value, fallback = 'rag') => typeof value === 'string' && contextStrategies.has(value) ? value : fallback;
 const sanitizeAllowedVaults = (value) => Array.isArray(value) ? value.filter((item) => typeof item === 'string' && item.trim().length > 0) : [];
 const sanitizePositiveNumber = (value) => typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : undefined;
 const sanitizeIntegerInRange = (value, fallback, minimum, maximum) => {
@@ -84,10 +87,14 @@ const sanitizeAgentProfile = (value) => {
     const defaultSearchMode = typeof value.defaultSearchMode === 'string' && searchModes.has(value.defaultSearchMode)
         ? value.defaultSearchMode
         : undefined;
+    const defaultContextStrategy = typeof value.defaultContextStrategy === 'string' && contextStrategies.has(value.defaultContextStrategy)
+        ? value.defaultContextStrategy
+        : undefined;
     const profile = {
         ...(defaultSearchLimit ? { defaultSearchLimit } : {}),
         ...(defaultContextTokens ? { defaultContextTokens } : {}),
-        ...(defaultSearchMode ? { defaultSearchMode } : {})
+        ...(defaultSearchMode ? { defaultSearchMode } : {}),
+        ...(defaultContextStrategy ? { defaultContextStrategy } : {})
     };
     return Object.keys(profile).length > 0 ? profile : null;
 };
@@ -169,6 +176,7 @@ const sanitizeConfig = (value) => ({
     defaultContextTokens: typeof value.defaultContextTokens === 'number' && value.defaultContextTokens > 0
         ? value.defaultContextTokens
         : defaultBrainlinkConfig.defaultContextTokens,
+    defaultContextStrategy: sanitizeContextStrategy(value.defaultContextStrategy, defaultBrainlinkConfig.defaultContextStrategy),
     allowedVaults: [...sanitizeAllowedVaults(value.allowedVaults), ...readAllowedVaultsFromEnv()],
     chunkSize: typeof value.chunkSize === 'number' && value.chunkSize > 0 ? value.chunkSize : defaultBrainlinkConfig.chunkSize,
     searchPack: sanitizeSearchPackConfig(value.searchPack),
@@ -182,7 +190,8 @@ export const resolveAgentRuntimeDefaults = (config, agent) => {
     return {
         defaultSearchLimit: profile?.defaultSearchLimit ?? config.defaultSearchLimit,
         defaultContextTokens: profile?.defaultContextTokens ?? config.defaultContextTokens,
-        defaultSearchMode: profile?.defaultSearchMode ?? config.defaultSearchMode
+        defaultSearchMode: profile?.defaultSearchMode ?? config.defaultSearchMode,
+        defaultContextStrategy: profile?.defaultContextStrategy ?? config.defaultContextStrategy
     };
 };
 const mergeConfigLayers = (layers) => layers.reduce((state, config) => ({

package/dist/infrastructure/context-packs.js

@@ -0,0 +1,122 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+const normalizePackKey = (key) => ({
+    query: key.query.trim().toLowerCase(),
+    limit: key.limit,
+    maxTokens: key.maxTokens,
+    agentId: key.agentId?.trim().toLowerCase() || undefined,
+    mode: key.mode
+});
+export const contextPacksDirectory = (vaultPath) => join(vaultPath, '.brainlink', 'context-packs');
+export const contextPackPath = (vaultPath, key) => {
+    const digest = createHash('sha256').update(JSON.stringify(normalizePackKey(key))).digest('hex');
+    return join(contextPacksDirectory(vaultPath), `${digest}.json`);
+};
+const isStoredContextPack = (value) => {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const candidate = value;
+    return candidate.version === 1 && typeof candidate.dataSignature === 'string' && Boolean(candidate.context);
+};
+const readStoredContextPack = async (path) => {
+    try {
+        const parsed = JSON.parse(await readFile(path, 'utf8'));
+        return isStoredContextPack(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+};
+const toContextPackSummary = async (path, dataSignature) => {
+    const [info, stored] = await Promise.all([
+        stat(path),
+        readStoredContextPack(path)
+    ]);
+    const stale = !stored || (typeof dataSignature === 'string' && stored.dataSignature !== dataSignature);
+    return {
+        path,
+        filename: basename(path),
+        createdAt: stored?.createdAt ?? null,
+        dataSignature: stored?.dataSignature ?? null,
+        key: stored?.key ?? null,
+        sizeBytes: info.size,
+        stale
+    };
+};
+export const listContextPacks = async (vaultPath, dataSignature) => {
+    const directory = contextPacksDirectory(vaultPath);
+    try {
+        const entries = await readdir(directory, { withFileTypes: true });
+        const paths = entries
+            .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+            .map((entry) => join(directory, entry.name));
+        const summaries = await Promise.all(paths.map((path) => toContextPackSummary(path, dataSignature)));
+        return summaries.sort((left, right) => (right.createdAt ?? '').localeCompare(left.createdAt ?? '') || left.filename.localeCompare(right.filename));
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+};
+export const clearContextPacks = async (vaultPath, options = {}) => {
+    const packs = await listContextPacks(vaultPath, options.dataSignature);
+    const removed = options.staleOnly ? packs.filter((pack) => pack.stale) : packs;
+    const kept = options.staleOnly ? packs.filter((pack) => !pack.stale) : [];
+    await Promise.all(removed.map((pack) => rm(pack.path, { force: true })));
+    return { removed, kept };
+};
+export const readContextPack = async (vaultPath, key, dataSignature) => {
+    const path = contextPackPath(vaultPath, key);
+    try {
+        const parsed = await readStoredContextPack(path);
+        if (!parsed) {
+            return { status: 'stale', path };
+        }
+        if (parsed.dataSignature !== dataSignature) {
+            return { status: 'stale', path };
+        }
+        return {
+            status: 'hit',
+            path,
+            context: {
+                ...parsed.context,
+                strategy: 'cag',
+                cache: {
+                    storage: 'context-pack',
+                    status: 'hit',
+                    dataSignature,
+                    path
+                }
+            }
+        };
+    }
+    catch {
+        return { status: 'miss', path };
+    }
+};
+export const writeContextPack = async (vaultPath, key, dataSignature, context) => {
+    const path = contextPackPath(vaultPath, key);
+    const stored = {
+        version: 1,
+        createdAt: new Date().toISOString(),
+        dataSignature,
+        key: normalizePackKey(key),
+        context: {
+            ...context,
+            strategy: 'cag',
+            cache: {
+                storage: 'context-pack',
+                status: 'refresh',
+                dataSignature,
+                path
+            }
+        }
+    };
+    await mkdir(contextPacksDirectory(vaultPath), { recursive: true });
+    await writeFile(path, `${JSON.stringify(stored, null, 2)}\n`, 'utf8');
+    return path;
+};

package/dist/mcp/server.js

@@ -1,5 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { addNoteInputSchema, addFileInputSchema, addFileTool, addNoteTool, volatileAddInputSchema, volatileAddTool, volatileClearInputSchema, volatileClearTool, dedupeInputSchema, dedupeResolveInputSchema, dedupeResolveTool, dedupeTool, brokenLinksInputSchema, brokenLinksTool, bootstrapInputSchema, bootstrapTool, canonicalizeContextLinksInputSchema, canonicalizeContextLinksTool, contextInputSchema, contextTool, graphContextsInputSchema, graphContextsTool, graphInputSchema, graphTool, indexInputSchema, indexTool, orphansInputSchema, orphansTool, policyInputSchema, policyTool, recommendationsInputSchema, recommendationsTool, searchInputSchema, searchTool, statsInputSchema, statsTool, syncInputSchema, syncTool, validateInputSchema, validateTool, versionInputSchema, versionTool } from './tools.js';
+import { addNoteInputSchema, addFileInputSchema, addFileTool, addNoteTool, volatileAddInputSchema, volatileAddTool, volatileClearInputSchema, volatileClearTool, dedupeInputSchema, dedupeResolveInputSchema, dedupeResolveTool, dedupeTool, brokenLinksInputSchema, brokenLinksTool, bootstrapInputSchema, bootstrapTool, canonicalizeContextLinksInputSchema, canonicalizeContextLinksTool, contextInputSchema, contextPacksInputSchema, contextPacksTool, contextTool, graphContextsInputSchema, graphContextsTool, graphInputSchema, graphTool, indexInputSchema, indexTool, orphansInputSchema, orphansTool, policyInputSchema, policyTool, recommendationsInputSchema, recommendationsTool, searchInputSchema, searchTool, statsInputSchema, statsTool, syncInputSchema, syncTool, validateInputSchema, validateTool, versionInputSchema, versionTool } from './tools.js';
 import { getRuntimeVersion } from './runtime.js';
 export const createBrainlinkMcpServer = () => {
     const server = new McpServer({
@@ -25,14 +25,19 @@ export const createBrainlinkMcpServer = () => {
     }, versionTool);
     server.registerTool('brainlink_recommendations', {
         title: 'Brainlink Recommended MCP Workflow',
-        description: 'Return a plug-and-play action plan for this vault/agent, including policy, bootstrap, context retrieval and durable write guidance.',
+        description: 'Return a plug-and-play action plan for this vault/agent, including policy, bootstrap, RAG/CAG context strategy, retrieval and durable write guidance.',
         inputSchema: recommendationsInputSchema
     }, recommendationsTool);
     server.registerTool('brainlink_context', {
         title: 'Build Brainlink Context',
-        description: 'Read indexed Brainlink memory for a task or question. Usually called after brainlink_bootstrap. This is read-only and does not create graph links.',
+        description: 'Read indexed Brainlink memory for a task or question. Agents can choose strategy per call: rag for fresh retrieval assembly, cag for persisted context packs, or auto for pack-hit CAG with RAG fallback. Usually called after brainlink_bootstrap. This is read-only and does not create graph links.',
         inputSchema: contextInputSchema
     }, contextTool);
+    server.registerTool('brainlink_context_packs', {
+        title: 'Manage Brainlink Context Packs',
+        description: 'List or clear persisted CAG context packs. Packs are derived artifacts and can be rebuilt from Markdown/index state.',
+        inputSchema: contextPacksInputSchema
+    }, contextPacksTool);
     server.registerTool('brainlink_search', {
         title: 'Search Brainlink Memory',
         description: 'Search indexed Brainlink notes with FTS, semantic or hybrid retrieval.',