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

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/build-context.js

@@ -1,5 +1,7 @@
 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';
@@ -15,14 +17,19 @@ 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 withCacheMetadata = (context, cache) => ({
+    ...context,
+    cache
 });
 const contextCacheGet = (key, dataSignature) => {
     const entry = contextCache.get(key);
@@ -34,7 +41,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 +56,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') => {
+    const totalStart = performance.now();
+    const cacheKey = toCacheKey(vaultPath, query, limit, maxTokens, agentId, mode, strategy);
     const dataSignature = await readContextDataSignature(vaultPath);
     const cached = contextCacheGet(cacheKey, dataSignature);
     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) => {
+    const contextPackage = await buildContextPackage(vaultPath, query, limit, maxTokens, agentId, mode, strategy);
     return contextPackage.content;
 };

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

@@ -1,14 +1,14 @@
 export const createClientCss = () => `:root {
-  color-scheme: light;
-  --bg: #eef2f7;
-  --panel: #ffffff;
-  --panel-strong: #f7f9fc;
-  --line: #d9e1ec;
-  --text: #172033;
-  --muted: #657386;
-  --accent: #0b6fcb;
-  --accent-weak: rgba(11, 111, 203, 0.12);
-  --danger: #d84949;
+  color-scheme: dark;
+  --bg: #071019;
+  --panel: #0d1823;
+  --panel-strong: #112130;
+  --line: rgba(143, 172, 204, 0.18);
+  --text: #edf4ff;
+  --muted: #97a9bd;
+  --accent: #5aa8ff;
+  --accent-weak: rgba(90, 168, 255, 0.18);
+  --danger: #ff6b6b;
 }
 
 * {
@@ -63,8 +63,8 @@ select {
   min-height: 72px;
   padding: 10px 16px;
   border-bottom: 1px solid var(--line);
-  background: rgba(255, 255, 255, 0.96);
-  box-shadow: 0 1px 8px rgba(23, 32, 51, 0.08);
+  background: rgba(9, 18, 28, 0.92);
+  box-shadow: 0 1px 14px rgba(1, 6, 13, 0.42);
   backdrop-filter: blur(8px);
 }
 
@@ -82,10 +82,14 @@ select {
   position: relative;
   width: 100%;
   height: 100%;
+  touch-action: none;
+  user-select: none;
+  -webkit-user-select: none;
   background:
-    linear-gradient(rgba(23, 32, 51, 0.035) 1px, transparent 1px),
-    linear-gradient(90deg, rgba(23, 32, 51, 0.035) 1px, transparent 1px),
-    #f6f8fb;
+    linear-gradient(rgba(164, 197, 230, 0.05) 1px, transparent 1px),
+    linear-gradient(90deg, rgba(164, 197, 230, 0.05) 1px, transparent 1px),
+    radial-gradient(circle at top, rgba(43, 93, 143, 0.22), transparent 44%),
+    #08131d;
   background-size: 28px 28px, 28px 28px, auto;
   overflow: hidden;
 }
@@ -96,6 +100,7 @@ select {
   inset: 0;
   width: 100%;
   height: 100%;
+  touch-action: none;
 }
 
 #graph {
@@ -131,21 +136,21 @@ select {
   max-width: 220px;
   transform: translate(-50%, calc(-100% - 12px));
   padding: 4px 8px;
-  border: 1px solid rgba(101, 115, 134, 0.24);
+  border: 1px solid rgba(143, 172, 204, 0.18);
   border-radius: 6px;
-  background: rgba(255, 255, 255, 0.92);
+  background: rgba(7, 16, 25, 0.92);
   color: var(--text);
   font-size: 11px;
   line-height: 1.25;
   white-space: nowrap;
   overflow: hidden;
   text-overflow: ellipsis;
-  box-shadow: 0 8px 22px rgba(23, 32, 51, 0.12);
+  box-shadow: 0 12px 28px rgba(1, 6, 13, 0.36);
 }
 
 .graph-label.is-focused {
-  border-color: rgba(11, 111, 203, 0.56);
-  color: #0b4f92;
+  border-color: rgba(90, 168, 255, 0.56);
+  color: #d7e9ff;
 }
 
 .graph-tooltip {
@@ -155,12 +160,12 @@ select {
   padding: 8px 10px;
   border: 1px solid var(--line);
   border-radius: 6px;
-  background: rgba(255, 255, 255, 0.96);
+  background: rgba(9, 18, 28, 0.96);
   color: var(--text);
   font-size: 12px;
   line-height: 1.35;
   pointer-events: none;
-  box-shadow: 0 16px 40px rgba(23, 32, 51, 0.18);
+  box-shadow: 0 18px 44px rgba(1, 6, 13, 0.42);
 }
 
 .graph-tooltip strong,
@@ -182,10 +187,10 @@ select {
   z-index: 3;
   width: 180px;
   height: 120px;
-  border: 1px solid rgba(129, 146, 170, 0.28);
+  border: 1px solid rgba(143, 172, 204, 0.18);
   border-radius: 8px;
-  background: rgba(255, 255, 255, 0.88);
-  box-shadow: 0 16px 42px rgba(23, 32, 51, 0.16);
+  background: rgba(8, 19, 29, 0.84);
+  box-shadow: 0 18px 40px rgba(1, 6, 13, 0.36);
 }
 
 .eyebrow {
@@ -218,7 +223,7 @@ select {
   border: 1px solid var(--line);
   border-radius: 8px;
   outline: none;
-  background: rgba(255, 255, 255, 0.94);
+  background: rgba(12, 24, 36, 0.94);
   color: var(--text);
   padding: 0 14px;
 }
@@ -239,7 +244,7 @@ select {
   height: 38px;
   border: 1px solid var(--line);
   border-radius: 8px;
-  background: rgba(255, 255, 255, 0.94);
+  background: rgba(12, 24, 36, 0.94);
   color: var(--text);
   cursor: pointer;
 }
@@ -260,7 +265,7 @@ select {
   padding: 10px 12px;
   border: 1px solid var(--line);
   border-radius: 10px;
-  background: rgba(255, 255, 255, 0.94);
+  background: rgba(12, 24, 36, 0.94);
   display: grid;
   gap: 3px;
 }
@@ -335,7 +340,7 @@ li small {
   padding: 12px;
   border: 1px solid var(--line);
   border-radius: 8px;
-  background: #f8fafc;
+  background: #091521;
   color: var(--text);
   white-space: pre-wrap;
   overflow: auto;
@@ -366,6 +371,7 @@ li small {
   background: var(--panel);
   color: var(--text);
   box-shadow: 0 24px 80px rgba(23, 32, 51, 0.22);
+  backdrop-filter: blur(10px);
   overflow: hidden;
 }
 
@@ -469,7 +475,7 @@ li small {
   padding: 10px;
   border: 1px solid var(--line);
   border-radius: 8px;
-  background: #f8fafc;
+  background: #091521;
   display: grid;
   grid-template-rows: auto minmax(0, 1fr);
   gap: 8px;
@@ -509,7 +515,7 @@ li small {
   display: flex;
   align-items: center;
   justify-content: center;
-  background: transparent;
+  background: linear-gradient(180deg, rgba(7, 16, 25, 0), rgba(7, 16, 25, 0.84));
 }
 
 .app-footer small {