/**
 * Public API for the memory domain — promoted from internal to public barrel.
 *
 * These functions are consumed by CLI commands (`packages/cleo`) and Studio
 * routes (`packages/studio`) and are therefore part of the stable public
 * surface of `@cleocode/core/memory`.
 *
 * None of these functions issue raw SQL; they compose over the existing
 * BRAIN retrieval, quality-feedback, decisions, patterns, and learnings
 * modules which own their respective schemas.
 *
 * @packageDocumentation
 * @task T9615
 * @epic T9592
 */
import type { MemoryDecisionRecord as DecisionRecord, LearningRecord, MemoryGraphStats, MemorySearchHit, PatternRecord } from '@cleocode/contracts';
export type { DecisionRecord, LearningRecord, MemoryGraphStats, MemorySearchHit, PatternRecord, };
/** Options for {@link findMemoryEntries}. */
export interface FindMemoryEntriesOptions {
    /** Text query; required. */
    query: string;
    /** Tables to search. Defaults to all four brain tables. */
    tables?: Array<'observations' | 'decisions' | 'patterns' | 'learnings'>;
    /** Maximum results per table (capped at 100). Defaults to 25. */
    limit?: number;
    /** Project root path; defaults to resolved root. */
    projectPath?: string;
}
/** Result of {@link findMemoryEntries}. */
export interface FindMemoryEntriesResult {
    /** Echo of the search query. */
    query: string;
    /** Flat list of matching entries across all tables. */
    hits: MemorySearchHit[];
    /** Total hits returned. */
    total: number;
}
/**
 * Cross-table LIKE search across all four brain tables.
 *
 * @param opts - Search options including query text, table filter, and limit
 * @returns Flat list of matching entries sorted by citation count descending
 *
 * @remarks
 * Uses LIKE-based scans. For heavy workloads, prefer the dispatch-layer
 * `memory.find` operation which uses the full RRF fusion pipeline.
 *
 * @example
 * ```typescript
 * const result = await findMemoryEntries({ query: 'authentication', limit: 10 });
 * console.log(`Found ${result.total} matches`);
 * ```
 *
 * @task T9615
 */
export declare function findMemoryEntries(opts: FindMemoryEntriesOptions): Promise<FindMemoryEntriesResult>;
/** A single brain observation record. */
export interface BrainObservation {
    /** Observation identifier. */
    id: string;
    /** Observation type tag. */
    type: string;
    /** Short title. */
    title: string;
    /** Optional subtitle. */
    subtitle: string | null;
    /** Full narrative text. */
    narrative: string | null;
    /** Project path scope. */
    project: string | null;
    /** Quality score in [0..1]. */
    qualityScore: number | null;
    /** Memory tier ('short' | 'medium' | 'long'). */
    memoryTier: string | null;
    /** Memory type tag. */
    memoryType: string | null;
    /** Owner-verified flag (1 = true, 0 = false). */
    verified: number;
    /** ISO timestamp when this observation became valid. */
    validAt: string | null;
    /** ISO timestamp when this observation was superseded. */
    invalidAt: string | null;
    /** Source confidence level. */
    sourceConfidence: string | null;
    /** Retrieval count. */
    citationCount: number;
    /** Whether this entry is a prune candidate. */
    pruneCandidate: number;
    /** ISO creation timestamp. */
    createdAt: string;
}
/** Options for {@link getObservations}. */
export interface GetObservationsOptions {
    /** Filter by memory tier ('short' | 'medium' | 'long'). */
    tier?: string;
    /** Filter by memory type. */
    type?: string;
    /** Minimum quality score (0..1). Entries with null score are excluded. */
    minQuality?: number;
    /** Maximum results (capped at 500). Defaults to 200. */
    limit?: number;
    /** Project root path; defaults to resolved root. */
    projectPath?: string;
}
/** Result of {@link getObservations}. */
export interface GetObservationsResult {
    /** Matching observations, ordered by creation time descending. */
    observations: BrainObservation[];
    /** Total rows in brain_observations regardless of filter. */
    total: number;
    /** Actual count returned. */
    filtered: number;
}
/**
 * List brain observations with optional filter by tier, type, and quality.
 *
 * @param opts - Optional filter and pagination options
 * @returns Paginated observation list plus total row count
 *
 * @example
 * ```typescript
 * const result = await getObservations({ tier: 'long', minQuality: 0.7 });
 * console.log(`${result.filtered} high-quality long-tier observations`);
 * ```
 *
 * @task T9615
 */
export declare function getObservations(opts?: GetObservationsOptions): Promise<GetObservationsResult>;
/** Options for {@link getDecisions}. */
export interface GetDecisionsOptions {
    /** FTS query string to filter decisions. Empty string returns all. */
    query?: string;
    /** Project root path; defaults to resolved root. */
    projectPath?: string;
    /** Maximum results. Defaults to 50. */
    limit?: number;
}
/**
 * Retrieve decision records from brain.db, optionally filtered by text query.
 *
 * @param opts - Query, project path, and limit options
 * @returns Array of decision records
 *
 * @example
 * ```typescript
 * const { decisions } = await getDecisions({ query: 'database architecture', limit: 20 });
 * ```
 *
 * @task T9615
 */
export declare function getDecisions(opts?: GetDecisionsOptions): Promise<{
    decisions: DecisionRecord[];
}>;
/** Options for {@link getPatterns}. */
export interface GetPatternsOptions {
    /** FTS query string. Empty string returns all. */
    query?: string;
    /** Filter by pattern type. */
    patternType?: string;
    /** Project root path; defaults to resolved root. */
    projectPath?: string;
    /** Maximum results. Defaults to 50. */
    limit?: number;
}
/**
 * Retrieve pattern records from brain.db, optionally filtered by text query.
 *
 * @param opts - Query, project path, and limit options
 * @returns Array of pattern records
 *
 * @example
 * ```typescript
 * const { patterns } = await getPatterns({ query: 'authentication', patternType: 'success' });
 * ```
 *
 * @task T9615
 */
export declare function getPatterns(opts?: GetPatternsOptions): Promise<{
    patterns: PatternRecord[];
}>;
/** Options for {@link getLearnings}. */
export interface GetLearningsOptions {
    /** FTS query string. Empty string returns all. */
    query?: string;
    /** Project root path; defaults to resolved root. */
    projectPath?: string;
    /** Maximum results. Defaults to 50. */
    limit?: number;
}
/**
 * Retrieve learning records from brain.db, optionally filtered by text query.
 *
 * @param opts - Query, project path, and limit options
 * @returns Array of learning records
 *
 * @example
 * ```typescript
 * const { learnings } = await getLearnings({ query: 'cache invalidation' });
 * ```
 *
 * @task T9615
 */
export declare function getLearnings(opts?: GetLearningsOptions): Promise<{
    learnings: LearningRecord[];
}>;
/** Options for {@link getMemoryGraph}. */
export interface GetMemoryGraphOptions {
    /** Project root path; defaults to resolved root. */
    projectPath?: string;
}
/**
 * Return aggregate statistics for the BRAIN memory graph.
 *
 * @param opts - Optional project path
 * @returns Aggregate graph statistics (node count, edge count, type distribution)
 *
 * @example
 * ```typescript
 * const stats = await getMemoryGraph({ projectPath: '/my/project' });
 * console.log(`Graph: ${stats.nodeCount} nodes, ${stats.edgeCount} edges`);
 * ```
 *
 * @task T9615
 */
export declare function getMemoryGraph(opts?: GetMemoryGraphOptions): Promise<MemoryGraphStats>;
/** Per-table tier count breakdown. */
export interface TableTierCounts {
    /** Brain table name. */
    table: string;
    /** Short-tier entry count. */
    short: number;
    /** Medium-tier entry count. */
    medium: number;
    /** Long-tier entry count. */
    long: number;
}
/** Medium entry approaching long-tier promotion. */
export interface UpcomingPromotion {
    /** Entry identifier. */
    id: string;
    /** Brain table name. */
    table: string;
    /** Fractional days remaining until 7-day gate elapses (0 = eligible now). */
    daysUntil: number;
    /** Human-readable track: "citation (N)" or "verified". */
    track: string;
}
/** Result of {@link getTierStats}. */
export interface TierStatsResult {
    /** Per-table tier distributions. */
    tables: TableTierCounts[];
    /** Top-5 medium entries closest to long-tier eligibility. */
    upcomingLongPromotions: UpcomingPromotion[];
}
/**
 * Return tier distribution and upcoming long-tier promotions.
 *
 * @param projectPath - Optional project root path
 * @returns Per-table tier counts and top-5 upcoming promotions
 *
 * @example
 * ```typescript
 * const stats = await getTierStats('/my/project');
 * console.log(`Short: ${stats.tables[0]?.short}, Long: ${stats.tables[0]?.long}`);
 * ```
 *
 * @task T9615
 */
export declare function getTierStats(
/** @reserved — will be threaded to getBrainNativeDb once multi-project support lands */
_projectPath?: string): Promise<TierStatsResult>;
/** A single pending-verify queue entry. */
export interface PendingVerifyEntry {
    /** Entry identifier. */
    id: string;
    /** Display title (decision text, pattern text, insight, or observation title). */
    title: string | null;
    /** Source confidence level. */
    sourceConfidence: string | null;
    /** Number of times this entry has been retrieved. */
    citationCount: number;
    /** Memory tier. */
    memoryTier: string | null;
    /** ISO creation timestamp. */
    createdAt: string;
    /** Source brain table. */
    table: 'observations' | 'decisions' | 'patterns' | 'learnings';
}
/** Options for {@link getPendingVerify}. */
export interface GetPendingVerifyOptions {
    /** Minimum citation count to include. Defaults to 5. */
    minCitations?: number;
    /** Maximum results to return. Defaults to 50. */
    limit?: number;
}
/** Result of {@link getPendingVerify}. */
export interface PendingVerifyResult {
    /** Total items returned. */
    count: number;
    /** Applied minimum citation threshold. */
    minCitations: number;
    /** Ranked pending-verify entries (highest citation count first). */
    items: PendingVerifyEntry[];
    /** Human-readable hint for the owner. */
    hint: string;
}
/**
 * Return unverified but highly-cited brain entries across all four tables.
 *
 * These are entries that the system keeps retrieving but the owner has not
 * promoted to ground-truth status. Exposing them surfaces the highest-leverage
 * candidates for `cleo memory verify`.
 *
 * @param projectPath - Optional project root path
 * @param opts - Minimum citation count and result limit
 * @returns Ranked list of pending-verify entries plus a hint
 *
 * @example
 * ```typescript
 * const result = await getPendingVerify('/my/project', { minCitations: 3 });
 * console.log(`${result.count} entries awaiting verification`);
 * ```
 *
 * @task T9615
 */
export declare function getPendingVerify(
/** @reserved — will be threaded to getBrainNativeDb once multi-project support lands */
_projectPath?: string, opts?: GetPendingVerifyOptions): Promise<PendingVerifyResult>;
/** Direction for {@link setEntryTier}. */
export type TierDirection = 'promote' | 'demote';
/** Result of {@link setEntryTier}. */
export interface SetEntryTierResult {
    /** Entry identifier. */
    id: string;
    /** Brain table where the entry was found. */
    table: string;
    /** Previous memory tier. */
    fromTier: string;
    /** New memory tier. */
    toTier: string;
    /** ISO timestamp of the update. */
    updatedAt: string;
}
/**
 * Set the memory tier of a single brain entry across all four brain tables.
 *
 * Validates direction (promote requires higher tier, demote requires lower tier)
 * and table membership before running the UPDATE. The long-tier demote guard
 * (requires explicit `force: true`) is enforced internally.
 *
 * @param id - Brain entry ID
 * @param targetTier - Target tier: 'short' | 'medium' | 'long'
 * @param direction - 'promote' or 'demote' (used for error messages and ordering checks)
 * @param opts - Additional options (force: allow demoting from long tier)
 * @returns Entry location + tier change details
 * @throws Error when entry not found, tier ordering is invalid, or long-tier guard fires
 *
 * @task T9619
 */
export declare function setEntryTier(id: string, targetTier: string, direction: TierDirection, opts?: {
    force?: boolean;
}): Promise<SetEntryTierResult>;
/** A group of duplicate brain entries sharing the same content hash. */
export interface DuplicateGroup {
    /** Brain table name. */
    table: string;
    /** Shared content hash. */
    hash: string;
    /** Number of entries sharing this hash. */
    count: number;
    /** Up to 3 sample entries (id + truncated label). */
    samples: string[];
}
/** Result of {@link scanDuplicateEntries}. */
export interface ScanDuplicatesResult {
    /** Total surplus rows (sum of count-1 across all groups). */
    totalDuplicateRows: number;
    /** All duplicate groups found. */
    groups: DuplicateGroup[];
}
/**
 * Scan all four brain tables for content-hash duplicates.
 *
 * Returns up to 20 duplicate groups per table with up to 3 sample entries each.
 * Does NOT modify any data — call {@link runConsolidation} to merge.
 *
 * @returns Duplicate groups and total surplus row count
 *
 * @task T9619
 */
export declare function scanDuplicateEntries(): Promise<ScanDuplicatesResult>;
//# sourceMappingURL=public-api.d.ts.map