@andespindola/brainlink 1.1.0 → 1.3.0

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/docs/AGENT_USAGE.md

@@ -72,6 +72,10 @@ BRAINLINK_MCP_TOKEN="change-me" brainlink mcp-server \
 
 The central service exposes `/mcp` for MCP clients plus `/healthz` and `/readyz` for platform probes. Use a Kubernetes `Service` for internal discovery, mount the Markdown vault through a persistent volume, and pass `Authorization: Bearer <token>` from clients when `BRAINLINK_MCP_TOKEN` or `--token` is configured.
 
+## Server Instructions On Connect
+
+The MCP server advertises `instructions` in its initialize response, so any client that surfaces them (for example Claude Code) injects Brainlink's memory discipline into the agent's context on connect — no per-agent prompt configuration required. The instructions tell the agent to treat Brainlink as its default context source: call `brainlink_bootstrap` first with a task `query`, prefer `strategy: auto` and `mode: hybrid`, stash within-session facts with `brainlink_volatile_add`, and persist durable learnings with `brainlink_remember` / `brainlink_add_note` (connected with `[[wiki links]]` and tags), reindexing afterwards. The field is advisory: clients that ignore `instructions` are unaffected and no tool contract depends on it.
+
 ## Agent Namespaces
 
 Each agent writes into a dedicated namespace under `agents/<agent-id>/`:

package/package.json

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