@andespindola/brainlink 0.1.0-beta.99 → 1.0.0

package/AGENTS.md

@@ -6,7 +6,7 @@ This file tells coding agents and AI assistants how to use this repository.
 
 Brainlink is a local-first knowledge memory for agents.
 
-It reads a Markdown vault, extracts `[[wiki links]]` and `#tags`, builds a local file index at `.brainlink/index.json`, and returns compact context packages that agents can inject into prompts.
+It reads a Markdown vault, extracts concise graph links from `## Context Links`, extracts `#tags`, builds a local file index at `.brainlink/index.json`, and returns compact context packages that agents can inject into prompts.
 
 ## Source Of Truth
 
@@ -27,15 +27,15 @@ By default, the installed Brainlink CLI uses `$HOME/.brainlink/vault` as its vau
 Use this loop when using Brainlink as memory:
 
 1. Write durable knowledge into Markdown notes.
-2. Link related notes with explicit `[[Note Title]]` wiki links inside the note body.
+2. Link related notes with explicit `[[Note Title]]` wiki links inside a `## Context Links` section.
 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.
+`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]]` inside `## Context Links` 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.
+When an agent adds durable memory, it should add only the canonical relationships to `## Context Links`. Prefer exact note titles in links, for example `[[Architecture]]`, and run `broken-links`, `orphans` or `validate` when graph health matters.
 
 Agents can mark important relationships by placing priority hints on the same line as a wiki link, for example `[[Architecture]] priority: high`, `[[Incident Runbook]] #important` or `[[Incident Runbook]] #critical`. Indexed graph edges expose `weight` and `priority` so agents can sort related notes by importance.
 
@@ -78,10 +78,10 @@ http://127.0.0.1:4321/
 http://127.0.0.1:4321/api/graph
 ```
 
-Use watch mode while editing notes:
+The graph server watches Markdown files by default while editing notes:
 
 ```bash
-npm run dev -- server --vault ./vault --watch
+npm run dev -- server --vault ./vault
 npm run dev -- watch --vault ./vault
 npm run dev -- bench --vault ./vault
 npm run dev -- bench --vault ./vault --watch

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.0.0
+
+- Promoted Brainlink to the first stable functional release.
+- Stabilized the local-first Markdown vault model with rebuildable indexes, graph links, tags, search packs and context packages.
+- Stabilized the CLI memory workflow for init, add, index, search, context, graph inspection, validation, migration and vault management.
+- Stabilized MCP tooling for bootstrap, policy, recommendations, RAG/CAG context, durable writes, volatile memory, graph reads and vault health checks.
+- Added remote MCP server mode for centralized cluster access over Streamable HTTP with health/readiness probes and optional bearer authentication.
+- Added dedicated `vaults` commands to list known vaults, choose the default vault and safely delete local filesystem vaults.
+- Improved graph UI stability, dark theme behavior, large-graph rendering, node interaction and graph node visibility.
+- Kept compatibility with the `0.1.0-beta` vault and index model; derived artifacts remain rebuildable from Markdown source.
+
 ## 0.1.0-beta.4
 
 - Added bootstrap session-state persistence in `$BRAINLINK_HOME/session-state.json` for vault/agent readiness tracking.
@@ -14,6 +25,9 @@
 - Added default MCP startup bootstrap behavior controlled by `brainlink_policy.autoBootstrapOnStartup`.
 - Added CLI MCP policy presets through `blink agent policy --preset fully-auto|strict`.
 - Added write-time non-orphan enforcement by auto-linking notes without wiki edges to agent hub notes.
+- Changed graph indexing to keep every non-self Markdown wiki link as a weighted graph edge so the default star graph represents complete note connectivity.
+- Added `blink index --full` and MCP `brainlink_index` `full=true` for complete source reindexing without clearing the existing index first.
+- Improved index migration so stale graph link model metadata automatically triggers a complete source reindex.
 - Added MCP `brainlink_policy` presets (`fully-auto`, `strict`) for one-call policy switching.
 - Added MCP write connectivity metadata in `brainlink_add_note`/`brainlink_add_file` responses.
 - Added MCP `brainlink_recommendations` tool for plug-and-play workflow guidance.

package/README.md

@@ -71,6 +71,8 @@ Legacy `.jsonl.gz` packs are upgraded to `.blpk` automatically on first search/c
 - Full-text, semantic and hybrid retrieval on a local file index.
 - Middle-out context assembly around the strongest chunk per document.
 - In-process index and context caching with automatic invalidation on index updates.
+- Optional CAG context packs at `.brainlink/context-packs/*.json`, derived from the current index signature and reusable across repeated context calls.
+- HTTP graph server caches generated frontend assets and graph-layout JSON payloads by signature, and skips layout serialization when ETag returns `304`.
 - Compressed-space prefiltering for `.blpk` packs before decryption and scan.
 - Incremental indexing that reprocesses only changed markdown files and reuses existing chunks/embeddings for unchanged notes.
 - Adaptive compressed-pack rebuild policy to keep indexing fast during small edit batches.
@@ -81,17 +83,17 @@ Legacy `.jsonl.gz` packs are upgraded to `.blpk` automatically on first search/c
 - Built-in MCP stdio server for agent tool integration.
 - Local HTTP API.
 - Realtime graph UI with agent selector and colored knowledge groups.
-- Graph renderer optimized for large datasets with viewport-driven node culling and edge lookup by visible nodes.
-- Canvas graph rendering uses the same batched node and edge pipeline for every graph size, reducing per-frame draw calls while keeping selected and hovered items highlighted.
-- WebGL acceleration is used when available for dense node and edge drawing, with Canvas 2D preserved as the interaction and fallback layer.
-- Graph zoom-out renders hierarchical ecosystem subgraphs only above 1000 notes: the memory hub stays centered, 1000-note groups stay as compact sand-like points, and focused groups gradually expand into smaller graph meshes before individual notes are rendered.
+- Graph renderer uses a cauliflower-style hub layout: the primary hub stays centered, segment hubs anchor surrounding lobes, and visual edges are simplified to root hub -> segment hubs -> local context nodes.
+- Real weighted `[[wiki link]]` edges stay preserved in the indexed graph APIs for backlinks, ranking and context traversal; the browser layout uses a separate visual edge layer for readability.
+- Graph exploration uses stable chunk streaming (`/api/graph-stream`) with explicit node/edge budgets, returning the full mode-level scene while it fits the budget.
+- Render pipeline uses WebGL in a dedicated worker through `OffscreenCanvas`, keeping the main thread focused on UI controls and details panels.
 - Large graph layout API automatically uses compact payload encoding with link-coverage-aware edge selection to reduce initial client load without hiding major relationships.
 - Large-segment layout spacing now grows logarithmically to keep initial visual density consistent between medium and very large vaults (for example, ~1k vs ~50k notes).
-- Graph coordinates are visually compacted across graph sizes so reset starts from a stable macro mass and zoom-in progressively expands toward local detail.
-- Zoomed-out graph LOD renders nested subgraphs and progressively expands only the focused cluster as zoom increases, including very large vaults.
-- Graph reset starts in macro "galaxy" overview mode and progressively reveals nearby nodes as zoom increases, including smaller vaults.
+- Graph coordinates are visually compacted across graph sizes so reset starts from a stable fitted scene and zoom-in progressively reveals local detail.
+- Zoomed-out graph summarizes the scene as segment hub clusters, then progressively reveals individual nodes as the user zooms in.
+- Graph reset fits the full graph scene instead of starting in a separate macro overview mode.
 - Graph filtering runs in a dedicated browser worker to keep the UI thread responsive during heavy datasets.
-- Edge rendering budgets adapt to zoom level to prevent frame spikes on large graph panoramas.
+- Node titles are shown as the user zooms closer, while labels remain bounded to visible on-screen nodes in very large graphs.
 
 ## Install
 
@@ -209,19 +211,19 @@ Only store knowledge that is likely to matter later:
 ```bash
 blink add "Testing Policy" \
   --agent "$BLINK_AGENT" \
-  --content "Run npm run check before final delivery. Related: [[Release Checklist]]. #testing #process"
+  --content $'Run npm run check before final delivery. #testing #process\n\n## Context Links\n\n- [[Release Checklist]]'
 ```
 
-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.
+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 graph link, write a concise `## Context Links` section and put the canonical `[[Note Title]]` links there.
 
 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:
 
-- Link the new note to at least one existing note when there is a related concept.
+- Link the new note to existing notes through `## Context Links` 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.
+- General wiki-link mentions outside `## Context Links` remain searchable Markdown content, but they do not become graph edges.
 
 If you disable auto-index, run `blink index` after batched writes.
 
@@ -264,7 +266,7 @@ blink search "jwt auth" --vault ./vault
 
 blink context "how does auth work?" --vault ./vault
 
-blink server --vault ./vault --watch
+blink server --vault ./vault
 ```
 
 Open the graph UI:
@@ -528,18 +530,23 @@ Available tools:
 
 - `brainlink_bootstrap`: plug-and-play entrypoint that runs index + health checks and can return context in one call.
 - `brainlink_policy`: read or update bootstrap/context-first policy, including presets (`preset: "fully-auto" | "strict"`).
-- `brainlink_recommendations`: return an automatic action plan so agents can run Brainlink in the recommended order.
-- `brainlink_context`: read indexed context for a task or question.
+- `brainlink_recommendations`: return an automatic action plan so agents can run Brainlink in the recommended order, including RAG/CAG context strategy guidance.
+- `brainlink_context`: read indexed context for a task or question; pass `strategy: "rag"` for fresh retrieval assembly, `strategy: "cag"` for persisted context packs or `strategy: "auto"` for CAG hits with RAG fallback.
+- `brainlink_context_packs`: list or clear persisted CAG context packs.
 - `brainlink_search`: search indexed notes.
 - `brainlink_dedupe`: detect duplicate candidates using exact hash + semantic similarity scores.
 - `brainlink_resolve_duplicate`: resolve duplicate pairs (`merge`, `link`, `ignore`) with connectivity-safe fallback edges.
 - `brainlink_add_note`: write durable Markdown memory and reindex.
 - `brainlink_add_file`: ingest a local file as a note and reindex.
-- `brainlink_index`: rebuild the vault index.
+- `brainlink_canonicalize_context_links`: ensure existing notes link to inferred context hubs.
+- `brainlink_volatile_add`: write temporary agent-decided memory with TTL; volatile sections are included in context and never create durable graph edges.
+- `brainlink_volatile_clear`: clear temporary memory for the current vault/agent namespace.
+- `brainlink_index`: rebuild the vault index. Pass `full=true` for a complete source reindex.
 - `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_graph_contexts`: list the visual graph contexts used by the local server.
 - `brainlink_broken_links`: list unresolved wiki links.
 - `brainlink_orphans`: list disconnected notes.
 
@@ -550,8 +557,9 @@ By default, Brainlink enforces bootstrap and auto-runs it for read tools when se
 If you disable `autoBootstrapOnRead` through `brainlink_policy`, read tools return a preflight instruction with suggested `brainlink_bootstrap` arguments.
 `brainlink_bootstrap`, `brainlink_policy` and preflight responses include structured `nextActions` so MCP clients can continue automatically without custom parsing.
 For one-call planning, use `brainlink_recommendations` to get the recommended tool sequence for the current vault/agent/query.
+The MCP context tools are plug-and-play by default: omit `strategy` to use the configured default (`rag` unless changed), pass `strategy: "cag"` for repeated/stable task context, or pass `strategy: "auto"` so Brainlink chooses CAG on fresh pack hits and RAG otherwise. `brainlink_recommendations`, preflight responses and policy next actions include executable context arguments so clients can continue without custom parsing.
 
-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 index + `writeConnectivity` metadata. Brainlink guarantees at least one edge per new note by auto-linking when needed.
+The same linking rule applies through MCP: `brainlink_context` is read-only, and real graph links require Markdown notes with explicit `## Context Links` sections. `brainlink_add_note` and `brainlink_add_file` reindex by default and include index + `writeConnectivity` metadata. Brainlink does not auto-link new notes to fallback hubs.
 
 Agents can raise the importance of a relationship by putting priority markers on the same line as a wiki link:
 
@@ -560,17 +568,25 @@ Agents can raise the importance of a relationship by putting priority markers on
 Related: [[Incident Runbook]] #critical
 ```
 
-Indexed edges expose `weight` and `priority` (`low`, `normal`, `high`, `critical`) through CLI JSON, HTTP graph APIs and `brainlink_graph`.
+Indexed edges expose `weight` and `priority` (`low`, `normal`, `high`, `critical`) through CLI JSON, HTTP graph APIs and `brainlink_graph`. Brainlink indexes every non-self `[[wiki link]]` inside `## Context Links` as a graph edge. Old indexes are rebuilt automatically when their graph link model version is missing or stale.
+
+To migrate older vaults without deleting existing Markdown, generate concise context-link sections from current wiki-link mentions:
+
+```bash
+blink migrate-context-links --vault ./vault --limit 5
+blink index --vault ./vault --full
+```
 
 ## Graph UI
 
 Start the local frontend:
 
 ```bash
-blink server --host 127.0.0.1 --port 4321 --watch
+blink server --host 127.0.0.1 --port 4321
 ```
 
 By default, the server uses `$HOME/.brainlink/vault`. Pass `--vault ./vault` only when you want to inspect a custom vault.
+By default, the server watches Markdown files in local filesystem vaults and reindexes after note changes. Use `--no-watch` to disable realtime reindexing.
 By default, `blink server` tries to open the graph in a native desktop GUI window:
 - macOS: Swift + WebKit
 - Windows: PowerShell WinForms WebBrowser
@@ -586,23 +602,27 @@ When native GUI is used, the GUI window automatically closes when the `blink ser
 The graph UI shows:
 
 - notes as nodes
-- `[[wiki links]]` as weighted edges
-- details opened on node click (tags, outgoing links, backlinks, full Markdown content)
+- all non-self `[[wiki links]]` inside `## Context Links` as weighted indexed edges
+- default cauliflower-style visual layout centered on the primary hub, with segment hubs anchoring surrounding lobes and visual edges simplified to root hub -> segment hubs -> local context nodes
+- details opened in a non-modal side panel (tags, outgoing links, backlinks, full Markdown content), so zoom and pan remain available while inspecting data
 - neutral graph nodes with segment/group metadata
 - agent selector (id-only labels) for isolated views
+- context selector for segment-scoped cauliflower subgraphs derived from the visual graph context
 - graph filter matches title, path, tags and note content
 - graph filter keeps hub context nodes visible (`Memory Hub`/`MOC`/high-degree fallback) to preserve relationship readability
-- realtime refresh while `--watch` is enabled
+- realtime refresh while watch mode is enabled
 - graph controls for zoom in, zoom out, fit visible nodes and reset-to-fit-all
 - wheel zoom (including `cmd+scroll` and `ctrl+scroll`) anchored to cursor position for faster navigation in large graphs
+- wheel/button zoom updates immediately at the cursor anchor without delayed focus-transition interpolation
+- Bloom-like scene navigation: reset fits the current graph scene, wheel zoom stays anchored to the cursor, and worker-driven WebGL rendering keeps pan/zoom interaction responsive
+- zoom-out cluster mode that shows segment hub clusters first, then reveals local nodes as zoom increases
 - keyboard shortcuts: `+` zoom in, `-` zoom out, `0` reset fit
-- double-click on canvas zooms in at cursor position
+- click on a node opens its details panel; double-click on empty canvas zooms in at cursor position
 - floating graph totals (notes, links, tags) below the Brainlink title
-- graph rendering safeguards (batched canvas drawing across graph sizes, edge draw caps, lower redraw rate, zoom-aware interaction)
-- WebGL node and edge acceleration when supported, falling back to Canvas 2D without changing graph behavior
-- compact macro-to-micro density progression so reset keeps the graph mass oriented and zoom-in separates local neighborhoods progressively
-- graph camera treats hub-centered navigation as structural only when the hub is dominant; diffuse stress graphs reset and zoom around the full graph mass
-- graph LOD progression: graphs up to 1000 notes render directly; larger graphs use one recursive model where each visible level targets up to 999 non-hub nodes, starts from a memory-hub-centered mesh, and each supernode can expand into another same-shape subgraph level (again up to 999 children) with latent fade-in, aggregated real links and local sibling mesh links so org-heavy and stress-50k follow the same structure at different depths; for massive graphs the first expansion starts much deeper in zoom and low-size child levels use slower easing so the view stays as one compact graph longer
+- graph rendering safeguards (batched GPU draw calls, lower redraw rate, zoom-aware interaction)
+- adaptive CPU safeguards for large graphs: idle frame pacing, throttled background physics updates and cached viewport dimensions to reduce redraw/layout overhead while preserving interaction responsiveness
+- worker-first WebGL rendering with Canvas fallback when `OffscreenCanvas` or worker rendering is unavailable
+- large graph view keeps one indexed graph model across zoom levels, uses a stable visual hierarchy for rendering, uses segment clusters at high zoom-out, and shows node titles as zoom approaches readable scale
 
 The server indexes before starting by default. Use `--no-index` to skip that step:
 
@@ -619,8 +639,11 @@ The server always refuses non-loopback hosts. Brainlink HTTP only runs on localh
 Routes:
 
 - `GET /api/agents`
+- `GET /api/graph-contexts`
 - `GET /api/graph`
 - `GET /api/graph-layout`
+- `GET /api/graph-view?x=<x>&y=<y>&w=<width>&h=<height>&scale=<scale>`
+- `GET /api/graph-stream?x=<x>&y=<y>&w=<width>&h=<height>&scale=<scale>&nodeBudget=<n>&edgeBudget=<n>`
 - `GET /api/graph-node?id=<node-id>`
 - `GET /api/search?q=<query>&limit=10&mode=hybrid`
 - `GET /api/context?q=<query>&limit=12&tokens=2000&mode=hybrid`
@@ -635,6 +658,7 @@ Read routes accept `agent=<agent-id>`:
 
 ```txt
 /api/graph-layout?agent=coding-agent
+/api/graph-layout?agent=coding-agent&context=Architecture
 /api/search?q=typescript&agent=coding-agent&mode=hybrid
 /api/context?q=module-boundaries&agent=coding-agent&mode=semantic
 ```
@@ -689,9 +713,25 @@ blink config set-vault "s3://my-memory-bucket/brainlink" --global
 
 `config set-vault` writes configuration through CLI (no manual file edits required).  
 By default it writes local config (`./brainlink.config.json`), appends the vault to `allowedVaults`, and migrates Markdown memory from the current configured vault when the target is empty.  
+When the configured default vault is changed manually in config files, Brainlink also performs automatic migration on the next command that uses the configured vault (without explicit `--vault`).
 Use `--global` to write to `$BRAINLINK_HOME/brainlink.config.json`, `--no-migrate` to skip migration, and `--no-index` to skip post-migration indexing.
 `config doctor` is dry-run by default; use `--fix` to apply safe config normalization and allowlist fixes.
 
+### `vaults`
+
+```bash
+blink vaults list
+blink vaults list --json
+blink vaults use /absolute/path/to/vault
+blink vaults use /absolute/path/to/vault --global
+blink vaults delete /absolute/path/to/vault --yes
+blink vaults delete /absolute/path/to/vault --yes --prune-config
+```
+
+Lists known vaults from the configured default, `allowedVaults`, and the built-in default at `$HOME/.brainlink/vault`.
+`vaults use` chooses the default vault without migrating memory; use `migrate-vault` or `config set-vault --migrate-from` when you want to copy Markdown memory between vaults.
+`vaults delete` only deletes local filesystem vaults, requires `--yes`, refuses bucket vaults, and refuses deleting the current default vault. Choose another default first with `vaults use`.
+
 ### `migrate-vault`
 
 ```bash
@@ -768,9 +808,12 @@ When action is not `merge`, Brainlink still creates a low-priority related edge
 ```bash
 blink index
 blink index --vault ./vault
+blink index --vault ./vault --full
 ```
 
-Rebuilds the local index from Markdown files.
+Rebuilds the local index from Markdown files. By default, unchanged notes reuse existing indexed chunks for speed.
+Use `--full` to force a complete source reindex of every Markdown note. Full reindex builds the replacement index before persisting it, so existing context is not cleared first.
+Brainlink also performs this complete source reindex automatically when it detects that the stored graph link model is older than the current model.
 
 ### `bench`
 
@@ -839,10 +882,15 @@ Context selection uses a middle-out strategy: it starts from the strongest chunk
 blink context "question" --vault ./vault --limit 12 --tokens 2000
 blink context "question" --vault ./vault --agent coding-agent --json
 blink context "question" --vault ./vault --agent coding-agent --mode hybrid --json
+blink context "question" --vault ./vault --agent coding-agent --strategy cag --json
+blink context "question" --vault ./vault --agent coding-agent --strategy auto --json
+blink context-packs --vault ./vault --json
+blink context-packs --vault ./vault --stale --clear
 ```
 
 Builds a compact context package for an agent.
 Repeated calls with the same vault, agent, query, mode and token/limit settings are served from a short in-memory cache while the index is unchanged.
+The default strategy is configured by `defaultContextStrategy` and starts as `rag`, which retrieves and assembles context from the current index. `--strategy cag` enables cache-augmented context generation by reading or refreshing a persisted context pack under `.brainlink/context-packs`; `--strategy auto` uses CAG when a fresh pack exists and RAG otherwise, refreshing a pack for future calls. Context responses include `cache`, `metrics`, `requestedStrategy` and `recommendedStrategy` metadata. Packs are derived artifacts and become stale when the index or volatile memory signature changes.
 
 ### `links`
 
@@ -922,15 +970,26 @@ blink watch --vault ./vault
 
 Watches Markdown files and rebuilds the index when notes change.
 
+### `canonicalize-context-links`
+
+```bash
+blink canonicalize-context-links --vault ./vault --dry-run
+blink canonicalize-context-links --vault ./vault
+```
+
+Ensures existing notes have canonical `## Context Links` entries to inferred context hubs such as `User Preferences Hub`, `GitHub Repositories Hub` or `Brainlink Hub`. The command is idempotent, creates missing hub notes by default, and fully reindexes after writes unless `--no-index` is passed.
+
 ### `server`
 
 ```bash
-blink server --watch
-blink server --vault ./vault --watch
-blink server --vault ./vault --watch --no-open
+blink server
+blink server --vault ./vault
+blink server --vault ./vault --no-open
+blink server --vault ./vault --no-watch
 ```
 
 Starts the local read-only graph UI and HTTP API.
+Watch mode is enabled by default for Markdown changes in local filesystem vaults. Use `--no-watch` to run without the watcher.
 By default, it tries to open a native desktop GUI window for the graph URL.
 On Linux, native GUI is disabled by default; enable it with `BRAINLINK_LINUX_NATIVE_GUI=1`.
 If native GUI launch is unavailable, it falls back to dedicated app-window mode and then browser open.
@@ -971,8 +1030,10 @@ If no `vault` is configured and no `--vault` flag is passed, Brainlink uses `$HO
   "allowedVaults": [".brainlink-vault"],
   "defaultAgent": "shared",
   "autoIndexOnWrite": true,
+  "autoCanonicalContextLinks": true,
   "defaultSearchLimit": 10,
   "defaultContextTokens": 2000,
+  "defaultContextStrategy": "rag",
   "embeddingProvider": "local",
   "defaultSearchMode": "hybrid",
   "chunkSize": 1200,
@@ -987,7 +1048,8 @@ If no `vault` is configured and no `--vault` flag is passed, Brainlink uses `$HO
     "coding-agent": {
       "defaultSearchMode": "semantic",
       "defaultSearchLimit": 8,
-      "defaultContextTokens": 2400
+      "defaultContextTokens": 2400,
+      "defaultContextStrategy": "auto"
     },
     "*": {
       "defaultSearchMode": "hybrid"
@@ -997,9 +1059,93 @@ If no `vault` is configured and no `--vault` flag is passed, Brainlink uses `$HO
 ```
 
 `defaultAgent` is optional. When set, CLI and MCP calls that omit `--agent`/`agent` use this value automatically. If not set, behavior remains as before.
-`agentProfiles` is optional. When present, CLI and MCP resolve `mode`, `limit` and `tokens` per agent automatically, then fallback to global defaults.
+`agentProfiles` is optional. When present, CLI and MCP resolve `mode`, `limit`, `tokens` and context `strategy` per agent automatically, then fallback to global defaults.
 
 `autoIndexOnWrite` is optional and defaults to `true`. Set it to `false` to defer indexing after writes.
+`autoCanonicalContextLinks` is optional and defaults to `true`. When enabled, `blink add`, `brainlink_add_note` and `brainlink_add_file` add a canonical `## Context Links` entry to the inferred context hub, creating that hub when needed.
+
+## Remote MCP Server
+
+Brainlink can run as a centralized MCP service for clustered workloads. This keeps one shared memory service inside the cluster while applications and agents connect to the MCP endpoint over Streamable HTTP.
+
+```bash
+BRAINLINK_MCP_TOKEN="change-me" brainlink mcp-server \
+  --vault /data/vault \
+  --host 0.0.0.0 \
+  --port 3333 \
+  --path /mcp
+```
+
+The server exposes:
+
+```txt
+POST /mcp      MCP Streamable HTTP endpoint
+GET /healthz  liveness probe
+GET /readyz   readiness probe
+```
+
+When `BRAINLINK_MCP_TOKEN` or `--token` is set, MCP requests must include:
+
+```txt
+Authorization: Bearer <token>
+```
+
+For Kubernetes, run Brainlink as a central `Deployment` with a `Service` and a mounted vault volume:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: brainlink-mcp
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: brainlink-mcp
+  template:
+    metadata:
+      labels:
+        app: brainlink-mcp
+    spec:
+      containers:
+        - name: brainlink
+          image: brainlink:latest
+          args: ["brainlink", "mcp-server", "--vault", "/data/vault", "--host", "0.0.0.0", "--port", "3333"]
+          env:
+            - name: BRAINLINK_MCP_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: brainlink-mcp
+                  key: token
+          ports:
+            - containerPort: 3333
+          readinessProbe:
+            httpGet:
+              path: /readyz
+              port: 3333
+          livenessProbe:
+            httpGet:
+              path: /healthz
+              port: 3333
+          volumeMounts:
+            - name: vault
+              mountPath: /data/vault
+      volumes:
+        - name: vault
+          persistentVolumeClaim:
+            claimName: brainlink-vault
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: brainlink-mcp
+spec:
+  selector:
+    app: brainlink-mcp
+  ports:
+    - port: 3333
+      targetPort: 3333
+```
 
 Use `"embeddingProvider": "none"` when you want FTS-only indexing.
 
@@ -1078,7 +1224,7 @@ Local CLI:
 
 ```bash
 npm run dev -- --help
-npm run dev -- server --vault .brainlink-vault --watch
+npm run dev -- server --vault .brainlink-vault
 ```
 
 Package smoke test:
@@ -1111,9 +1257,9 @@ Detailed notes:
 - HTTP API is local and unauthenticated.
 - Watch mode depends on the platform filesystem watcher.
 
-## Beta Scope
+## Stable Scope
 
-The `0.1.0-beta` line is intended to stabilize the local-first memory loop:
+The `1.0.0` line is the first stable functional release of the local-first memory loop:
 
 - Markdown as durable memory.
 - Rebuildable file index plus local embeddings and encrypted pack exports.
@@ -1121,8 +1267,10 @@ The `0.1.0-beta` line is intended to stabilize the local-first memory loop:
 - 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.
+- Remote MCP server mode for centralized cluster access.
+- Vault management commands for listing, selecting and safely deleting local vaults.
 
-The beta includes local semantic retrieval. Remote embedding providers, remote auth, advanced deduplication and graph editing are future milestones.
+The stable release includes local semantic retrieval, local-first storage, remote MCP transport and operational vault management. Remote embedding providers and deeper graph editing remain future milestones.
 
 ## Security
 

package/dist/application/add-note.js

@@ -1,20 +1,14 @@
-import { access } from 'node:fs/promises';
-import { join } from 'node:path';
 import { writeMarkdownFile } from '../infrastructure/file-system-vault.js';
 import { sanitizeAgentId, sharedAgentId } from '../domain/agents.js';
-import { extractWikiLinks } from '../domain/markdown.js';
 import { validateNoteInput } from '../domain/note-safety.js';
 import { ensureVault } from '../infrastructure/file-system-vault.js';
+import { addCanonicalContextLinkToContent, ensureCanonicalContextHub } from './canonical-context-links.js';
 const slugify = (title) => title
     .normalize('NFKD')
     .replace(/[\u0300-\u036f]/g, '')
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, '-')
     .replace(/^-+|-+$/g, '');
-const systemHubTitle = 'Memory Hub';
-const systemRootTitle = 'Knowledge Root';
-const normalizeTitle = (title) => title.trim().replace(/\.md$/i, '').toLowerCase();
-const noteFilename = (agentId, title) => `agents/${agentId}/${slugify(title) || 'untitled'}.md`;
 const buildNote = (title, content, agentId) => [
     `---`,
     `title: "${title.replaceAll('"', '\\"')}"`,
@@ -26,38 +20,6 @@ const buildNote = (title, content, agentId) => [
     content.trim(),
     ''
 ].join('\n');
-const ensureSystemNote = async (vaultPath, absoluteVaultPath, agentId, title, content) => {
-    const filename = noteFilename(agentId, title);
-    const absolutePath = join(absoluteVaultPath, filename);
-    try {
-        await access(absolutePath);
-        return;
-    }
-    catch { }
-    await writeMarkdownFile(vaultPath, filename, buildNote(title, content, agentId));
-};
-const ensureNonOrphanContent = async (vaultPath, absoluteVaultPath, title, content, agentId) => {
-    const links = extractWikiLinks(content).filter((link) => normalizeTitle(link) !== normalizeTitle(title));
-    if (links.length > 0) {
-        return {
-            content: content.trim(),
-            autoLinked: false,
-            linkTarget: null
-        };
-    }
-    const fallbackTitle = normalizeTitle(title) === normalizeTitle(systemHubTitle) ? systemRootTitle : systemHubTitle;
-    if (fallbackTitle === systemRootTitle) {
-        await ensureSystemNote(vaultPath, absoluteVaultPath, agentId, systemRootTitle, `Entry point for agent memory. [[${systemHubTitle}]] #memory #root`);
-    }
-    else {
-        await ensureSystemNote(vaultPath, absoluteVaultPath, agentId, systemHubTitle, 'Central memory index for this agent namespace. #memory #hub');
-    }
-    return {
-        content: `${content.trim()}\n\nRelated: [[${fallbackTitle}]]`,
-        autoLinked: true,
-        linkTarget: fallbackTitle
-    };
-};
 export const addNoteWithMetadata = async (vaultPath, title, content, agentId = sharedAgentId, options = {}) => {
     validateNoteInput({
         title,
@@ -65,15 +27,22 @@ export const addNoteWithMetadata = async (vaultPath, title, content, agentId = s
         allowSensitive: options.allowSensitive
     });
     const sanitizedAgentId = sanitizeAgentId(agentId);
-    const absoluteVaultPath = await ensureVault(vaultPath);
     const filename = `agents/${sanitizedAgentId}/${slugify(title) || 'untitled'}.md`;
-    const linkedContent = await ensureNonOrphanContent(vaultPath, absoluteVaultPath, title, content, sanitizedAgentId);
-    const note = buildNote(title, linkedContent.content, sanitizedAgentId);
+    await ensureVault(vaultPath);
+    const canonical = options.autoContextLinks === false
+        ? null
+        : addCanonicalContextLinkToContent(title, content.trim());
+    const hub = canonical?.changed
+        ? await ensureCanonicalContextHub(vaultPath, canonical.context, sanitizedAgentId)
+        : null;
+    const note = buildNote(title, canonical?.content ?? content.trim(), sanitizedAgentId);
     const path = await writeMarkdownFile(vaultPath, filename, note);
     return {
         path,
-        autoLinked: linkedContent.autoLinked,
-        linkTarget: linkedContent.linkTarget
+        autoLinked: canonical?.changed ?? false,
+        linkTarget: canonical?.changed ? canonical.hubTitle : null,
+        context: canonical?.context ?? null,
+        hubCreated: hub?.created ?? false
     };
 };
 export const addNote = async (vaultPath, title, content, agentId = sharedAgentId, options = {}) => (await addNoteWithMetadata(vaultPath, title, content, agentId, options)).path;

package/dist/application/analyze-vault.js

@@ -50,7 +50,7 @@ export const getExtendedStats = async (vaultPath, agentId) => {
     await searchKnowledge(absoluteVaultPath, probeQuery, Math.min(defaults.defaultSearchLimit, 8), agentId, 'hybrid');
     const searchLatency = performance.now() - searchStart;
     const contextStart = performance.now();
-    await buildContextPackage(absoluteVaultPath, probeQuery, Math.min(defaults.defaultSearchLimit, 8), defaults.defaultContextTokens, agentId, 'hybrid');
+    await buildContextPackage(absoluteVaultPath, probeQuery, Math.min(defaults.defaultSearchLimit, 8), defaults.defaultContextTokens, agentId, 'hybrid', undefined, defaults.defaultContextCacheTtlMs);
     const contextLatency = performance.now() - contextStart;
     return {
         stats,

package/dist/application/auto-migrate-configured-vault.js

@@ -0,0 +1,37 @@
+import { indexVault } from './index-vault.js';
+import { migrateVaultContent } from './migrate-vault.js';
+import { getLastConfiguredVaultForKey, setLastConfiguredVaultForKey } from '../infrastructure/vault-migration-state.js';
+export const autoMigrateConfiguredVaultIfChanged = async (input) => {
+    const configKey = input.configKey.trim();
+    const configuredVault = input.configuredVault.trim();
+    if (configKey.length === 0 || configuredVault.length === 0) {
+        return {
+            changed: false,
+            migrated: false
+        };
+    }
+    const previousVault = await getLastConfiguredVaultForKey(configKey);
+    if (!previousVault) {
+        await setLastConfiguredVaultForKey(configKey, configuredVault);
+        return {
+            changed: false,
+            migrated: false
+        };
+    }
+    if (previousVault === configuredVault) {
+        return {
+            changed: false,
+            migrated: false
+        };
+    }
+    const migration = await migrateVaultContent(previousVault, configuredVault);
+    const shouldIndex = migration.copied + migration.conflicted > 0;
+    if (shouldIndex) {
+        await indexVault(configuredVault);
+    }
+    await setLastConfiguredVaultForKey(configKey, configuredVault);
+    return {
+        changed: true,
+        migrated: shouldIndex
+    };
+};