@andespindola/brainlink 0.1.0-beta.12 → 0.1.0-beta.13

package/README.md

@@ -57,7 +57,7 @@ LLMs do not have infinite context. Brainlink gives agents an external memory lay
 6. Brainlink returns compact, source-backed context.
 
 Markdown is the source of truth. `.brainlink/brainlink.db` is only a rebuildable index.
-Brainlink now keeps an automatic rollback snapshot at `.brainlink/brainlink.db.backup`. If the main SQLite file is corrupted, Brainlink automatically restores from snapshot (or recreates a clean index when no snapshot exists).
+Brainlink now keeps an automatic rollback snapshot at `.brainlink/brainlink.db.backup` plus rotating snapshots in `.brainlink/brainlink.db.backup.snapshots/`. If the main SQLite file is corrupted, Brainlink automatically restores the newest valid snapshot (or recreates a clean index when no snapshot exists).
 After each index run, Brainlink also writes private encrypted search packs at `.brainlink/search-packs/*.blpk`. If SQLite is unavailable, search falls back to these packs automatically.
 Pack decryption uses a Brainlink key from `$BRAINLINK_HOME/keys` or from `BRAINLINK_SEARCH_PACK_KEY` when explicitly configured.
 

package/dist/application/analyze-vault.js

@@ -1,5 +1,5 @@
 import { stat } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import { existsSync, readdirSync } from 'node:fs';
 import { performance } from 'node:perf_hooks';
 import { join } from 'node:path';
 import { validateGraph, getBrokenLinks, getOrphanNodes, getVaultStats } from '../domain/graph-analysis.js';
@@ -97,7 +97,11 @@ export const doctorVault = async (vaultPath) => {
     const graph = await getGraphSummary(absoluteVaultPath);
     const validation = validateGraph(graph);
     const backupPath = join(absoluteVaultPath, '.brainlink', 'brainlink.db.backup');
+    const snapshotDirectory = join(absoluteVaultPath, '.brainlink', 'brainlink.db.backup.snapshots');
     const hasBackup = existsSync(backupPath);
+    const snapshotCount = existsSync(snapshotDirectory)
+        ? readdirSync(snapshotDirectory).filter((name) => name.endsWith('.db')).length
+        : 0;
     const backupReady = graph.nodes.length === 0 || hasBackup;
     const checks = [
         createCheck('vault', true, `Vault ready at ${absoluteVaultPath}`),
@@ -105,7 +109,9 @@ export const doctorVault = async (vaultPath) => {
         createCheck('index', graph.nodes.length > 0, `${graph.nodes.length} indexed documents found`),
         createCheck('broken-links', validation.brokenLinks.length === 0, `${validation.brokenLinks.length} broken links found`),
         createCheck('index-backup', backupReady, backupReady
-            ? (hasBackup ? 'SQLite recovery snapshot is available' : 'No index yet. Snapshot will be created after first indexing run')
+            ? (hasBackup
+                ? `SQLite recovery snapshot is available (${snapshotCount} rotating snapshots)`
+                : 'No index yet. Snapshot will be created after first indexing run')
             : 'Recovery snapshot missing. Run blink index to create a rollback snapshot')
     ];
     const recommendations = files.length === 0 && graph.nodes.length === 0

package/dist/infrastructure/sqlite/recovery.js

@@ -1,6 +1,6 @@
 import Database from 'better-sqlite3';
-import { copyFileSync, existsSync, mkdirSync, renameSync, rmSync, unlinkSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
 const sqliteCorruptionHints = [
     'database disk image is malformed',
     'file is not a database',
@@ -8,6 +8,7 @@ const sqliteCorruptionHints = [
     'malformed database schema',
     'sqlite quick_check failed'
 ];
+const maxSnapshotFiles = 24;
 const normalizeMessage = (error) => error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
 const isSqliteCorruptionError = (error) => sqliteCorruptionHints.some((hint) => normalizeMessage(error).includes(hint));
 const safeUnlink = (path) => {
@@ -39,15 +40,19 @@ const archiveCorruptedDatabase = (databasePath) => {
     const archivedPath = `${databasePath}.corrupt-${Date.now()}`;
     renameSync(databasePath, archivedPath);
 };
-const restoreFromBackupOrReset = (databasePath, backupPath) => {
-    clearSidecars(databasePath);
-    archiveCorruptedDatabase(databasePath);
-    if (existsSync(backupPath)) {
-        copyFileSync(backupPath, databasePath);
-        clearSidecars(databasePath);
+const snapshotDirectoryPath = (backupPath) => join(dirname(backupPath), `${basename(backupPath)}.snapshots`);
+const snapshotFileName = () => `snapshot-${new Date().toISOString().replace(/[:.]/g, '-')}.db`;
+const cleanupSnapshotOverflow = (backupPath) => {
+    const directory = snapshotDirectoryPath(backupPath);
+    if (!existsSync(directory)) {
         return;
     }
-    rmSync(databasePath, { force: true });
+    const snapshots = readdirSync(directory)
+        .filter((name) => name.endsWith('.db'))
+        .sort((left, right) => right.localeCompare(left));
+    snapshots.slice(maxSnapshotFiles).forEach((name) => {
+        rmSync(join(directory, name), { force: true });
+    });
 };
 const openCheckedDatabase = (databasePath) => {
     const database = new Database(databasePath);
@@ -60,13 +65,88 @@ const openCheckedDatabase = (databasePath) => {
     }
     return database;
 };
+const isValidDatabaseSnapshot = (path) => {
+    if (!existsSync(path)) {
+        return false;
+    }
+    try {
+        const size = statSync(path).size;
+        if (size <= 0) {
+            return false;
+        }
+    }
+    catch {
+        return false;
+    }
+    try {
+        const database = new Database(path);
+        try {
+            assertQuickCheck(database);
+            return true;
+        }
+        finally {
+            database.close();
+        }
+    }
+    catch {
+        return false;
+    }
+};
+const candidateBackupFiles = (backupPath) => {
+    const directory = snapshotDirectoryPath(backupPath);
+    const snapshots = existsSync(directory)
+        ? readdirSync(directory)
+            .filter((name) => name.endsWith('.db'))
+            .sort((left, right) => right.localeCompare(left))
+            .map((name) => join(directory, name))
+        : [];
+    return [backupPath, ...snapshots];
+};
+const ensureSnapshotDirectory = (backupPath) => {
+    mkdirSync(snapshotDirectoryPath(backupPath), { recursive: true, mode: 0o700 });
+};
+const writeRecoveryMarker = (backupPath, restoredFrom) => {
+    const markerPath = join(dirname(backupPath), 'recovery-last-restore.json');
+    const payload = {
+        restoredAt: new Date().toISOString(),
+        restoredFrom
+    };
+    writeFileSync(markerPath, `${JSON.stringify(payload, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+};
+const restoreFromBackupOrReset = (databasePath, backupPath) => {
+    clearSidecars(databasePath);
+    archiveCorruptedDatabase(databasePath);
+    for (const candidate of candidateBackupFiles(backupPath)) {
+        if (!isValidDatabaseSnapshot(candidate)) {
+            continue;
+        }
+        copyFileSync(candidate, databasePath);
+        clearSidecars(databasePath);
+        if (isValidDatabaseSnapshot(databasePath)) {
+            writeRecoveryMarker(backupPath, candidate);
+            return;
+        }
+    }
+    rmSync(databasePath, { force: true });
+};
 export const createRecoverySnapshot = (database, backupPath) => {
     const backupDirectory = dirname(backupPath);
     const tempBackupPath = `${backupPath}.tmp`;
+    const snapshotDirectory = snapshotDirectoryPath(backupPath);
+    const snapshotPath = join(snapshotDirectory, snapshotFileName());
     mkdirSync(backupDirectory, { recursive: true });
+    ensureSnapshotDirectory(backupPath);
     rmSync(tempBackupPath, { force: true });
+    try {
+        database.pragma('wal_checkpoint(PASSIVE)');
+    }
+    catch {
+        // Checkpoint is best-effort.
+    }
     database.prepare('VACUUM INTO ?').run(tempBackupPath);
     renameSync(tempBackupPath, backupPath);
+    copyFileSync(backupPath, snapshotPath);
+    cleanupSnapshotOverflow(backupPath);
 };
 export const openDatabaseWithRecovery = (databasePath, backupPath) => {
     mkdirSync(dirname(databasePath), { recursive: true });

package/docs/AGENT_USAGE.md

@@ -634,7 +634,7 @@ GET  /api/validate
 
 The HTTP API is read-only. Use the CLI for writes and indexing.
 
-Brainlink maintains an automatic SQLite rollback snapshot at `.brainlink/brainlink.db.backup`. When `.brainlink/brainlink.db` is corrupted, Brainlink restores from snapshot automatically or recreates a clean index if no snapshot exists yet.
+Brainlink maintains an automatic SQLite rollback snapshot at `.brainlink/brainlink.db.backup` and rotating snapshots in `.brainlink/brainlink.db.backup.snapshots/`. When `.brainlink/brainlink.db` is corrupted, Brainlink restores the newest valid snapshot automatically or recreates a clean index if no snapshot exists yet.
 Indexing also writes private encrypted search packs at `.brainlink/search-packs/*.blpk`; when SQLite cannot be opened, Brainlink falls back to pack-based search automatically.
 Pack decryption keys are resolved from `$BRAINLINK_HOME/keys` (or `BRAINLINK_SEARCH_PACK_KEY` when explicitly set).
 

package/docs/ARCHITECTURE.md

@@ -300,7 +300,7 @@ Markdown keeps the system portable, inspectable, Git-friendly, and compatible wi
 
 SQLite gives fast local search, local vector storage and rebuildable retrieval without forcing users to run external infrastructure.
 Hybrid retrieval also uses a short-lived in-memory cache keyed by vault/query/agent and invalidated by index file mtime to reduce repeated query latency.
-Brainlink also writes a local rollback snapshot (`.brainlink/brainlink.db.backup`) after successful indexing. On corruption detection (`quick_check`/SQLite malformed errors), Brainlink restores from snapshot automatically before reopening the index.
+Brainlink also writes a local rollback snapshot (`.brainlink/brainlink.db.backup`) plus rotating point-in-time snapshots (`.brainlink/brainlink.db.backup.snapshots/`) after successful indexing. On corruption detection (`quick_check`/SQLite malformed errors), Brainlink restores the newest valid snapshot automatically before reopening the index.
 Indexing additionally exports private encrypted pack files (`.brainlink/search-packs/*.blpk`) from indexed chunks. Search falls back to these packs when SQLite is unavailable, preserving retrieval continuity in degraded mode.
 Pack encryption keys are resolved from `$BRAINLINK_HOME/keys` or from `BRAINLINK_SEARCH_PACK_KEY` when configured.
 

package/package.json

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