@lingxiao-office/sdk 1.0.0

package/dist/memory/MemoryEmbedding.js

@@ -0,0 +1,104 @@
+/**
+ * MemoryEmbedding — Embedding generation and vector storage for memory entries.
+ *
+ * Uses the local LLM Gateway (http://127.0.0.1:62000) /embeddings endpoint
+ * to generate embeddings. Falls back to deterministic pseudo-embedding if
+ * the gateway is unavailable.
+ *
+ * Storage: embeddings are stored in a separate SQLite table (memory_embedding)
+ * alongside the FTS index, keyed by the same path as the memory entry.
+ */
+import { coreLogger } from '../core/Log.js';
+import { getConfigValue } from '../config.js';
+import { isLlmGatewaySkKey, resolveLocalLlmGateway } from '../core/LocalLlmGateway.js';
+function getGatewayKey() {
+    const key = String(getConfigValue('llm_gateway.api_key') || '').trim();
+    return isLlmGatewaySkKey(key) ? key : '';
+}
+const DEFAULT_EMBEDDING_DIMENSIONS = 256;
+/** 获取网关基础 URL：优先运行时绑定的随机端口，回退到配置端口 */
+function getGatewayUrl() {
+    try {
+        const gateway = resolveLocalLlmGateway();
+        if (gateway)
+            return gateway.origin;
+    }
+    catch { /* expected */ }
+    return 'http://127.0.0.1:62000'; // 最终回退
+}
+/**
+ * Generate an embedding vector for the given text using the local LLM Gateway.
+ * Falls back to a deterministic hash-based pseudo-embedding if the gateway is unavailable.
+ */
+export async function generateEmbedding(text, model = 'text-embedding-3-small', dimensions = DEFAULT_EMBEDDING_DIMENSIONS) {
+    try {
+        const response = await fetch(`${getGatewayUrl()}/llm/openai/v1/embeddings`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${getGatewayKey()}`,
+            },
+            body: JSON.stringify({
+                model,
+                input: text,
+            }),
+        });
+        if (!response.ok) {
+            throw new Error(`Gateway returned ${response.status}: ${response.statusText}`);
+        }
+        const data = await response.json();
+        if (data.data && data.data.length > 0 && data.data[0].embedding) {
+            return {
+                vector: data.data[0].embedding,
+                model: data.model || model,
+                dimensions: data.data[0].embedding.length,
+            };
+        }
+        throw new Error('No embedding in response');
+    }
+    catch (err) {
+        coreLogger.warn(`[MemoryEmbedding] Gateway embedding failed, using deterministic fallback: ${err instanceof Error ? err.message : err}`);
+        return {
+            vector: deterministicPseudoEmbedding(text, dimensions),
+            model: 'deterministic-fallback',
+            dimensions,
+        };
+    }
+}
+/**
+ * Compute cosine similarity between two vectors.
+ */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length)
+        return 0;
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    return denom > 0 ? dot / denom : 0;
+}
+/**
+ * Deterministic pseudo-embedding fallback: generates a fixed-dimension vector
+ * from text using a hash-based approach. Not semantically meaningful but stable.
+ */
+function deterministicPseudoEmbedding(text, dimensions) {
+    const result = new Array(dimensions).fill(0);
+    for (let i = 0; i < text.length; i++) {
+        const charCode = text.charCodeAt(i);
+        const slot = (charCode * 31 + i) % dimensions;
+        result[slot] += Math.sin(charCode * 0.01 + i * 0.001);
+    }
+    const norm = Math.sqrt(result.reduce((sum, v) => sum + v * v, 0));
+    if (norm > 0) {
+        for (let i = 0; i < dimensions; i++) {
+            result[i] /= norm;
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=MemoryEmbedding.js.map

package/dist/memory/MemoryEmbedding.js.map

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

package/dist/memory/MemoryFTS.d.ts

@@ -0,0 +1,55 @@
+/**
+ * MemoryFTS — FTS5 + BM25 memory search backed by node:sqlite.
+ *
+ * Strategy:
+ * - Try FTS5 virtual table on init. If the engine supports it, use MATCH + bm25().
+ * - If FTS5 is unavailable (old node builds), fall back to LIKE-based token matching.
+ */
+import type { MemoryFTSEntry, MemoryFTSScope, MemoryFTSType, MemorySearchResult, MemoryFTSSearchOptions } from './types.js';
+export declare class MemoryFTS {
+    private db;
+    private fts5Available;
+    private dbPath;
+    /** top_score * floorRatio = the relevance floor for trimming weak hits. */
+    private floorRatio;
+    constructor(dbPath: string, floorRatio?: number);
+    private initSchema;
+    /** Upsert a memory entry. Returns true if body was actually updated. */
+    upsert(entry: Omit<MemoryFTSEntry, 'id' | 'last_indexed_at'> & {
+        id?: string;
+    }): boolean;
+    /** Remove entries whose paths are no longer present. */
+    prune(validPaths: Set<string>): number;
+    /** Search memory entries using BM25 (FTS5) or LIKE fallback. */
+    search(query: string, options?: MemoryFTSSearchOptions): MemorySearchResult[];
+    /** Store an embedding vector for a memory entry. */
+    storeEmbedding(path: string, vector: number[], model: string): void;
+    /** Retrieve embedding vector for a path. Returns null if not stored. */
+    getEmbedding(path: string): number[] | null;
+    /**
+     * Hybrid search: combine FTS/BM25 results with vector cosine similarity.
+     * @param query Query text
+     * @param queryVector Optional pre-computed query embedding
+     * @param options Search options
+     * @param weights Fusion weights { fts, vector }
+     */
+    hybridSearch(query: string, queryVector: number[] | null, options?: MemoryFTSSearchOptions, weights?: {
+        fts: number;
+        vector: number;
+    }): MemorySearchResult[];
+    private searchFTS5;
+    private searchLike;
+    private buildFilterClause;
+    private extractSnippet;
+    /** Get all indexed paths. */
+    getAllPaths(): string[];
+    /** Get entries by scope. */
+    getByScope(scope: MemoryFTSScope, scopeId?: string): MemoryFTSEntry[];
+    /** Get entries by type within a time range. */
+    getByTypeAfter(type: MemoryFTSType, afterTimestamp: number): MemoryFTSEntry[];
+    /** Close the database connection. */
+    close(): void;
+    /** Check if FTS5 is available. */
+    isFTS5Available(): boolean;
+}
+//# sourceMappingURL=MemoryFTS.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryFTS.d.ts","sourceRoot":"","sources":["../../src/memory/MemoryFTS.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAQpB,qBAAa,SAAS;IACpB,OAAO,CAAC,EAAE,CAAe;IACzB,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,MAAM,CAAS;IACvB,2EAA2E;IAC3E,OAAO,CAAC,UAAU,CAAS;gBAEf,MAAM,EAAE,MAAM,EAAE,UAAU,SAAO;IAa7C,OAAO,CAAC,UAAU;IA8ClB,wEAAwE;IACxE,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,cAAc,EAAE,IAAI,GAAG,iBAAiB,CAAC,GAAG;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO;IA2BxF,wDAAwD;IACxD,KAAK,CAAC,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM;IAYtC,gEAAgE;IAChE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B,GAAG,kBAAkB,EAAE;IAcjF,oDAAoD;IACpD,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAOnE,wEAAwE;IACxE,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI;IAS3C;;;;;;OAMG;IACH,YAAY,CACV,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EAAE,GAAG,IAAI,EAC5B,OAAO,GAAE,sBAA2B,EACpC,OAAO,GAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAA8B,GACnE,kBAAkB,EAAE;IA2BvB,OAAO,CAAC,UAAU;IA6ClB,OAAO,CAAC,UAAU;IAwDlB,OAAO,CAAC,iBAAiB;IAoBzB,OAAO,CAAC,cAAc;IA4BtB,6BAA6B;IAC7B,WAAW,IAAI,MAAM,EAAE;IAKvB,4BAA4B;IAC5B,UAAU,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,cAAc,EAAE;IAWrE,+CAA+C;IAC/C,cAAc,CAAC,IAAI,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,GAAG,cAAc,EAAE;IAM7E,qCAAqC;IACrC,KAAK,IAAI,IAAI;IAQb,kCAAkC;IAClC,eAAe,IAAI,OAAO;CAG3B"}

package/dist/memory/MemoryFTS.js

@@ -0,0 +1,333 @@
+/**
+ * MemoryFTS — FTS5 + BM25 memory search backed by node:sqlite.
+ *
+ * Strategy:
+ * - Try FTS5 virtual table on init. If the engine supports it, use MATCH + bm25().
+ * - If FTS5 is unavailable (old node builds), fall back to LIKE-based token matching.
+ */
+import { DatabaseSync } from 'node:sqlite';
+import { cosineSimilarity } from './MemoryEmbedding.js';
+import { existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { coreLogger } from '../core/Log.js';
+const TOKEN_RE = /[\p{L}\p{N}_]+/gu;
+function tokenize(query) {
+    return Array.from(query.matchAll(TOKEN_RE), (m) => m[0].toLowerCase());
+}
+export class MemoryFTS {
+    db;
+    fts5Available = false;
+    dbPath;
+    /** top_score * floorRatio = the relevance floor for trimming weak hits. */
+    floorRatio;
+    constructor(dbPath, floorRatio = 0.15) {
+        this.dbPath = dbPath;
+        this.floorRatio = floorRatio;
+        const dir = dirname(dbPath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        this.db = new DatabaseSync(dbPath);
+        this.db.exec('PRAGMA journal_mode = WAL');
+        this.db.exec('PRAGMA busy_timeout = 5000');
+        this.initSchema();
+    }
+    initSchema() {
+        // Core table
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS memory_entry (
+        id TEXT PRIMARY KEY,
+        path TEXT NOT NULL UNIQUE,
+        scope TEXT NOT NULL,
+        scope_id TEXT NOT NULL,
+        type TEXT NOT NULL,
+        body TEXT NOT NULL,
+        fingerprint TEXT NOT NULL,
+        last_indexed_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS memory_scope_idx ON memory_entry(scope, scope_id);
+      CREATE INDEX IF NOT EXISTS memory_type_idx ON memory_entry(type);
+    `);
+        // Try FTS5
+        try {
+            this.db.exec(`
+        CREATE VIRTUAL TABLE IF NOT EXISTS memory_fts USING fts5(
+          body,
+          content='memory_entry',
+          content_rowid='rowid'
+        );
+      `);
+            // Triggers to keep FTS in sync
+            this.db.exec(`
+        CREATE TRIGGER IF NOT EXISTS memory_fts_ai AFTER INSERT ON memory_entry BEGIN
+          INSERT INTO memory_fts(rowid, body) VALUES (NEW.rowid, NEW.body);
+        END;
+        CREATE TRIGGER IF NOT EXISTS memory_fts_ad AFTER DELETE ON memory_entry BEGIN
+          INSERT INTO memory_fts(memory_fts, rowid, body) VALUES('delete', OLD.rowid, OLD.body);
+        END;
+        CREATE TRIGGER IF NOT EXISTS memory_fts_au AFTER UPDATE ON memory_entry BEGIN
+          INSERT INTO memory_fts(memory_fts, rowid, body) VALUES('delete', OLD.rowid, OLD.body);
+          INSERT INTO memory_fts(rowid, body) VALUES (NEW.rowid, NEW.body);
+        END;
+      `);
+            this.fts5Available = true;
+        }
+        catch {
+            coreLogger.warn('[MemoryFTS] FTS5 not available, falling back to LIKE-based search');
+            this.fts5Available = false;
+        }
+    }
+    /** Upsert a memory entry. Returns true if body was actually updated. */
+    upsert(entry) {
+        const now = Date.now();
+        const id = entry.id || randomUUID();
+        // Check existing fingerprint
+        const existing = this.db.prepare('SELECT id, fingerprint FROM memory_entry WHERE path = ?').get(entry.path);
+        if (existing && existing.fingerprint === entry.fingerprint) {
+            return false; // No change
+        }
+        if (existing) {
+            this.db.prepare(`
+        UPDATE memory_entry SET body = ?, scope = ?, scope_id = ?, type = ?, fingerprint = ?, last_indexed_at = ?
+        WHERE id = ?
+      `).run(entry.body, entry.scope, entry.scope_id, entry.type, entry.fingerprint, now, existing.id);
+        }
+        else {
+            this.db.prepare(`
+        INSERT INTO memory_entry (id, path, scope, scope_id, type, body, fingerprint, last_indexed_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(id, entry.path, entry.scope, entry.scope_id, entry.type, entry.body, entry.fingerprint, now);
+        }
+        return true;
+    }
+    /** Remove entries whose paths are no longer present. */
+    prune(validPaths) {
+        const allRows = this.db.prepare('SELECT id, path FROM memory_entry').all();
+        let removed = 0;
+        for (const row of allRows) {
+            if (!validPaths.has(row.path)) {
+                this.db.prepare('DELETE FROM memory_entry WHERE id = ?').run(row.id);
+                removed++;
+            }
+        }
+        return removed;
+    }
+    /** Search memory entries using BM25 (FTS5) or LIKE fallback. */
+    search(query, options = {}) {
+        const tokens = tokenize(query);
+        if (tokens.length === 0)
+            return [];
+        const maxResults = options.maxResults ?? 10;
+        if (this.fts5Available) {
+            return this.searchFTS5(tokens, options, maxResults);
+        }
+        return this.searchLike(tokens, options, maxResults);
+    }
+    // P1: Hybrid search — combine BM25 (FTS) with vector cosine similarity
+    /** Store an embedding vector for a memory entry. */
+    storeEmbedding(path, vector, model) {
+        const buf = Buffer.from(new Float32Array(vector).buffer);
+        this.db.prepare(`INSERT OR REPLACE INTO memory_embedding (path, embedding, model, dimensions, created_at) VALUES (?, ?, ?, ?, ?)`).run(path, buf, model, vector.length, Date.now());
+    }
+    /** Retrieve embedding vector for a path. Returns null if not stored. */
+    getEmbedding(path) {
+        const row = this.db.prepare('SELECT embedding, dimensions FROM memory_embedding WHERE path = ?').get(path);
+        if (!row)
+            return null;
+        const floatArr = new Float32Array(row.embedding.buffer, row.embedding.byteOffset, row.dimensions);
+        return Array.from(floatArr);
+    }
+    /**
+     * Hybrid search: combine FTS/BM25 results with vector cosine similarity.
+     * @param query Query text
+     * @param queryVector Optional pre-computed query embedding
+     * @param options Search options
+     * @param weights Fusion weights { fts, vector }
+     */
+    hybridSearch(query, queryVector, options = {}, weights = { fts: 0.7, vector: 0.3 }) {
+        // Get FTS results first
+        const ftsResults = this.search(query, options);
+        if (ftsResults.length === 0 || !queryVector)
+            return ftsResults;
+        // Compute vector scores for each FTS result
+        const scored = ftsResults.map((r) => {
+            const entryVector = this.getEmbedding(r.path);
+            const vectorScore = entryVector ? cosineSimilarity(queryVector, entryVector) : 0;
+            const ftsScore = r.score;
+            // Normalize FTS score to 0-1 range (rough normalization)
+            const normalizedFts = Math.min(1, ftsScore / 10);
+            // Weighted fusion
+            const fusedScore = weights.fts * normalizedFts + weights.vector * vectorScore;
+            return {
+                ...r,
+                score: fusedScore,
+                ftsScore,
+                vectorScore,
+            };
+        });
+        // Re-sort by fused score
+        scored.sort((a, b) => b.score - a.score);
+        return scored;
+    }
+    searchFTS5(tokens, options, maxResults) {
+        // Build FTS5 MATCH expression: "token1" OR "token2" OR ...
+        const matchExpr = tokens.map((t) => `"${t}"`).join(' OR ');
+        // Build WHERE clause for scope/type filtering
+        const { clause, params } = this.buildFilterClause(options);
+        const sql = `
+      SELECT e.path, e.body, e.scope, e.scope_id, e.type, bm25(memory_fts) AS score
+      FROM memory_fts f
+      JOIN memory_entry e ON e.rowid = f.rowid
+      WHERE memory_fts MATCH ?
+      ${clause ? 'AND ' + clause : ''}
+      ORDER BY score ASC
+      LIMIT ?
+    `;
+        const rows = this.db.prepare(sql).all(matchExpr, ...params, maxResults * 2);
+        if (rows.length === 0)
+            return [];
+        // BM25 returns negative scores (lower = better). Convert to positive.
+        const results = rows.map((r) => ({
+            path: r.path,
+            snippet: this.extractSnippet(r.body, tokens),
+            score: -r.score, // Flip sign so higher = better
+            scope: r.scope,
+            scope_id: r.scope_id,
+            type: r.type,
+        }));
+        // Apply score floor: top_score * 0.15. The best hit (index 0) is always
+        // preserved even when an explicit scoreFloor is passed above topScore —
+        // otherwise a caller-supplied floor could discard the single best match and
+        // return nothing. This mirrors mimo's "keep #1" guarantee.
+        const topScore = results[0]?.score ?? 0;
+        const floor = options.scoreFloor ?? topScore * this.floorRatio;
+        return results
+            .filter((r, i) => i === 0 || r.score >= floor)
+            .slice(0, maxResults);
+    }
+    searchLike(tokens, options, maxResults) {
+        const { clause, params } = this.buildFilterClause(options);
+        // Build LIKE conditions: at least one token must match
+        const likeConditions = tokens.map(() => 'LOWER(e.body) LIKE ?').join(' OR ');
+        const likeParams = tokens.map((t) => `%${t}%`);
+        const whereClause = [
+            `(${likeConditions})`,
+            clause,
+        ].filter(Boolean).join(' AND ');
+        const sql = `
+      SELECT e.path, e.body, e.scope, e.scope_id, e.type
+      FROM memory_entry e
+      WHERE ${whereClause}
+    `;
+        const rows = this.db.prepare(sql).all(...likeParams, ...params);
+        // Score by token hit count
+        const scored = rows.map((r) => {
+            const bodyLower = r.body.toLowerCase();
+            let score = 0;
+            for (const t of tokens) {
+                const idx = bodyLower.indexOf(t);
+                if (idx !== -1)
+                    score += 1;
+                // Bonus for multiple occurrences
+                let pos = idx;
+                while (pos !== -1) {
+                    pos = bodyLower.indexOf(t, pos + 1);
+                    if (pos !== -1)
+                        score += 0.3;
+                }
+            }
+            return {
+                path: r.path,
+                snippet: this.extractSnippet(r.body, tokens),
+                score,
+                scope: r.scope,
+                scope_id: r.scope_id,
+                type: r.type,
+            };
+        });
+        scored.sort((a, b) => b.score - a.score);
+        // Keep the best hit even under an explicit scoreFloor (see searchFTS5).
+        const topScore = scored[0]?.score ?? 0;
+        const floor = options.scoreFloor ?? topScore * this.floorRatio;
+        return scored
+            .filter((r, i) => i === 0 || r.score >= floor)
+            .slice(0, maxResults);
+    }
+    buildFilterClause(options) {
+        const conditions = [];
+        const params = [];
+        if (options.scopes && options.scopes.length > 0) {
+            conditions.push(`e.scope IN (${options.scopes.map(() => '?').join(',')})`);
+            params.push(...options.scopes);
+        }
+        if (options.scopeIds && options.scopeIds.length > 0) {
+            conditions.push(`e.scope_id IN (${options.scopeIds.map(() => '?').join(',')})`);
+            params.push(...options.scopeIds);
+        }
+        if (options.types && options.types.length > 0) {
+            conditions.push(`e.type IN (${options.types.map(() => '?').join(',')})`);
+            params.push(...options.types);
+        }
+        return { clause: conditions.join(' AND '), params };
+    }
+    extractSnippet(body, tokens, contextChars = 120) {
+        const bodyLower = body.toLowerCase();
+        let bestPos = 0;
+        let bestScore = 0;
+        // Find position with most token density
+        for (const token of tokens) {
+            const idx = bodyLower.indexOf(token);
+            if (idx === -1)
+                continue;
+            let windowScore = 0;
+            for (const t of tokens) {
+                const window = bodyLower.slice(Math.max(0, idx - contextChars), idx + contextChars);
+                if (window.includes(t))
+                    windowScore++;
+            }
+            if (windowScore > bestScore) {
+                bestScore = windowScore;
+                bestPos = idx;
+            }
+        }
+        const start = Math.max(0, bestPos - contextChars / 2);
+        const end = Math.min(body.length, bestPos + contextChars);
+        let snippet = body.slice(start, end).replace(/\n+/g, ' ').trim();
+        if (start > 0)
+            snippet = '...' + snippet;
+        if (end < body.length)
+            snippet = snippet + '...';
+        return snippet;
+    }
+    /** Get all indexed paths. */
+    getAllPaths() {
+        const rows = this.db.prepare('SELECT path FROM memory_entry').all();
+        return rows.map((r) => r.path);
+    }
+    /** Get entries by scope. */
+    getByScope(scope, scopeId) {
+        if (scopeId) {
+            return this.db.prepare('SELECT * FROM memory_entry WHERE scope = ? AND scope_id = ?').all(scope, scopeId);
+        }
+        return this.db.prepare('SELECT * FROM memory_entry WHERE scope = ?').all(scope);
+    }
+    /** Get entries by type within a time range. */
+    getByTypeAfter(type, afterTimestamp) {
+        return this.db.prepare('SELECT * FROM memory_entry WHERE type = ? AND last_indexed_at > ?').all(type, afterTimestamp);
+    }
+    /** Close the database connection. */
+    close() {
+        try {
+            this.db.close();
+        }
+        catch {
+            // Ignore close errors
+        }
+    }
+    /** Check if FTS5 is available. */
+    isFTS5Available() {
+        return this.fts5Available;
+    }
+}
+//# sourceMappingURL=MemoryFTS.js.map

package/dist/memory/MemoryFTS.js.map

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

package/dist/memory/MemoryGC.d.ts

@@ -0,0 +1,40 @@
+/**
+ * MemoryGC — Garbage collection for expired memory entries.
+ *
+ * Scans memory entries for TTL/expiresAt fields in frontmatter and removes
+ * entries that have expired. Integrated into MemoryMaintenance time gate.
+ *
+ * Configuration via config.memory.gc:
+ * - enabled: boolean (default false)
+ * - dry_run: boolean (default false) — log expired entries without deleting
+ * - max_deletions: number (default 50) — cap per GC run
+ * - interval_days: number (default 1) — minimum days between GC runs
+ * - protected_types: MemoryType[] (default ['user']) — never GC these types
+ */
+export interface MemoryGCOptions {
+    /** Memory root directory to scan. */
+    memoryRoot: string;
+    /** Dry run mode: log but don't delete. Default false. */
+    dryRun?: boolean;
+    /** Maximum deletions per GC run. Default 50. */
+    maxDeletions?: number;
+    /** Memory types that should never be GC'd. Default ['user']. */
+    protectedTypes?: string[];
+    /** Optional progress reporter. */
+    reporter?: (msg: string) => void;
+}
+export interface MemoryGCResult {
+    scanned: number;
+    expired: number;
+    deleted: number;
+    errors: number;
+    dryRun: boolean;
+}
+/**
+ * Run garbage collection on expired memory entries.
+ *
+ * @param options GC options.
+ * @returns GC result with scan/delete statistics.
+ */
+export declare function runMemoryGC(options: MemoryGCOptions): MemoryGCResult;
+//# sourceMappingURL=MemoryGC.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryGC.d.ts","sourceRoot":"","sources":["../../src/memory/MemoryGC.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,MAAM,WAAW,eAAe;IAC9B,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,kCAAkC;IAClC,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;CACjB;AAuFD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,cAAc,CA4DpE"}