autosnippet/dist/lib/agent/memory/PersistentMemory.d.ts

Extract code patterns into a knowledge base for AI coding assistants

/**
 * PersistentMemory — 持久化语义记忆 (Tier 3) — Facade
 *
 * 统一的项目级永久记忆存储，使用 SQLite 提供:
 *   - 重要性评分 (importance 1.0-10.0)
 *   - 综合检索 (recency × importance × relevance)
 *   - Extract-Update 模式固化 (ADD / UPDATE / MERGE / NOOP)
 *   - Mem0 风格冲突解决 (矛盾检测 + 自动替换)
 *   - TTL 自动过期 + 访问计数
 *   - 向量嵌入预留接口
 *   - 预算感知 toPromptSection
 *
 * 内部委托:
 *   - MemoryStore        — CRUD + SQL 基础设施
 *   - MemoryRetriever    — 三维打分检索 + Prompt 生成
 *   - MemoryConsolidator — 智能固化 + 冲突解决
 *
 * 记忆类型: fact / insight / preference
 * 来源: bootstrap / user / system
 *
 * @module PersistentMemory
 */
import type { CandidateMemory, ConsolidateOptions, ConsolidateStats } from './MemoryConsolidator.js';
import type { MemoryEmbeddingStore } from './MemoryEmbeddingStore.js';
import type { AppendEntry, EmbeddingFn, LoadOptions, PromptSectionOptions, RetrieveOptions, ScoredMemory } from './MemoryRetriever.js';
import type { DeserializedMemory, MemoryInput, MemoryUpdates, SqliteDatabase } from './MemoryStore.js';
/** PersistentMemory 构造选项 */
export interface PersistentMemoryOptions {
    logger?: MemoryLogger | null;
    embeddingFn?: EmbeddingFn;
    embeddingStore?: MemoryEmbeddingStore;
}
/** Logger 接口 */
interface MemoryLogger {
    info(msg: string): void;
    warn?(msg: string): void;
    debug?(msg: string): void;
}
/** 数据库包装器 (getDb 模式) */
interface DbWrapper {
    getDb(): SqliteDatabase;
}
export declare class PersistentMemory {
    #private;
    /** @param db better-sqlite3 实例 */
    constructor(db: SqliteDatabase | DbWrapper, opts?: PersistentMemoryOptions);
    /** 添加一条记忆 */
    add(memory: MemoryInput): {
        id: string;
        action: string;
    };
    /** 更新已有记忆 */
    update(id: string, updates: MemoryUpdates): boolean;
    /** 删除一条记忆 */
    delete(id: string): boolean;
    /** 按 ID 获取 */
    get(id: string): DeserializedMemory | null;
    /** 智能固化 (ADD / UPDATE / MERGE / NOOP + 冲突解决) */
    consolidate(candidateMemories: CandidateMemory[], opts?: ConsolidateOptions): ConsolidateStats;
    /** 三维打分综合检索 (含向量相关性) */
    retrieve(query: string, opts?: RetrieveOptions): Promise<ScoredMemory[]>;
    /** 简单文本搜索 */
    search(content: string, opts?: {
        limit?: number;
    }): DeserializedMemory[];
    /** 预算感知 Prompt section */
    toPromptSection(opts?: PromptSectionOptions): Promise<string>;
    /** 兼容 Memory.load() */
    load(limit: number, opts?: LoadOptions): {
        ts: string;
        type: string;
        content: string;
        source: string;
        importance: number;
    }[];
    /** 兼容 Memory.append() */
    append(entry: AppendEntry): void;
    /** 记忆总数 */
    size(opts?: {
        source?: string;
    }): number;
    /** 维护: 过期清理 + 容量控制 */
    compact(): {
        expired: number;
        forgotten: number;
        archived: number;
        remaining: number;
    };
    /** 获取统计信息 */
    getStats(): {
        total: number;
        byType: {
            [k: string]: number;
        };
        bySource: {
            [k: string]: number;
        };
        avgImportance: number;
    };
    /** 清除所有 bootstrap 来源的记忆 */
    clearBootstrapMemories(): number;
    /** 从旧版 Memory.js JSONL 文件迁移 */
    migrateFromLegacy(projectRoot: string): Promise<{
        migrated: number;
        skipped: number;
        error?: string;
    }>;
    /** 设置向量嵌入函数 */
    setEmbeddingFunction(fn: EmbeddingFn | null): void;
    /** 获取当前嵌入函数 */
    getEmbeddingFunction(): EmbeddingFn | null;
    /**
     * 为所有缺少 embedding 的记忆批量生成向量嵌入
     * @param batchSize 每批数量
     * @returns 成功嵌入的记忆数
     */
    embedAllMemories(batchSize?: number): Promise<number>;
    /**
     * 计算语义相关性 (异步，使用向量余弦相似度)
     * @param query 查询文本
     * @param content 记忆内容
     * @returns 相似度分数 或 null
     */
    computeEmbeddingRelevance(query: string, content: string): Promise<number | null>;
}
export { PersistentMemory as ProjectSemanticMemory };
export default PersistentMemory;