/**
 * Nexus Memory — Superior to MemPalace
 *
 * Combines the best of 2026 memory research into one zero-dependency system:
 *
 * 1. BM25 RETRIEVAL (replaces TF-IDF)
 *    - Term frequency saturation (long docs don't dominate)
 *    - Document length normalization
 *    - 500x faster than naive TF-IDF on large corpora
 *
 * 2. OBSERVATIONAL MEMORY (inspired by Mastra, 94.87% LongMemEval)
 *    - Don't store raw conversations — extract atomic observations
 *    - Each observation = one fact, one timestamp, one confidence
 *    - Resolves ambiguous references at extraction time
 *
 * 3. KNOWLEDGE GRAPH + TUNNELS (inspired by MemPalace)
 *    - Concepts as nodes, relationships as edges
 *    - Auto-tunnels: same concept in different projects → linked
 *    - BFS traversal for related memory discovery
 *
 * 4. PROGRESSIVE RETRIEVAL (3 levels)
 *    - L1: Index scan — instant, <1ms, metadata only
 *    - L2: BM25 search — fast, <10ms, top-K results
 *    - L3: Graph expansion — deep, <50ms, BFS + related concepts
 *
 * 5. TEMPORAL AWARENESS
 *    - When was this learned? (timestamp)
 *    - Is it still valid? (decay function)
 *    - Was it contradicted? (version chain)
 *    - How often recalled? (access frequency)
 */
/**
 * Collapse caller-controlled memory metadata to a short inert label. Prompt
 * instructions and secrets are rejected/redacted before the label is used in
 * graph nodes, filenames, search filters, or rendered skill metadata.
 */
export declare function normalizeMemoryLabel(value: string | undefined, fallback?: string, maxLength?: number): string;
/** An atomic unit of knowledge. */
export type Observation = {
    id: string;
    /** The fact itself — one clear statement. */
    content: string;
    /** Domain/project this belongs to. */
    domain: string;
    /** Specific topic within the domain. */
    topic: string;
    /** Tags for filtering. */
    tags: string[];
    /** When this was first observed. */
    createdAt: string;
    /** When this was last confirmed/accessed. */
    accessedAt: string;
    /** How many times recalled. */
    accessCount: number;
    /** Confidence 0-1. Decays over time, increases on re-confirmation. */
    confidence: number;
    /** Previous version ID if this was updated. */
    previousVersionId?: string;
    /** Is this still believed to be true? */
    valid: boolean;
    /** Source: which session/interaction. */
    sourceSessionId?: string;
    /** BM25 pre-computed term frequencies. */
    termFreqs: Record<string, number>;
    /** Document length in tokens. */
    docLength: number;
};
/** A node in the knowledge graph. */
export type KnowledgeNode = {
    id: string;
    label: string;
    type: "concept" | "project" | "file" | "tool" | "person" | "error" | "skill";
    /** Observation IDs linked to this node. */
    observationIds: string[];
    /** When last active. */
    lastActiveAt: string;
    weight: number;
};
/** An edge in the knowledge graph. */
export type KnowledgeEdge = {
    from: string;
    to: string;
    relation: "contains" | "uses" | "causes" | "fixes" | "related" | "tunnel" | "contradicts" | "evolves";
    weight: number;
};
/** Search result with relevance score. */
export type MemoryResult = {
    observation: Observation;
    score: number;
    /** How this result was found. */
    retrievalLevel: "L1" | "L2" | "L3";
    /** Related observations found via graph. */
    related?: Observation[];
};
/** Memory statistics. */
export type MemoryStats = {
    totalObservations: number;
    validObservations: number;
    graphNodes: number;
    graphEdges: number;
    tunnels: number;
    domains: string[];
    avgConfidence: number;
    avgDocLength: number;
};
/** Extract atomic observations from raw text. */
export declare function extractObservations(text: string, domain: string, sessionId?: string, extraTags?: string[]): Observation[];
export type NexusMemory = {
    /** Add raw text and auto-extract observations. */
    ingest: (text: string, domain: string, sessionId?: string, tags?: string[]) => number;
    /** Add a pre-formed observation. */
    addObservation: (obs: Observation) => void;
    /** L1: Quick metadata scan. */
    scanIndex: (domain?: string, topic?: string, tags?: string[]) => Observation[];
    /** L2: BM25 search. */
    search: (query: string, limit?: number) => MemoryResult[];
    /** L3: Graph-expanded search. */
    deepSearch: (query: string, limit?: number) => MemoryResult[];
    /** Confirm an observation (boost confidence, update access). */
    confirm: (id: string) => void;
    /** Invalidate an observation. */
    invalidate: (id: string) => void;
    /** Get all tunnels (cross-domain connections). */
    getTunnels: () => KnowledgeEdge[];
    /** Get stats. */
    getStats: () => MemoryStats;
    /** Persist to disk. */
    save: () => void;
    /** Get the knowledge graph. */
    getGraph: () => {
        nodes: KnowledgeNode[];
        edges: KnowledgeEdge[];
    };
    /** Toggle learned-embedding query expansion at runtime (for A/B eval). */
    setEmbeddings: (on: boolean) => void;
};
export declare function createNexusMemory(dataDir: string, opts?: {
    useEmbeddings?: boolean;
}): NexusMemory;