@andespindola/brainlink 0.1.0-beta.164 → 0.1.0-beta.166

package/README.md

@@ -71,6 +71,7 @@ Legacy `.jsonl.gz` packs are upgraded to `.blpk` automatically on first search/c
 - Full-text, semantic and hybrid retrieval on a local file index.
 - Middle-out context assembly around the strongest chunk per document.
 - In-process index and context caching with automatic invalidation on index updates.
+- Optional CAG context packs at `.brainlink/context-packs/*.json`, derived from the current index signature and reusable across repeated context calls.
 - HTTP graph server caches generated frontend assets and graph-layout JSON payloads by signature, and skips layout serialization when ETag returns `304`.
 - Compressed-space prefiltering for `.blpk` packs before decryption and scan.
 - Incremental indexing that reprocesses only changed markdown files and reuses existing chunks/embeddings for unchanged notes.
@@ -529,8 +530,9 @@ Available tools:
 
 - `brainlink_bootstrap`: plug-and-play entrypoint that runs index + health checks and can return context in one call.
 - `brainlink_policy`: read or update bootstrap/context-first policy, including presets (`preset: "fully-auto" | "strict"`).
-- `brainlink_recommendations`: return an automatic action plan so agents can run Brainlink in the recommended order.
-- `brainlink_context`: read indexed context for a task or question.
+- `brainlink_recommendations`: return an automatic action plan so agents can run Brainlink in the recommended order, including RAG/CAG context strategy guidance.
+- `brainlink_context`: read indexed context for a task or question; pass `strategy: "rag"` for fresh retrieval assembly, `strategy: "cag"` for persisted context packs or `strategy: "auto"` for CAG hits with RAG fallback.
+- `brainlink_context_packs`: list or clear persisted CAG context packs.
 - `brainlink_search`: search indexed notes.
 - `brainlink_dedupe`: detect duplicate candidates using exact hash + semantic similarity scores.
 - `brainlink_resolve_duplicate`: resolve duplicate pairs (`merge`, `link`, `ignore`) with connectivity-safe fallback edges.
@@ -555,6 +557,7 @@ By default, Brainlink enforces bootstrap and auto-runs it for read tools when se
 If you disable `autoBootstrapOnRead` through `brainlink_policy`, read tools return a preflight instruction with suggested `brainlink_bootstrap` arguments.
 `brainlink_bootstrap`, `brainlink_policy` and preflight responses include structured `nextActions` so MCP clients can continue automatically without custom parsing.
 For one-call planning, use `brainlink_recommendations` to get the recommended tool sequence for the current vault/agent/query.
+The MCP context tools are plug-and-play by default: omit `strategy` to use the configured default (`rag` unless changed), pass `strategy: "cag"` for repeated/stable task context, or pass `strategy: "auto"` so Brainlink chooses CAG on fresh pack hits and RAG otherwise. `brainlink_recommendations`, preflight responses and policy next actions include executable context arguments so clients can continue without custom parsing.
 
 The same linking rule applies through MCP: `brainlink_context` is read-only, and real graph links require Markdown notes with explicit `## Context Links` sections. `brainlink_add_note` and `brainlink_add_file` reindex by default and include index + `writeConnectivity` metadata. Brainlink does not auto-link new notes to fallback hubs.
 
@@ -864,10 +867,15 @@ Context selection uses a middle-out strategy: it starts from the strongest chunk
 blink context "question" --vault ./vault --limit 12 --tokens 2000
 blink context "question" --vault ./vault --agent coding-agent --json
 blink context "question" --vault ./vault --agent coding-agent --mode hybrid --json
+blink context "question" --vault ./vault --agent coding-agent --strategy cag --json
+blink context "question" --vault ./vault --agent coding-agent --strategy auto --json
+blink context-packs --vault ./vault --json
+blink context-packs --vault ./vault --stale --clear
 ```
 
 Builds a compact context package for an agent.
 Repeated calls with the same vault, agent, query, mode and token/limit settings are served from a short in-memory cache while the index is unchanged.
+The default strategy is configured by `defaultContextStrategy` and starts as `rag`, which retrieves and assembles context from the current index. `--strategy cag` enables cache-augmented context generation by reading or refreshing a persisted context pack under `.brainlink/context-packs`; `--strategy auto` uses CAG when a fresh pack exists and RAG otherwise, refreshing a pack for future calls. Context responses include `cache`, `metrics`, `requestedStrategy` and `recommendedStrategy` metadata. Packs are derived artifacts and become stale when the index or volatile memory signature changes.
 
 ### `links`
 
@@ -1010,6 +1018,7 @@ If no `vault` is configured and no `--vault` flag is passed, Brainlink uses `$HO
   "autoCanonicalContextLinks": true,
   "defaultSearchLimit": 10,
   "defaultContextTokens": 2000,
+  "defaultContextStrategy": "rag",
   "embeddingProvider": "local",
   "defaultSearchMode": "hybrid",
   "chunkSize": 1200,
@@ -1024,7 +1033,8 @@ If no `vault` is configured and no `--vault` flag is passed, Brainlink uses `$HO
     "coding-agent": {
       "defaultSearchMode": "semantic",
       "defaultSearchLimit": 8,
-      "defaultContextTokens": 2400
+      "defaultContextTokens": 2400,
+      "defaultContextStrategy": "auto"
     },
     "*": {
       "defaultSearchMode": "hybrid"
@@ -1034,7 +1044,7 @@ If no `vault` is configured and no `--vault` flag is passed, Brainlink uses `$HO
 ```
 
 `defaultAgent` is optional. When set, CLI and MCP calls that omit `--agent`/`agent` use this value automatically. If not set, behavior remains as before.
-`agentProfiles` is optional. When present, CLI and MCP resolve `mode`, `limit` and `tokens` per agent automatically, then fallback to global defaults.
+`agentProfiles` is optional. When present, CLI and MCP resolve `mode`, `limit`, `tokens` and context `strategy` per agent automatically, then fallback to global defaults.
 
 `autoIndexOnWrite` is optional and defaults to `true`. Set it to `false` to defer indexing after writes.
 `autoCanonicalContextLinks` is optional and defaults to `true`. When enabled, `blink add`, `brainlink_add_note` and `brainlink_add_file` add a canonical `## Context Links` entry to the inferred context hub, creating that hub when needed.

package/dist/application/analyze-vault.js

@@ -50,7 +50,7 @@ export const getExtendedStats = async (vaultPath, agentId) => {
     await searchKnowledge(absoluteVaultPath, probeQuery, Math.min(defaults.defaultSearchLimit, 8), agentId, 'hybrid');
     const searchLatency = performance.now() - searchStart;
     const contextStart = performance.now();
-    await buildContextPackage(absoluteVaultPath, probeQuery, Math.min(defaults.defaultSearchLimit, 8), defaults.defaultContextTokens, agentId, 'hybrid');
+    await buildContextPackage(absoluteVaultPath, probeQuery, Math.min(defaults.defaultSearchLimit, 8), defaults.defaultContextTokens, agentId, 'hybrid', undefined, defaults.defaultContextCacheTtlMs);
     const contextLatency = performance.now() - contextStart;
     return {
         stats,

package/dist/application/build-context.js

@@ -1,9 +1,10 @@
 import { stat } from 'node:fs/promises';
+import { performance } from 'node:perf_hooks';
 import { formatContextPackage, selectContextSections } from '../domain/context.js';
+import { readContextPack, writeContextPack } from '../infrastructure/context-packs.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 readFileSignature = async (path) => {
@@ -15,16 +16,21 @@ const readFileSignature = async (path) => {
         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({
+export const readContextDataSignature = async (vaultPath) => `${await readFileSignature(indexStoragePath(vaultPath))}|${await readFileSignature(volatileMemoryStoragePath(vaultPath))}`;
+const toCacheKey = (vaultPath, query, limit, maxTokens, agentId, mode, strategy) => JSON.stringify({
     vaultPath,
     query: query.trim().toLowerCase(),
     limit,
     maxTokens,
     agentId: agentId?.trim().toLowerCase() ?? '*',
-    mode: mode ?? 'default'
+    mode: mode ?? 'default',
+    strategy
 });
-const contextCacheGet = (key, dataSignature) => {
+const withCacheMetadata = (context, cache) => ({
+    ...context,
+    cache
+});
+const contextCacheGet = (key, dataSignature, contextCacheTtlMs) => {
     const entry = contextCache.get(key);
     if (!entry) {
         return undefined;
@@ -34,7 +40,11 @@ const contextCacheGet = (key, dataSignature) => {
         contextCache.delete(key);
         return undefined;
     }
-    return entry.context;
+    return withCacheMetadata(entry.context, {
+        storage: 'memory',
+        status: 'hit',
+        dataSignature
+    });
 };
 const contextCacheSet = (entry) => {
     contextCache.set(entry.key, entry);
@@ -45,32 +55,115 @@ const contextCacheSet = (entry) => {
     const keys = Array.from(contextCache.keys()).slice(0, overflow);
     keys.forEach((key) => contextCache.delete(key));
 };
-export const buildContextPackage = async (vaultPath, query, limit, maxTokens, agentId, mode) => {
-    const cacheKey = toCacheKey(vaultPath, query, limit, maxTokens, agentId, mode);
+const elapsedMs = (start) => Math.round((performance.now() - start) * 1000) / 1000;
+const estimateSectionTokens = (context) => Math.ceil(context.content.length / 4);
+const emptyMetrics = (context, totalMs, overrides = {}) => ({
+    totalMs,
+    packReadMs: 0,
+    searchMs: 0,
+    selectionMs: 0,
+    volatileMs: 0,
+    packWriteMs: 0,
+    sectionCount: context.sections.length,
+    volatileSectionCount: context.volatileSections?.length ?? 0,
+    estimatedTokens: estimateSectionTokens(context),
+    ...overrides
+});
+export const buildContextPackage = async (vaultPath, query, limit, maxTokens, agentId, mode, strategy = 'rag', contextCacheTtlMs = 120_000) => {
+    const totalStart = performance.now();
+    const cacheKey = toCacheKey(vaultPath, query, limit, maxTokens, agentId, mode, strategy);
     const dataSignature = await readContextDataSignature(vaultPath);
-    const cached = contextCacheGet(cacheKey, dataSignature);
+    const cached = contextCacheGet(cacheKey, dataSignature, contextCacheTtlMs);
     if (cached) {
         return cached;
     }
+    const shouldUseContextPack = strategy === 'cag' || strategy === 'auto';
+    let packReadMs = 0;
+    if (shouldUseContextPack) {
+        const packReadStart = performance.now();
+        const pack = await readContextPack(vaultPath, { query, limit, maxTokens, agentId, mode }, dataSignature);
+        packReadMs = elapsedMs(packReadStart);
+        if (pack.status === 'hit') {
+            const contextFromPack = {
+                ...pack.context,
+                strategy: 'cag',
+                requestedStrategy: strategy,
+                recommendedStrategy: {
+                    strategy: 'cag',
+                    reason: strategy === 'auto'
+                        ? 'A fresh context pack exists, so auto selected CAG.'
+                        : 'The requested CAG context pack is fresh.'
+                },
+                metrics: emptyMetrics(pack.context, elapsedMs(totalStart), { packReadMs })
+            };
+            contextCacheSet({
+                key: cacheKey,
+                createdAt: Date.now(),
+                dataSignature,
+                strategy,
+                context: contextFromPack
+            });
+            return contextFromPack;
+        }
+    }
+    const searchStart = performance.now();
     const results = await searchKnowledge(vaultPath, query, limit, agentId, mode);
+    const searchMs = elapsedMs(searchStart);
+    const selectionStart = performance.now();
     const durableSections = selectContextSections(results, maxTokens);
+    const selectionMs = elapsedMs(selectionStart);
+    const volatileStart = performance.now();
     const volatileSections = await searchVolatileMemory(vaultPath, query, Math.min(3, limit), agentId, mode ?? 'hybrid');
+    const volatileMs = elapsedMs(volatileStart);
     const sections = [...volatileSections, ...durableSections];
+    const effectiveStrategy = strategy === 'cag' ? 'cag' : 'rag';
     const context = {
         query,
         sections,
         content: formatContextPackage(query, sections),
-        ...(volatileSections.length > 0 ? { volatileSections } : {})
+        ...(volatileSections.length > 0 ? { volatileSections } : {}),
+        strategy: effectiveStrategy,
+        requestedStrategy: strategy,
+        recommendedStrategy: {
+            strategy: effectiveStrategy,
+            reason: strategy === 'auto'
+                ? 'No fresh context pack was available, so auto selected fresh RAG assembly and refreshed a pack for future reuse.'
+                : effectiveStrategy === 'cag'
+                    ? 'CAG was requested; Brainlink refreshed the context pack from current retrieval results.'
+                    : 'RAG was requested; Brainlink assembled context directly from current retrieval results.'
+        }
+    };
+    const packWriteStart = performance.now();
+    const packPath = shouldUseContextPack
+        ? await writeContextPack(vaultPath, { query, limit, maxTokens, agentId, mode }, dataSignature, context)
+        : undefined;
+    const packWriteMs = packPath ? elapsedMs(packWriteStart) : 0;
+    const contextWithMetadata = withCacheMetadata(context, {
+        storage: shouldUseContextPack ? 'context-pack' : 'memory',
+        status: shouldUseContextPack ? 'refresh' : 'miss',
+        dataSignature,
+        ...(packPath ? { path: packPath } : {})
+    });
+    const contextWithMetrics = {
+        ...contextWithMetadata,
+        metrics: emptyMetrics(contextWithMetadata, elapsedMs(totalStart), {
+            packReadMs,
+            searchMs,
+            selectionMs,
+            volatileMs,
+            packWriteMs
+        })
     };
     contextCacheSet({
         key: cacheKey,
         createdAt: Date.now(),
         dataSignature,
-        context
+        strategy,
+        context: contextWithMetrics
     });
-    return context;
+    return contextWithMetrics;
 };
-export const buildContext = async (vaultPath, query, limit, maxTokens, agentId, mode) => {
-    const contextPackage = await buildContextPackage(vaultPath, query, limit, maxTokens, agentId, mode);
+export const buildContext = async (vaultPath, query, limit, maxTokens, agentId, mode, strategy, contextCacheTtlMs = 120_000) => {
+    const contextPackage = await buildContextPackage(vaultPath, query, limit, maxTokens, agentId, mode, strategy, contextCacheTtlMs);
     return contextPackage.content;
 };

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,27 @@ 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 readContextCacheTtlMs = async (url) => {
+    const config = await loadBrainlinkConfig();
+    const defaults = resolveAgentRuntimeDefaults(config, readAgentQuery(url));
+    return defaults.defaultContextCacheTtlMs;
 };
 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 +385,15 @@ 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);
+        const contextCacheTtlMs = await readContextCacheTtlMs(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, contextCacheTtlMs)), 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, resolved.defaults.defaultContextCacheTtlMs);
         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, resolved.defaults.defaultContextCacheTtlMs)
             : null;
         const agentIntegration = options.installAgent === false
             ? null

package/dist/infrastructure/config.js

@@ -13,6 +13,8 @@ export const defaultBrainlinkConfig = {
     autoCanonicalContextLinks: true,
     defaultSearchLimit: 10,
     defaultContextTokens: 2000,
+    defaultContextStrategy: 'rag',
+    defaultContextCacheTtlMs: 120_000,
     embeddingProvider: 'local',
     defaultSearchMode: 'hybrid',
     chunkSize: 1200,
@@ -41,8 +43,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 +88,20 @@ 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 defaultContextCacheTtlMs = typeof value.defaultContextCacheTtlMs === 'number' &&
+        Number.isFinite(value.defaultContextCacheTtlMs) &&
+        value.defaultContextCacheTtlMs > 0
+        ? Math.floor(value.defaultContextCacheTtlMs)
+        : undefined;
     const profile = {
         ...(defaultSearchLimit ? { defaultSearchLimit } : {}),
         ...(defaultContextTokens ? { defaultContextTokens } : {}),
-        ...(defaultSearchMode ? { defaultSearchMode } : {})
+        ...(defaultSearchMode ? { defaultSearchMode } : {}),
+        ...(defaultContextStrategy ? { defaultContextStrategy } : {}),
+        ...(defaultContextCacheTtlMs ? { defaultContextCacheTtlMs } : {})
     };
     return Object.keys(profile).length > 0 ? profile : null;
 };
@@ -169,6 +183,10 @@ const sanitizeConfig = (value) => ({
     defaultContextTokens: typeof value.defaultContextTokens === 'number' && value.defaultContextTokens > 0
         ? value.defaultContextTokens
         : defaultBrainlinkConfig.defaultContextTokens,
+    defaultContextStrategy: sanitizeContextStrategy(value.defaultContextStrategy, defaultBrainlinkConfig.defaultContextStrategy),
+    defaultContextCacheTtlMs: typeof value.defaultContextCacheTtlMs === 'number' && Number.isFinite(value.defaultContextCacheTtlMs) && value.defaultContextCacheTtlMs > 0
+        ? Math.floor(value.defaultContextCacheTtlMs)
+        : defaultBrainlinkConfig.defaultContextCacheTtlMs,
     allowedVaults: [...sanitizeAllowedVaults(value.allowedVaults), ...readAllowedVaultsFromEnv()],
     chunkSize: typeof value.chunkSize === 'number' && value.chunkSize > 0 ? value.chunkSize : defaultBrainlinkConfig.chunkSize,
     searchPack: sanitizeSearchPackConfig(value.searchPack),
@@ -182,7 +200,9 @@ 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,
+        defaultContextCacheTtlMs: profile?.defaultContextCacheTtlMs ?? config.defaultContextCacheTtlMs
     };
 };
 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.',

package/dist/mcp/tools.js

@@ -3,14 +3,15 @@ import { basename, extname } from 'node:path';
 import { z } from 'zod';
 import { getBrokenLinksReport, getOrphansReport, getStats, validateVault } from '../application/analyze-vault.js';
 import { addNoteWithMetadata } from '../application/add-note.js';
-import { buildContextPackage } from '../application/build-context.js';
+import { buildContextPackage, readContextDataSignature } from '../application/build-context.js';
 import { canonicalizeContextLinks } from '../application/canonical-context-links.js';
 import { resolveDuplicateNotes, scanDuplicateNotes } from '../application/dedupe-notes.js';
 import { getGraph } from '../application/get-graph.js';
 import { getGraphContexts } from '../application/get-graph-contexts.js';
 import { indexVault } from '../application/index-vault.js';
 import { searchKnowledge } from '../application/search-knowledge.js';
-import { resolveAgentRuntimeDefaults, sanitizeSearchMode } from '../infrastructure/config.js';
+import { resolveAgentRuntimeDefaults, sanitizeContextStrategy, sanitizeSearchMode } from '../infrastructure/config.js';
+import { clearContextPacks, listContextPacks } from '../infrastructure/context-packs.js';
 import { loadBrainlinkConfig } from '../infrastructure/config.js';
 import { assertVaultAllowed } from '../infrastructure/file-system-vault.js';
 import { addVolatileMemory, clearVolatileMemory } from '../infrastructure/volatile-memory.js';
@@ -40,6 +41,12 @@ const agentInput = {
 const searchModeInput = {
     mode: z.enum(['fts', 'semantic', 'hybrid']).optional().describe('Search mode. Defaults to the Brainlink config value.')
 };
+const contextStrategyInput = {
+    strategy: z
+        .enum(['rag', 'cag', 'auto'])
+        .optional()
+        .describe('Context strategy per call. Use rag for fresh retrieval assembly, cag to reuse persisted context packs when fresh, or auto to choose CAG on fresh pack hits and RAG otherwise. Defaults to the Brainlink config value.')
+};
 const resolveExecutionContext = async (input) => {
     const config = await loadBrainlinkConfig();
     const vault = await assertVaultAllowed(input.vault ?? config.vault, config.allowedVaults);
@@ -122,12 +129,14 @@ const ensureBootstrapReady = async (context, input, toolName) => {
         };
     }
     const mode = typeof input.mode === 'string' && ['fts', 'semantic', 'hybrid'].includes(input.mode) ? input.mode : 'hybrid';
+    const strategy = sanitizeContextStrategy(typeof input.strategy === 'string' ? input.strategy : undefined, 'rag');
     const query = typeof input.query === 'string' && input.query.trim().length > 0 ? input.query : undefined;
     const bootstrapArgs = {
         vault: context.vault,
         ...(context.agent ? { agent: context.agent } : {}),
         ...(query ? { query } : {}),
-        mode
+        mode,
+        strategy
     };
     const nextActions = [
         {
@@ -178,6 +187,7 @@ const ensureContextReady = async (context, input, toolName) => {
             ? input.contextQuery
             : '<task>';
     const mode = sanitizeSearchMode(typeof input.mode === 'string' ? input.mode : undefined, context.defaults.defaultSearchMode);
+    const strategy = sanitizeContextStrategy(typeof input.strategy === 'string' ? input.strategy : undefined, context.defaults.defaultContextStrategy);
     const limit = typeof input.limit === 'number' && Number.isFinite(input.limit) && input.limit > 0
         ? input.limit
         : typeof input.contextLimit === 'number' && Number.isFinite(input.contextLimit) && input.contextLimit > 0
@@ -193,6 +203,7 @@ const ensureContextReady = async (context, input, toolName) => {
         ...(context.agent ? { agent: context.agent } : {}),
         query: queryFromInput,
         mode,
+        strategy,
         limit,
         tokens
     };
@@ -219,10 +230,17 @@ export const contextInputSchema = {
     ...vaultInput,
     ...agentInput,
     ...searchModeInput,
+    ...contextStrategyInput,
     query: z.string().min(1).describe('Task or question to retrieve Brainlink context for.'),
     limit: optionalPositiveInteger().describe('Maximum search results before context selection.'),
     tokens: optionalPositiveInteger().describe('Maximum estimated context tokens.')
 };
+export const contextPacksInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    action: z.enum(['list', 'clear']).optional().default('list').describe('Action to perform on persisted CAG context packs.'),
+    staleOnly: z.boolean().optional().default(false).describe('When clearing, remove only packs stale for the current index and volatile-memory signature.')
+};
 export const searchInputSchema = {
     ...vaultInput,
     ...agentInput,
@@ -311,6 +329,7 @@ export const syncInputSchema = {
     ...agentInput,
     contextQuery: z.string().min(1).optional().describe('Optional context smoke query. Omit to skip context probe.'),
     mode: z.enum(['fts', 'semantic', 'hybrid']).optional().describe('Search mode for the optional context probe. Defaults to config value.'),
+    strategy: z.enum(['rag', 'cag', 'auto']).optional().describe('Context strategy for the optional context probe. Defaults to the Brainlink config value.'),
     contextLimit: optionalPositiveInteger().describe('Context smoke result limit when contextQuery is provided.'),
     contextTokens: optionalPositiveInteger().describe('Context smoke token target when contextQuery is provided.')
 };
@@ -318,6 +337,7 @@ export const bootstrapInputSchema = {
     ...vaultInput,
     ...agentInput,
     ...searchModeInput,
+    ...contextStrategyInput,
     query: z
         .string()
         .min(1)
@@ -350,6 +370,7 @@ export const recommendationsInputSchema = {
     ...vaultInput,
     ...agentInput,
     ...searchModeInput,
+    ...contextStrategyInput,
     query: z.string().min(1).optional().describe('Optional current task query to generate context-focused recommendations.'),
     limit: optionalPositiveInteger().describe('Optional context limit override for generated recommendations.'),
     tokens: optionalPositiveInteger().describe('Optional context token budget override for generated recommendations.')
@@ -375,14 +396,16 @@ export const contextTool = async (input) => {
         return readiness.preflight;
     }
     const mode = sanitizeSearchMode(input.mode, context.defaults.defaultSearchMode);
+    const strategy = sanitizeContextStrategy(input.strategy, context.defaults.defaultContextStrategy);
     const limit = input.limit ?? context.defaults.defaultSearchLimit;
     const tokens = input.tokens ?? context.defaults.defaultContextTokens;
-    const contextPackage = await buildContextPackage(context.vault, input.query, limit, tokens, context.agent, mode);
+    const contextPackage = await buildContextPackage(context.vault, input.query, limit, tokens, context.agent, mode, strategy, context.defaults.defaultContextCacheTtlMs);
     const contextSession = await touchContextSession(context.vault, context.agent);
     return jsonResult({
         vault: context.vault,
         agent: context.agent,
         mode,
+        strategy,
         limit,
         tokens,
         contextSession,
@@ -390,6 +413,32 @@ export const contextTool = async (input) => {
         ...contextPackage
     });
 };
+export const contextPacksTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const dataSignature = await readContextDataSignature(context.vault);
+    if (input.action === 'clear') {
+        const result = await clearContextPacks(context.vault, {
+            staleOnly: input.staleOnly === true,
+            dataSignature
+        });
+        return jsonResult({
+            vault: context.vault,
+            agent: context.agent,
+            dataSignature,
+            action: 'clear',
+            staleOnly: input.staleOnly === true,
+            ...result
+        });
+    }
+    const packs = await listContextPacks(context.vault, dataSignature);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        dataSignature,
+        action: 'list',
+        packs
+    });
+};
 export const searchTool = async (input) => {
     const context = await resolveExecutionContext(input);
     const readiness = await ensureBootstrapReady(context, input, 'brainlink_search');
@@ -666,14 +715,16 @@ export const syncTool = async (input) => {
         return jsonResult(response);
     }
     const mode = sanitizeSearchMode(input.mode, context.defaults.defaultSearchMode);
+    const strategy = sanitizeContextStrategy(input.strategy, context.defaults.defaultContextStrategy);
     const contextLimit = input.contextLimit ?? context.defaults.defaultSearchLimit;
     const contextTokens = input.contextTokens ?? context.defaults.defaultContextTokens;
-    const contextPackage = await buildContextPackage(context.vault, input.contextQuery, contextLimit, contextTokens, context.agent, mode);
+    const contextPackage = await buildContextPackage(context.vault, input.contextQuery, contextLimit, contextTokens, context.agent, mode, strategy, context.defaults.defaultContextCacheTtlMs);
     const contextSession = await touchContextSession(context.vault, context.agent);
     return jsonResult({
         ...response,
         context: {
             mode,
+            strategy,
             contextSession,
             ...contextPackage
         }
@@ -685,10 +736,11 @@ export const bootstrapTool = async (input) => {
     const stats = await getStats(context.vault, context.agent);
     const validation = await validateVault(context.vault, context.agent);
     const mode = sanitizeSearchMode(input.mode, context.defaults.defaultSearchMode);
+    const strategy = sanitizeContextStrategy(input.strategy, context.defaults.defaultContextStrategy);
     const limit = input.limit ?? context.defaults.defaultSearchLimit;
     const tokens = input.tokens ?? context.defaults.defaultContextTokens;
     const contextPackage = input.query
-        ? await buildContextPackage(context.vault, input.query, limit, tokens, context.agent, mode)
+        ? await buildContextPackage(context.vault, input.query, limit, tokens, context.agent, mode, strategy, context.defaults.defaultContextCacheTtlMs)
         : undefined;
     const contextSession = input.query ? await touchContextSession(context.vault, context.agent) : undefined;
     const guidance = stats.documentCount === 0
@@ -742,6 +794,7 @@ export const bootstrapTool = async (input) => {
                         ...(context.agent ? { agent: context.agent } : {}),
                         query: '<task>',
                         mode,
+                        strategy,
                         limit,
                         tokens
                     }
@@ -751,6 +804,7 @@ export const bootstrapTool = async (input) => {
         vault: context.vault,
         agent: context.agent,
         mode,
+        strategy,
         limit,
         tokens,
         index,
@@ -806,7 +860,8 @@ export const policyTool = async (input) => {
                 args: {
                     vault: context.vault,
                     ...(context.agent ? { agent: context.agent } : {}),
-                    mode: context.defaults.defaultSearchMode
+                    mode: context.defaults.defaultSearchMode,
+                    strategy: context.defaults.defaultContextStrategy
                 }
             }
         ];
@@ -821,6 +876,7 @@ export const policyTool = async (input) => {
                     ...(context.agent ? { agent: context.agent } : {}),
                     query: '<task>',
                     mode: context.defaults.defaultSearchMode,
+                    strategy: context.defaults.defaultContextStrategy,
                     limit: context.defaults.defaultSearchLimit,
                     tokens: context.defaults.defaultContextTokens
                 }
@@ -852,6 +908,7 @@ export const recommendationsTool = async (input) => {
     const contextStatus = await getContextSessionStatus(context.vault, context.agent);
     const stats = await getStats(context.vault, context.agent);
     const mode = sanitizeSearchMode(input.mode, context.defaults.defaultSearchMode);
+    const strategy = sanitizeContextStrategy(input.strategy, context.defaults.defaultContextStrategy);
     const limit = input.limit ?? context.defaults.defaultSearchLimit;
     const tokens = input.tokens ?? context.defaults.defaultContextTokens;
     const query = input.query?.trim();
@@ -876,6 +933,7 @@ export const recommendationsTool = async (input) => {
                         vault: context.vault,
                         ...(context.agent ? { agent: context.agent } : {}),
                         mode,
+                        strategy,
                         ...(query ? { query } : {})
                     }
                 }
@@ -891,6 +949,7 @@ export const recommendationsTool = async (input) => {
                         ...(context.agent ? { agent: context.agent } : {}),
                         query: query ?? '<task>',
                         mode,
+                        strategy,
                         limit,
                         tokens
                     }
@@ -926,6 +985,7 @@ export const recommendationsTool = async (input) => {
                 ...(context.agent ? { agent: context.agent } : {}),
                 query: query ?? '<task>',
                 mode,
+                strategy,
                 limit,
                 tokens
             }
@@ -957,9 +1017,24 @@ export const recommendationsTool = async (input) => {
         agent: context.agent,
         defaults: {
             mode,
+            strategy,
             limit,
             tokens
         },
+        contextStrategies: [
+            {
+                strategy: 'rag',
+                useWhen: 'Use for fresh retrieval and context assembly from the current index.'
+            },
+            {
+                strategy: 'cag',
+                useWhen: 'Use for repeated or stable task context so Brainlink can reuse a fresh persisted context pack.'
+            },
+            {
+                strategy: 'auto',
+                useWhen: 'Use when the agent wants Brainlink to choose CAG on fresh pack hits and RAG otherwise.'
+            }
+        ],
         policy,
         bootstrapStatus,
         contextStatus,

package/docs/AGENT_USAGE.md

@@ -51,7 +51,7 @@ Set `BRAINLINK_HOME` when the whole Brainlink home directory should live somewhe
 Use `blink config where` and `blink config doctor` to inspect active paths and effective source.
 
 You can also set `defaultAgent` in `brainlink.config.json` / `.brainlink.json` (for example `"defaultAgent": "coding-agent"`). When set, CLI commands and MCP calls reuse it when `--agent`/`agent` is not passed.
-You can set `agentProfiles` to define per-agent defaults for `defaultSearchMode`, `defaultSearchLimit` and `defaultContextTokens`.
+You can set `agentProfiles` to define per-agent defaults for `defaultSearchMode`, `defaultSearchLimit`, `defaultContextTokens`, `defaultContextStrategy` and `defaultContextCacheTtlMs`.
 You can tune search-pack compression with `searchPack.rowChunkSize`, `searchPack.compressionLevel` and `searchPack.useDictionary`.
 Guardrails for benchmark acceptance are configured with `searchPack.guardrailMinSavingsPercent` and `searchPack.guardrailMaxLatencyRegressionPercent`.
 
@@ -542,9 +542,14 @@ blink context "how does authentication work?" --vault ./vault --limit 12 --token
 blink context "how does authentication work?" --vault ./vault --json
 blink context "how does authentication work?" --vault ./vault --agent coding-agent --json
 blink context "how does authentication work?" --vault ./vault --agent coding-agent --mode hybrid --json
+blink context "how does authentication work?" --vault ./vault --agent coding-agent --strategy cag --json
+blink context "how does authentication work?" --vault ./vault --agent coding-agent --strategy auto --json
+blink context-packs --vault ./vault --json
+blink context-packs --vault ./vault --stale --clear
 ```
 
 This returns a Markdown context package optimized for prompt injection.
+The default strategy is configured by `defaultContextStrategy` and starts as `rag`. Use `--strategy cag` when the same agent/task context should be served from a persisted context pack when the index and volatile-memory signatures are unchanged. Use `--strategy auto` when Brainlink should use CAG on fresh pack hits and RAG otherwise. Context responses include `cache`, `metrics`, `requestedStrategy` and `recommendedStrategy` metadata. CAG packs live under `.brainlink/context-packs` and are rebuildable derived artifacts.
 
 ### Inspect Links
 
@@ -670,6 +675,7 @@ Available MCP tools:
 - `brainlink_policy`
 - `brainlink_recommendations`
 - `brainlink_context`
+- `brainlink_context_packs`
 - `brainlink_search`
 - `brainlink_dedupe`
 - `brainlink_resolve_duplicate`
@@ -693,6 +699,7 @@ If `autoBootstrapOnRead` or `enforceContextFirst` are disabled through `brainlin
 `brainlink_bootstrap`, `brainlink_policy` and preflight responses include structured `nextActions` so clients can continue tool flows automatically.
 `brainlink_policy` also accepts policy presets (`fully-auto`, `strict`) so MCP clients can switch behavior in one call.
 `brainlink_recommendations` returns the suggested execution order so an agent can follow Brainlink best practices automatically.
+MCP context is plug-and-play: agents may omit `strategy` for the configured default, pass `strategy: "rag"` for explicit fresh retrieval assembly, pass `strategy: "cag"` to reuse persisted context packs when the task context is stable or repeated, or pass `strategy: "auto"` to use CAG on fresh pack hits and RAG otherwise. `brainlink_recommendations`, policy next actions and preflight responses return executable context arguments, so clients can continue without custom parsing. `brainlink_context_packs` lists or clears persisted CAG packs.
 
 MCP clients can pass `vault` and `agent` arguments per tool call. Set `BRAINLINK_ALLOWED_VAULTS` when exposing Brainlink to an external agent process so a tool cannot pass arbitrary vault paths:
 

package/docs/ARCHITECTURE.md

@@ -136,6 +136,8 @@ read markdown files
 
 ```txt
 question
+  -> selected strategy: rag | cag | auto
+  -> if cag/auto and fresh context pack exists, return cached Markdown package
   -> selected mode: fts | semantic | hybrid
   -> optional query embedding
   -> optional compressed pack prefilter (token bloom)
@@ -145,8 +147,12 @@ question
   -> ranked chunks with textScore and semanticScore
   -> token-budget selection
   -> Markdown context package
+  -> if cag/auto, persist derived context pack with current data signature
+  -> return cache, strategy and timing metrics
 ```
 
+Context packs are stored under `.brainlink/context-packs/*.json`. They are derived artifacts keyed by query, agent, mode, limit and token budget, and are invalidated by the combined index and volatile-memory signature. Markdown remains the source of truth. The `auto` strategy uses CAG on fresh pack hits and falls back to RAG assembly otherwise, refreshing a pack for later calls.
+
 ## Graph Server Flow
 
 ```txt

package/docs/QUICKSTART.md

@@ -50,7 +50,9 @@ Optional per-agent retrieval defaults in `brainlink.config.json`:
     "coding-agent": {
       "defaultSearchMode": "semantic",
       "defaultSearchLimit": 8,
-      "defaultContextTokens": 2400
+      "defaultContextTokens": 2400,
+      "defaultContextStrategy": "auto",
+      "defaultContextCacheTtlMs": 120000
     }
   }
 }

package/package.json

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