@shuyhere/takotako 0.0.1

package/dist/memory/hybrid.js

@@ -0,0 +1,156 @@
+/**
+ * Hybrid search — fuses BM25 (keyword) + vector (semantic) results.
+ *
+ * Falls back gracefully: if no embedding provider is configured,
+ * search uses BM25 only. If workspace files are missing, returns
+ * empty results instead of throwing.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { MarkdownIndexer } from './markdown.js';
+import { VectorStore } from './vector.js';
+/** Target chunk size in characters (~100 tokens). */
+const CHUNK_TARGET_CHARS = 400;
+/** Overlap between chunks in characters (~20 tokens). */
+const CHUNK_OVERLAP_CHARS = 80;
+export class HybridMemoryStore {
+    workspacePath;
+    markdownIndexer;
+    vectorStore;
+    initialized = false;
+    constructor(workspacePath, embeddingProvider) {
+        this.workspacePath = workspacePath;
+        this.markdownIndexer = new MarkdownIndexer(workspacePath);
+        this.vectorStore = new VectorStore(embeddingProvider);
+    }
+    /** Set (or replace) the embedding provider. */
+    setEmbeddingProvider(provider) {
+        this.vectorStore.setProvider(provider);
+    }
+    /**
+     * Initialize the memory store — index all workspace .md files.
+     * Safe to call multiple times (no-ops after first init).
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        try {
+            await this.markdownIndexer.indexAll();
+            // Index chunks into vector store for files already in the markdown index
+            for (const [path, entry] of this.markdownIndexer.getIndex()) {
+                await this.indexChunks(path, entry.content);
+            }
+            this.initialized = true;
+        }
+        catch {
+            // Workspace may not exist yet — that's okay
+            this.initialized = true;
+        }
+    }
+    async search(query, opts) {
+        await this.initialize();
+        const limit = opts?.limit ?? 5;
+        // Run both searches in parallel
+        const [bm25Results, vectorResults] = await Promise.all([
+            Promise.resolve(this.markdownIndexer.search(query, limit * 2)),
+            this.vectorStore.search(query, { ...opts, limit: limit * 2 }).catch(() => []),
+        ]);
+        // If only BM25 results, return them directly
+        if (vectorResults.length === 0) {
+            return bm25Results.slice(0, limit);
+        }
+        // Reciprocal Rank Fusion (RRF) to merge results
+        const k = 60; // RRF constant
+        const scores = new Map();
+        for (let i = 0; i < bm25Results.length; i++) {
+            const r = bm25Results[i];
+            const key = `${r.path}:${r.range.start}`;
+            const existing = scores.get(key);
+            const rrfScore = 1 / (k + i + 1);
+            if (existing) {
+                existing.score += rrfScore;
+            }
+            else {
+                scores.set(key, { snippet: { ...r, source: 'hybrid' }, score: rrfScore });
+            }
+        }
+        for (let i = 0; i < vectorResults.length; i++) {
+            const r = vectorResults[i];
+            const key = `${r.path}:${r.range.start}`;
+            const existing = scores.get(key);
+            const rrfScore = 1 / (k + i + 1);
+            if (existing) {
+                existing.score += rrfScore;
+            }
+            else {
+                scores.set(key, { snippet: { ...r, source: 'hybrid' }, score: rrfScore });
+            }
+        }
+        return Array.from(scores.values())
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit)
+            .map((s) => ({ ...s.snippet, score: s.score }));
+    }
+    /** Graceful get — returns empty string for missing files instead of throwing. */
+    async get(path, range) {
+        const fullPath = join(this.workspacePath, path);
+        try {
+            const content = await readFile(fullPath, 'utf-8');
+            if (!range)
+                return content;
+            const lines = content.split('\n');
+            return lines.slice(range.start - 1, range.end).join('\n');
+        }
+        catch {
+            return '';
+        }
+    }
+    async index(path) {
+        await this.markdownIndexer.indexFile(path);
+        const entry = this.markdownIndexer.getIndex().get(path);
+        if (entry) {
+            await this.indexChunks(path, entry.content);
+        }
+    }
+    /** Full reindex of the workspace. */
+    async reindexAll() {
+        await this.markdownIndexer.indexAll();
+        this.vectorStore.clear();
+        for (const [path, entry] of this.markdownIndexer.getIndex()) {
+            await this.indexChunks(path, entry.content);
+        }
+    }
+    /**
+     * Chunk text with overlap and index into the vector store.
+     * Uses sliding window approach for better context preservation.
+     */
+    async indexChunks(path, content) {
+        const lines = content.split('\n');
+        // For short files, index as a single chunk
+        if (content.length <= CHUNK_TARGET_CHARS * 1.5) {
+            await this.vectorStore.index(path, 1, lines.length, content);
+            return;
+        }
+        // Sliding window chunking with overlap
+        let charOffset = 0;
+        let lineOffset = 1;
+        while (charOffset < content.length) {
+            const chunkEnd = Math.min(charOffset + CHUNK_TARGET_CHARS, content.length);
+            let chunk = content.slice(charOffset, chunkEnd);
+            // Try to break at a paragraph boundary
+            const lastParagraph = chunk.lastIndexOf('\n\n');
+            if (lastParagraph > CHUNK_TARGET_CHARS * 0.3) {
+                chunk = chunk.slice(0, lastParagraph);
+            }
+            const chunkLines = chunk.split('\n').length;
+            await this.vectorStore.index(path, lineOffset, lineOffset + chunkLines - 1, chunk);
+            // Advance with overlap
+            const advance = Math.max(chunk.length - CHUNK_OVERLAP_CHARS, CHUNK_OVERLAP_CHARS);
+            charOffset += advance;
+            // Recalculate line offset
+            const advancedText = content.slice(0, charOffset);
+            lineOffset = advancedText.split('\n').length;
+        }
+    }
+}
+//# sourceMappingURL=hybrid.js.map

package/dist/memory/hybrid.js.map

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

package/dist/memory/markdown.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Markdown file indexer — reads and indexes .md files for BM25 search.
+ *
+ * Implements proper BM25 scoring with:
+ * - TF-IDF weighting (not just TF)
+ * - Document length normalization
+ * - Temporal decay for dated files (daily logs get recency boost)
+ */
+import type { Snippet, LineRange } from './store.js';
+export interface IndexEntry {
+    path: string;
+    content: string;
+    lines: string[];
+    modifiedAt: Date;
+    /** Word count for BM25 length normalization */
+    wordCount: number;
+}
+export declare class MarkdownIndexer {
+    private workspacePath;
+    private index;
+    /** Document frequency: how many documents contain each term */
+    private docFreq;
+    /** Average document length (in words) */
+    private avgDocLength;
+    constructor(workspacePath: string);
+    /** Index a single file and rebuild IDF stats. */
+    indexFile(relativePath: string): Promise<void>;
+    /** Scan workspace and index all .md files, then rebuild IDF stats. */
+    indexAll(): Promise<void>;
+    /** Rebuild document frequency and average length stats after indexing. */
+    private rebuildStats;
+    private scanDir;
+    /** Get a snippet from a file. */
+    getSnippet(path: string, range: LineRange): Snippet | null;
+    /**
+     * BM25 search with IDF weighting and temporal decay.
+     * Returns scored snippets sorted by relevance.
+     */
+    search(query: string, limit?: number): Snippet[];
+    /**
+     * Find the region of the document with the highest term density.
+     * Returns a ~500 char snippet centered on the best matching area.
+     */
+    private findBestSnippet;
+    /** Get all indexed entries. */
+    getIndex(): Map<string, IndexEntry>;
+}
+//# sourceMappingURL=markdown.d.ts.map

package/dist/memory/markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/memory/markdown.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAErD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,EAAE,IAAI,CAAC;IACjB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;CACnB;AAYD,qBAAa,eAAe;IAC1B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,KAAK,CAAiC;IAC9C,+DAA+D;IAC/D,OAAO,CAAC,OAAO,CAA6B;IAC5C,yCAAyC;IACzC,OAAO,CAAC,YAAY,CAAK;gBAEb,aAAa,EAAE,MAAM;IAIjC,iDAAiD;IAC3C,SAAS,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBpD,sEAAsE;IAChE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAK/B,0EAA0E;IAC1E,OAAO,CAAC,YAAY;YAmBN,OAAO;IAiBrB,iCAAiC;IACjC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,GAAG,IAAI;IAa1D;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,MAAU,GAAG,OAAO,EAAE;IAuDnD;;;OAGG;IACH,OAAO,CAAC,eAAe;IAmCvB,+BAA+B;IAC/B,QAAQ,IAAI,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC;CAGpC"}

package/dist/memory/markdown.js

@@ -0,0 +1,228 @@
+/**
+ * Markdown file indexer — reads and indexes .md files for BM25 search.
+ *
+ * Implements proper BM25 scoring with:
+ * - TF-IDF weighting (not just TF)
+ * - Document length normalization
+ * - Temporal decay for dated files (daily logs get recency boost)
+ */
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+/** BM25 tuning parameters */
+const BM25_K1 = 1.2; // Term frequency saturation
+const BM25_B = 0.75; // Length normalization factor
+/** Temporal decay half-life in days */
+const DECAY_HALF_LIFE_DAYS = 30;
+/** Files that never decay (evergreen) */
+const EVERGREEN_PATTERNS = ['MEMORY.md', 'SOUL.md', 'IDENTITY.md', 'AGENTS.md', 'TOOLS.md', 'USER.md'];
+export class MarkdownIndexer {
+    workspacePath;
+    index = new Map();
+    /** Document frequency: how many documents contain each term */
+    docFreq = new Map();
+    /** Average document length (in words) */
+    avgDocLength = 0;
+    constructor(workspacePath) {
+        this.workspacePath = workspacePath;
+    }
+    /** Index a single file and rebuild IDF stats. */
+    async indexFile(relativePath) {
+        const fullPath = join(this.workspacePath, relativePath);
+        try {
+            const content = await readFile(fullPath, 'utf-8');
+            const fileStat = await stat(fullPath);
+            const words = tokenize(content);
+            this.index.set(relativePath, {
+                path: relativePath,
+                content,
+                lines: content.split('\n'),
+                modifiedAt: fileStat.mtime,
+                wordCount: words.length,
+            });
+            // Rebuild IDF stats to include the new/updated file
+            this.rebuildStats();
+        }
+        catch {
+            // File not found or unreadable — skip
+        }
+    }
+    /** Scan workspace and index all .md files, then rebuild IDF stats. */
+    async indexAll() {
+        await this.scanDir('.');
+        this.rebuildStats();
+    }
+    /** Rebuild document frequency and average length stats after indexing. */
+    rebuildStats() {
+        this.docFreq.clear();
+        let totalWords = 0;
+        for (const [, entry] of this.index) {
+            totalWords += entry.wordCount;
+            // Count unique terms per document
+            const seen = new Set();
+            for (const word of tokenize(entry.content)) {
+                if (!seen.has(word)) {
+                    seen.add(word);
+                    this.docFreq.set(word, (this.docFreq.get(word) ?? 0) + 1);
+                }
+            }
+        }
+        this.avgDocLength = this.index.size > 0 ? totalWords / this.index.size : 1;
+    }
+    async scanDir(dir) {
+        const fullDir = join(this.workspacePath, dir);
+        try {
+            const entries = await readdir(fullDir, { withFileTypes: true });
+            for (const entry of entries) {
+                const relPath = join(dir, entry.name);
+                if (entry.isDirectory() && !entry.name.startsWith('.')) {
+                    await this.scanDir(relPath);
+                }
+                else if (entry.isFile() && entry.name.endsWith('.md')) {
+                    await this.indexFile(relPath);
+                }
+            }
+        }
+        catch {
+            // Directory not found — skip
+        }
+    }
+    /** Get a snippet from a file. */
+    getSnippet(path, range) {
+        const entry = this.index.get(path);
+        if (!entry)
+            return null;
+        const lines = entry.lines.slice(range.start - 1, range.end);
+        return {
+            path,
+            range,
+            content: lines.join('\n'),
+            score: 1.0,
+            source: 'bm25',
+        };
+    }
+    /**
+     * BM25 search with IDF weighting and temporal decay.
+     * Returns scored snippets sorted by relevance.
+     */
+    search(query, limit = 5) {
+        const terms = tokenize(query);
+        if (terms.length === 0)
+            return [];
+        const N = this.index.size;
+        const results = [];
+        const now = Date.now();
+        for (const [path, entry] of this.index) {
+            const docWords = tokenize(entry.content);
+            const docLength = docWords.length;
+            // Count term frequencies in this document
+            const tf = new Map();
+            for (const word of docWords) {
+                tf.set(word, (tf.get(word) ?? 0) + 1);
+            }
+            // BM25 score
+            let score = 0;
+            for (const term of terms) {
+                const termFreq = tf.get(term) ?? 0;
+                if (termFreq === 0)
+                    continue;
+                // IDF: log((N - df + 0.5) / (df + 0.5) + 1)
+                const df = this.docFreq.get(term) ?? 0;
+                const idf = Math.log((N - df + 0.5) / (df + 0.5) + 1);
+                // BM25 TF component with length normalization
+                const tfNorm = (termFreq * (BM25_K1 + 1)) /
+                    (termFreq + BM25_K1 * (1 - BM25_B + BM25_B * (docLength / this.avgDocLength)));
+                score += idf * tfNorm;
+            }
+            if (score <= 0)
+                continue;
+            // Apply temporal decay for dated files (daily logs)
+            score *= temporalDecay(path, entry.modifiedAt, now);
+            // Find the best matching snippet region
+            const snippet = this.findBestSnippet(entry, terms);
+            results.push({
+                path,
+                range: snippet.range,
+                content: snippet.content,
+                score,
+                source: 'bm25',
+            });
+        }
+        return results.sort((a, b) => b.score - a.score).slice(0, limit);
+    }
+    /**
+     * Find the region of the document with the highest term density.
+     * Returns a ~500 char snippet centered on the best matching area.
+     */
+    findBestSnippet(entry, terms) {
+        const lines = entry.lines;
+        if (lines.length <= 15) {
+            return {
+                range: { start: 1, end: lines.length },
+                content: entry.content.slice(0, 700),
+            };
+        }
+        // Score each line by term hits
+        let bestStart = 0;
+        let bestScore = 0;
+        const windowSize = Math.min(10, lines.length);
+        for (let i = 0; i <= lines.length - windowSize; i++) {
+            let windowScore = 0;
+            for (let j = i; j < i + windowSize; j++) {
+                const lineWords = tokenize(lines[j]);
+                for (const term of terms) {
+                    if (lineWords.includes(term))
+                        windowScore++;
+                }
+            }
+            if (windowScore > bestScore) {
+                bestScore = windowScore;
+                bestStart = i;
+            }
+        }
+        const snippetLines = lines.slice(bestStart, bestStart + windowSize);
+        return {
+            range: { start: bestStart + 1, end: bestStart + windowSize },
+            content: snippetLines.join('\n').slice(0, 700),
+        };
+    }
+    /** Get all indexed entries. */
+    getIndex() {
+        return this.index;
+    }
+}
+/** Tokenize text into lowercase words. */
+function tokenize(text) {
+    return text.toLowerCase().match(/[a-z0-9_]+/g) ?? [];
+}
+/**
+ * Compute temporal decay multiplier for a file.
+ * Evergreen files (MEMORY.md, SOUL.md, etc.) never decay.
+ * Dated daily files (YYYY-MM-DD.md) decay exponentially.
+ */
+function temporalDecay(path, modifiedAt, now) {
+    // Check if file is evergreen
+    for (const pattern of EVERGREEN_PATTERNS) {
+        if (path.endsWith(pattern))
+            return 1.0;
+    }
+    // Try to extract date from filename (memory/YYYY-MM-DD.md)
+    const dateMatch = path.match(/(\d{4}-\d{2}-\d{2})\.md$/);
+    let fileDate;
+    if (dateMatch) {
+        fileDate = new Date(dateMatch[1]);
+        if (isNaN(fileDate.getTime()))
+            fileDate = modifiedAt;
+    }
+    else {
+        // Non-dated file — use modification time with gentle decay
+        fileDate = modifiedAt;
+    }
+    const ageInDays = (now - fileDate.getTime()) / (1000 * 60 * 60 * 24);
+    if (ageInDays <= 0)
+        return 1.0;
+    // Exponential decay: score * e^(-lambda * age)
+    // lambda = ln(2) / halfLife
+    const lambda = Math.LN2 / DECAY_HALF_LIFE_DAYS;
+    return Math.exp(-lambda * ageInDays);
+}
+//# sourceMappingURL=markdown.js.map

package/dist/memory/markdown.js.map

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

package/dist/memory/store.d.ts

@@ -0,0 +1,88 @@
+/**
+ * MemoryStore — persistence + recall trait.
+ *
+ * Markdown files are the source of truth. The store provides semantic
+ * search (vector + BM25 hybrid), direct file reads, and indexing.
+ *
+ * Memory hierarchy:
+ * - `MEMORY.md` — curated long-term memory (always in context)
+ * - `memory/YYYY-MM-DD.md` — daily append-only logs (accessed on-demand)
+ * - Workspace files — SOUL.md, IDENTITY.md, etc. (indexed for search)
+ *
+ * @example
+ * ```typescript
+ * const store = new HybridMemoryStore('/workspace');
+ * await store.initialize();
+ * const results = await store.search('TypeScript patterns', { limit: 5 });
+ * const content = await store.get('MEMORY.md');
+ * ```
+ */
+/** A search result snippet with content, location, and relevance score. */
+export interface Snippet {
+    /** File path relative to workspace root */
+    path: string;
+    /** Line range this snippet covers */
+    range: LineRange;
+    /** The text content of the snippet */
+    content: string;
+    /** Relevance score (higher = more relevant, scale depends on source) */
+    score: number;
+    /** Which search method produced this result */
+    source?: 'vector' | 'bm25' | 'hybrid';
+}
+/** Options for memory search. */
+export interface SearchOpts {
+    /** Maximum number of results to return (default: 10) */
+    limit?: number;
+    /** Minimum relevance threshold — results below this are excluded */
+    threshold?: number;
+    /** Restrict search to files matching these paths or glob patterns */
+    paths?: string[];
+    /** Include only files modified after this date */
+    since?: Date;
+}
+/** A 1-based inclusive line range within a file. */
+export interface LineRange {
+    /** 1-based start line */
+    start: number;
+    /** 1-based end line (inclusive) */
+    end: number;
+}
+/**
+ * MemoryStore — the persistence and recall trait.
+ *
+ * Implementations provide hybrid search (BM25 keyword + vector semantic)
+ * over the agent's markdown-based memory. The agent loop uses this for
+ * memory_search, memory_get, and memory_store tools.
+ *
+ * Built-in implementation:
+ * - {@link HybridMemoryStore} — BM25 + vector search with RRF fusion
+ */
+export interface MemoryStore {
+    /**
+     * Search across indexed memory files using hybrid retrieval.
+     * Returns snippets ranked by relevance (BM25 + vector + temporal decay).
+     *
+     * @param query - Natural language search query
+     * @param opts - Search options (limit, threshold, path filters)
+     * @returns Ranked array of matching snippets
+     */
+    search(query: string, opts?: SearchOpts): Promise<Snippet[]>;
+    /**
+     * Read a specific file or line range from the workspace.
+     * Returns empty string for missing files (graceful degradation).
+     *
+     * @param path - File path relative to workspace root
+     * @param range - Optional line range to extract
+     * @returns File content (or line range subset)
+     */
+    get(path: string, range?: LineRange): Promise<string>;
+    /**
+     * Index (or re-index) a file for search.
+     * Updates both BM25 and vector indexes.
+     *
+     * @param path - File path relative to workspace root
+     */
+    index(path: string): Promise<void>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/memory/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/memory/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,2EAA2E;AAC3E,MAAM,WAAW,OAAO;IACtB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,KAAK,EAAE,SAAS,CAAC;IACjB,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;CACvC;AAED,iCAAiC;AACjC,MAAM,WAAW,UAAU;IACzB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,kDAAkD;IAClD,KAAK,CAAC,EAAE,IAAI,CAAC;CACd;AAED,oDAAoD;AACpD,MAAM,WAAW,SAAS;IACxB,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,GAAG,EAAE,MAAM,CAAC;CACb;AAID;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAE7D;;;;;;;OAOG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEtD;;;;;OAKG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC"}

package/dist/memory/store.js

@@ -0,0 +1,21 @@
+/**
+ * MemoryStore — persistence + recall trait.
+ *
+ * Markdown files are the source of truth. The store provides semantic
+ * search (vector + BM25 hybrid), direct file reads, and indexing.
+ *
+ * Memory hierarchy:
+ * - `MEMORY.md` — curated long-term memory (always in context)
+ * - `memory/YYYY-MM-DD.md` — daily append-only logs (accessed on-demand)
+ * - Workspace files — SOUL.md, IDENTITY.md, etc. (indexed for search)
+ *
+ * @example
+ * ```typescript
+ * const store = new HybridMemoryStore('/workspace');
+ * await store.initialize();
+ * const results = await store.search('TypeScript patterns', { limit: 5 });
+ * const content = await store.get('MEMORY.md');
+ * ```
+ */
+export {};
+//# sourceMappingURL=store.js.map

package/dist/memory/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/memory/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/dist/memory/vector.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Vector search — embedding-based semantic search.
+ */
+import type { Snippet, SearchOpts } from './store.js';
+export interface EmbeddingProvider {
+    /** Generate embeddings for a list of texts. */
+    embed(texts: string[]): Promise<number[][]>;
+    /** Dimension of the embedding vectors. */
+    dimensions: number;
+}
+export declare class VectorStore {
+    private entries;
+    private provider;
+    constructor(provider?: EmbeddingProvider);
+    /** Set the embedding provider. */
+    setProvider(provider: EmbeddingProvider): void;
+    /** Index a text chunk with its location. */
+    index(path: string, startLine: number, endLine: number, text: string): Promise<void>;
+    /** Search for similar text chunks. */
+    search(query: string, opts?: SearchOpts): Promise<Snippet[]>;
+    /** Clear all indexed entries. */
+    clear(): void;
+}
+//# sourceMappingURL=vector.d.ts.map

package/dist/memory/vector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector.d.ts","sourceRoot":"","sources":["../../src/memory/vector.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEtD,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC5C,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;CACpB;AAUD,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,QAAQ,CAAkC;gBAEtC,QAAQ,CAAC,EAAE,iBAAiB;IAIxC,kCAAkC;IAClC,WAAW,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAI9C,4CAA4C;IACtC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO1F,sCAAsC;IAChC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IA0BlE,iCAAiC;IACjC,KAAK,IAAI,IAAI;CAGd"}