memgrid 0.5.0

package/dist/memgrid.d.ts

@@ -0,0 +1,50 @@
+import type { MemoryUnit, ScanOptions, SearchOptions, SearchResult, SyncOptions, SyncResult } from './shared/types.js';
+import { FileStore } from './store/file-store.js';
+import { type Scanner } from './scanner/index.js';
+import { RetrieveEngine } from './retrieve/index.js';
+import { SemanticRetriever, type EmbeddingProvider } from './retrieve/semantic.js';
+import { LearnEngine, type TaskResult, type LearningSuggestions } from './learn/index.js';
+import { SyncEngine } from './sync/index.js';
+export declare class MemGrid {
+    store: FileStore;
+    scanner: Scanner;
+    retrieve: RetrieveEngine;
+    semantic: SemanticRetriever;
+    learn: LearnEngine;
+    syncEngine: SyncEngine;
+    projectRoot: string;
+    constructor(projectRoot: string, provider?: EmbeddingProvider, scanner?: Scanner);
+    init(options: ScanOptions): Promise<MemoryUnit[]>;
+    /**
+     * Generate and persist fileSnapshot for all scanned files.
+     * Done once on init; sync() diffs against this baseline.
+     */
+    private saveFileSnapshot;
+    search(query: string, options?: SearchOptions): Promise<SearchResult>;
+    add(unit: Partial<MemoryUnit> & {
+        id: string;
+        type: MemoryUnit['type'];
+        summary: string;
+        content: MemoryUnit['content'];
+    }): Promise<MemoryUnit>;
+    update(id: string, patch: Partial<MemoryUnit>): Promise<MemoryUnit | null>;
+    archive(id: string): Promise<void>;
+    context(result: SearchResult): string;
+    analyzeTask(task: TaskResult): Promise<LearningSuggestions>;
+    applySuggestions(suggestions: LearningSuggestions): Promise<string[]>;
+    formatSuggestions(suggestions: LearningSuggestions): string;
+    /**
+     * Incremental sync — re-scan only changed files and repair associations.
+     * Much faster than full init() when only a few files changed.
+     */
+    sync(options: SyncOptions): Promise<SyncResult>;
+    stats(): Promise<{
+        lastScanAt: string | null;
+        version: string;
+        totalUnits: number;
+        activeUnits: number;
+        archivedUnits: number;
+        typeDistribution: Record<string, number>;
+    }>;
+}
+//# sourceMappingURL=memgrid.d.ts.map

package/dist/memgrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memgrid.d.ts","sourceRoot":"","sources":["../src/memgrid.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAgB,MAAM,mBAAmB,CAAC;AACrI,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAKL,KAAK,OAAO,EACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAA4B,MAAM,wBAAwB,CAAC;AAC7G,OAAO,EAAE,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC1F,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,qBAAa,OAAO;IAClB,KAAK,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,cAAc,CAAC;IACzB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,KAAK,EAAE,WAAW,CAAC;IACnB,UAAU,EAAE,UAAU,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;gBAER,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,OAAO;IAW1E,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAiCvD;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAmDlB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IASrE,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC;IAmB/I,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAW1E,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM;IAI/B,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAI3D,gBAAgB,CAAC,WAAW,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAI3E,iBAAiB,CAAC,WAAW,EAAE,mBAAmB,GAAG,MAAM;IAI3D;;;OAGG;IACG,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAI/C,KAAK;;;;;;;;CAUZ"}

package/dist/memgrid.js

@@ -0,0 +1,175 @@
+import * as fs from 'fs';
+import * as crypto from 'crypto';
+import * as path from 'path';
+import { FileStore } from './store/file-store.js';
+import { TypeScriptScanner, RulesScanner, ConfigScanner, MarkdownScanner, } from './scanner/index.js';
+import { RetrieveEngine } from './retrieve/index.js';
+import { SemanticRetriever, KeywordEmbeddingProvider } from './retrieve/semantic.js';
+import { LearnEngine } from './learn/index.js';
+import { SyncEngine } from './sync/index.js';
+export class MemGrid {
+    store;
+    scanner;
+    retrieve;
+    semantic;
+    learn;
+    syncEngine;
+    projectRoot;
+    constructor(projectRoot, provider, scanner) {
+        this.projectRoot = projectRoot;
+        this.store = new FileStore(projectRoot);
+        // Accept optional scanner injection, default to TypeScript
+        this.scanner = scanner ?? new TypeScriptScanner(this.store, projectRoot);
+        this.retrieve = new RetrieveEngine(this.store);
+        this.semantic = new SemanticRetriever(this.store, provider || new KeywordEmbeddingProvider());
+        this.learn = new LearnEngine(this.store);
+        this.syncEngine = new SyncEngine(this.store, this.scanner, projectRoot);
+    }
+    async init(options) {
+        // Load existing cache first (if any)
+        this.store.load();
+        // Run language scanner
+        const units = await this.scanner.scan(options);
+        // Run universal scanners (rules, config, markdown) in parallel
+        const universalScans = [];
+        if (options.includeRules) {
+            const rulesScanner = new RulesScanner(this.projectRoot);
+            if (rulesScanner.detect(this.projectRoot))
+                universalScans.push(rulesScanner.scan(options));
+        }
+        universalScans.push(new ConfigScanner(this.projectRoot).scan(options));
+        const mdScanner = new MarkdownScanner(this.projectRoot);
+        if (mdScanner.detect(this.projectRoot))
+            universalScans.push(mdScanner.scan(options));
+        const universalResults = await Promise.all(universalScans);
+        for (const result of universalResults) {
+            // Save universal scanner units (language scanner saves its own)
+            for (const unit of result) {
+                this.store.saveUnit(unit);
+                units.push(unit);
+            }
+        }
+        // Build semantic index after scan
+        await this.semantic.buildIndex();
+        // Record file snapshot for future incremental syncs
+        this.saveFileSnapshot(options);
+        return units;
+    }
+    /**
+     * Generate and persist fileSnapshot for all scanned files.
+     * Done once on init; sync() diffs against this baseline.
+     */
+    saveFileSnapshot(options) {
+        const snapshot = {};
+        const sourceExts = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.py', '.go', '.rs', '.md']);
+        const testPatterns = ['.spec.', '.test.', '_test.'];
+        const collectHashes = (dir) => {
+            if (!fs.existsSync(dir))
+                return;
+            for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                const abs = path.join(dir, entry.name);
+                const rel = path.relative(this.projectRoot, abs);
+                if (entry.isDirectory()) {
+                    const skipDirs = new Set(['node_modules', 'dist', '.next', 'vendor', 'target', '__pycache__']);
+                    if (!skipDirs.has(entry.name) && !entry.name.startsWith('.')) {
+                        collectHashes(abs);
+                    }
+                }
+                else {
+                    const ext = path.extname(entry.name);
+                    if (sourceExts.has(ext)) {
+                        // Skip test files
+                        if (testPatterns.some((p) => entry.name.includes(p)))
+                            continue;
+                        snapshot[rel] = crypto.createHash('sha256').update(fs.readFileSync(abs, 'utf-8')).digest('hex');
+                    }
+                }
+            }
+        };
+        // Scan source dirs
+        ['apps', 'packages', 'src', 'lib', 'cmd', 'internal', 'pkg', 'app'].forEach((d) => collectHashes(path.join(this.projectRoot, d)));
+        // Rules and examples
+        if (options.includeRules)
+            collectHashes(path.join(this.projectRoot, '.claude', 'rules'));
+        if (options.includeExamples)
+            collectHashes(path.join(this.projectRoot, '.claude', 'examples'));
+        // Config files
+        for (const f of ['package.json', 'pyproject.toml', 'go.mod', 'Cargo.toml', 'docker-compose.yml']) {
+            const abs = path.join(this.projectRoot, f);
+            if (fs.existsSync(abs)) {
+                snapshot[f] = crypto.createHash('sha256').update(fs.readFileSync(abs, 'utf-8')).digest('hex');
+            }
+        }
+        const grid = this.store.getGrid();
+        if (grid) {
+            grid.fileSnapshot = snapshot;
+            this.store.saveGrid(grid);
+        }
+    }
+    async search(query, options) {
+        const result = await this.semantic.search(query, options);
+        // Touch usage counts for retrieved units (in-memory, periodically flushed)
+        for (const unit of result.units) {
+            this.store.touch(unit.id);
+        }
+        return result;
+    }
+    async add(unit) {
+        const fullUnit = {
+            ...unit,
+            signatures: unit.signatures || [],
+            associations: unit.associations || [],
+            meta: {
+                created: new Date().toISOString(),
+                updated: new Date().toISOString(),
+                confidence: unit.meta?.confidence ?? 0.7,
+                usage_count: 0,
+                status: 'active',
+            },
+        };
+        this.store.ensureDirs();
+        this.store.saveUnit(fullUnit);
+        return fullUnit;
+    }
+    async update(id, patch) {
+        const unit = this.store.getUnit(id);
+        if (!unit)
+            return null;
+        Object.assign(unit, patch);
+        unit.meta.updated = new Date().toISOString();
+        this.store.saveUnit(unit);
+        return unit;
+    }
+    async archive(id) {
+        this.store.archiveUnit(id);
+    }
+    context(result) {
+        return this.semantic.toContext(result);
+    }
+    async analyzeTask(task) {
+        return await this.learn.analyze(task);
+    }
+    async applySuggestions(suggestions) {
+        return await this.learn.apply(suggestions);
+    }
+    formatSuggestions(suggestions) {
+        return this.learn.formatSuggestions(suggestions);
+    }
+    /**
+     * Incremental sync — re-scan only changed files and repair associations.
+     * Much faster than full init() when only a few files changed.
+     */
+    async sync(options) {
+        return this.syncEngine.sync(options);
+    }
+    async stats() {
+        const cached = this.store.getStats();
+        const grid = this.store.getGrid();
+        return {
+            ...cached,
+            lastScanAt: grid?.lastScanAt || null,
+            version: grid?.version || '0.1.0',
+        };
+    }
+}
+//# sourceMappingURL=memgrid.js.map

package/dist/memgrid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memgrid.js","sourceRoot":"","sources":["../src/memgrid.ts"],"names":[],"mappings":"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"}

package/dist/retrieve/index.d.ts

@@ -0,0 +1,27 @@
+import type { MemoryUnit, SearchResult } from '../shared/types.js';
+import type { FileStore } from '../store/file-store.js';
+export declare class RetrieveEngine {
+    private store;
+    private index;
+    private indexBuilt;
+    private unitVersion;
+    private resultCache;
+    constructor(store: FileStore);
+    /**
+     * Build MiniSearch index once. Call after init or when units change.
+     */
+    ensureIndex(): void;
+    /**
+     * Incremental index update — call when a single unit is added/updated.
+     */
+    updateIndex(unit: MemoryUnit): void;
+    invalidateIndex(): void;
+    search(query: string, maxResults?: number, maxHops?: number): Promise<SearchResult>;
+    private computeAssociationBonus;
+    /**
+     * Get units from store's in-memory cache (no disk I/O).
+     */
+    private getCachedUnits;
+    toContext(result: SearchResult): string;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/retrieve/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/retrieve/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAe,MAAM,oBAAoB,CAAC;AAChF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAoBxD,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAY;IACzB,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,WAAW,CAAK;IAGxB,OAAO,CAAC,WAAW,CAA2C;gBAElD,KAAK,EAAE,SAAS;IAI5B;;OAEG;IACH,WAAW,IAAI,IAAI;IA+BnB;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAcnC,eAAe,IAAI,IAAI;IAMjB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,SAAK,EAAE,OAAO,SAAI,GAAG,OAAO,CAAC,YAAY,CAAC;IAkFhF,OAAO,CAAC,uBAAuB;IAe/B;;OAEG;IACH,OAAO,CAAC,cAAc;IAatB,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM;CAoCxC"}

package/dist/retrieve/index.js

@@ -0,0 +1,209 @@
+import MiniSearch from 'minisearch';
+/**
+ * Simple LRU cache for search results.
+ */
+class LRUCache {
+    max;
+    map = new Map();
+    constructor(max = 200) {
+        this.max = max;
+    }
+    get(key) { return this.map.get(key); }
+    set(key, value) {
+        if (this.map.size >= this.max) {
+            const first = this.map.keys().next().value;
+            this.map.delete(first);
+        }
+        this.map.set(key, value);
+    }
+    clear() { this.map.clear(); }
+}
+export class RetrieveEngine {
+    store;
+    index = null;
+    indexBuilt = false;
+    unitVersion = 0; // Incremented on add/update/archive — invalidates index
+    // LRU cache: query hash → SearchResult
+    resultCache = new LRUCache(200);
+    constructor(store) {
+        this.store = store;
+    }
+    /**
+     * Build MiniSearch index once. Call after init or when units change.
+     */
+    ensureIndex() {
+        if (this.index && this.indexBuilt)
+            return;
+        this.index = new MiniSearch({
+            fields: ['summary', 'signatures', 'content.description', 'content.trigger', 'content.action'],
+            storeFields: ['id'],
+            searchOptions: {
+                boost: { summary: 5, signatures: 3 },
+                prefix: true,
+                fuzzy: 0.2,
+            },
+        });
+        // Load from cache (already in memory)
+        const units = this.getCachedUnits();
+        if (units.length > 0) {
+            this.index.addAll(units.map((u) => ({
+                id: u.id,
+                summary: u.summary,
+                signatures: u.signatures.join(' '),
+                'content.description': u.content.description,
+                'content.trigger': u.content.trigger || '',
+                'content.action': u.content.action || '',
+            })));
+        }
+        this.indexBuilt = true;
+    }
+    /**
+     * Incremental index update — call when a single unit is added/updated.
+     */
+    updateIndex(unit) {
+        if (!this.index)
+            return;
+        this.index.remove(unit.id);
+        this.index.add({
+            id: unit.id,
+            summary: unit.summary,
+            signatures: unit.signatures.join(' '),
+            'content.description': unit.content.description,
+            'content.trigger': unit.content.trigger || '',
+            'content.action': unit.content.action || '',
+        });
+        this.resultCache.clear(); // Invalidate cache on any change
+    }
+    invalidateIndex() {
+        this.index = null;
+        this.indexBuilt = false;
+        this.resultCache.clear();
+    }
+    async search(query, maxResults = 10, maxHops = 2) {
+        const startTime = Date.now();
+        // Check result cache first (exact query match)
+        const cacheKey = `${query}::${maxResults}::${maxHops}`;
+        const cached = this.resultCache.get(cacheKey);
+        if (cached) {
+            return { ...cached, elapsedMs: Date.now() - startTime };
+        }
+        // Ensure index is built
+        this.ensureIndex();
+        if (!this.index) {
+            return { query, units: [], totalHops: 0, elapsedMs: Date.now() - startTime };
+        }
+        // Step 1: Keyword search (reused index — no rebuild!)
+        const results = this.index.search(query, { prefix: true, fuzzy: 0.2 });
+        const keywordUnitIds = new Map();
+        for (const r of results) {
+            keywordUnitIds.set(r.id, r.score);
+        }
+        // Step 2: Traverse associations (BFS)
+        const visited = new Set();
+        const queue = [];
+        for (const [id] of keywordUnitIds) {
+            visited.add(id);
+            queue.push({ id, hop: 0 });
+        }
+        const grid = this.store.getGrid();
+        const edgeIndex = grid?.edgeIndex ?? {};
+        while (queue.length > 0) {
+            const current = queue.shift();
+            if (current.hop >= maxHops)
+                continue;
+            const edges = edgeIndex[current.id] || [];
+            for (const edge of edges) {
+                if (!visited.has(edge.to)) {
+                    visited.add(edge.to);
+                    queue.push({ id: edge.to, hop: current.hop + 1 });
+                }
+            }
+        }
+        // Step 3: Collect and rank (from cache, O(1) lookups)
+        const matchedUnits = [];
+        const allUnits = this.getCachedUnits();
+        const unitMap = new Map();
+        for (const u of allUnits)
+            unitMap.set(u.id, u);
+        for (const id of visited) {
+            const unit = unitMap.get(id);
+            if (!unit)
+                continue;
+            const keywordScore = keywordUnitIds.get(id) || 0;
+            const associationBonus = this.computeAssociationBonus(id, keywordUnitIds, edgeIndex);
+            const usageBonus = Math.min(unit.meta.usage_count / 50, 0.2);
+            const score = keywordScore * 0.7 + associationBonus * 0.2 + usageBonus * 0.1;
+            matchedUnits.push({ unit, score });
+        }
+        matchedUnits.sort((a, b) => b.score - a.score);
+        const topUnits = matchedUnits.slice(0, maxResults).map((m) => m.unit);
+        const result = {
+            query,
+            units: topUnits,
+            totalHops: maxHops,
+            elapsedMs: Date.now() - startTime,
+        };
+        // Cache result
+        this.resultCache.set(cacheKey, result);
+        return result;
+    }
+    computeAssociationBonus(unitId, seedScores, edgeIndex) {
+        let bonus = 0;
+        for (const [seedId, score] of seedScores) {
+            const edges = edgeIndex[seedId] || [];
+            if (edges.some((e) => e.to === unitId)) {
+                bonus += score * 0.1;
+            }
+        }
+        return Math.min(bonus, 1.0);
+    }
+    /**
+     * Get units from store's in-memory cache (no disk I/O).
+     */
+    getCachedUnits() {
+        // FileStore.load() already loaded everything into memory
+        // We access via listUnits() which reads from Map, not disk
+        const units = [];
+        const storeWithCache = this.store;
+        if (storeWithCache.cache && storeWithCache.cache.size > 0) {
+            for (const u of storeWithCache.cache.values()) {
+                units.push(u);
+            }
+        }
+        return units;
+    }
+    toContext(result) {
+        if (result.units.length === 0) {
+            return 'No relevant memory units found.';
+        }
+        const lines = [
+            `## MemGrid Context (${result.units.length} units, ${result.elapsedMs}ms)`,
+            '',
+        ];
+        for (const unit of result.units) {
+            lines.push(`### ${unit.id} (${unit.type})`);
+            lines.push(`- **${unit.summary}**`);
+            if (unit.source) {
+                lines.push(`- location: \`${unit.source.file}\`${unit.source.lines ? `:${unit.source.lines}` : ''}`);
+            }
+            if (unit.content.inputs && unit.content.inputs !== 'none') {
+                lines.push(`- inputs: ${unit.content.inputs}`);
+            }
+            if (unit.content.outputs && unit.content.outputs !== 'void') {
+                lines.push(`- outputs: ${unit.content.outputs}`);
+            }
+            lines.push(`- ${unit.content.description}`);
+            if (unit.content.style_notes) {
+                lines.push(`- style: ${unit.content.style_notes}`);
+            }
+            if (unit.content.code_snippet) {
+                lines.push('```ts');
+                lines.push(unit.content.code_snippet.slice(0, 300));
+                lines.push('```');
+            }
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/retrieve/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/retrieve/index.ts"],"names":[],"mappings":"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"}

package/dist/retrieve/semantic.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Semantic search layer for MemGrid.
+ * v0.4: Pluggable embedding providers + cosine similarity ranking.
+ * No native dependencies (pure JS). Embedding API calls are optional —
+ * falls back gracefully to keyword-only search if no embedding provider configured.
+ */
+import type { FileStore } from '../store/file-store.js';
+import type { SearchResult } from '../shared/types.js';
+export interface EmbeddingProvider {
+    name: string;
+    embed(texts: string[]): Promise<number[][]>;
+    dimensions: number;
+}
+export interface SemanticSearchOptions {
+    maxResults?: number;
+    maxHops?: number;
+    /** Weight of semantic vs keyword score: 0.0 = keyword only, 1.0 = semantic only */
+    semanticWeight?: number;
+}
+export declare class SemanticRetriever {
+    private baseEngine;
+    private store;
+    private provider;
+    private vectorCache;
+    private resultCache;
+    constructor(store: FileStore, provider?: EmbeddingProvider);
+    setProvider(provider: EmbeddingProvider): void;
+    /**
+     * Build embedding vectors for all units in the grid.
+     * Called after memgrid init to pre-compute embeddings.
+     */
+    buildIndex(): Promise<{
+        indexed: number;
+        errors: number;
+    }>;
+    /**
+     * Hybrid search: semantic (cosine) + keyword (minisearch) → merged & reranked.
+     */
+    search(query: string, options?: SemanticSearchOptions): Promise<SearchResult>;
+    toContext(result: SearchResult): string;
+    private cosine;
+}
+/**
+ * No-external-dependency provider: uses keyword overlap as pseudo-embedding.
+ * Not real semantic search but provides scoring diversity without API calls.
+ */
+export declare class KeywordEmbeddingProvider implements EmbeddingProvider {
+    name: string;
+    dimensions: number;
+    embed(texts: string[]): Promise<number[][]>;
+}
+/**
+ * Provider that calls an external embedding API (OpenAI-compatible format).
+ *
+ * Usage:
+ *   const provider = new APIEmbeddingProvider('https://api.deepseek.com/v1/embeddings', 'sk-...');
+ */
+export declare class APIEmbeddingProvider implements EmbeddingProvider {
+    name: string;
+    dimensions: number;
+    private baseUrl;
+    private apiKey;
+    private model;
+    constructor(baseUrl: string, apiKey: string, model?: string, dimensions?: number);
+    embed(texts: string[]): Promise<number[][]>;
+}
+//# sourceMappingURL=semantic.d.ts.map

package/dist/retrieve/semantic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic.d.ts","sourceRoot":"","sources":["../../src/retrieve/semantic.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAc,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAcnE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC5C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mFAAmF;IACnF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,UAAU,CAAiB;IACnC,OAAO,CAAC,KAAK,CAAY;IACzB,OAAO,CAAC,QAAQ,CAAkC;IAClD,OAAO,CAAC,WAAW,CAAoC;IACvD,OAAO,CAAC,WAAW,CAAqD;gBAE5D,KAAK,EAAE,SAAS,EAAE,QAAQ,CAAC,EAAE,iBAAiB;IAQ1D,WAAW,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAK9C;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IA8BhE;;OAEG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,YAAY,CAAC;IAoFnF,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM;IAIvC,OAAO,CAAC,MAAM;CAgBf;AASD;;;GAGG;AACH,qBAAa,wBAAyB,YAAW,iBAAiB;IAChE,IAAI,SAAa;IACjB,UAAU,SAAK;IAET,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;CA6BlD;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,YAAW,iBAAiB;IAC5D,IAAI,SAAS;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAAS;gBAEV,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,SAA2B,EAAE,UAAU,SAAO;IAO1F,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;CAoBlD"}