@andespindola/brainlink 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.4.0
+
+- **Shared namespace by default.** `defaultAgent` now defaults to `shared`, so every agent (Claude, Codex, GPT, …) reads and writes the same namespace and sees each other's memory unless a call passes an explicit `--agent`/`agent`. Set `defaultAgent` to another id, or pass `--agent` per call, to scope to a private namespace.
+- **Domain partitioning on write.** `brainlink_add_note`, `brainlink_add_notes` (batch-level and per-note) and `brainlink_remember` accept a `context`. When set, the note is linked to its `<context> Hub` (created if missing) so the knowledge graph stays split into navigable domains instead of collapsing into a single per-namespace context. An explicit context always links, even when auto context links are otherwise disabled.
+- **Lossless namespace merge.** New `brainlink_vault_merge_agents` MCP tool and `blink vaults merge-agents` CLI merge one agent namespace into another within a vault (e.g. `claude-code` → `shared`) without losing data: identical notes are skipped, colliding slugs with different content are kept under a `-from-<agent>` name, everything else is moved, and merged notes are aggregated into domain hubs. Source notes are kept unless `deleteSource` is set; `dryRun` previews the plan.
+- **Stronger on-connect instructions.** The advertised server instructions now encode consult-before-acting, domain partitioning on every write, persistent and volatile memory used together, and shared-by-default so all agents form one continuous brain. The field stays advisory and no tool contract changed.
+
+## 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.

package/README.md

@@ -543,9 +543,9 @@ Available tools:
 - `brainlink_similar_notes`: find the notes most similar to a given note (by title or path), excluding the note itself.
 - `brainlink_dedupe`: detect duplicate candidates using exact hash + semantic similarity scores.
 - `brainlink_resolve_duplicate`: resolve duplicate pairs (`merge`, `link`, `ignore`) with connectivity-safe fallback edges.
-- `brainlink_add_note`: write durable Markdown memory and reindex.
-- `brainlink_add_notes`: write several notes in one batch, reindexing once.
-- `brainlink_remember`: capture durable memory with inferred title, tags and Context Links; supports dry-run.
+- `brainlink_add_note`: write durable Markdown memory and reindex. Pass `context` to partition the note under a `<context> Hub` (created if missing) so the graph stays split by domain.
+- `brainlink_add_notes`: write several notes in one batch, reindexing once. Accepts a batch-level `context` and per-note `context` overrides.
+- `brainlink_remember`: capture durable memory with inferred title, tags and Context Links; supports dry-run. Pass `context` to partition it under a domain hub.
 - `brainlink_inbox_add`: capture a quick untriaged memory item.
 - `brainlink_inbox_list`: list untriaged inbox memory items.
 - `brainlink_inbox_process`: suggest titles, tags and links for inbox items.
@@ -563,6 +563,7 @@ Available tools:
 - `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_vault_merge_agents`: losslessly merge one agent namespace into another within the same vault (e.g. `claude-code` → `shared`). Identical notes are skipped, colliding slugs with different content are kept under a `-from-<agent>` name, everything else is moved, and merged notes are aggregated into domain `<context> Hub` notes. Source notes are kept unless `deleteSource` is set; `dryRun` previews the plan.
 - `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.
@@ -1184,7 +1185,7 @@ If no `vault` is configured and no `--vault` flag is passed, Brainlink uses `$HO
 }
 ```
 
-`defaultAgent` is optional. When set, CLI and MCP calls that omit `--agent`/`agent` use this value automatically. If not set, behavior remains as before.
+`defaultAgent` defaults to `shared`, so every agent (Claude, Codex, GPT, …) reads and writes the same shared namespace and sees each other's memory unless a call passes an explicit `--agent`/`agent`. Set it to another id to make a different namespace the default, or pass `--agent` per call to scope to a private namespace.
 `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.

package/dist/application/add-note.js

@@ -29,9 +29,12 @@ export const addNoteWithMetadata = async (vaultPath, title, content, agentId = s
     const sanitizedAgentId = sanitizeAgentId(agentId);
     const filename = `agents/${sanitizedAgentId}/${slugify(title) || 'untitled'}.md`;
     await ensureVault(vaultPath);
-    const canonical = options.autoContextLinks === false
+    const contextOverride = options.context?.trim() || undefined;
+    // An explicit context always partitions the note, even when auto context links
+    // are otherwise disabled; without an override, honor the auto-link setting.
+    const canonical = options.autoContextLinks === false && !contextOverride
         ? null
-        : addCanonicalContextLinkToContent(title, content.trim(), await loadVisualContextRules(vaultPath), filename);
+        : addCanonicalContextLinkToContent(title, content.trim(), await loadVisualContextRules(vaultPath), filename, contextOverride);
     const hub = canonical?.changed
         ? await ensureCanonicalContextHub(vaultPath, canonical.context, sanitizedAgentId)
         : null;

package/dist/application/canonical-context-links.js

@@ -228,15 +228,19 @@ export const canonicalizeContextLinks = async (vaultPath, options = {}) => {
         entries
     };
 };
-export const addCanonicalContextLinkToContent = (title, content, rules = [], notePath = '') => {
-    const context = inferVisualGraphContext({
-        id: '',
-        agentId: sharedAgentId,
-        title,
-        path: notePath,
-        content,
-        tags: [],
-    }, rules);
+// When an explicit context is provided by the caller, it overrides inference so
+// a note lands in that domain hub instead of the generic per-namespace fallback
+// (which collapses every agent note into a single "Agent Memory" context). An
+// empty/whitespace override is ignored, preserving inference.
+const resolveContextTitle = (contextOverride, title, content, notePath, rules) => {
+    const explicit = contextOverride?.trim();
+    if (explicit) {
+        return explicit;
+    }
+    return inferVisualGraphContext({ id: '', agentId: sharedAgentId, title, path: notePath, content, tags: [] }, rules).title;
+};
+export const addCanonicalContextLinkToContent = (title, content, rules = [], notePath = '', contextOverride) => {
+    const context = { title: resolveContextTitle(contextOverride, title, content, notePath, rules) };
     const hubTitle = hubTitleForContext(context.title);
     const nextContent = normalizeTitle(title) === normalizeTitle(hubTitle) ? content : upsertCanonicalContextLink(content, hubTitle);
     return {

package/dist/application/merge-agent-namespace.js

@@ -0,0 +1,130 @@
+import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { sanitizeAgentId } from '../domain/agents.js';
+import { canonicalizeContextLinks } from './canonical-context-links.js';
+import { indexVault } from './index-vault.js';
+import { deleteMarkdownFile, ensureVault, readMarkdownFileSummaries, writeMarkdownFile } from '../infrastructure/file-system-vault.js';
+const toPosix = (value) => value.replaceAll('\\', '/');
+const namespacePrefix = (agentId) => `agents/${agentId}/`;
+// Content hash used only to detect exact duplicates during merge, so identical
+// notes collapse instead of producing a redundant "-from-<agent>" copy.
+const contentHash = (content) => createHash('sha256').update(content.replace(/\s+/g, ' ').trim()).digest('hex');
+// Rewrite the `agent:` value inside the leading frontmatter block so a moved
+// note reports the target namespace. Body content is left untouched.
+const rewriteAgentFrontmatter = (content, targetAgent) => {
+    const match = content.match(/^(---\r?\n)([\s\S]*?)(\r?\n---)/);
+    if (!match) {
+        return content;
+    }
+    const [, open, body, close] = match;
+    const rewrittenBody = /^agent\s*:/im.test(body)
+        ? body.replace(/^agent\s*:.*$/im, `agent: "${targetAgent}"`)
+        : `${body}\nagent: "${targetAgent}"`;
+    return `${open}${rewrittenBody}${close}${content.slice(match[0].length)}`;
+};
+const withSuffix = (relativePath, suffix) => relativePath.replace(/\.md$/i, `-${suffix}.md`);
+// Pick a target path that does not clobber an existing note. Same slug + same
+// content is treated by the caller as a no-op; same slug + different content is
+// disambiguated so no data is ever lost.
+const resolveTargetPath = (desiredPath, sourceAgent, taken) => {
+    if (!taken.has(desiredPath)) {
+        return desiredPath;
+    }
+    const primary = withSuffix(desiredPath, `from-${sourceAgent}`);
+    if (!taken.has(primary)) {
+        return primary;
+    }
+    for (let counter = 2;; counter += 1) {
+        const candidate = withSuffix(desiredPath, `from-${sourceAgent}-${counter}`);
+        if (!taken.has(candidate)) {
+            return candidate;
+        }
+    }
+};
+// Merge one agent namespace into another within the same vault, losslessly:
+// identical notes are skipped, colliding slugs with different content are
+// renamed, everything else is moved, and the merged set is aggregated into
+// domain hubs. Source notes are kept unless deleteSource is set.
+export const mergeAgentNamespace = async (vaultPath, options) => {
+    const sourceAgent = sanitizeAgentId(options.sourceAgent);
+    const targetAgent = sanitizeAgentId(options.targetAgent);
+    if (sourceAgent === targetAgent) {
+        throw new Error(`Cannot merge agent namespace "${sourceAgent}" into itself.`);
+    }
+    const absoluteVaultPath = await ensureVault(vaultPath);
+    const dryRun = options.dryRun === true;
+    const deleteSource = options.deleteSource === true;
+    const linkContexts = options.linkContexts !== false;
+    const summaries = await readMarkdownFileSummaries(absoluteVaultPath);
+    const sourcePrefix = namespacePrefix(sourceAgent);
+    const targetPrefix = namespacePrefix(targetAgent);
+    const sourceNotes = summaries.filter((summary) => toPosix(summary.relativePath).startsWith(sourcePrefix));
+    const taken = new Set(summaries.map((summary) => toPosix(summary.relativePath)));
+    const targetContentHashes = new Set();
+    await Promise.all(summaries
+        .filter((summary) => toPosix(summary.relativePath).startsWith(targetPrefix))
+        .map(async (summary) => {
+        targetContentHashes.add(contentHash(await readFile(summary.absolutePath, 'utf8')));
+    }));
+    const entries = [];
+    let moved = 0;
+    let identicalSkipped = 0;
+    let renamedCollisions = 0;
+    let deletedSource = 0;
+    for (const note of sourceNotes) {
+        const sourceRelative = toPosix(note.relativePath);
+        const raw = await readFile(note.absolutePath, 'utf8');
+        const rewritten = rewriteAgentFrontmatter(raw, targetAgent);
+        const desiredPath = targetPrefix + sourceRelative.slice(sourcePrefix.length);
+        // Exact duplicate already in the target: nothing to write, no data lost.
+        if (targetContentHashes.has(contentHash(rewritten))) {
+            identicalSkipped += 1;
+            entries.push({ sourcePath: sourceRelative, targetPath: desiredPath, action: 'identical-skipped' });
+            if (deleteSource && !dryRun) {
+                await deleteMarkdownFile(absoluteVaultPath, sourceRelative);
+                deletedSource += 1;
+            }
+            continue;
+        }
+        const targetPath = resolveTargetPath(desiredPath, sourceAgent, taken);
+        const isCollision = targetPath !== desiredPath;
+        taken.add(targetPath);
+        targetContentHashes.add(contentHash(rewritten));
+        if (!dryRun) {
+            await writeMarkdownFile(absoluteVaultPath, targetPath, rewritten);
+            if (deleteSource) {
+                await deleteMarkdownFile(absoluteVaultPath, sourceRelative);
+                deletedSource += 1;
+            }
+        }
+        if (isCollision) {
+            renamedCollisions += 1;
+            entries.push({ sourcePath: sourceRelative, targetPath, action: 'renamed-collision' });
+        }
+        else {
+            moved += 1;
+            entries.push({ sourcePath: sourceRelative, targetPath, action: 'moved' });
+        }
+    }
+    // Aggregate the merged notes into domain hubs so they partition by context
+    // instead of piling into a single namespace blob.
+    const contextLinks = linkContexts && !dryRun
+        ? await canonicalizeContextLinks(absoluteVaultPath, { agentId: targetAgent, createMissingHubs: true })
+        : null;
+    if (!dryRun && options.autoIndex !== false) {
+        await indexVault(absoluteVaultPath);
+    }
+    return {
+        sourceAgent,
+        targetAgent,
+        dryRun,
+        scanned: sourceNotes.length,
+        moved,
+        identicalSkipped,
+        renamedCollisions,
+        deletedSource,
+        contextLinksAdded: contextLinks?.changed ?? 0,
+        hubsCreated: contextLinks?.createdHubs ?? 0,
+        entries
+    };
+};

package/dist/cli/commands/vault-commands.js

@@ -1,6 +1,7 @@
 import { readdir, readFile, rm, stat } from 'node:fs/promises';
 import { extname, isAbsolute, join } from 'node:path';
 import { doctorVault } from '../../application/analyze-vault.js';
+import { mergeAgentNamespace } from '../../application/merge-agent-namespace.js';
 import { defaultBrainlinkConfig, loadBrainlinkConfig, loadRawConfig, writeRawConfig } from '../../infrastructure/config.js';
 import { assertVaultAllowed, isBucketVaultPath, resolveVaultPath } from '../../infrastructure/file-system-vault.js';
 import { print } from '../runtime.js';
@@ -144,6 +145,30 @@ export const registerVaultCommands = (program) => {
             doctor
         }, () => `Default ${scope} vault set to ${targetVault} in ${configPath}.`);
     });
+    vaultsCommand
+        .command('merge-agents <source> <target>')
+        .option('--vault <vault>', 'vault to operate on (defaults to the configured vault)')
+        .option('--delete-source', 'remove each source note after it is safely present in the target')
+        .option('--no-link-contexts', 'skip aggregating merged notes into domain hubs')
+        .option('--dry-run', 'preview the merge plan without writing anything')
+        .option('--json', 'print machine-readable JSON')
+        .description('losslessly merge one agent namespace into another within a vault')
+        .action(async (source, target, options) => {
+        const config = await loadBrainlinkConfig();
+        const vault = options.vault ? normalizeVaultPath(options.vault) : config.vault;
+        const result = await mergeAgentNamespace(vault, {
+            sourceAgent: source,
+            targetAgent: target,
+            deleteSource: options.deleteSource === true,
+            linkContexts: options.linkContexts !== false,
+            dryRun: options.dryRun === true
+        });
+        print(options.json, { vault, ...result }, () => [
+            `${result.dryRun ? 'Planned merge' : 'Merged'} ${result.sourceAgent} → ${result.targetAgent} in ${vault}`,
+            `scanned=${result.scanned} moved=${result.moved} identical-skipped=${result.identicalSkipped} renamed-collisions=${result.renamedCollisions}`,
+            `deleted-source=${result.deletedSource} hubs-created=${result.hubsCreated} context-links-added=${result.contextLinksAdded}`
+        ].join('\n'));
+    });
     vaultsCommand
         .command('delete <vault>')
         .option('--yes', 'confirm destructive vault deletion')

package/dist/infrastructure/config.js

@@ -1,14 +1,18 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { homedir } from 'node:os';
-import { sanitizeAgentId } from '../domain/agents.js';
+import { sanitizeAgentId, sharedAgentId } from '../domain/agents.js';
 import { getBrainlinkHomePath, getDefaultVaultPath } from './paths.js';
 export const defaultBrainlinkConfig = {
     vault: getDefaultVaultPath(),
     host: '127.0.0.1',
     port: 4321,
     allowedVaults: [],
-    defaultAgent: undefined,
+    // Default every agent (Claude, Codex, GPT, …) to the shared namespace so they
+    // all read and write the same memory and see each other's context. Set an
+    // explicit `agent` per call, or override defaultAgent in config, to scope to a
+    // private namespace.
+    defaultAgent: sharedAgentId,
     autoIndexOnWrite: true,
     autoCanonicalContextLinks: true,
     autoVersion: false,

package/dist/mcp/server-instructions.js

@@ -0,0 +1,31 @@
+// Advisory instructions sent to MCP clients in the initialize response. Clients
+// that support the field (e.g. Claude Code) inject this text into the agent's
+// context on connect, so every agent treats Brainlink as its default context
+// source without per-agent configuration. Clients that ignore the field are
+// unaffected — no tool contract depends on this text.
+export const brainlinkServerInstructions = `Brainlink is your brain and canonical memory — your default context source for everything. It is the continuity of your cognition across turns and sessions, not an optional tool consulted when convenient. Keep it present in your context on every turn: operating without Brainlink context is an invalid state. Ground yourself in it before any decision, recommendation, question, or implementation, and write back to it after anything worth remembering.
+
+Load context first — every session and whenever context is stale:
+- Call brainlink_bootstrap first, passing a "query" describing the current task. This checks memory state and returns a grounding context package in the same call. Do this before acting on anything relevant.
+
+Use the full potential, not shallow retrieval. Extract the maximum relevant context available before acting:
+- Both retrieval modes: RAG (fresh on-demand assembly) AND CAG (reuse of still-fresh context packs). Prefer strategy "auto" (CAG on a fresh-pack hit, RAG otherwise); force "rag"/"cag" only with a clear reason. Inspect prebuilt packs with brainlink_context_packs.
+- Hybrid search (mode "hybrid" = FTS + semantic) by default; use pure "fts"/"semantic" only when it clearly fits.
+- The knowledge graph: brainlink_graph, brainlink_graph_contexts and context packs to navigate relations between notes and contexts.
+- Explainability and quality: brainlink_explain (chunk/score), brainlink_recommendations, brainlink_validate, brainlink_stats, plus link/orphan/duplicate hygiene.
+- Volatile turn memory: brainlink_volatile_add to stash useful within-session facts (they expire on a TTL); brainlink_volatile_clear to drop them.
+
+Consult before you act. Before any decision, recommendation, question to the user, or implementation, ground yourself in Brainlink first — never act from memory alone when durable context may exist. This is not optional politeness; it is how you stay coherent across turns and sessions.
+
+Write back — after any durable learning (a preference, decision, pattern, or a change to a repo/config/doc that alters operating context):
+- Persist it with brainlink_remember (or brainlink_add_note for explicit path/content). Write connected memory: include [[wiki links]], tags, and priority markers so the graph stays navigable — not loose notes.
+- Partition by domain: pass a "context" (e.g. "RSHUB", "Brainlink", "Trading") on every write. Brainlink links the note to that domain's "<context> Hub" (creating it if missing) so the knowledge graph stays split into navigable domains instead of collapsing into one undifferentiated blob. Writing without a context is a degraded mode — always name the domain.
+- Reindex with brainlink_index and validate with brainlink_validate after writes when applicable.
+
+Persistent and volatile memory — use both, like a real brain:
+- Persistent: durable Markdown notes for anything worth remembering across sessions (decisions, preferences, project maps, runbooks, recurring gotchas).
+- Volatile: brainlink_volatile_add for within-session working state — current task, hypotheses, unconfirmed findings, transient preferences. It expires on a TTL; clear it with brainlink_volatile_clear when done. Prefer volatile for the ephemeral so persistent memory stays signal-rich.
+
+Shared by default: unless told otherwise, all agents (Claude, Codex, GPT, …) share one namespace ("shared") and one vault, so memory written by any of them is visible to all. Do not silo context into a private namespace without a clear reason — the point is one continuous brain across every agent and session.
+
+Capture context early and proactively rather than reconstructing it later. When durability is uncertain but the reuse cost is low, capture anyway; use volatile memory for what is ephemeral. Anchoring everything you learn in Brainlink — connected, partitioned by domain, and shared — is what preserves your continuity between turns, sessions and agents.`;

package/dist/mcp/server.js

@@ -1,6 +1,7 @@
 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, vaultCommitInputSchema, vaultCommitTool, vaultExportInputSchema, vaultExportTool, vaultHistoryInputSchema, vaultHistoryTool, vaultImportInputSchema, vaultImportTool, vaultInitInputSchema, vaultInitTool, vaultProvisionInputSchema, vaultProvisionTool, vaultPullInputSchema, vaultPullTool, vaultRestoreInputSchema, vaultRestoreTool, vaultStatusInputSchema, vaultStatusTool, 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, vaultMergeAgentsInputSchema, vaultMergeAgentsTool, vaultProvisionInputSchema, vaultProvisionTool, vaultPullInputSchema, vaultPullTool, vaultRestoreInputSchema, vaultRestoreTool, vaultStatusInputSchema, vaultStatusTool, versionInputSchema, versionTool } from './tools.js';
 import { getRuntimeVersion } from './runtime.js';
+import { brainlinkServerInstructions } from './server-instructions.js';
 import { guardToolHandler } from './tool-guard.js';
 export const createBrainlinkMcpServer = () => {
     const server = new McpServer({
@@ -8,7 +9,7 @@ export const createBrainlinkMcpServer = () => {
         title: 'Brainlink',
         version: getRuntimeVersion(),
         description: 'Local-first Markdown memory tools for AI agents.'
-    });
+    }, { instructions: brainlinkServerInstructions });
     // Route every tool registration through the error guard so a thrown handler
     // returns a structured isError result instead of propagating to the client.
     // Wrapping registerTool once keeps the call sites below unchanged and also
@@ -170,6 +171,11 @@ export const createBrainlinkMcpServer = () => {
         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_merge_agents', {
+        title: 'Merge Agent Namespaces',
+        description: 'Losslessly merge one agent namespace into another within the same vault (e.g. claude-code → shared): identical notes are skipped, colliding slugs with different content are kept under a "-from-<agent>" name, everything else is moved, and merged notes are aggregated into domain "<context> Hub" notes. Source notes are kept unless deleteSource is set. Use dryRun to preview.',
+        inputSchema: vaultMergeAgentsInputSchema
+    }, vaultMergeAgentsTool);
     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.',

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

@@ -2,6 +2,7 @@ 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 { mergeAgentNamespace } from '../../application/merge-agent-namespace.js';
 import { jsonResult, optionalPositiveInteger, resolveExecutionContext, vaultInput } from './shared.js';
 export const vaultStatusInputSchema = { ...vaultInput };
 export const vaultInitInputSchema = {
@@ -45,6 +46,23 @@ export const vaultProvisionInputSchema = {
     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.')
 };
+export const vaultMergeAgentsInputSchema = {
+    ...vaultInput,
+    sourceAgent: z.string().min(1).describe('Agent namespace to merge FROM (e.g. "claude-code").'),
+    targetAgent: z.string().min(1).describe('Agent namespace to merge INTO (e.g. "shared").'),
+    deleteSource: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Remove each source note after it is safely present in the target. Defaults to false (non-destructive copy).'),
+    linkContexts: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe('Aggregate merged notes into domain "<context> Hub" notes after moving. Defaults to true.'),
+    dryRun: z.boolean().optional().default(false).describe('Preview the merge plan without writing anything.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex the vault once after the merge.')
+};
 // 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.
@@ -145,6 +163,23 @@ export const vaultImportTool = async (input) => {
         return failure(context.vault, error);
     }
 };
+export const vaultMergeAgentsTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    try {
+        const result = await mergeAgentNamespace(context.vault, {
+            sourceAgent: input.sourceAgent,
+            targetAgent: input.targetAgent,
+            deleteSource: input.deleteSource,
+            linkContexts: input.linkContexts,
+            dryRun: input.dryRun,
+            autoIndex: input.autoIndex
+        });
+        return jsonResult({ vault: context.vault, ok: true, ...result });
+    }
+    catch (error) {
+        return failure(context.vault, error);
+    }
+};
 export const vaultProvisionTool = async (input) => {
     const context = await resolveExecutionContext(input);
     try {

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

@@ -16,6 +16,11 @@ export const addNoteInputSchema = {
         .min(1)
         .describe('Durable Markdown memory. Include explicit [[wiki links]] and #tags when the memory should be connected. Put priority markers near important links, for example priority: high, #important or #critical.'),
     ...agentInput,
+    context: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Domain context this memory belongs to (e.g. "RSHUB", "Brainlink", "Trading"). Strongly recommended: it partitions the note under a "<context> Hub" so the knowledge graph stays split by domain instead of collapsing into one blob. The hub is created automatically if missing.'),
     allowSensitive: z.boolean().optional().default(false).describe('Allow content that looks like a secret.'),
     autoIndex: z.boolean().optional().default(true).describe('Reindex vault after writing note.'),
     autoContextLinks: z
@@ -28,6 +33,11 @@ export const rememberInputSchema = {
     ...agentInput,
     title: z.string().min(1).optional().describe('Optional note title. When omitted, Brainlink infers it from content.'),
     content: z.string().min(1).describe('Memory content to capture as a durable Markdown note.'),
+    context: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Domain context this memory belongs to (e.g. "RSHUB", "Brainlink", "Trading"). Strongly recommended: it partitions the note under a "<context> Hub" so the knowledge graph stays split by domain. The hub is created automatically if missing.'),
     tags: z.array(z.string()).optional().default([]).describe('Extra tags to include.'),
     links: z.array(z.string()).optional().default([]).describe('Explicit Context Links to include.'),
     linkLimit: positiveInteger(5).describe('Maximum suggested Context Links to include.'),
@@ -65,11 +75,21 @@ export const addNotesInputSchema = {
     notes: z
         .array(z.object({
         title: z.string().min(1).describe('Markdown note title.'),
-        content: z.string().min(1).describe('Durable Markdown memory. Include [[wiki links]] and #tags to connect it.')
+        content: z.string().min(1).describe('Durable Markdown memory. Include [[wiki links]] and #tags to connect it.'),
+        context: z
+            .string()
+            .min(1)
+            .optional()
+            .describe('Per-note domain context override. Falls back to the batch-level context when omitted.')
     }))
         .min(1)
         .max(100)
         .describe('Notes to add in a single batch. The vault is reindexed once after all notes are written.'),
+    context: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Default domain context applied to every note in the batch (partitions them under a "<context> Hub"). Per-note context overrides it. Strongly recommended.'),
     allowSensitive: z.boolean().optional().default(false).describe('Allow content that looks like a secret.'),
     autoIndex: z.boolean().optional().default(true).describe('Reindex vault once after writing all notes.'),
     autoContextLinks: z
@@ -118,7 +138,8 @@ export const addNoteTool = async (input) => {
     const shouldIndex = isTruthy(input.autoIndex);
     const added = await addNoteWithMetadata(context.vault, input.title, input.content, context.agent, {
         allowSensitive: input.allowSensitive,
-        autoContextLinks: input.autoContextLinks ?? context.config.autoCanonicalContextLinks
+        autoContextLinks: input.autoContextLinks ?? context.config.autoCanonicalContextLinks,
+        context: input.context
     });
     const index = shouldIndex ? await indexVault(context.vault) : undefined;
     const focusPath = added.path.includes('agents/') ? added.path.slice(added.path.indexOf('agents/')).replaceAll('\\', '/') : undefined;
@@ -166,7 +187,10 @@ export const rememberTool = async (input) => {
     }
     const added = await addNoteWithMetadata(context.vault, suggestion.title, suggestion.content, context.agent, {
         allowSensitive: input.allowSensitive,
-        autoContextLinks: false
+        // remember already curates its own Context Links; only force a canonical hub
+        // link when the caller pins an explicit domain context to partition it.
+        autoContextLinks: false,
+        context: input.context
     });
     const index = input.autoIndex ? await indexVault(context.vault) : undefined;
     return jsonResult({
@@ -175,6 +199,13 @@ export const rememberTool = async (input) => {
         agent: context.agent,
         suggestion,
         path: added.path,
+        writeConnectivity: {
+            autoLinked: added.autoLinked,
+            linkTarget: added.linkTarget,
+            context: added.context,
+            hubCreated: added.hubCreated,
+            guaranteedEdge: added.autoLinked
+        },
         ...(index ? { index } : {})
     });
 };
@@ -239,7 +270,8 @@ export const addNotesTool = async (input) => {
         try {
             const added = await addNoteWithMetadata(context.vault, note.title, note.content, context.agent, {
                 allowSensitive: input.allowSensitive,
-                autoContextLinks
+                autoContextLinks,
+                context: note.context ?? input.context
             });
             notes.push({
                 ok: true,

package/dist/mcp/tools.js

@@ -1,4 +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';
+export { vaultCommitInputSchema, vaultCommitTool, vaultExportInputSchema, vaultExportTool, vaultHistoryInputSchema, vaultHistoryTool, vaultImportInputSchema, vaultImportTool, vaultInitInputSchema, vaultInitTool, vaultMergeAgentsInputSchema, vaultMergeAgentsTool, 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.2.0",
+  "version": "1.4.0",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",