@cartisien/engram 0.3.0 → 0.4.0

package/README.md

@@ -2,6 +2,8 @@
 
 > **Persistent semantic memory for AI agents.**
 
+![Engram demo](assets/demo.gif)
+
 ```typescript
 import { Engram } from '@cartisien/engram';
 
@@ -127,11 +129,43 @@ await memory.forget('session_abc', { id: 'entry_id' });     // one
 await memory.forget('session_abc', { before: new Date() }); // old entries
 ```
 
+### `graph(sessionId, entity)`
+
+Returns a one-hop relationship map for a named entity — all connected entities and the memories that link them.
+
+Requires `graphMemory: true` in config and a running Ollama instance with `qwen2.5:32b` (or override via `graphModel`).
+
+```typescript
+const memory = new Engram({
+  dbPath: './memory.db',
+  graphMemory: true,
+  graphModel: 'qwen2.5:32b', // default
+});
+
+const graph = await memory.graph('session_abc', 'GovScout');
+// {
+//   entity: 'GovScout',
+//   edges: [
+//     { relation: 'uses', target: 'MUI', sourceMemoryId: '...' },
+//     { relation: 'built_by', target: 'Jeff', sourceMemoryId: '...' },
+//   ],
+//   memories: [ { content: '...', ... } ]
+// }
+```
+
+### `recall()` with graph augmentation
+
+```typescript
+const results = await memory.recall('session_abc', 'what is GovScout?', 5, {
+  includeGraph: true, // augment top results with graph-connected memories
+});
+```
+
 ### `stats(sessionId)`
 
 ```typescript
 const stats = await memory.stats('session_abc');
-// { total: 42, byRole: { user: 21, assistant: 21 }, withEmbeddings: 42, ... }
+// { total: 42, byRole: { user: 21, assistant: 21 }, withEmbeddings: 42, graphNodes: 18, graphEdges: 31 }
 ```
 
 ## MCP Server
@@ -167,7 +201,7 @@ Engram doesn't just persist data — it gives your agents **continuity**. The ab
 
 - **v0.1** ✅ SQLite persistence, keyword search
 - **v0.2** ✅ Semantic search via local Ollama embeddings
-- **v0.3** 🚧 Graph memory — entity relationships, connected context
+- **v0.3** ✅ Graph memory — entity relationships, connected context
 - **v0.4** 📋 Memory consolidation, long-term summarization
 
 ## The Cartisien Memory Suite

package/dist/adapters/base.d.ts

@@ -0,0 +1,2 @@
+export type { IMemoryAdapter } from '../types.js';
+//# sourceMappingURL=base.d.ts.map

package/dist/adapters/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/adapters/base.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA"}

package/dist/adapters/base.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=base.js.map

package/dist/adapters/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/adapters/base.ts"],"names":[],"mappings":""}

package/dist/adapters/memory.d.ts

@@ -0,0 +1,17 @@
+import type { IMemoryAdapter, Memory, SearchOptions, SearchResult } from '../types.js';
+/**
+ * In-process MemoryAdapter — no persistence, ideal for testing and ephemeral agents.
+ * The simplest possible trace: exists only as long as the process lives.
+ */
+export declare class MemoryAdapter implements IMemoryAdapter {
+    private _cache;
+    init(): Promise<void>;
+    store(memory: Memory): Promise<Memory>;
+    get(id: string): Promise<Memory | null>;
+    search(embedding: number[], options: Required<SearchOptions>): Promise<SearchResult[]>;
+    forget(id: string): Promise<void>;
+    list(agentId: string, limit?: number): Promise<Memory[]>;
+    close(): Promise<void>;
+    get size(): number;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/adapters/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/adapters/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAGtF;;;GAGG;AACH,qBAAa,aAAc,YAAW,cAAc;IAClD,OAAO,CAAC,MAAM,CAA4B;IAEpC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKtC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAcvC,MAAM,CACV,SAAS,EAAE,MAAM,EAAE,EACnB,OAAO,EAAE,QAAQ,CAAC,aAAa,CAAC,GAC/B,OAAO,CAAC,YAAY,EAAE,CAAC;IAepB,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAOpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/adapters/memory.js

@@ -0,0 +1,58 @@
+import { cosineSimilarity } from '../utils/similarity.js';
+/**
+ * In-process MemoryAdapter — no persistence, ideal for testing and ephemeral agents.
+ * The simplest possible trace: exists only as long as the process lives.
+ */
+export class MemoryAdapter {
+    constructor() {
+        this._cache = new Map();
+    }
+    async init() {
+        // nothing to set up
+    }
+    async store(memory) {
+        this._cache.set(memory.id, memory);
+        return memory;
+    }
+    async get(id) {
+        const memory = this._cache.get(id) ?? null;
+        if (memory) {
+            const updated = {
+                ...memory,
+                accessedAt: new Date(),
+                accessCount: memory.accessCount + 1,
+            };
+            this._cache.set(id, updated);
+            return updated;
+        }
+        return null;
+    }
+    async search(embedding, options) {
+        const results = [];
+        for (const memory of this._cache.values()) {
+            const score = cosineSimilarity(embedding, memory.embedding);
+            if (score >= options.threshold) {
+                results.push({ memory, score });
+            }
+        }
+        return results
+            .sort((a, b) => b.score - a.score)
+            .slice(0, options.limit);
+    }
+    async forget(id) {
+        this._cache.delete(id);
+    }
+    async list(agentId, limit = 50) {
+        return [...this._cache.values()]
+            .filter((m) => m.agentId === agentId)
+            .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime())
+            .slice(0, limit);
+    }
+    async close() {
+        this._cache.clear();
+    }
+    get size() {
+        return this._cache.size;
+    }
+}
+//# sourceMappingURL=memory.js.map

package/dist/adapters/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../src/adapters/memory.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAEzD;;;GAGG;AACH,MAAM,OAAO,aAAa;IAA1B;QACU,WAAM,GAAG,IAAI,GAAG,EAAkB,CAAA;IA6D5C,CAAC;IA3DC,KAAK,CAAC,IAAI;QACR,oBAAoB;IACtB,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,MAAc;QACxB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAA;QAClC,OAAO,MAAM,CAAA;IACf,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,EAAU;QAClB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,IAAI,CAAA;QAC1C,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,OAAO,GAAW;gBACtB,GAAG,MAAM;gBACT,UAAU,EAAE,IAAI,IAAI,EAAE;gBACtB,WAAW,EAAE,MAAM,CAAC,WAAW,GAAG,CAAC;aACpC,CAAA;YACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,CAAA;YAC5B,OAAO,OAAO,CAAA;QAChB,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED,KAAK,CAAC,MAAM,CACV,SAAmB,EACnB,OAAgC;QAEhC,MAAM,OAAO,GAAmB,EAAE,CAAA;QAElC,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YAC1C,MAAM,KAAK,GAAG,gBAAgB,CAAC,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,CAAA;YAC3D,IAAI,KAAK,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;gBAC/B,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAA;YACjC,CAAC;QACH,CAAC;QAED,OAAO,OAAO;aACX,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;aACjC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAA;IAC5B,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,EAAU;QACrB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;IACxB,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,OAAe,EAAE,KAAK,GAAG,EAAE;QACpC,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;aAC7B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC;aACpC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;aAC7D,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAA;IACpB,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAA;IACrB,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAA;IACzB,CAAC;CACF"}

package/dist/adapters/postgres.d.ts

@@ -0,0 +1,33 @@
+import type { IMemoryAdapter, Memory, SearchOptions, SearchResult } from '../types.js';
+/**
+ * PostgresAdapter — uses pgvector for semantic similarity search.
+ *
+ * TODO: implement with `pg` + pgvector extension.
+ * Requires: CREATE EXTENSION IF NOT EXISTS vector;
+ *
+ * Schema:
+ *   CREATE TABLE engram_memories (
+ *     id          TEXT PRIMARY KEY,
+ *     agent_id    TEXT NOT NULL,
+ *     content     TEXT NOT NULL,
+ *     embedding   vector(1536),
+ *     importance  FLOAT NOT NULL DEFAULT 0.5,
+ *     metadata    JSONB NOT NULL DEFAULT '{}',
+ *     created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+ *     accessed_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+ *     access_count INT NOT NULL DEFAULT 0
+ *   );
+ *   CREATE INDEX ON engram_memories USING ivfflat (embedding vector_cosine_ops);
+ */
+export declare class PostgresAdapter implements IMemoryAdapter {
+    private readonly connectionString;
+    constructor(connectionString: string);
+    init(): Promise<void>;
+    store(_memory: Memory): Promise<Memory>;
+    get(_id: string): Promise<Memory | null>;
+    search(_embedding: number[], _options: Required<SearchOptions>): Promise<SearchResult[]>;
+    forget(_id: string): Promise<void>;
+    list(_agentId: string, _limit?: number): Promise<Memory[]>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=postgres.d.ts.map

package/dist/adapters/postgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../../src/adapters/postgres.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAEtF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,eAAgB,YAAW,cAAc;IACxC,OAAO,CAAC,QAAQ,CAAC,gBAAgB;gBAAhB,gBAAgB,EAAE,MAAM;IAE/C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIvC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAIxC,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAIxF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAI1D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/adapters/postgres.js

@@ -0,0 +1,47 @@
+/**
+ * PostgresAdapter — uses pgvector for semantic similarity search.
+ *
+ * TODO: implement with `pg` + pgvector extension.
+ * Requires: CREATE EXTENSION IF NOT EXISTS vector;
+ *
+ * Schema:
+ *   CREATE TABLE engram_memories (
+ *     id          TEXT PRIMARY KEY,
+ *     agent_id    TEXT NOT NULL,
+ *     content     TEXT NOT NULL,
+ *     embedding   vector(1536),
+ *     importance  FLOAT NOT NULL DEFAULT 0.5,
+ *     metadata    JSONB NOT NULL DEFAULT '{}',
+ *     created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+ *     accessed_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+ *     access_count INT NOT NULL DEFAULT 0
+ *   );
+ *   CREATE INDEX ON engram_memories USING ivfflat (embedding vector_cosine_ops);
+ */
+export class PostgresAdapter {
+    constructor(connectionString) {
+        this.connectionString = connectionString;
+    }
+    async init() {
+        throw new Error('PostgresAdapter 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=postgres.js.map

package/dist/adapters/postgres.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.js","sourceRoot":"","sources":["../../src/adapters/postgres.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,eAAe;IAC1B,YAA6B,gBAAwB;QAAxB,qBAAgB,GAAhB,gBAAgB,CAAQ;IAAG,CAAC;IAEzD,KAAK,CAAC,IAAI;QACR,MAAM,IAAI,KAAK,CAAC,iEAAiE,CAAC,CAAA;IACpF,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/adapters/sqlite.d.ts

@@ -0,0 +1,19 @@
+import type { IMemoryAdapter, Memory, SearchOptions, SearchResult } from '../types.js';
+/**
+ * SqliteAdapter — local file-backed persistence with vector search.
+ *
+ * TODO: implement with `better-sqlite3` + manual cosine similarity
+ * (sqlite-vss or sqlite-vec extension optional).
+ */
+export declare class SqliteAdapter implements IMemoryAdapter {
+    private readonly filePath;
+    constructor(filePath: string);
+    init(): Promise<void>;
+    store(_memory: Memory): Promise<Memory>;
+    get(_id: string): Promise<Memory | null>;
+    search(_embedding: number[], _options: Required<SearchOptions>): Promise<SearchResult[]>;
+    forget(_id: string): Promise<void>;
+    list(_agentId: string, _limit?: number): Promise<Memory[]>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=sqlite.d.ts.map

package/dist/adapters/sqlite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite.d.ts","sourceRoot":"","sources":["../../src/adapters/sqlite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAEtF;;;;;GAKG;AACH,qBAAa,aAAc,YAAW,cAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,MAAM;IAEvC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIvC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAIxC,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAIxF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAI1D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

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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"}