@andespindola/brainlink 0.1.0-beta.7 → 0.1.0-beta.9

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.1.0-beta.4
+
+- Added bootstrap session-state persistence in `$BRAINLINK_HOME/session-state.json` for vault/agent readiness tracking.
+- Added MCP `brainlink_policy` tool and default bootstrap enforcement for read tools.
+- Added `agent install --self-test` diagnostics and bootstrap readiness details in `agent status`.
+- Added `agent upgrade` for legacy installations to reapply latest MCP/plugin defaults with self-test diagnostics.
+- Added `config doctor --fix` safe autofix mode with dry-run default behavior.
+- Added detailed per-file migration reporting through `migrate-vault --report`.
+- Added `quickstart` command to run plug-and-play vault + bootstrap + agent setup in one flow.
+- Added structured MCP `nextActions` in bootstrap/policy/preflight responses for automatic client continuation.
+- Added default MCP read auto-bootstrap behavior controlled by `brainlink_policy.autoBootstrapOnRead`.
+- 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.
+- 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.
+- Improved graph/index robustness by splitting oversized paragraphs into bounded chunks and dropping self-referential links.
+- Added `agentProfiles` configuration support so CLI and MCP can resolve per-agent defaults for mode/limit/tokens.
+- Added short-lived hybrid search cache with automatic invalidation on index changes.
+- Added `stats --extended` observability output with storage, quality and latency probes.
+- Added `docs/QUICKSTART.md` and aligned README/agent docs with the latest CLI/MCP flows.
+
+## 0.1.0-beta.3
+
+- Added CLI configuration commands for effective vault management, including `config where`, `config get`, `config doctor` and `config set-vault`.
+- Added explicit `migrate-vault` command with `--dry-run` preview and conflict-preserving copy behavior.
+- Added one-command agent setup through `agent install` plus `agent status` diagnostics.
+- Added MCP `brainlink_bootstrap` default entrypoint guidance for plug-and-play agent memory flows.
+- Added migration coverage for S3 bucket vault targets.
+- Updated architecture and agent-usage documentation to reflect current CLI/MCP behavior and configuration precedence.
+
 ## 0.1.0-beta.2
 
 - Added MCP installation guidance for direct server configuration and local client stores.

package/README.md

@@ -106,6 +106,8 @@ npx @andespindola/brainlink@latest --help
 
 This section is written for agents. If you are an AI agent operating in a user workspace, use this workflow to install and use Brainlink without requiring the user to run commands manually.
 
+For a condensed setup path, see [docs/QUICKSTART.md](./docs/QUICKSTART.md).
+
 ### 1. Check Whether Brainlink Is Installed
 
 ```bash
@@ -380,6 +382,35 @@ Example MCP client configuration:
 }
 ```
 
+### One-Command Agent Setup
+
+If your agent runtime is Codex-compatible, run:
+
+```bash
+blink agent install --self-test
+blink agent upgrade
+```
+
+This configures `~/.codex/config.toml` with Brainlink MCP (`brainlink-mcp`) so Brainlink is available by default in agent sessions.
+
+If you are inside this repository and want plugin gallery setup too:
+
+```bash
+blink agent install --plugin-path ./plugins/brainlink
+```
+
+To verify:
+
+```bash
+blink agent status
+```
+
+For fully automated first run (vault index + health + bootstrap readiness + agent integration):
+
+```bash
+blink quickstart --query "what should I know before this task?" --json
+```
+
 For a locked-down setup, allowlist the vaults that MCP clients may access:
 
 ```json
@@ -475,6 +506,9 @@ Restart the client after changing marketplace or MCP configuration so it reloads
 
 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 enforcement 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_search`: search indexed notes.
 - `brainlink_add_note`: write durable Markdown memory and reindex.
@@ -487,7 +521,14 @@ Available tools:
 - `brainlink_broken_links`: list unresolved wiki links.
 - `brainlink_orphans`: list disconnected notes.
 
-The same linking rule applies through MCP: `brainlink_context` is read-only, and real graph links require Markdown notes with explicit `[[wiki links]]`. `brainlink_add_note` and `brainlink_add_file` reindex by default and include the index result when enabled.
+For the most automatic workflow, start MCP sessions with `brainlink_bootstrap` (optionally with `query`) and then continue with `brainlink_context`/`brainlink_add_note`.
+By default, MCP startup already runs bootstrap on the configured default vault/agent (`autoBootstrapOnStartup=true`), so sessions begin warm.
+By default, Brainlink enforces bootstrap and auto-runs it for read tools when session state is missing or stale (`autoBootstrapOnRead=true`).
+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 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.
 
 Agents can raise the importance of a relationship by putting priority markers on the same line as a wiki link:
 
@@ -556,14 +597,75 @@ Read routes accept `agent=<agent-id>`:
 
 Every command works with either `brainlink` or `blink`.
 
+### `agent`
+
+```bash
+blink agent install
+blink agent install --self-test
+blink agent upgrade
+blink agent policy --preset fully-auto
+blink agent policy --preset strict
+blink agent install --plugin-path ./plugins/brainlink
+blink agent install --mcp-only --allowed-vaults "/absolute/vault,/absolute/team-vault"
+blink agent status
+```
+
+Installs/checks agent integration. `install` writes Brainlink MCP config into `~/.codex/config.toml`.
+When plugin files are available, it also links Brainlink plugin files into `~/plugins/brainlink` and updates `~/.agents/plugins/marketplace.json`.
+With `--self-test`, install also validates MCP block presence, command wiring and local plugin registration signals.
+Use `agent upgrade` on legacy installations to reapply current defaults and run the same self-test diagnostics.
+Use `agent policy --preset fully-auto` for plug-and-play defaults, or `agent policy --preset strict` to require explicit bootstrap calls.
+
+### `quickstart`
+
+```bash
+blink quickstart --json
+blink quickstart --vault ./team-vault --agent coding-agent --query "architecture decisions" --json
+blink quickstart --vault ./team-vault --mcp-only --json
+```
+
+Runs index + doctor + stats + validation, refreshes bootstrap session readiness, optionally returns context for a query, and (by default) upgrades local agent integration for plug-and-play MCP usage.
+When `--mode`, `--limit` or `--tokens` are omitted, quickstart uses agent profile defaults when available.
+
+### `config`
+
+```bash
+blink config where
+blink config get vault
+blink config doctor
+blink config doctor --fix
+blink config set-vault /absolute/path/to/existing-vault
+blink config set-vault /absolute/path/to/existing-vault --migrate-from ~/.brainlink/vault
+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.  
+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.
+
+### `migrate-vault`
+
+```bash
+blink migrate-vault --from ~/.brainlink/vault --to ./team-vault --dry-run
+blink migrate-vault --from ~/.brainlink/vault --to ./team-vault
+blink migrate-vault --from ~/.brainlink/vault --to "s3://my-memory-bucket/brainlink"
+blink migrate-vault --from ~/.brainlink/vault --to ./team-vault --report ./migration-report.json
+```
+
+Runs explicit markdown migration between vaults while preserving conflicts as `.conflict-<timestamp>` files.  
+Use `--dry-run` to preview `copied`, `conflicted` and `unchanged` counts before writing.
+
 ### `init`
 
 ```bash
 blink init
 blink init ./vault
+blink init ./team-vault --migrate-from ~/.brainlink/vault
 ```
 
 Initializes vault metadata. Without an argument, Brainlink initializes the default vault at `$HOME/.brainlink/vault`.
+When initializing an empty custom vault, existing Markdown content from the default vault is copied into it and reindexed so context is not left behind. Use `--no-migrate-existing` to start with an empty custom vault, or `--migrate-from <vault>` to copy from a specific source. Existing target files are never overwritten; conflicting source files are preserved with a `.conflict-<timestamp>` suffix.
 
 ### `add`
 
@@ -577,6 +679,7 @@ blink add "Note Title" --vault ./vault --content-file ./notes.md --no-auto-index
 `--content` and `--content-file` are mutually exclusive. Add `--no-auto-index` when you want to defer reindexing.
 
 Creates a Markdown note under `agents/<agent-id>/`. Common secret patterns are blocked by default; use `--allow-sensitive` only for an intentionally protected vault.
+To avoid disconnected memory, Brainlink auto-adds a fallback wiki edge when a note is written without links, creating agent hub notes when needed.
 
 ### `index`
 
@@ -605,6 +708,7 @@ blink search "query" --vault ./vault --mode semantic --json
 ```
 
 Runs retrieval over indexed chunks.
+If `--mode` or `--limit` is omitted, Brainlink resolves values from the current agent profile before falling back to global defaults.
 
 Modes:
 
@@ -612,6 +716,8 @@ Modes:
 - `fts`: exact lexical retrieval through SQLite FTS.
 - `semantic`: local deterministic embedding similarity only.
 
+Hybrid results are cached in-memory for a short TTL and invalidated automatically when the local index file changes.
+
 ### `context`
 
 ```bash
@@ -654,9 +760,11 @@ Prints indexed graph data. Edges include `weight` and `priority` so agents can c
 ```bash
 blink stats --vault ./vault
 blink stats --vault ./vault --agent coding-agent --json
+blink stats --vault ./vault --agent coding-agent --extended --json
 ```
 
 Prints vault metrics.
+Use `--extended` to include storage footprint, link quality ratios and observability probes (`index`, `search`, `context` latencies).
 
 ### `broken-links`
 
@@ -688,7 +796,7 @@ Validates graph health. The command exits non-zero when required checks fail.
 blink doctor --vault ./vault
 ```
 
-Runs environment and vault checks.
+Runs environment and vault checks. When vault has zero markdown and zero indexed documents, `doctor` prints recommended next steps (add note, inspect config source, migrate memory).
 
 ### `watch`
 
@@ -725,7 +833,13 @@ npm run --silent dev -- context "question" --vault ./vault --json
 
 ## Configuration
 
-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`.
+Brainlink merges configuration in this order:
+
+1. Global: `$BRAINLINK_HOME/brainlink.config.json` (or `$HOME/.brainlink/brainlink.config.json` by default)
+2. Local: `brainlink.config.json` in the current working directory
+3. Local legacy compatibility: `.brainlink.json` in the current working directory
+
+If no `vault` is configured and no `--vault` flag is passed, Brainlink uses `$HOME/.brainlink/vault`.
 
 ```json
 {
@@ -739,11 +853,22 @@ Brainlink reads `brainlink.config.json` or `.brainlink.json` from the current wo
   "defaultContextTokens": 2000,
   "embeddingProvider": "local",
   "defaultSearchMode": "hybrid",
-  "chunkSize": 1200
+  "chunkSize": 1200,
+  "agentProfiles": {
+    "coding-agent": {
+      "defaultSearchMode": "semantic",
+      "defaultSearchLimit": 8,
+      "defaultContextTokens": 2400
+    },
+    "*": {
+      "defaultSearchMode": "hybrid"
+    }
+  }
 }
 ```
 
 `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.
 
 `autoIndexOnWrite` is optional and defaults to `true`. Set it to `false` to defer indexing after writes.
 

package/dist/application/add-note.js

@@ -1,30 +1,79 @@
+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';
 const slugify = (title) => title
     .normalize('NFKD')
     .replace(/[\u0300-\u036f]/g, '')
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, '-')
     .replace(/^-+|-+$/g, '');
-export const addNote = async (vaultPath, title, content, agentId = sharedAgentId, options = {}) => {
+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('"', '\\"')}"`,
+    `agent: "${agentId}"`,
+    `---`,
+    '',
+    `# ${title}`,
+    '',
+    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,
         content,
         allowSensitive: options.allowSensitive
     });
     const sanitizedAgentId = sanitizeAgentId(agentId);
+    const absoluteVaultPath = await ensureVault(vaultPath);
     const filename = `agents/${sanitizedAgentId}/${slugify(title) || 'untitled'}.md`;
-    const note = [
-        `---`,
-        `title: "${title.replaceAll('"', '\\"')}"`,
-        `agent: "${sanitizedAgentId}"`,
-        `---`,
-        '',
-        `# ${title}`,
-        '',
-        content.trim(),
-        ''
-    ].join('\n');
-    return writeMarkdownFile(vaultPath, filename, note);
+    const linkedContent = await ensureNonOrphanContent(vaultPath, absoluteVaultPath, title, content, sanitizedAgentId);
+    const note = buildNote(title, linkedContent.content, sanitizedAgentId);
+    const path = await writeMarkdownFile(vaultPath, filename, note);
+    return {
+        path,
+        autoLinked: linkedContent.autoLinked,
+        linkTarget: linkedContent.linkTarget
+    };
 };
+export const addNote = async (vaultPath, title, content, agentId = sharedAgentId, options = {}) => (await addNoteWithMetadata(vaultPath, title, content, agentId, options)).path;

package/dist/application/analyze-vault.js

@@ -1,10 +1,89 @@
+import { stat } from 'node:fs/promises';
+import { performance } from 'node:perf_hooks';
 import { validateGraph, getBrokenLinks, getOrphanNodes, getVaultStats } from '../domain/graph-analysis.js';
-import { ensureVault, readMarkdownFiles } from '../infrastructure/file-system-vault.js';
+import { ensureVault, listVaultFiles, readMarkdownFiles } from '../infrastructure/file-system-vault.js';
+import { resolveAgentRuntimeDefaults } from '../infrastructure/config.js';
 import { getGraph } from './get-graph.js';
+import { buildContextPackage } from './build-context.js';
+import { indexVault } from './index-vault.js';
+import { searchKnowledge } from './search-knowledge.js';
+import { loadBrainlinkConfig } from '../infrastructure/config.js';
 export const getStats = async (vaultPath, agentId) => getVaultStats(await getGraph(vaultPath, agentId));
 export const getBrokenLinksReport = async (vaultPath, agentId) => getBrokenLinks(await getGraph(vaultPath, agentId));
 export const getOrphansReport = async (vaultPath, agentId) => getOrphanNodes(await getGraph(vaultPath, agentId));
 export const validateVault = async (vaultPath, agentId) => validateGraph(await getGraph(vaultPath, agentId));
+const toRatio = (part, total) => total === 0 ? 0 : Number((part / total).toFixed(4));
+export const getExtendedStats = async (vaultPath, agentId) => {
+    const absoluteVaultPath = await ensureVault(vaultPath);
+    const graph = await getGraph(absoluteVaultPath, agentId);
+    const stats = getVaultStats(graph);
+    const markdownFiles = await readMarkdownFiles(absoluteVaultPath);
+    const allFiles = await listVaultFiles(absoluteVaultPath);
+    const totalBytes = (await Promise.all(allFiles.map(async (filePath) => {
+        try {
+            return (await stat(filePath)).size;
+        }
+        catch {
+            return 0;
+        }
+    }))).reduce((sum, value) => sum + value, 0);
+    const updatedAt = markdownFiles
+        .map((file) => file.updatedAt.getTime())
+        .filter((time) => Number.isFinite(time))
+        .sort((left, right) => left - right);
+    const priorities = graph.edges.reduce((state, edge) => ({
+        ...state,
+        [edge.priority]: state[edge.priority] + 1
+    }), {
+        low: 0,
+        normal: 0,
+        high: 0,
+        critical: 0
+    });
+    const config = await loadBrainlinkConfig();
+    const defaults = resolveAgentRuntimeDefaults(config, agentId);
+    const probeQuery = graph.nodes[0]?.title ?? 'architecture';
+    const indexStart = performance.now();
+    await indexVault(absoluteVaultPath);
+    const indexLatency = performance.now() - indexStart;
+    const searchStart = performance.now();
+    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');
+    const contextLatency = performance.now() - contextStart;
+    return {
+        stats,
+        storage: {
+            markdownFileCount: markdownFiles.length,
+            totalFileCount: allFiles.length,
+            totalBytes,
+            averageMarkdownBytes: markdownFiles.length === 0
+                ? 0
+                : Math.round(markdownFiles.reduce((sum, file) => sum + Buffer.byteLength(file.content, 'utf8'), 0) / markdownFiles.length),
+            ...(updatedAt.length > 0
+                ? {
+                    oldestNoteUpdatedAt: new Date(updatedAt[0]).toISOString(),
+                    newestNoteUpdatedAt: new Date(updatedAt[updatedAt.length - 1]).toISOString()
+                }
+                : {})
+        },
+        quality: {
+            resolvedLinkRatio: toRatio(stats.resolvedLinkCount, stats.linkCount),
+            brokenLinkRatio: toRatio(stats.brokenLinkCount, stats.linkCount),
+            orphanRatio: toRatio(stats.orphanCount, Math.max(stats.documentCount, 1)),
+            priorityDistribution: priorities
+        },
+        observability: {
+            probeQuery,
+            latenciesMs: {
+                index: Number(indexLatency.toFixed(2)),
+                search: Number(searchLatency.toFixed(2)),
+                context: Number(contextLatency.toFixed(2))
+            }
+        }
+    };
+};
 const createCheck = (name, ok, message) => ({
     name,
     ok,
@@ -21,8 +100,16 @@ export const doctorVault = async (vaultPath) => {
         createCheck('index', graph.nodes.length > 0, `${graph.nodes.length} indexed documents found`),
         createCheck('broken-links', validation.brokenLinks.length === 0, `${validation.brokenLinks.length} broken links found`)
     ];
+    const recommendations = files.length === 0 && graph.nodes.length === 0
+        ? [
+            `Vault is empty. Add your first note: blink add "Architecture" --vault "${absoluteVaultPath}" --content "Markdown source of truth. #architecture"`,
+            `If this path is not the expected vault, inspect active config: blink config where`,
+            `If you changed vault recently, migrate existing memory: blink migrate-vault --from ~/.brainlink/vault --to "${absoluteVaultPath}"`
+        ]
+        : [];
     return {
         ok: checks.every((check) => check.ok),
-        checks
+        checks,
+        ...(recommendations.length > 0 ? { recommendations } : {})
     };
 };

package/dist/application/migrate-vault.js

@@ -0,0 +1,91 @@
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, extname, isAbsolute, join, relative } from 'node:path';
+import { ensureVault, isBucketVaultPath, listVaultFiles, resolveVaultPath, writeMarkdownFile } from '../infrastructure/file-system-vault.js';
+const directoryMode = 0o700;
+const fileMode = 0o600;
+const isMarkdownPath = (path) => extname(path).toLowerCase() === '.md';
+const timestamp = () => new Date().toISOString().replace(/[-:]/g, '').replace(/\..+$/, 'Z');
+const isPathInside = (parent, child) => {
+    const path = relative(parent, child);
+    return path === '' || (!path.startsWith('..') && !isAbsolute(path));
+};
+const conflictPath = (targetPath) => {
+    const extension = extname(targetPath);
+    const base = extension ? targetPath.slice(0, -extension.length) : targetPath;
+    return `${base}.conflict-${timestamp()}${extension}`;
+};
+const writePreservedFile = async (absolutePath, content) => {
+    await mkdir(dirname(absolutePath), { recursive: true, mode: directoryMode });
+    await writeFile(absolutePath, content, { mode: fileMode });
+    await chmod(absolutePath, fileMode);
+};
+const writeMigratedFile = async (targetVault, targetRoot, absolutePath, content) => {
+    if (isBucketVaultPath(targetVault)) {
+        await writeMarkdownFile(targetVault, relative(targetRoot, absolutePath), content.toString('utf8'));
+        return;
+    }
+    await writePreservedFile(absolutePath, content);
+};
+export const planVaultMigration = async (source, target) => {
+    const sourceFiles = (await listVaultFiles(source)).filter(isMarkdownPath);
+    return sourceFiles.reduce(async (statePromise, sourceFile) => {
+        const state = await statePromise;
+        const targetFile = join(target, relative(source, sourceFile));
+        if (!isPathInside(target, targetFile)) {
+            return state;
+        }
+        const sourceContent = await readFile(sourceFile);
+        try {
+            const targetContent = await readFile(targetFile);
+            if (sourceContent.equals(targetContent)) {
+                return [...state, { kind: 'unchanged', sourcePath: sourceFile, targetPath: targetFile, sourceContent }];
+            }
+            return [...state, { kind: 'conflict', sourcePath: sourceFile, targetPath: conflictPath(targetFile), sourceContent }];
+        }
+        catch (error) {
+            if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT') {
+                throw error;
+            }
+            return [...state, { kind: 'copy', sourcePath: sourceFile, targetPath: targetFile, sourceContent }];
+        }
+    }, Promise.resolve([]));
+};
+export const previewVaultMigration = async (sourceVault, targetVault) => {
+    const source = await ensureVault(sourceVault);
+    const target = await ensureVault(targetVault);
+    if (source === target) {
+        return { source, target, copied: 0, unchanged: 0, conflicted: 0 };
+    }
+    const actions = await planVaultMigration(source, target);
+    const copied = actions.filter((action) => action.kind === 'copy').length;
+    const unchanged = actions.filter((action) => action.kind === 'unchanged').length;
+    const conflicted = actions.filter((action) => action.kind === 'conflict').length;
+    return { source, target, copied, unchanged, conflicted };
+};
+export const migrateVaultContent = async (sourceVault, targetVault) => {
+    const source = await ensureVault(sourceVault);
+    const target = await ensureVault(targetVault);
+    if (source === target) {
+        return { source, target, copied: 0, unchanged: 0, conflicted: 0 };
+    }
+    const actions = await planVaultMigration(source, target);
+    for (const action of actions) {
+        if (action.kind === 'unchanged') {
+            continue;
+        }
+        await writeMigratedFile(targetVault, target, action.targetPath, action.sourceContent);
+    }
+    const copied = actions.filter((action) => action.kind === 'copy').length;
+    const unchanged = actions.filter((action) => action.kind === 'unchanged').length;
+    const conflicted = actions.filter((action) => action.kind === 'conflict').length;
+    return { source, target, copied, unchanged, conflicted };
+};
+export const shouldMigrateDefaultVault = async (sourceVault, targetVault) => {
+    const source = resolveVaultPath(sourceVault);
+    const target = resolveVaultPath(targetVault);
+    if (source === target) {
+        return false;
+    }
+    const [sourceFiles, targetFiles] = await Promise.all([listVaultFiles(source), listVaultFiles(target)]);
+    return sourceFiles.filter(isMarkdownPath).length > 0 && targetFiles.filter(isMarkdownPath).length === 0;
+};

package/dist/application/search-knowledge.js

@@ -1,17 +1,72 @@
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
 import { ensureVault } from '../infrastructure/file-system-vault.js';
 import { openSqliteIndex } from '../infrastructure/sqlite-index.js';
 import { createEmbeddingProvider } from '../domain/embeddings.js';
 import { loadBrainlinkConfig, sanitizeSearchMode } from '../infrastructure/config.js';
+const hybridCacheTtlMs = 30_000;
+const hybridCacheMaxEntries = 200;
+const hybridSearchCache = new Map();
+const readIndexMtimeMs = async (vaultPath) => {
+    try {
+        return (await stat(join(vaultPath, '.brainlink', 'brainlink.db'))).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+};
+const toCacheKey = (vaultPath, query, limit, agentId) => JSON.stringify({
+    vaultPath,
+    query: query.trim().toLowerCase(),
+    limit,
+    agentId: agentId?.trim().toLowerCase() ?? '*'
+});
+const cacheGet = (key, indexMtimeMs) => {
+    const entry = hybridSearchCache.get(key);
+    if (!entry) {
+        return undefined;
+    }
+    const fresh = Date.now() - entry.createdAt <= hybridCacheTtlMs && entry.indexMtimeMs === indexMtimeMs;
+    if (!fresh) {
+        hybridSearchCache.delete(key);
+        return undefined;
+    }
+    return entry.results;
+};
+const cacheSet = (entry) => {
+    hybridSearchCache.set(entry.key, entry);
+    if (hybridSearchCache.size <= hybridCacheMaxEntries) {
+        return;
+    }
+    const overflow = hybridSearchCache.size - hybridCacheMaxEntries;
+    const keys = Array.from(hybridSearchCache.keys()).slice(0, overflow);
+    keys.forEach((key) => hybridSearchCache.delete(key));
+};
 export const searchKnowledge = async (vaultPath, query, limit, agentId, mode) => {
     const absoluteVaultPath = await ensureVault(vaultPath);
     const config = await loadBrainlinkConfig();
     const searchMode = sanitizeSearchMode(mode, config.defaultSearchMode);
+    const cacheKey = searchMode === 'hybrid' ? toCacheKey(absoluteVaultPath, query, limit, agentId) : undefined;
+    const indexMtimeMs = cacheKey ? await readIndexMtimeMs(absoluteVaultPath) : 0;
+    const cached = cacheKey ? cacheGet(cacheKey, indexMtimeMs) : undefined;
+    if (cached) {
+        return cached;
+    }
     const provider = createEmbeddingProvider(config.embeddingProvider);
     const shouldEmbedQuery = searchMode !== 'fts' && provider.name !== 'none';
     const queryEmbedding = shouldEmbedQuery ? (await provider.embed([query]))[0] ?? [] : [];
     const index = openSqliteIndex(absoluteVaultPath);
     try {
-        return index.search(query, limit, agentId, searchMode, queryEmbedding);
+        const results = index.search(query, limit, agentId, searchMode, queryEmbedding);
+        if (cacheKey) {
+            cacheSet({
+                key: cacheKey,
+                createdAt: Date.now(),
+                indexMtimeMs,
+                results
+            });
+        }
+        return results;
     }
     finally {
         index.close();