@andespindola/brainlink 1.0.7 → 1.1.0

package/dist/cli/commands/vault-sync-commands.js

@@ -0,0 +1,115 @@
+import { cloneVault, commitVault, initVaultGit, pullVault, pushVault, restoreVault, vaultGitStatus, vaultHistory } from '../../application/vault-git.js';
+import { exportVaultSnapshot, importVaultSnapshot } from '../../application/vault-snapshot.js';
+import { print, resolveOptions } from '../runtime.js';
+export const registerVaultSyncCommands = (program) => {
+    program
+        .command('vault-init-git')
+        .option('--vault <vault>', 'vault directory')
+        .option('--remote <url>', 'git remote URL (SSH or credential-helper backed; inline tokens are rejected)')
+        .option('--json', 'print machine-readable JSON')
+        .description('initialize git versioning for the vault (ignores the derived .brainlink/)')
+        .action(async (options) => {
+        const { vault } = await resolveOptions(options);
+        const result = await initVaultGit(vault, { remote: options.remote });
+        print(options.json, result, () => `${result.initialized ? 'Initialized' : 'Reused'} git repo at ${result.root}${options.remote ? ` (origin: ${options.remote})` : ''}.`);
+    });
+    program
+        .command('vault-commit')
+        .requiredOption('-m, --message <message>', 'commit message')
+        .option('--vault <vault>', 'vault directory')
+        .option('--json', 'print machine-readable JSON')
+        .description('commit the vault Markdown')
+        .action(async (options) => {
+        const { vault } = await resolveOptions(options);
+        const hash = await commitVault(vault, options.message ?? 'Update vault');
+        print(options.json, { committed: hash != null, hash }, () => hash ? `Committed ${hash.slice(0, 10)}.` : 'Nothing to commit.');
+    });
+    program
+        .command('vault-status')
+        .option('--vault <vault>', 'vault directory')
+        .option('--json', 'print machine-readable JSON')
+        .description('show git status of the vault Markdown')
+        .action(async (options) => {
+        const { vault } = await resolveOptions(options);
+        const status = await vaultGitStatus(vault);
+        print(options.json, status, () => `Branch ${status.branch}; ${status.dirty ? `${status.changedMarkdown.length} changed markdown file(s)` : 'clean'}.`);
+    });
+    program
+        .command('vault-history')
+        .option('--vault <vault>', 'vault directory')
+        .option('--limit <n>', 'number of entries', '20')
+        .option('--json', 'print machine-readable JSON')
+        .description('show vault commit history')
+        .action(async (options) => {
+        const { vault } = await resolveOptions(options);
+        const entries = await vaultHistory(vault, Number.parseInt(options.limit ?? '20', 10));
+        print(options.json, entries, () => entries.map((entry) => `${entry.hash.slice(0, 10)}  ${entry.date}  ${entry.subject}`).join('\n') || 'No history.');
+    });
+    program
+        .command('vault-push')
+        .option('--vault <vault>', 'vault directory')
+        .option('--json', 'print machine-readable JSON')
+        .description('push the vault to its git remote')
+        .action(async (options) => {
+        const { vault } = await resolveOptions(options);
+        await pushVault(vault);
+        print(options.json, { pushed: true }, () => 'Pushed to origin.');
+    });
+    program
+        .command('vault-pull')
+        .option('--vault <vault>', 'vault directory')
+        .option('--no-index', 'skip reindexing after pull')
+        .option('--json', 'print machine-readable JSON')
+        .description('pull the vault from git and reindex changed notes')
+        .action(async (options) => {
+        const { vault } = await resolveOptions(options);
+        const result = await pullVault(vault, { skipIndex: options.index === false });
+        print(options.json, result, () => `Pulled. ${result.changedMarkdown.length} markdown file(s) changed${result.index ? `; reindexed ${result.index.documentCount} docs` : ''}.`);
+    });
+    program
+        .command('vault-restore')
+        .argument('<ref>', 'git ref (commit, tag, branch) to restore Markdown from')
+        .option('--vault <vault>', 'vault directory')
+        .option('--no-index', 'skip reindexing after restore')
+        .option('--json', 'print machine-readable JSON')
+        .description('restore vault Markdown from a git ref and reindex')
+        .action(async (ref, options) => {
+        const { vault } = await resolveOptions(options);
+        const result = await restoreVault(vault, ref, { skipIndex: options.index === false });
+        print(options.json, result, () => `Restored from ${ref}. ${result.changedMarkdown.length} markdown file(s) changed${result.index ? `; reindexed ${result.index.documentCount} docs` : ''}.`);
+    });
+    program
+        .command('vault-clone')
+        .argument('<remote>', 'git remote URL')
+        .argument('<dir>', 'target directory')
+        .option('--no-index', 'skip building the index after clone')
+        .option('--json', 'print machine-readable JSON')
+        .description('clone a remote vault and build its index')
+        .action(async (remote, dir, options) => {
+        const result = await cloneVault(remote, dir, { skipIndex: options.index === false });
+        print(options.json, result, () => `Cloned to ${result.root}${result.index ? `; indexed ${result.index.documentCount} docs` : ''}.`);
+    });
+    program
+        .command('vault-export')
+        .requiredOption('-o, --output <file>', 'output .blvault file')
+        .option('--vault <vault>', 'vault directory')
+        .option('--json', 'print machine-readable JSON')
+        .description('export the vault Markdown to a portable .blvault snapshot')
+        .action(async (options) => {
+        const { vault } = await resolveOptions(options);
+        const result = await exportVaultSnapshot(vault, options.output ?? 'vault.blvault');
+        print(options.json, result, () => `Exported ${result.fileCount} files to ${result.file} (${result.bytes} bytes).`);
+    });
+    program
+        .command('vault-import')
+        .argument('<file>', 'input .blvault file')
+        .option('--vault <vault>', 'vault directory')
+        .option('--no-index', 'skip reindexing after import')
+        .option('--json', 'print machine-readable JSON')
+        .description('import a .blvault snapshot into the vault and reindex')
+        .action(async (file, options) => {
+        const { vault } = await resolveOptions(options);
+        const result = await importVaultSnapshot(file, vault, { skipIndex: options.index === false });
+        print(options.json, result, () => `Imported ${result.imported} files (${result.conflicted} conflicts)${result.index ? `; reindexed ${result.index.documentCount} docs` : ''}.`);
+    });
+};

package/dist/cli/main.js

@@ -10,6 +10,7 @@ import { registerConfigCommands } from './commands/config-commands.js';
 import { registerPracticalCommands } from './commands/practical-commands.js';
 import { registerReadCommands } from './commands/read-commands.js';
 import { registerVaultCommands } from './commands/vault-commands.js';
+import { registerVaultSyncCommands } from './commands/vault-sync-commands.js';
 import { registerWriteCommands } from './commands/write-commands.js';
 const readPackageMetadata = () => {
     const packagePath = join(dirname(fileURLToPath(import.meta.url)), '../../package.json');
@@ -63,6 +64,7 @@ registerReadCommands(program);
 registerPracticalCommands(program);
 registerConfigCommands(program);
 registerVaultCommands(program);
+registerVaultSyncCommands(program);
 registerAgentCommands(program);
 await maybePrintUpdateNotice(packageMetadata);
 program.parseAsync().catch((error) => {

package/dist/infrastructure/config.js

@@ -21,6 +21,7 @@ export const defaultBrainlinkConfig = {
     embedding: {},
     defaultSearchMode: 'hybrid',
     chunkSize: 1200,
+    storageBackend: 'json',
     searchPack: {
         rowChunkSize: 5_000,
         compressionLevel: 5,
@@ -47,6 +48,8 @@ const isRecord = (value) => typeof value === 'object' && value !== null && !Arra
 const embeddingProviders = new Set(['none', 'local', 'ollama', 'openai']);
 const searchModes = new Set(['fts', 'semantic', 'hybrid']);
 const contextStrategies = new Set(['rag', 'cag', 'auto']);
+const storageBackends = new Set(['json', 'binary', 'lmdb']);
+const sanitizeStorageBackend = (value) => typeof value === 'string' && storageBackends.has(value) ? value : defaultBrainlinkConfig.storageBackend;
 const sanitizeEmbeddingProvider = (value) => typeof value === 'string' && embeddingProviders.has(value) ? value : defaultBrainlinkConfig.embeddingProvider;
 const sanitizeOptionalString = (value) => typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
 const sanitizeEmbeddingConfig = (value) => {
@@ -220,6 +223,7 @@ const sanitizeConfig = (value) => ({
         : defaultBrainlinkConfig.defaultContextCacheTtlMs,
     allowedVaults: [...sanitizeAllowedVaults(value.allowedVaults), ...readAllowedVaultsFromEnv()],
     chunkSize: typeof value.chunkSize === 'number' && value.chunkSize > 0 ? value.chunkSize : defaultBrainlinkConfig.chunkSize,
+    storageBackend: sanitizeStorageBackend(value.storageBackend),
     searchPack: sanitizeSearchPackConfig(value.searchPack),
     embeddingProvider: sanitizeEmbeddingProvider(value.embeddingProvider),
     embedding: sanitizeEmbeddingConfig(value.embedding),

package/dist/infrastructure/file-index.js

@@ -1,18 +1,8 @@
 import { mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-import { createEmbeddingBuckets, dotProduct } from '../domain/embeddings.js';
-import { bm25TermScore, minMaxNormalize } from '../domain/scoring.js';
-import { selectSemanticCandidates } from './semantic-prefilter.js';
-const queryTokenPattern = /[\p{L}\p{N}_-]+/gu;
+import { createStoredIndexQueries, emptyIndex, toStoredIndex } from './knowledge-store/stored-index.js';
 const indexCacheMaxEntries = 16;
 const indexCache = new Map();
-const emptyIndex = () => ({
-    version: 1,
-    updatedAt: new Date().toISOString(),
-    documents: [],
-    chunks: [],
-    links: []
-});
 // Raised when index.json exists but cannot be parsed. Search treats it as a
 // signal to fall back to the independent compressed search packs instead of
 // silently returning an empty result set.
@@ -54,6 +44,11 @@ const quarantineCorruptIndex = async (path, cause) => {
         }
     }
 };
+// Exposed so the binary backend can serve reads from a legacy index.json until
+// the next index run materializes the binary store (seamless migration).
+export function readJsonStoredIndex(vaultPath, strict = false) {
+    return readIndex(vaultPath, strict);
+}
 const readIndex = async (vaultPath, strict = false) => {
     const path = indexStoragePath(vaultPath);
     let stats = null;
@@ -126,403 +121,21 @@ const writeIndex = async (vaultPath, index) => {
         index
     });
 };
-const normalizeToken = (value) => value
-    .normalize('NFKD')
-    .replace(/\p{Diacritic}/gu, '')
-    .toLowerCase();
-const tokenize = (query) => query
-    .match(queryTokenPattern)
-    ?.map(normalizeToken)
-    .filter((token) => token.length > 1) ?? [];
-const countOccurrences = (text, token) => {
-    let hits = 0;
-    let cursor = 0;
-    while (cursor < text.length) {
-        const index = text.indexOf(token, cursor);
-        if (index < 0) {
-            break;
-        }
-        hits += 1;
-        cursor = index + token.length;
+// JSON file backend: the original single `index.json` store. Loading/persisting
+// is its own concern; the graph/search/link reads come from the shared query
+// core so this backend stays behavior-identical to the binary backend.
+export const openFileIndex = (vaultPath) => ({
+    reset: async () => {
+        await writeIndex(vaultPath, emptyIndex());
+    },
+    saveDocuments: async (documents) => {
+        await writeIndex(vaultPath, toStoredIndex(documents));
+    },
+    ...createStoredIndexQueries({
+        load: () => readIndex(vaultPath),
+        loadStrict: () => readIndex(vaultPath, true)
+    }),
+    close: () => {
+        // File-based index has no persistent connection.
     }
-    return hits;
-};
-const titleFieldWeight = 5;
-const tagFieldWeight = 4;
-const pathFieldWeight = 2;
-const contentHitCap = 6;
-const hybridTextWeight = 0.6;
-const hybridSemanticWeight = 0.4;
-const normalizeFields = (row) => ({
-    title: normalizeToken(row.title),
-    path: normalizeToken(row.path),
-    content: normalizeToken(row.content),
-    tags: normalizeToken(row.tags.join(' '))
 });
-// Field-weighted term frequency: title/tag/path matches count more than body
-// matches, and body hits saturate at a cap so a term repeated many times in one
-// chunk cannot dominate. This weighted frequency feeds BM25 below.
-const weightedTermFrequency = (fields, token) => {
-    const titleHits = countOccurrences(fields.title, token);
-    const tagHits = countOccurrences(fields.tags, token);
-    const pathHits = countOccurrences(fields.path, token);
-    const contentHits = countOccurrences(fields.content, token);
-    return (titleHits * titleFieldWeight +
-        tagHits * tagFieldWeight +
-        pathHits * pathFieldWeight +
-        Math.min(contentHits, contentHitCap));
-};
-// Naive additive field score retained for graph-node title/path lookup, where
-// the candidate set is documents (not chunks) and corpus-wide BM25 statistics
-// add no signal over a direct weighted hit count.
-const lexicalFieldScore = (row, tokens) => {
-    if (tokens.length === 0) {
-        return 0;
-    }
-    const fields = normalizeFields(row);
-    return tokens.reduce((score, token) => score + weightedTermFrequency(fields, token), 0);
-};
-// A single chunk with a non-finite cached tokenCount (legacy index, partial
-// write, manual edit) would otherwise poison the shared averageLength and zero
-// out lexical scoring for the whole corpus, so coerce to a safe positive length.
-const safeDocumentLength = (tokenCount) => Number.isFinite(tokenCount) && tokenCount > 0 ? tokenCount : 1;
-const buildCorpusStatistics = (prepared, tokens) => {
-    const documentCount = prepared.length;
-    const totalLength = prepared.reduce((sum, entry) => sum + safeDocumentLength(entry.row.tokenCount), 0);
-    const documentFrequencyByTerm = new Map();
-    for (const term of tokens) {
-        let documentFrequency = 0;
-        for (const entry of prepared) {
-            if ((entry.weightedTermFrequencies.get(term) ?? 0) > 0) {
-                documentFrequency += 1;
-            }
-        }
-        documentFrequencyByTerm.set(term, documentFrequency);
-    }
-    return {
-        documentCount,
-        averageLength: documentCount > 0 ? totalLength / documentCount : 0,
-        documentFrequencyByTerm
-    };
-};
-const bm25TextScore = (entry, tokens, stats) => tokens.reduce((score, term) => score +
-    bm25TermScore({
-        termFrequency: entry.weightedTermFrequencies.get(term) ?? 0,
-        documentLength: safeDocumentLength(entry.row.tokenCount),
-        documentCount: stats.documentCount,
-        documentFrequency: stats.documentFrequencyByTerm.get(term) ?? 0,
-        averageLength: stats.averageLength
-    }), 0);
-const semanticScore = (row, queryEmbedding) => queryEmbedding.length > 0 && row.embedding.length > 0 ? dotProduct(queryEmbedding, row.embedding) : 0;
-const rangeOf = (values) => values.reduce((range, value) => ({ min: Math.min(range.min, value), max: Math.max(range.max, value) }), { min: Infinity, max: -Infinity });
-const toResult = (row, mode, score, text, semantic) => ({
-    documentId: row.documentId,
-    agentId: row.agentId,
-    title: row.title,
-    path: row.path,
-    chunkId: row.chunkId,
-    chunkOrdinal: row.chunkOrdinal,
-    content: row.content,
-    score,
-    textScore: text,
-    semanticScore: semantic,
-    tokenCount: row.tokenCount,
-    searchMode: mode,
-    tags: row.tags
-});
-const toGraphLink = (link, documentsById) => {
-    const source = documentsById.get(link.fromDocumentId);
-    const target = link.toDocumentId ? documentsById.get(link.toDocumentId) : undefined;
-    return {
-        agentId: source?.agentId ?? 'shared',
-        fromTitle: source?.title ?? 'Unknown',
-        fromPath: source?.path ?? 'Unknown',
-        toTitle: target?.title ?? link.toTitle,
-        toPath: target?.path ?? null,
-        weight: link.weight,
-        priority: link.priority
-    };
-};
-export const openFileIndex = (vaultPath) => {
-    const load = async () => readIndex(vaultPath);
-    const persist = async (index) => writeIndex(vaultPath, index);
-    return {
-        reset: async () => {
-            await persist(emptyIndex());
-        },
-        saveDocuments: async (documents) => {
-            const chunks = documents.flatMap((document) => document.chunks);
-            const links = documents.flatMap((document) => document.links);
-            await persist({
-                version: 1,
-                updatedAt: new Date().toISOString(),
-                documents: documents.map((document) => document.document),
-                chunks,
-                links
-            });
-        },
-        getIndexedDocuments: async (agentId) => {
-            const index = await load();
-            const documents = agentId ? index.documents.filter((document) => document.agentId === agentId) : index.documents;
-            const selectedDocumentIds = new Set(documents.map((document) => document.id));
-            const chunksByDocumentId = index.chunks.reduce((state, chunk) => {
-                if (!selectedDocumentIds.has(chunk.documentId)) {
-                    return state;
-                }
-                const current = state.get(chunk.documentId) ?? [];
-                current.push(chunk);
-                state.set(chunk.documentId, current);
-                return state;
-            }, new Map());
-            const linksByDocumentId = index.links.reduce((state, link) => {
-                if (!selectedDocumentIds.has(link.fromDocumentId)) {
-                    return state;
-                }
-                const current = state.get(link.fromDocumentId) ?? [];
-                current.push(link);
-                state.set(link.fromDocumentId, current);
-                return state;
-            }, new Map());
-            return documents
-                .map((document) => ({
-                document,
-                chunks: [...(chunksByDocumentId.get(document.id) ?? [])].sort((left, right) => left.ordinal - right.ordinal),
-                links: linksByDocumentId.get(document.id) ?? []
-            }))
-                .sort((left, right) => left.document.path.localeCompare(right.document.path));
-        },
-        search: async (query, limit, agentId, mode = 'hybrid', queryEmbedding = []) => {
-            // Strict load: a corrupt index throws so the caller can fall back to the
-            // independent search packs rather than reporting "no results".
-            const index = await readIndex(vaultPath, true);
-            const documentsById = new Map(index.documents.map((document) => [document.id, document]));
-            const rows = index.chunks.flatMap((chunk) => {
-                const document = documentsById.get(chunk.documentId);
-                if (!document) {
-                    return [];
-                }
-                if (agentId && document.agentId !== agentId) {
-                    return [];
-                }
-                return [
-                    {
-                        documentId: document.id,
-                        agentId: document.agentId,
-                        title: document.title,
-                        path: document.path,
-                        chunkId: chunk.id,
-                        chunkOrdinal: chunk.ordinal,
-                        content: chunk.content,
-                        tokenCount: chunk.tokenCount,
-                        tags: document.tags,
-                        embedding: chunk.embedding,
-                        buckets: chunk.buckets
-                    }
-                ];
-            });
-            const tokens = tokenize(query);
-            // Pure-semantic scoring on a large vault can skip chunks that share no
-            // embedding bucket with the query. Hybrid/fts keep every row so lexical
-            // matches are never dropped; the prefilter also falls back to a full scan
-            // on small or partially-indexed vaults.
-            const candidates = mode === 'semantic' && queryEmbedding.length > 0
-                ? selectSemanticCandidates(rows, createEmbeddingBuckets(queryEmbedding), limit)
-                : rows;
-            // Pass 1: field-weighted term frequencies per candidate, then corpus-wide
-            // statistics (document frequency, average length) needed for BM25 IDF and
-            // length normalization.
-            const prepared = candidates.map((row) => {
-                const fields = normalizeFields(row);
-                const weightedTermFrequencies = new Map();
-                for (const term of tokens) {
-                    const frequency = weightedTermFrequency(fields, term);
-                    if (frequency > 0) {
-                        weightedTermFrequencies.set(term, frequency);
-                    }
-                }
-                return { row, weightedTermFrequencies };
-            });
-            const stats = buildCorpusStatistics(prepared, tokens);
-            // Pass 2: raw lexical (BM25) and semantic (cosine) component scores.
-            const componentScored = prepared.map((entry) => ({
-                row: entry.row,
-                text: tokens.length > 0 ? bm25TextScore(entry, tokens, stats) : 0,
-                semantic: semanticScore(entry.row, queryEmbedding)
-            }));
-            // Filter on raw relevance before normalization so a legitimate match that
-            // happens to be the weakest in its mode is never min-max scaled to zero
-            // and dropped. fts stays lexical-only and semantic stays vector-only.
-            const relevant = componentScored.filter((entry) => {
-                if (tokens.length === 0) {
-                    return true;
-                }
-                if (mode === 'fts') {
-                    return entry.text > 0;
-                }
-                if (mode === 'semantic') {
-                    return entry.semantic > 0;
-                }
-                return entry.text > 0 || entry.semantic > 0;
-            });
-            if (relevant.length === 0) {
-                return [];
-            }
-            const textRange = rangeOf(relevant.map((entry) => entry.text));
-            const semanticRange = rangeOf(relevant.map((entry) => entry.semantic));
-            const finalScore = (entry) => {
-                if (mode === 'fts') {
-                    return entry.text;
-                }
-                if (mode === 'semantic') {
-                    return entry.semantic;
-                }
-                // Hybrid mixes the two components on a shared [0, 1] scale so neither the
-                // unbounded BM25 magnitude nor the bounded cosine value can swamp the
-                // other, replacing the previous fixed `text + semantic * 8` blend.
-                const textNorm = minMaxNormalize(entry.text, textRange.min, textRange.max);
-                const semanticNorm = minMaxNormalize(entry.semantic, semanticRange.min, semanticRange.max);
-                return textNorm * hybridTextWeight + semanticNorm * hybridSemanticWeight;
-            };
-            return relevant
-                .map((entry) => toResult(entry.row, mode, finalScore(entry), entry.text, entry.semantic))
-                .sort((left, right) => right.score - left.score || left.title.localeCompare(right.title))
-                .slice(0, Math.max(0, limit));
-        },
-        listLinks: async (agentId) => {
-            const index = await load();
-            const documentsById = new Map(index.documents.map((document) => [document.id, document]));
-            return index.links
-                .filter((link) => {
-                const source = documentsById.get(link.fromDocumentId);
-                return agentId ? source?.agentId === agentId : true;
-            })
-                .map((link) => toGraphLink(link, documentsById))
-                .sort((left, right) => left.fromTitle.localeCompare(right.fromTitle));
-        },
-        listBacklinks: async (title, agentId) => {
-            const index = await load();
-            const titleKey = title.toLowerCase();
-            const documentsById = new Map(index.documents.map((document) => [document.id, document]));
-            return index.links
-                .filter((link) => link.toTitle.toLowerCase() === titleKey)
-                .filter((link) => {
-                const source = documentsById.get(link.fromDocumentId);
-                return agentId ? source?.agentId === agentId : true;
-            })
-                .map((link) => toGraphLink(link, documentsById))
-                .sort((left, right) => right.weight - left.weight || left.fromTitle.localeCompare(right.fromTitle));
-        },
-        getGraph: async (agentId) => {
-            const index = await load();
-            const documents = agentId ? index.documents.filter((document) => document.agentId === agentId) : index.documents;
-            const documentIds = new Set(documents.map((document) => document.id));
-            const edges = index.links
-                .filter((link) => documentIds.has(link.fromDocumentId))
-                .map((link) => ({
-                source: link.fromDocumentId,
-                target: link.toDocumentId,
-                targetTitle: link.toTitle,
-                weight: link.weight,
-                priority: link.priority
-            }));
-            return {
-                nodes: documents.map((document) => ({
-                    id: document.id,
-                    agentId: document.agentId,
-                    title: document.title,
-                    path: document.path,
-                    content: document.content,
-                    tags: document.tags,
-                    contextLinks: document.contextLinks ?? []
-                })),
-                edges
-            };
-        },
-        getGraphSummary: async (agentId) => {
-            const graph = await (async () => {
-                const index = await load();
-                const documents = agentId ? index.documents.filter((document) => document.agentId === agentId) : index.documents;
-                const documentIds = new Set(documents.map((document) => document.id));
-                const edges = index.links
-                    .filter((link) => documentIds.has(link.fromDocumentId))
-                    .map((link) => ({
-                    source: link.fromDocumentId,
-                    target: link.toDocumentId,
-                    targetTitle: link.toTitle,
-                    weight: link.weight,
-                    priority: link.priority
-                }));
-                return {
-                    nodes: documents.map((document) => ({
-                        id: document.id,
-                        agentId: document.agentId,
-                        title: document.title,
-                        path: document.path,
-                        content: '',
-                        tags: document.tags,
-                        contextLinks: document.contextLinks ?? []
-                    })),
-                    edges
-                };
-            })();
-            return graph;
-        },
-        getGraphNode: async (id, agentId) => {
-            const index = await load();
-            const document = index.documents.find((row) => row.id === id && (!agentId || row.agentId === agentId));
-            return document
-                ? {
-                    id: document.id,
-                    agentId: document.agentId,
-                    title: document.title,
-                    path: document.path,
-                    content: document.content,
-                    tags: document.tags,
-                    contextLinks: document.contextLinks ?? []
-                }
-                : undefined;
-        },
-        searchGraphNodeIds: async (query, limit, agentId) => {
-            const index = await load();
-            const normalized = normalizeToken(query);
-            if (normalized.length === 0 || limit <= 0) {
-                return [];
-            }
-            const tokens = tokenize(query);
-            const scored = index.documents
-                .filter((document) => (!agentId || document.agentId === agentId))
-                .map((document) => {
-                const score = lexicalFieldScore({
-                    documentId: document.id,
-                    agentId: document.agentId,
-                    title: document.title,
-                    path: document.path,
-                    chunkId: document.id,
-                    chunkOrdinal: 0,
-                    content: document.content,
-                    tokenCount: 0,
-                    tags: document.tags,
-                    embedding: []
-                }, tokens);
-                return { id: document.id, score };
-            })
-                .filter((row) => row.score > 0)
-                .sort((left, right) => right.score - left.score || left.id.localeCompare(right.id))
-                .slice(0, limit);
-            return scored.map((row) => row.id);
-        },
-        listAgents: async () => {
-            const index = await load();
-            const counts = index.documents.reduce((state, document) => {
-                state.set(document.agentId, (state.get(document.agentId) ?? 0) + 1);
-                return state;
-            }, new Map());
-            return Array.from(counts.entries())
-                .sort((left, right) => left[0].localeCompare(right[0]))
-                .map(([id, documentCount]) => ({ id, documentCount }));
-        },
-        close: () => {
-            // File-based index has no persistent connection.
-        }
-    };
-};