@andespindola/brainlink 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -1,6 +1,20 @@
 # Changelog
 
-## Unreleased
+## 1.3.0
+
+- **MCP server instructions on connect.** The server now advertises `instructions` in its initialize response, so clients that surface them (e.g. Claude Code) inject Brainlink's memory discipline into the agent's context the moment it connects — treat Brainlink as the default context source for everything, bootstrap first with a task query, use the full toolkit (both RAG and CAG via `strategy: auto`, context packs, hybrid search, the knowledge graph, explain/recommendations/validate/stats) instead of shallow retrieval, keep ephemeral facts in volatile memory, and persist durable learnings as connected notes. The field is advisory (clients that ignore it are unaffected) and no tool contract changed.
+
+## 1.2.0
+
+- **Reciprocal Rank Fusion for hybrid search.** Hybrid mode now fuses the lexical (BM25) and semantic rankings by rank position (`Σ 1/(k+rank)`, k=60) instead of a fixed `0.6/0.4` min-max blend, which is robust to the two components' very different score scales. Gated by a new `hybridFusion` config (`rrf` default | `linear`); `fts`/`semantic` modes and stored data are unchanged.
+- **Per-document CAG invalidation.** Persisted context packs now record the documents they were assembled from and are fresh only while each cited document is unchanged, so editing one note refreshes only the packs that cite it instead of the whole cache. A new optional `cagPackTtlMs` bounds pack lifetime as a safety net for newly added notes. Freshness is evaluated with a few `stat`s and no index load.
+- **int8 ANN with partial exact-vector reads (binary backend).** Search loads a compact int8 scan index and reads the exact Float32 vectors by offset only for the shortlist it reranks (embedding-bucket coarse prune → int8 scan → exact Float32 rerank), so the exact vectors never become fully resident on a large vault. Small vaults rerank every candidate exactly, staying bit-identical to a full scan; `fts` reads no vectors.
+- **The binary storage backend is now the default** (`storageBackend: "binary"`). Existing `json` vaults auto-migrate on first use (no re-embedding), and switching backends forces a one-time full reindex so the index is rewritten in the active format. The in-memory search/context caches key on a backend-agnostic commit signature (fixing a stale-read window on the binary backend). The `json` backend remains available.
+- **Vault versioning over MCP.** `brainlink_vault_status` / `_init` / `_commit` / `_history` / `_pull` / `_restore` / `_export` / `_import` expose the git and `.blvault` versioning to agents (previously CLI-only); pull/restore/import reindex automatically.
+- **Self-managed versioning repository.** `brainlink_vault_provision` / `blink vault-provision` create a private GitHub repository for the vault with the authenticated `gh` CLI, wire it as origin, push the first snapshot, and enable `autoVersion` — after which a successful index that changed Markdown commits and pushes automatically (best-effort; a git/network failure never breaks indexing).
+- **Encrypted vault versioning.** With `vaultEncryption` (enabled by `vault-provision` by default), the git repository holds AES-256-GCM ciphertext (`<note>.md.enc`) and git-ignores the plaintext Markdown, so the repository is opaque to anyone without the per-vault key (in `$BRAINLINK_HOME/keys`, never committed, or via `BRAINLINK_VAULT_KEY`). Encryption is deterministic per note (no git churn); pull/restore/clone decrypt back to Markdown before reindexing.
+
+## 1.1.0
 
 - Added an optional **binary storage backend** (`storageBackend: "binary"`) that stores chunk embeddings as dense little-endian Float32 (`vectors.f32`) and document/chunk/link metadata as Brotli-compressed JSON, cutting the on-disk index ~75% on a typical vault with much cheaper loads than parsing decimal-text vectors. The graph/search/link reads now run through a shared query core so the JSON and binary backends are behavior-identical for the same candidates. Switching to `binary` converts an existing `index.json` in place on first use (no re-embedding) and falls back to it for reads until the binary store is materialized. The canonical Markdown is unaffected and the index stays fully regenerable.
 - Introduced a `KnowledgeStore` port and a shared, backend-agnostic ranker, so the index storage layout can evolve without touching the application layer and every backend produces an identical ranking.

package/README.md

@@ -71,7 +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.
+- Optional CAG context packs at `.brainlink/context-packs/*.json`, invalidated per cited document (editing one note only refreshes the packs that cite it) 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.
@@ -560,6 +560,9 @@ Available tools:
 - `brainlink_doctor_actions`: return vault checks plus prioritized executable next actions.
 - `brainlink_validate`: validate broken links and orphan notes.
 - `brainlink_sync`: run index, stats, validation, broken-link and orphan checks in one call.
+- `brainlink_vault_provision`: create a private GitHub repository for the vault with the authenticated `gh` CLI, wire it as `origin`, push the first snapshot, and enable `autoVersion` so later indexed changes are committed and pushed automatically. By default the repository is **encrypted** (`vaultEncryption`): it holds AES-256-GCM ciphertext, decryptable only by a Brainlink instance with the local key.
+- `brainlink_vault_status` / `brainlink_vault_init` / `brainlink_vault_commit` / `brainlink_vault_history` / `brainlink_vault_pull` / `brainlink_vault_restore`: version the vault's canonical Markdown with git (the derived index is git-ignored). Pull and restore reindex changed files automatically so the vault stays immediately searchable.
+- `brainlink_vault_export` / `brainlink_vault_import`: write and read a portable `.blvault` snapshot (gzip envelope of the Markdown with per-file SHA-256). Import verifies checksums, preserves divergent local files as `*.conflict-<ts>.md`, and reindexes.
 - `brainlink_graph`: read indexed graph nodes and weighted links.
 - `brainlink_graph_contexts`: list the visual graph contexts used by the local server.
 - `brainlink_broken_links`: list unresolved wiki links.
@@ -763,11 +766,24 @@ Use `--global` to write to `$BRAINLINK_HOME/brainlink.config.json`, `--no-migrat
 
 `storageBackend` selects how the derived index is stored (the canonical Markdown is unaffected):
 
-- `json` (default) — the original single `index.json`.
-- `binary` — Float32 vectors plus Brotli-compressed metadata; a smaller, faster-to-load index (~75% smaller on a typical vault). Switching is seamless: an existing `index.json` is converted in place on first use (no re-embedding) and reads fall back to it until then.
+- `binary` (default) — Float32 vectors plus Brotli-compressed metadata; a smaller, faster-to-load index (~75% smaller on a typical vault). Switching is seamless: an existing `index.json` is converted in place on first use (no re-embedding), and changing the backend forces a one-time full reindex so the index is rewritten in the active format. On large vaults, semantic/hybrid search uses an approximate-nearest-neighbour path — a compact int8 vector scan (with embedding-bucket coarse pruning) shortlists candidates, and only that shortlist's exact Float32 vectors are read from disk and reranked, so the exact vectors never become fully resident. Small vaults rerank every candidate exactly, staying bit-identical to a full scan.
+- `json` — the original single `index.json`. Larger and loaded whole, but a simple, human-readable artifact.
 
 ```json
-{ "storageBackend": "binary" }
+{ "storageBackend": "json" }
+```
+
+#### Hybrid fusion
+
+`hybridFusion` selects how the lexical (BM25) and semantic (cosine) rankings are combined in `hybrid` search mode:
+
+- `rrf` (default) — Reciprocal Rank Fusion. Combines the two rankings by rank position (`Σ 1/(k + rank)`), so a document both retrievers agree on ranks highly regardless of the very different score scales of BM25 and cosine. No weight tuning required.
+- `linear` — the legacy min-max normalized weighted blend (`0.6·lexical + 0.4·semantic`).
+
+`fts` and `semantic` modes are unaffected. The change is additive: existing vaults need no reindex.
+
+```json
+{ "hybridFusion": "linear" }
 ```
 
 ### `vaults`
@@ -930,6 +946,12 @@ The derived `.brainlink/` directory is never versioned; any operation that chang
 Markdown reindexes automatically so the vault stays immediately usable.
 
 ```bash
+# One-shot: create an ENCRYPTED private GitHub repo (via authenticated gh),
+# push, and enable autoVersion so later indexed changes commit and push
+# automatically. The repo holds AES-256-GCM ciphertext; only a Brainlink
+# instance with the local key can decrypt. Use --no-encrypt for plaintext.
+blink vault-provision --name brainlink-vault
+
 # Git: history, remotes, restore
 blink vault-init-git --remote git@github.com:you/your-vault.git
 blink vault-commit -m "snapshot notes"
@@ -990,7 +1012,9 @@ 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 `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.
+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 invalidated **per cited document**: a pack becomes stale only when one of the documents it was assembled from (or volatile memory) changes, so editing a single note no longer invalidates every pack. `cagPackTtlMs` (default `0`, disabled) sets an optional upper bound in milliseconds on how long a pack survives even when all its cited documents are unchanged — a safety net for a newly added note that would now rank into the result but is not among the pack's existing dependencies.
 
 ### `links`
 
@@ -1164,6 +1188,8 @@ If no `vault` is configured and no `--vault` flag is passed, Brainlink uses `$HO
 `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.
+`autoVersion` is optional and defaults to `false`. When enabled (e.g. by `blink vault-provision` / `brainlink_vault_provision`), a successful index that changed Markdown commits and pushes the vault to its git remote automatically, best-effort — a git or network failure is logged and never breaks indexing. It is a no-op unless the vault is a git repo with an `origin` remote.
+`vaultEncryption` is optional and defaults to `false`. When enabled, vault versioning commits AES-256-GCM ciphertext (`<note>.md.enc`) and git-ignores the plaintext Markdown, so the repository is opaque to anyone without the key — only a Brainlink instance holding the per-vault key can decrypt it. The key lives at `$BRAINLINK_HOME/keys/vault-versioning-<hash>.key` (outside the vault, never committed) or can be supplied via `BRAINLINK_VAULT_KEY` to restore an encrypted vault on another machine. Pull, restore and clone decrypt back to Markdown before reindexing; encryption is deterministic per note, so unchanged notes add no git churn. `blink vault-provision` enables this by default.
 `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.
 `autoUpdateCheck` is optional and defaults to `true`. Brainlink checks the npm registry no more often than `updateCheckIntervalMs` and prints an update notice to `stderr`; it never installs updates automatically.
 

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', undefined, defaults.defaultContextCacheTtlMs);
+    await buildContextPackage(absoluteVaultPath, probeQuery, Math.min(defaults.defaultSearchLimit, 8), defaults.defaultContextTokens, agentId, 'hybrid', undefined, defaults.defaultContextCacheTtlMs, defaults.cagPackTtlMs);
     const contextLatency = performance.now() - contextStart;
     return {
         stats,

package/dist/application/build-context.js

@@ -2,7 +2,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 { indexCommitSignature } from '../infrastructure/index-signature.js';
 import { searchVolatileMemory, volatileMemoryStoragePath } from '../infrastructure/volatile-memory.js';
 import { searchKnowledge } from './search-knowledge.js';
 const contextCacheMaxEntries = 200;
@@ -16,7 +16,12 @@ const readFileSignature = async (path) => {
         return '0:0';
     }
 };
-export const readContextDataSignature = async (vaultPath) => `${await readFileSignature(indexStoragePath(vaultPath))}|${await readFileSignature(volatileMemoryStoragePath(vaultPath))}`;
+export const readContextDataSignature = async (vaultPath) => `${await indexCommitSignature(vaultPath)}|${await readFileSignature(volatileMemoryStoragePath(vaultPath))}`;
+// Signature of just the volatile-memory file. Disk context packs no longer gate
+// on the whole-vault index signature (that invalidated every pack on any edit);
+// they gate per cited document plus this volatile signature, so turn memory
+// changes still refresh a pack while unrelated document edits do not.
+export const readVolatileSignature = (vaultPath) => readFileSignature(volatileMemoryStoragePath(vaultPath));
 const toCacheKey = (vaultPath, query, limit, maxTokens, agentId, mode, strategy) => JSON.stringify({
     vaultPath,
     query: query.trim().toLowerCase(),
@@ -69,7 +74,7 @@ const emptyMetrics = (context, totalMs, overrides = {}) => ({
     estimatedTokens: estimateSectionTokens(context),
     ...overrides
 });
-export const buildContextPackage = async (vaultPath, query, limit, maxTokens, agentId, mode, strategy = 'rag', contextCacheTtlMs = 120_000) => {
+export const buildContextPackage = async (vaultPath, query, limit, maxTokens, agentId, mode, strategy = 'rag', contextCacheTtlMs = 120_000, cagPackTtlMs = 0) => {
     const totalStart = performance.now();
     const cacheKey = toCacheKey(vaultPath, query, limit, maxTokens, agentId, mode, strategy);
     const dataSignature = await readContextDataSignature(vaultPath);
@@ -78,10 +83,12 @@ export const buildContextPackage = async (vaultPath, query, limit, maxTokens, ag
         return cached;
     }
     const shouldUseContextPack = strategy === 'cag' || strategy === 'auto';
+    const volatileSignature = await readVolatileSignature(vaultPath);
+    const packFreshness = { volatileSignature, ttlMs: cagPackTtlMs };
     let packReadMs = 0;
     if (shouldUseContextPack) {
         const packReadStart = performance.now();
-        const pack = await readContextPack(vaultPath, { query, limit, maxTokens, agentId, mode }, dataSignature);
+        const pack = await readContextPack(vaultPath, { query, limit, maxTokens, agentId, mode }, packFreshness);
         packReadMs = elapsedMs(packReadStart);
         if (pack.status === 'hit' && pack.context.sections.length > 0) {
             const contextFromPack = {
@@ -139,7 +146,7 @@ export const buildContextPackage = async (vaultPath, query, limit, maxTokens, ag
     const hasSections = sections.length > 0;
     const packWriteStart = performance.now();
     const packPath = shouldUseContextPack && hasSections
-        ? await writeContextPack(vaultPath, { query, limit, maxTokens, agentId, mode }, dataSignature, context)
+        ? await writeContextPack(vaultPath, { query, limit, maxTokens, agentId, mode }, context, { volatileSignature })
         : undefined;
     const packWriteMs = packPath ? elapsedMs(packWriteStart) : 0;
     const contextWithMetadata = withCacheMetadata(context, {
@@ -169,7 +176,7 @@ export const buildContextPackage = async (vaultPath, query, limit, maxTokens, ag
     }
     return contextWithMetrics;
 };
-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);
+export const buildContext = async (vaultPath, query, limit, maxTokens, agentId, mode, strategy, contextCacheTtlMs = 120_000, cagPackTtlMs = 0) => {
+    const contextPackage = await buildContextPackage(vaultPath, query, limit, maxTokens, agentId, mode, strategy, contextCacheTtlMs, cagPackTtlMs);
     return contextPackage.content;
 };

package/dist/application/index-vault-phases.js

@@ -72,6 +72,7 @@ export const detectChanges = (params) => {
     const settingsChanged = previousState == null ||
         previousState.chunkSize !== config.chunkSize ||
         previousState.embeddingProvider !== embeddingSignature(config) ||
+        previousState.storageBackend !== config.storageBackend ||
         graphLinkModelChanged;
     const packSettingsChanged = previousState == null ||
         previousState.searchPackRowChunkSize !== config.searchPack.rowChunkSize ||

package/dist/application/index-vault.js

@@ -5,6 +5,7 @@ import { ensureVault, readMarkdownFileSummaries } from '../infrastructure/file-s
 import { readIndexState, writeIndexState } from '../infrastructure/index-state.js';
 import { ensureSearchPackManifest } from '../infrastructure/search-packs.js';
 import { openKnowledgeStore } from '../infrastructure/knowledge-store/index.js';
+import { autoVersionVault } from './vault-git-core.js';
 import { assembleIndexedDocuments, createTitleMaps, decidePackRebuild, detectChanges, embedChangedDocuments, rebuildSearchPacksIfNeeded } from './index-vault-phases.js';
 const toIndexResult = (documents) => ({
     documentCount: documents.length,
@@ -162,6 +163,7 @@ export const indexVaultWithOptions = async (vaultPath, options) => {
         await writeIndexState(absoluteVaultPath, {
             chunkSize: config.chunkSize,
             embeddingProvider: embeddingSignature(config),
+            storageBackend: config.storageBackend,
             graphLinkModelVersion,
             searchPackRowChunkSize: config.searchPack.rowChunkSize,
             searchPackCompressionLevel: config.searchPack.compressionLevel,
@@ -169,6 +171,18 @@ export const indexVaultWithOptions = async (vaultPath, options) => {
             files: currentSnapshot,
             pendingPackChanges: packsRebuilt ? 0 : pendingPackChanges
         });
+        // Auto-version the vault when enabled and Markdown actually changed. Runs
+        // after the index is committed, is best-effort (a git/network failure never
+        // breaks indexing), and is a no-op unless the vault is a git repo with an
+        // origin remote — commitVault itself skips when nothing is staged.
+        if (config.autoVersion && changedDocumentsByPath.size > 0) {
+            try {
+                await autoVersionVault(absoluteVaultPath, `chore(vault): update ${new Date().toISOString()}`);
+            }
+            catch (error) {
+                process.stderr.write(`brainlink: auto-version skipped (${error instanceof Error ? error.message : String(error)})\n`);
+            }
+        }
         const result = {
             ...toIndexResult(indexedDocuments),
             elapsedMs: elapsedMs(),

package/dist/application/provision-vault.js

@@ -0,0 +1,74 @@
+// Provision a private GitHub repository for the vault using the already
+// authenticated `gh` CLI, wire it as origin, push the first snapshot, and enable
+// auto-versioning so later changes are committed and pushed automatically. Only
+// the canonical Markdown is versioned; the derived index stays git-ignored.
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { loadRawConfig, writeRawConfig } from '../infrastructure/config.js';
+import { commitVault, hasRemote, initVaultGit, pushVault } from './vault-git-core.js';
+const execFileAsync = promisify(execFile);
+export class GhUnavailableError extends Error {
+    constructor() {
+        super('gh executable not found. Install and authenticate the GitHub CLI (gh auth login) to provision a vault repo.');
+        this.name = 'GhUnavailableError';
+    }
+}
+export class GhCommandError extends Error {
+    constructor(args, stderr) {
+        super(`gh ${args.join(' ')} failed: ${stderr.trim() || 'unknown error'}`);
+        this.name = 'GhCommandError';
+    }
+}
+const isMissingBinary = (error) => error instanceof Error && 'code' in error && error.code === 'ENOENT';
+const runGh = async (cwd, args) => {
+    try {
+        const { stdout } = await execFileAsync('gh', [...args], { cwd, maxBuffer: 16 * 1024 * 1024 });
+        return stdout;
+    }
+    catch (error) {
+        if (isMissingBinary(error)) {
+            throw new GhUnavailableError();
+        }
+        const stderr = error.stderr ?? (error instanceof Error ? error.message : String(error));
+        throw new GhCommandError(args, stderr);
+    }
+};
+// Fail early with an actionable message if gh is not authenticated, rather than
+// letting `repo create` fail deep in the flow.
+const assertGhAuthenticated = async (cwd) => {
+    await runGh(cwd, ['auth', 'status']);
+};
+// Persist config toggles to the global config. Global scope matches the common
+// case of a single default vault; a project-local vault can set these in its own
+// config. Written BEFORE the first commit so the initial snapshot is encrypted
+// and the gitignore is correct from the start.
+const mergeGlobalConfig = async (patch) => {
+    const current = await loadRawConfig('global');
+    await writeRawConfig('global', { ...current, ...patch });
+};
+export const provisionVaultRepo = async (vaultPath, options = {}) => {
+    const name = options.name ?? 'brainlink-vault';
+    const enableAutoVersion = options.enableAutoVersion !== false;
+    const encrypt = options.encrypt !== false;
+    // Toggle config first so initVaultGit/commitVault encrypt from the very first
+    // snapshot and git-ignore the plaintext Markdown.
+    await mergeGlobalConfig({
+        ...(encrypt ? { vaultEncryption: true } : {}),
+        ...(enableAutoVersion ? { autoVersion: true } : {})
+    });
+    const { root } = await initVaultGit(vaultPath);
+    const committed = await commitVault(vaultPath, options.message ?? 'chore(vault): initial snapshot');
+    // A pre-existing origin means the repo is already provisioned: just push the
+    // current state. Only creating a new repository needs gh, so the reuse path
+    // works without it.
+    const created = !(await hasRemote(root));
+    if (created) {
+        await assertGhAuthenticated(root);
+        const visibility = options.private === false ? '--public' : '--private';
+        await runGh(root, ['repo', 'create', name, visibility, '--source', root, '--remote', 'origin', '--push']);
+    }
+    else {
+        await pushVault(vaultPath);
+    }
+    return { repo: name, created, committed, pushed: true, autoVersionEnabled: enableAutoVersion, encrypted: encrypt };
+};

package/dist/application/ranking/run-search.js

@@ -33,6 +33,10 @@ const pathFieldWeight = 2;
 const contentHitCap = 6;
 const hybridTextWeight = 0.6;
 const hybridSemanticWeight = 0.4;
+// Rank-fusion damping constant (Cormack et al.). 60 is the field-standard value:
+// large enough that the top ranks are not wildly separated, small enough that a
+// document ranked highly by one retriever still clearly outweighs low ranks.
+const rrfConstant = 60;
 const normalizeFields = (row) => ({
     title: normalizeToken(row.title),
     path: normalizeToken(row.path),
@@ -110,10 +114,35 @@ const toResult = (row, mode, score, text, semantic) => ({
     searchMode: mode,
     tags: row.tags
 });
+// Reciprocal Rank Fusion: rank the candidates independently by each component
+// (lexical, semantic) and fuse by rank position, `Σ 1/(k + rank)`. Because it
+// consumes ranks rather than raw magnitudes it is immune to the scale mismatch
+// between unbounded BM25 and bounded cosine, so a strong lexical hit and a
+// strong semantic hit contribute comparably without hand-tuned weights. A
+// candidate absent from a component's ranking (zero score there) simply
+// contributes nothing for that component. Ties break by title to stay
+// deterministic, matching the final ordering.
+const reciprocalRankFusion = (entries) => {
+    const ranksByField = (component) => {
+        const ranked = entries
+            .filter((entry) => component(entry) > 0)
+            .slice()
+            .sort((left, right) => component(right) - component(left) || left.row.title.localeCompare(right.row.title));
+        return new Map(ranked.map((entry, index) => [entry, index + 1]));
+    };
+    const textRanks = ranksByField((entry) => entry.text);
+    const semanticRanks = ranksByField((entry) => entry.semantic);
+    return new Map(entries.map((entry) => {
+        const textRank = textRanks.get(entry);
+        const semanticRank = semanticRanks.get(entry);
+        const score = (textRank ? 1 / (rrfConstant + textRank) : 0) + (semanticRank ? 1 / (rrfConstant + semanticRank) : 0);
+        return [entry, score];
+    }));
+};
 // Rank an already-selected candidate set. Backends own candidate selection
 // (full scan, bucket prefilter, ANN); this function owns scoring and ordering so
 // the result is identical regardless of how the candidates were gathered.
-export const runSearch = (candidates, query, limit, mode, queryEmbedding = []) => {
+export const runSearch = (candidates, query, limit, mode, queryEmbedding = [], fusion = 'rrf') => {
     const tokens = tokenize(query);
     // Pass 1: field-weighted term frequencies per candidate, then corpus-wide
     // statistics (document frequency, average length) needed for BM25 IDF and
@@ -156,6 +185,9 @@ export const runSearch = (candidates, query, limit, mode, queryEmbedding = []) =
     }
     const textRange = rangeOf(relevant.map((entry) => entry.text));
     const semanticRange = rangeOf(relevant.map((entry) => entry.semantic));
+    // Rank-fused hybrid scores are precomputed once over the whole candidate set
+    // (RRF needs each component's global ranking); other modes score per entry.
+    const rrfScores = mode === 'hybrid' && fusion === 'rrf' ? reciprocalRankFusion(relevant) : null;
     const finalScore = (entry) => {
         if (mode === 'fts') {
             return entry.text;
@@ -163,8 +195,11 @@ export const runSearch = (candidates, query, limit, mode, queryEmbedding = []) =
         if (mode === 'semantic') {
             return entry.semantic;
         }
-        // Hybrid mixes the two components on a shared [0, 1] scale so neither the
-        // unbounded BM25 magnitude nor the bounded cosine value can swamp the
+        if (rrfScores) {
+            return rrfScores.get(entry) ?? 0;
+        }
+        // Linear hybrid mixes the two components on a shared [0, 1] scale so neither
+        // the unbounded BM25 magnitude nor the bounded cosine value can swamp the
         // other, replacing the previous fixed `text + semantic * 8` blend.
         const textNorm = minMaxNormalize(entry.text, textRange.min, textRange.max);
         const semanticNorm = minMaxNormalize(entry.semantic, semanticRange.min, semanticRange.max);

package/dist/application/search-knowledge.js

@@ -1,7 +1,6 @@
-import { stat } from 'node:fs/promises';
 import { ensureVault } from '../infrastructure/file-system-vault.js';
 import { ensurePrivatePacksFromLegacyIndex, searchInPacks } from '../infrastructure/search-packs.js';
-import { indexStoragePath } from '../infrastructure/file-index.js';
+import { indexCommitSignature } from '../infrastructure/index-signature.js';
 import { openKnowledgeStore } from '../infrastructure/knowledge-store/index.js';
 import { createEmbeddingProvider } from '../domain/embeddings.js';
 import { loadBrainlinkConfig, sanitizeSearchMode } from '../infrastructure/config.js';
@@ -18,26 +17,18 @@ const embedQuerySafely = async (provider, query) => {
 const hybridCacheTtlMs = 30_000;
 const hybridCacheMaxEntries = 200;
 const hybridSearchCache = new Map();
-const readIndexMtimeMs = async (vaultPath) => {
-    try {
-        return (await stat(indexStoragePath(vaultPath))).mtimeMs;
-    }
-    catch {
-        return 0;
-    }
-};
 const toCacheKey = (vaultPath, query, limit, agentId) => JSON.stringify({
     vaultPath,
     query: query.trim().toLowerCase(),
     limit,
     agentId: agentId?.trim().toLowerCase() ?? '*'
 });
-const cacheGet = (key, indexMtimeMs) => {
+const cacheGet = (key, indexSignature) => {
     const entry = hybridSearchCache.get(key);
     if (!entry) {
         return undefined;
     }
-    const fresh = Date.now() - entry.createdAt <= hybridCacheTtlMs && entry.indexMtimeMs === indexMtimeMs;
+    const fresh = Date.now() - entry.createdAt <= hybridCacheTtlMs && entry.indexSignature === indexSignature;
     if (!fresh) {
         hybridSearchCache.delete(key);
         return undefined;
@@ -59,8 +50,8 @@ export const searchKnowledge = async (vaultPath, query, limit, agentId, mode) =>
     const searchMode = sanitizeSearchMode(mode, config.defaultSearchMode);
     await ensurePrivatePacksFromLegacyIndex(absoluteVaultPath);
     const cacheKey = searchMode === 'hybrid' ? toCacheKey(absoluteVaultPath, query, limit, agentId) : undefined;
-    const indexMtimeMs = cacheKey ? await readIndexMtimeMs(absoluteVaultPath) : 0;
-    const cached = cacheKey ? cacheGet(cacheKey, indexMtimeMs) : undefined;
+    const indexSignature = cacheKey ? await indexCommitSignature(absoluteVaultPath) : '';
+    const cached = cacheKey ? cacheGet(cacheKey, indexSignature) : undefined;
     if (cached) {
         return cached;
     }
@@ -81,7 +72,7 @@ export const searchKnowledge = async (vaultPath, query, limit, agentId, mode) =>
                 cacheSet({
                     key: cacheKey,
                     createdAt: Date.now(),
-                    indexMtimeMs,
+                    indexSignature,
                     results
                 });
             }
@@ -97,7 +88,7 @@ export const searchKnowledge = async (vaultPath, query, limit, agentId, mode) =>
             cacheSet({
                 key: cacheKey,
                 createdAt: Date.now(),
-                indexMtimeMs,
+                indexSignature,
                 results: fallbackResults
             });
         }

package/dist/application/server/routes.js

@@ -40,6 +40,10 @@ const readContextCacheTtlMs = async (url) => {
     const defaults = await readRuntimeDefaults(url);
     return defaults.defaultContextCacheTtlMs;
 };
+const readCagPackTtlMs = async (url) => {
+    const defaults = await readRuntimeDefaults(url);
+    return defaults.cagPackTtlMs;
+};
 const hasInvalidSearchMode = (url) => {
     const mode = url.searchParams.get('mode');
     return mode !== null && !['fts', 'semantic', 'hybrid'].includes(mode);
@@ -445,13 +449,14 @@ export const route = async (request, url, vaultPath) => {
         const mode = await readSearchMode(url);
         const strategy = await readContextStrategy(url);
         const contextCacheTtlMs = await readContextCacheTtlMs(url);
+        const cagPackTtlMs = await readCagPackTtlMs(url);
         if (hasInvalidSearchMode(url)) {
             return createResponse(createJsonResponse({ error: 'Invalid mode. Use fts, semantic or hybrid.' }), 400, 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']);
+        return createResponse(createJsonResponse(await buildContextPackage(vaultPath, query, limit, tokens, readAgentQuery(url), mode, strategy, contextCacheTtlMs, cagPackTtlMs)), 200, contentTypes['.json']);
     }
     if (isReadMethod(request) && url.pathname === '/api/links') {
         return createResponse(createJsonResponse({ links: await listLinks(vaultPath, readAgentQuery(url)) }), 200, contentTypes['.json']);

package/dist/application/vault-encryption.js

@@ -0,0 +1,64 @@
+// Encrypted vault versioning: the git repo tracks `<note>.md.enc` ciphertext
+// (opaque without the local key), while the plaintext `.md` stays the canonical
+// working copy and is git-ignored. Committing refreshes the ciphertext mirror;
+// pulling/cloning/restoring decrypts it back to Markdown before reindexing. Only
+// content that changed is rewritten, so encryption adds no git churn.
+import { readFile, rm, writeFile } from 'node:fs/promises';
+import { extname } from 'node:path';
+import { loadBrainlinkConfig } from '../infrastructure/config.js';
+import { ensureVault, listVaultFiles } from '../infrastructure/file-system-vault.js';
+import { decryptVaultContent, encryptVaultContent, readOrCreateVaultKey } from '../infrastructure/vault-crypto.js';
+const encryptedSuffix = '.md.enc';
+const isMarkdown = (path) => extname(path).toLowerCase() === '.md';
+const isEncryptedMarkdown = (path) => path.toLowerCase().endsWith(encryptedSuffix);
+export const vaultEncryptionEnabled = async () => (await loadBrainlinkConfig()).vaultEncryption === true;
+// Refresh the ciphertext mirror: (re)write `<note>.md.enc` for every Markdown
+// file whose ciphertext is missing or stale, and drop orphan `.md.enc` whose
+// source Markdown was deleted. Deterministic encryption means an unchanged note
+// produces identical bytes, so it is skipped (no write, no git churn).
+export const encryptVaultTree = async (vaultPath) => {
+    const root = await ensureVault(vaultPath);
+    const key = await readOrCreateVaultKey(root);
+    const files = await listVaultFiles(root);
+    const markdown = files.filter(isMarkdown);
+    const expected = new Set(markdown.map((path) => `${path}.enc`));
+    let written = 0;
+    for (const source of markdown) {
+        const payload = encryptVaultContent(key, await readFile(source));
+        const target = `${source}.enc`;
+        let current = null;
+        try {
+            current = await readFile(target);
+        }
+        catch {
+            current = null;
+        }
+        if (!current || !current.equals(payload)) {
+            await writeFile(target, payload, { mode: 0o600 });
+            written += 1;
+        }
+    }
+    let removed = 0;
+    for (const encrypted of files.filter(isEncryptedMarkdown)) {
+        if (!expected.has(encrypted)) {
+            await rm(encrypted, { force: true });
+            removed += 1;
+        }
+    }
+    return { written, removed };
+};
+// Rebuild plaintext Markdown from the ciphertext mirror after a checkout. Fails
+// loudly if the key cannot decrypt a payload (wrong/missing key) rather than
+// writing garbage.
+export const decryptVaultTree = async (vaultPath) => {
+    const root = await ensureVault(vaultPath);
+    const key = await readOrCreateVaultKey(root);
+    const encrypted = (await listVaultFiles(root)).filter(isEncryptedMarkdown);
+    let written = 0;
+    for (const source of encrypted) {
+        const plaintext = decryptVaultContent(key, await readFile(source));
+        await writeFile(source.slice(0, -'.enc'.length), plaintext, { mode: 0o600 });
+        written += 1;
+    }
+    return { written };
+};