@andespindola/brainlink 0.1.0-alpha.0 → 0.1.0-alpha.10

package/AGENTS.md

@@ -20,17 +20,23 @@ npm run dev -- index --vault ./vault
 
 Do not store permanent knowledge only in SQLite.
 
+By default, the installed Brainlink CLI uses `$HOME/.brainlink/vault` as its vault. Passing `--vault` or setting `vault` in `brainlink.config.json` intentionally selects a custom vault such as `./vault`.
+
 ## Agent Workflow
 
 Use this loop when using Brainlink as memory:
 
 1. Write durable knowledge into Markdown notes.
-2. Link related notes with `[[Note Title]]`.
+2. Link related notes with explicit `[[Note Title]]` wiki links inside the note body.
 3. Add explicit `#tags` for retrieval.
 4. Run `index` after writes.
 5. Run `context "<task or question>"` before answering.
 6. Use the returned sources as grounded context.
 
+`context` is read-only. It does not create notes, backlinks, graph edges or durable memory by itself. A relationship exists only when a Markdown note contains a `[[wiki link]]` to another note and the vault has been indexed after that write.
+
+When an agent adds durable memory, it should connect the new note to at least one existing concept unless the note is intentionally a root concept. Prefer exact note titles in links, for example `[[Architecture]]`, and run `broken-links`, `orphans` or `validate` when the graph looks disconnected.
+
 ## Commands
 
 ```bash
@@ -80,7 +86,7 @@ npm run dev -- watch --vault ./vault
 Start MCP over stdio:
 
 ```bash
-npm run dev -- mcp
+npm run dev:mcp
 ```
 
 Automation-facing CLI commands support `--json`. When invoking through `npm`, use `npm run --silent dev -- ...` so stdout remains valid JSON.

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="./assets/brainlink-logo.svg" alt="Brainlink" width="720">
+</p>
+
 # Brainlink
 
 Local-first memory and knowledge graph for AI agents.
@@ -64,7 +68,7 @@ Markdown is the source of truth. `.brainlink/brainlink.db` is only a rebuildable
 - Agent namespaces under `agents/<agent-id>/`.
 - CLI with machine-readable `--json` output.
 - Short CLI alias: `blink`.
-- Compatible with MCP servers that execute local CLI commands.
+- Built-in MCP stdio server for agent tool integration.
 - Local HTTP API.
 - Realtime graph UI with agent selector and colored knowledge groups.
 
@@ -76,7 +80,7 @@ Requirements:
 - npm
 
 ```bash
-npm install -g @andespindola/brainlink
+npm install -g @andespindola/brainlink@latest
 ```
 
 The package installs two equivalent commands:
@@ -88,6 +92,14 @@ blink --help
 
 Use `brainlink` when clarity matters. Use `blink` for faster daily terminal usage.
 
+The npm package page may show `npm i @andespindola/brainlink`. That installs
+Brainlink as a project dependency. Use `-g` when you want the terminal commands
+available globally, or run it without a global install:
+
+```bash
+npx @andespindola/brainlink@latest --help
+```
+
 ## Agent Autonomous Setup
 
 This section is written for agents. If you are an AI agent operating in a user workspace, use this workflow to install and use Brainlink without requiring the user to run commands manually.
@@ -101,7 +113,7 @@ command -v blink || command -v brainlink
 If neither command exists, install it:
 
 ```bash
-npm install -g @andespindola/brainlink
+npm install -g @andespindola/brainlink@latest
 ```
 
 Then verify:
@@ -110,26 +122,33 @@ Then verify:
 blink --help
 ```
 
-### 2. Choose A Vault Path
+### 2. Use The Default Vault Or Choose A Custom Vault
 
-Prefer a project-local vault when memory belongs to one repository:
+By default, Brainlink stores memory in:
 
 ```bash
-BLINK_VAULT=".brainlink-vault"
+$HOME/.brainlink/vault
 ```
 
-Use a user-level vault only when memory should span many projects:
+Use the default vault when memory should span many projects:
 
 ```bash
-BLINK_VAULT="$HOME/.brainlink/vault"
+blink init
 ```
 
-Initialize the vault:
+Choose a project-local vault only when memory belongs to one repository:
 
 ```bash
+BLINK_VAULT=".brainlink-vault"
 blink init "$BLINK_VAULT"
 ```
 
+You can also set `BRAINLINK_HOME` to move Brainlink's default home directory:
+
+```bash
+export BRAINLINK_HOME="/path/to/brainlink-home"
+```
+
 ### 3. Choose An Agent Namespace
 
 Use a stable namespace for yourself:
@@ -146,7 +165,6 @@ Before answering or changing code, retrieve context:
 
 ```bash
 blink context "What should I know before working on this task?" \
-  --vault "$BLINK_VAULT" \
   --agent "$BLINK_AGENT" \
   --json
 ```
@@ -155,7 +173,6 @@ If the context is weak, inspect raw search results:
 
 ```bash
 blink search "architecture conventions tests release" \
-  --vault "$BLINK_VAULT" \
   --agent "$BLINK_AGENT" \
   --mode hybrid \
   --limit 10 \
@@ -168,23 +185,31 @@ Only store knowledge that is likely to matter later:
 
 ```bash
 blink add "Testing Policy" \
-  --vault "$BLINK_VAULT" \
   --agent "$BLINK_AGENT" \
   --content "Run npm run check before final delivery. Related: [[Release Checklist]]. #testing #process"
 ```
 
+Brainlink does not infer durable graph relationships from generated context. A context result is only a read package for the model. To create a real link in the knowledge graph, the agent must write Markdown that contains an explicit `[[Note Title]]` wiki link and then rebuild the index.
+
+When adding memory, follow this contract:
+
+- Link the new note to at least one existing note when there is a related concept.
+- Use the exact target note title inside `[[...]]`.
+- Add retrieval tags such as `#architecture`, `#decision`, `#runbook` or `#preference`.
+- Do not leave isolated notes unless they are intentionally root concepts.
+
 Rebuild the index:
 
 ```bash
-blink index --vault "$BLINK_VAULT"
+blink index
 ```
 
 ### 6. Validate Memory Health
 
 ```bash
-blink validate --vault "$BLINK_VAULT" --agent "$BLINK_AGENT" --json
-blink broken-links --vault "$BLINK_VAULT" --agent "$BLINK_AGENT" --json
-blink orphans --vault "$BLINK_VAULT" --agent "$BLINK_AGENT" --json
+blink validate --agent "$BLINK_AGENT" --json
+blink broken-links --agent "$BLINK_AGENT" --json
+blink orphans --agent "$BLINK_AGENT" --json
 ```
 
 ### Agent Operating Loop
@@ -192,12 +217,12 @@ blink orphans --vault "$BLINK_VAULT" --agent "$BLINK_AGENT" --json
 Use this loop during real work:
 
 1. Identify the task and choose `BLINK_AGENT`.
-2. Run `blink context "<task>" --vault "$BLINK_VAULT" --agent "$BLINK_AGENT" --json`.
+2. Run `blink context "<task>" --agent "$BLINK_AGENT" --json`.
 3. Use returned sources as project memory.
 4. Perform the task.
-5. Save only durable learnings with `blink add`.
+5. Save only durable learnings with `blink add`, including `[[wiki links]]` to related notes.
 6. Run `blink index`.
-7. Validate with `blink validate`.
+7. Validate with `blink validate`, `blink broken-links` and `blink orphans` when graph links matter.
 
 Do not store secrets, credentials, private keys, access tokens or transient chat noise.
 
@@ -229,6 +254,8 @@ Open the graph UI:
 http://127.0.0.1:4321
 ```
 
+When `--vault` is omitted, commands use the default vault at `$HOME/.brainlink/vault`. Pass `--vault` or configure `vault` in `brainlink.config.json` when you want a custom project-local vault.
+
 ## Core Model
 
 ```txt
@@ -307,59 +334,47 @@ This allows `coding-agent` and `research-agent` to both have a note named `Archi
 
 ## MCP Server Integration
 
-Brainlink is not an MCP server. It is a CLI-first memory engine.
-
-An MCP server can use Brainlink by spawning `blink` or `brainlink` as a subprocess and reading `--json` output. This keeps Brainlink decoupled from any specific MCP SDK while still making it usable by MCP-compatible agents.
-
-Minimum integration contract:
+Brainlink ships a stdio MCP server with the npm package:
 
 ```bash
-blink context "<task>" --vault "$BLINK_VAULT" --agent "$BLINK_AGENT" --json
-blink add "Decision Title" --vault "$BLINK_VAULT" --agent "$BLINK_AGENT" --content "Durable memory. #decision"
-blink index --vault "$BLINK_VAULT"
+brainlink-mcp
 ```
 
-Example Node.js wrapper inside an external MCP server:
-
-```js
-import { execFile } from 'node:child_process'
-import { promisify } from 'node:util'
+Example MCP client configuration:
 
-const execFileAsync = promisify(execFile)
-
-export const brainlinkContext = async ({ vault, agent, query }) => {
-  const { stdout } = await execFileAsync('blink', [
-    'context',
-    query,
-    '--vault',
-    vault,
-    '--agent',
-    agent,
-    '--mode',
-    'hybrid',
-    '--json'
-  ])
-
-  return JSON.parse(stdout)
+```json
+{
+  "mcpServers": {
+    "brainlink": {
+      "command": "brainlink-mcp"
+    }
+  }
 }
 ```
 
-Recommended MCP tools exposed by the external server:
+Available tools:
+
+- `brainlink_context`: read indexed context for a task or question.
+- `brainlink_search`: search indexed notes.
+- `brainlink_add_note`: write durable Markdown memory and reindex.
+- `brainlink_index`: rebuild the vault index.
+- `brainlink_validate`: validate broken links and orphan notes.
+- `brainlink_graph`: read indexed graph nodes and links.
+- `brainlink_broken_links`: list unresolved wiki links.
+- `brainlink_orphans`: list disconnected notes.
 
-- `brainlink_context`: calls `blink context ... --json`.
-- `brainlink_search`: calls `blink search ... --json`.
-- `brainlink_add_note`: calls `blink add ... --json`, then `blink index`.
-- `brainlink_graph`: calls `blink graph ... --json`.
-- `brainlink_validate`: calls `blink validate ... --json`.
+The same linking rule applies through MCP: `brainlink_context` is read-only, and real graph links require Markdown notes with explicit `[[wiki links]]` followed by indexing.
 
 ## Graph UI
 
 Start the local frontend:
 
 ```bash
-blink server --vault ./vault --host 127.0.0.1 --port 4321 --watch
+blink server --host 127.0.0.1 --port 4321 --watch
 ```
 
+By default, the server uses `$HOME/.brainlink/vault`. Pass `--vault ./vault` only when you want to inspect a custom vault.
+
 The graph UI shows:
 
 - notes as nodes
@@ -380,7 +395,7 @@ blink server --vault ./vault --no-index
 
 The HTTP API is read-only and exists only to power the graph UI and local inspection workflows.
 
-The server refuses non-loopback hosts by default. Use `--allow-public` only behind your own authentication, authorization and TLS.
+The server always refuses non-loopback hosts. Brainlink HTTP only runs on localhost.
 
 Routes:
 
@@ -411,14 +426,16 @@ Every command works with either `brainlink` or `blink`.
 ### `init`
 
 ```bash
+blink init
 blink init ./vault
 ```
 
-Initializes vault metadata.
+Initializes vault metadata. Without an argument, Brainlink initializes the default vault at `$HOME/.brainlink/vault`.
 
 ### `add`
 
 ```bash
+blink add "Note Title" --agent coding-agent --content "Markdown content"
 blink add "Note Title" --vault ./vault --agent coding-agent --content "Markdown content"
 ```
 
@@ -427,6 +444,7 @@ Creates a Markdown note under `agents/<agent-id>/`. Common secret patterns are b
 ### `index`
 
 ```bash
+blink index
 blink index --vault ./vault
 ```
 
@@ -546,12 +564,13 @@ Watches Markdown files and rebuilds the index when notes change.
 ### `server`
 
 ```bash
+blink server --watch
 blink server --vault ./vault --watch
 ```
 
 Starts the local read-only graph UI and HTTP API.
 
-To bind outside localhost, pass `--allow-public` and put the server behind your own auth and TLS.
+The HTTP server only binds to loopback hosts such as `127.0.0.1`, `localhost` or `::1`.
 
 ## Machine-Readable Output
 
@@ -569,7 +588,7 @@ npm run --silent dev -- context "question" --vault ./vault --json
 
 ## Configuration
 
-Brainlink reads `brainlink.config.json` or `.brainlink.json` from the current working directory.
+Brainlink reads `brainlink.config.json` or `.brainlink.json` from the current working directory. If no `vault` is configured and no `--vault` flag is passed, Brainlink uses `$HOME/.brainlink/vault`.
 
 ```json
 {
@@ -679,7 +698,6 @@ Detailed notes:
 - Semantic search uses SQLite embedding buckets to narrow candidates before cosine scoring.
 - `embeddingProvider` currently supports `local` and `none`.
 - Link resolution is title-based inside each agent namespace, with `shared` as fallback.
-- No embedded MCP server is shipped; MCP integration is done by external servers wrapping the CLI.
 - HTTP API is local and unauthenticated.
 - Watch mode depends on the platform filesystem watcher.
 
@@ -700,6 +718,7 @@ The alpha includes local semantic retrieval. Remote embedding providers, remote
 Brainlink is local-first by default.
 
 - Do not expose the HTTP server publicly without authentication.
+- Brainlink HTTP is localhost-only and refuses non-loopback hosts.
 - Brainlink blocks common secret patterns by default when adding notes. Use `--allow-sensitive` only for intentional, protected vaults.
 - Do not store secrets, credentials, API keys or regulated personal data unless the vault is protected by your own storage controls.
 - Treat `.brainlink/brainlink.db` as disposable derived data.

package/SECURITY.md

@@ -5,7 +5,7 @@ Brainlink is local-first.
 ## Defaults
 
 - The HTTP server binds to `127.0.0.1` by default.
-- The HTTP server refuses non-loopback hosts unless `--allow-public` is passed.
+- The HTTP server always refuses non-loopback hosts.
 - The HTTP server is read-only and does not expose note creation, indexing or update routes.
 - The SQLite database is a derived local index.
 - Markdown files are user-owned source data.
@@ -14,7 +14,7 @@ Brainlink is local-first.
 
 ## Remote Exposure
 
-Do not expose the HTTP server on a public interface without adding authentication, authorization and transport security.
+Brainlink HTTP is intentionally localhost-only. It does not support binding to a public interface.
 
 ## Sensitive Memory
 

package/assets/brainlink-logo.svg

@@ -0,0 +1,25 @@
+<svg width="900" height="220" viewBox="0 0 900 220" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">
+  <title id="title">Brainlink</title>
+  <desc id="desc">Brainlink logo with a linked memory graph mark and wordmark.</desc>
+  <rect width="900" height="220" fill="transparent"/>
+  <g transform="translate(42 24)">
+    <rect x="6" y="6" width="160" height="160" rx="36" fill="#F8FAFC"/>
+    <rect x="6" y="6" width="160" height="160" rx="36" stroke="#111827" stroke-width="8"/>
+    <path d="M47 84C47 65.225 62.225 50 81 50H92C110.775 50 126 65.225 126 84C126 102.775 110.775 118 92 118H81C62.225 118 47 102.775 47 84Z" stroke="#111827" stroke-width="12" stroke-linecap="round"/>
+    <path d="M67 84C67 76.268 73.268 70 81 70H92C99.732 70 106 76.268 106 84C106 91.732 99.732 98 92 98H81C73.268 98 67 91.732 67 84Z" fill="#FFFFFF"/>
+    <path d="M54 132L43 121L54 110" stroke="#2563EB" stroke-width="10" stroke-linecap="round" stroke-linejoin="round"/>
+    <path d="M118 110L129 121L118 132" stroke="#2563EB" stroke-width="10" stroke-linecap="round" stroke-linejoin="round"/>
+    <circle cx="55" cy="43" r="12" fill="#14B8A6"/>
+    <circle cx="121" cy="43" r="12" fill="#2563EB"/>
+    <circle cx="86" cy="136" r="12" fill="#111827"/>
+    <path d="M66.5 47.5L109.5 47.5" stroke="#94A3B8" stroke-width="7" stroke-linecap="round"/>
+    <path d="M62 54L79 125" stroke="#94A3B8" stroke-width="7" stroke-linecap="round"/>
+    <path d="M115 54L92 125" stroke="#94A3B8" stroke-width="7" stroke-linecap="round"/>
+  </g>
+  <g transform="translate(244 68)">
+    <text x="0" y="62" fill="#111827" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" font-size="72" font-weight="760">Brainlink</text>
+    <text x="4" y="102" fill="#475569" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" font-size="24" font-weight="500">Local-first memory for AI agents</text>
+    <path d="M0 124H268" stroke="#14B8A6" stroke-width="8" stroke-linecap="round"/>
+    <path d="M292 124H392" stroke="#2563EB" stroke-width="8" stroke-linecap="round"/>
+  </g>
+</svg>

package/dist/application/server/host-security.js

@@ -1,6 +1,6 @@
 export const isLoopbackHost = (host) => host === 'localhost' || host === '::1' || host === '[::1]' || host.startsWith('127.');
-export const assertPublicBindAllowed = (host, allowPublic = false) => {
-    if (!allowPublic && !isLoopbackHost(host)) {
-        throw new Error(`Refusing to bind Brainlink server to non-loopback host ${host}. Pass --allow-public only behind your own auth and TLS.`);
+export const assertLoopbackHost = (host) => {
+    if (!isLoopbackHost(host)) {
+        throw new Error(`Refusing to bind Brainlink server to non-loopback host ${host}. Brainlink HTTP only runs on localhost.`);
     }
 };

package/dist/application/start-server.js

@@ -1,11 +1,11 @@
 import { createServer } from 'node:http';
 import { indexVault } from './index-vault.js';
 import { startVaultWatcher } from './watch-vault.js';
-import { assertPublicBindAllowed } from './server/host-security.js';
+import { assertLoopbackHost } from './server/host-security.js';
 import { contentTypes, createJsonResponse, isHttpError } from './server/http.js';
 import { route } from './server/routes.js';
 export const startServer = async (input) => {
-    assertPublicBindAllowed(input.host, input.allowPublic);
+    assertLoopbackHost(input.host);
     if (input.shouldIndex) {
         await indexVault(input.vaultPath);
     }

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

@@ -10,7 +10,7 @@ export const registerReadCommands = (program) => {
     program
         .command('search')
         .argument('<query>', 'search query')
-        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('-v, --vault <vault>', 'vault directory')
         .option('-a, --agent <agent>', 'filter by agent memory namespace')
         .option('-l, --limit <limit>', 'maximum results', '10')
         .option('-m, --mode <mode>', 'search mode: fts, semantic or hybrid')
@@ -27,7 +27,7 @@ export const registerReadCommands = (program) => {
     });
     program
         .command('links')
-        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('-v, --vault <vault>', 'vault directory')
         .option('-a, --agent <agent>', 'filter by agent memory namespace')
         .option('--json', 'print machine-readable JSON')
         .description('list indexed wiki links')
@@ -44,7 +44,7 @@ export const registerReadCommands = (program) => {
     program
         .command('backlinks')
         .argument('<title>', 'target note title')
-        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('-v, --vault <vault>', 'vault directory')
         .option('-a, --agent <agent>', 'filter by agent memory namespace')
         .option('--json', 'print machine-readable JSON')
         .description('list notes linking to a target note')
@@ -56,7 +56,7 @@ export const registerReadCommands = (program) => {
     program
         .command('context')
         .argument('<query>', 'context query')
-        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('-v, --vault <vault>', 'vault directory')
         .option('-a, --agent <agent>', 'filter by agent memory namespace')
         .option('-l, --limit <limit>', 'maximum search results before context selection', '12')
         .option('-t, --tokens <tokens>', 'maximum estimated context tokens', '2000')
@@ -71,7 +71,7 @@ export const registerReadCommands = (program) => {
     });
     program
         .command('graph')
-        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('-v, --vault <vault>', 'vault directory')
         .option('-a, --agent <agent>', 'filter by agent memory namespace')
         .option('--json', 'print machine-readable JSON')
         .description('print indexed graph data')
@@ -82,7 +82,7 @@ export const registerReadCommands = (program) => {
     });
     program
         .command('agents')
-        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('-v, --vault <vault>', 'vault directory')
         .option('--json', 'print machine-readable JSON')
         .description('list indexed agent memory namespaces')
         .action(async (options) => {
@@ -92,7 +92,7 @@ export const registerReadCommands = (program) => {
     });
     program
         .command('stats')
-        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('-v, --vault <vault>', 'vault directory')
         .option('-a, --agent <agent>', 'filter by agent memory namespace')
         .option('--json', 'print machine-readable JSON')
         .description('print indexed vault statistics')
@@ -110,7 +110,7 @@ export const registerReadCommands = (program) => {
     });
     program
         .command('broken-links')
-        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('-v, --vault <vault>', 'vault directory')
         .option('-a, --agent <agent>', 'filter by agent memory namespace')
         .option('--json', 'print machine-readable JSON')
         .description('list unresolved wiki links')
@@ -123,7 +123,7 @@ export const registerReadCommands = (program) => {
     });
     program
         .command('orphans')
-        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('-v, --vault <vault>', 'vault directory')
         .option('-a, --agent <agent>', 'filter by agent memory namespace')
         .option('--json', 'print machine-readable JSON')
         .description('list indexed notes without incoming or outgoing links')
@@ -134,7 +134,7 @@ export const registerReadCommands = (program) => {
     });
     program
         .command('validate')
-        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('-v, --vault <vault>', 'vault directory')
         .option('-a, --agent <agent>', 'filter by agent memory namespace')
         .option('--json', 'print machine-readable JSON')
         .description('validate indexed vault graph health')

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

@@ -9,19 +9,19 @@ import { parsePositiveInteger, print, resolveOptions } from '../runtime.js';
 export const registerWriteCommands = (program) => {
     program
         .command('init')
-        .argument('[vault]', 'vault directory', '.')
+        .argument('[vault]', 'vault directory')
         .option('--json', 'print machine-readable JSON')
         .description('initialize a Brainlink vault')
         .action(async (vault, options) => {
         const config = await loadBrainlinkConfig();
-        const path = await ensureVault(assertVaultAllowed(vault, config.allowedVaults));
+        const path = await ensureVault(assertVaultAllowed(vault ?? config.vault, config.allowedVaults));
         print(options.json, { path }, () => `Initialized Brainlink vault at ${path}`);
     });
     program
         .command('add')
         .argument('<title>', 'note title')
         .requiredOption('-c, --content <content>', 'markdown content')
-        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('-v, --vault <vault>', 'vault directory')
         .option('-a, --agent <agent>', 'agent memory namespace', 'shared')
         .option('--allow-sensitive', 'allow writing content that looks like a secret')
         .option('--json', 'print machine-readable JSON')
@@ -35,7 +35,7 @@ export const registerWriteCommands = (program) => {
     });
     program
         .command('index')
-        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('-v, --vault <vault>', 'vault directory')
         .option('--json', 'print machine-readable JSON')
         .description('index markdown notes, links, tags and chunks')
         .action(async (options) => {
@@ -45,7 +45,7 @@ export const registerWriteCommands = (program) => {
     });
     program
         .command('doctor')
-        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('-v, --vault <vault>', 'vault directory')
         .option('--json', 'print machine-readable JSON')
         .description('run Brainlink environment and vault checks')
         .action(async (options) => {
@@ -56,7 +56,7 @@ export const registerWriteCommands = (program) => {
     });
     program
         .command('watch')
-        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('-v, --vault <vault>', 'vault directory')
         .option('--json', 'print machine-readable JSON events')
         .description('watch markdown files and reindex on changes')
         .action(async (options) => {
@@ -84,12 +84,11 @@ export const registerWriteCommands = (program) => {
     });
     program
         .command('server')
-        .option('-v, --vault <vault>', 'vault directory', '.')
+        .option('-v, --vault <vault>', 'vault directory')
         .option('-h, --host <host>', 'server host', '127.0.0.1')
         .option('-p, --port <port>', 'server port', '4321')
         .option('--no-index', 'skip indexing before starting the server')
         .option('-w, --watch', 'watch markdown files and reindex on changes')
-        .option('--allow-public', 'allow binding the server to a non-loopback host')
         .option('--json', 'print machine-readable JSON')
         .description('start a local web UI for the knowledge graph')
         .action(async (options) => {
@@ -99,8 +98,7 @@ export const registerWriteCommands = (program) => {
             host: options.host ?? resolved.config.host,
             port: parsePositiveInteger(options.port ?? String(resolved.config.port), resolved.config.port),
             shouldIndex: options.index,
-            shouldWatch: Boolean(options.watch),
-            allowPublic: Boolean(options.allowPublic)
+            shouldWatch: Boolean(options.watch)
         });
         print(options.json, { url: server.url, watch: Boolean(options.watch), readonly: true }, () => `Brainlink graph server running at ${server.url}`);
     });

package/dist/cli/main.js

@@ -1,8 +1,15 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
-import { basename } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { registerReadCommands } from './commands/read-commands.js';
 import { registerWriteCommands } from './commands/write-commands.js';
+const readPackageVersion = () => {
+    const packagePath = join(dirname(fileURLToPath(import.meta.url)), '../../package.json');
+    const metadata = JSON.parse(readFileSync(packagePath, 'utf8'));
+    return metadata.version ?? '0.0.0';
+};
 const program = new Command();
 const cliName = basename(process.argv[1] ?? 'brainlink');
 const displayName = cliName === 'blink' ? 'blink' : 'brainlink';
@@ -11,7 +18,7 @@ program
     .name(displayName)
     .alias(aliasName)
     .description('Local-first knowledge memory for agents')
-    .version('0.1.0');
+    .version(readPackageVersion());
 registerWriteCommands(program);
 registerReadCommands(program);
 program.parseAsync().catch((error) => {

package/dist/infrastructure/config.js

@@ -1,7 +1,8 @@
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
+import { getDefaultVaultPath } from './paths.js';
 export const defaultBrainlinkConfig = {
-    vault: '.',
+    vault: getDefaultVaultPath(),
     host: '127.0.0.1',
     port: 4321,
     allowedVaults: [],

package/dist/infrastructure/file-system-vault.js

@@ -1,5 +1,6 @@
 import { chmod, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { dirname, extname, isAbsolute, join, relative, resolve } from 'node:path';
+import { resolvePath } from './paths.js';
 const excludedDirectories = new Set(['.brainlink', '.git', 'node_modules', 'dist']);
 const directoryMode = 0o700;
 const fileMode = 0o600;
@@ -14,7 +15,7 @@ const walkMarkdownFiles = async (directory) => {
     }));
     return nested.flat();
 };
-export const resolveVaultPath = (vaultPath) => resolve(process.cwd(), vaultPath);
+export const resolveVaultPath = (vaultPath) => resolvePath(vaultPath);
 const isPathInside = (parent, child) => {
     const path = relative(parent, child);
     return path === '' || (!path.startsWith('..') && !isAbsolute(path));

package/dist/infrastructure/paths.js

@@ -0,0 +1,14 @@
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+const defaultHomeDirectoryName = '.brainlink';
+const defaultVaultDirectoryName = 'vault';
+export const expandHomePath = (path) => path === '~' || path.startsWith('~/') ? join(homedir(), path.slice(2)) : path;
+export const resolvePath = (path, cwd = process.cwd()) => {
+    const expandedPath = expandHomePath(path);
+    return isAbsolute(expandedPath) ? expandedPath : resolve(cwd, expandedPath);
+};
+export const getBrainlinkHomePath = () => {
+    const configuredHome = process.env.BRAINLINK_HOME?.trim();
+    return configuredHome ? resolvePath(configuredHome) : join(homedir(), defaultHomeDirectoryName);
+};
+export const getDefaultVaultPath = () => join(getBrainlinkHomePath(), defaultVaultDirectoryName);

package/dist/infrastructure/sqlite/schema.js

@@ -1,4 +1,9 @@
 const schemaVersion = 4;
+const requiredTableColumns = {
+    documents: ['id', 'agent_id', 'title', 'path', 'content', 'tags_json', 'frontmatter_json', 'created_at', 'updated_at'],
+    chunks: ['id', 'document_id', 'ordinal', 'content', 'token_count', 'embedding_provider', 'embedding_json'],
+    chunks_fts: ['chunk_id', 'document_id', 'agent_id', 'title', 'content']
+};
 const getStoredSchemaVersion = (database) => {
     const hasMetadata = database
         .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'metadata'")
@@ -18,9 +23,17 @@ const dropDerivedSchema = (database) => {
     DROP TABLE IF EXISTS documents;
   `);
 };
+const getTableColumns = (database, tableName) => {
+    const rows = database.prepare(`SELECT name FROM pragma_table_info(?)`).all(tableName);
+    return rows.map((row) => row.name);
+};
+const hasCompatibleSchemaShape = (database) => Object.entries(requiredTableColumns).every(([tableName, requiredColumns]) => {
+    const columns = getTableColumns(database, tableName);
+    return columns.length === 0 || requiredColumns.every((column) => columns.includes(column));
+});
 export const createSchema = (database) => {
     const storedSchemaVersion = getStoredSchemaVersion(database);
-    if (storedSchemaVersion > 0 && storedSchemaVersion < schemaVersion) {
+    if ((storedSchemaVersion > 0 && storedSchemaVersion < schemaVersion) || !hasCompatibleSchemaShape(database)) {
         dropDerivedSchema(database);
     }
     database.exec(`

package/dist/mcp/main.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createBrainlinkMcpServer } from './server.js';
+const server = createBrainlinkMcpServer();
+const transport = new StdioServerTransport();
+server.connect(transport).catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exitCode = 1;
+});

package/dist/mcp/server.js

@@ -0,0 +1,59 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { addNoteInputSchema, addNoteTool, brokenLinksInputSchema, brokenLinksTool, contextInputSchema, contextTool, graphInputSchema, graphTool, indexInputSchema, indexTool, orphansInputSchema, orphansTool, searchInputSchema, searchTool, validateInputSchema, validateTool } from './tools.js';
+const readPackageVersion = () => {
+    const packagePath = join(dirname(fileURLToPath(import.meta.url)), '../../package.json');
+    const metadata = JSON.parse(readFileSync(packagePath, 'utf8'));
+    return metadata.version ?? '0.0.0';
+};
+export const createBrainlinkMcpServer = () => {
+    const server = new McpServer({
+        name: 'brainlink',
+        title: 'Brainlink',
+        version: readPackageVersion(),
+        description: 'Local-first Markdown memory tools for AI agents.'
+    });
+    server.registerTool('brainlink_context', {
+        title: 'Build Brainlink Context',
+        description: 'Read indexed Brainlink memory for a task or question. This is read-only and does not create graph links.',
+        inputSchema: contextInputSchema
+    }, contextTool);
+    server.registerTool('brainlink_search', {
+        title: 'Search Brainlink Memory',
+        description: 'Search indexed Brainlink notes with FTS, semantic or hybrid retrieval.',
+        inputSchema: searchInputSchema
+    }, searchTool);
+    server.registerTool('brainlink_add_note', {
+        title: 'Add Brainlink Note',
+        description: 'Write durable Markdown memory, then reindex the vault. Include explicit [[wiki links]] for connected graph memory.',
+        inputSchema: addNoteInputSchema
+    }, addNoteTool);
+    server.registerTool('brainlink_index', {
+        title: 'Index Brainlink Vault',
+        description: 'Rebuild the local Brainlink index from Markdown notes.',
+        inputSchema: indexInputSchema
+    }, indexTool);
+    server.registerTool('brainlink_validate', {
+        title: 'Validate Brainlink Vault',
+        description: 'Validate indexed graph health, including broken links and orphan notes.',
+        inputSchema: validateInputSchema
+    }, validateTool);
+    server.registerTool('brainlink_graph', {
+        title: 'Read Brainlink Graph',
+        description: 'Read indexed graph nodes and wiki-link edges.',
+        inputSchema: graphInputSchema
+    }, graphTool);
+    server.registerTool('brainlink_broken_links', {
+        title: 'List Brainlink Broken Links',
+        description: 'List unresolved indexed wiki links.',
+        inputSchema: brokenLinksInputSchema
+    }, brokenLinksTool);
+    server.registerTool('brainlink_orphans', {
+        title: 'List Brainlink Orphans',
+        description: 'List indexed notes without incoming or outgoing graph links.',
+        inputSchema: orphansInputSchema
+    }, orphansTool);
+    return server;
+};

package/dist/mcp/tools.js

@@ -0,0 +1,166 @@
+import { z } from 'zod';
+import { getBrokenLinksReport, getOrphansReport, validateVault } from '../application/analyze-vault.js';
+import { addNote } from '../application/add-note.js';
+import { buildContextPackage } from '../application/build-context.js';
+import { getGraph } from '../application/get-graph.js';
+import { indexVault } from '../application/index-vault.js';
+import { searchKnowledge } from '../application/search-knowledge.js';
+import { sanitizeSearchMode } from '../infrastructure/config.js';
+import { loadBrainlinkConfig } from '../infrastructure/config.js';
+import { assertVaultAllowed } from '../infrastructure/file-system-vault.js';
+const positiveInteger = (fallback) => z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .transform((value) => value ?? fallback);
+const vaultInput = {
+    vault: z.string().min(1).optional().describe('Vault directory. Omit to use the configured Brainlink default vault.')
+};
+const agentInput = {
+    agent: z.string().min(1).optional().describe('Agent memory namespace. Omit to read shared/default indexed memory.')
+};
+const searchModeInput = {
+    mode: z.enum(['fts', 'semantic', 'hybrid']).optional().describe('Search mode. Defaults to the Brainlink config value.')
+};
+const resolveVault = async (vault) => {
+    const config = await loadBrainlinkConfig();
+    return assertVaultAllowed(vault ?? config.vault, config.allowedVaults);
+};
+const jsonResult = (value) => ({
+    content: [
+        {
+            type: 'text',
+            text: JSON.stringify(value, null, 2)
+        }
+    ],
+    structuredContent: value
+});
+export const contextInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    ...searchModeInput,
+    query: z.string().min(1).describe('Task or question to retrieve Brainlink context for.'),
+    limit: positiveInteger(12).describe('Maximum search results before context selection.'),
+    tokens: positiveInteger(2000).describe('Maximum estimated context tokens.')
+};
+export const searchInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    ...searchModeInput,
+    query: z.string().min(1).describe('Search query.'),
+    limit: positiveInteger(10).describe('Maximum result count.')
+};
+export const addNoteInputSchema = {
+    ...vaultInput,
+    title: z.string().min(1).describe('Markdown note title.'),
+    content: z
+        .string()
+        .min(1)
+        .describe('Durable Markdown memory. Include explicit [[wiki links]] and #tags when the memory should be connected.'),
+    agent: z.string().min(1).optional().default('shared').describe('Agent memory namespace. Defaults to shared.'),
+    allowSensitive: z.boolean().optional().default(false).describe('Allow content that looks like a secret.')
+};
+export const indexInputSchema = {
+    ...vaultInput
+};
+export const validateInputSchema = {
+    ...vaultInput,
+    ...agentInput
+};
+export const graphInputSchema = {
+    ...vaultInput,
+    ...agentInput
+};
+export const brokenLinksInputSchema = {
+    ...vaultInput,
+    ...agentInput
+};
+export const orphansInputSchema = {
+    ...vaultInput,
+    ...agentInput
+};
+export const contextTool = async (input) => {
+    const vault = await resolveVault(input.vault);
+    const config = await loadBrainlinkConfig();
+    const mode = sanitizeSearchMode(input.mode, config.defaultSearchMode);
+    const contextPackage = await buildContextPackage(vault, input.query, input.limit, input.tokens, input.agent, mode);
+    return jsonResult({
+        vault,
+        agent: input.agent,
+        mode,
+        ...contextPackage
+    });
+};
+export const searchTool = async (input) => {
+    const vault = await resolveVault(input.vault);
+    const config = await loadBrainlinkConfig();
+    const mode = sanitizeSearchMode(input.mode, config.defaultSearchMode);
+    const results = await searchKnowledge(vault, input.query, input.limit, input.agent, mode);
+    return jsonResult({
+        vault,
+        agent: input.agent,
+        query: input.query,
+        limit: input.limit,
+        mode,
+        results
+    });
+};
+export const addNoteTool = async (input) => {
+    const vault = await resolveVault(input.vault);
+    const path = await addNote(vault, input.title, input.content, input.agent, {
+        allowSensitive: input.allowSensitive
+    });
+    const index = await indexVault(vault);
+    return jsonResult({
+        vault,
+        title: input.title,
+        agent: input.agent,
+        path,
+        index
+    });
+};
+export const indexTool = async (input) => {
+    const vault = await resolveVault(input.vault);
+    const result = await indexVault(vault);
+    return jsonResult({
+        vault,
+        ...result
+    });
+};
+export const validateTool = async (input) => {
+    const vault = await resolveVault(input.vault);
+    const validation = await validateVault(vault, input.agent);
+    return jsonResult({
+        vault,
+        agent: input.agent,
+        ...validation
+    });
+};
+export const graphTool = async (input) => {
+    const vault = await resolveVault(input.vault);
+    const graph = await getGraph(vault, input.agent);
+    return jsonResult({
+        vault,
+        agent: input.agent,
+        ...graph
+    });
+};
+export const brokenLinksTool = async (input) => {
+    const vault = await resolveVault(input.vault);
+    const brokenLinks = await getBrokenLinksReport(vault, input.agent);
+    return jsonResult({
+        vault,
+        agent: input.agent,
+        brokenLinks
+    });
+};
+export const orphansTool = async (input) => {
+    const vault = await resolveVault(input.vault);
+    const orphans = await getOrphansReport(vault, input.agent);
+    return jsonResult({
+        vault,
+        agent: input.agent,
+        orphans
+    });
+};

package/docs/AGENT_USAGE.md

@@ -29,6 +29,18 @@ blink --help
 
 Use `blink` as the short terminal alias and `brainlink` in documentation when explicit naming is more important.
 
+## Default Vault
+
+When `--vault` is omitted, Brainlink uses a user-level vault:
+
+```txt
+$HOME/.brainlink/vault
+```
+
+`blink server` follows the same rule, so it serves the default Brainlink vault instead of the current working directory.
+
+Use `--vault <path>` for a one-off custom vault, or set `vault` in `brainlink.config.json` / `.brainlink.json` for a workspace-level custom default. Set `BRAINLINK_HOME` when the whole Brainlink home directory should live somewhere else.
+
 ## Agent Namespaces
 
 Each agent writes into a dedicated namespace under `agents/<agent-id>/`:
@@ -126,12 +138,47 @@ Rules:
 - Prefer summaries over raw transcripts.
 - Preserve dates when the timing matters.
 
+## Linking Contract
+
+Brainlink only builds graph edges from Markdown `[[wiki links]]`.
+
+The `context` command is read-only. It retrieves indexed notes and returns a compact package for the model, but it does not write memory, create backlinks, infer relationships or modify the graph. If an agent reads context and then learns something durable, the agent must write a note with explicit links before that knowledge becomes connected memory.
+
+Required write behavior:
+
+1. Choose a clear title for the new note.
+2. Look for an existing related concept with `search`, `links` or `backlinks`.
+3. Add at least one `[[Existing Note Title]]` link unless the note is intentionally a root concept.
+4. Add useful `#tags` for retrieval.
+5. Run `index` after the write.
+6. Run `validate`, `broken-links` or `orphans` when the graph should be connected.
+
+Good linked note:
+
+```bash
+blink add "SQLite Index Rebuild" \
+  --agent coding-agent \
+  --content "Legacy derived indexes without agent columns are rebuilt because SQLite is disposable. Related: [[Architecture]], [[Agent Namespaces]]. #sqlite #architecture #decision"
+blink index
+blink validate --agent coding-agent
+```
+
+Poor disconnected note:
+
+```bash
+blink add "SQLite Index Rebuild" \
+  --agent coding-agent \
+  --content "We rebuild old indexes now."
+```
+
+The poor note may be searchable, but it will not create graph links, backlinks or useful traversal paths.
+
 ## Read Policy
 
 Before answering a memory-dependent question, run:
 
 ```bash
-blink context "<question>" --vault ./vault --agent coding-agent
+blink context "<question>" --agent coding-agent
 ```
 
 Use the returned context as source-grounded memory.
@@ -139,7 +186,7 @@ Use the returned context as source-grounded memory.
 For machine-readable output, use:
 
 ```bash
-blink context "<question>" --vault ./vault --agent coding-agent --json
+blink context "<question>" --agent coding-agent --json
 ```
 
 If the context is empty or weak:
@@ -158,20 +205,18 @@ These examples assume the agent can run shell commands in the user workspace.
 Run this at the start of a task:
 
 ```bash
-export BLINK_VAULT=".brainlink-vault"
 export BLINK_AGENT="codex"
-blink init "$BLINK_VAULT"
-blink context "$USER_TASK" --vault "$BLINK_VAULT" --agent "$BLINK_AGENT" --mode hybrid --json
+blink init
+blink context "$USER_TASK" --agent "$BLINK_AGENT" --mode hybrid --json
 ```
 
 After discovering durable project knowledge:
 
 ```bash
 blink add "Implementation Boundary" \
-  --vault "$BLINK_VAULT" \
   --agent "$BLINK_AGENT" \
   --content "Keep use cases in application and pure transformations in domain. [[Architecture]] #architecture #typescript"
-blink index --vault "$BLINK_VAULT"
+blink index
 ```
 
 ### Claude Code-Style Agent
@@ -224,16 +269,19 @@ blink index --vault .brainlink-vault
 ### Initialize A Vault
 
 ```bash
+blink init
 blink init ./vault
 ```
 
 Creates:
 
 ```txt
-vault/
+$HOME/.brainlink/vault/
   .brainlink/
 ```
 
+`blink init ./vault` creates a custom vault instead.
+
 ### Add A Note
 
 ```bash
@@ -344,11 +392,14 @@ shared: 30 documents
 ### Start Graph UI
 
 ```bash
+blink server --host 127.0.0.1 --port 4321
 blink server --vault ./vault --host 127.0.0.1 --port 4321
 ```
 
 This starts a local frontend for inspecting the knowledge graph.
 
+Without `--vault`, the graph UI serves `$HOME/.brainlink/vault`.
+
 The frontend includes an agent selector. Selecting an agent calls the same read APIs with `agent=<agent-id>` and renders that namespace instead of merging every agent into one graph.
 
 The command reindexes by default, then serves:
@@ -380,19 +431,38 @@ blink watch --vault ./vault
 
 This process watches Markdown files and rebuilds the index after changes.
 
-### Use From An External MCP Server
+### Use From MCP
 
-Brainlink does not ship an MCP server. An MCP server can use Brainlink by executing the CLI and parsing `--json`.
+Brainlink ships a stdio MCP server:
 
-Recommended wrapper mapping:
+```bash
+brainlink-mcp
+```
+
+Example MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "brainlink": {
+      "command": "brainlink-mcp"
+    }
+  }
+}
+```
+
+Available MCP tools:
 
-- `brainlink_context`: run `blink context "<query>" --vault <vault> --agent <agent> --mode hybrid --json`.
-- `brainlink_search`: run `blink search "<query>" --vault <vault> --agent <agent> --mode hybrid --json`.
-- `brainlink_add_note`: run `blink add "<title>" --vault <vault> --agent <agent> --content "<content>" --json`, then `blink index`.
-- `brainlink_graph`: run `blink graph --vault <vault> --agent <agent> --json`.
-- `brainlink_validate`: run `blink validate --vault <vault> --agent <agent> --json`.
+- `brainlink_context`
+- `brainlink_search`
+- `brainlink_add_note`
+- `brainlink_index`
+- `brainlink_validate`
+- `brainlink_graph`
+- `brainlink_broken_links`
+- `brainlink_orphans`
 
-External wrappers should set `BRAINLINK_ALLOWED_VAULTS` before invoking the CLI:
+MCP clients can pass `vault` and `agent` arguments per tool call. Set `BRAINLINK_ALLOWED_VAULTS` when exposing Brainlink to an external agent process so a tool cannot pass arbitrary vault paths:
 
 ```bash
 export BRAINLINK_ALLOWED_VAULTS="/absolute/path/to/project-vault"
@@ -437,6 +507,12 @@ Output:
 
 Agents should include source paths in their reasoning or final answer when the user needs traceability.
 
+Non-goals:
+
+- `context` must not be treated as a write operation.
+- Retrieved context must not be assumed to create graph edges.
+- Backlinks are derived only from indexed `[[wiki links]]`.
+
 ## Operational Rules
 
 - Re-run `index` after modifying notes.
@@ -445,6 +521,8 @@ Agents should include source paths in their reasoning or final answer when the u
 - Do not manually edit the database.
 - Keep generated context short enough for the target model.
 - Prefer specific queries over broad queries.
+- Write explicit `[[wiki links]]` when durable memory should be connected.
+- Check `orphans` before assuming the graph is healthy.
 
 ## Failure Modes
 
@@ -472,6 +550,6 @@ Weak retrieval usually means:
 
 - Search supports FTS, local semantic embeddings, SQLite semantic buckets and hybrid ranking.
 - Local embeddings are deterministic and provider-free; remote embedding providers are not implemented yet.
-- MCP integration is external: wrap the CLI from your own MCP server.
+- MCP integration is available through the `brainlink-mcp` stdio server.
 - HTTP API is local and unauthenticated.
 - Watch mode depends on platform filesystem watcher behavior.

package/docs/ARCHITECTURE.md

@@ -167,20 +167,18 @@ HTTP request
 
 The HTTP API is local-first and unauthenticated. It is meant for local agents, browser UI, and development workflows.
 
-## External MCP Flow
+## MCP Flow
 
-Brainlink does not contain an MCP server. MCP compatibility is achieved by an external MCP server wrapping the CLI.
+Brainlink includes a stdio MCP server for agent integrations.
 
 ```txt
 MCP client
-  -> external MCP server
-  -> child_process execFile("blink", ["context", ..., "--json"])
-  -> Brainlink CLI
+  -> brainlink-mcp
   -> application use case
-  -> JSON stdout
+  -> MCP tool result
 ```
 
-This keeps the package CLI-first and avoids coupling the core project to one MCP SDK.
+The MCP adapter stays thin. It validates tool inputs, resolves the configured vault and calls the same application use cases used by the CLI.
 
 ## Link Resolution
 

package/docs/RELEASE.md

@@ -32,19 +32,34 @@ blink context "release smoke" --vault ./tmp-vault --mode hybrid --json
 blink server --vault ./tmp-vault --host 127.0.0.1 --port 4321
 ```
 
-9. Verify the server refuses accidental public binds:
+9. Verify the server refuses public binds:
 
 ```bash
 blink server --vault ./tmp-vault --host 0.0.0.0
 ```
 
 10. Confirm no test/demo vault files are included in the package tarball.
-11. Create the git tag only after the package name is final.
-12. Publish only from a logged-in npm account with permission for the package name.
+11. Confirm the repository has an `NPM_TOKEN` secret with publish permission for `@andespindola/brainlink`.
+12. Create the git tag only after the package name is final.
+13. Publish from GitHub Actions by publishing a GitHub Release for the tag.
 
 ## Publish Commands
 
-For scoped public packages:
+The preferred path is the `Publish npm` GitHub Actions workflow:
+
+- Push to `main`: runs checks, pack smoke, then publishes the package to npm with `latest` when `package.json` contains a version that is not already published.
+- GitHub Release `published`: runs checks, pack smoke, then publishes to npm with provenance.
+- Manual `workflow_dispatch`: runs a dry run by default. Disable `dry_run` only for an intentional manual publish.
+- Manual `workflow_dispatch` accepts an optional `dist_tag` override. Use `latest` only when the default npm install command should resolve to that version.
+- Prerelease versions publish under their prerelease dist-tag, for example `0.1.0-alpha.1` publishes with `--tag alpha`.
+
+On `main`, the publish job checks npm before publishing. If the version already exists, it automatically bumps the package inside the runner to the next available version before checks, packing and publishing. For example, `0.1.0-alpha.4` becomes `0.1.0-alpha.5`.
+
+The automatic bump is intentionally not pushed back to `main`. The branch stays protected, and npm remains the source of truth for the latest published package version.
+
+Manual and GitHub Release publishes do not auto-bump. If their version already exists, they skip `npm publish` because npm versions are immutable.
+
+For emergency local publishing of scoped public packages:
 
 ```bash
 npm publish --access public

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/brainlink",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.10",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",
@@ -25,10 +25,12 @@
   ],
   "bin": {
     "brainlink": "dist/cli/main.js",
-    "blink": "dist/cli/main.js"
+    "blink": "dist/cli/main.js",
+    "brainlink-mcp": "dist/mcp/main.js"
   },
   "files": [
     "dist",
+    "assets",
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
@@ -44,6 +46,7 @@
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "build": "npm run clean && tsc -p tsconfig.json",
     "dev": "tsx src/cli/main.ts",
+    "dev:mcp": "tsx src/mcp/main.ts",
     "test": "vitest run --config vitest.config.ts",
     "check": "npm run build && npm run test",
     "benchmark:large": "tsx src/benchmarks/large-vault.ts",
@@ -51,8 +54,10 @@
     "pack:smoke": "npm pack --dry-run"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "better-sqlite3": "^12.9.0",
-    "commander": "^14.0.2"
+    "commander": "^14.0.2",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",