clementine-agent 1.2.1 → 1.2.3

package/dist/memory/store.d.ts

@@ -10,6 +10,8 @@
  * (single-user, one MCP subprocess handles all writes).
  */
 import type { Feedback, MemoryExtraction, SearchResult, SessionSummary, SyncStats, TranscriptTurn, WikilinkConnection } from '../types.js';
+import { HotCache } from './hot-cache.js';
+import { type WriteQueueOpts } from './write-queue.js';
 export declare class MemoryStore {
     private dbPath;
     private vaultDir;
@@ -17,6 +19,8 @@ export declare class MemoryStore {
     private _stmtChunkCount;
     private _stmtInsertTranscript;
     private _stmtInsertUsage;
+    private chunkRowCache;
+    private writeQueue;
     constructor(dbPath: string, vaultDir: string);
     /**
      * Create the database and schema if needed.
@@ -215,6 +219,25 @@ export declare class MemoryStore {
         category?: string;
         topic?: string;
     }, strict?: boolean): SearchResult[];
+    /**
+     * 1-hop wikilink expansion: for each seed chunk's source_file, find files
+     * that link to it or that it links to, and pull their top chunks. Returns
+     * SearchResult-shaped rows with a fractional boost so they enter the
+     * candidate pool below the seed scores but above pure noise.
+     *
+     * Pattern: 2026-frontier agent memory uses graph expansion (Mem0g, Zep
+     * Graphiti) to surface chunks that share an entity but miss the lexical
+     * match. Wikilinks are the cheapest available edge — Clementine already
+     * extracts them on every vault sync. The richer FalkorDB graph adds
+     * temporal validity and entity types but isn't required for this lift.
+     */
+    expandViaWikilinks(seeds: SearchResult[], opts?: {
+        boost?: number;
+        limitPerFile?: number;
+        maxNeighbors?: number;
+        agentSlug?: string;
+        strict?: boolean;
+    }): SearchResult[];
     /**
      * Combined FTS5 relevance + recency search for context injection.
      *
@@ -223,6 +246,7 @@ export declare class MemoryStore {
      * 2. Recency fetch -> N most recent chunks
      * 3. Deduplicate by (source_file, section)
      * 4. Apply salience boost to FTS results
+     * 5. Wikilink graph expansion -> 1-hop neighbors of top seeds (boost 0.7×)
      */
     searchContext(query: string, limitOrOpts?: number | {
         limit?: number;
@@ -252,6 +276,15 @@ export declare class MemoryStore {
         scores: number[];
         agentSlug?: string | null;
     }): void;
+    /** Internal sync recall_trace insert. Called by the WriteQueue. */
+    _logRecallTraceSync(opts: {
+        sessionKey: string;
+        messageId?: string | null;
+        query: string;
+        chunkIds: number[];
+        scores: number[];
+        agentSlug?: string | null;
+    }): void;
     /**
      * Fetch recent recall traces for a session, newest first.
      * Used by the dashboard chat panel to show "what memory powered this answer".
@@ -303,6 +336,25 @@ export declare class MemoryStore {
         salience: number;
         updatedAt: string;
     }>;
+    /** Cache stats for the dashboard / debugging. */
+    getChunkCacheStats(): ReturnType<HotCache<number, unknown>['stats']>;
+    /**
+     * Enable the write-behind queue. After this call, saveTurn / recordAccess /
+     * recordOutcome / logRecallTrace enqueue instead of running SQL on the
+     * caller's thread. Idempotent. Tests leave this off and rely on the sync path.
+     */
+    enableWriteQueue(opts?: WriteQueueOpts): void;
+    /** Drain and stop the write queue. Call on graceful shutdown. */
+    flushWrites(): Promise<void>;
+    /** Stats for the dashboard / debugging. Returns null when queue disabled. */
+    getWriteQueueStats(): {
+        size: number;
+        dropped: number;
+    } | null;
+    /** Drop a single cache entry — called from mutations that touch a chunk. */
+    invalidateChunkCache(chunkId: number): void;
+    /** Drop the whole cache — fullSync and similar bulk operations call this. */
+    clearChunkCache(): void;
     private _parseJsonArray;
     /** The fixed slot vocabulary. Adding new slots is a code change so the
      *  agent doesn't sprawl into ad-hoc namespaces. */
@@ -366,6 +418,19 @@ export declare class MemoryStore {
      * async, which propagates up the entire searchContext chain.
      */
     private searchByDenseEmbedding;
+    /**
+     * Pre-embed the top N most-cited chunks at startup. Eliminates cold-start
+     * latency for the chunks the agent is most likely to retrieve next. Skips
+     * chunks that already have a current-model dense embedding.
+     *
+     * Ranking: by outcome citation count in the last 30d (chunks the agent
+     * actually used), tiebroken by recency. Soft-deleted excluded.
+     */
+    warmDenseEmbeddings(topN?: number): Promise<{
+        warmed: number;
+        skipped: number;
+        failed: number;
+    }>;
     /**
      * Backfill dense embeddings on chunks that don't yet have one (or that
      * were embedded by an older model). Async because the dense model itself
@@ -396,9 +461,12 @@ export declare class MemoryStore {
      */
     getConnections(noteName: string): WikilinkConnection[];
     /**
-     * Save a conversation turn to the transcripts table.
+     * Save a conversation turn to the transcripts table. Routes through the
+     * write queue when enabled so the request thread doesn't block on SQL.
      */
     saveTurn(sessionKey: string, role: string, content: string, model?: string): void;
+    /** Internal sync transcript insert. Called directly by the WriteQueue. */
+    _saveTurnSync(sessionKey: string, role: string, content: string, model: string): void;
     /**
      * Get all turns for a given session, ordered chronologically.
      */
@@ -426,9 +494,12 @@ export declare class MemoryStore {
      */
     getRecentSummaries(limit?: number): SessionSummary[];
     /**
-     * Record that chunks were accessed (retrieved/displayed).
+     * Record that chunks were accessed (retrieved/displayed). Routes through
+     * the write queue when enabled.
      */
     recordAccess(chunkIds: number[], accessType?: string): void;
+    /** Internal sync access log insert. Called directly by the WriteQueue. */
+    _recordAccessSync(chunkIds: number[], accessType: string): void;
     /**
      * Recompute salience score for a chunk based on access patterns.
      *
@@ -451,6 +522,11 @@ export declare class MemoryStore {
         chunkId: number;
         referenced: boolean;
     }>, sessionKey?: string | null): void;
+    /** Internal sync outcome insert + EMA update. Called by the WriteQueue. */
+    _recordOutcomeSync(outcomes: Array<{
+        chunkId: number;
+        referenced: boolean;
+    }>, sessionKey?: string | null): void;
     /**
      * Idempotent append for a batch of SDK session transcript entries.
      * Entries with a uuid are upserted on (session_id, subpath, uuid);
@@ -663,6 +739,127 @@ export declare class MemoryStore {
         usageLogPruned: number;
         recallTracesPruned: number;
     };
+    /**
+     * User-model slots whose `updated_at` is older than maxAgeDays. These are
+     * candidates for the "verify or refresh" nudge — high-relevance memories
+     * that may have become silently wrong (Mem0 2026 calls this out as an
+     * open problem; we surface it via observability rather than auto-decay).
+     *
+     * Empty content is skipped (an empty slot has no claim to verify).
+     */
+    findStaleUserModelSlots(opts?: {
+        maxAgeDays?: number;
+        agentSlug?: string | null;
+    }): Array<{
+        slot: string;
+        ageDays: number;
+        agentSlug: string | null;
+    }>;
+    /**
+     * High-salience chunks whose outcome EMA has drifted negative — i.e., we
+     * keep ranking them high but the agent stopped citing them. Strong signal
+     * that the chunk is stale or wrong even though salience hasn't decayed.
+     *
+     * Conservative threshold: salience > 0.8 AND last_outcome_score < 0.
+     * Soft-deleted excluded.
+     */
+    findStaleHighSalienceChunks(opts?: {
+        salienceFloor?: number;
+        outcomeCeiling?: number;
+        limit?: number;
+    }): Array<{
+        chunkId: number;
+        sourceFile: string;
+        section: string;
+        salience: number;
+        lastOutcomeScore: number;
+    }>;
+    /**
+     * Format staleness findings into ready-to-inject prompt text. Heartbeat
+     * builders can drop this into the system prompt verbatim. Returns null
+     * if there's nothing to nudge about — caller should not inject empty text.
+     */
+    getStalenessNudges(opts?: {
+        agentSlug?: string | null;
+        maxSlotAgeDays?: number;
+    }): string | null;
+    /**
+     * Find procedure chunks whose frontmatter `triggers` overlap with words
+     * in the query. Used to surface learned workflows ("how Nate ships a
+     * release", "how to handle inbound replies") above generic facts when
+     * the user's intent matches.
+     *
+     * Match rule: case-insensitive substring of any trigger phrase appears
+     * in the query. Empty result if no procedure chunks exist or no triggers
+     * match — caller should treat this as additive context, not the whole
+     * answer.
+     */
+    findRelevantProcedures(query: string, opts?: {
+        limit?: number;
+        agentSlug?: string | null;
+    }): Array<{
+        id: number;
+        sourceFile: string;
+        section: string;
+        content: string;
+        triggers: string[];
+        matched: string[];
+    }>;
+    /** Persistent key/value for janitor state (last vacuum, etc.). */
+    getMaintenanceMeta(key: string): string | null;
+    setMaintenanceMeta(key: string, value: string): void;
+    /**
+     * Two-phase delete for consolidated, low-salience, unused chunks.
+     *
+     * Phase 1: soft-delete chunks where consolidated=1, not pinned, salience
+     *          below floor, and never accessed (or last access older than
+     *          expireDays).
+     * Phase 2: physically delete chunks that have been in chunk_soft_deletes
+     *          for graceDays. Cascades to access_log, outcomes, chunk_history
+     *          for the same chunk_id.
+     *
+     * Summary chunks whose `derived_from` references the deleted IDs are
+     * intentionally NOT propagate-deleted — the summary still encodes signal.
+     */
+    expireConsolidated(opts?: {
+        expireDays?: number;
+        salienceFloor?: number;
+        graceDays?: number;
+    }): {
+        softDeleted: number;
+        physicallyDeleted: number;
+    };
+    /** Trim outcomes table to a rolling window. Append-only, can grow fast. */
+    pruneOutcomes(retentionDays?: number): number;
+    /**
+     * Cap memory_extractions to maxRows. Deletes oldest non-active rows first;
+     * 'active' extractions are preserved regardless of count to protect the
+     * audit trail for in-flight work.
+     */
+    capExtractions(maxRows?: number): number;
+    /** Approximate SQLite database file size on disk, in bytes. */
+    dbSizeBytes(): number;
+    /**
+     * VACUUM the database. Reclaims space from deleted rows. Holds an
+     * exclusive lock for the duration — caller is expected to gate on
+     * idleness (see lastActivityAt).
+     */
+    vacuum(): {
+        sizeBeforeBytes: number;
+        sizeAfterBytes: number;
+        durationMs: number;
+    };
+    /**
+     * Most recent timestamp across the high-write activity tables, as a Unix
+     * milliseconds value. Returns null if all tables are empty. Used by the
+     * janitor's idle gate.
+     *
+     * Implementation note: SQLite's datetime() returns "YYYY-MM-DD HH:MM:SS"
+     * in UTC with no timezone marker — JS Date.parse interprets that as local
+     * time and skews by the offset. We compute the unix epoch in SQL to avoid
+     * the bug entirely.
+     */
+    lastActivityAt(): number | null;
     /**
      * Get chunks within a date range, ordered chronologically.
      * Useful for "what happened last week" type queries.
@@ -904,6 +1101,66 @@ export declare class MemoryStore {
      * Reduces salience so they appear lower in search results (but aren't deleted).
      */
     markConsolidated(chunkIds: number[]): void;
+    /**
+     * Aggregate memory-health snapshot for the dashboard.
+     *
+     * Single-pass queries over each table; cheap enough to call on every
+     * dashboard tab visit without caching. Adds graph stats only if a
+     * graphStore is supplied and reachable.
+     */
+    getMemoryHealth(opts?: {
+        graphStore?: {
+            isAvailable(): boolean;
+            nodeCount?(): Promise<number>;
+            edgeCount?(): Promise<number>;
+        };
+        topCitedLimit?: number;
+    }): {
+        chunks: {
+            total: number;
+            consolidated: number;
+            pinned: number;
+            softDeleted: number;
+            zombieCount: number;
+        };
+        chunksByCategory: Array<{
+            category: string | null;
+            count: number;
+        }>;
+        tableRowCounts: Record<string, number>;
+        topCitedLast30d: Array<{
+            chunkId: number;
+            sourceFile: string;
+            section: string;
+            refCount: number;
+        }>;
+        staleUserModelSlots: Array<{
+            slot: string;
+            ageDays: number;
+            agentSlug: string | null;
+        }>;
+        staleHighSalienceChunks: Array<{
+            chunkId: number;
+            sourceFile: string;
+            section: string;
+            salience: number;
+            lastOutcomeScore: number;
+        }>;
+        chunkCacheStats: ReturnType<HotCache<number, unknown>['stats']>;
+        writeQueue: {
+            size: number;
+            dropped: number;
+        } | null;
+        lastIntegrityReport: {
+            ftsOk: boolean;
+            ftsRebuilt: boolean;
+            orphanRefsNulled: number;
+            missingEmbeddings: number;
+            ranAt: string;
+        } | null;
+        dbSizeBytes: number;
+        lastVacuumAt: string | null;
+    };
     /**
      * Get consolidation stats for monitoring.
      */