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

package/AGENTS.md

@@ -20,6 +20,8 @@ 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:

package/README.md

@@ -110,26 +110,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 +153,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 +161,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,7 +173,6 @@ 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"
 ```
@@ -176,15 +180,15 @@ blink add "Testing Policy" \
 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,7 +196,7 @@ 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`.
@@ -229,6 +233,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
@@ -314,9 +320,9 @@ An MCP server can use Brainlink by spawning `blink` or `brainlink` as a subproce
 Minimum integration contract:
 
 ```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"
+blink context "<task>" --agent "$BLINK_AGENT" --json
+blink add "Decision Title" --agent "$BLINK_AGENT" --content "Durable memory. #decision"
+blink index
 ```
 
 Example Node.js wrapper inside an external MCP server:
@@ -357,9 +363,11 @@ Recommended MCP tools exposed by the external server:
 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
@@ -411,14 +419,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 +437,7 @@ Creates a Markdown note under `agents/<agent-id>/`. Common secret patterns are b
 ### `index`
 
 ```bash
+blink index
 blink index --vault ./vault
 ```
 
@@ -546,6 +557,7 @@ Watches Markdown files and rebuilds the index when notes change.
 ### `server`
 
 ```bash
+blink server --watch
 blink server --vault ./vault --watch
 ```
 
@@ -569,7 +581,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
 {

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,7 +84,7 @@ 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')

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/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>/`:
@@ -131,7 +143,7 @@ Rules:
 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 +151,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 +170,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 +234,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 +357,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:

package/docs/RELEASE.md

@@ -39,12 +39,19 @@ 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:
+
+- 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.
+- Prerelease versions publish under their prerelease dist-tag, for example `0.1.0-alpha.1` publishes with `--tag alpha`.
+
+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.2",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",