@aria-cli/types 1.0.19 → 1.0.31

package/dist-cjs/memoria.d.ts

@@ -1,428 +0,0 @@
-/**
- * Minimal IMemoria interface for consumers that need memory capabilities
- * without depending on the concrete @aria/memoria package.
- *
- * Structural types (MemoryItem, ToolItem, RecallResult) replace bare
- * `unknown` returns so consumers get usable shapes without coupling to
- * the full Memoria domain model.
- */
-/** A single stored memory. */
-export interface MemoryItem {
-    id: string;
-    content: string;
-    summary?: string;
-    network?: string;
-    importance?: number;
-    confidence?: number;
-    createdAt?: Date;
-    metadata?: Record<string, unknown>;
-}
-/** A single tool-store entry. */
-export interface ToolItem {
-    id: string;
-    name: string;
-    description: string;
-    source?: ToolSourceItem;
-    importance?: number;
-    confidence?: number;
-    tags?: string[];
-    createdAt?: Date;
-    updatedAt?: Date;
-    accessedAt?: Date;
-    accessCount?: number;
-    evidenceIds?: string[];
-    category?: "filesystem" | "code" | "shell" | "web" | "data" | "memory" | "meta" | "arion";
-    parameters?: Record<string, unknown>;
-    riskLevel?: "safe" | "moderate" | "dangerous";
-    responseTemplate?: string;
-    knowledge?: string;
-    usageHint?: string;
-    adoptedAt?: number;
-    lastUsedAt?: number;
-    usageCount?: number;
-    schema?: Record<string, unknown>;
-    capabilities?: string[];
-    metrics?: Record<string, unknown>;
-}
-export type ToolSourceItem = {
-    type: "built-in";
-} | {
-    type: "external";
-    ref: string;
-    format: "skill-file" | "markdown" | "json" | "web-search";
-} | {
-    type: "organic";
-    method: "execution" | "observation" | "feedback";
-    episodeId?: string;
-};
-/** Result shape returned by observation query primitives. */
-export interface ObservationQueryResult {
-    observations: string;
-    currentTask: string | null;
-    suggestedResponse: string | null;
-    sessionId: string;
-    updatedAt: number;
-}
-/** Result envelope returned by the APR pipeline. */
-export interface RecallResult {
-    memories: MemoryItem[];
-    /** @deprecated Legacy alias retained for compatibility with older callers. */
-    data?: MemoryItem[];
-    query?: string;
-    totalCount?: number;
-    degradationLevel?: "full" | "reduced" | "minimal";
-    skippedStages?: string[];
-    warnings?: string[];
-}
-/** Result from lightweight FTS5-only recall. */
-export interface LightweightRecallResult {
-    memories: MemoryItem[];
-    formattedContext: {
-        context: string;
-    };
-    query: string;
-}
-export interface ExtractedConversationMemoryItem {
-    content: string;
-    network: "world" | "episodes" | "beliefs" | "entities" | "procedures" | "strategies";
-    /** Optional durability marker describing how the memory was routed */
-    durability?: "permanent" | "session";
-}
-export interface ConversationExtractionResult {
-    learned: ExtractedConversationMemoryItem[];
-    error?: string;
-}
-export interface SkillTriggerItem {
-    type: "keyword" | "intent" | "context" | "entity";
-    pattern: string;
-    confidence: number;
-}
-export interface SkillRequirementsItem {
-    bins?: string[];
-    env?: string[];
-    os?: ("darwin" | "linux" | "win32")[];
-}
-export type SkillSourceItem = {
-    type: "auto-learned";
-    sequenceId: string;
-} | {
-    type: "file";
-    path: string;
-    format: "skill-file";
-} | {
-    type: "cli";
-    command: string;
-} | {
-    type: "web";
-    url: string;
-} | {
-    type: "user";
-    ref?: string;
-};
-export interface SkillItem {
-    id: string;
-    name: string;
-    description: string;
-    content: string;
-    toolIds: string[];
-    triggers: SkillTriggerItem[];
-    requires?: SkillRequirementsItem;
-    tags: string[];
-    source: SkillSourceItem;
-    executionCount: number;
-    successCount: number;
-    lastExecuted: Date | null;
-    averageDurationMs: number | null;
-    confidence: number;
-    importance: number;
-    createdAt: Date;
-    updatedAt: Date;
-    accessedAt: Date;
-    accessCount: number;
-    archivedAt?: Date;
-}
-export interface SkillExecutionRecord {
-    id: string;
-    skillId: string;
-    success: boolean;
-    durationMs?: number;
-    notes?: string;
-    episodeId?: string;
-    timestamp: Date;
-}
-export interface ToolUseSequenceRecord {
-    tool: string;
-    input?: Record<string, unknown>;
-    output?: string;
-    success: boolean;
-    timestamp: Date;
-}
-/**
- * Minimal observation engine interface for consumers that need observation
- * capabilities without depending on the concrete @aria/memoria package.
- *
- * Matches the public surface of ObservationEngine from @aria/memoria.
- */
-export interface IObservationEngine {
-    /** Prepare context before model call — may trigger observation and filter messages. */
-    prepareContext(opts: {
-        sessionId: string;
-        messages: unknown[];
-        originalSystemPrompt: string;
-        readOnly?: boolean;
-        signal?: AbortSignal;
-    }): Promise<{
-        messagesToSend: unknown[];
-        filteredMessageIds: Set<string>;
-        observationTriggered: boolean;
-    }>;
-    /** Track new message IDs added to the conversation since last observation. */
-    trackNewMessages(messageIds: string[]): void;
-    /** Force observation of remaining unobserved messages at session end. */
-    finalObservation(sessionId: string, messages?: unknown[], signal?: AbortSignal): Promise<void>;
-    /** Observe messages — used for explicit observation triggers. */
-    observe(sessionId: string, messages: unknown[], signal?: AbortSignal, opts?: {
-        force?: boolean;
-    }): Promise<void>;
-    /** Get the observation record for a session, or null. */
-    getRecord(sessionId: string): unknown;
-    /** Get the active observation text for a session. */
-    getActiveObservations(sessionId: string): string;
-    /** Drain pending observation work (wait for in-flight observations to complete). */
-    drain(): Promise<void>;
-}
-export interface IMemoria {
-    /** Store a memory. Returns an object with `id` on success, or null. */
-    remember(content: string, options?: Record<string, unknown>): Promise<{
-        id: string;
-    } | null>;
-    /**
-     * Internal fast-path for storing execution-trace episodes without the full
-     * entity extraction pipeline. Optional for backward compatibility.
-     */
-    storeEpisode?(content: string): Promise<{
-        id: string;
-    } | null>;
-    /** Retrieve memories matching a query. Includes degradation metadata when available. */
-    recall(query: string, options?: Record<string, unknown>): Promise<RecallResult>;
-    /** Lightweight FTS5-only recall for session seeding. No LLM calls. */
-    recallLightweight(query: string, options?: {
-        limit?: number;
-        networks?: string[];
-    }): Promise<LightweightRecallResult>;
-    /**
-     * Planner-first unified recall: 1 LLM call for classification + plan + expansion.
-     * Routes to direct lookup (skipping APR) or mixed APR + primitive execution.
-     * This is the preferred recall path — recallWithAPR delegates to this.
-     */
-    recallUnified?(query: string, options?: {
-        limit?: number;
-        networks?: string[];
-    }): Promise<{
-        memories: MemoryItem[];
-        formattedContext?: {
-            context?: string;
-            text?: string;
-            tokenCount?: number;
-        } | null;
-        intent?: {
-            type?: string;
-            confidence?: number;
-            entities?: string[];
-            temporalFocus?: string | null;
-            extractedEntities?: string[];
-            extractedTimeframe?: Record<string, unknown>;
-        };
-        sourceStats?: unknown;
-        plan?: Array<{
-            primitive: string;
-            args: Record<string, unknown>;
-        }>;
-        planReasoning?: string;
-        primitiveResults?: Array<{
-            source: string;
-            data: unknown;
-        }>;
-    }>;
-    /** Retrieve memories via the Adaptive Parallel Retrieval pipeline. */
-    recallWithAPR(query: string, options?: {
-        limit?: number;
-        networks?: string[];
-    }): Promise<{
-        memories: MemoryItem[];
-        formattedContext?: {
-            context?: string;
-            text?: string;
-            tokenCount?: number;
-        };
-        intent?: {
-            type?: string;
-            confidence?: number;
-            entities?: string[];
-            temporalFocus?: string | null;
-            extractedEntities?: string[];
-            extractedTimeframe?: Record<string, unknown>;
-        };
-        sourceStats?: unknown;
-        query?: string;
-        totalCount?: number;
-        degradationLevel?: "full" | "reduced" | "minimal";
-        skippedStages?: string[];
-        warnings?: string[];
-    }>;
-    /**
-     * Lightweight vector-only recall with network filtering. Bypasses the full APR
-     * pipeline (no classification, no multi-index fusion, no diversity). Designed
-     * for time-critical paths like session bootstrap.
-     */
-    recallDirect(query: string, options: {
-        networks: string[];
-        limit: number;
-        threshold?: number;
-    }): Promise<MemoryItem[]>;
-    /** Recall memories by network type. Direct SQL query, no LLM classification. */
-    recallByNetwork(network: string, options?: {
-        limit?: number;
-    }): Promise<MemoryItem[]>;
-    /** Recall recent memories, optionally filtered by network. Direct SQL query sorted by created_at DESC. */
-    recallRecent(options?: {
-        limit?: number;
-        network?: string;
-    }): Promise<MemoryItem[]>;
-    /** Recall memories by vector similarity. Uses embedding model only (0 LLM calls). */
-    recallSimilar(query: string, options?: {
-        k?: number;
-        threshold?: number;
-    }): Promise<MemoryItem[]>;
-    /** Store a tool with semantic indexing. Returns the generated id. */
-    rememberTool(tool: {
-        name: string;
-        description: string;
-    } & Record<string, unknown>): Promise<string>;
-    /** Query the tool store. */
-    recallTools(options: {
-        query: string;
-        limit?: number;
-        /** Optional offset used for paged list retrieval (matchAll mode). */
-        offset?: number;
-        minConfidence?: number;
-        /** When true, bypasses semantic/keyword matching and lists stored tools. */
-        matchAll?: boolean;
-        /** When false, recall becomes read-only and does not mutate access stats. */
-        updateAccessStats?: boolean;
-    }): Promise<ToolItem[]>;
-    /** Retrieve a single tool entry by ID. */
-    getToolById(id: string): Promise<ToolItem | null>;
-    /** Delete a tool entry by ID. Returns true if deleted, false if not found. */
-    forgetTool(id: string): Promise<boolean>;
-    /** Store a skill directly. Returns the generated skill ID. */
-    rememberSkill(skill: {
-        name: string;
-        description: string;
-        content: string;
-        toolIds?: string[];
-        triggers?: SkillTriggerItem[];
-        requires?: SkillRequirementsItem;
-        tags?: string[];
-        source: SkillSourceItem;
-        importance?: number;
-        confidence?: number;
-    }): Promise<string>;
-    /** Skill retrieval API. */
-    recallSkills(options?: {
-        query?: string;
-        triggerType?: SkillTriggerItem["type"];
-        limit?: number;
-    }): Promise<SkillItem[]>;
-    /** Skill lookup API. */
-    getSkill(idOrName: string): Promise<SkillItem | null>;
-    /** Record skill execution metrics. */
-    recordSkillExecution(options: {
-        skillId: string;
-        success: boolean;
-        durationMs?: number;
-        notes?: string;
-        episodeId?: string;
-    }): Promise<SkillExecutionRecord>;
-    /** Start recording a tool-use sequence for procedural learning. */
-    startToolSequence?(task: string, options?: {
-        sessionId?: string;
-    }): void;
-    /** Record a single tool execution within the active sequence. */
-    recordToolUse?(record: ToolUseSequenceRecord, options?: {
-        sessionId?: string;
-    }): void;
-    /** Finalize the active tool-use sequence and trigger learning. */
-    endToolSequence?(success: boolean, options?: {
-        sessionId?: string;
-    }): Promise<void>;
-    /** Delete a single memory by ID. */
-    deleteMemory(id: string): Promise<boolean>;
-    /** Merge a JSON patch into a memory's metadata. */
-    updateMemoryMetadata(id: string, patch: Record<string, unknown>): void;
-    /** Soft-invalidate a memory in place (sets confidence to 0, marks reason). Allows recovery. */
-    invalidateMemoryInPlace(memoryId: string, reason?: string): Promise<void>;
-    /** Requeue failed embedding jobs and return how many were scheduled. */
-    retryFailedEmbeddings?(): Promise<number>;
-    /** Extract memories from a user/assistant conversation turn. */
-    extractFromConversation(userMessage: string, assistantResponse: string, options?: {
-        signal?: AbortSignal;
-    }): Promise<ConversationExtractionResult>;
-    /** Observation engine for Mastra-style observation/reflection memory layer. */
-    readonly observationEngine?: IObservationEngine;
-    /**
-     * Extract durable knowledge from observation text into the knowledge graph.
-     * Optional for backward compatibility — always present on concrete Memoria instances.
-     */
-    extractFromObservations?(observations: string, options?: {
-        sessionId?: string;
-        signal?: AbortSignal;
-    }): Promise<ConversationExtractionResult>;
-    /**
-     * Return the most recently updated observation session ID.
-     * When `arionId` is provided, scope to that arion's observation records.
-     */
-    getMostRecentSessionId?(options?: {
-        arionId?: string;
-    }): Promise<string | null>;
-    /**
-     * Fetch persisted active observations for a session.
-     * Returns null when no observation record exists for the session.
-     */
-    getSessionObservations?(sessionId: string): Promise<string | null>;
-    /**
-     * Full-text search across observation records (LIKE on observations, current_task, suggested_response).
-     * Returns matching records ordered by recency.
-     */
-    searchObservations?(query: string, limit?: number): Promise<ObservationQueryResult[]>;
-    /**
-     * Retrieve a specific field from the most recent observation record.
-     * Valid fields: "suggested_response", "current_task", "active_observations".
-     */
-    getObservationField?(field: "suggested_response" | "current_task" | "active_observations"): Promise<string | null>;
-    /**
-     * Retrieve the N most recent observation records, ordered by updated_at DESC.
-     */
-    getRecentObservations?(limit?: number): Promise<ObservationQueryResult[]>;
-    /** Shut down the memory system and release resources. */
-    close(): Promise<void>;
-    /**
-     * Entity-first recall — fast-path for entity/self queries.
-     * Returns a formatted string when the query matches a known entity or
-     * self-query pattern. Returns null to signal fallback to APR.
-     */
-    entityRecall(query: string): Promise<string | null>;
-    /** Whether this instance has been closed. */
-    readonly isClosed: boolean;
-    /** Return the total number of stored memories. */
-    count(): Promise<number>;
-    /** List stored memories. */
-    list(options?: {
-        limit?: number;
-        network?: string;
-    }): Promise<MemoryItem[]>;
-    /** Get a config value by key. Returns null if not found. */
-    getConfig(key: string): Promise<string | null>;
-    /** Set a config value by key. Creates or overwrites. */
-    setConfig(key: string, value: string): Promise<void>;
-}