@framers/agentos 0.1.101 → 0.1.103

package/dist/memory/decay/DecayModel.d.ts

@@ -79,6 +79,39 @@ export declare function computeInterference(similarities: Array<{
     similarity: number;
     currentStrength: number;
 }>, config?: DecayConfig): InterferenceResult;
+/**
+ * Result of applying the unused-trace penalty to a memory trace's decay
+ * parameters.
+ */
+export interface PenaltyResult {
+    /** Updated encoding strength after the 10% immediate penalty. */
+    encodingStrength: number;
+    /** Updated stability — halved, floored at 60 000 ms (1 minute). */
+    stability: number;
+    /** Timestamp of the penalty application (Unix ms). */
+    lastAccessedAt: number;
+}
+/**
+ * Accelerates decay for a trace that was retrieved and injected into the
+ * prompt but subsequently ignored by the LLM's response.
+ *
+ * Rationale: if a memory was surfaced but the model produced a response
+ * that didn't use it, the trace is likely less relevant than its current
+ * strength suggests.  Halving stability makes the forgetting curve steeper
+ * going forward (the trace will reach the pruning threshold faster), while
+ * the 10% immediate strength penalty provides a small but observable signal
+ * to the consolidation pipeline.
+ *
+ * The stability floor of 60 000 ms (1 minute) prevents pathological
+ * oscillation on traces that are repeatedly penalised — they still decay
+ * naturally but aren't instantly pruned by a single feedback event.
+ *
+ * @param trace - The memory trace that was injected but ignored.
+ * @param now   - Current wall-clock timestamp in milliseconds.
+ * @returns Updated `encodingStrength`, `stability`, and `lastAccessedAt`
+ *   suitable for writing back to the trace store.
+ */
+export declare function penalizeUnused(trace: MemoryTrace, now: number): PenaltyResult;
 /**
  * Identify traces that have decayed below the pruning threshold.
  * These should be soft-deleted (isActive = false).

package/dist/memory/decay/DecayModel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DecayModel.d.ts","sourceRoot":"","sources":["../../../src/memory/decay/DecayModel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAOhD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAG9E;AAMD,MAAM,WAAW,qBAAqB;IACpC,0CAA0C;IAC1C,gBAAgB,EAAE,MAAM,CAAC;IACzB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,yBAAyB;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,8BAA8B;IAC9B,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,qBAAqB,CA4BxF;AAMD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,kBAAkB,EAAE,kBAAkB,EAAE,CAAC;IACzC,4DAA4D;IAC5D,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CAAC,EACrF,MAAM,GAAE,WAAkC,GACzC,kBAAkB,CAuBpB;AAMD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,WAAW,EAAE,EACrB,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,WAAkC,GACzC,MAAM,EAAE,CAWV"}
+{"version":3,"file":"DecayModel.d.ts","sourceRoot":"","sources":["../../../src/memory/decay/DecayModel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAOhD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAG9E;AAMD,MAAM,WAAW,qBAAqB;IACpC,0CAA0C;IAC1C,gBAAgB,EAAE,MAAM,CAAC;IACzB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,yBAAyB;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,8BAA8B;IAC9B,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,qBAAqB,CA4BxF;AAMD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,kBAAkB,EAAE,kBAAkB,EAAE,CAAC;IACzC,4DAA4D;IAC5D,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CAAC,EACrF,MAAM,GAAE,WAAkC,GACzC,kBAAkB,CAuBpB;AAMD;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,iEAAiE;IACjE,gBAAgB,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CAY7E;AAMD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,WAAW,EAAE,EACrB,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,WAAkC,GACzC,MAAM,EAAE,CAWV"}

package/dist/memory/decay/DecayModel.js

@@ -95,6 +95,37 @@ export function computeInterference(similarities, config = DEFAULT_DECAY_CONFIG)
         proactiveReduction: Math.min(0.3, proactiveReduction), // cap proactive interference
     };
 }
+/**
+ * Accelerates decay for a trace that was retrieved and injected into the
+ * prompt but subsequently ignored by the LLM's response.
+ *
+ * Rationale: if a memory was surfaced but the model produced a response
+ * that didn't use it, the trace is likely less relevant than its current
+ * strength suggests.  Halving stability makes the forgetting curve steeper
+ * going forward (the trace will reach the pruning threshold faster), while
+ * the 10% immediate strength penalty provides a small but observable signal
+ * to the consolidation pipeline.
+ *
+ * The stability floor of 60 000 ms (1 minute) prevents pathological
+ * oscillation on traces that are repeatedly penalised — they still decay
+ * naturally but aren't instantly pruned by a single feedback event.
+ *
+ * @param trace - The memory trace that was injected but ignored.
+ * @param now   - Current wall-clock timestamp in milliseconds.
+ * @returns Updated `encodingStrength`, `stability`, and `lastAccessedAt`
+ *   suitable for writing back to the trace store.
+ */
+export function penalizeUnused(trace, now) {
+    const currentStrength = computeCurrentStrength(trace, now);
+    // Floor: 1 minute — prevents traces from reaching an unusable stability
+    // value even after many consecutive ignore penalties.
+    const newStability = Math.max(trace.stability * 0.5, 60000);
+    return {
+        encodingStrength: currentStrength * 0.9, // 10% immediate strength penalty
+        stability: newStability,
+        lastAccessedAt: now,
+    };
+}
 // ---------------------------------------------------------------------------
 // Batch decay sweep (for consolidation pipeline)
 // ---------------------------------------------------------------------------

package/dist/memory/decay/DecayModel.js.map

@@ -1 +1 @@
-{"version":3,"file":"DecayModel.js","sourceRoot":"","sources":["../../../src/memory/decay/DecayModel.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"DecayModel.js","sourceRoot":"","sources":["../../../src/memory/decay/DecayModel.ts"],"names":[],"mappings":"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"}

package/dist/memory/facade/Memory.d.ts

@@ -0,0 +1,228 @@
+/**
+ * @fileoverview Memory facade -- unified public API for the complete memory system.
+ *
+ * The `Memory` class wires together every subsystem built in Tasks 1-12:
+ * - SqliteBrain (unified SQLite connection with WAL, full schema)
+ * - SqliteKnowledgeGraph (IKnowledgeGraph backed by SQLite)
+ * - SqliteMemoryGraph (IMemoryGraph with spreading activation)
+ * - LoaderRegistry (document loaders: text, md, html, pdf, docx)
+ * - FolderScanner (recursive directory scanning)
+ * - ChunkingEngine (4 chunking strategies)
+ * - RetrievalFeedbackSignal (used/ignored detection)
+ * - ConsolidationLoop (6-step self-improvement)
+ * - I/O exporters and importers (JSON, Markdown, Obsidian, SQLite, ChatGPT)
+ *
+ * Consumers only need to import this single class to interact with the entire
+ * memory subsystem.
+ *
+ * @module memory/facade/Memory
+ */
+import type { MemoryTrace } from '../types.js';
+import type { MemoryConfig, RememberOptions, RecallOptions, IngestOptions, IngestResult, ExportOptions, ImportOptions, ImportResult, ConsolidationResult, MemoryHealth } from './types.js';
+import type { IKnowledgeGraph, KnowledgeEntity, KnowledgeRelation } from '../../core/knowledge/IKnowledgeGraph.js';
+/**
+ * A memory trace paired with its retrieval relevance score.
+ *
+ * Returned by {@link Memory.recall} as a ranked list of matches.
+ */
+export interface ScoredTrace {
+    /** The full memory trace envelope. */
+    trace: MemoryTrace;
+    /** Composite relevance score; higher is better. */
+    score: number;
+}
+/**
+ * Unified public API for the AgentOS memory system.
+ *
+ * One `Memory` instance manages the full lifecycle of an agent's memories:
+ * storing, retrieving, ingesting documents, building a knowledge graph,
+ * self-improving through consolidation, and importing/exporting data.
+ *
+ * ## Quick start
+ * ```ts
+ * const mem = new Memory({ store: 'sqlite', path: './brain.sqlite' });
+ *
+ * await mem.remember('The user prefers dark mode');
+ * const results = await mem.recall('dark mode preference');
+ * console.log(results[0].trace.content);
+ *
+ * await mem.close();
+ * ```
+ */
+export declare class Memory {
+    private readonly _brain;
+    private readonly _knowledgeGraph;
+    private readonly _memoryGraph;
+    private readonly _loaderRegistry;
+    private readonly _folderScanner;
+    private readonly _chunkingEngine;
+    private readonly _feedbackSignal;
+    private readonly _consolidationLoop;
+    private readonly _config;
+    private _initPromise;
+    /**
+     * Create a new Memory instance and wire together all subsystems.
+     *
+     * Initialization sequence:
+     * 1. Merge `config` with defaults (store='sqlite', path=tmpdir, graph=true,
+     *    selfImprove=true, decay=true).
+     * 2. Create `SqliteBrain(config.path)`.
+     * 3. Check embedding dimension compatibility (warn on mismatch).
+     * 4. Create `SqliteKnowledgeGraph(brain)`.
+     * 5. Create `SqliteMemoryGraph(brain)` and call `.initialize()`.
+     * 6. Create `LoaderRegistry()` (pre-registers all built-in loaders).
+     * 7. Create `FolderScanner(registry)`.
+     * 8. Create `ChunkingEngine()`.
+     * 9. If `selfImprove`: create `RetrievalFeedbackSignal(brain)` and
+     *    `ConsolidationLoop(brain, memoryGraph)`.
+     *
+     * @param config - Optional configuration; see {@link MemoryConfig}.
+     */
+    constructor(config?: MemoryConfig);
+    /**
+     * Store a new memory trace.
+     *
+     * Creates a trace in the `memory_traces` table with a unique ID, content
+     * hash for deduplication, and optional type/scope/tags metadata. If the
+     * memory graph is available the trace is also added as a graph node.
+     *
+     * @param content - The text content to remember.
+     * @param options - Optional metadata (type, scope, tags, importance, etc.).
+     * @returns The created MemoryTrace-like object.
+     */
+    remember(content: string, options?: RememberOptions): Promise<MemoryTrace>;
+    /**
+     * Search for memory traces matching a natural-language query.
+     *
+     * Uses FTS5 full-text search with the Porter tokenizer. Results are ranked
+     * by `strength * abs(fts_rank)` and filtered by optional type/scope/strength
+     * criteria.
+     *
+     * @param query   - Natural-language search query.
+     * @param options - Optional filters (limit, type, scope, minStrength).
+     * @returns Ranked array of {@link ScoredTrace} results.
+     */
+    recall(query: string, options?: RecallOptions): Promise<ScoredTrace[]>;
+    /**
+     * Soft-delete a memory trace by setting `deleted = 1`.
+     *
+     * The trace remains in the database for audit/recovery purposes but is
+     * excluded from all recall queries and health reports.
+     *
+     * @param traceId - The ID of the trace to forget.
+     */
+    forget(traceId: string): Promise<void>;
+    /**
+     * Ingest documents from a file, directory, or URL.
+     *
+     * Workflow:
+     * 1. Detect source type (file, directory, or URL).
+     * 2. Load document(s) using the appropriate loader.
+     * 3. Chunk each document using the configured strategy.
+     * 4. For each chunk: insert into `document_chunks`, create a memory trace.
+     * 5. Record the document in the `documents` table.
+     *
+     * @param source  - File path, directory path, or URL.
+     * @param options - Optional ingestion settings (recursive, include/exclude globs).
+     * @returns Summary of the ingestion run.
+     */
+    ingest(source: string, options?: IngestOptions): Promise<IngestResult>;
+    /**
+     * Add or update an entity in the knowledge graph.
+     *
+     * Delegates to `SqliteKnowledgeGraph.upsertEntity()`. Accepts a partial
+     * entity; `id`, `createdAt`, and `updatedAt` are auto-generated when omitted.
+     *
+     * @param entity - Partial entity descriptor.
+     * @returns The complete, persisted entity.
+     */
+    addEntity(entity: Partial<KnowledgeEntity>): Promise<KnowledgeEntity>;
+    /**
+     * Add or update a relation (edge) in the knowledge graph.
+     *
+     * Delegates to `SqliteKnowledgeGraph.upsertRelation()`. Accepts a partial
+     * relation; `id` and `createdAt` are auto-generated when omitted.
+     *
+     * @param relation - Partial relation descriptor.
+     * @returns The complete, persisted relation.
+     */
+    addRelation(relation: Partial<KnowledgeRelation>): Promise<KnowledgeRelation>;
+    /**
+     * Access the underlying IKnowledgeGraph implementation.
+     *
+     * Useful for advanced queries (traversal, semantic search, neighbourhood
+     * lookups) that are not exposed on the facade directly.
+     */
+    get graph(): IKnowledgeGraph;
+    /**
+     * Run one consolidation cycle (prune, merge, strengthen, derive, compact,
+     * re-index).
+     *
+     * @param options - Optional topic filter (reserved for future use).
+     * @returns Statistics from the consolidation run.
+     * @throws {Error} When `selfImprove` was set to `false` in the config.
+     */
+    consolidate(options?: {
+        topic?: string;
+    }): Promise<ConsolidationResult>;
+    /**
+     * Record retrieval feedback for a memory trace.
+     *
+     * Fire-and-forget: the feedback is persisted asynchronously and this method
+     * returns immediately without waiting for the write to complete.
+     *
+     * @param traceId - The ID of the trace being evaluated.
+     * @param signal  - Whether the trace was `'used'` or `'ignored'` by the LLM.
+     */
+    feedback(traceId: string, signal: 'used' | 'ignored'): void;
+    /**
+     * Export the memory store to a file or directory.
+     *
+     * Format is detected from `options.format` or the file extension:
+     * - `.json` -> JSON
+     * - `.sqlite` / `.db` -> SQLite file copy
+     * - directory path -> Markdown or Obsidian (based on `options.format`)
+     *
+     * @param outputPath - Path to write the export to.
+     * @param options    - Optional format and content controls.
+     */
+    export(outputPath: string, options?: ExportOptions): Promise<void>;
+    /**
+     * Import memory data from a file or directory.
+     *
+     * Format is detected from `options.format`, the file extension, or by
+     * inspecting the content.
+     *
+     * @param source  - Path to the import source (file or directory).
+     * @param options - Optional format hint and dedup settings.
+     * @returns Summary of the import operation.
+     */
+    importFrom(source: string, options?: ImportOptions): Promise<ImportResult>;
+    /**
+     * Return a health snapshot of the memory store.
+     *
+     * Queries aggregate statistics from all tables and returns a
+     * {@link MemoryHealth} report.
+     */
+    health(): Promise<MemoryHealth>;
+    /**
+     * Close the Memory instance and release all resources.
+     *
+     * Flushes the SQLite WAL and releases the file lock. Must be called when
+     * the agent shuts down.
+     */
+    close(): Promise<void>;
+    /**
+     * Convert a raw `memory_traces` row into a `MemoryTrace` object.
+     */
+    private _buildTrace;
+    /**
+     * Detect the export format from options or file extension.
+     */
+    private _detectExportFormat;
+    /**
+     * Detect the import format from options, file extension, or content inspection.
+     */
+    private _detectImportFormat;
+}
+//# sourceMappingURL=Memory.d.ts.map

package/dist/memory/facade/Memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Memory.d.ts","sourceRoot":"","sources":["../../../src/memory/facade/Memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAOH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EACV,YAAY,EACZ,eAAe,EACf,aAAa,EACb,aAAa,EACb,YAAY,EACZ,aAAa,EACb,aAAa,EACb,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACb,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EACf,iBAAiB,EAClB,MAAM,yCAAyC,CAAC;AA0BjD;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,sCAAsC;IACtC,KAAK,EAAE,WAAW,CAAC;IACnB,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;CACf;AAwDD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,MAAM;IAEjB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAuB;IACvD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAoB;IACjD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAiB;IACjD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgB;IAC/C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAiB;IACjD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAiC;IACjE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA2B;IAC9D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoG;IAC5H,OAAO,CAAC,YAAY,CAAgB;IAMpC;;;;;;;;;;;;;;;;;OAiBG;gBACS,MAAM,CAAC,EAAE,YAAY;IAwDjC;;;;;;;;;;OAUG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC;IA0EhF;;;;;;;;;;OAUG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAmD5E;;;;;;;OAOG;IACG,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY5C;;;;;;;;;;;;;OAaG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAmN5E;;;;;;;;OAQG;IACG,SAAS,CACb,MAAM,EAAE,OAAO,CAAC,eAAe,CAAC,GAC/B,OAAO,CAAC,eAAe,CAAC;IAoB3B;;;;;;;;OAQG;IACG,WAAW,CACf,QAAQ,EAAE,OAAO,CAAC,iBAAiB,CAAC,GACnC,OAAO,CAAC,iBAAiB,CAAC;IAsB7B;;;;;OAKG;IACH,IAAI,KAAK,IAAI,eAAe,CAE3B;IAMD;;;;;;;OAOG;IACG,WAAW,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAa7E;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAgB3D;;;;;;;;;;OAUG;IACG,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAgCxE;;;;;;;;;OASG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAoChF;;;;;OAKG;IACG,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAoGrC;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B;;OAEG;IACH,OAAO,CAAC,WAAW;IAgDnB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAe3B;;OAEG;YACW,mBAAmB;CA+BlC"}