@cartisien/engram 0.2.0 → 0.4.0

package/dist/adapters/sqlite.js

@@ -0,0 +1,33 @@
+/**
+ * SqliteAdapter — local file-backed persistence with vector search.
+ *
+ * TODO: implement with `better-sqlite3` + manual cosine similarity
+ * (sqlite-vss or sqlite-vec extension optional).
+ */
+export class SqliteAdapter {
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    async init() {
+        throw new Error('SqliteAdapter not yet implemented. Use MemoryAdapter for now.');
+    }
+    async store(_memory) {
+        throw new Error('Not implemented');
+    }
+    async get(_id) {
+        throw new Error('Not implemented');
+    }
+    async search(_embedding, _options) {
+        throw new Error('Not implemented');
+    }
+    async forget(_id) {
+        throw new Error('Not implemented');
+    }
+    async list(_agentId, _limit) {
+        throw new Error('Not implemented');
+    }
+    async close() {
+        // no-op until implemented
+    }
+}
+//# sourceMappingURL=sqlite.js.map

package/dist/adapters/sqlite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite.js","sourceRoot":"","sources":["../../src/adapters/sqlite.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,OAAO,aAAa;IACxB,YAA6B,QAAgB;QAAhB,aAAQ,GAAR,QAAQ,CAAQ;IAAG,CAAC;IAEjD,KAAK,CAAC,IAAI;QACR,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAA;IAClF,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,OAAe;QACzB,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAA;IACpC,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAA;IACpC,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,UAAoB,EAAE,QAAiC;QAClE,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAA;IACpC,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAA;IACpC,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,QAAgB,EAAE,MAAe;QAC1C,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAA;IACpC,CAAC;IAED,KAAK,CAAC,KAAK;QACT,0BAA0B;IAC5B,CAAC;CACF"}

package/dist/engram.d.ts

@@ -0,0 +1,57 @@
+import type { EngramConfig, Memory, MemoryInput, SearchOptions, SearchResult } from './types.js';
+/**
+ * Engram — persistent semantic memory for AI agents.
+ *
+ * "We no longer live in the age of cogito. We live in the age of the trace."
+ * — Derrida (via Orlo Rodriguez, "I Compute, Therefore Am I?")
+ *
+ * Usage:
+ *   const mem = new Engram({ adapter: 'memory', agentId: 'my-agent' })
+ *   await mem.wake()
+ *   await mem.store({ content: 'The user prefers dark mode' })
+ *   const results = await mem.search('user preferences')
+ *   await mem.sleep()
+ */
+export declare class Engram {
+    private adapter;
+    private readonly config;
+    private initialized;
+    private sessionStart;
+    constructor(config: EngramConfig);
+    /**
+     * Initialize the adapter and record session start.
+     * Call this at agent startup.
+     */
+    wake(): Promise<void>;
+    /**
+     * Persist state and close connections.
+     * Call this at agent shutdown.
+     */
+    sleep(): Promise<void>;
+    /**
+     * Store a memory. Embeds content automatically.
+     */
+    store(input: MemoryInput): Promise<Memory>;
+    /**
+     * Store multiple memories in parallel.
+     */
+    storeMany(inputs: MemoryInput[]): Promise<Memory[]>;
+    /**
+     * Semantic search over stored memories.
+     */
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Retrieve a memory by ID.
+     */
+    get(id: string): Promise<Memory | null>;
+    /**
+     * Delete a memory permanently.
+     */
+    forget(id: string): Promise<void>;
+    /**
+     * List recent memories for this agent.
+     */
+    list(limit?: number): Promise<Memory[]>;
+    private ensureReady;
+}
+//# sourceMappingURL=engram.d.ts.map

package/dist/engram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engram.d.ts","sourceRoot":"","sources":["../src/engram.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,YAAY,EAEZ,MAAM,EACN,WAAW,EACX,aAAa,EACb,YAAY,EACb,MAAM,YAAY,CAAA;AAMnB;;;;;;;;;;;;GAYG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;IAC/C,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,YAAY,CAAoB;gBAE5B,MAAM,EAAE,YAAY;IAiChC;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ3B;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAe5B;;OAEG;IACG,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAqBhD;;OAEG;IACG,SAAS,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAIzD;;OAEG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAWjF;;OAEG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAK7C;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKvC;;OAEG;IACG,IAAI,CAAC,KAAK,SAAK,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;YAS3B,WAAW;CAK1B"}

package/dist/engram.js

@@ -0,0 +1,148 @@
+import { randomUUID } from 'node:crypto';
+import { MemoryAdapter } from './adapters/memory.js';
+import { PostgresAdapter } from './adapters/postgres.js';
+import { SqliteAdapter } from './adapters/sqlite.js';
+import { embedText, DEFAULT_DIMENSIONS } from './utils/embeddings.js';
+/**
+ * Engram — persistent semantic memory for AI agents.
+ *
+ * "We no longer live in the age of cogito. We live in the age of the trace."
+ * — Derrida (via Orlo Rodriguez, "I Compute, Therefore Am I?")
+ *
+ * Usage:
+ *   const mem = new Engram({ adapter: 'memory', agentId: 'my-agent' })
+ *   await mem.wake()
+ *   await mem.store({ content: 'The user prefers dark mode' })
+ *   const results = await mem.search('user preferences')
+ *   await mem.sleep()
+ */
+export class Engram {
+    constructor(config) {
+        this.initialized = false;
+        this.sessionStart = null;
+        this.config = {
+            adapter: config.adapter,
+            agentId: config.agentId,
+            connectionString: config.connectionString ?? '',
+            embeddingDimensions: config.embeddingDimensions ?? DEFAULT_DIMENSIONS,
+        };
+        switch (config.adapter) {
+            case 'memory':
+                this.adapter = new MemoryAdapter();
+                break;
+            case 'postgres':
+                if (!config.connectionString) {
+                    throw new Error('connectionString required for postgres adapter');
+                }
+                this.adapter = new PostgresAdapter(config.connectionString);
+                break;
+            case 'sqlite':
+                if (!config.connectionString) {
+                    throw new Error('connectionString (file path) required for sqlite adapter');
+                }
+                this.adapter = new SqliteAdapter(config.connectionString);
+                break;
+            default:
+                throw new Error(`Unknown adapter: ${config.adapter}`);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Lifecycle
+    // ---------------------------------------------------------------------------
+    /**
+     * Initialize the adapter and record session start.
+     * Call this at agent startup.
+     */
+    async wake() {
+        if (!this.initialized) {
+            await this.adapter.init();
+            this.initialized = true;
+        }
+        this.sessionStart = new Date();
+    }
+    /**
+     * Persist state and close connections.
+     * Call this at agent shutdown.
+     */
+    async sleep() {
+        if (this.sessionStart) {
+            const duration = Date.now() - this.sessionStart.getTime();
+            // TODO: emit session summary to a "session" memory
+            void duration;
+            this.sessionStart = null;
+        }
+        await this.adapter.close();
+        this.initialized = false;
+    }
+    // ---------------------------------------------------------------------------
+    // Core API
+    // ---------------------------------------------------------------------------
+    /**
+     * Store a memory. Embeds content automatically.
+     */
+    async store(input) {
+        await this.ensureReady();
+        const embedding = await embedText(input.content, this.config.embeddingDimensions);
+        const now = new Date();
+        const memory = {
+            id: randomUUID(),
+            agentId: this.config.agentId,
+            content: input.content,
+            embedding,
+            importance: input.importance ?? 0.5,
+            metadata: input.metadata ?? {},
+            createdAt: now,
+            accessedAt: now,
+            accessCount: 0,
+        };
+        return this.adapter.store(memory);
+    }
+    /**
+     * Store multiple memories in parallel.
+     */
+    async storeMany(inputs) {
+        return Promise.all(inputs.map((input) => this.store(input)));
+    }
+    /**
+     * Semantic search over stored memories.
+     */
+    async search(query, options = {}) {
+        await this.ensureReady();
+        const embedding = await embedText(query, this.config.embeddingDimensions);
+        return this.adapter.search(embedding, {
+            limit: options.limit ?? 10,
+            threshold: options.threshold ?? 0.0,
+            filter: options.filter ?? {},
+        });
+    }
+    /**
+     * Retrieve a memory by ID.
+     */
+    async get(id) {
+        await this.ensureReady();
+        return this.adapter.get(id);
+    }
+    /**
+     * Delete a memory permanently.
+     */
+    async forget(id) {
+        await this.ensureReady();
+        return this.adapter.forget(id);
+    }
+    /**
+     * List recent memories for this agent.
+     */
+    async list(limit = 50) {
+        await this.ensureReady();
+        return this.adapter.list(this.config.agentId, limit);
+    }
+    // ---------------------------------------------------------------------------
+    // Internals
+    // ---------------------------------------------------------------------------
+    async ensureReady() {
+        if (!this.initialized) {
+            await this.wake();
+        }
+    }
+}
+//# sourceMappingURL=engram.js.map

package/dist/engram.js.map

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

package/dist/index.d.ts

@@ -1,73 +1,89 @@
+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;
+}
+export interface GraphNode {
+    entity: string;
+    type?: string;
+}
+export interface GraphEdge {
+    from: string;
+    relation: string;
+    to: string;
+    confidence?: number;
+}
+export interface GraphResult {
+    entity: string;
+    relationships: Array<{
+        type: 'outgoing' | 'incoming';
+        relation: string;
+        target: string;
+        confidence?: number;
+    }>;
+    relatedMemories: MemoryEntry[];
 }
 export interface RecallOptions {
     limit?: number;
     before?: Date;
     after?: Date;
     role?: 'user' | 'assistant' | 'system';
+    includeGraph?: boolean;
+    tiers?: MemoryTier[];
 }
-export interface TemporalRecallOptions extends RecallOptions {
-    /** Natural language time expression: 'yesterday', 'last week', '3 days ago', etc. */
-    temporalQuery?: string;
-    /** Timezone offset in minutes from UTC (default: local timezone) */
-    timezoneOffset?: number;
+export interface ConsolidateOptions {
+    batch?: number;
+    keep?: number;
+    model?: string;
+    dryRun?: boolean;
 }
-export interface TimeRange {
-    start: Date;
-    end: Date;
-    description: string;
+export interface ConsolidationResult {
+    summarized: number;
+    created: number;
+    archived: number;
+    previews?: string[];
 }
 export interface EngramConfig {
     dbPath?: string;
     maxContextLength?: number;
+    embeddingUrl?: string;
+    embeddingModel?: string;
+    semanticSearch?: boolean;
+    graphMemory?: boolean;
+    graphModel?: string;
+    autoConsolidate?: boolean;
+    consolidateThreshold?: number;
+    consolidateKeep?: number;
+    consolidateBatch?: number;
+    consolidateModel?: string;
 }
 /**
- * Temporal query parser for natural language time expressions
- */
-export declare class TemporalQuery {
-    private referenceDate;
-    private timezoneOffset;
-    constructor(referenceDate?: Date, timezoneOffset?: number);
-    /**
-     * Parse a natural language time expression into a concrete time range
-     *
-     * Supports:
-     * - Relative: 'today', 'yesterday', 'tomorrow'
-     * - Days ago: '3 days ago', 'a week ago', '2 weeks ago'
-     * - Last: 'last monday', 'last week', 'last month'
-     * - This: 'this week', 'this month', 'this year'
-     * - Recent: 'recent', 'lately', 'recently' (last 7 days)
-     * - Between: 'january 15 to january 20', '3/1 to 3/15'
-     */
-    parse(expression: string): TimeRange | null;
-    private parseDate;
-    private startOfDay;
-    private endOfDay;
-}
-/**
- * Engram - Persistent memory for AI assistants
+ * Engram - Persistent semantic memory for AI agents
  *
- * A lightweight, SQLite-backed memory system that gives your AI assistants
- * the ability to remember conversations across sessions.
+ * 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' });
+ * const memory = new Engram({
+ *   dbPath: './memory.db',
+ *   autoConsolidate: true,
+ *   consolidateThreshold: 100,
+ * });
  *
- * // Store a memory
- * await memory.remember('user_123', 'Jeff loves Triumph motorcycles', 'user');
- *
- * // Retrieve with temporal query
- * const yesterday = await memory.recallByTime('user_123', 'yesterday');
- * const lastWeek = await memory.recallByTime('user_123', 'last week');
+ * // Manual consolidation
+ * const result = await memory.consolidate('session_1');
+ * // → { summarized: 50, created: 4, archived: 50 }
  * ```
  */
 export declare class Engram {
@@ -75,113 +91,74 @@ export declare class Engram {
     private maxContextLength;
     private dbPath;
     private initialized;
+    private embeddingUrl;
+    private embeddingModel;
+    private semanticSearch;
+    private graphMemory;
+    private graphModel;
+    private autoConsolidate;
+    private consolidateThreshold;
+    private consolidateKeep;
+    private consolidateBatch;
+    private consolidateModel;
     constructor(config?: EngramConfig);
     private init;
+    private embed;
+    private extractGraph;
+    private upsertNode;
+    private storeEdge;
+    private cosineSimilarity;
     /**
-     * Store a memory entry
+     * Call LLM to summarize a batch of memories into consolidated entries.
+     * Returns an array of summary strings (typically 2-5 per batch).
      */
-    remember(sessionId: string, content: string, role?: 'user' | 'assistant' | 'system', metadata?: Record<string, unknown>): Promise<MemoryEntry>;
+    private summarizeMemories;
     /**
-     * Recall memories for a session
+     * v0.4: Consolidate working memories into long-term summaries.
      *
-     * Supports temporal queries via options.temporalQuery:
-     * - 'yesterday', 'today', 'tomorrow'
-     * - '3 days ago', 'a week ago', '2 weeks ago'
-     * - 'last monday', 'last week', 'last month'
-     * - 'this week', 'this month'
-     * - 'last 3 days', 'last week'
-     * - 'january 15', '3/15', '2024-01-15'
-     * - 'jan 15 to jan 20', '3/1 to 3/15'
-     */
-    recall(sessionId: string, query?: string, limit?: number, options?: TemporalRecallOptions): Promise<MemoryEntry[]>;
-    /**
-     * Recall memories by natural language time expression
+     * 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
-     * // Get yesterday's memories
-     * const yesterday = await memory.recallByTime('session_123', 'yesterday');
-     *
-     * // Get last week's memories
-     * const lastWeek = await memory.recallByTime('session_123', 'last week');
+     * const result = await memory.consolidate('session_1');
+     * // → { summarized: 50, created: 4, archived: 50 }
      *
-     * // Get memories from 3 days ago
-     * const threeDaysAgo = await memory.recallByTime('session_123', '3 days ago');
+     * // Preview without writing
+     * const preview = await memory.consolidate('session_1', { dryRun: true });
+     * // → { summarized: 50, created: 0, archived: 0, previews: ['...', '...'] }
      * ```
      */
-    recallByTime(sessionId: string, temporalQuery: string, query?: string, limit?: number, options?: Omit<TemporalRecallOptions, 'temporalQuery'>): Promise<{
-        entries: MemoryEntry[];
-        range: TimeRange;
-    }>;
-    /**
-     * Get memories from the last N days
-     */
-    recallRecent(sessionId: string, days?: number, query?: string, limit?: number, options?: Omit<TemporalRecallOptions, 'after' | 'before'>): Promise<{
-        entries: MemoryEntry[];
-        days: number;
-        since: Date;
-    }>;
+    consolidate(sessionId: string, options?: ConsolidateOptions): Promise<ConsolidationResult>;
     /**
-     * Get memories since a specific date
+     * Store a memory entry. With autoConsolidate enabled, triggers consolidation
+     * when working memory count exceeds the configured threshold.
      */
-    recallSince(sessionId: string, since: Date, query?: string, limit?: number, options?: Omit<TemporalRecallOptions, 'after'>): Promise<{
-        entries: MemoryEntry[];
-        since: Date;
-        count: number;
-    }>;
-    /**
-     * Get memories between two dates
-     */
-    recallBetween(sessionId: string, start: Date, end: Date, query?: string, limit?: number, options?: Omit<TemporalRecallOptions, 'after' | 'before'>): Promise<{
-        entries: MemoryEntry[];
-        start: Date;
-        end: Date;
-        count: number;
-    }>;
-    /**
-     * Get a daily summary of memories
-     *
-     * Returns memories grouped by day, useful for "what happened each day" views
-     */
-    dailySummary(sessionId: string, days?: number): Promise<{
-        date: Date;
-        entries: MemoryEntry[];
-        count: number;
-    }[]>;
+    remember(sessionId: string, content: string, role?: 'user' | 'assistant' | 'system', metadata?: Record<string, unknown>): Promise<MemoryEntry>;
     /**
-     * Get recent conversation history for a session
+     * 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[]>;
+    private augmentWithGraph;
+    graph(sessionId: string, entity: string): Promise<GraphResult>;
     history(sessionId: string, limit?: number): Promise<MemoryEntry[]>;
-    /**
-     * Forget (delete) memories
-     */
     forget(sessionId: string, options?: {
         before?: Date;
-        after?: Date;
         id?: string;
+        includeLongTerm?: boolean;
     }): Promise<number>;
-    /**
-     * Get memory statistics for a session
-     */
     stats(sessionId: string): Promise<{
         total: number;
         byRole: Record<string, number>;
+        byTier: Record<MemoryTier, number>;
         oldest: Date | null;
         newest: Date | null;
+        withEmbeddings: number;
+        graphNodes?: number;
+        graphEdges?: number;
     }>;
-    /**
-     * Get temporal statistics for a session
-     *
-     * Returns memory counts grouped by day, useful for activity visualization
-     */
-    temporalStats(sessionId: string, days?: number): Promise<{
-        date: string;
-        count: number;
-        byRole: Record<string, number>;
-    }[]>;
-    /**
-     * Close the database connection
-     */
     close(): Promise<void>;
 }
 export default Engram;

package/dist/index.d.ts.map

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