@getanima/core 0.3.3 → 0.4.0

package/dist/episodes.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Episodic Memory Engine — structured records of experiences.
+ *
+ * Unlike flat memories, episodes capture the full context of an experience:
+ * who was involved, what happened, how important it was, what was learned,
+ * and how it connects to other memories, opinions, and knowledge.
+ *
+ * Episodes decay based on importance and emotional weight.
+ * High-importance episodes get promoted to semantic knowledge automatically.
+ *
+ * Zero external dependencies. File-based persistence.
+ */
+import type { Episode, EpisodeInput, EpisodeQuery, EpisodeStats, KnowledgeEntry, KnowledgeInput } from './types';
+export declare class EpisodicMemory {
+    private storagePath;
+    private episodesDir;
+    private knowledgeDir;
+    private episodes;
+    private knowledge;
+    private loaded;
+    private knowledgeLoaded;
+    constructor(storagePath: string);
+    /**
+     * Record a new episode — a structured experience.
+     *
+     * @example
+     * ```ts
+     * await episodes.record({
+     *   title: 'Customer escalation resolved',
+     *   summary: 'User was frustrated about billing. De-escalated with empathy first.',
+     *   emotionalWeight: 0.7,
+     *   participants: ['user-123'],
+     *   tags: ['customer-service', 'conflict'],
+     *   lessons: ['Empathy before solutions works better than jumping to fixes'],
+     * });
+     * ```
+     */
+    record(input: EpisodeInput): Promise<Episode>;
+    /**
+     * Search episodes by various criteria.
+     * Returns episodes sorted by relevance (importance * recency * match).
+     */
+    query(q: EpisodeQuery): Promise<Episode[]>;
+    /**
+     * Get a single episode by ID.
+     */
+    get(id: string): Promise<Episode | null>;
+    /**
+     * Get the most recent N episodes.
+     */
+    recent(limit?: number): Promise<Episode[]>;
+    /**
+     * Get episodes connected to a specific episode.
+     */
+    related(episodeId: string): Promise<Episode[]>;
+    /**
+     * Add a lesson learned to an existing episode.
+     * Use when you realize something new about a past experience.
+     */
+    addLesson(episodeId: string, lesson: string): Promise<Episode | null>;
+    /**
+     * Connect two episodes together.
+     */
+    connect(episodeIdA: string, episodeIdB: string): Promise<boolean>;
+    /**
+     * Archive an episode (soft delete). Can be restored.
+     */
+    archive(episodeId: string): Promise<boolean>;
+    /**
+     * Restore an archived episode.
+     */
+    restore(episodeId: string): Promise<boolean>;
+    /**
+     * Store a distilled lesson — semantic knowledge not tied to a specific moment.
+     *
+     * @example
+     * ```ts
+     * await episodes.learn({
+     *   topic: 'customer-retention',
+     *   insight: 'Users who get a callback within 2 hours have 3x retention',
+     *   confidence: 0.8,
+     *   tags: ['business', 'retention'],
+     * });
+     * ```
+     */
+    learn(input: KnowledgeInput): Promise<KnowledgeEntry>;
+    /**
+     * Search knowledge by topic or text.
+     */
+    recall(query: string, limit?: number): Promise<KnowledgeEntry[]>;
+    /**
+     * Get all knowledge entries.
+     */
+    getAllKnowledge(): Promise<KnowledgeEntry[]>;
+    /**
+     * Consolidate episodes — decay old ones, promote lessons, clean up.
+     * Call this periodically (e.g., during heartbeats or sleep).
+     */
+    consolidate(): Promise<EpisodeStats>;
+    stats(): Promise<EpisodeStats>;
+    private calculateImportance;
+    private validateConnections;
+    private extractTopicFromLesson;
+    private load;
+    private save;
+    private loadKnowledge;
+    private saveKnowledge;
+}
+//# sourceMappingURL=episodes.d.ts.map

package/dist/episodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"episodes.d.ts","sourceRoot":"","sources":["../src/episodes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAwBjH,qBAAa,cAAc;IACzB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,SAAS,CAAwB;IACzC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,eAAe,CAAS;gBAEpB,WAAW,EAAE,MAAM;IAQ/B;;;;;;;;;;;;;;OAcG;IACG,MAAM,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;IAmFnD;;;OAGG;IACG,KAAK,CAAC,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAgGhD;;OAEG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAU9C;;OAEG;IACG,MAAM,CAAC,KAAK,GAAE,MAAW,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAQpD;;OAEG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAoBpD;;;OAGG;IACG,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAuB3E;;OAEG;IACG,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAwBvE;;OAEG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAUlD;;OAEG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYlD;;;;;;;;;;;;OAYG;IACG,KAAK,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAiE3D;;OAEG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IA2B1E;;OAEG;IACG,eAAe,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAOlD;;;OAGG;IACG,WAAW,IAAI,OAAO,CAAC,YAAY,CAAC;IA+DpC,KAAK,IAAI,OAAO,CAAC,YAAY,CAAC;IAepC,OAAO,CAAC,mBAAmB;IA2B3B,OAAO,CAAC,mBAAmB;IAmB3B,OAAO,CAAC,sBAAsB;YAOhB,IAAI;YAcJ,IAAI;YAQJ,aAAa;YAcb,aAAa;CAO5B"}