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

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);
     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);
     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)
         : 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` and `defaultContextStrategy`.
 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,8 @@ Optional per-agent retrieval defaults in `brainlink.config.json`:
     "coding-agent": {
       "defaultSearchMode": "semantic",
       "defaultSearchLimit": 8,
-      "defaultContextTokens": 2400
+      "defaultContextTokens": 2400,
+      "defaultContextStrategy": "auto"
     }
   }
 }

package/package.json

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