@cartisien/engram 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,8 @@
 # Engram
 
-> **Persistent memory for AI assistants with temporal recall.**
+> **Persistent semantic memory for AI agents.**
+
+![Engram demo](assets/demo.gif)
 
 ```typescript
 import { Engram } from '@cartisien/engram';
@@ -8,11 +10,11 @@ import { Engram } from '@cartisien/engram';
 const memory = new Engram({ dbPath: './memory.db' });
 
 // Store
-await memory.remember('user_123', 'I ride a Triumph Bonneville', 'user');
+await memory.remember('user_123', 'User prefers TypeScript and dark mode', 'user');
 
-// Recall with temporal queries
-const yesterday = await memory.recallByTime('user_123', 'yesterday');
-const lastWeek = await memory.recallByTime('user_123', 'last week');
+// Recall semantically — finds the right memory even without exact keyword match
+const context = await memory.recall('user_123', 'what are the user\'s preferences?', 5);
+// [{ content: 'User prefers TypeScript and dark mode', similarity: 0.82, ... }]
 ```
 
 ---
@@ -21,16 +23,16 @@ const lastWeek = await memory.recallByTime('user_123', 'last week');
 
 AI assistants are amnesiacs. Every conversation starts fresh. Context windows fill up. Important details get lost.
 
-You wouldn't hire an employee who forgot every meeting. Why accept it from your AI?
+Stuffing everything into the system prompt wastes tokens and still misses things. You need a retrieval layer — not a dump.
 
 ## The Solution
 
-Engram gives your assistants **persistent, queryable memory** — backed by SQLite, designed for simplicity.
+Engram gives your agents **persistent, semantically searchable memory** — SQLite-backed, TypeScript-first, zero config.
 
-- **Zero config:** Works out of the box
-- **Fast:** SQLite with proper indexes
-- **Temporal:** Natural language time queries ("yesterday", "last week", "3 days ago")
-- **Portable:** Single file database
+- **Semantic search:** Finds relevant memories by meaning, not just keywords (via local Ollama embeddings)
+- **Zero config:** Works out of the box, falls back to keyword search without Ollama
+- **Local-first:** Your data stays on your machine. No API keys, no cloud required
+- **MCP-native:** Drop into Claude Desktop or Cursor via [`@cartisien/engram-mcp`](https://github.com/Cartisien/engram-mcp)
 - **Typed:** Full TypeScript support
 
 ## Installation
@@ -39,285 +41,184 @@ Engram gives your assistants **persistent, queryable memory** — backed by SQLi
 npm install @cartisien/engram
 ```
 
+### Optional: Local Embeddings (Recommended)
+
+For semantic search, install [Ollama](https://ollama.ai) and pull the embedding model:
+
+```bash
+ollama pull nomic-embed-text
+```
+
+Without Ollama, Engram falls back to keyword search automatically.
+
 ## Quick Start
 
 ```typescript
 import { Engram } from '@cartisien/engram';
 
 const memory = new Engram({
-  dbPath: './bot-memory.db'  // or ':memory:' for ephemeral
+  dbPath: './bot-memory.db',
+  embeddingUrl: 'http://localhost:11434', // Ollama default
 });
 
-// In your chat handler
-async function handleChat(sessionId: string, message: string) {
-  // 1. Store the user's message
-  await memory.remember(sessionId, message, 'user');
-  
-  // 2. Retrieve relevant context
+// In your agent/chat handler
+async function handleMessage(sessionId: string, message: string) {
+  // 1. Recall relevant context semantically
   const context = await memory.recall(sessionId, message, 5);
-  
-  // 3. Build prompt with memory
+
+  // 2. Build prompt with memory
   const prompt = buildPrompt(context, message);
-  
-  // 4. Get AI response
-  const response = await openai.chat.completions.create({ messages: prompt });
-  
-  // 5. Store the response
-  await memory.remember(sessionId, response.choices[0].message.content, 'assistant');
-  
-  return response;
-}
-```
 
-## Temporal Recall
+  // 3. Get AI response
+  const response = await llm.chat(prompt);
 
-Engram understands natural language time expressions. Ask for memories from any point in time:
+  // 4. Store both sides
+  await memory.remember(sessionId, message, 'user');
+  await memory.remember(sessionId, response, 'assistant');
 
-```typescript
-// Simple temporal queries
-const yesterday = await memory.recallByTime('session_123', 'yesterday');
-const lastWeek = await memory.recallByTime('session_123', 'last week');
-const threeDaysAgo = await memory.recallByTime('session_123', '3 days ago');
-
-// Combined with keyword search
-const meetingsLastWeek = await memory.recallByTime(
-  'session_123', 
-  'last week', 
-  'meeting'  // Only entries containing "meeting"
-);
-
-// Recent memories (last 7 days)
-const recent = await memory.recallRecent('session_123', 7);
-
-// Since a specific date
-const sinceLaunch = await memory.recallSince('session_123', new Date('2024-01-01'));
-
-// Daily summaries
-const lastWeekByDay = await memory.dailySummary('session_123', 7);
-// Returns: [{ date, entries: [...], count }, ...]
+  return response;
+}
 ```
 
-### Supported Temporal Expressions
-
-| Expression | Meaning |
-|------------|---------|
-| `today` | From midnight to now |
-| `yesterday` | Full previous day |
-| `tomorrow` | Next day (useful for scheduled items) |
-| `3 days ago` | Specific day 3 days back |
-| `a week ago` | 7 days ago |
-| `2 weeks ago` | 14 days ago |
-| `last monday` | Most recent Monday |
-| `last week` | Previous full week (Sun-Sat) |
-| `last month` | Previous full month |
-| `this week` | Current week (Sun-today) |
-| `this month` | Current month |
-| `last 3 days` | Last 72 hours |
-| `last 7 days` | Last week (rolling) |
-| `january 15` | Specific date |
-| `3/15` | March 15 (current year) |
-| `jan 15 to jan 20` | Date range |
-| `recent`, `lately` | Last 7 days |
-
 ## API
 
 ### `new Engram(config?)`
 
-Create a memory instance.
-
 ```typescript
 const memory = new Engram({
-  dbPath: './memory.db',        // Database file path
-  maxContextLength: 4000        // Max characters per entry
+  dbPath: './memory.db',           // SQLite file path (default: ':memory:')
+  maxContextLength: 4000,          // Max chars per entry (default: 4000)
+  embeddingUrl: 'http://localhost:11434',  // Ollama base URL
+  embeddingModel: 'nomic-embed-text',     // Embedding model
+  semanticSearch: true,            // Enable semantic search (default: true)
 });
 ```
 
 ### `remember(sessionId, content, role?, metadata?)`
 
-Store a memory entry.
+Store a memory. Embedding is generated automatically.
 
 ```typescript
-await memory.remember('session_abc', 'User loves Thai food', 'user', {
-  source: 'preference_extraction'
-});
+await memory.remember('session_abc', 'User loves Thai food', 'user');
 ```
 
 ### `recall(sessionId, query?, limit?, options?)`
 
-Retrieve memories for a session. Supports temporal filtering via `options.temporalQuery`.
+Retrieve relevant memories. Uses semantic search when available, keyword fallback otherwise. Returns entries sorted by similarity score.
 
 ```typescript
-// Recent memories
-const recent = await memory.recall('session_abc', undefined, 10);
-
-// Keyword search
-const relevant = await memory.recall('session_abc', 'food preferences', 5);
-
-// Temporal + keyword
-const yesterdayMeetings = await memory.recall(
-  'session_abc', 
-  'meeting', 
-  10, 
-  { temporalQuery: 'yesterday' }
-);
-
-// Filtered by role
-const userOnly = await memory.recall('session_abc', undefined, 10, { role: 'user' });
+const results = await memory.recall('session_abc', 'food preferences', 5);
+// [{ content: '...', similarity: 0.84, ... }]
 ```
 
-### `recallByTime(sessionId, temporalQuery, keyword?, limit?, options?)`
+### `history(sessionId, limit?)`
 
-Recall memories by natural language time expression.
+Chronological conversation history.
 
 ```typescript
-const { entries, range } = await memory.recallByTime(
-  'session_abc',
-  'last week',
-  'project update'  // optional keyword filter
-);
-
-console.log(`Found ${entries.length} entries from ${range.description}`);
-console.log(`Range: ${range.start.toDateString()} to ${range.end.toDateString()}`);
+const chat = await memory.history('session_abc', 20);
 ```
 
-### `recallRecent(sessionId, days?, keyword?, limit?, options?)`
+### `forget(sessionId, options?)`
 
-Get memories from the last N days.
+Delete memories.
 
 ```typescript
-const { entries, days, since } = await memory.recallRecent('session_abc', 7);
-console.log(`${entries.length} entries in the last ${days} days`);
+await memory.forget('session_abc');                          // all
+await memory.forget('session_abc', { id: 'entry_id' });     // one
+await memory.forget('session_abc', { before: new Date() }); // old entries
 ```
 
-### `recallSince(sessionId, since, keyword?, limit?, options?)`
+### `graph(sessionId, entity)`
 
-Get memories since a specific date.
+Returns a one-hop relationship map for a named entity — all connected entities and the memories that link them.
 
-```typescript
-const { entries, count } = await memory.recallSince(
-  'session_abc', 
-  new Date('2024-01-01')
-);
-```
-
-### `recallBetween(sessionId, start, end, keyword?, limit?, options?)`
-
-Get memories between two dates.
+Requires `graphMemory: true` in config and a running Ollama instance with `qwen2.5:32b` (or override via `graphModel`).
 
 ```typescript
-const { entries, count } = await memory.recallBetween(
-  'session_abc',
-  new Date('2024-01-01'),
-  new Date('2024-01-31')
-);
-```
-
-### `dailySummary(sessionId, days?)`
-
-Get memories grouped by day.
+const memory = new Engram({
+  dbPath: './memory.db',
+  graphMemory: true,
+  graphModel: 'qwen2.5:32b', // default
+});
 
-```typescript
-const summary = await memory.dailySummary('session_abc', 7);
-// [
-//   { date: Date, entries: MemoryEntry[], count: 5 },
-//   { date: Date, entries: MemoryEntry[], count: 3 },
-//   ...
-// ]
+const graph = await memory.graph('session_abc', 'GovScout');
+// {
+//   entity: 'GovScout',
+//   edges: [
+//     { relation: 'uses', target: 'MUI', sourceMemoryId: '...' },
+//     { relation: 'built_by', target: 'Jeff', sourceMemoryId: '...' },
+//   ],
+//   memories: [ { content: '...', ... } ]
+// }
 ```
 
-### `history(sessionId, limit?)`
-
-Get chronological conversation history.
+### `recall()` with graph augmentation
 
 ```typescript
-const chat = await memory.history('session_abc', 20);
-```
-
-### `forget(sessionId, options?)`
-
-Delete memories.
-
-```typescript
-// Delete all for session
-await memory.forget('session_abc');
-
-// Delete specific entry
-await memory.forget('session_abc', { id: 'entry_id' });
-
-// Delete before a date
-await memory.forget('session_abc', { before: new Date('2024-01-01') });
-
-// Delete in a date range
-await memory.forget('session_abc', { 
-  after: new Date('2024-01-01'),
-  before: new Date('2024-02-01')
+const results = await memory.recall('session_abc', 'what is GovScout?', 5, {
+  includeGraph: true, // augment top results with graph-connected memories
 });
 ```
 
 ### `stats(sessionId)`
 
-Get memory statistics.
-
 ```typescript
 const stats = await memory.stats('session_abc');
-// { total: 42, byRole: { user: 21, assistant: 21 }, oldest: Date, newest: Date }
+// { total: 42, byRole: { user: 21, assistant: 21 }, withEmbeddings: 42, graphNodes: 18, graphEdges: 31 }
 ```
 
-### `temporalStats(sessionId, days?)`
+## MCP Server
 
-Get activity statistics grouped by day.
+Use Engram directly in Claude Desktop, Cursor, or any MCP client:
 
-```typescript
-const activity = await memory.temporalStats('session_abc', 30);
-// [
-//   { date: '2024-01-15', count: 5, byRole: { user: 3, assistant: 2 } },
-//   ...
-// ]
+```bash
+npx -y @cartisien/engram-mcp
 ```
 
-## The TemporalQuery Parser
-
-You can use the temporal parser standalone:
-
-```typescript
-import { TemporalQuery } from '@cartisien/engram';
-
-const parser = new TemporalQuery();
-const range = parser.parse('last week');
-
-if (range) {
-  console.log(range.description);  // "last week"
-  console.log(range.start);        // Sun, Jan 07 2024 00:00:00
-  console.log(range.end);          // Sat, Jan 13 2024 23:59:59
+```json
+{
+  "mcpServers": {
+    "engram": {
+      "command": "npx",
+      "args": ["-y", "@cartisien/engram-mcp"]
+    }
+  }
 }
 ```
 
+→ [`@cartisien/engram-mcp`](https://github.com/Cartisien/engram-mcp) on GitHub
+
 ## Philosophy
 
-> *"The trace precedes presence."* — Derrida
+> *"The trace precedes presence."*
 
 Memory isn't storage. It's the substrate of self.
 
-Engram doesn't just persist data. It gives your assistants **continuity** — the ability to learn, reference, and grow across conversations. Time is not a sequence of moments to be archived, but a horizon of meaning that shifts with each recollection.
+Engram doesn't just persist data — it gives your agents **continuity**. The ability to learn, reference, and grow across conversations.
 
-The Cartesian cogito assumed memory was given. We're making it so.
+## Roadmap
 
-## The Trilogy
+- **v0.1** ✅ SQLite persistence, keyword search
+- **v0.2** ✅ Semantic search via local Ollama embeddings
+- **v0.3** ✅ Graph memory — entity relationships, connected context
+- **v0.4** 📋 Memory consolidation, long-term summarization
 
-Engram is part of the **Cartisien Memory Suite**:
+## The Cartisien Memory Suite
 
 | Package | Purpose |
 |---------|---------|
-| `@cartisien/engram` | **This package** — persistent memory with temporal recall |
-| `@cartisien/extensa` | Vector infrastructure (coming soon) |
-| `@cartisien/cogito` | Identity & state management (coming soon) |
+| [`@cartisien/engram`](https://github.com/Cartisien/engram) | Persistent memory SDK — **this package** |
+| [`@cartisien/engram-mcp`](https://github.com/Cartisien/engram-mcp) | MCP server for Claude Desktop / Cursor |
+| `@cartisien/extensa` | Vector infrastructure *(coming soon)* |
+| `@cartisien/cogito` | Agent identity & lifecycle *(coming soon)* |
 
 *Res cogitans meets res extensa.*
 
 ## License
 
-MIT © Cartisien Interactive
+MIT © [Cartisien Interactive](https://cartisien.com)
 
 ---
 
-**Built with 🖤 by people who think forgetting is a bug.**
+**Built for people who think forgetting is a bug.**

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