@andespindola/brainlink 1.0.7 → 1.1.0

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+- 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.
+- Added **vault versioning** for the canonical Markdown. Git: `vault-init-git`, `vault-commit`, `vault-status`, `vault-history`, `vault-push`, `vault-pull`, `vault-restore`, `vault-clone` (driven through the system `git` binary; the derived `.brainlink/` is git-ignored). Portable snapshots: `vault-export`/`vault-import` produce and restore a self-contained gzip `.blvault` with per-file SHA-256. Every operation that changes Markdown reindexes automatically so the vault is immediately usable, merge conflicts abort cleanly instead of leaving markers in Markdown, conflicting local edits are preserved as `*.conflict-<ts>.md`, and remote URLs with inline credentials are rejected.
+- Pinned the transitive `fast-uri` dependency to `>=4.1.0` to clear a high-severity Snyk advisory affecting the entire 3.x line.
+
 - Added `brainlink_similar_notes` MCP tool: find the notes most similar to a given note (selected by title or path), using the note's own content as the retrieval query and excluding the note itself.
 - Added batch write tools `brainlink_add_notes` and `brainlink_delete_notes` that write or delete up to 100 notes in a single call and reindex once for the whole batch; batch deletion reports per-note failures without aborting the batch.
 

package/README.md

@@ -759,6 +759,17 @@ When the configured default vault is changed manually in config files, Brainlink
 Use `--global` to write to `$BRAINLINK_HOME/brainlink.config.json`, `--no-migrate` to skip migration, and `--no-index` to skip post-migration indexing.
 `config doctor` is dry-run by default; use `--fix` to apply safe config normalization and allowlist fixes.
 
+#### Storage backend
+
+`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.
+
+```json
+{ "storageBackend": "binary" }
+```
+
 ### `vaults`
 
 ```bash
@@ -912,6 +923,30 @@ blink pack-backup --vault ./vault --json
 Creates an offline backup artifact of encrypted search packs with a second compression pass.
 This is intentionally outside the online retrieval path (`index`, `search`, `context`).
 
+### Vault Versioning
+
+Version the canonical Markdown with git, or move a vault as a single portable file.
+The derived `.brainlink/` directory is never versioned; any operation that changes
+Markdown reindexes automatically so the vault stays immediately usable.
+
+```bash
+# Git: history, remotes, restore
+blink vault-init-git --remote git@github.com:you/your-vault.git
+blink vault-commit -m "snapshot notes"
+blink vault-push
+blink vault-pull                 # pulls and reindexes changed notes
+blink vault-history --limit 20
+blink vault-restore <commit>     # restore Markdown from a ref and reindex
+blink vault-clone git@github.com:you/your-vault.git ./vault   # clone + build index
+blink vault-status
+
+# Portable snapshot (self-contained, index excluded; import rebuilds it)
+blink vault-export -o vault.blvault
+blink vault-import vault.blvault  # conflicting local edits preserved as *.conflict-<ts>.md
+```
+
+Inline credentials in a remote URL are rejected — use SSH or a git credential helper.
+
 ### `agents`
 
 ```bash

package/dist/application/get-graph-node.js

@@ -1,8 +1,8 @@
 import { ensureVault } from '../infrastructure/file-system-vault.js';
-import { openFileIndex } from '../infrastructure/file-index.js';
+import { openKnowledgeStore } from '../infrastructure/knowledge-store/index.js';
 export const getGraphNode = async (vaultPath, id, agentId) => {
     const absoluteVaultPath = await ensureVault(vaultPath);
-    const index = openFileIndex(absoluteVaultPath);
+    const index = openKnowledgeStore(absoluteVaultPath);
     try {
         return await index.getGraphNode(id, agentId);
     }

package/dist/application/get-graph-summary.js

@@ -1,8 +1,8 @@
 import { ensureVault } from '../infrastructure/file-system-vault.js';
-import { openFileIndex } from '../infrastructure/file-index.js';
+import { openKnowledgeStore } from '../infrastructure/knowledge-store/index.js';
 export const getGraphSummary = async (vaultPath, agentId) => {
     const absoluteVaultPath = await ensureVault(vaultPath);
-    const index = openFileIndex(absoluteVaultPath);
+    const index = openKnowledgeStore(absoluteVaultPath);
     try {
         return await index.getGraphSummary(agentId);
     }

package/dist/application/get-graph.js

@@ -1,8 +1,8 @@
 import { ensureVault } from '../infrastructure/file-system-vault.js';
-import { openFileIndex } from '../infrastructure/file-index.js';
+import { openKnowledgeStore } from '../infrastructure/knowledge-store/index.js';
 export const getGraph = async (vaultPath, agentId) => {
     const absoluteVaultPath = await ensureVault(vaultPath);
-    const index = openFileIndex(absoluteVaultPath);
+    const index = openKnowledgeStore(absoluteVaultPath);
     try {
         return await index.getGraph(agentId);
     }

package/dist/application/index-vault.js

@@ -4,7 +4,7 @@ import { embeddingSignature, loadBrainlinkConfig } from '../infrastructure/confi
 import { ensureVault, readMarkdownFileSummaries } from '../infrastructure/file-system-vault.js';
 import { readIndexState, writeIndexState } from '../infrastructure/index-state.js';
 import { ensureSearchPackManifest } from '../infrastructure/search-packs.js';
-import { openFileIndex } from '../infrastructure/file-index.js';
+import { openKnowledgeStore } from '../infrastructure/knowledge-store/index.js';
 import { assembleIndexedDocuments, createTitleMaps, decidePackRebuild, detectChanges, embedChangedDocuments, rebuildSearchPacksIfNeeded } from './index-vault-phases.js';
 const toIndexResult = (documents) => ({
     documentCount: documents.length,
@@ -56,7 +56,7 @@ export const indexVaultWithOptions = async (vaultPath, options) => {
         hasPreviousState: previousState != null
     });
     const fullReindex = options.full === true;
-    const index = openFileIndex(absoluteVaultPath);
+    const index = openKnowledgeStore(absoluteVaultPath);
     try {
         const existingIndexedDocuments = await index.getIndexedDocuments();
         const existingByPath = new Map(existingIndexedDocuments.map((document) => [document.document.path, document]));

package/dist/application/list-agents.js

@@ -1,8 +1,8 @@
 import { ensureVault } from '../infrastructure/file-system-vault.js';
-import { openFileIndex } from '../infrastructure/file-index.js';
+import { openKnowledgeStore } from '../infrastructure/knowledge-store/index.js';
 export const listAgents = async (vaultPath) => {
     const absoluteVaultPath = await ensureVault(vaultPath);
-    const index = openFileIndex(absoluteVaultPath);
+    const index = openKnowledgeStore(absoluteVaultPath);
     try {
         return await index.listAgents();
     }

package/dist/application/list-links.js

@@ -1,8 +1,8 @@
 import { ensureVault } from '../infrastructure/file-system-vault.js';
-import { openFileIndex } from '../infrastructure/file-index.js';
+import { openKnowledgeStore } from '../infrastructure/knowledge-store/index.js';
 export const listLinks = async (vaultPath, agentId) => {
     const absoluteVaultPath = await ensureVault(vaultPath);
-    const index = openFileIndex(absoluteVaultPath);
+    const index = openKnowledgeStore(absoluteVaultPath);
     try {
         return await index.listLinks(agentId);
     }
@@ -12,7 +12,7 @@ export const listLinks = async (vaultPath, agentId) => {
 };
 export const listBacklinks = async (vaultPath, title, agentId) => {
     const absoluteVaultPath = await ensureVault(vaultPath);
-    const index = openFileIndex(absoluteVaultPath);
+    const index = openKnowledgeStore(absoluteVaultPath);
     try {
         return await index.listBacklinks(title, agentId);
     }

package/dist/application/ports/knowledge-store.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,177 @@
+// Backend-agnostic ranking. Given a candidate set (chunks already selected by a
+// storage backend), this module owns the deterministic scoring math: field
+// weighting, BM25 lexical relevance, cosine semantic relevance, hybrid fusion,
+// and stable ordering. Keeping it here means every KnowledgeStore backend
+// (JSON, binary, LMDB) produces an identical ranking for the same candidates.
+import { dotProduct } from '../../domain/embeddings.js';
+import { bm25TermScore, minMaxNormalize } from '../../domain/scoring.js';
+const queryTokenPattern = /[\p{L}\p{N}_-]+/gu;
+export const normalizeToken = (value) => value
+    .normalize('NFKD')
+    .replace(/\p{Diacritic}/gu, '')
+    .toLowerCase();
+export const tokenize = (query) => query
+    .match(queryTokenPattern)
+    ?.map(normalizeToken)
+    .filter((token) => token.length > 1) ?? [];
+const countOccurrences = (text, token) => {
+    let hits = 0;
+    let cursor = 0;
+    while (cursor < text.length) {
+        const index = text.indexOf(token, cursor);
+        if (index < 0) {
+            break;
+        }
+        hits += 1;
+        cursor = index + token.length;
+    }
+    return hits;
+};
+const titleFieldWeight = 5;
+const tagFieldWeight = 4;
+const pathFieldWeight = 2;
+const contentHitCap = 6;
+const hybridTextWeight = 0.6;
+const hybridSemanticWeight = 0.4;
+const normalizeFields = (row) => ({
+    title: normalizeToken(row.title),
+    path: normalizeToken(row.path),
+    content: normalizeToken(row.content),
+    tags: normalizeToken(row.tags.join(' '))
+});
+// Field-weighted term frequency: title/tag/path matches count more than body
+// matches, and body hits saturate at a cap so a term repeated many times in one
+// chunk cannot dominate. This weighted frequency feeds BM25 below.
+const weightedTermFrequency = (fields, token) => {
+    const titleHits = countOccurrences(fields.title, token);
+    const tagHits = countOccurrences(fields.tags, token);
+    const pathHits = countOccurrences(fields.path, token);
+    const contentHits = countOccurrences(fields.content, token);
+    return (titleHits * titleFieldWeight +
+        tagHits * tagFieldWeight +
+        pathHits * pathFieldWeight +
+        Math.min(contentHits, contentHitCap));
+};
+// Naive additive field score retained for graph-node title/path lookup, where
+// the candidate set is documents (not chunks) and corpus-wide BM25 statistics
+// add no signal over a direct weighted hit count.
+export const lexicalFieldScore = (row, tokens) => {
+    if (tokens.length === 0) {
+        return 0;
+    }
+    const fields = normalizeFields(row);
+    return tokens.reduce((score, token) => score + weightedTermFrequency(fields, token), 0);
+};
+// A single chunk with a non-finite cached tokenCount (legacy index, partial
+// write, manual edit) would otherwise poison the shared averageLength and zero
+// out lexical scoring for the whole corpus, so coerce to a safe positive length.
+const safeDocumentLength = (tokenCount) => Number.isFinite(tokenCount) && tokenCount > 0 ? tokenCount : 1;
+const buildCorpusStatistics = (prepared, tokens) => {
+    const documentCount = prepared.length;
+    const totalLength = prepared.reduce((sum, entry) => sum + safeDocumentLength(entry.row.tokenCount), 0);
+    const documentFrequencyByTerm = new Map();
+    for (const term of tokens) {
+        let documentFrequency = 0;
+        for (const entry of prepared) {
+            if ((entry.weightedTermFrequencies.get(term) ?? 0) > 0) {
+                documentFrequency += 1;
+            }
+        }
+        documentFrequencyByTerm.set(term, documentFrequency);
+    }
+    return {
+        documentCount,
+        averageLength: documentCount > 0 ? totalLength / documentCount : 0,
+        documentFrequencyByTerm
+    };
+};
+const bm25TextScore = (entry, tokens, stats) => tokens.reduce((score, term) => score +
+    bm25TermScore({
+        termFrequency: entry.weightedTermFrequencies.get(term) ?? 0,
+        documentLength: safeDocumentLength(entry.row.tokenCount),
+        documentCount: stats.documentCount,
+        documentFrequency: stats.documentFrequencyByTerm.get(term) ?? 0,
+        averageLength: stats.averageLength
+    }), 0);
+const semanticScore = (row, queryEmbedding) => queryEmbedding.length > 0 && row.embedding.length > 0 ? dotProduct(queryEmbedding, row.embedding) : 0;
+const rangeOf = (values) => values.reduce((range, value) => ({ min: Math.min(range.min, value), max: Math.max(range.max, value) }), { min: Infinity, max: -Infinity });
+const toResult = (row, mode, score, text, semantic) => ({
+    documentId: row.documentId,
+    agentId: row.agentId,
+    title: row.title,
+    path: row.path,
+    chunkId: row.chunkId,
+    chunkOrdinal: row.chunkOrdinal,
+    content: row.content,
+    score,
+    textScore: text,
+    semanticScore: semantic,
+    tokenCount: row.tokenCount,
+    searchMode: mode,
+    tags: row.tags
+});
+// 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 = []) => {
+    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
+    // length normalization.
+    const prepared = candidates.map((row) => {
+        const fields = normalizeFields(row);
+        const weightedTermFrequencies = new Map();
+        for (const term of tokens) {
+            const frequency = weightedTermFrequency(fields, term);
+            if (frequency > 0) {
+                weightedTermFrequencies.set(term, frequency);
+            }
+        }
+        return { row, weightedTermFrequencies };
+    });
+    const stats = buildCorpusStatistics(prepared, tokens);
+    // Pass 2: raw lexical (BM25) and semantic (cosine) component scores.
+    const componentScored = prepared.map((entry) => ({
+        row: entry.row,
+        text: tokens.length > 0 ? bm25TextScore(entry, tokens, stats) : 0,
+        semantic: semanticScore(entry.row, queryEmbedding)
+    }));
+    // Filter on raw relevance before normalization so a legitimate match that
+    // happens to be the weakest in its mode is never min-max scaled to zero
+    // and dropped. fts stays lexical-only and semantic stays vector-only.
+    const relevant = componentScored.filter((entry) => {
+        if (tokens.length === 0) {
+            return true;
+        }
+        if (mode === 'fts') {
+            return entry.text > 0;
+        }
+        if (mode === 'semantic') {
+            return entry.semantic > 0;
+        }
+        return entry.text > 0 || entry.semantic > 0;
+    });
+    if (relevant.length === 0) {
+        return [];
+    }
+    const textRange = rangeOf(relevant.map((entry) => entry.text));
+    const semanticRange = rangeOf(relevant.map((entry) => entry.semantic));
+    const finalScore = (entry) => {
+        if (mode === 'fts') {
+            return entry.text;
+        }
+        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
+        // 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);
+        return textNorm * hybridTextWeight + semanticNorm * hybridSemanticWeight;
+    };
+    return relevant
+        .map((entry) => toResult(entry.row, mode, finalScore(entry), entry.text, entry.semantic))
+        .sort((left, right) => right.score - left.score || left.title.localeCompare(right.title))
+        .slice(0, Math.max(0, limit));
+};

package/dist/application/search-graph-node-ids.js

@@ -1,6 +1,7 @@
 import { stat } from 'node:fs/promises';
 import { ensureVault } from '../infrastructure/file-system-vault.js';
-import { indexStoragePath, openFileIndex } from '../infrastructure/file-index.js';
+import { indexStoragePath } from '../infrastructure/file-index.js';
+import { openKnowledgeStore } from '../infrastructure/knowledge-store/index.js';
 import { getGraphLayout } from './get-graph-layout.js';
 const graphSearchCacheTtlMs = 20_000;
 const graphSearchCacheMaxEntries = 120;
@@ -52,7 +53,7 @@ export const searchGraphNodeIds = async (vaultPath, query, limit, agentId, conte
     const contextNodeIds = context
         ? new Set((await getGraphLayout(absoluteVaultPath, { agentId, context })).layout.nodes.map((node) => node.id))
         : new Set();
-    const index = openFileIndex(absoluteVaultPath);
+    const index = openKnowledgeStore(absoluteVaultPath);
     try {
         const searchLimit = context ? Math.max(limit, 5000) : limit;
         const foundNodeIds = await index.searchGraphNodeIds(query, searchLimit, agentId);

package/dist/application/search-knowledge.js

@@ -1,7 +1,8 @@
 import { stat } from 'node:fs/promises';
 import { ensureVault } from '../infrastructure/file-system-vault.js';
 import { ensurePrivatePacksFromLegacyIndex, searchInPacks } from '../infrastructure/search-packs.js';
-import { indexStoragePath, openFileIndex } from '../infrastructure/file-index.js';
+import { indexStoragePath } from '../infrastructure/file-index.js';
+import { openKnowledgeStore } from '../infrastructure/knowledge-store/index.js';
 import { createEmbeddingProvider } from '../domain/embeddings.js';
 import { loadBrainlinkConfig, sanitizeSearchMode } from '../infrastructure/config.js';
 const embedQuerySafely = async (provider, query) => {
@@ -73,7 +74,7 @@ export const searchKnowledge = async (vaultPath, query, limit, agentId, mode) =>
     // to lexical (fts) so a transient provider outage still yields results.
     const effectiveMode = searchMode === 'semantic' && shouldEmbedQuery && queryEmbedding.length === 0 ? 'fts' : searchMode;
     try {
-        const index = openFileIndex(absoluteVaultPath);
+        const index = openKnowledgeStore(absoluteVaultPath);
         try {
             const results = await index.search(query, limit, agentId, effectiveMode, queryEmbedding);
             if (cacheKey) {

package/dist/application/vault-git.js

@@ -0,0 +1,180 @@
+// Git-backed versioning for the vault's canonical Markdown. The derived
+// `.brainlink/` directory is git-ignored; only `.md` is versioned. After any
+// operation that changes Markdown on disk (pull, restore), the index is rebuilt
+// so the vault stays immediately usable ("no losing the use of the data").
+//
+// Git is driven through the system binary via execFile (never a shell, args as
+// an array) to keep runtime dependencies minimal and history/merge behavior
+// native. A missing git binary degrades to a clear, actionable error.
+import { execFile } from 'node:child_process';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { indexVault } from './index-vault.js';
+import { ensureVault } from '../infrastructure/file-system-vault.js';
+const execFileAsync = promisify(execFile);
+export class GitUnavailableError extends Error {
+    constructor() {
+        super('git executable not found. Install git to use vault versioning.');
+        this.name = 'GitUnavailableError';
+    }
+}
+export class GitCommandError extends Error {
+    constructor(args, stderr) {
+        super(`git ${args.join(' ')} failed: ${stderr.trim() || 'unknown error'}`);
+        this.name = 'GitCommandError';
+    }
+}
+const isMissingBinary = (error) => error instanceof Error && 'code' in error && error.code === 'ENOENT';
+const runGit = async (cwd, args) => {
+    try {
+        const { stdout } = await execFileAsync('git', [...args], { cwd, maxBuffer: 64 * 1024 * 1024 });
+        return stdout;
+    }
+    catch (error) {
+        if (isMissingBinary(error)) {
+            throw new GitUnavailableError();
+        }
+        const stderr = error.stderr ?? (error instanceof Error ? error.message : String(error));
+        throw new GitCommandError(args, stderr);
+    }
+};
+const isInsideGitRepo = async (cwd) => {
+    try {
+        const out = await runGit(cwd, ['rev-parse', '--is-inside-work-tree']);
+        return out.trim() === 'true';
+    }
+    catch (error) {
+        if (error instanceof GitUnavailableError) {
+            throw error;
+        }
+        return false;
+    }
+};
+const gitignoreLines = ['.brainlink/', '*.tmp', '.DS_Store'];
+const ensureGitignore = async (vaultRoot) => {
+    const path = join(vaultRoot, '.gitignore');
+    let current = '';
+    try {
+        current = await readFile(path, 'utf8');
+    }
+    catch {
+        current = '';
+    }
+    const existing = new Set(current.split('\n').map((line) => line.trim()));
+    const missing = gitignoreLines.filter((line) => !existing.has(line));
+    if (missing.length === 0 && current.length > 0) {
+        return;
+    }
+    const next = `${[current.trimEnd(), ...missing].filter(Boolean).join('\n')}\n`;
+    await writeFile(path, next, 'utf8');
+};
+// Reject credentials embedded in a remote URL: they would be written to
+// .git/config in clear text. Users should rely on SSH or a git credential
+// helper instead.
+const assertSafeRemote = (remote) => {
+    if (/\/\/[^/@]*:[^/@]*@/.test(remote) || /x-access-token|:[^/]*@github/.test(remote)) {
+        throw new Error('Refusing a remote URL with an inline credential. Use SSH or a git credential helper.');
+    }
+};
+const markdownOnly = (paths) => paths.filter((path) => path.toLowerCase().endsWith('.md'));
+export const initVaultGit = async (vaultPath, options = {}) => {
+    const root = await ensureVault(vaultPath);
+    await mkdir(root, { recursive: true });
+    const already = await isInsideGitRepo(root);
+    if (!already) {
+        await runGit(root, ['init']);
+    }
+    await ensureGitignore(root);
+    if (options.remote) {
+        assertSafeRemote(options.remote);
+        const remotes = await runGit(root, ['remote']);
+        const verb = remotes.split('\n').map((line) => line.trim()).includes('origin') ? 'set-url' : 'add';
+        await runGit(root, ['remote', verb, 'origin', options.remote]);
+    }
+    return { root, initialized: !already };
+};
+export const vaultGitStatus = async (vaultPath) => {
+    const root = await ensureVault(vaultPath);
+    const branch = (await runGit(root, ['rev-parse', '--abbrev-ref', 'HEAD']).catch(() => 'HEAD')).trim();
+    const porcelain = await runGit(root, ['status', '--porcelain']);
+    const changed = porcelain
+        .split('\n')
+        .map((line) => line.slice(3).trim())
+        .filter(Boolean);
+    return { branch, dirty: changed.length > 0, changedMarkdown: markdownOnly(changed) };
+};
+// Stage and commit only Markdown. Returns null when there is nothing to commit.
+export const commitVault = async (vaultPath, message) => {
+    const root = await ensureVault(vaultPath);
+    await runGit(root, ['add', '-A', '--', '*.md', ':(glob)**/*.md', '.gitignore']);
+    const staged = await runGit(root, ['diff', '--cached', '--name-only']);
+    if (staged.trim().length === 0) {
+        return null;
+    }
+    await runGit(root, ['commit', '-m', message]);
+    return (await runGit(root, ['rev-parse', 'HEAD'])).trim();
+};
+export const vaultHistory = async (vaultPath, limit = 20) => {
+    const root = await ensureVault(vaultPath);
+    const out = await runGit(root, [
+        'log',
+        `-n${Math.max(1, Math.floor(limit))}`,
+        '--format=%H%x00%an%x00%aI%x00%s',
+        '--',
+        '*.md'
+    ]).catch(() => '');
+    return out
+        .split('\n')
+        .map((line) => line.split('\u0000'))
+        .filter((parts) => parts.length === 4)
+        .map(([hash, author, date, subject]) => ({ hash: hash, author: author, date: date, subject: subject }));
+};
+const reindexAfterMarkdownChange = async (vaultPath, changedMarkdown, skipIndex) => !skipIndex && changedMarkdown.length > 0 ? indexVault(vaultPath) : undefined;
+export const pushVault = async (vaultPath, branch) => {
+    const root = await ensureVault(vaultPath);
+    const target = branch ?? (await runGit(root, ['rev-parse', '--abbrev-ref', 'HEAD'])).trim();
+    await runGit(root, ['push', '-u', 'origin', target]);
+};
+// Pull from origin and reindex when Markdown changed, so the vault is usable
+// immediately. On a merge conflict the merge is aborted and a clear error is
+// raised rather than leaving conflict markers in the Markdown.
+export const pullVault = async (vaultPath, options = {}) => {
+    const root = await ensureVault(vaultPath);
+    const before = (await runGit(root, ['rev-parse', 'HEAD']).catch(() => '')).trim();
+    try {
+        await runGit(root, ['pull', '--no-rebase', '--no-edit', 'origin']);
+    }
+    catch (error) {
+        await runGit(root, ['merge', '--abort']).catch(() => undefined);
+        throw error instanceof GitCommandError
+            ? new GitCommandError(['pull'], 'merge conflict; aborted. Resolve manually, then commit.')
+            : error;
+    }
+    const after = (await runGit(root, ['rev-parse', 'HEAD']).catch(() => '')).trim();
+    const diff = before && after && before !== after
+        ? await runGit(root, ['diff', '--name-only', before, after, '--', '*.md'])
+        : '';
+    const changedMarkdown = markdownOnly(diff.split('\n').map((line) => line.trim()).filter(Boolean));
+    const index = await reindexAfterMarkdownChange(vaultPath, changedMarkdown, options.skipIndex === true);
+    return { changedMarkdown, index };
+};
+export const restoreVault = async (vaultPath, ref, options = {}) => {
+    const root = await ensureVault(vaultPath);
+    const head = (await runGit(root, ['rev-parse', 'HEAD']).catch(() => '')).trim();
+    const diff = await runGit(root, ['diff', '--name-only', ref, '--', '*.md']).catch(() => '');
+    await runGit(root, ['checkout', ref, '--', '.']);
+    const changedMarkdown = markdownOnly(diff.split('\n').map((line) => line.trim()).filter(Boolean));
+    const index = await reindexAfterMarkdownChange(vaultPath, changedMarkdown, options.skipIndex === true);
+    void head;
+    return { changedMarkdown, index };
+};
+// Clone a remote vault and build its index from scratch so it is immediately
+// searchable. The clone target must not already exist.
+export const cloneVault = async (remote, targetPath, options = {}) => {
+    assertSafeRemote(remote);
+    await runGit(process.cwd(), ['clone', remote, targetPath]);
+    const root = await ensureVault(targetPath);
+    const index = options.skipIndex === true ? undefined : await indexVault(root, { full: true });
+    return { root, index };
+};

package/dist/application/vault-snapshot.js

@@ -0,0 +1,87 @@
+// Portable vault snapshot (`.blvault`): a single gzip-compressed envelope of the
+// canonical Markdown (with per-file SHA-256), self-contained and movable to any
+// machine. The derived index is never included — import rebuilds it so the vault
+// is immediately usable. Conflicts on import are preserved as `*.conflict-<ts>.md`
+// rather than overwriting local edits.
+import { createHash } from 'node:crypto';
+import { gzipSync, gunzipSync } from 'node:zlib';
+import { extname, relative } from 'node:path';
+import { readFile, writeFile } from 'node:fs/promises';
+import { indexVault } from './index-vault.js';
+import { ensureVault, listVaultFiles, writeMarkdownFile } from '../infrastructure/file-system-vault.js';
+const snapshotVersion = 1;
+const isMarkdown = (path) => extname(path).toLowerCase() === '.md';
+const toPosix = (path) => path.split('\\').join('/');
+const sha256 = (data) => createHash('sha256').update(data).digest('hex');
+const conflictName = (path) => {
+    const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\..+$/, 'Z');
+    const extension = extname(path);
+    const base = extension ? path.slice(0, -extension.length) : path;
+    return `${base}.conflict-${stamp}${extension}`;
+};
+export const exportVaultSnapshot = async (vaultPath, outputFile) => {
+    const root = await ensureVault(vaultPath);
+    const markdownFiles = (await listVaultFiles(root)).filter(isMarkdown);
+    const entries = await Promise.all(markdownFiles.map(async (absolutePath) => {
+        const content = await readFile(absolutePath);
+        const path = toPosix(relative(root, absolutePath));
+        return {
+            manifest: { path, sha256: sha256(content), bytes: content.byteLength },
+            file: { path, contentB64: content.toString('base64') }
+        };
+    }));
+    const envelope = {
+        version: snapshotVersion,
+        createdAt: new Date().toISOString(),
+        manifest: entries.map((entry) => entry.manifest),
+        files: entries.map((entry) => entry.file)
+    };
+    const packed = gzipSync(Buffer.from(JSON.stringify(envelope), 'utf8'), { level: 9 });
+    await writeFile(outputFile, packed, { mode: 0o600 });
+    return { file: outputFile, fileCount: entries.length, bytes: packed.byteLength };
+};
+const parseEnvelope = (raw) => {
+    const envelope = JSON.parse(gunzipSync(raw).toString('utf8'));
+    if (!envelope || envelope.version !== snapshotVersion || !Array.isArray(envelope.files)) {
+        throw new Error('Unrecognized .blvault snapshot format.');
+    }
+    return envelope;
+};
+export const importVaultSnapshot = async (snapshotFile, vaultPath, options = {}) => {
+    const root = await ensureVault(vaultPath);
+    const envelope = parseEnvelope(await readFile(snapshotFile));
+    const manifestByPath = new Map(envelope.manifest.map((entry) => [entry.path, entry]));
+    let imported = 0;
+    let conflicted = 0;
+    for (const file of envelope.files) {
+        if (!isMarkdown(file.path)) {
+            continue;
+        }
+        const content = Buffer.from(file.contentB64, 'base64');
+        const expected = manifestByPath.get(file.path)?.sha256;
+        if (expected && sha256(content) !== expected) {
+            throw new Error(`Checksum mismatch for ${file.path}; snapshot is corrupt.`);
+        }
+        // Preserve local edits: write divergent incoming files under a conflict name
+        // instead of overwriting. writeMarkdownFile guards against path traversal.
+        let existing = null;
+        try {
+            existing = await readFile(`${root}/${file.path}`);
+        }
+        catch {
+            existing = null;
+        }
+        if (existing && !existing.equals(content)) {
+            await writeMarkdownFile(root, conflictName(file.path), content.toString('utf8'));
+            conflicted += 1;
+            continue;
+        }
+        if (existing && existing.equals(content)) {
+            continue;
+        }
+        await writeMarkdownFile(root, file.path, content.toString('utf8'));
+        imported += 1;
+    }
+    const index = !options.skipIndex && imported + conflicted > 0 ? await indexVault(root) : undefined;
+    return { imported, conflicted, index };
+};