clementine-agent 1.2.2 → 1.3.0

package/dist/memory/integrity.js

@@ -0,0 +1,119 @@
+/**
+ * Memory store integrity probes — self-healing checks that run on the
+ * janitor's periodic cycle. Each probe is independent and conservative:
+ *  - reports what it found,
+ *  - repairs only when the fix is non-destructive,
+ *  - never throws (logs and continues).
+ *
+ * Three checks today (the cheap, high-value ones):
+ *   1. FTS5 contentless-table integrity → auto-rebuild on failure
+ *   2. derived_from references to deleted chunks → nullify the dangling refs
+ *   3. chunks with content but no embedding → return count for backfill
+ *
+ * Graph reachability is intentionally NOT probed here — it lives in
+ * graph-store.ts's own health probe, which auto-restarts FalkorDB.
+ */
+import pino from 'pino';
+const logger = pino({ name: 'clementine.integrity' });
+/**
+ * Run all probes and apply safe repairs. Returns a report; never throws.
+ * The store argument is typed loose so this module can be called from
+ * maintenance.ts without an import cycle.
+ */
+export function runIntegrityProbes(store) {
+    const report = {
+        ftsOk: true,
+        ftsRebuilt: false,
+        orphanRefsNulled: 0,
+        missingEmbeddings: 0,
+    };
+    // 1. FTS5 integrity. Contentless tables can corrupt under specific failure
+    //    modes (process kill mid-trigger, manual SQL on chunks_fts, etc.).
+    //    integrity-check returns 'ok' on success; rebuild is the standard fix.
+    try {
+        const conn = store.conn;
+        if (conn) {
+            try {
+                const row = conn.prepare(`INSERT INTO chunks_fts(chunks_fts) VALUES('integrity-check') RETURNING ''`).get();
+                // 'integrity-check' is a no-op insert that throws on failure. If we
+                // got a row back, FTS is fine. (Some SQLite builds don't support the
+                // RETURNING form on virtual tables — fall back to plain run().)
+                void row;
+            }
+            catch (innerErr) {
+                // Try the plain form before declaring failure.
+                try {
+                    conn.prepare(`INSERT INTO chunks_fts(chunks_fts) VALUES('integrity-check')`).run();
+                }
+                catch {
+                    report.ftsOk = false;
+                    logger.warn({ err: innerErr }, 'FTS5 integrity check failed — rebuilding');
+                    try {
+                        conn.prepare(`INSERT INTO chunks_fts(chunks_fts) VALUES('rebuild')`).run();
+                        report.ftsRebuilt = true;
+                    }
+                    catch (rebuildErr) {
+                        logger.warn({ err: rebuildErr }, 'FTS5 rebuild failed');
+                    }
+                }
+            }
+        }
+    }
+    catch (err) {
+        logger.warn({ err }, 'FTS integrity probe error');
+    }
+    // 2. derived_from dangling references. Phase-2 janitor deletes a chunk
+    //    that was a source for a summary; we keep the summary but the JSON
+    //    array of source ids may now contain ids that no longer exist. Walk
+    //    summary chunks, prune missing ids; fully empty array → null.
+    try {
+        const conn = store.conn;
+        if (conn) {
+            const summaries = conn.prepare(`SELECT id, derived_from FROM chunks
+         WHERE derived_from IS NOT NULL AND derived_from != ''`).all();
+            const liveCheck = conn.prepare('SELECT 1 FROM chunks WHERE id = ?');
+            const updateStmt = conn.prepare('UPDATE chunks SET derived_from = ? WHERE id = ?');
+            for (const s of summaries) {
+                let ids;
+                try {
+                    ids = JSON.parse(s.derived_from);
+                }
+                catch {
+                    continue;
+                }
+                if (!Array.isArray(ids))
+                    continue;
+                const live = ids.filter((id) => {
+                    if (typeof id !== 'number')
+                        return false;
+                    return !!liveCheck.get(id);
+                });
+                if (live.length !== ids.length) {
+                    updateStmt.run(live.length === 0 ? null : JSON.stringify(live), s.id);
+                    report.orphanRefsNulled++;
+                }
+            }
+        }
+    }
+    catch (err) {
+        logger.warn({ err }, 'derived_from orphan probe failed');
+    }
+    // 3. Missing dense embeddings — a counter for the dashboard / next backfill
+    //    cycle. Doesn't repair (backfill is async + heavy); just surfaces.
+    try {
+        const conn = store.conn;
+        if (conn) {
+            const row = conn.prepare(`SELECT COUNT(*) AS c FROM chunks c
+         LEFT JOIN chunk_soft_deletes sd ON sd.chunk_id = c.id
+         WHERE sd.chunk_id IS NULL
+           AND c.embedding_dense IS NULL
+           AND length(c.content) > 0`).get();
+            report.missingEmbeddings = row.c;
+        }
+    }
+    catch (err) {
+        logger.warn({ err }, 'Missing-embedding probe failed');
+    }
+    return report;
+}
+//# sourceMappingURL=integrity.js.map

package/dist/memory/maintenance.d.ts

@@ -4,9 +4,30 @@
  * Runs startup and periodic maintenance so the memory store stays healthy
  * without manual intervention. New users get this out of the box.
  *
- * Startup: decay salience, prune stale data, backfill embeddings
- * Periodic (every 6h): full consolidation cycle + embedding rebuild
+ * Startup: decay salience, prune stale data, backfill embeddings, run janitor
+ * Periodic (every 6h): full consolidation cycle + embedding rebuild + janitor
+ *                      + idle-gated VACUUM at most once per week
  */
+/**
+ * Janitor pass — keeps the store bounded. Safe to call repeatedly.
+ * Idempotent within a single run; surfaces totals for logging.
+ */
+export declare function runJanitor(store: any): {
+    softDeleted: number;
+    physicallyDeleted: number;
+    outcomesPruned: number;
+    extractionsCapped: number;
+};
+/**
+ * Run VACUUM if (a) it's been more than vacuumIntervalDays since the last
+ * one and (b) the store has been idle for at least vacuumIdleSeconds.
+ * Returns null when skipped, otherwise the size delta.
+ */
+export declare function maybeVacuum(store: any): {
+    sizeBeforeBytes: number;
+    sizeAfterBytes: number;
+    durationMs: number;
+} | null;
 /**
  * Run one-time maintenance at daemon startup.
  * Non-blocking — errors are logged but never thrown.

package/dist/memory/maintenance.js

@@ -4,12 +4,82 @@
  * Runs startup and periodic maintenance so the memory store stays healthy
  * without manual intervention. New users get this out of the box.
  *
- * Startup: decay salience, prune stale data, backfill embeddings
- * Periodic (every 6h): full consolidation cycle + embedding rebuild
+ * Startup: decay salience, prune stale data, backfill embeddings, run janitor
+ * Periodic (every 6h): full consolidation cycle + embedding rebuild + janitor
+ *                      + idle-gated VACUUM at most once per week
  */
 import pino from 'pino';
+import { MEMORY_JANITOR } from '../config.js';
+import { runIntegrityProbes } from './integrity.js';
 const logger = pino({ name: 'clementine.maintenance' });
 const PERIODIC_INTERVAL_MS = 6 * 60 * 60 * 1000; // 6 hours
+const VACUUM_META_KEY = 'last_vacuum_at';
+/**
+ * Janitor pass — keeps the store bounded. Safe to call repeatedly.
+ * Idempotent within a single run; surfaces totals for logging.
+ */
+export function runJanitor(store) {
+    let softDeleted = 0;
+    let physicallyDeleted = 0;
+    try {
+        const result = store.expireConsolidated?.({
+            expireDays: MEMORY_JANITOR.consolidatedExpireDays,
+            salienceFloor: MEMORY_JANITOR.consolidatedSalienceFloor,
+            graceDays: MEMORY_JANITOR.softDeleteGraceDays,
+        });
+        if (result) {
+            softDeleted = result.softDeleted;
+            physicallyDeleted = result.physicallyDeleted;
+        }
+    }
+    catch (err) {
+        logger.warn({ err }, 'expireConsolidated failed');
+    }
+    let outcomesPruned = 0;
+    try {
+        outcomesPruned = store.pruneOutcomes?.(MEMORY_JANITOR.auxRetentionDays) ?? 0;
+    }
+    catch (err) {
+        logger.warn({ err }, 'pruneOutcomes failed');
+    }
+    let extractionsCapped = 0;
+    try {
+        extractionsCapped = store.capExtractions?.(MEMORY_JANITOR.extractionsMaxRows) ?? 0;
+    }
+    catch (err) {
+        logger.warn({ err }, 'capExtractions failed');
+    }
+    return { softDeleted, physicallyDeleted, outcomesPruned, extractionsCapped };
+}
+/**
+ * Run VACUUM if (a) it's been more than vacuumIntervalDays since the last
+ * one and (b) the store has been idle for at least vacuumIdleSeconds.
+ * Returns null when skipped, otherwise the size delta.
+ */
+export function maybeVacuum(store) {
+    try {
+        const lastIso = store.getMaintenanceMeta?.(VACUUM_META_KEY);
+        if (lastIso) {
+            const last = new Date(lastIso).getTime();
+            const ageMs = Date.now() - last;
+            if (ageMs < MEMORY_JANITOR.vacuumIntervalDays * 86_400_000)
+                return null;
+        }
+        const lastActivity = store.lastActivityAt?.();
+        if (lastActivity !== null && lastActivity !== undefined) {
+            const idleMs = Date.now() - lastActivity;
+            if (idleMs < MEMORY_JANITOR.vacuumIdleSeconds * 1000)
+                return null;
+        }
+        const result = store.vacuum?.();
+        store.setMaintenanceMeta?.(VACUUM_META_KEY, new Date().toISOString());
+        return result ?? null;
+    }
+    catch (err) {
+        logger.warn({ err }, 'VACUUM failed');
+        return null;
+    }
+}
 /**
  * Run one-time maintenance at daemon startup.
  * Non-blocking — errors are logged but never thrown.
@@ -56,6 +126,32 @@ export async function runStartupMaintenance(store) {
     catch {
         // Table may not exist yet — non-fatal
     }
+    // Janitor — bounded growth pass.
+    try {
+        const result = runJanitor(store);
+        if (result.softDeleted || result.physicallyDeleted || result.outcomesPruned || result.extractionsCapped) {
+            logger.info(result, 'Janitor pass complete');
+        }
+    }
+    catch (err) {
+        logger.warn({ err }, 'Startup janitor failed');
+    }
+    // Embedding warm-up — pre-embed the most-cited chunks in the background so
+    // the first retrievals after startup don't pay cold-start latency. Fire
+    // and forget; never blocks startup.
+    if (typeof store.warmDenseEmbeddings === 'function') {
+        void (async () => {
+            try {
+                const result = await store.warmDenseEmbeddings(200);
+                if (result.warmed > 0) {
+                    logger.info(result, 'Embedding warm-up complete');
+                }
+            }
+            catch (err) {
+                logger.warn({ err }, 'Embedding warm-up failed');
+            }
+        })();
+    }
     logger.info({ durationMs: Date.now() - start }, 'Startup maintenance complete');
 }
 /**
@@ -104,7 +200,7 @@ export function startPeriodicMaintenance(store, llmCall) {
                 logger.warn({ err }, 'Post-consolidation embedding build failed');
             }
         }
-        // 5. Extraction log pruning
+        // 5. Extraction log pruning (legacy 90-day rule retained alongside cap)
         try {
             const conn = store.conn;
             if (conn) {
@@ -114,6 +210,47 @@ export function startPeriodicMaintenance(store, llmCall) {
             }
         }
         catch { /* non-fatal */ }
+        // 6. Janitor — bounded growth.
+        try {
+            const result = runJanitor(store);
+            if (result.softDeleted || result.physicallyDeleted || result.outcomesPruned || result.extractionsCapped) {
+                logger.info(result, 'Janitor pass complete');
+            }
+        }
+        catch (err) {
+            logger.warn({ err }, 'Periodic janitor failed');
+        }
+        // 6b. Integrity probes — FTS health, orphan derived_from, embedding gaps.
+        try {
+            const report = runIntegrityProbes(store);
+            // Persist for the dashboard so the "last integrity check" surface
+            // doesn't depend on log scraping.
+            try {
+                store.setMaintenanceMeta?.('last_integrity_report', JSON.stringify({ ...report, ranAt: new Date().toISOString() }));
+            }
+            catch { /* meta write is best-effort */ }
+            if (!report.ftsOk || report.ftsRebuilt || report.orphanRefsNulled > 0 || report.missingEmbeddings > 0) {
+                logger.info(report, 'Integrity probes complete');
+            }
+        }
+        catch (err) {
+            logger.warn({ err }, 'Integrity probes failed');
+        }
+        // 7. VACUUM — idle-gated, at most once per vacuumIntervalDays.
+        try {
+            const vac = maybeVacuum(store);
+            if (vac) {
+                logger.info({
+                    sizeBeforeBytes: vac.sizeBeforeBytes,
+                    sizeAfterBytes: vac.sizeAfterBytes,
+                    reclaimedBytes: vac.sizeBeforeBytes - vac.sizeAfterBytes,
+                    durationMs: vac.durationMs,
+                }, 'VACUUM complete');
+            }
+        }
+        catch (err) {
+            logger.warn({ err }, 'Periodic VACUUM failed');
+        }
         logger.info({ durationMs: Date.now() - start }, 'Periodic maintenance complete');
     };
     return setInterval(runCycle, PERIODIC_INTERVAL_MS);

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.
      */