@andespindola/brainlink 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 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/dist/mcp/server-instructions.js

@@ -0,0 +1,22 @@
+// 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.
+
+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.
+- Reindex with brainlink_index and validate with brainlink_validate after writes when applicable.
+
+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 is what preserves your continuity between turns and sessions.`;

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 { 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

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.3.0",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",