@andespindola/brainlink 0.1.0-beta.99 → 1.0.0

package/dist/mcp/server.js

@@ -1,18 +1,11 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { addNoteInputSchema, addFileInputSchema, addFileTool, addNoteTool, dedupeInputSchema, dedupeResolveInputSchema, dedupeResolveTool, dedupeTool, brokenLinksInputSchema, brokenLinksTool, bootstrapInputSchema, bootstrapTool, contextInputSchema, contextTool, graphInputSchema, graphTool, indexInputSchema, indexTool, orphansInputSchema, orphansTool, policyInputSchema, policyTool, recommendationsInputSchema, recommendationsTool, searchInputSchema, searchTool, statsInputSchema, statsTool, syncInputSchema, syncTool, validateInputSchema, validateTool } from './tools.js';
-const readPackageVersion = () => {
-    const packagePath = join(dirname(fileURLToPath(import.meta.url)), '../../package.json');
-    const metadata = JSON.parse(readFileSync(packagePath, 'utf8'));
-    return metadata.version ?? '0.0.0';
-};
+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({
         name: 'brainlink',
         title: 'Brainlink',
-        version: readPackageVersion(),
+        version: getRuntimeVersion(),
         description: 'Local-first Markdown memory tools for AI agents.'
     });
     server.registerTool('brainlink_bootstrap', {
@@ -25,16 +18,26 @@ export const createBrainlinkMcpServer = () => {
         description: 'Read or update bootstrap enforcement policy and inspect bootstrap readiness for the current vault/agent.',
         inputSchema: policyInputSchema
     }, policyTool);
+    server.registerTool('brainlink_version', {
+        title: 'Read Brainlink Runtime Version',
+        description: 'Return the current Brainlink MCP runtime package version and metadata.',
+        inputSchema: versionInputSchema
+    }, 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.',
@@ -55,14 +58,29 @@ export const createBrainlinkMcpServer = () => {
         description: 'Write durable Markdown memory, then reindex the vault. Include explicit [[wiki links]] for connected graph memory. Add priority markers near links, such as priority: high, #important or #critical, when a relationship should be weighted higher.',
         inputSchema: addNoteInputSchema
     }, addNoteTool);
+    server.registerTool('brainlink_volatile_add', {
+        title: 'Add Volatile Brainlink Memory',
+        description: 'Write temporary agent-decided memory with TTL. Use for transient task state without polluting durable Markdown memory.',
+        inputSchema: volatileAddInputSchema
+    }, volatileAddTool);
+    server.registerTool('brainlink_volatile_clear', {
+        title: 'Clear Volatile Brainlink Memory',
+        description: 'Clear active volatile memory for the current vault/agent namespace.',
+        inputSchema: volatileClearInputSchema
+    }, volatileClearTool);
     server.registerTool('brainlink_add_file', {
         title: 'Ingest Markdown File',
         description: 'Read a local markdown/text file and ingest it as a Brainlink note. Reindex defaults to true.',
         inputSchema: addFileInputSchema
     }, addFileTool);
+    server.registerTool('brainlink_canonicalize_context_links', {
+        title: 'Canonicalize Brainlink Context Links',
+        description: 'Ensure notes have canonical Context Links to inferred context hubs. Supports dry-run and can create missing hub notes.',
+        inputSchema: canonicalizeContextLinksInputSchema
+    }, canonicalizeContextLinksTool);
     server.registerTool('brainlink_index', {
         title: 'Index Brainlink Vault',
-        description: 'Rebuild the local Brainlink index from Markdown notes.',
+        description: 'Rebuild the local Brainlink index from Markdown notes. Pass full=true to force a complete source rebuild.',
         inputSchema: indexInputSchema
     }, indexTool);
     server.registerTool('brainlink_stats', {
@@ -85,6 +103,11 @@ export const createBrainlinkMcpServer = () => {
         description: 'Read indexed graph nodes and wiki-link edges. Edges include weight and priority fields so agents can rank importance and priority.',
         inputSchema: graphInputSchema
     }, graphTool);
+    server.registerTool('brainlink_graph_contexts', {
+        title: 'List Brainlink Graph Contexts',
+        description: 'List visual graph contexts used by the Brainlink server to separate memory domains such as preferences, repositories and machine configuration.',
+        inputSchema: graphContextsInputSchema
+    }, graphContextsTool);
     server.registerTool('brainlink_broken_links', {
         title: 'List Brainlink Broken Links',
         description: 'List unresolved indexed wiki links.',

package/dist/mcp/tools.js

@@ -3,15 +3,20 @@ 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';
 import { getBootstrapPolicy, getBootstrapSessionStatus, getContextSessionStatus, setBootstrapPolicy, touchBootstrapSession, touchContextSession } from '../infrastructure/session-state.js';
+import { getRuntimeMetadata } from './runtime.js';
 const positiveInteger = (fallback) => z
     .number()
     .int()
@@ -36,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);
@@ -118,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 = [
         {
@@ -174,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
@@ -189,6 +203,7 @@ const ensureContextReady = async (context, input, toolName) => {
         ...(context.agent ? { agent: context.agent } : {}),
         query: queryFromInput,
         mode,
+        strategy,
         limit,
         tokens
     };
@@ -215,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,
@@ -235,7 +257,25 @@ export const addNoteInputSchema = {
         .describe('Durable Markdown memory. Include explicit [[wiki links]] and #tags when the memory should be connected. Put priority markers near important links, for example priority: high, #important or #critical.'),
     ...agentInput,
     allowSensitive: z.boolean().optional().default(false).describe('Allow content that looks like a secret.'),
-    autoIndex: z.boolean().optional().default(true).describe('Reindex vault after writing note.')
+    autoIndex: z.boolean().optional().default(true).describe('Reindex vault after writing note.'),
+    autoContextLinks: z
+        .boolean()
+        .optional()
+        .describe('Automatically add canonical Context Links to the inferred visual context hub. Defaults to Brainlink config.')
+};
+export const volatileAddInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    content: z
+        .string()
+        .min(1)
+        .describe('Temporary agent-decided memory. Use for current task state, hypotheses, transient user preferences and unconfirmed findings.'),
+    ttlMinutes: optionalPositiveInteger().describe('Minutes before this volatile memory expires. Defaults to 240.'),
+    tags: z.array(z.string()).optional().default([]).describe('Optional tags for volatile retrieval.')
+};
+export const volatileClearInputSchema = {
+    ...vaultInput,
+    ...agentInput
 };
 export const addFileInputSchema = {
     ...vaultInput,
@@ -245,8 +285,20 @@ export const addFileInputSchema = {
     autoIndex: z.boolean().optional().default(true).describe('Reindex vault after ingesting file.'),
     allowSensitive: z.boolean().optional().default(false).describe('Allow content that looks like a secret.')
 };
+export const canonicalizeContextLinksInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    dryRun: z.boolean().optional().default(false).describe('Preview canonical context-link writes without changing Markdown.'),
+    createHubs: z.boolean().optional().default(true).describe('Create missing context hub notes when needed.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex after canonicalization when files changed.')
+};
 export const indexInputSchema = {
-    ...vaultInput
+    ...vaultInput,
+    full: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Force a complete reindex from Markdown source without reusing unchanged index entries.')
 };
 export const validateInputSchema = {
     ...vaultInput,
@@ -256,6 +308,10 @@ export const graphInputSchema = {
     ...vaultInput,
     ...agentInput
 };
+export const graphContextsInputSchema = {
+    ...vaultInput,
+    ...agentInput
+};
 export const brokenLinksInputSchema = {
     ...vaultInput,
     ...agentInput
@@ -273,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.')
 };
@@ -280,6 +337,7 @@ export const bootstrapInputSchema = {
     ...vaultInput,
     ...agentInput,
     ...searchModeInput,
+    ...contextStrategyInput,
     query: z
         .string()
         .min(1)
@@ -304,10 +362,15 @@ export const policyInputSchema = {
         .describe('Run automatic bootstrap during MCP server startup using configured default vault/agent.'),
     staleAfterMinutes: positiveInteger(120).describe('Bootstrap freshness window in minutes before read tools require a new bootstrap.')
 };
+export const versionInputSchema = {
+    ...vaultInput,
+    ...agentInput
+};
 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.')
@@ -333,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,
@@ -348,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');
@@ -376,7 +467,8 @@ export const addNoteTool = async (input) => {
     const context = await resolveExecutionContext(input);
     const shouldIndex = isTruthy(input.autoIndex);
     const added = await addNoteWithMetadata(context.vault, input.title, input.content, context.agent, {
-        allowSensitive: input.allowSensitive
+        allowSensitive: input.allowSensitive,
+        autoContextLinks: input.autoContextLinks ?? context.config.autoCanonicalContextLinks
     });
     const index = shouldIndex ? await indexVault(context.vault) : undefined;
     const focusPath = added.path.includes('agents/') ? added.path.slice(added.path.indexOf('agents/')).replaceAll('\\', '/') : undefined;
@@ -395,12 +487,33 @@ export const addNoteTool = async (input) => {
         writeConnectivity: {
             autoLinked: added.autoLinked,
             linkTarget: added.linkTarget,
-            guaranteedEdge: true
+            context: added.context,
+            hubCreated: added.hubCreated,
+            guaranteedEdge: added.autoLinked
         },
         possibleDuplicates,
         ...(index ? { index } : {})
     });
 };
+export const volatileAddTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const entry = await addVolatileMemory(context.vault, input.content, context.agent ?? 'shared', input.ttlMinutes ?? 240, input.tags);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        volatile: true,
+        entry
+    });
+};
+export const volatileClearTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const cleared = await clearVolatileMemory(context.vault, context.agent);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        cleared
+    });
+};
 export const addFileTool = async (input) => {
     const context = await resolveExecutionContext(input);
     const content = await readFile(input.filePath, 'utf8');
@@ -411,7 +524,8 @@ export const addFileTool = async (input) => {
     }
     const shouldIndex = isTruthy(input.autoIndex);
     const added = await addNoteWithMetadata(context.vault, title, content, context.agent, {
-        allowSensitive: input.allowSensitive
+        allowSensitive: input.allowSensitive,
+        autoContextLinks: context.config.autoCanonicalContextLinks
     });
     const index = shouldIndex ? await indexVault(context.vault) : undefined;
     return jsonResult({
@@ -423,14 +537,35 @@ export const addFileTool = async (input) => {
         writeConnectivity: {
             autoLinked: added.autoLinked,
             linkTarget: added.linkTarget,
-            guaranteedEdge: true
+            context: added.context,
+            hubCreated: added.hubCreated,
+            guaranteedEdge: added.autoLinked
         },
         ...(index ? { index } : {})
     });
 };
+export const canonicalizeContextLinksTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const result = await canonicalizeContextLinks(context.vault, {
+        agentId: context.agent,
+        dryRun: input.dryRun === true,
+        createMissingHubs: input.createHubs !== false
+    });
+    const index = input.autoIndex !== false && !result.dryRun && result.changed > 0
+        ? await indexVault(context.vault, { full: true })
+        : undefined;
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        ...result,
+        ...(index ? { index } : {})
+    });
+};
 export const indexTool = async (input) => {
     const context = await resolveExecutionContext(input);
-    const result = await indexVault(context.vault);
+    const result = await indexVault(context.vault, {
+        full: input.full === true
+    });
     return jsonResult({
         vault: context.vault,
         ...result
@@ -474,6 +609,25 @@ export const graphTool = async (input) => {
         ...graph
     });
 };
+export const graphContextsTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const readiness = await ensureBootstrapReady(context, input, 'brainlink_graph_contexts');
+    if (readiness.preflight) {
+        return readiness.preflight;
+    }
+    const contextReadiness = await ensureContextReady(context, input, 'brainlink_graph_contexts');
+    if (contextReadiness.preflight) {
+        return contextReadiness.preflight;
+    }
+    const contexts = await getGraphContexts(context.vault, context.agent);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
+        contexts
+    });
+};
 export const brokenLinksTool = async (input) => {
     const context = await resolveExecutionContext(input);
     const readiness = await ensureBootstrapReady(context, input, 'brainlink_broken_links');
@@ -561,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
         }
@@ -580,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
@@ -637,6 +794,7 @@ export const bootstrapTool = async (input) => {
                         ...(context.agent ? { agent: context.agent } : {}),
                         query: '<task>',
                         mode,
+                        strategy,
                         limit,
                         tokens
                     }
@@ -646,6 +804,7 @@ export const bootstrapTool = async (input) => {
         vault: context.vault,
         agent: context.agent,
         mode,
+        strategy,
         limit,
         tokens,
         index,
@@ -701,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
                 }
             }
         ];
@@ -716,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
                 }
@@ -725,12 +886,21 @@ export const policyTool = async (input) => {
     return jsonResult(withNextActions({
         vault: context.vault,
         agent: context.agent,
+        runtime: getRuntimeMetadata(),
         policy,
         bootstrapStatus,
         contextStatus,
         ...(input.preset ? { presetApplied: input.preset } : {})
     }, withContextAction));
 };
+export const versionTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        runtime: getRuntimeMetadata()
+    });
+};
 export const recommendationsTool = async (input) => {
     const context = await resolveExecutionContext(input);
     const policy = await getBootstrapPolicy();
@@ -738,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();
@@ -762,6 +933,7 @@ export const recommendationsTool = async (input) => {
                         vault: context.vault,
                         ...(context.agent ? { agent: context.agent } : {}),
                         mode,
+                        strategy,
                         ...(query ? { query } : {})
                     }
                 }
@@ -777,6 +949,7 @@ export const recommendationsTool = async (input) => {
                         ...(context.agent ? { agent: context.agent } : {}),
                         query: query ?? '<task>',
                         mode,
+                        strategy,
                         limit,
                         tokens
                     }
@@ -812,6 +985,7 @@ export const recommendationsTool = async (input) => {
                 ...(context.agent ? { agent: context.agent } : {}),
                 query: query ?? '<task>',
                 mode,
+                strategy,
                 limit,
                 tokens
             }
@@ -843,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,