@andespindola/brainlink 0.1.0-beta.99 → 1.0.0

package/docs/AGENT_USAGE.md

@@ -51,11 +51,26 @@ Set `BRAINLINK_HOME` when the whole Brainlink home directory should live somewhe
 Use `blink config where` and `blink config doctor` to inspect active paths and effective source.
 
 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.
-You can set `agentProfiles` to define per-agent defaults for `defaultSearchMode`, `defaultSearchLimit` and `defaultContextTokens`.
+You can set `agentProfiles` to define per-agent defaults for `defaultSearchMode`, `defaultSearchLimit`, `defaultContextTokens`, `defaultContextStrategy` and `defaultContextCacheTtlMs`.
 You can tune search-pack compression with `searchPack.rowChunkSize`, `searchPack.compressionLevel` and `searchPack.useDictionary`.
 Guardrails for benchmark acceptance are configured with `searchPack.guardrailMinSavingsPercent` and `searchPack.guardrailMaxLatencyRegressionPercent`.
 
 `autoIndexOnWrite` (default: `true`) controls whether `add` and MCP write tools index right after writing.
+`autoCanonicalContextLinks` (default: `true`) controls whether CLI/MCP write tools add canonical `## Context Links` to inferred context hubs.
+
+## Central MCP Service
+
+For clustered applications, run Brainlink as one central MCP service and let workloads connect to it 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 central service exposes `/mcp` for MCP clients plus `/healthz` and `/readyz` for platform probes. Use a Kubernetes `Service` for internal discovery, mount the Markdown vault through a persistent volume, and pass `Authorization: Bearer <token>` from clients when `BRAINLINK_MCP_TOKEN` or `--token` is configured.
 
 ## Agent Namespaces
 
@@ -161,7 +176,7 @@ 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.
 
-Graph edges are weighted during indexing. Repeated links increase weight. Links inside headings or task-list lines receive a small boost. Priority markers on the same line as a link raise its priority:
+Graph edges are weighted during indexing. Repeated links increase weight. Links inside headings or task-list lines receive a small boost. Priority markers on the same line as a link raise its priority. The graph relationship model indexes every non-self Markdown `[[wiki link]]` as an edge, including structural hub links such as `Memory Hub`, `Knowledge Root`, `MOC` and map notes. Older indexes without the current graph link model version are automatically rebuilt on the next index run.
 
 ```md
 - [ ] Review [[Architecture]] priority: high
@@ -292,6 +307,8 @@ blink add "Implementation Boundary" \
 blink index
 ```
 
+Use `blink index --full` when you need to rebuild every note from Markdown source. Full reindexing builds the replacement index before persisting it, preserving the previous context until the new index is ready. Brainlink also runs this complete source reindex automatically when it detects an older stored graph link model.
+
 ### Claude Code-Style Agent
 
 Use Brainlink as a preflight memory read before editing files:
@@ -368,6 +385,19 @@ blink config set-vault /absolute/path/to/vault --global
 
 `config set-vault` updates Brainlink config through CLI. By default it writes local `brainlink.config.json`, appends the vault to `allowedVaults`, and migrates markdown when the target is empty.
 
+### Manage Known Vaults
+
+```bash
+blink vaults list
+blink vaults use /absolute/path/to/vault
+blink vaults use /absolute/path/to/vault --global
+blink vaults delete /absolute/path/to/vault --yes
+```
+
+`vaults list` shows the configured default vault, allowlisted vaults and the built-in default vault, including local existence and Markdown/index counts when available.
+`vaults use` switches the default vault without migrating memory.
+`vaults delete` deletes only local filesystem vaults, requires `--yes`, and refuses deleting the current default vault.
+
 ### Migrate Vaults Explicitly
 
 ```bash
@@ -539,9 +569,14 @@ blink context "how does authentication work?" --vault ./vault --limit 12 --token
 blink context "how does authentication work?" --vault ./vault --json
 blink context "how does authentication work?" --vault ./vault --agent coding-agent --json
 blink context "how does authentication work?" --vault ./vault --agent coding-agent --mode hybrid --json
+blink context "how does authentication work?" --vault ./vault --agent coding-agent --strategy cag --json
+blink context "how does authentication work?" --vault ./vault --agent coding-agent --strategy auto --json
+blink context-packs --vault ./vault --json
+blink context-packs --vault ./vault --stale --clear
 ```
 
 This returns a Markdown context package optimized for prompt injection.
+The default strategy is configured by `defaultContextStrategy` and starts as `rag`. Use `--strategy cag` when the same agent/task context should be served from a persisted context pack when the index and volatile-memory signatures are unchanged. Use `--strategy auto` when Brainlink should use CAG on fresh pack hits and RAG otherwise. Context responses include `cache`, `metrics`, `requestedStrategy` and `recommendedStrategy` metadata. CAG packs live under `.brainlink/context-packs` and are rebuildable derived artifacts.
 
 ### Inspect Links
 
@@ -607,7 +642,7 @@ Without `--vault`, the graph UI serves `$HOME/.brainlink/vault`.
 
 The frontend includes an agent selector that shows only the agent id. Selecting an agent calls the same read APIs with `agent=<agent-id>` and renders that namespace instead of merging every agent into one graph.
 
-Graph navigation controls include zoom in, zoom out, fit visible nodes and reset-to-fit-all nodes. Mouse wheel zoom (including `cmd+scroll` and `ctrl+scroll`) is anchored to the cursor. Keyboard shortcuts are `+` (zoom in), `-` (zoom out) and `0` (reset fit). Double-click on canvas zooms in at cursor position. Totals for notes, links and tags stay visible as floating metrics under the Brainlink title, and node details open on click in a modal (tags, outgoing links, backlinks and Markdown content).
+Graph navigation controls include zoom in, zoom out, fit visible nodes and reset-to-fit-all nodes. Mouse wheel zoom (including `cmd+scroll` and `ctrl+scroll`) is anchored to the cursor and applied immediately without delayed focus interpolation. Keyboard shortcuts are `+` (zoom in), `-` (zoom out) and `0` (reset fit). Double-click on empty canvas zooms in at cursor position. Clicking a node opens its details panel. Totals for notes, links and tags stay visible as floating metrics under the Brainlink title, and node details open in a non-modal side panel (tags, outgoing links, backlinks and Markdown content), so zoom and pan remain available during inspection. The visual layout is a cauliflower 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. Indexed weighted wiki-link edges remain available for backlinks, ranking and context traversal outside the render layer. At high zoom-out, graph streams show segment hub clusters first; zooming in progressively reveals the individual nodes inside those lobes. Node titles appear as zoom approaches readable scale, limited to on-screen nodes in very large graphs.
 During graph filtering, Brainlink keeps hub context nodes visible (`Memory Hub`/`MOC`/high-degree fallback) so filtered views still show relationship anchors.
 
 The command reindexes by default, then serves:
@@ -625,12 +660,14 @@ Use `--no-index` when you need to inspect the current index without rebuilding i
 blink server --vault ./vault --no-index
 ```
 
-Use `--watch` to keep the graph updated after Markdown edits:
+The server watches Markdown files by default and keeps the graph updated after edits:
 
 ```bash
-blink server --vault ./vault --watch
+blink server --vault ./vault
 ```
 
+Use `--no-watch` when you need to run the graph server without realtime reindexing.
+
 ### Watch A Vault
 
 ```bash
@@ -665,16 +702,21 @@ Available MCP tools:
 - `brainlink_policy`
 - `brainlink_recommendations`
 - `brainlink_context`
+- `brainlink_context_packs`
 - `brainlink_search`
 - `brainlink_dedupe`
 - `brainlink_resolve_duplicate`
 - `brainlink_add_note`
 - `brainlink_add_file`
+- `brainlink_canonicalize_context_links`
+- `brainlink_volatile_add`
+- `brainlink_volatile_clear`
 - `brainlink_index`
 - `brainlink_stats`
 - `brainlink_validate`
 - `brainlink_sync`
 - `brainlink_graph`
+- `brainlink_graph_contexts`
 - `brainlink_broken_links`
 - `brainlink_orphans`
 
@@ -684,11 +726,13 @@ If `autoBootstrapOnRead` or `enforceContextFirst` are disabled through `brainlin
 `brainlink_bootstrap`, `brainlink_policy` and preflight responses include structured `nextActions` so clients can continue tool flows automatically.
 `brainlink_policy` also accepts policy presets (`fully-auto`, `strict`) so MCP clients can switch behavior in one call.
 `brainlink_recommendations` returns the suggested execution order so an agent can follow Brainlink best practices automatically.
+MCP context is plug-and-play: agents may omit `strategy` for the configured default, pass `strategy: "rag"` for explicit fresh retrieval assembly, pass `strategy: "cag"` to reuse persisted context packs when the task context is stable or repeated, or pass `strategy: "auto"` to use CAG on fresh pack hits and RAG otherwise. `brainlink_recommendations`, policy next actions and preflight responses return executable context arguments, so clients can continue without custom parsing. `brainlink_context_packs` lists or clears persisted CAG packs.
 
 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:
 
 `brainlink_graph` returns weighted edges. Agents should prefer higher `weight` and stronger `priority` when deciding which related notes matter most.
 `brainlink_add_note` and `brainlink_add_file` return `writeConnectivity` metadata and guarantee at least one edge for new notes.
+Agents should use `brainlink_volatile_add` for temporary task state, hypotheses, local execution details and unconfirmed findings. Volatile memory is included in `brainlink_context` with `Volatile: true`, expires by TTL and does not create durable Markdown notes or graph edges.
 
 ```bash
 export BRAINLINK_ALLOWED_VAULTS="/absolute/path/to/project-vault"
@@ -699,6 +743,7 @@ export BRAINLINK_ALLOWED_VAULTS="/absolute/path/to/project-vault"
 ```txt
 GET  /api/graph
 GET  /api/graph-layout
+GET  /api/graph-view?x=<x>&y=<y>&w=<width>&h=<height>&scale=<scale>
 GET  /api/graph-node?id=<node-id>
 GET  /api/graph-filter?q=<query>&limit=<n>
 GET  /api/search?q=<query>&limit=10&mode=hybrid

package/docs/ARCHITECTURE.md

@@ -136,6 +136,8 @@ read markdown files
 
 ```txt
 question
+  -> selected strategy: rag | cag | auto
+  -> if cag/auto and fresh context pack exists, return cached Markdown package
   -> selected mode: fts | semantic | hybrid
   -> optional query embedding
   -> optional compressed pack prefilter (token bloom)
@@ -145,8 +147,12 @@ question
   -> ranked chunks with textScore and semanticScore
   -> token-budget selection
   -> Markdown context package
+  -> if cag/auto, persist derived context pack with current data signature
+  -> return cache, strategy and timing metrics
 ```
 
+Context packs are stored under `.brainlink/context-packs/*.json`. They are derived artifacts keyed by query, agent, mode, limit and token budget, and are invalidated by the combined index and volatile-memory signature. Markdown remains the source of truth. The `auto` strategy uses CAG on fresh pack hits and falls back to RAG assembly otherwise, refreshing a pack for later calls.
+
 ## Graph Server Flow
 
 ```txt
@@ -154,11 +160,15 @@ server command
   -> optional index rebuild
   -> HTTP server
   -> /api/agents lists indexed namespaces
+  -> /api/graph-contexts lists visual graph contexts
   -> /api/graph reads indexed documents and links
+  -> /api/graph-layout derives a cauliflower hub layout from indexed graph data
+  -> optional context query narrows the layout to a segment-scoped cauliflower subgraph
   -> browser renders graph canvas
 ```
 
 The graph UI is intentionally read-only. Markdown remains the write interface and index artifacts remain derived data.
+The cauliflower layout is a visual projection over the indexed graph. Indexed weighted wiki-link edges remain unchanged for backlinks, ranking, graph reads and context traversal. The browser layout renders a simplified hierarchy instead: primary hub -> segment hubs -> local context nodes. This avoids unstable cross-context visual edges while preserving the real relationship model outside the render layer. Zoomed-out graph streams summarize those lobes as segment clusters before revealing individual nodes on zoom-in.
 
 ## HTTP API Flow
 
@@ -171,6 +181,7 @@ HTTP request
 ```
 
 The HTTP API is local-first and unauthenticated. It is meant for local agents, browser UI, and development workflows.
+The route adapter caches generated frontend assets (`/`, `/styles.css`, `/app.js`, `/app-worker.js`) and graph-layout JSON payloads by layout signature to reduce repeated CPU and allocation pressure during navigation.
 
 ## MCP Flow
 

package/docs/QUICKSTART.md

@@ -50,7 +50,9 @@ Optional per-agent retrieval defaults in `brainlink.config.json`:
     "coding-agent": {
       "defaultSearchMode": "semantic",
       "defaultSearchLimit": 8,
-      "defaultContextTokens": 2400
+      "defaultContextTokens": 2400,
+      "defaultContextStrategy": "auto",
+      "defaultContextCacheTtlMs": 120000
     }
   }
 }

package/docs/RELEASE.md

@@ -2,7 +2,7 @@
 
 Brainlink releases are built from the CLI package. Do not publish until the package name, npm account and version are confirmed.
 
-## Beta Release Checklist
+## Release Checklist
 
 1. Confirm `package.json` name, version, repository, license and bin entries.
 2. Run `npm install` from a clean checkout when dependencies changed.
@@ -51,9 +51,10 @@ 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.
 - 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-beta.1` publishes with `--tag beta`.
+- Stable versions publish under the `latest` dist-tag by default.
+- Prerelease versions publish under their prerelease dist-tag, for example `1.1.0-beta.1` publishes with `--tag beta`.
 
-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-beta.4` becomes `0.1.0-beta.5`.
+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, `1.0.0` becomes `1.0.1`, and `1.1.0-beta.4` becomes `1.1.0-beta.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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/brainlink",
-  "version": "0.1.0-beta.99",
+  "version": "1.0.0",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",
@@ -48,6 +48,7 @@
     "build": "npm run clean && npx --yes snyk test && tsc -p tsconfig.json",
     "dev": "tsx src/cli/main.ts",
     "dev:mcp": "tsx src/mcp/main.ts",
+    "dev:mcp:http": "tsx src/cli/main.ts mcp-server",
     "brainlink:sync": "bash scripts/brainlink-sync.sh",
     "security": "npx --yes snyk test",
     "test": "vitest run --config vitest.config.ts",
@@ -63,6 +64,7 @@
     "zod": "^4.3.6"
   },
   "overrides": {
+    "hono": "4.12.21",
     "qs": "6.15.2"
   },
   "devDependencies": {