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

Extract code patterns into a knowledge base for AI coding assistants

/**
 * MemoryStore — 持久化记忆 SQLite 存储层（Drizzle 类型安全版）
 *
 * 从 PersistentMemory.js 提取的 CRUD + SQL 基础设施。
 * 负责:
 *   - 基本 CRUD: add, update, delete, get
 *   - 批量查询: getAllActive, size, getStats
 *   - 访问计数: touchAccess
 *   - 容量控制: enforceCapacity
 *   - 维护: compact
 *   - 统计: getStats, clearBootstrapMemories
 *
 * 设计原则:
 *   - 大部分操作通过 Drizzle 类型安全 API
 *   - update() 使用 Drizzle 类型安全 partial update
 *   - embedding 已迁移至 MemoryEmbeddingStore (JSON sidecar)
 *   - 数据序列化/反序列化统一在此层处理
 *
 * @module MemoryStore
 */
/** better-sqlite3 Database 结构接口 */
export interface SqliteDatabase {
    prepare(sql: string): SqliteStatement;
    exec(sql: string): void;
    transaction<T extends (...args: unknown[]) => unknown>(fn: T): T;
}
/** better-sqlite3 Statement 结构接口 */
export interface SqliteStatement {
    run(...params: unknown[]): {
        changes: number;
        lastInsertRowid: number | bigint;
    };
    get(...params: unknown[]): Record<string, unknown> | undefined;
    all(...params: unknown[]): Record<string, unknown>[];
}
/** 数据库行 (raw row from SQLite — 保持向后兼容) */
export interface MemoryRow {
    id: string;
    type: string;
    content: string;
    source: string;
    importance: number;
    access_count: number;
    last_accessed_at: string | null;
    created_at: string;
    updated_at: string;
    expires_at: string | null;
    related_entities: string;
    related_memories: string;
    source_dimension: string | null;
    source_evidence: string | null;
    bootstrap_session: string | null;
    tags: string;
    /** findSimilar 附加字段 */
    similarity?: number;
    related_memories_raw?: string;
}
/** 反序列化后的记忆对象 */
export interface DeserializedMemory {
    id: string;
    type: string;
    content: string;
    source: string;
    importance: number;
    accessCount: number;
    lastAccessedAt: string | null;
    createdAt: string;
    updatedAt: string;
    expiresAt: string | null;
    relatedEntities: string[];
    relatedMemories: string[];
    sourceDimension: string | null;
    sourceEvidence: string | null;
    bootstrapSession: string | null;
    tags: string[];
}
/** 添加记忆时的输入 */
export interface MemoryInput {
    type?: string;
    content: string;
    source?: string;
    importance?: number;
    ttlDays?: number | null;
    relatedEntities?: string[];
    sourceDimension?: string | null;
    sourceEvidence?: string | null;
    bootstrapSession?: string | null;
    tags?: string[];
}
/** 更新记忆时的字段 */
export interface MemoryUpdates {
    content?: string;
    importance?: number;
    accessCount?: number;
    relatedEntities?: string[];
    relatedMemories?: string[];
    tags?: string[];
}
export declare class MemoryStore {
    #private;
    /** @param db better-sqlite3 实例 (raw) */
    constructor(db: SqliteDatabase);
    /** 获取原始 db 引用 (for transaction) */
    get db(): SqliteDatabase;
    /**
     * 添加一条记忆
     * @returns }
     */
    add(memory: MemoryInput): {
        id: string;
        action: string;
    };
    /**
     * 更新已有记忆
     */
    update(id: string, updates: MemoryUpdates): boolean;
    /** 删除一条记忆 */
    delete(id: string): boolean;
    /** 按 ID 获取 */
    get(id: string): DeserializedMemory | null;
    /**
     * 获取所有活跃记忆 (未过期)
     * @returns raw rows
     */
    getAllActive({ source, type }?: {
        source?: string;
        type?: string;
    }): MemoryRow[];
    /** 获取候选记忆 (用于相似度搜索) */
    getCandidates(type: string | null): MemoryRow[];
    /** 更新访问计数 */
    touchAccess(id: string): void;
    /** 记忆总数 */
    size({ source }?: {
        source?: string;
    }): number;
    /**
     * 执行维护: 清理过期记忆 + 容量控制
     * @returns }
     */
    compact(): {
        expired: number;
        forgotten: number;
        archived: number;
        remaining: number;
    };
    /** 容量控制 */
    enforceCapacity(): void;
    /** 获取统计信息 */
    getStats(): {
        total: number;
        byType: {
            [k: string]: number;
        };
        bySource: {
            [k: string]: number;
        };
        avgImportance: number;
    };
    /** 清除所有 bootstrap 来源的记忆 */
    clearBootstrapMemories(): number;
    /**
     * 查找相似记忆 (基于 token overlap)
     * @param content 搜索文本
     * @param type 过滤 type (null=全部)
     * @param limit 返回条数
     * @returns 带 similarity 和 related_memories_raw 字段的 raw rows
     */
    findSimilar(content: string, type: string | null, limit: number): MemoryRow[];
    /**
     * 计算两段文本的相似度 (Jaccard + 子串匹配)
     * @returns 0.0-1.0
     */
    static computeSimilarity(tokensA: Set<string>, lowerA: string, contentB: string): number;
    /** 创建 transaction wrapper */
    transaction<T extends (...args: unknown[]) => unknown>(fn: T): T;
    /** 反序列化数据库行为域对象 */
    static deserialize(row: MemoryRow): DeserializedMemory;
    static safeParseJSON<T>(str: string | null | undefined, fallback: T): T;
}