@dcyfr/ai 2.1.1 → 3.0.0

package/dist/ai/src/compaction/memory-compaction.d.ts

@@ -0,0 +1,138 @@
+/**
+ * @module compaction/memory-compaction
+ * @description Memory compaction utilities for FileMemoryAdapter.
+ *
+ * Extends context compaction to:
+ * 1. Deduplicate entries across file-based and mem0 backends
+ * 2. Use hybrid search (BM25 + vector) for dedup when SQLite index available
+ * 3. Consolidate conversation files >N days old into monthly summaries
+ * 4. Archive contradicted/stale facts instead of deleting
+ *
+ * @license MIT
+ * @copyright DCYFR Labs (https://www.dcyfr.ai)
+ */
+export interface MemoryEntry {
+    /** Unique ID */
+    id: string;
+    /** Memory content */
+    content: string;
+    /** Source backend: 'file' or 'mem0' */
+    source: 'file' | 'mem0';
+    /** SHA-256 of content */
+    hash: string;
+    /** Timestamp */
+    timestamp: string;
+    /** Topic/category */
+    topic?: string;
+    /** Owner (userId or agentId) */
+    owner?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+export interface DeduplicationResult {
+    /** Total entries before dedup */
+    totalBefore: number;
+    /** Total entries after dedup */
+    totalAfter: number;
+    /** Number of duplicates removed */
+    duplicatesRemoved: number;
+    /** Entries kept (deduplicated) */
+    entries: MemoryEntry[];
+    /** Duplicate pairs found */
+    duplicatePairs: Array<{
+        kept: string;
+        removed: string;
+        similarity: number;
+    }>;
+}
+export interface ConversationSummaryResult {
+    /** Number of conversation files processed */
+    filesProcessed: number;
+    /** Number of monthly summaries created */
+    summariesCreated: number;
+    /** Paths of created summary files */
+    summaryPaths: string[];
+    /** Paths of archived conversation files */
+    archivedPaths: string[];
+}
+export interface FactArchivalResult {
+    /** Number of facts evaluated */
+    factsEvaluated: number;
+    /** Number of stale facts archived */
+    factsArchived: number;
+    /** Archived facts with reasons */
+    archivedFacts: Array<{
+        id: string;
+        content: string;
+        reason: string;
+    }>;
+    /** Path to archive file */
+    archivePath: string;
+}
+export interface MemoryCompactionConfig {
+    /** Memory root directory (default: ~/.dcyfr/memory) */
+    rootDir: string;
+    /** Agent ID for namespacing */
+    agentId: string;
+    /** BM25 similarity threshold for dedup (0-1). Default: 0.85 */
+    dedupThreshold?: number;
+    /** Conversation retention period in days. Default: 30 */
+    retentionDays?: number;
+    /** Optional LLM function for fact contradiction detection */
+    llmCall?: (prompt: string, systemPrompt: string) => Promise<string>;
+    /** Optional embedding function for vector-based dedup */
+    embedFn?: (text: string) => Promise<number[]>;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+export declare class MemoryCompaction {
+    private readonly rootDir;
+    private readonly agentId;
+    private readonly dedupThreshold;
+    private readonly retentionDays;
+    private readonly llmCall?;
+    private readonly embedFn?;
+    private readonly debug;
+    constructor(config: MemoryCompactionConfig);
+    /**
+     * Deduplicate memory entries across file and mem0 backends.
+     *
+     * Algorithm:
+     * 1. Collect all entries from file backend
+     * 2. Collect all entries from mem0 backend (if provided)
+     * 3. Hash-based exact dedup (O(n))
+     * 4. Similarity-based fuzzy dedup (O(n²) but typically small n)
+     * 5. Keep file-backend entries over mem0 (file is source of truth)
+     */
+    deduplicateEntries(fileEntries: MemoryEntry[], mem0Entries?: MemoryEntry[]): DeduplicationResult;
+    /**
+     * Enhanced deduplication using vector embeddings when available.
+     * Falls back to BM25-only (textSimilarity) when embeddings unavailable.
+     */
+    deduplicateWithHybridSearch(entries: MemoryEntry[]): Promise<DeduplicationResult>;
+    /**
+     * Consolidate conversation files older than retentionDays into monthly summaries.
+     *
+     * 1. Scan conversations directory for files older than threshold
+     * 2. Group by month
+     * 3. Generate summary per month (LLM if available, else concatenate)
+     * 4. Write summary to summaries directory
+     * 5. Move original files to archive
+     */
+    compactConversations(): Promise<ConversationSummaryResult>;
+    /**
+     * Archive stale or contradicted facts to facts-archived.md.
+     *
+     * Strategy:
+     * 1. Read all facts from facts.md
+     * 2. Detect contradictions (LLM-powered when available)
+     * 3. Move stale/contradicted facts to facts-archived.md
+     * 4. Rewrite facts.md without archived entries
+     */
+    archiveStaleFacts(): Promise<FactArchivalResult>;
+    private _fallbackSummary;
+    private _detectContradictions;
+    private _detectContradictionsWithLLM;
+    private _detectContradictionsHeuristic;
+}
+//# sourceMappingURL=memory-compaction.d.ts.map

package/dist/ai/src/compaction/memory-compaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-compaction.d.ts","sourceRoot":"","sources":["../../../../packages/ai/src/compaction/memory-compaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAUH,MAAM,WAAW,WAAW;IAC1B,gBAAgB;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,qBAAqB;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,mBAAmB;IAClC,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kCAAkC;IAClC,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,4BAA4B;IAC5B,cAAc,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC9E;AAED,MAAM,WAAW,yBAAyB;IACxC,6CAA6C;IAC7C,cAAc,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,gBAAgB,EAAE,MAAM,CAAC;IACzB,qCAAqC;IACrC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,2CAA2C;IAC3C,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,gCAAgC;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,aAAa,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtE,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACrC,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACpE,yDAAyD;IACzD,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9C,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AA6LD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAA4D;IACrF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAsC;IAC/D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;gBAEpB,MAAM,EAAE,sBAAsB;IAY1C;;;;;;;;;OASG;IACH,kBAAkB,CAChB,WAAW,EAAE,WAAW,EAAE,EAC1B,WAAW,GAAE,WAAW,EAAO,GAC9B,mBAAmB;IA2FtB;;;OAGG;IACG,2BAA2B,CAC/B,OAAO,EAAE,WAAW,EAAE,GACrB,OAAO,CAAC,mBAAmB,CAAC;IAsF/B;;;;;;;;OAQG;IACG,oBAAoB,IAAI,OAAO,CAAC,yBAAyB,CAAC;IAuGhE;;;;;;;;OAQG;IACG,iBAAiB,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAkGtD,OAAO,CAAC,gBAAgB;YAqBV,qBAAqB;YASrB,4BAA4B;IAgC1C,OAAO,CAAC,8BAA8B;CAwBvC"}