/**
 * Memory Quality Feedback Loop — BRAIN self-improvement system.
 *
 * Closes the retrieval→usage→outcome loop so that memory quality scores
 * reflect real-world utility, not just insert-time heuristics.
 *
 * Three operations:
 *
 * 1. trackMemoryUsage — record whether a retrieved memory was actually used
 *    by an agent after task completion.
 *
 * 2. correlateOutcomes — scan the retrieval log, join against task outcomes,
 *    and apply quality adjustments:
 *      - Memory retrieved before a successful task completion: +0.05
 *      - Memory retrieved before a failed task: -0.05
 *      - Memory never retrieved in 30 days: flagged for pruning
 *
 * 3. getMemoryQualityReport — dashboard metrics over the entire brain.db.
 *
 * Schema addition: brain_usage_log (entry_id, task_id, used, outcome, created_at).
 * The table is self-healing — created on first access.
 *
 * @task T555
 */
/**
 * Outcome of a task that used a retrieved memory.
 * - `success`  — task completed successfully (boosts quality score).
 * - `failure`  — task failed (penalises quality score).
 * - `verified` — gate verification triggered (neutral; records lifecycle touch).
 * - `unknown`  — outcome not yet resolved.
 */
export type MemoryOutcome = 'success' | 'failure' | 'verified' | 'unknown';
/** A single row in brain_usage_log. */
export interface UsageLogRow {
    id: number;
    entry_id: string;
    task_id: string | null;
    used: number;
    outcome: string;
    created_at: string;
}
/** Aggregate memory statistics for the quality report. */
export interface MemoryQualityReport {
    /** Total rows in brain_retrieval_log. */
    totalRetrievals: number;
    /** Count of distinct entry IDs that have ever been retrieved. */
    uniqueEntriesRetrieved: number;
    /** Ratio of usage_log rows with used=1 over total usage_log rows (0–1). */
    usageRate: number;
    /** Top 10 entries sorted by citation_count descending. */
    topRetrieved: Array<{
        id: string;
        type: string;
        title: string;
        citationCount: number;
    }>;
    /** Up to 10 entries with citation_count = 0, candidates for pruning. */
    neverRetrieved: Array<{
        id: string;
        type: string;
        title: string;
        qualityScore: number;
    }>;
    /** Distribution of quality scores bucketed into [0.0,0.3), [0.3,0.6), [0.6,1.0]. */
    qualityDistribution: {
        low: number;
        medium: number;
        high: number;
    };
    /** Count of entries per memory tier. */
    tierDistribution: {
        short: number;
        medium: number;
        long: number;
        unknown: number;
    };
    /** Ratio of entries with quality_score < 0.3 to total entries. */
    noiseRatio: number;
}
/** Result of a correlateOutcomes run. */
export interface CorrelateOutcomesResult {
    /** Number of entries that received a quality boost (+0.05). */
    boosted: number;
    /** Number of entries that received a quality penalty (-0.05). */
    penalized: number;
    /** Number of entries flagged for pruning (prune_candidate = 1). */
    flaggedForPruning: number;
    /** Timestamp of this run (ISO string). */
    ranAt: string;
}
/**
 * Record whether a retrieved memory entry was actually used by an agent.
 *
 * Call this after task completion, once the agent has decided which retrieved
 * entries were referenced. Inserts a row into brain_usage_log; the
 * correlateOutcomes pass will read these rows to adjust quality scores.
 *
 * @param projectRoot - Project root directory
 * @param memoryId    - The brain entry ID (e.g. "O-...", "D-...", "P-...")
 * @param used        - Whether the agent actually used this entry
 * @param taskId      - Optional task ID for outcome correlation
 * @param outcome     - Optional task outcome; defaults to 'unknown' until correlated
 */
export declare function trackMemoryUsage(projectRoot: string, memoryId: string, used: boolean, taskId?: string, outcome?: MemoryOutcome): Promise<void>;
/**
 * Analyse the retrieval log and usage log against task outcomes, then
 * adjust quality scores to reflect real-world utility.
 *
 * Algorithm:
 *   1. Read brain_usage_log where outcome != 'unknown' — these are rows
 *      already tagged with a definitive outcome.
 *   2. For success rows: boost quality_score by +0.05 for each entry used.
 *   3. For failure rows: penalise quality_score by -0.05 for each entry used.
 *   4. Flag entries whose citation_count = 0 AND last retrieval (if any) is
 *      older than 30 days as prune candidates.
 *
 * This is designed to be idempotent — running it twice on the same data
 * applies the delta twice (small, intentional drift toward ground truth).
 * Callers should schedule it once per session end or per task batch.
 *
 * @param projectRoot - Project root directory
 * @returns Summary of changes made
 */
export declare function correlateOutcomes(projectRoot: string): Promise<CorrelateOutcomesResult>;
/**
 * Return dashboard-level quality metrics for the BRAIN memory system.
 *
 * Aggregates across all four typed tables (decisions, patterns, learnings,
 * observations) and the retrieval log to produce a single report object.
 *
 * @param projectRoot - Project root directory
 * @returns Quality metrics report
 */
export declare function getMemoryQualityReport(projectRoot: string): Promise<MemoryQualityReport>;
//# sourceMappingURL=quality-feedback.d.ts.map