/**
 * BRAIN Retrieval Operations — 3-layer pattern (search -> timeline -> fetch).
 *
 * Provides token-efficient memory access modeled after claude-mem's
 * search/timeline/get_observations workflow:
 *
 * 1. searchBrainCompact — lightweight index (IDs + titles, ~50 tokens/hit)
 * 2. timelineBrain      — chronological context around an anchor entry
 * 3. fetchBrainEntries  — full details for a filtered set of IDs
 * 4. observeBrain       — unified save (observations table)
 *
 * Wave 2A provides the core implementations; Wave 2B wires them through
 * the dispatch layer (engine-compat -> domain handler -> MCP gateway).
 *
 * @task T5131 T5132 T5133 T5134 T5135
 * @epic T5149
 */
import type { BRAIN_OBSERVATION_SOURCE_TYPES, BRAIN_OBSERVATION_TYPES } from '../store/brain-schema.js';
import type { BrainAnchor } from './brain-row-types.js';
/** Compact search hit — minimal fields for index-level results. */
export interface BrainCompactHit {
    id: string;
    type: 'decision' | 'pattern' | 'learning' | 'observation';
    title: string;
    date: string;
    relevance?: number;
}
/** Parameters for searchBrainCompact. */
export interface SearchBrainCompactParams {
    query: string;
    limit?: number;
    tables?: Array<'decisions' | 'patterns' | 'learnings' | 'observations'>;
    dateStart?: string;
    dateEnd?: string;
}
/** Result from searchBrainCompact. */
export interface SearchBrainCompactResult {
    results: BrainCompactHit[];
    total: number;
    tokensEstimated: number;
}
/** Parameters for timelineBrain. */
export interface TimelineBrainParams {
    anchor: string;
    depthBefore?: number;
    depthAfter?: number;
}
/** Timeline entry — compact id/type/date tuple. */
export interface TimelineNeighbor {
    id: string;
    type: string;
    date: string;
}
/** Result from timelineBrain. */
export interface TimelineBrainResult {
    anchor: BrainAnchor | null;
    before: TimelineNeighbor[];
    after: TimelineNeighbor[];
}
/** Parameters for fetchBrainEntries. */
export interface FetchBrainEntriesParams {
    ids: string[];
}
/** Fetched entry with full data. */
export interface FetchedBrainEntry {
    id: string;
    type: string;
    data: unknown;
}
/** Result from fetchBrainEntries. */
export interface FetchBrainEntriesResult {
    results: FetchedBrainEntry[];
    notFound: string[];
    tokensEstimated: number;
}
/** Observation type from schema. */
export type BrainObservationType = (typeof BRAIN_OBSERVATION_TYPES)[number];
/** Observation source type from schema. */
export type BrainObservationSourceType = (typeof BRAIN_OBSERVATION_SOURCE_TYPES)[number];
/** Parameters for observeBrain. */
export interface ObserveBrainParams {
    text: string;
    title?: string;
    type?: BrainObservationType;
    project?: string;
    sourceSessionId?: string;
    sourceType?: BrainObservationSourceType;
}
/** Result from observeBrain. */
export interface ObserveBrainResult {
    id: string;
    type: string;
    createdAt: string;
}
/**
 * Token-efficient compact search across BRAIN tables.
 * Returns index-level hits (~50 tokens per result).
 *
 * Delegates to searchBrain() from brain-search.ts for FTS5/LIKE search,
 * then projects results to a compact format with optional date filtering.
 *
 * @param projectRoot - Project root directory
 * @param params - Search parameters
 * @returns Compact search results with token estimate
 */
export declare function searchBrainCompact(projectRoot: string, params: SearchBrainCompactParams): Promise<SearchBrainCompactResult>;
/**
 * Get chronological context around an anchor entry.
 * Fetches the anchor's full data, then queries all 4 BRAIN tables
 * via UNION ALL to find chronological neighbors.
 *
 * @param projectRoot - Project root directory
 * @param params - Timeline parameters with anchor ID and depth
 * @returns Anchor entry data with surrounding chronological entries
 */
export declare function timelineBrain(projectRoot: string, params: TimelineBrainParams): Promise<TimelineBrainResult>;
/**
 * Batch-fetch full details by IDs.
 * Groups IDs by prefix to query the correct tables via BrainDataAccessor.
 *
 * @param projectRoot - Project root directory
 * @param params - Fetch parameters with IDs
 * @returns Full entry data for each found ID, plus not-found list
 */
export declare function fetchBrainEntries(projectRoot: string, params: FetchBrainEntriesParams): Promise<FetchBrainEntriesResult>;
/**
 * Save an observation to the BRAIN observations table.
 * Replaces the external claude-mem save_observation pattern.
 *
 * Auto-classifies type from text if not provided. Generates a
 * unique ID with O- prefix + base36 timestamp.
 *
 * @param projectRoot - Project root directory
 * @param params - Observation data
 * @returns Created observation ID, type, and timestamp
 */
export declare function observeBrain(projectRoot: string, params: ObserveBrainParams): Promise<ObserveBrainResult>;
/** Result from populateEmbeddings backfill. */
export interface PopulateEmbeddingsResult {
    processed: number;
    skipped: number;
}
/**
 * Backfill embeddings for existing observations that lack them.
 *
 * Iterates through observations not yet in brain_embeddings and
 * generates vectors using the registered embedding provider.
 * Processes in batches to avoid memory pressure.
 *
 * @param projectRoot - Project root directory
 * @param options - Optional batch size configuration
 * @returns Count of processed and skipped observations
 */
export declare function populateEmbeddings(projectRoot: string, options?: {
    batchSize?: number;
}): Promise<PopulateEmbeddingsResult>;
//# sourceMappingURL=brain-retrieval.d.ts.map