@andespindola/brainlink 1.0.4 → 1.0.5

package/README.md

@@ -569,7 +569,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 MCP context tools are plug-and-play by default: omit `strategy` to use the configured token-efficient default (`auto` unless changed), pass `strategy: "cag"` for repeated/stable task context, or pass `strategy: "rag"` when fresh retrieval is required. `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.
 
@@ -657,8 +657,8 @@ Routes:
 - `GET /api/graph-view?x=<x>&y=<y>&w=<width>&h=<height>&scale=<scale>`
 - `GET /api/graph-stream?x=<x>&y=<y>&w=<width>&h=<height>&scale=<scale>&nodeBudget=<n>&edgeBudget=<n>`
 - `GET /api/graph-node?id=<node-id>`
-- `GET /api/search?q=<query>&limit=10&mode=hybrid`
-- `GET /api/context?q=<query>&limit=12&tokens=2000&mode=hybrid`
+- `GET /api/search?q=<query>&limit=8&mode=hybrid`
+- `GET /api/context?q=<query>&limit=8&tokens=1500&mode=hybrid`
 - `GET /api/links`
 - `GET /api/backlinks?title=<title>`
 - `GET /api/stats`
@@ -936,7 +936,7 @@ Context selection uses a middle-out strategy: it starts from the strongest chunk
 ### `context`
 
 ```bash
-blink context "question" --vault ./vault --limit 12 --tokens 2000
+blink context "question" --vault ./vault --limit 8 --tokens 1500
 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
@@ -947,7 +947,7 @@ 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.
+The default strategy is configured by `defaultContextStrategy` and starts as `auto`, which uses CAG when a fresh pack exists and RAG otherwise, refreshing a pack for future calls. `--strategy cag` enables cache-augmented context generation by reading or refreshing a persisted context pack under `.brainlink/context-packs`; `--strategy rag` forces fresh retrieval assembly from the current index. 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`
 
@@ -1088,9 +1088,9 @@ If no `vault` is configured and no `--vault` flag is passed, Brainlink uses `$HO
   "defaultAgent": "shared",
   "autoIndexOnWrite": true,
   "autoCanonicalContextLinks": true,
-  "defaultSearchLimit": 10,
-  "defaultContextTokens": 2000,
-  "defaultContextStrategy": "rag",
+  "defaultSearchLimit": 8,
+  "defaultContextTokens": 1500,
+  "defaultContextStrategy": "auto",
   "embeddingProvider": "local",
   "defaultSearchMode": "hybrid",
   "chunkSize": 1200,
@@ -1105,7 +1105,7 @@ If no `vault` is configured and no `--vault` flag is passed, Brainlink uses `$HO
     "coding-agent": {
       "defaultSearchMode": "semantic",
       "defaultSearchLimit": 8,
-      "defaultContextTokens": 2400,
+      "defaultContextTokens": 1500,
       "defaultContextStrategy": "auto"
     },
     "*": {

package/dist/application/server/routes.js

@@ -24,19 +24,20 @@ import { createClientWorkerJs } from '../frontend/client-worker-js.js';
 import { createClientRenderWorkerJs } from '../frontend/client-render-worker-js.js';
 import { contentTypes, createJsonResponse, isReadMethod, parsePositiveInteger } from './http.js';
 import { parseMultipartForm } from './multipart.js';
-const readSearchMode = async (url) => {
+const readRuntimeDefaults = async (url) => {
     const config = await loadBrainlinkConfig();
-    const defaults = resolveAgentRuntimeDefaults(config, readAgentQuery(url));
+    return resolveAgentRuntimeDefaults(config, readAgentQuery(url));
+};
+const readSearchMode = async (url) => {
+    const defaults = await readRuntimeDefaults(url);
     return sanitizeSearchMode(url.searchParams.get('mode'), defaults.defaultSearchMode);
 };
 const readContextStrategy = async (url) => {
-    const config = await loadBrainlinkConfig();
-    const defaults = resolveAgentRuntimeDefaults(config, readAgentQuery(url));
+    const defaults = await readRuntimeDefaults(url);
     return sanitizeContextStrategy(url.searchParams.get('strategy'), defaults.defaultContextStrategy);
 };
 const readContextCacheTtlMs = async (url) => {
-    const config = await loadBrainlinkConfig();
-    const defaults = resolveAgentRuntimeDefaults(config, readAgentQuery(url));
+    const defaults = await readRuntimeDefaults(url);
     return defaults.defaultContextCacheTtlMs;
 };
 const hasInvalidSearchMode = (url) => {
@@ -428,7 +429,8 @@ export const route = async (request, url, vaultPath) => {
     }
     if (isReadMethod(request) && url.pathname === '/api/search') {
         const query = url.searchParams.get('q') ?? '';
-        const limit = parsePositiveInteger(url.searchParams.get('limit'), 10);
+        const defaults = await readRuntimeDefaults(url);
+        const limit = parsePositiveInteger(url.searchParams.get('limit'), defaults.defaultSearchLimit);
         const mode = await readSearchMode(url);
         if (hasInvalidSearchMode(url)) {
             return createResponse(createJsonResponse({ error: 'Invalid mode. Use fts, semantic or hybrid.' }), 400, contentTypes['.json']);
@@ -437,8 +439,9 @@ export const route = async (request, url, vaultPath) => {
     }
     if (isReadMethod(request) && url.pathname === '/api/context') {
         const query = url.searchParams.get('q') ?? '';
-        const limit = parsePositiveInteger(url.searchParams.get('limit'), 12);
-        const tokens = parsePositiveInteger(url.searchParams.get('tokens'), 2000);
+        const defaults = await readRuntimeDefaults(url);
+        const limit = parsePositiveInteger(url.searchParams.get('limit'), defaults.defaultSearchLimit);
+        const tokens = parsePositiveInteger(url.searchParams.get('tokens'), defaults.defaultContextTokens);
         const mode = await readSearchMode(url);
         const strategy = await readContextStrategy(url);
         const contextCacheTtlMs = await readContextCacheTtlMs(url);

package/dist/infrastructure/config.js

@@ -11,9 +11,9 @@ export const defaultBrainlinkConfig = {
     defaultAgent: undefined,
     autoIndexOnWrite: true,
     autoCanonicalContextLinks: true,
-    defaultSearchLimit: 10,
-    defaultContextTokens: 2000,
-    defaultContextStrategy: 'rag',
+    defaultSearchLimit: 8,
+    defaultContextTokens: 1500,
+    defaultContextStrategy: 'auto',
     defaultContextCacheTtlMs: 120_000,
     embeddingProvider: 'local',
     defaultSearchMode: 'hybrid',
@@ -46,7 +46,7 @@ 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;
+export const sanitizeContextStrategy = (value, fallback = defaultBrainlinkConfig.defaultContextStrategy) => 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) => {

package/docs/AGENT_USAGE.md

@@ -585,7 +585,7 @@ Context assembly uses middle-out ordering inside each note: the highest-scoring
 ### Build Agent Context
 
 ```bash
-blink context "how does authentication work?" --vault ./vault --limit 12 --tokens 2000
+blink context "how does authentication work?" --vault ./vault --limit 8 --tokens 1500
 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
@@ -596,7 +596,7 @@ 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.
+The default strategy is configured by `defaultContextStrategy` and starts as `auto`, so repeated stable context can reuse fresh CAG packs while misses fall back to RAG and refresh a pack for later calls. Use `--strategy cag` when the same agent/task context must be served from a persisted context pack when the index and volatile-memory signatures are unchanged. Use `--strategy rag` when fresh retrieval is required. Context responses include `cache`, `metrics`, `requestedStrategy` and `recommendedStrategy` metadata. CAG packs live under `.brainlink/context-packs` and are rebuildable derived artifacts.
 
 ### Inspect Links
 
@@ -778,8 +778,8 @@ GET  /api/graph-layout
 GET  /api/graph-view?x=<x>&y=<y>&w=<width>&h=<height>&scale=<scale>
 GET  /api/graph-node?id=<node-id>
 GET  /api/graph-filter?q=<query>&limit=<n>
-GET  /api/search?q=<query>&limit=10&mode=hybrid
-GET  /api/context?q=<query>&limit=12&tokens=2000&mode=hybrid
+GET  /api/search?q=<query>&limit=8&mode=hybrid
+GET  /api/context?q=<query>&limit=8&tokens=1500&mode=hybrid
 GET  /api/links
 GET  /api/backlinks?title=<title>
 GET  /api/stats

package/docs/QUICKSTART.md

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

package/package.json

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