@andespindola/brainlink 1.0.7 → 1.2.0

package/dist/mcp/server.js

@@ -1,5 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { addNoteInputSchema, addFileInputSchema, addFileTool, addNoteTool, addNotesInputSchema, addNotesTool, deleteNoteInputSchema, deleteNoteTool, deleteNotesInputSchema, deleteNotesTool, volatileAddInputSchema, volatileAddTool, volatileClearInputSchema, volatileClearTool, dedupeInputSchema, dedupeResolveInputSchema, dedupeResolveTool, dedupeTool, brokenLinksInputSchema, brokenLinksTool, bootstrapInputSchema, bootstrapTool, canonicalizeContextLinksInputSchema, canonicalizeContextLinksTool, contextInputSchema, contextPacksInputSchema, contextPacksTool, contextTool, doctorActionsInputSchema, doctorActionsTool, graphContextsInputSchema, graphContextsTool, graphInputSchema, graphTool, explainInputSchema, explainTool, indexInputSchema, indexTool, inboxAddInputSchema, inboxAddTool, inboxListInputSchema, inboxListTool, inboxProcessInputSchema, inboxProcessTool, orphansInputSchema, orphansTool, policyInputSchema, policyTool, projectInitInputSchema, projectInitTool, recommendationsInputSchema, recommendationsTool, rememberInputSchema, rememberTool, repairLinksInputSchema, repairLinksTool, searchInputSchema, searchTool, similarNotesInputSchema, similarNotesTool, sessionCloseInputSchema, sessionCloseTool, statsInputSchema, statsTool, suggestLinksInputSchema, suggestLinksTool, syncInputSchema, syncTool, validateInputSchema, validateTool, versionInputSchema, versionTool } from './tools.js';
+import { addNoteInputSchema, addFileInputSchema, addFileTool, addNoteTool, addNotesInputSchema, addNotesTool, deleteNoteInputSchema, deleteNoteTool, deleteNotesInputSchema, deleteNotesTool, volatileAddInputSchema, volatileAddTool, volatileClearInputSchema, volatileClearTool, dedupeInputSchema, dedupeResolveInputSchema, dedupeResolveTool, dedupeTool, brokenLinksInputSchema, brokenLinksTool, bootstrapInputSchema, bootstrapTool, canonicalizeContextLinksInputSchema, canonicalizeContextLinksTool, contextInputSchema, contextPacksInputSchema, contextPacksTool, contextTool, doctorActionsInputSchema, doctorActionsTool, graphContextsInputSchema, graphContextsTool, graphInputSchema, graphTool, explainInputSchema, explainTool, indexInputSchema, indexTool, inboxAddInputSchema, inboxAddTool, inboxListInputSchema, inboxListTool, inboxProcessInputSchema, inboxProcessTool, orphansInputSchema, orphansTool, policyInputSchema, policyTool, projectInitInputSchema, projectInitTool, recommendationsInputSchema, recommendationsTool, rememberInputSchema, rememberTool, repairLinksInputSchema, repairLinksTool, searchInputSchema, searchTool, similarNotesInputSchema, similarNotesTool, sessionCloseInputSchema, sessionCloseTool, statsInputSchema, statsTool, suggestLinksInputSchema, suggestLinksTool, syncInputSchema, syncTool, validateInputSchema, validateTool, vaultCommitInputSchema, vaultCommitTool, vaultExportInputSchema, vaultExportTool, vaultHistoryInputSchema, vaultHistoryTool, vaultImportInputSchema, vaultImportTool, vaultInitInputSchema, vaultInitTool, vaultProvisionInputSchema, vaultProvisionTool, vaultPullInputSchema, vaultPullTool, vaultRestoreInputSchema, vaultRestoreTool, vaultStatusInputSchema, vaultStatusTool, versionInputSchema, versionTool } from './tools.js';
 import { getRuntimeVersion } from './runtime.js';
 import { guardToolHandler } from './tool-guard.js';
 export const createBrainlinkMcpServer = () => {
@@ -155,6 +155,51 @@ export const createBrainlinkMcpServer = () => {
         description: 'Run index, stats, validate, broken-links and orphans checks in one call. Optionally run context probe.',
         inputSchema: syncInputSchema
     }, syncTool);
+    server.registerTool('brainlink_vault_status', {
+        title: 'Vault Git Status',
+        description: 'Report the vault git branch, whether it is dirty, and which Markdown files changed. Only Markdown is versioned; the derived index is git-ignored.',
+        inputSchema: vaultStatusInputSchema
+    }, vaultStatusTool);
+    server.registerTool('brainlink_vault_init', {
+        title: 'Initialize Vault Git',
+        description: 'Initialize git versioning for the vault (git init + .gitignore for the derived index), optionally setting an origin remote. Inline-credential remotes are refused.',
+        inputSchema: vaultInitInputSchema
+    }, vaultInitTool);
+    server.registerTool('brainlink_vault_provision', {
+        title: 'Provision Vault Repository',
+        description: '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. Only Markdown is versioned.',
+        inputSchema: vaultProvisionInputSchema
+    }, vaultProvisionTool);
+    server.registerTool('brainlink_vault_commit', {
+        title: 'Commit Vault Markdown',
+        description: 'Stage and commit the canonical Markdown (and .gitignore), optionally pushing to origin. Returns null commit when there is nothing to commit.',
+        inputSchema: vaultCommitInputSchema
+    }, vaultCommitTool);
+    server.registerTool('brainlink_vault_history', {
+        title: 'Vault Markdown History',
+        description: 'List recent git commits that touched the vault Markdown, with hash, author, date and subject.',
+        inputSchema: vaultHistoryInputSchema
+    }, vaultHistoryTool);
+    server.registerTool('brainlink_vault_pull', {
+        title: 'Pull Vault From Origin',
+        description: 'Pull Markdown from origin and reindex changed files so the vault stays immediately searchable. A merge conflict is aborted with a clear error instead of leaving conflict markers.',
+        inputSchema: vaultPullInputSchema
+    }, vaultPullTool);
+    server.registerTool('brainlink_vault_restore', {
+        title: 'Restore Vault To Ref',
+        description: 'Restore the vault Markdown to a git ref (commit, tag or branch) and reindex the changed files.',
+        inputSchema: vaultRestoreInputSchema
+    }, vaultRestoreTool);
+    server.registerTool('brainlink_vault_export', {
+        title: 'Export Vault Snapshot',
+        description: 'Write a portable .blvault snapshot (gzip envelope of the Markdown with per-file SHA-256). The derived index is not included; import rebuilds it.',
+        inputSchema: vaultExportInputSchema
+    }, vaultExportTool);
+    server.registerTool('brainlink_vault_import', {
+        title: 'Import Vault Snapshot',
+        description: 'Import a .blvault snapshot into the vault and reindex. Checksums are verified; divergent local files are preserved as *.conflict-<ts>.md instead of being overwritten.',
+        inputSchema: vaultImportInputSchema
+    }, vaultImportTool);
     server.registerTool('brainlink_graph', {
         title: 'Read Brainlink Graph',
         description: 'Read indexed graph nodes and wiki-link edges. Edges include weight and priority fields so agents can rank importance and priority.',

package/dist/mcp/tools/maintenance-tools.js

@@ -176,7 +176,7 @@ export const syncTool = async (input) => {
     const strategy = sanitizeContextStrategy(input.strategy, context.defaults.defaultContextStrategy);
     const contextLimit = input.contextLimit ?? context.defaults.defaultSearchLimit;
     const contextTokens = input.contextTokens ?? context.defaults.defaultContextTokens;
-    const contextPackage = await buildContextPackage(context.vault, input.contextQuery, contextLimit, contextTokens, context.agent, mode, strategy, context.defaults.defaultContextCacheTtlMs);
+    const contextPackage = await buildContextPackage(context.vault, input.contextQuery, contextLimit, contextTokens, context.agent, mode, strategy, context.defaults.defaultContextCacheTtlMs, context.defaults.cagPackTtlMs);
     const contextSession = await touchContextSession(context.vault, context.agent);
     return jsonResult({
         ...response,
@@ -198,7 +198,7 @@ export const bootstrapTool = async (input) => {
     const limit = input.limit ?? context.defaults.defaultSearchLimit;
     const tokens = input.tokens ?? context.defaults.defaultContextTokens;
     const contextPackage = input.query
-        ? await buildContextPackage(context.vault, input.query, limit, tokens, context.agent, mode, strategy, context.defaults.defaultContextCacheTtlMs)
+        ? await buildContextPackage(context.vault, input.query, limit, tokens, context.agent, mode, strategy, context.defaults.defaultContextCacheTtlMs, context.defaults.cagPackTtlMs)
         : undefined;
     const contextSession = input.query ? await touchContextSession(context.vault, context.agent) : undefined;
     const guidance = stats.documentCount === 0

package/dist/mcp/tools/read-tools.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { getBrokenLinksReport, getOrphansReport, getStats, validateVault } from '../../application/analyze-vault.js';
-import { buildContextPackage, readContextDataSignature } from '../../application/build-context.js';
+import { buildContextPackage, readContextDataSignature, readVolatileSignature } from '../../application/build-context.js';
 import { getGraph } from '../../application/get-graph.js';
 import { getGraphContexts } from '../../application/get-graph-contexts.js';
 import { explainSearchResults, suggestBrokenLinkFixes, suggestContextLinks } from '../../application/memory-suggestions.js';
@@ -107,7 +107,7 @@ export const contextTool = async (input) => {
     const strategy = sanitizeContextStrategy(input.strategy, context.defaults.defaultContextStrategy);
     const limit = input.limit ?? context.defaults.defaultSearchLimit;
     const tokens = input.tokens ?? context.defaults.defaultContextTokens;
-    const contextPackage = await buildContextPackage(context.vault, input.query, limit, tokens, context.agent, mode, strategy, context.defaults.defaultContextCacheTtlMs);
+    const contextPackage = await buildContextPackage(context.vault, input.query, limit, tokens, context.agent, mode, strategy, context.defaults.defaultContextCacheTtlMs, context.defaults.cagPackTtlMs);
     const contextSession = await touchContextSession(context.vault, context.agent);
     return jsonResult({
         vault: context.vault,
@@ -124,10 +124,14 @@ export const contextTool = async (input) => {
 export const contextPacksTool = async (input) => {
     const context = await resolveExecutionContext(input);
     const dataSignature = await readContextDataSignature(context.vault);
+    const freshness = {
+        volatileSignature: await readVolatileSignature(context.vault),
+        ttlMs: context.defaults.cagPackTtlMs
+    };
     if (input.action === 'clear') {
         const result = await clearContextPacks(context.vault, {
             staleOnly: input.staleOnly === true,
-            dataSignature
+            freshness
         });
         return jsonResult({
             vault: context.vault,
@@ -138,7 +142,7 @@ export const contextPacksTool = async (input) => {
             ...result
         });
     }
-    const packs = await listContextPacks(context.vault, dataSignature);
+    const packs = await listContextPacks(context.vault, freshness);
     return jsonResult({
         vault: context.vault,
         agent: context.agent,

package/dist/mcp/tools/vault-tools.js

@@ -0,0 +1,163 @@
+import { z } from 'zod';
+import { commitVault, initVaultGit, pullVault, pushVault, restoreVault, vaultGitStatus, vaultHistory } from '../../application/vault-git.js';
+import { provisionVaultRepo } from '../../application/provision-vault.js';
+import { exportVaultSnapshot, importVaultSnapshot } from '../../application/vault-snapshot.js';
+import { jsonResult, optionalPositiveInteger, resolveExecutionContext, vaultInput } from './shared.js';
+export const vaultStatusInputSchema = { ...vaultInput };
+export const vaultInitInputSchema = {
+    ...vaultInput,
+    remote: z.string().min(1).optional().describe('Optional git remote URL for origin. Inline credentials are rejected; use SSH or a git credential helper.'),
+    branch: z.string().min(1).optional().describe('Optional branch name to use.')
+};
+export const vaultCommitInputSchema = {
+    ...vaultInput,
+    message: z.string().min(1).describe('Commit message. Only Markdown and .gitignore are staged; the derived index is git-ignored.'),
+    push: z.boolean().optional().default(false).describe('Push to origin after committing.'),
+    branch: z.string().min(1).optional().describe('Branch to push when push is true. Defaults to the current branch.')
+};
+export const vaultHistoryInputSchema = {
+    ...vaultInput,
+    limit: optionalPositiveInteger().describe('Maximum number of Markdown commits to return. Defaults to 20.')
+};
+export const vaultPullInputSchema = {
+    ...vaultInput,
+    skipIndex: z.boolean().optional().default(false).describe('Skip the automatic reindex after pulling changed Markdown.')
+};
+export const vaultRestoreInputSchema = {
+    ...vaultInput,
+    ref: z.string().min(1).describe('Git ref (commit, tag or branch) to restore the Markdown to.'),
+    skipIndex: z.boolean().optional().default(false).describe('Skip the automatic reindex after restoring Markdown.')
+};
+export const vaultExportInputSchema = {
+    ...vaultInput,
+    outputFile: z.string().min(1).describe('Path to write the portable .blvault snapshot to.')
+};
+export const vaultImportInputSchema = {
+    ...vaultInput,
+    snapshotFile: z.string().min(1).describe('Path to a .blvault snapshot to import. Divergent local files are preserved as *.conflict-<ts>.md.'),
+    skipIndex: z.boolean().optional().default(false).describe('Skip the automatic reindex after importing Markdown.')
+};
+export const vaultProvisionInputSchema = {
+    ...vaultInput,
+    name: z.string().min(1).optional().describe('Repository name to create. Defaults to brainlink-vault.'),
+    private: z.boolean().optional().default(true).describe('Create a private repository (default true).'),
+    enableAutoVersion: z.boolean().optional().default(true).describe('Enable autoVersion so later indexed changes auto-commit and push the vault.'),
+    encrypt: z.boolean().optional().default(true).describe('Encrypt the versioned vault: commit AES-256-GCM ciphertext and git-ignore plaintext Markdown. Only a Brainlink instance holding the local key can decrypt.'),
+    message: z.string().min(1).optional().describe('Initial commit message.')
+};
+// Vault versioning shells out to the `git` binary and touches the filesystem, so
+// a missing binary or a git failure is surfaced as an actionable result rather
+// than an unhandled exception.
+const failure = (vault, error) => jsonResult({ vault, ok: false, error: error instanceof Error ? error.message : String(error) });
+const reindexSummary = (result) => ({
+    changedMarkdown: result.changedMarkdown,
+    reindexed: result.index != null
+});
+export const vaultStatusTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    try {
+        return jsonResult({ vault: context.vault, ok: true, ...(await vaultGitStatus(context.vault)) });
+    }
+    catch (error) {
+        return failure(context.vault, error);
+    }
+};
+export const vaultInitTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    try {
+        const result = await initVaultGit(context.vault, { remote: input.remote, branch: input.branch });
+        return jsonResult({ vault: context.vault, ok: true, ...result });
+    }
+    catch (error) {
+        return failure(context.vault, error);
+    }
+};
+export const vaultCommitTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    try {
+        const commit = await commitVault(context.vault, input.message);
+        if (commit && input.push === true) {
+            await pushVault(context.vault, input.branch);
+        }
+        return jsonResult({
+            vault: context.vault,
+            ok: true,
+            commit,
+            committed: commit != null,
+            pushed: commit != null && input.push === true
+        });
+    }
+    catch (error) {
+        return failure(context.vault, error);
+    }
+};
+export const vaultHistoryTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    try {
+        return jsonResult({ vault: context.vault, ok: true, history: await vaultHistory(context.vault, input.limit ?? 20) });
+    }
+    catch (error) {
+        return failure(context.vault, error);
+    }
+};
+export const vaultPullTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    try {
+        const result = await pullVault(context.vault, { skipIndex: input.skipIndex === true });
+        return jsonResult({ vault: context.vault, ok: true, ...reindexSummary(result) });
+    }
+    catch (error) {
+        return failure(context.vault, error);
+    }
+};
+export const vaultRestoreTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    try {
+        const result = await restoreVault(context.vault, input.ref, { skipIndex: input.skipIndex === true });
+        return jsonResult({ vault: context.vault, ok: true, ref: input.ref, ...reindexSummary(result) });
+    }
+    catch (error) {
+        return failure(context.vault, error);
+    }
+};
+export const vaultExportTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    try {
+        return jsonResult({ vault: context.vault, ok: true, ...(await exportVaultSnapshot(context.vault, input.outputFile)) });
+    }
+    catch (error) {
+        return failure(context.vault, error);
+    }
+};
+export const vaultImportTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    try {
+        const result = await importVaultSnapshot(input.snapshotFile, context.vault, { skipIndex: input.skipIndex === true });
+        return jsonResult({
+            vault: context.vault,
+            ok: true,
+            imported: result.imported,
+            conflicted: result.conflicted,
+            reindexed: result.index != null
+        });
+    }
+    catch (error) {
+        return failure(context.vault, error);
+    }
+};
+export const vaultProvisionTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    try {
+        const result = await provisionVaultRepo(context.vault, {
+            name: input.name,
+            private: input.private,
+            enableAutoVersion: input.enableAutoVersion,
+            encrypt: input.encrypt,
+            message: input.message
+        });
+        return jsonResult({ vault: context.vault, ok: true, ...result });
+    }
+    catch (error) {
+        return failure(context.vault, error);
+    }
+};

package/dist/mcp/tools.js

@@ -1,3 +1,4 @@
 export { brokenLinksInputSchema, brokenLinksTool, contextInputSchema, contextPacksInputSchema, contextPacksTool, contextTool, doctorActionsInputSchema, doctorActionsTool, explainInputSchema, explainTool, graphContextsInputSchema, graphContextsTool, graphInputSchema, graphTool, orphansInputSchema, orphansTool, recommendationsInputSchema, recommendationsTool, searchInputSchema, searchTool, similarNotesInputSchema, similarNotesTool, statsInputSchema, statsTool, suggestLinksInputSchema, suggestLinksTool, validateInputSchema, validateTool, versionInputSchema, versionTool } from './tools/read-tools.js';
 export { addFileInputSchema, addFileTool, addNoteInputSchema, addNoteTool, addNotesInputSchema, addNotesTool, deleteNoteInputSchema, deleteNoteTool, deleteNotesInputSchema, deleteNotesTool, inboxAddInputSchema, inboxAddTool, inboxListInputSchema, inboxListTool, inboxProcessInputSchema, inboxProcessTool, rememberInputSchema, rememberTool, volatileAddInputSchema, volatileAddTool, volatileClearInputSchema, volatileClearTool } from './tools/write-tools.js';
 export { bootstrapInputSchema, bootstrapTool, canonicalizeContextLinksInputSchema, canonicalizeContextLinksTool, dedupeInputSchema, dedupeResolveInputSchema, dedupeResolveTool, dedupeTool, indexInputSchema, indexTool, policyInputSchema, policyTool, projectInitInputSchema, projectInitTool, repairLinksInputSchema, repairLinksTool, sessionCloseInputSchema, sessionCloseTool, syncInputSchema, syncTool } from './tools/maintenance-tools.js';
+export { vaultCommitInputSchema, vaultCommitTool, vaultExportInputSchema, vaultExportTool, vaultHistoryInputSchema, vaultHistoryTool, vaultImportInputSchema, vaultImportTool, vaultInitInputSchema, vaultInitTool, vaultProvisionInputSchema, vaultProvisionTool, vaultPullInputSchema, vaultPullTool, vaultRestoreInputSchema, vaultRestoreTool, vaultStatusInputSchema, vaultStatusTool } from './tools/vault-tools.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/brainlink",
-  "version": "1.0.7",
+  "version": "1.2.0",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",
@@ -65,7 +65,8 @@
   },
   "overrides": {
     "hono": "4.12.26",
-    "qs": "6.15.2"
+    "qs": "6.15.2",
+    "fast-uri": "^4.1.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.2",