@andespindola/brainlink 0.1.0-beta.15 → 0.1.0-beta.151

package/dist/mcp/tools.js

@@ -4,13 +4,16 @@ import { z } from 'zod';
 import { getBrokenLinksReport, getOrphansReport, getStats, validateVault } from '../application/analyze-vault.js';
 import { addNoteWithMetadata } from '../application/add-note.js';
 import { buildContextPackage } from '../application/build-context.js';
+import { resolveDuplicateNotes, scanDuplicateNotes } from '../application/dedupe-notes.js';
 import { getGraph } from '../application/get-graph.js';
 import { indexVault } from '../application/index-vault.js';
 import { searchKnowledge } from '../application/search-knowledge.js';
 import { resolveAgentRuntimeDefaults, sanitizeSearchMode } from '../infrastructure/config.js';
 import { loadBrainlinkConfig } from '../infrastructure/config.js';
 import { assertVaultAllowed } from '../infrastructure/file-system-vault.js';
+import { addVolatileMemory, clearVolatileMemory } from '../infrastructure/volatile-memory.js';
 import { getBootstrapPolicy, getBootstrapSessionStatus, getContextSessionStatus, setBootstrapPolicy, touchBootstrapSession, touchContextSession } from '../infrastructure/session-state.js';
+import { getRuntimeMetadata } from './runtime.js';
 const positiveInteger = (fallback) => z
     .number()
     .int()
@@ -236,6 +239,20 @@ export const addNoteInputSchema = {
     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 volatileAddInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    content: z
+        .string()
+        .min(1)
+        .describe('Temporary agent-decided memory. Use for current task state, hypotheses, transient user preferences and unconfirmed findings.'),
+    ttlMinutes: optionalPositiveInteger().describe('Minutes before this volatile memory expires. Defaults to 240.'),
+    tags: z.array(z.string()).optional().default([]).describe('Optional tags for volatile retrieval.')
+};
+export const volatileClearInputSchema = {
+    ...vaultInput,
+    ...agentInput
+};
 export const addFileInputSchema = {
     ...vaultInput,
     ...agentInput,
@@ -245,7 +262,12 @@ export const addFileInputSchema = {
     allowSensitive: z.boolean().optional().default(false).describe('Allow content that looks like a secret.')
 };
 export const indexInputSchema = {
-    ...vaultInput
+    ...vaultInput,
+    full: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Force a complete reindex from Markdown source without reusing unchanged index entries.')
 };
 export const validateInputSchema = {
     ...vaultInput,
@@ -303,6 +325,10 @@ export const policyInputSchema = {
         .describe('Run automatic bootstrap during MCP server startup using configured default vault/agent.'),
     staleAfterMinutes: positiveInteger(120).describe('Bootstrap freshness window in minutes before read tools require a new bootstrap.')
 };
+export const versionInputSchema = {
+    ...vaultInput,
+    ...agentInput
+};
 export const recommendationsInputSchema = {
     ...vaultInput,
     ...agentInput,
@@ -311,6 +337,20 @@ export const recommendationsInputSchema = {
     limit: optionalPositiveInteger().describe('Optional context limit override for generated recommendations.'),
     tokens: optionalPositiveInteger().describe('Optional context token budget override for generated recommendations.')
 };
+export const dedupeInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    limit: optionalPositiveInteger().describe('Maximum duplicate candidate pairs to return.'),
+    minScore: z.number().min(0).max(1).optional().describe('Minimum semantic similarity score between 0 and 1.'),
+    semantic: z.boolean().optional().default(true).describe('Enable semantic duplicate detection in addition to exact content hash matches.')
+};
+export const dedupeResolveInputSchema = {
+    ...vaultInput,
+    leftPath: z.string().min(1).describe('Left note path from dedupe results.'),
+    rightPath: z.string().min(1).describe('Right note path from dedupe results.'),
+    action: z.enum(['merge', 'link', 'ignore']).describe('Resolution action.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex after duplicate resolution.')
+};
 export const contextTool = async (input) => {
     const context = await resolveExecutionContext(input);
     const readiness = await ensureBootstrapReady(context, input, 'brainlink_context');
@@ -364,6 +404,14 @@ export const addNoteTool = async (input) => {
         allowSensitive: input.allowSensitive
     });
     const index = shouldIndex ? await indexVault(context.vault) : undefined;
+    const focusPath = added.path.includes('agents/') ? added.path.slice(added.path.indexOf('agents/')).replaceAll('\\', '/') : undefined;
+    const possibleDuplicates = await scanDuplicateNotes(context.vault, {
+        agentId: context.agent,
+        focusPath,
+        limit: 5,
+        minSemanticScore: 0.92,
+        includeSemantic: true
+    });
     return jsonResult({
         vault: context.vault,
         title: input.title,
@@ -374,9 +422,29 @@ export const addNoteTool = async (input) => {
             linkTarget: added.linkTarget,
             guaranteedEdge: true
         },
+        possibleDuplicates,
         ...(index ? { index } : {})
     });
 };
+export const volatileAddTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const entry = await addVolatileMemory(context.vault, input.content, context.agent ?? 'shared', input.ttlMinutes ?? 240, input.tags);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        volatile: true,
+        entry
+    });
+};
+export const volatileClearTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const cleared = await clearVolatileMemory(context.vault, context.agent);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        cleared
+    });
+};
 export const addFileTool = async (input) => {
     const context = await resolveExecutionContext(input);
     const content = await readFile(input.filePath, 'utf8');
@@ -406,7 +474,9 @@ export const addFileTool = async (input) => {
 };
 export const indexTool = async (input) => {
     const context = await resolveExecutionContext(input);
-    const result = await indexVault(context.vault);
+    const result = await indexVault(context.vault, {
+        full: input.full === true
+    });
     return jsonResult({
         vault: context.vault,
         ...result
@@ -701,12 +771,21 @@ export const policyTool = async (input) => {
     return jsonResult(withNextActions({
         vault: context.vault,
         agent: context.agent,
+        runtime: getRuntimeMetadata(),
         policy,
         bootstrapStatus,
         contextStatus,
         ...(input.preset ? { presetApplied: input.preset } : {})
     }, withContextAction));
 };
+export const versionTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        runtime: getRuntimeMetadata()
+    });
+};
 export const recommendationsTool = async (input) => {
     const context = await resolveExecutionContext(input);
     const policy = await getBootstrapPolicy();
@@ -792,6 +871,17 @@ export const recommendationsTool = async (input) => {
                 tokens
             }
         },
+        {
+            tool: 'brainlink_dedupe',
+            reason: 'Detect and resolve duplicate durable notes to keep memory quality high.',
+            args: {
+                vault: context.vault,
+                ...(context.agent ? { agent: context.agent } : {}),
+                limit: 10,
+                minScore: 0.92,
+                semantic: true
+            }
+        },
         {
             tool: 'brainlink_add_note',
             reason: 'Persist durable outcomes after task completion (write responses include connectivity metadata).',
@@ -818,3 +908,30 @@ export const recommendationsTool = async (input) => {
         recommendations
     });
 };
+export const dedupeTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const duplicates = await scanDuplicateNotes(context.vault, {
+        agentId: context.agent,
+        limit: input.limit ?? 25,
+        minSemanticScore: input.minScore ?? 0.92,
+        includeSemantic: input.semantic !== false
+    });
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        duplicates
+    });
+};
+export const dedupeResolveTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const result = await resolveDuplicateNotes(context.vault, {
+        leftPath: input.leftPath,
+        rightPath: input.rightPath,
+        action: input.action,
+        autoIndex: isTruthy(input.autoIndex)
+    });
+    return jsonResult({
+        vault: context.vault,
+        ...result
+    });
+};

package/docs/AGENT_USAGE.md

@@ -52,6 +52,8 @@ Use `blink config where` and `blink config doctor` to inspect active paths and e
 
 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 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.
 
@@ -159,7 +161,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
@@ -290,6 +292,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:
@@ -377,6 +381,18 @@ blink migrate-vault --from ~/.brainlink/vault --to ./team-vault --report ./migra
 
 Use `--dry-run` to preview `copied`, `conflicted`, `unchanged` before writing files.
 
+### Import Legacy SQLite DB
+
+```bash
+blink db-import --vault ./team-vault
+blink db-import --vault ./team-vault --db ./legacy/brainlink.db
+blink db-import --vault ./team-vault --db ./legacy/brainlink.db --table legacy_notes --dry-run
+```
+
+`db-import` migrates rows from legacy SQLite memory into Markdown notes in the current vault and indexes the result by default.
+Without `--db`, Brainlink auto-detects common legacy database paths.
+Use `--agent` to force namespace, `--limit` for staged migration, `--dry-run` to preview writes, and `--no-index` to postpone indexing.
+
 ### Install Agent Integration
 
 ```bash
@@ -390,6 +406,7 @@ blink agent status
 ```
 
 `agent install` configures Brainlink MCP in `~/.codex/config.toml` so compatible agents can use Brainlink by default.
+`agent install` and `agent upgrade` automatically apply the `fully-auto` MCP bootstrap policy (`enforceBootstrap=true`, `enforceContextFirst=true`, `autoBootstrapOnRead=true`, `autoBootstrapOnStartup=true`) so all plug-and-play Brainlink features start enabled.
 Use `agent upgrade` on legacy installations to reapply the latest defaults and run self-test diagnostics.
 Use `agent policy --preset fully-auto` to keep startup/read auto-bootstrap enabled, or `agent policy --preset strict` to force explicit bootstrap calls.
 
@@ -417,6 +434,25 @@ 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.
 Brainlink also auto-connects notes that have no `[[wiki links]]` by adding a fallback edge to an agent hub note, so new memory does not stay disconnected.
+`add` also returns `possibleDuplicates` (exact hash + semantic candidates) so agents can decide duplicate resolution immediately.
+
+### Detect Duplicate Notes
+
+```bash
+blink dedupe --vault ./vault --json
+blink dedupe --vault ./vault --agent coding-agent --limit 20 --min-score 0.92 --json
+blink dedupe --vault ./vault --no-semantic --json
+```
+
+### Resolve Duplicate Notes
+
+```bash
+blink dedupe-resolve --vault ./vault --left agents/shared/a.md --right agents/shared/b.md --action merge --json
+blink dedupe-resolve --vault ./vault --left agents/shared/a.md --right agents/shared/b.md --action link --json
+blink dedupe-resolve --vault ./vault --left agents/shared/a.md --right agents/shared/b.md --action ignore --json
+```
+
+`dedupe-resolve` keeps connectivity: non-merge actions still create a low-priority related edge (`#related-to`).
 
 For agent-private memory:
 
@@ -446,6 +482,37 @@ This scans Markdown files and rebuilds:
 - links
 - full-text search records
 
+### Benchmark Indexing Realtime
+
+```bash
+blink bench --vault ./vault
+blink bench --vault ./vault --watch
+blink bench --vault ./vault --watch --debounce 500
+blink bench --vault ./vault --json
+```
+
+`bench` runs indexing with realtime phase events and prints a run summary with:
+
+- indexed totals (documents, chunks, links)
+- elapsed time and changed document count
+- pack rebuild status and reason
+- pack compression metrics (`inputBytes`, `outputBytes`, ratio/saved percentage)
+- objective guardrails (`guardrailMinSavingsPercent`, `guardrailMaxLatencyRegressionPercent`)
+
+Use `--watch` for continuous benchmark runs while editing notes. Watch mode is supported only for local filesystem vaults.
+If pack manifest metadata is missing but encrypted `.blpk` files are present, Brainlink repairs manifest metadata before deciding rebuild policy to avoid unnecessary full repacks on small updates.
+
+### Create Offline Pack Backup
+
+```bash
+blink pack-backup --vault ./vault
+blink pack-backup --vault ./vault --output ./vault/.brainlink/backups/custom.blpkbak.gz
+blink pack-backup --vault ./vault --json
+```
+
+`pack-backup` creates an offline artifact with second-stage compression on top of encrypted `.blpk` packs.
+This is outside the online retrieval path (`index`, `search`, `context`), which keeps a single compression stage.
+
 ### Search Knowledge
 
 ```bash
@@ -465,6 +532,7 @@ Search modes:
 - `semantic`: local deterministic embedding similarity.
 
 Hybrid results are cached in-memory for a short TTL and invalidated when `.brainlink/index.json` changes.
+Context assembly uses middle-out ordering inside each note: the highest-scoring chunk is selected first, then nearby chunks are expanded while token budget allows.
 
 ### Build Agent Context
 
@@ -523,15 +591,26 @@ shared: 30 documents
 ```bash
 blink server --host 127.0.0.1 --port 4321
 blink server --vault ./vault --host 127.0.0.1 --port 4321
+blink server --vault ./vault --host 127.0.0.1 --port 4321 --no-open
 ```
 
 This starts a local frontend for inspecting the knowledge graph.
+By default it tries to open the graph in a native desktop GUI window:
+- macOS: Swift + WebKit
+- Windows: PowerShell WinForms WebBrowser
+- Linux: optional Python GTK + WebKit2 (requires `python3` + `gi` + `WebKit2`)
+
+On Linux, native GUI is disabled by default for better startup performance. Enable it with `BRAINLINK_LINUX_NATIVE_GUI=1`.
+If native GUI launch is unavailable, it falls back to dedicated app-window mode and then to the default browser.
+Use `--no-open` to keep the server headless.
+When native GUI is active, the GUI window closes automatically when the `blink server` process stops.
 
 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 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 is anchored to the cursor. 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 star centered on the primary hub, while underlying weighted wiki-link edges are preserved for backlinks, ranking and context traversal. Vaults above 1000 notes keep the same single graph scene and render the full filtered node/edge set during navigation, without viewport-sampled subgraph switching. 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:
 
@@ -589,8 +668,12 @@ Available MCP tools:
 - `brainlink_recommendations`
 - `brainlink_context`
 - `brainlink_search`
+- `brainlink_dedupe`
+- `brainlink_resolve_duplicate`
 - `brainlink_add_note`
 - `brainlink_add_file`
+- `brainlink_volatile_add`
+- `brainlink_volatile_clear`
 - `brainlink_index`
 - `brainlink_stats`
 - `brainlink_validate`
@@ -610,6 +693,7 @@ MCP clients can pass `vault` and `agent` arguments per tool call. Set `BRAINLINK
 
 `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"
@@ -620,6 +704,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
@@ -635,6 +720,7 @@ GET  /api/validate
 The HTTP API is read-only. Use the CLI for writes and indexing.
 
 Indexing writes private encrypted search packs at `.brainlink/search-packs/*.blpk` for resilient retrieval and portability.
+Pack search now uses compressed-space prefiltering (token bloom index per pack) before decrypting/reading pack payloads.
 Pack decryption keys are resolved from `$BRAINLINK_HOME/keys` (or `BRAINLINK_SEARCH_PACK_KEY` when explicitly set).
 
 ## Agent Integration Contract

package/docs/ARCHITECTURE.md

@@ -138,8 +138,10 @@ read markdown files
 question
   -> selected mode: fts | semantic | hybrid
   -> optional query embedding
+  -> optional compressed pack prefilter (token bloom)
   -> lexical scoring and/or semantic cosine scoring
   -> cosine similarity over candidate chunks
+  -> middle-out context expansion around strongest chunk
   -> ranked chunks with textScore and semanticScore
   -> token-budget selection
   -> Markdown context package
@@ -153,10 +155,12 @@ server command
   -> HTTP server
   -> /api/agents lists indexed namespaces
   -> /api/graph reads indexed documents and links
+  -> /api/graph-layout derives a star layout from indexed graph data
   -> browser renders graph canvas
 ```
 
 The graph UI is intentionally read-only. Markdown remains the write interface and index artifacts remain derived data.
+The star layout is visual only: it keeps the indexed weighted wiki-link edges unchanged so backlinks, ranking and context traversal keep their original semantics.
 
 ## HTTP API Flow
 
@@ -169,6 +173,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
 
@@ -293,6 +298,7 @@ Markdown keeps the system portable, inspectable, Git-friendly, and compatible wi
 Brainlink uses a local JSON index plus encrypted pack exports for fast rebuildable retrieval without external infrastructure.
 Hybrid retrieval also uses a short-lived in-memory cache keyed by vault/query/agent and invalidated by index file mtime to reduce repeated query latency.
 Indexing exports private encrypted pack files (`.brainlink/search-packs/*.blpk`) from indexed chunks for fast retrieval and recovery continuity.
+Pack manifests include compressed-space token bloom metadata so retrieval can skip unrelated packs before decryption.
 Pack encryption keys are resolved from `$BRAINLINK_HOME/keys` or from `BRAINLINK_SEARCH_PACK_KEY` when configured.
 Legacy `.jsonl.gz` search packs are auto-upgraded to `.blpk` on first retrieval flow.
 

package/docs/QUICKSTART.md

@@ -102,3 +102,10 @@ S3 target:
 ```bash
 blink migrate-vault --from ~/.brainlink/vault --to "s3://my-memory-bucket/brainlink" --dry-run
 ```
+
+Legacy SQLite import:
+
+```bash
+blink db-import --vault ./team-vault
+blink db-import --vault ./team-vault --db ./legacy/brainlink.db --dry-run
+```

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@andespindola/brainlink",
-  "version": "0.1.0-beta.15",
+  "version": "0.1.0-beta.151",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",
-  "author": "Anderson Espindola",
+  "author": "Substructa",
   "homepage": "https://github.com/andersonflima/brainlink#readme",
   "repository": {
     "type": "git",
@@ -32,6 +32,7 @@
     "dist",
     "assets",
     "README.md",
+    "COPYRIGHT.md",
     "LICENSE",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
@@ -61,6 +62,10 @@
     "commander": "^14.0.2",
     "zod": "^4.3.6"
   },
+  "overrides": {
+    "hono": "4.12.21",
+    "qs": "6.15.2"
+  },
   "devDependencies": {
     "@types/node": "^24.9.2",
     "tsx": "^4.21.0",