@jungjaehoon/mama-core 1.1.1 → 1.1.3

package/dist/mama-api.d.ts

@@ -0,0 +1,954 @@
+/**
+ * MAMA (Memory-Augmented MCP Architecture) - Simple Public API
+ *
+ * Clean wrapper around MAMA's internal functions
+ * Follows Claude-First Design: Simple, Transparent, Non-Intrusive
+ *
+ * Core Principle: MAMA = Librarian, Claude = Researcher
+ * - MAMA stores (organize books), retrieves (find books), indexes (catalog)
+ * - Claude decides what to save and how to use recalled decisions
+ *
+ * v1.3 Update: Collaborative Reasoning Graph
+ * - Auto-search on save: Find similar decisions before saving
+ * - Collaborative invitation: Suggest build-on/debate/synthesize
+ * - AX-first: Soft warnings, not hard blocks
+ *
+ * @module mama-api
+ * @version 1.3
+ * @date 2025-11-26
+ */
+import { DecisionRecord } from './db-manager.js';
+import { SemanticEdges } from './decision-formatter.js';
+/**
+ * Parameters for mama.save()
+ */
+interface SaveParams {
+    topic: string;
+    decision: string;
+    reasoning: string;
+    confidence?: number;
+    type?: 'user_decision' | 'assistant_insight';
+    outcome?: 'pending' | 'success' | 'failure' | 'partial' | 'superseded';
+    failure_reason?: string | null;
+    limitation?: string | null;
+    trust_context?: Record<string, unknown> | null;
+}
+/**
+ * Similar decision result from search
+ */
+interface SimilarDecision {
+    id: string;
+    topic: string;
+    decision: string;
+    reasoning?: string;
+    similarity?: number;
+    created_at?: number | string;
+}
+/**
+ * Search result from mama.search()
+ */
+interface SearchResult {
+    query: string;
+    results: SimilarDecision[];
+    meta: {
+        count: number;
+        search_method: string;
+        threshold: number;
+        recency_boost: {
+            weight: number;
+            scale: number;
+            decay: number;
+        } | null;
+        graph_expansion: {
+            total_results: number;
+            primary_count: number;
+            expanded_count: number;
+            sources: Record<string, number>;
+        } | null;
+    };
+}
+/**
+ * Suggest options for mama.suggest()
+ */
+export interface SuggestOptions {
+    limit?: number;
+    threshold?: number;
+    format?: 'full' | 'teaser' | 'brief' | 'markdown';
+    recency_boost?: boolean | {
+        weight?: number;
+        scale?: number;
+        decay?: number;
+    };
+    graph_expansion?: boolean;
+}
+/**
+ * Reasoning graph info
+ */
+interface ReasoningGraphInfo {
+    topic: string;
+    depth: number;
+    latest: string;
+}
+/**
+ * Save result from mama.save()
+ */
+interface SaveResult {
+    success: boolean;
+    id: string;
+    similar_decisions?: SimilarDecision[];
+    warning?: string;
+    collaboration_hint?: string;
+    reasoning_graph?: ReasoningGraphInfo;
+    error?: string;
+}
+/**
+ * Suggest result from mama.suggest()
+ */
+export interface SuggestResult {
+    query: string;
+    formatted_context: string;
+    raw_decisions?: SimilarDecision[];
+    meta?: SearchResult['meta'];
+    error?: string;
+}
+/**
+ * Recall result from mama.recall()
+ */
+export interface RecallResult {
+    id: string;
+    topic: string;
+    decision: string;
+    reasoning?: string;
+    outcome?: string | null;
+    failure_reason?: string | null;
+    confidence: number;
+    supersedes?: string | null;
+    superseded_by?: string | null;
+    created_at: number | string;
+    updated_at?: number | string;
+    trust_context?: Record<string, unknown> | null;
+    history?: DecisionRecord[];
+    semantic_edges?: SemanticEdges;
+    error?: string;
+}
+/**
+ * Update result from mama.update()
+ */
+export interface UpdateResult {
+    success: boolean;
+    id: string;
+    updated_fields: string[];
+    error?: string;
+}
+/**
+ * Checkpoint params
+ */
+export interface CheckpointParams {
+    summary: string;
+    next_steps?: string;
+    open_files?: string[];
+}
+/**
+ * Checkpoint result
+ */
+export interface CheckpointResult {
+    success: boolean;
+    id: string;
+    timestamp: string;
+    error?: string;
+}
+/**
+ * Load checkpoint result
+ */
+export interface LoadCheckpointResult {
+    found: boolean;
+    summary?: string;
+    next_steps?: string;
+    open_files?: string[];
+    created_at?: string;
+    error?: string;
+}
+/**
+ * Outcome badge map type
+ */
+export type OutcomeBadgeMap = Record<string, string | null>;
+/**
+ * Recall options
+ */
+interface RecallOptions {
+    format?: 'json' | 'markdown';
+}
+/**
+ * DB stats result for decision_edges
+ */
+export interface DBStatsResult {
+    total_links: number;
+    llm_created: number;
+    approved: number;
+}
+/**
+ * DB link stats result
+ */
+export interface DBLinkStatsResult {
+    total_links: number;
+    llm_created: number;
+    approved: number;
+    unique_decisions: number;
+    relationship_breakdown: string;
+}
+/**
+ * Deletion target for auto-generated links
+ */
+interface DeletionTarget {
+    from_id: string;
+    to_id: string;
+    relationship: string;
+}
+/**
+ * Post cleanup report structure
+ */
+export interface PostCleanupReport {
+    orphaned_decisions: number;
+    duplicate_links: number;
+    invalid_references: number;
+}
+/**
+ * Quality report options
+ */
+interface QualityReportOptions {
+    format?: 'json' | 'markdown' | null;
+    period?: '24h' | '7d' | '30d' | null;
+    thresholds?: QualityThresholds | null;
+}
+/**
+ * Quality thresholds
+ */
+interface QualityThresholds {
+    minSuccessRate?: number;
+    maxLatencyMs?: number;
+}
+/**
+ * Deprecate auto-links result
+ */
+interface DeprecateAutoLinksResult {
+    dryRun: boolean;
+    deprecated: number;
+    protected: number;
+    total: number;
+    autoLinkRatio: string;
+    links: Array<{
+        from_id: string;
+        to_id: string;
+        relationship: string;
+        reason?: string;
+        created_at?: number | string;
+    }>;
+}
+/**
+ * Scan auto-links result
+ */
+interface ScanAutoLinksResult {
+    total_links: number;
+    auto_links: number;
+    protected_links: number;
+    deletion_targets: number;
+    deletion_target_list: DeletionTarget[];
+}
+/**
+ * Create link backup result
+ */
+interface CreateLinkBackupResult {
+    backup_file: string;
+    manifest_file: string;
+    checksum: string;
+    link_count: number;
+}
+/**
+ * Restore link backup result
+ */
+interface RestoreLinkBackupResult {
+    total_links: number;
+    restored: number;
+    failed: number;
+    backup_file: string;
+}
+/**
+ * Verify backup exists result
+ */
+interface VerifyBackupResult {
+    backup_file: string;
+    age_hours: number;
+    link_count: number;
+}
+/**
+ * Delete auto-links result (dry run mode)
+ */
+interface DeleteAutoLinksDryRunResult {
+    dry_run: true;
+    would_delete: number;
+    deleted: 0;
+    backup_file: string;
+    large_deletion_warning: boolean;
+    warning_message: string | null;
+    sample_links: Array<{
+        from_id: string;
+        to_id: string;
+        relationship: string;
+    }>;
+    message: string;
+}
+/**
+ * Delete auto-links error entry
+ */
+type DeleteAutoLinksError = {
+    link: string;
+    error: string;
+} | {
+    batch_index: number;
+    batch_size: number;
+    error: string;
+};
+/**
+ * Delete auto-links result (execute mode)
+ */
+interface DeleteAutoLinksExecuteResult {
+    dry_run: false;
+    deleted: number;
+    failed: number;
+    total_targets: number;
+    batches_processed: number;
+    backup_file: string;
+    errors: DeleteAutoLinksError[];
+    success_rate: number;
+}
+/**
+ * Delete auto-links result (empty case)
+ */
+interface DeleteAutoLinksEmptyResult {
+    dry_run: boolean;
+    deleted: 0;
+    failed: 0;
+    total_targets: 0;
+    backup_file: string;
+    message: string;
+}
+/**
+ * Delete auto-links union type
+ */
+type DeleteAutoLinksResult = DeleteAutoLinksDryRunResult | DeleteAutoLinksExecuteResult | DeleteAutoLinksEmptyResult;
+/**
+ * Quality recommendation
+ */
+export interface QualityRecommendation {
+    category: string;
+    severity: string;
+    message: string;
+}
+/**
+ * Quality report structure
+ */
+export interface QualityReport {
+    successRate: {
+        period: string;
+        total: number;
+        success: number;
+        failure: number;
+        successRate: string;
+        meetsTarget: boolean;
+    };
+    latency?: {
+        avgMs: number;
+        p50Ms: number;
+        p95Ms: number;
+        maxMs: number;
+        meetsTarget: boolean;
+    };
+}
+/**
+ * Save a decision or insight to MAMA's memory
+ *
+ * Simple API for Claude to save insights without complex configuration
+ * AC #1: Simple API - no complex configuration required
+ *
+ * @param {Object} params - Decision parameters
+ * @param {string} params.topic - Decision topic (e.g., 'auth_strategy', 'date_format')
+ * @param {string} params.decision - The decision made (e.g., 'JWT', 'ISO 8601 + Unix')
+ * @param {string} params.reasoning - Why this decision was made
+ * @param {number} [params.confidence=0.5] - Confidence score 0.0-1.0 (optional)
+ * @param {string} [params.type='user_decision'] - 'user_decision' or 'assistant_insight' (optional)
+ * @param {string} [params.outcome='pending'] - 'pending', 'success', 'failure', 'partial', 'superseded' (optional)
+ * @param {string} [params.failure_reason] - Why this decision failed (optional, used with outcome='failure')
+ * @param {string} [params.limitation] - Known limitations of this decision (optional)
+ * @returns {Promise<{success: boolean, id: string, similar_decisions?: Array, warning?: string, collaboration_hint?: string, reasoning_graph?: Object}>} Save result with decision ID and metadata
+ *
+ * @example
+ * const decisionId = await mama.save({
+ *   topic: 'date_calculation_format',
+ *   decision: 'Support both ISO 8601 and Unix timestamp formats',
+ *   reasoning: 'Bootstrap data stored as ISO 8601 causing NaN errors',
+ *   confidence: 0.95,
+ *   type: 'assistant_insight',
+ *   outcome: 'success'
+ * });
+ */
+declare function save({ topic, decision, reasoning, confidence, type, outcome, failure_reason, limitation, trust_context, }: SaveParams): Promise<SaveResult>;
+/**
+ * Recall decisions by topic
+ *
+ * DEFAULT: Returns JSON object with decisions and edges (LLM-first design)
+ * OPTIONAL: Returns Markdown string if format='markdown' (for human display)
+ *
+ * @param {string} topic - Decision topic to recall
+ * @param {Object} [options] - Options
+ * @param {string} [options.format='json'] - Output format: 'json' (default) or 'markdown'
+ * @returns {Promise<Object|string>} Decision history as JSON or Markdown
+ *
+ * @example
+ * // LLM usage (default)
+ * const data = await mama.recall('auth_strategy');
+ * // → { topic, decisions: [...], edges: [...], meta: {...} }
+ *
+ * // Human display
+ * const markdown = await mama.recall('auth_strategy', { format: 'markdown' });
+ * // → "📋 Decision History: auth_strategy\n━━━━━━━━..."
+ */
+declare function recall(topic: string, options?: RecallOptions): Promise<unknown>;
+/**
+ * Update outcome of a decision
+ *
+ * Track whether a decision succeeded, failed, or partially worked
+ * AC: Evolutionary Decision Memory - Learn from outcomes
+ *
+ * @param {string} decisionId - Decision ID to update
+ * @param {Object} outcome - Outcome details
+ * @param {string} outcome.outcome - 'SUCCESS', 'FAILED', or 'PARTIAL'
+ * @param {string} [outcome.failure_reason] - Reason for failure (if FAILED)
+ * @param {string} [outcome.limitation] - Limitation description (if PARTIAL)
+ * @returns {Promise<void>}
+ *
+ * @example
+ * await mama.updateOutcome('decision_auth_strategy_123456_abc', {
+ *   outcome: 'FAILED',
+ *   failure_reason: 'Missing token expiration handling'
+ * });
+ */
+interface UpdateOutcomeParams {
+    outcome: string;
+    failure_reason?: string | null;
+    limitation?: string | null;
+}
+declare function updateOutcome(decisionId: string, { outcome, failure_reason, limitation }: UpdateOutcomeParams): Promise<void>;
+/**
+ * Suggest relevant decisions based on user question
+ *
+ * DEFAULT: Returns JSON object with search results (LLM-first design)
+ * OPTIONAL: Returns Markdown string if format='markdown' (for human display)
+ *
+ * Simplified: Direct vector search without LLM intent analysis
+ * Works with short queries, long questions, Korean/English
+ *
+ * @param {string} userQuestion - User's question or intent
+ * @param {Object} options - Search options
+ * @param {string} [options.format='json'] - Output format: 'json' (default) or 'markdown'
+ * @param {number} [options.limit=5] - Max results to return
+ * @param {number} [options.threshold=0.6] - Minimum similarity (adaptive by query length)
+ * @param {boolean} [options.useReranking=false] - Use LLM re-ranking (optional, slower)
+ * @returns {Promise<Object|string|null>} Search results as JSON or Markdown, null if no results
+ *
+ * @example
+ * // LLM usage (default)
+ * const data = await mama.suggest('Why did we choose JWT?');
+ * // → { query, results: [...], meta: {...} }
+ *
+ * // Human display
+ * const markdown = await mama.suggest('mesh optimization', { format: 'markdown' });
+ * // → "💡 MAMA found 3 related topics:\n1. ..."
+ */
+interface SuggestFunctionOptions {
+    format?: 'json' | 'markdown';
+    limit?: number;
+    threshold?: number;
+    useReranking?: boolean;
+    recencyWeight?: number;
+    recencyScale?: number;
+    recencyDecay?: number;
+    disableRecency?: boolean;
+}
+declare function suggest(userQuestion: string, options?: SuggestFunctionOptions): Promise<any>;
+/**
+ * List recent decisions (all topics, chronological)
+ *
+ * DEFAULT: Returns JSON array with recent decisions (LLM-first design)
+ * OPTIONAL: Returns Markdown string if format='markdown' (for human display)
+ *
+ * @param {Object} [options] - Options
+ * @param {number} [options.limit=10] - Max results
+ * @param {string} [options.format='json'] - Output format
+ * @returns {Promise<Array|string>} Recent decisions
+ */
+interface ListDecisionsOptions {
+    limit?: number;
+    format?: 'json' | 'markdown';
+}
+declare function listDecisions(options?: ListDecisionsOptions): Promise<DecisionRecord[] | string>;
+/**
+ * Save current session checkpoint (New Feature: Session Continuity)
+ *
+ * @param {string} summary - Summary of current session state
+ * @param {Array<string>} openFiles - List of currently open files
+ * @param {string} nextSteps - Next steps to be taken
+ * @returns {Promise<number>} Checkpoint ID
+ */
+declare function saveCheckpoint(summary: string, openFiles?: string[], nextSteps?: string, recentConversation?: any[]): Promise<number | bigint>;
+/**
+ * Load latest active checkpoint (New Feature: Session Continuity)
+ *
+ * @returns {Promise<Object|null>} Latest checkpoint or null
+ */
+interface CheckpointRow {
+    id?: number;
+    timestamp?: number;
+    summary?: string;
+    open_files?: string | string[];
+    next_steps?: string;
+    recent_conversation?: string | unknown[];
+    status?: string;
+}
+declare function loadCheckpoint(): Promise<CheckpointRow | null>;
+/**
+ * List recent checkpoints (New Feature: Session Continuity)
+ *
+ * @param {number} limit - Max number of checkpoints to return
+ * @returns {Promise<Array>} Recent checkpoints
+ */
+declare function listCheckpoints(limit?: number): Promise<CheckpointRow[]>;
+/**
+ * Propose a new link between decisions (Epic 3 - Story 3.1)
+ *
+ * LLM proposes a link for user approval. Link is created but marked as pending.
+ *
+ * @param {Object} params - Link parameters
+ * @param {string} params.from_id - Source decision ID
+ * @param {string} params.to_id - Target decision ID
+ * @param {string} params.relationship - 'refines' or 'contradicts'
+ * @param {string} params.reason - Why this link should exist
+ * @param {string} [params.decision_id] - Context decision where link was proposed
+ * @param {string} [params.evidence] - Supporting evidence
+ * @returns {Promise<void>}
+ */
+interface ProposeLinkParams {
+    from_id: string;
+    to_id: string;
+    relationship: string;
+    reason: string;
+    decision_id?: string;
+    evidence?: string;
+}
+declare function proposeLink({ from_id, to_id, relationship, reason, decision_id, evidence, }: ProposeLinkParams): Promise<void>;
+/**
+ * Approve a proposed link (Epic 3 - Story 3.1)
+ *
+ * User approves a pending link, making it active.
+ *
+ * @param {string} from_id - Source decision ID
+ * @param {string} to_id - Target decision ID
+ * @param {string} relationship - Link relationship type
+ * @returns {Promise<void>}
+ */
+declare function approveLink(from_id: string, to_id: string, relationship: string): Promise<void>;
+/**
+ * Reject a proposed link (Epic 3 - Story 3.1)
+ *
+ * User rejects a pending link, removing it from the database.
+ *
+ * @param {string} from_id - Source decision ID
+ * @param {string} to_id - Target decision ID
+ * @param {string} relationship - Link relationship type
+ * @param {string} [reason] - Optional reason for rejection
+ * @returns {Promise<void>}
+ */
+declare function rejectLink(from_id: string, to_id: string, relationship: string, reason?: string): Promise<void>;
+/**
+ * Get pending links awaiting approval (Epic 3 - Story 3.1)
+ *
+ * Returns all links that need user approval.
+ *
+ * @param {Object} [options] - Query options
+ * @param {string} [options.from_id] - Filter by source decision
+ * @param {string} [options.to_id] - Filter by target decision
+ * @returns {Promise<Array>} Pending links with decision details
+ */
+interface GetPendingLinksOptions {
+    from_id?: string;
+    to_id?: string;
+}
+declare function getPendingLinks(options?: GetPendingLinksOptions): Promise<any[]>;
+/**
+ * Deprecate auto-generated links (Epic 3 - Story 3.3)
+ *
+ * Identifies and removes v0 auto-generated links that lack explicit approval context.
+ * Protected links (with decision_id or created_by='llm') are preserved.
+ *
+ * @param {Object} [options] - Deprecation options
+ * @param {boolean} [options.dryRun=true] - If true, only report without deleting
+ * @returns {Promise<Object>} Report with counts and deprecated links
+ */
+interface DeprecateAutoLinksOptions {
+    dryRun?: boolean;
+}
+interface EdgeLink {
+    from_id: string;
+    to_id: string;
+    relationship: string;
+    reason?: string;
+    created_at?: number | string;
+}
+declare function deprecateAutoLinks(options?: DeprecateAutoLinksOptions): Promise<DeprecateAutoLinksResult>;
+/**
+ * Scan and identify auto-generated links for cleanup (Epic 5 - Story 5.1)
+ *
+ * Identifies auto-generated links lacking proper approval metadata.
+ * Separates deletion targets from protected links.
+ *
+ * Identification criteria:
+ * - approved_by_user = 0 OR (created_by IS NULL AND decision_id IS NULL)
+ *
+ * Protected (excluded from deletion):
+ * - approved_by_user = 1 AND (decision_id IS NOT NULL OR evidence IS NOT NULL)
+ *
+ * @returns {Object} Scan results with counts and link details
+ */
+declare function scanAutoLinks(): ScanAutoLinksResult;
+/**
+ * Create backup of links before cleanup (Epic 5 - Story 5.1)
+ *
+ * Backs up deletion target links with full metadata to JSON file.
+ * Generates SHA-256 checksum for data integrity verification.
+ * Creates backup manifest with timestamp and metadata.
+ *
+ * @param {Array} targetLinks - Links to back up
+ * @returns {Object} Backup result with file paths and checksum
+ */
+declare function createLinkBackup(targetLinks: EdgeLink[]): CreateLinkBackupResult;
+/**
+ * Generate pre-cleanup report with risk assessment (Epic 5 - Story 5.1)
+ *
+ * Creates comprehensive report with statistics, risk level, and samples.
+ * Risk assessment based on deletion ratio:
+ * - HIGH: > 50% deletion
+ * - MEDIUM: 30-50% deletion
+ * - LOW: < 30% deletion
+ *
+ * @returns {Object} Report data with markdown output and file path
+ */
+declare function generatePreCleanupReport(): {
+    report: {
+        generated_at: string;
+        statistics: {
+            total_links: number;
+            auto_links: number;
+            protected_links: number;
+            deletion_targets: number;
+            deletion_ratio: string;
+        };
+        risk_assessment: {
+            level: string;
+            message: string;
+        };
+        deletion_target_samples: {
+            from_id: any;
+            to_id: any;
+            relationship: any;
+            reason: any;
+            created_by: any;
+            approved_by_user: any;
+        }[];
+    };
+    report_file: string;
+    markdown: string;
+};
+/**
+ * Restore links from backup file (Epic 5 - Story 5.1)
+ *
+ * Restores previously backed-up links to the database.
+ * Verifies checksum before restoration to ensure data integrity.
+ * Reports number of restored and failed links.
+ *
+ * @param {string} backupFile - Path to backup file
+ * @returns {Object} Restoration result with counts
+ */
+declare function restoreLinkBackup(backupFile: string): RestoreLinkBackupResult;
+/**
+ * Verify backup file exists and is recent (Epic 5 - Story 5.2)
+ *
+ * Checks for backup files in backup directory and verifies they are recent enough.
+ * Required as safety check before executing link deletion.
+ *
+ * @param {number} maxAgeHours - Maximum age of backup in hours (default: 24)
+ * @returns {Object} Backup verification result with latest backup info
+ */
+declare function verifyBackupExists(maxAgeHours?: number): VerifyBackupResult;
+/**
+ * Delete auto-generated links with batch processing (Epic 5 - Story 5.2)
+ *
+ * Executes batch deletion of auto-generated links with transaction support.
+ * Requires recent backup (within 24 hours) before execution.
+ * Logs all deletions to audit trail.
+ *
+ * Safety features:
+ * - Backup verification before deletion
+ * - Batch processing with transaction support
+ * - Dry-run mode for simulation
+ * - Large deletion warning (> 1000 links)
+ *
+ * @param {number} batchSize - Number of links to delete per batch (default: 100)
+ * @param {boolean} dryRun - If true, simulate deletion without actual changes (default: true)
+ * @returns {Object} Deletion result with counts and backup info
+ */
+declare function deleteAutoLinks(batchSize?: number, dryRun?: boolean): DeleteAutoLinksResult;
+/**
+ * Validate cleanup result and generate post-cleanup report (Epic 5 - Story 5.2)
+ *
+ * Re-scans for remaining auto-generated links and evaluates cleanup success.
+ * Generates comprehensive report with statistics and recommendations.
+ *
+ * Success criteria:
+ * - SUCCESS: Remaining auto links < 5%
+ * - PARTIAL: Remaining auto links 5-10%
+ * - FAILED: Remaining auto links > 10%
+ *
+ * @returns {Object} Validation result with report and file path
+ */
+declare function validateCleanupResult(): {
+    status: string;
+    total_links_before: number;
+    auto_links_remaining: number;
+    remaining_ratio: number;
+    protected_links: number;
+    report: {
+        validated_at: string;
+        status: string;
+        message: string;
+        statistics: {
+            total_links: number;
+            remaining_auto_links: number;
+            remaining_ratio: string;
+            protected_links: number;
+            deletion_targets: number;
+        };
+        recommendation: string;
+    };
+    report_file: string;
+    markdown: string;
+};
+/**
+ * Calculate coverage metrics (Epic 4 - Story 4.1)
+ *
+ * Measures narrative coverage (% of decisions with narrative fields)
+ * and link coverage (% of decisions with at least one link).
+ *
+ * @returns {Object} Coverage metrics
+ */
+declare function calculateCoverage(): {
+    narrativeCoverage: string;
+    linkCoverage: string;
+    totalDecisions: number;
+    completeNarratives: number;
+    decisionsWithLinks: number;
+};
+/**
+ * Log restart attempt (Epic 4 - Story 4.2)
+ *
+ * Records restart attempt with success/failure status, latency, and mode.
+ * Replaces in-memory restart-metrics.js with SQLite-backed storage.
+ *
+ * @param {string} sessionId - Session identifier
+ * @param {string} status - 'success' or 'failure'
+ * @param {string|null} failureReason - 'NO_CHECKPOINT', 'LOAD_ERROR', 'CONTEXT_INCOMPLETE', or null
+ * @param {number} latencyMs - Latency in milliseconds
+ * @param {string} mode - 'full' (narrative+links) or 'summary' (summary only)
+ * @returns {void}
+ */
+declare function logRestartAttempt(sessionId: string, status: string, failureReason: string | null, latencyMs: number, mode?: string): void;
+/**
+ * Calculate restart success rate (Epic 4 - Story 4.2)
+ *
+ * Calculates success rate over a given period (24h, 7d, 30d).
+ *
+ * @param {string} period - '24h', '7d', or '30d'
+ * @returns {Object} Success rate metrics
+ */
+declare function calculateRestartSuccessRate(period?: '24h' | '7d' | '30d'): {
+    period: "24h" | "7d" | "30d";
+    total: number;
+    success: number;
+    failure: number;
+    successRate: string;
+    meetsTarget: boolean;
+};
+/**
+ * Calculate restart latency percentiles (Epic 4 - Story 4.2)
+ *
+ * Calculates p50, p95, p99 latencies for successful restarts.
+ * Optionally filters by mode (full/summary).
+ *
+ * @param {string} period - '24h', '7d', or '30d'
+ * @param {string|null} mode - 'full', 'summary', or null (all modes)
+ * @returns {Object} Latency percentile metrics
+ */
+declare function calculateRestartLatency(period?: '24h' | '7d' | '30d', mode?: string | null): {
+    p50: number;
+    p95: number;
+    p99: number;
+    count: number;
+    mode: string;
+};
+/**
+ * Get restart metrics (Epic 4 - Story 4.2)
+ *
+ * Combines success rate and latency metrics for a given period.
+ *
+ * @param {string} period - '24h', '7d', or '30d'
+ * @param {boolean} includeLatency - Whether to include latency percentiles
+ * @returns {Object} Combined restart metrics
+ */
+declare function getRestartMetrics(period?: '24h' | '7d' | '30d', includeLatency?: boolean): {
+    successRate: ReturnType<typeof calculateRestartSuccessRate>;
+    latency?: {
+        full: ReturnType<typeof calculateRestartLatency>;
+        summary: ReturnType<typeof calculateRestartLatency>;
+    };
+};
+/**
+ * Calculate quality metrics (Epic 4 - Story 4.1)
+ *
+ * Measures narrative quality (field completeness per layer)
+ * and link quality (rich reason ratio, approved link ratio).
+ *
+ * @returns {Object} Quality metrics
+ */
+declare function calculateQuality(): {
+    narrativeQuality: {
+        evidence: string;
+        alternatives: string;
+        risks: string;
+    };
+    linkQuality: {
+        richReasonRatio: string;
+        approvedRatio: string;
+        totalLinks: number;
+        richLinks: number;
+        approvedLinks: number;
+    };
+};
+/**
+ * Generate quality report with recommendations (Epic 4 - Story 4.1 + 4.2)
+ *
+ * Generates a comprehensive quality report with coverage, quality metrics,
+ * restart metrics, and recommendations for improvement.
+ *
+ * @param {Object} options - Report options
+ * @param {string} [options.format='json'] - Output format: 'json' or 'markdown'
+ * @param {string} [options.period='7d'] - Period for restart metrics: '24h', '7d', or '30d'
+ * @param {Object} [options.thresholds] - Custom thresholds
+ * @param {number} [options.thresholds.narrativeCoverage=0.8] - Narrative coverage threshold (0-1)
+ * @param {number} [options.thresholds.linkCoverage=0.7] - Link coverage threshold (0-1)
+ * @param {number} [options.thresholds.richReasonRatio=0.7] - Rich reason ratio threshold (0-1)
+ * @param {number} [options.thresholds.restartSuccessRate=0.95] - Restart success rate threshold (0-1)
+ * @param {number} [options.thresholds.restartLatencyP95Full=2500] - Full mode p95 latency threshold (ms)
+ * @param {number} [options.thresholds.restartLatencyP95Summary=1000] - Summary mode p95 latency threshold (ms)
+ * @returns {Object|string} Quality report as JSON or Markdown
+ */
+declare function generateQualityReport(options?: QualityReportOptions): string | {
+    generated_at: string;
+    period: "24h" | "7d" | "30d" | null;
+    coverage: {
+        narrativeCoverage: string;
+        linkCoverage: string;
+        totalDecisions: number;
+        completeNarratives: number;
+        decisionsWithLinks: number;
+    };
+    quality: {
+        narrativeQuality: {
+            evidence: string;
+            alternatives: string;
+            risks: string;
+        };
+        linkQuality: {
+            richReasonRatio: string;
+            approvedRatio: string;
+            totalLinks: number;
+            richLinks: number;
+            approvedLinks: number;
+        };
+    };
+    restart: {
+        successRate: ReturnType<typeof calculateRestartSuccessRate>;
+        latency?: {
+            full: ReturnType<typeof calculateRestartLatency>;
+            summary: ReturnType<typeof calculateRestartLatency>;
+        };
+    };
+    thresholds: {
+        minSuccessRate?: number;
+        maxLatencyMs?: number;
+        narrativeCoverage: number;
+        linkCoverage: number;
+        richReasonRatio: number;
+        restartSuccessRate: number;
+        restartLatencyP95Full: number;
+        restartLatencyP95Summary: number;
+    };
+    recommendations: {
+        type: string;
+        message: string;
+        target: string;
+        current: string;
+    }[];
+    format: "json" | "markdown" | null;
+};
+/**
+ * MAMA Public API
+ *
+ * Simple, clean interface for Claude to interact with MAMA
+ * Hides complex implementation details (embeddings, vector search, graph queries)
+ *
+ * Key Principles:
+ * 1. Simple API First - No complex configuration
+ * 2. Transparent Process - Each step is visible
+ * 3. Claude-First Design - Claude decides what to save
+ * 4. Non-Intrusive - Silent failures for helpers (suggest)
+ */
+declare const mama: {
+    save: typeof save;
+    suggest: typeof suggest;
+    list: typeof listDecisions;
+    listCheckpoints: typeof listCheckpoints;
+    updateOutcome: typeof updateOutcome;
+    saveCheckpoint: typeof saveCheckpoint;
+    loadCheckpoint: typeof loadCheckpoint;
+    recall: typeof recall;
+    proposeLink: typeof proposeLink;
+    approveLink: typeof approveLink;
+    rejectLink: typeof rejectLink;
+    getPendingLinks: typeof getPendingLinks;
+    deprecateAutoLinks: typeof deprecateAutoLinks;
+    calculateCoverage: typeof calculateCoverage;
+    calculateQuality: typeof calculateQuality;
+    generateQualityReport: typeof generateQualityReport;
+    logRestartAttempt: typeof logRestartAttempt;
+    calculateRestartSuccessRate: typeof calculateRestartSuccessRate;
+    calculateRestartLatency: typeof calculateRestartLatency;
+    getRestartMetrics: typeof getRestartMetrics;
+    scanAutoLinks: typeof scanAutoLinks;
+    createLinkBackup: typeof createLinkBackup;
+    generatePreCleanupReport: typeof generatePreCleanupReport;
+    restoreLinkBackup: typeof restoreLinkBackup;
+    verifyBackupExists: typeof verifyBackupExists;
+    deleteAutoLinks: typeof deleteAutoLinks;
+    validateCleanupResult: typeof validateCleanupResult;
+};
+export { save, suggest, listDecisions as list, listCheckpoints, updateOutcome, saveCheckpoint, loadCheckpoint, recall, proposeLink, approveLink, rejectLink, getPendingLinks, deprecateAutoLinks, calculateCoverage, calculateQuality, generateQualityReport, logRestartAttempt, calculateRestartSuccessRate, calculateRestartLatency, getRestartMetrics, scanAutoLinks, createLinkBackup, generatePreCleanupReport, restoreLinkBackup, verifyBackupExists, deleteAutoLinks, validateCleanupResult, };
+export default mama;
+//# sourceMappingURL=mama-api.d.ts.map