@andespindola/brainlink 0.1.0-beta.0 → 0.1.0-beta.2

package/README.md

@@ -191,7 +191,9 @@ blink add "Testing Policy" \
   --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.
+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.
+
+Writes with `blink add` reindex the vault automatically by default. This can be disabled with `--no-auto-index` and controlled globally with `autoIndexOnWrite` in `brainlink.config.json`.
 
 When adding memory, follow this contract:
 
@@ -200,11 +202,7 @@ When adding memory, follow this contract:
 - 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
-```
+If you disable auto-index, run `blink index` after batched writes.
 
 ### 6. Validate Memory Health
 
@@ -223,7 +221,7 @@ Use this loop during real work:
 3. Use returned sources as project memory.
 4. Perform the task.
 5. Save only durable learnings with `blink add`, including `[[wiki links]]` to related notes.
-6. Run `blink index`.
+6. Run `blink index` only when auto-index was disabled during a batch.
 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.
@@ -241,8 +239,6 @@ blink add "Auth Decision" \
   --vault ./vault \
   --content "We chose JWT for API clients. [[Architecture]] #auth #jwt"
 
-blink index --vault ./vault
-
 blink search "jwt auth" --vault ./vault
 
 blink context "how does auth work?" --vault ./vault
@@ -384,18 +380,114 @@ Example MCP client configuration:
 }
 ```
 
+For a locked-down setup, allowlist the vaults that MCP clients may access:
+
+```json
+{
+  "mcpServers": {
+    "brainlink": {
+      "command": "brainlink-mcp",
+      "env": {
+        "BRAINLINK_ALLOWED_VAULTS": "/absolute/path/to/project-vault,/absolute/path/to/team-vault"
+      }
+    }
+  }
+}
+```
+
+### Install In MCP Client Stores
+
+Brainlink can be exposed to MCP-compatible client stores in two ways:
+
+1. Register the stdio server directly when the client accepts `mcpServers` configuration.
+2. Register the local plugin from this repository when the client supports a plugin gallery or local marketplace.
+
+Direct MCP server setup:
+
+```bash
+npm install -g @andespindola/brainlink@latest
+command -v brainlink-mcp
+```
+
+Use this server configuration in any MCP-compatible client that reads a JSON MCP manifest:
+
+```json
+{
+  "mcpServers": {
+    "brainlink": {
+      "command": "brainlink-mcp"
+    }
+  }
+}
+```
+
+Local plugin gallery setup:
+
+```bash
+npm install -g @andespindola/brainlink@latest
+git clone https://github.com/andersonflima/brainlink.git "$HOME/brainlink"
+mkdir -p "$HOME/plugins"
+ln -s "$HOME/brainlink/plugins/brainlink" "$HOME/plugins/brainlink"
+```
+
+Then register the plugin in the local marketplace file used by compatible clients:
+
+```bash
+node <<'NODE'
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+
+const marketplacePath = path.join(os.homedir(), '.agents', 'plugins', 'marketplace.json')
+const pluginEntry = {
+  name: 'brainlink',
+  source: {
+    source: 'local',
+    path: './plugins/brainlink'
+  },
+  policy: {
+    installation: 'AVAILABLE',
+    authentication: 'ON_INSTALL'
+  },
+  category: 'Productivity'
+}
+
+fs.mkdirSync(path.dirname(marketplacePath), { recursive: true })
+
+const marketplace = fs.existsSync(marketplacePath)
+  ? JSON.parse(fs.readFileSync(marketplacePath, 'utf8'))
+  : {
+      name: 'local',
+      interface: {
+        displayName: 'Local'
+      },
+      plugins: []
+    }
+
+const plugins = Array.isArray(marketplace.plugins) ? marketplace.plugins : []
+marketplace.plugins = [...plugins.filter((plugin) => plugin?.name !== 'brainlink'), pluginEntry]
+
+fs.writeFileSync(marketplacePath, `${JSON.stringify(marketplace, null, 2)}\n`)
+NODE
+```
+
+Restart the client after changing marketplace or MCP configuration so it reloads the Brainlink entry. The plugin starts `brainlink-mcp` and exposes the same tool set listed below.
+
 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_add_file`: ingest a local file as a note and reindex.
 - `brainlink_index`: rebuild the vault index.
+- `brainlink_stats`: read indexed vault statistics.
 - `brainlink_validate`: validate broken links and orphan notes.
+- `brainlink_sync`: run index, stats, validation, broken-link and orphan checks in one call.
 - `brainlink_graph`: read indexed graph nodes and weighted links.
 - `brainlink_broken_links`: list unresolved wiki links.
 - `brainlink_orphans`: list disconnected notes.
 
-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.
+The same linking rule applies through MCP: `brainlink_context` is read-only, and real graph links require Markdown notes with explicit `[[wiki links]]`. `brainlink_add_note` and `brainlink_add_file` reindex by default and include the index result when enabled.
 
 Agents can raise the importance of a relationship by putting priority markers on the same line as a wiki link:
 
@@ -478,8 +570,12 @@ Initializes vault metadata. Without an argument, Brainlink initializes the defau
 ```bash
 blink add "Note Title" --agent coding-agent --content "Markdown content"
 blink add "Note Title" --vault ./vault --agent coding-agent --content "Markdown content"
+blink add "Note Title" --vault ./vault --content-file ./notes.md
+blink add "Note Title" --vault ./vault --content-file ./notes.md --no-auto-index
 ```
 
+`--content` and `--content-file` are mutually exclusive. Add `--no-auto-index` when you want to defer reindexing.
+
 Creates a Markdown note under `agents/<agent-id>/`. Common secret patterns are blocked by default; use `--allow-sensitive` only for an intentionally protected vault.
 
 ### `index`
@@ -638,15 +734,18 @@ Brainlink reads `brainlink.config.json` or `.brainlink.json` from the current wo
   "port": 4321,
   "allowedVaults": [".brainlink-vault"],
   "defaultAgent": "shared",
+  "autoIndexOnWrite": true,
   "defaultSearchLimit": 10,
   "defaultContextTokens": 2000,
   "embeddingProvider": "local",
   "defaultSearchMode": "hybrid",
   "chunkSize": 1200
 }
+```
 
 `defaultAgent` is optional. When set, CLI and MCP calls that omit `--agent`/`agent` use this value automatically. If not set, behavior remains as before.
-```
+
+`autoIndexOnWrite` is optional and defaults to `true`. Set it to `false` to defer indexing after writes.
 
 Use `"embeddingProvider": "none"` when you want FTS-only indexing.
 
@@ -759,17 +858,18 @@ Detailed notes:
 - HTTP API is local and unauthenticated.
 - Watch mode depends on the platform filesystem watcher.
 
-## Alpha Scope
+## Beta Scope
 
-`0.1.0-alpha.0` is intended to prove the local-first memory loop:
+`0.1.0-beta.0` is intended to stabilize the local-first memory loop:
 
 - Markdown as durable memory.
 - SQLite FTS plus local embeddings and semantic buckets as rebuildable retrieval index.
 - CLI as the primary agent interface.
 - HTTP graph API and frontend as inspection tools.
 - Agent namespaces to avoid context mixing.
+- MCP tools for context retrieval, durable memory writes and graph maintenance.
 
-The alpha includes local semantic retrieval. Remote embedding providers, remote auth, advanced deduplication and graph editing are future milestones.
+The beta includes local semantic retrieval. Remote embedding providers, remote auth, advanced deduplication and graph editing are future milestones.
 
 ## Security
 

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

@@ -1,3 +1,4 @@
+import { readFileSync } from 'node:fs';
 import { addNote } from '../../application/add-note.js';
 import { indexVault } from '../../application/index-vault.js';
 import { startServer } from '../../application/start-server.js';
@@ -6,6 +7,15 @@ import { doctorVault } from '../../application/analyze-vault.js';
 import { loadBrainlinkConfig } from '../../infrastructure/config.js';
 import { assertVaultAllowed, ensureVault } from '../../infrastructure/file-system-vault.js';
 import { parsePositiveInteger, print, resolveOptions } from '../runtime.js';
+const resolveAddContent = (options) => {
+    if (options.content != null && options.content.trim().length > 0) {
+        return options.content;
+    }
+    if (options.contentFile == null || options.contentFile.trim().length === 0) {
+        throw new Error('Use --content or --content-file to provide note content.');
+    }
+    return readFileSync(options.contentFile, 'utf8');
+};
 export const registerWriteCommands = (program) => {
     program
         .command('init')
@@ -20,18 +30,23 @@ export const registerWriteCommands = (program) => {
     program
         .command('add')
         .argument('<title>', 'note title')
-        .requiredOption('-c, --content <content>', 'markdown content')
+        .option('-c, --content <content>', 'markdown content')
+        .option('-f, --content-file <contentFile>', 'read markdown content from a file')
         .option('-v, --vault <vault>', 'vault directory')
         .option('-a, --agent <agent>', 'agent memory namespace')
         .option('--allow-sensitive', 'allow writing content that looks like a secret')
+        .option('--no-auto-index', 'skip reindexing after add')
         .option('--json', 'print machine-readable JSON')
         .description('add a markdown note to the vault')
         .action(async (title, options) => {
         const resolved = await resolveOptions(options);
-        const path = await addNote(resolved.vault, title, options.content, resolved.agent, {
+        const content = resolveAddContent(options);
+        const notePath = await addNote(resolved.vault, title, content, resolved.agent, {
             allowSensitive: Boolean(options.allowSensitive)
         });
-        print(options.json, { title, agent: resolved.agent ?? 'shared', path }, () => `Created note at ${path}`);
+        const shouldAutoIndex = options.autoIndex !== false && resolved.config.autoIndexOnWrite;
+        const index = shouldAutoIndex ? await indexVault(resolved.vault) : undefined;
+        print(options.json, { title, agent: resolved.agent ?? 'shared', path: notePath, ...(index ? { index } : {}) }, () => `Created note at ${notePath}`);
     });
     program
         .command('index')

package/dist/infrastructure/config.js

@@ -8,6 +8,7 @@ export const defaultBrainlinkConfig = {
     port: 4321,
     allowedVaults: [],
     defaultAgent: undefined,
+    autoIndexOnWrite: true,
     defaultSearchLimit: 10,
     defaultContextTokens: 2000,
     embeddingProvider: 'local',
@@ -45,6 +46,7 @@ const sanitizeConfig = (value) => ({
     defaultAgent: typeof value.defaultAgent === 'string' && value.defaultAgent.trim().length > 0
         ? sanitizeAgentId(value.defaultAgent)
         : defaultBrainlinkConfig.defaultAgent,
+    autoIndexOnWrite: typeof value.autoIndexOnWrite === 'boolean' ? value.autoIndexOnWrite : defaultBrainlinkConfig.autoIndexOnWrite,
     defaultSearchLimit: typeof value.defaultSearchLimit === 'number' && value.defaultSearchLimit > 0
         ? value.defaultSearchLimit
         : defaultBrainlinkConfig.defaultSearchLimit,

package/dist/mcp/server.js

@@ -2,7 +2,7 @@ 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, statsInputSchema, statsTool, syncInputSchema, syncTool, validateInputSchema, validateTool } from './tools.js';
+import { addNoteInputSchema, addFileInputSchema, addFileTool, addNoteTool, brokenLinksInputSchema, brokenLinksTool, contextInputSchema, contextTool, graphInputSchema, graphTool, indexInputSchema, indexTool, orphansInputSchema, orphansTool, searchInputSchema, searchTool, statsInputSchema, statsTool, syncInputSchema, syncTool, validateInputSchema, validateTool } from './tools.js';
 const readPackageVersion = () => {
     const packagePath = join(dirname(fileURLToPath(import.meta.url)), '../../package.json');
     const metadata = JSON.parse(readFileSync(packagePath, 'utf8'));
@@ -30,6 +30,11 @@ export const createBrainlinkMcpServer = () => {
         description: 'Write durable Markdown memory, then reindex the vault. Include explicit [[wiki links]] for connected graph memory. Add priority markers near links, such as priority: high, #important or #critical, when a relationship should be weighted higher.',
         inputSchema: addNoteInputSchema
     }, addNoteTool);
+    server.registerTool('brainlink_add_file', {
+        title: 'Ingest Markdown File',
+        description: 'Read a local markdown/text file and ingest it as a Brainlink note. Reindex defaults to true.',
+        inputSchema: addFileInputSchema
+    }, addFileTool);
     server.registerTool('brainlink_index', {
         title: 'Index Brainlink Vault',
         description: 'Rebuild the local Brainlink index from Markdown notes.',

package/dist/mcp/tools.js

@@ -1,3 +1,5 @@
+import { readFile } from 'node:fs/promises';
+import { basename, extname } from 'node:path';
 import { z } from 'zod';
 import { getBrokenLinksReport, getOrphansReport, getStats, validateVault } from '../application/analyze-vault.js';
 import { addNote } from '../application/add-note.js';
@@ -32,11 +34,21 @@ const resolveExecutionContext = async (input) => {
     const vault = await assertVaultAllowed(input.vault ?? config.vault, config.allowedVaults);
     const agent = input.agent ?? config.defaultAgent;
     return {
-        vault,
         config,
+        vault,
         agent
     };
 };
+const inferTitleFromPath = (filePath) => {
+    const extension = extname(filePath);
+    const fromFileName = basename(filePath, extension);
+    return fromFileName
+        .trim()
+        .replace(/[-_]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+};
+const isTruthy = (value) => value !== false;
 const jsonResult = (value) => ({
     content: [
         {
@@ -68,7 +80,16 @@ export const addNoteInputSchema = {
         .string()
         .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.'),
-    agent: z.string().min(1).optional().describe('Agent memory namespace.'),
+    ...agentInput,
+    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.')
+};
+export const addFileInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    title: z.string().min(1).optional().describe('Optional note title override. If omitted, uses file name.'),
+    filePath: z.string().min(1).describe('Filesystem path to markdown or text file to ingest.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex vault after ingesting file.'),
     allowSensitive: z.boolean().optional().default(false).describe('Allow content that looks like a secret.')
 };
 export const indexInputSchema = {
@@ -128,16 +149,39 @@ export const searchTool = async (input) => {
 };
 export const addNoteTool = async (input) => {
     const context = await resolveExecutionContext(input);
+    const shouldIndex = isTruthy(input.autoIndex);
     const path = await addNote(context.vault, input.title, input.content, context.agent, {
         allowSensitive: input.allowSensitive
     });
-    const index = await indexVault(context.vault);
+    const index = shouldIndex ? await indexVault(context.vault) : undefined;
     return jsonResult({
         vault: context.vault,
         title: input.title,
         agent: context.agent,
         path,
-        index
+        ...(index ? { index } : {})
+    });
+};
+export const addFileTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const content = await readFile(input.filePath, 'utf8');
+    const inferredTitle = inferTitleFromPath(input.filePath);
+    const title = input.title ?? inferredTitle;
+    if (title == null || title.length === 0) {
+        throw new Error('Cannot infer note title from file path. Provide a title explicitly.');
+    }
+    const shouldIndex = isTruthy(input.autoIndex);
+    const path = await addNote(context.vault, title, content, context.agent, {
+        allowSensitive: input.allowSensitive
+    });
+    const index = shouldIndex ? await indexVault(context.vault) : undefined;
+    return jsonResult({
+        vault: context.vault,
+        title,
+        agent: context.agent,
+        filePath: input.filePath,
+        path,
+        ...(index ? { index } : {})
     });
 };
 export const indexTool = async (input) => {

package/docs/AGENT_USAGE.md

@@ -43,6 +43,8 @@ Use `--vault <path>` for a one-off custom vault, or set `vault` in `brainlink.co
 
 You can also set `defaultAgent` in `brainlink.config.json` / `.brainlink.json` (for example `"defaultAgent": "coding-agent"`). When set, CLI commands and MCP calls reuse it when `--agent`/`agent` is not passed.
 
+`autoIndexOnWrite` (default: `true`) controls whether `add` and MCP write tools index right after writing.
+
 ## Agent Namespaces
 
 Each agent writes into a dedicated namespace under `agents/<agent-id>/`:
@@ -162,7 +164,7 @@ Required write behavior:
 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.
+5. `add` writes are indexed by default. Only batch with explicit `--no-auto-index`, then run `index` once.
 6. Run `validate`, `broken-links` or `orphans` when the graph should be connected.
 
 Good linked note:
@@ -171,7 +173,6 @@ Good linked note:
 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
 ```
 
@@ -247,7 +248,7 @@ When using MCP, use this compact sequence for the same memory discipline:
 1. Bootstrap context:
    - `brainlink_context` with `agent`, `query`, `mode: hybrid`, `limit`.
 2. Capture durable decisions:
-   - `brainlink_add_note` with explicit `[[wiki links]]` and `#tags`.
+   - `brainlink_add_note` or `brainlink_add_file` with explicit `[[wiki links]]` and `#tags`.
 3. Run maintenance before handoff or before the next step:
    - `brainlink_sync` with `agent`, `contextQuery`, `mode: hybrid`.
 4. Diagnose graph issues only when needed:
@@ -346,8 +347,12 @@ $HOME/.brainlink/vault/
 
 ```bash
 blink add "Note Title" --vault ./vault --content "Markdown content"
+blink add "Note Title" --vault ./vault --content-file ./notes.md
+blink add "Note Title" --vault ./vault --content-file ./notes.md --no-auto-index
 ```
 
+`--content` and `--content-file` are mutually exclusive. Use `--no-auto-index` if you want to defer indexing in batch operations.
+
 This creates a slugged Markdown file with frontmatter and a heading.
 
 The CLI blocks common secret patterns by default. Do not use `--allow-sensitive` unless the vault is intentionally protected.
@@ -516,8 +521,11 @@ Available MCP tools:
 - `brainlink_context`
 - `brainlink_search`
 - `brainlink_add_note`
+- `brainlink_add_file`
 - `brainlink_index`
+- `brainlink_stats`
 - `brainlink_validate`
+- `brainlink_sync`
 - `brainlink_graph`
 - `brainlink_broken_links`
 - `brainlink_orphans`

package/package.json

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