@cartisien/engram 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -1,9 +1,12 @@
+export type MemoryTier = 'working' | 'long_term' | 'archived';
 export interface MemoryEntry {
     id: string;
     sessionId: string;
     content: string;
     role: 'user' | 'assistant' | 'system';
     timestamp: Date;
+    tier: MemoryTier;
+    consolidatedFrom?: string[];
     metadata?: Record<string, unknown>;
     similarity?: number;
 }
@@ -33,6 +36,19 @@ export interface RecallOptions {
     after?: Date;
     role?: 'user' | 'assistant' | 'system';
     includeGraph?: boolean;
+    tiers?: MemoryTier[];
+}
+export interface ConsolidateOptions {
+    batch?: number;
+    keep?: number;
+    model?: string;
+    dryRun?: boolean;
+}
+export interface ConsolidationResult {
+    summarized: number;
+    created: number;
+    archived: number;
+    previews?: string[];
 }
 export interface EngramConfig {
     dbPath?: string;
@@ -42,23 +58,32 @@ export interface EngramConfig {
     semanticSearch?: boolean;
     graphMemory?: boolean;
     graphModel?: string;
+    autoConsolidate?: boolean;
+    consolidateThreshold?: number;
+    consolidateKeep?: number;
+    consolidateBatch?: number;
+    consolidateModel?: string;
 }
 /**
  * Engram - Persistent semantic memory for AI agents
  *
- * v0.3 adds graph memory — entity relationships extracted from memories
- * using a local LLM, enabling richer contextual recall.
+ * v0.4 adds memory consolidation — working memories are periodically
+ * summarized into long-term memories by a local LLM, keeping context
+ * dense and relevant as conversations grow.
  *
  * @example
  * ```typescript
  * import { Engram } from '@cartisien/engram';
  *
- * const memory = new Engram({ dbPath: './memory.db', graphMemory: true });
+ * const memory = new Engram({
+ *   dbPath: './memory.db',
+ *   autoConsolidate: true,
+ *   consolidateThreshold: 100,
+ * });
  *
- * await memory.remember('session_1', 'Jeff is building GovScout in React 19', 'user');
- * const context = await memory.recall('session_1', 'what is Jeff building?', 5);
- * const graph = await memory.graph('session_1', 'GovScout');
- * // → { entity: 'GovScout', relationships: [{ relation: 'built_with', target: 'React 19' }], ... }
+ * // Manual consolidation
+ * const result = await memory.consolidate('session_1');
+ * // → { summarized: 50, created: 4, archived: 50 }
  * ```
  */
 export declare class Engram {
@@ -71,61 +96,63 @@ export declare class Engram {
     private semanticSearch;
     private graphMemory;
     private graphModel;
+    private autoConsolidate;
+    private consolidateThreshold;
+    private consolidateKeep;
+    private consolidateBatch;
+    private consolidateModel;
     constructor(config?: EngramConfig);
     private init;
-    /**
-     * Fetch embedding vector from Ollama
-     */
     private embed;
-    /**
-     * Extract entity-relationship triples from text using a local LLM
-     */
     private extractGraph;
-    /**
-     * Upsert a graph node
-     */
     private upsertNode;
+    private storeEdge;
+    private cosineSimilarity;
     /**
-     * Store a graph edge
+     * Call LLM to summarize a batch of memories into consolidated entries.
+     * Returns an array of summary strings (typically 2-5 per batch).
      */
-    private storeEdge;
+    private summarizeMemories;
     /**
-     * Cosine similarity between two vectors
+     * v0.4: Consolidate working memories into long-term summaries.
+     *
+     * Takes the oldest `batch` working memories (excluding the `keep` most recent),
+     * summarizes them via LLM, stores summaries as `long_term` tier, and archives
+     * the originals.
+     *
+     * @example
+     * ```typescript
+     * const result = await memory.consolidate('session_1');
+     * // → { summarized: 50, created: 4, archived: 50 }
+     *
+     * // Preview without writing
+     * const preview = await memory.consolidate('session_1', { dryRun: true });
+     * // → { summarized: 50, created: 0, archived: 0, previews: ['...', '...'] }
+     * ```
      */
-    private cosineSimilarity;
+    consolidate(sessionId: string, options?: ConsolidateOptions): Promise<ConsolidationResult>;
     /**
-     * Store a memory entry
+     * Store a memory entry. With autoConsolidate enabled, triggers consolidation
+     * when working memory count exceeds the configured threshold.
      */
     remember(sessionId: string, content: string, role?: 'user' | 'assistant' | 'system', metadata?: Record<string, unknown>): Promise<MemoryEntry>;
     /**
-     * Recall memories with optional graph traversal
+     * Recall memories. Searches working and long_term tiers by default.
+     * Archived memories (consolidated originals) are excluded unless explicitly requested.
      */
     recall(sessionId: string, query?: string, limit?: number, options?: RecallOptions): Promise<MemoryEntry[]>;
-    /**
-     * Augment recall results with graph-connected memories
-     */
     private augmentWithGraph;
-    /**
-     * v0.3: Query the knowledge graph for an entity
-     */
     graph(sessionId: string, entity: string): Promise<GraphResult>;
-    /**
-     * Get recent conversation history
-     */
     history(sessionId: string, limit?: number): Promise<MemoryEntry[]>;
-    /**
-     * Delete memories
-     */
     forget(sessionId: string, options?: {
         before?: Date;
         id?: string;
+        includeLongTerm?: boolean;
     }): Promise<number>;
-    /**
-     * Memory statistics
-     */
     stats(sessionId: string): Promise<{
         total: number;
         byRole: Record<string, number>;
+        byTier: Record<MemoryTier, number>;
         oldest: Date | null;
         newest: Date | null;
         withEmbeddings: number;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;IACtC,SAAS,EAAE,IAAI,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,KAAK,CAAC;QACnB,IAAI,EAAE,UAAU,GAAG,UAAU,CAAC;QAC9B,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;IACH,eAAe,EAAE,WAAW,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,IAAI,CAAC;IACd,KAAK,CAAC,EAAE,IAAI,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;IACvC,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,EAAE,CAAkB;IAC5B,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,cAAc,CAAU;IAChC,OAAO,CAAC,WAAW,CAAU;IAC7B,OAAO,CAAC,UAAU,CAAS;gBAEf,MAAM,GAAE,YAAiB;YAUvB,IAAI;IAoElB;;OAEG;YACW,KAAK;IAgBnB;;OAEG;YACW,YAAY;IAyC1B;;OAEG;YACW,UAAU;IASxB;;OAEG;YACW,SAAS;IAgBvB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAWxB;;OAEG;IACG,QAAQ,CACZ,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,MAAM,GAAG,WAAW,GAAG,QAAiB,EAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,WAAW,CAAC;IAwCvB;;OAEG;IACG,MAAM,CACV,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,MAAM,EACd,KAAK,GAAE,MAAW,EAClB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,WAAW,EAAE,CAAC;IA4EzB;;OAEG;YACW,gBAAgB;IAiD9B;;OAEG;IACG,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IA4DpE;;OAEG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAI5E;;OAEG;IACG,MAAM,CACV,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,IAAI,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,GACvC,OAAO,CAAC,MAAM,CAAC;IAuBlB;;OAEG;IACG,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QACtC,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,MAAM,EAAE,IAAI,GAAG,IAAI,CAAC;QACpB,MAAM,EAAE,IAAI,GAAG,IAAI,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC;QACvB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IA2CI,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAM7B;AAED,eAAe,MAAM,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}