@cartisien/engram 1.0.0 → 1.0.1

package/README.md

@@ -1,270 +1,353 @@
 # Engram
 
-> **Persistent semantic memory for AI agents.**
+> Persistent semantic memory for AI agents — local-first, zero cloud, zero config.
 
-![Engram demo](assets/demo.gif)
+[![npm](https://img.shields.io/npm/v/@cartisien/engram)](https://www.npmjs.com/package/@cartisien/engram)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18988892.svg)](https://doi.org/10.5281/zenodo.18988892)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
-```typescript
-import { Engram } from '@cartisien/engram';
+---
 
-const memory = new Engram({ dbPath: './memory.db' });
+## Quickstart — 30 seconds
 
-// Store
-await memory.remember('user_123', 'User prefers TypeScript and dark mode', 'user');
+### Claude Desktop / Cursor (MCP)
 
-// 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, ... }]
+```json
+{
+  "mcpServers": {
+    "engram": {
+      "command": "npx",
+      "args": ["-y", "@cartisien/engram-mcp"]
+    }
+  }
+}
 ```
 
+That's it. Engram gives Claude persistent memory across conversations — stored locally in a SQLite file, no API key required.
+
+→ Full MCP docs: [`@cartisien/engram-mcp`](https://github.com/Cartisien/engram-mcp)
+
 ---
 
-## The Problem
+### TypeScript / Node.js SDK
+
+```bash
+npm install @cartisien/engram
+```
 
-AI assistants are amnesiacs. Every conversation starts fresh. Context windows fill up. Important details get lost.
+```typescript
+import { Engram } from '@cartisien/engram';
 
-Stuffing everything into the system prompt wastes tokens and still misses things. You need a retrieval layer — not a dump.
+const memory = new Engram(); // zero config — saves to ./engram.db
 
-## The Solution
+await memory.remember('user_123', 'Prefers TypeScript and dark mode');
+const context = await memory.recall('user_123', 'what does this user prefer?');
+// → [{ content: 'Prefers TypeScript and dark mode', similarity: 0.91 }]
+```
 
-Engram gives your agents **persistent, semantically searchable memory** — SQLite-backed, TypeScript-first, zero config.
+No Ollama? It falls back to keyword search automatically and tells you:
+```
+[engram] Ollama not found — falling back to keyword search.
+         For semantic search: install Ollama and run: ollama pull nomic-embed-text
+```
 
-- **Semantic search:** Finds relevant memories by meaning, not just keywords (via local Ollama embeddings)
-- **Graph memory:** Extracts entity-relationship triples — recall connected context automatically
-- **Consolidation:** Summarizes old memories into long-term entries so context stays dense, not noisy
-- **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
+### Python SDK
 
 ```bash
-npm install @cartisien/engram
+pip install cartisien-engram
 ```
 
-### Optional: Local Embeddings (Recommended)
+```python
+from cartisien_engram import Engram
 
-For semantic search, install [Ollama](https://ollama.ai) and pull the embedding model:
+memory = Engram()  # saves to ./engram.db
 
-```bash
-ollama pull nomic-embed-text
+memory.remember("user_123", "Prefers dark mode and async Python")
+context = memory.recall("user_123", "user preferences")
 ```
 
-Without Ollama, Engram falls back to keyword search automatically.
+---
+
+## Drop into your agent
 
-## Quick Start
+Paste this into any LLM chat handler:
 
 ```typescript
 import { Engram } from '@cartisien/engram';
 
-const memory = new Engram({
-  dbPath: './bot-memory.db',
-  embeddingUrl: 'http://localhost:11434', // Ollama default
-});
-
-// 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);
+const memory = new Engram();
 
-  // 2. Build prompt with memory
-  const prompt = buildPrompt(context, message);
+async function chat(sessionId: string, userMessage: string, llm: any) {
+  // 1. Pull relevant context before calling LLM
+  const context = await memory.recall(sessionId, userMessage, 5);
+  const contextStr = context.map(m => m.content).join('\n');
 
-  // 3. Get AI response
-  const response = await llm.chat(prompt);
+  // 2. Call your LLM with memory in the system prompt
+  const response = await llm.chat({
+    system: `Relevant context from memory:\n${contextStr}`,
+    user: userMessage,
+  });
 
-  // 4. Store both sides
-  await memory.remember(sessionId, message, 'user');
+  // 3. Store both sides
+  await memory.remember(sessionId, userMessage, 'user');
   await memory.remember(sessionId, response, 'assistant');
 
   return response;
 }
 ```
 
+**Vercel AI SDK:**
+```typescript
+import { Engram } from '@cartisien/engram';
+import { streamText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+const memory = new Engram();
+
+export async function POST(req: Request) {
+  const { messages, sessionId } = await req.json();
+  const lastMessage = messages.at(-1)?.content ?? '';
+
+  const context = await memory.recall(sessionId, lastMessage, 5);
+  const contextStr = context.map(m => m.content).join('\n');
+
+  // Store user message
+  await memory.remember(sessionId, lastMessage, 'user');
+
+  const result = streamText({
+    model: openai('gpt-4o'),
+    system: context.length ? `Memory:\n${contextStr}` : undefined,
+    messages,
+    onFinish: async ({ text }) => {
+      await memory.remember(sessionId, text, 'assistant');
+    },
+  });
+
+  return result.toDataStreamResponse();
+}
+```
+
+---
+
+## Why Engram
+
+AI assistants forget everything between conversations. Most memory solutions either:
+- Require cloud accounts and send your data to their servers
+- Store raw chunks that go stale and contradict each other
+
+Engram stores memories as **evolving beliefs** — locally, in SQLite, with no cloud dependency.
+
+| | Engram | Mem0 | Zep |
+|---|---|---|---|
+| Local-first | ✅ | ⚠️ self-host option | ⚠️ self-host option |
+| Zero API key | ✅ | ❌ | ❌ |
+| Zero config | ✅ | ❌ | ❌ |
+| TypeScript-first | ✅ | ❌ Python-first | ❌ Python-first |
+| MCP native | ✅ | ❌ | ❌ |
+| Belief revision | ✅ | ⚠️ | ❌ |
+| Open source | ✅ MIT | ✅ | ✅ |
+
+---
+
+## Semantic search setup (optional)
+
+Engram uses Ollama for local embeddings. Without it, keyword search works automatically.
+
+```bash
+# Install Ollama: https://ollama.ai
+ollama pull nomic-embed-text
+```
+
+That's the only setup step. Engram detects it automatically.
+
+---
+
 ## API
 
-### `new Engram(config?)`
+### Core
 
 ```typescript
-const memory = new Engram({
-  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)
-});
+const memory = new Engram(config?)
 ```
 
-### `remember(sessionId, content, role?, metadata?)`
+Config defaults (all optional):
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `dbPath` | `./engram.db` | SQLite file path |
+| `embeddingUrl` | `$OLLAMA_URL` or `http://localhost:11434` | Ollama base URL |
+| `embeddingModel` | `nomic-embed-text` | Embedding model |
+| `semanticSearch` | `true` | Enable semantic search |
+| `graphMemory` | `false` | Entity relationship extraction |
+| `autoConsolidate` | `false` | Auto-summarize old memories |
 
-Store a memory. Embedding is generated automatically.
+### `remember(sessionId, content, role?, metadata?)`
+Store a memory. Embedding generated automatically.
 
 ```typescript
-await memory.remember('session_abc', 'User loves Thai food', 'user');
+await memory.remember('session_1', 'User is vegetarian', 'user');
 ```
 
 ### `recall(sessionId, query?, limit?, options?)`
-
-Retrieve relevant memories. Uses semantic search when available, keyword fallback otherwise. Returns entries sorted by similarity score.
+Retrieve relevant memories. Semantic + keyword + recency, merged via RRF.
 
 ```typescript
-const results = await memory.recall('session_abc', 'food preferences', 5);
-// [{ content: '...', similarity: 0.84, ... }]
+const results = await memory.recall('session_1', 'dietary preferences', 5);
+// [{ content: 'User is vegetarian', similarity: 0.91, certainty: 0.5, ... }]
 ```
 
 ### `history(sessionId, limit?)`
-
 Chronological conversation history.
 
 ```typescript
-const chat = await memory.history('session_abc', 20);
+const chat = await memory.history('session_1', 20);
 ```
 
 ### `forget(sessionId, options?)`
-
 Delete memories.
 
 ```typescript
-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
+await memory.forget('session_1');                           // all
+await memory.forget('session_1', { id: 'entry_id' });      // one
+await memory.forget('session_1', { before: new Date() });  // old
 ```
 
-### `graph(sessionId, entity)`
+### `stats(sessionId)`
+Memory counts by tier, role, embeddings.
 
-Returns a one-hop relationship map for a named entity — all connected entities and the memories that link them.
+```typescript
+const s = await memory.stats('session_1');
+// { total: 42, byTier: { working: 30, long_term: 12 }, withEmbeddings: 42 }
+```
 
-Requires `graphMemory: true` in config and a running Ollama instance with `qwen2.5:32b` (or override via `graphModel`).
+---
+
+## Belief revision
+
+Every memory has a `certainty` score (0–1). Stale or contradicted memories fade naturally.
 
 ```typescript
-const memory = new Engram({
-  dbPath: './memory.db',
-  graphMemory: true,
-  graphModel: 'qwen2.5:32b', // default
-});
+// Confirm a memory
+await memory.reinforce(entryId);               // certainty += 0.15
 
-const graph = await memory.graph('session_abc', 'GovScout');
-// {
-//   entity: 'GovScout',
-//   edges: [
-//     { relation: 'uses', target: 'MUI', sourceMemoryId: '...' },
-//     { relation: 'built_by', target: 'Jeff', sourceMemoryId: '...' },
-//   ],
-//   memories: [ { content: '...', ... } ]
-// }
-```
+// Flag a contradiction — old memory marked contradicted, new one stored
+await memory.contradict('session_1', oldId, 'User switched to dark mode');
 
-### `recall()` with graph augmentation
+// Remove a memory from recall
+await memory.invalidate(entryId);
 
-```typescript
-const results = await memory.recall('session_abc', 'what is GovScout?', 5, {
-  includeGraph: true, // augment top results with graph-connected memories
-});
+// Detect contradictions before storing
+const result = await memory.detectContradictions('session_1', newContent);
+if (result.detected) { /* handle */ }
 ```
 
-### `consolidate(sessionId, options?)` *(v0.4)*
+---
 
-Summarizes old working memories into dense long-term entries via a local LLM. Originals are archived (hidden from recall but not deleted).
+## Consolidation
+
+Summarize old working memories into dense long-term entries via local LLM.
 
 ```typescript
 const memory = new Engram({
-  dbPath: './memory.db',
-  autoConsolidate: true,       // auto-trigger on remember() (default: false)
-  consolidateThreshold: 100,   // trigger when working memories exceed this (default: 100)
-  consolidateKeep: 20,         // keep N most recent working memories untouched (default: 20)
-  consolidateBatch: 50,        // memories to process per run (default: 50)
-  consolidateModel: 'qwen2.5:32b', // LLM for summarization
+  autoConsolidate: true,
+  consolidateThreshold: 100,  // trigger when working memories exceed this
+  consolidateModel: 'qwen2.5:32b',
 });
 
-// Manual consolidation
-const result = await memory.consolidate('session_abc');
+// Or manually
+const result = await memory.consolidate('session_1');
 // → { summarized: 50, created: 4, archived: 50 }
 
 // Preview without writing
-const preview = await memory.consolidate('session_abc', { dryRun: true });
-// → { summarized: 50, created: 0, archived: 0, previews: ['User prefers TypeScript...', ...] }
+const preview = await memory.consolidate('session_1', { dryRun: true });
 ```
 
-**Memory tiers:**
-- `working` — recent, granular memories (default)
-- `long_term` — LLM-generated summaries of consolidated batches
-- `archived` — original memories after consolidation (excluded from recall)
+---
+
+## Graph memory
 
-`recall()` searches `working` and `long_term` by default. Pass `tiers` to override:
+Entity-relationship extraction for connected context.
 
 ```typescript
-// Search all tiers including archived
-const results = await memory.recall('session_abc', 'preferences', 10, {
-  tiers: ['working', 'long_term', 'archived'],
+const memory = new Engram({ graphMemory: true });
+
+// After remembering "Jeff is building GovScout with MUI and React"
+const graph = await memory.graph('session_1', 'GovScout');
+// {
+//   entity: 'govscout',
+//   relationships: [
+//     { type: 'outgoing', relation: 'uses', target: 'mui' },
+//     { type: 'outgoing', relation: 'built_by', target: 'jeff' },
+//   ]
+// }
+
+// Auto-augment recall with graph-connected memories
+const results = await memory.recall('session_1', 'what is GovScout?', 5, {
+  includeGraph: true,
 });
 ```
 
-### `stats(sessionId)`
+---
+
+## reflect()
+
+Synthesize insights across memories — actual reasoning, not just retrieval.
 
 ```typescript
-const stats = await memory.stats('session_abc');
-// {
-//   total: 42,
-//   byRole: { user: 21, assistant: 21 },
-//   byTier: { working: 30, long_term: 12, archived: 50 },
-//   withEmbeddings: 42,
-//   graphNodes: 18,
-//   graphEdges: 31
+const result = await memory.reflect('session_1', 'What does this user care most about?');
+// → {
+//   insights: [
+//     'User strongly prefers TypeScript over JavaScript',
+//     'Has a recurring deadline sensitivity around Fridays',
+//   ],
+//   memoriesUsed: [...],
 // }
 ```
 
-## MCP Server
+---
 
-Use Engram directly in Claude Desktop, Cursor, or any MCP client:
+## User-scoped memory
 
-```bash
-npx -y @cartisien/engram-mcp
-```
+Persist facts about a user across all sessions.
 
-```json
-{
-  "mcpServers": {
-    "engram": {
-      "command": "npx",
-      "args": ["-y", "@cartisien/engram-mcp"]
-    }
-  }
-}
-```
+```typescript
+await memory.rememberUser('user_jeff', 'Prefers TypeScript');
+await memory.rememberUser('user_jeff', 'Timezone: America/New_York');
 
-→ [`@cartisien/engram-mcp`](https://github.com/Cartisien/engram-mcp) on GitHub
+// Blend into any session recall
+const results = await memory.recall('any_session', 'preferences', 10, {
+  userId: 'user_jeff',
+});
+```
 
-## Philosophy
+---
 
-> *"The trace precedes presence."*
+## Remote client
 
-Memory isn't storage. It's the substrate of self.
+Connect to a self-hosted Engram server.
 
-Engram doesn't just persist data — it gives your agents **continuity**. The ability to learn, reference, and grow across conversations.
+```typescript
+import { EngramClient } from '@cartisien/engram';
 
-## Roadmap
+const memory = new EngramClient({ baseUrl: 'http://your-server:3470' });
+// Same API as Engram
+```
 
-- **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
+---
 
 ## The Cartisien Memory Suite
 
 | Package | Purpose |
 |---------|---------|
-| [`@cartisien/engram`](https://github.com/Cartisien/engram) | Persistent memory SDK — **this package** |
+| [`@cartisien/engram`](https://github.com/Cartisien/engram) | 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)* |
+| `@cartisien/extensa` | Vector infrastructure |
+| `@cartisien/cogito` | Agent identity & lifecycle |
 
-*Res cogitans meets res extensa.*
+---
 
 ## License
 
 MIT © [Cartisien Interactive](https://cartisien.com)
-
----
-
-**Built for people who think forgetting is a bug.**

package/dist/benchmarks/ab-eval/harness.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A/B Evaluation Harness
+ *
+ * Compares two retrieval modes:
+ *   Mode A: Raw chunk retrieval — embed query, cosine search against raw conversation text
+ *   Mode B: Claim retrieval — extractClaims + runAllValidators, embed canonical_text, cosine search
+ *
+ * For each question, both modes retrieve context, then an LLM answers from that context.
+ * Scoring uses exact substring match + LLM-based semantic match as fallback.
+ */
+import type { ConversationTurn } from '../../compiler/schemas.js';
+import { type EvalQuestion } from './questions.js';
+export interface PerQuestionResult {
+    questionId: number;
+    question: string;
+    expected_answer: string;
+    mode_a_answer: string;
+    mode_b_answer: string;
+    mode_a_correct: boolean;
+    mode_b_correct: boolean;
+    mode_a_context: string;
+    mode_b_context: string;
+}
+export interface ABTestReport {
+    mode_a_score: number;
+    mode_b_score: number;
+    total_questions: number;
+    per_question_results: PerQuestionResult[];
+}
+export declare function runABTest(apiKey: string, corpus: ConversationTurn[][], questions?: EvalQuestion[]): Promise<ABTestReport>;
+//# sourceMappingURL=harness.d.ts.map

package/dist/benchmarks/ab-eval/harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.d.ts","sourceRoot":"","sources":["../../../src/benchmarks/ab-eval/harness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAA;AAKjE,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAMlE,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,eAAe,EAAE,MAAM,CAAA;IACvB,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,cAAc,EAAE,OAAO,CAAA;IACvB,cAAc,EAAE,OAAO,CAAA;IACvB,cAAc,EAAE,MAAM,CAAA;IACtB,cAAc,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,EAAE,MAAM,CAAA;IACpB,eAAe,EAAE,MAAM,CAAA;IACvB,oBAAoB,EAAE,iBAAiB,EAAE,CAAA;CAC1C;AA8LD,wBAAsB,SAAS,CAC7B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,gBAAgB,EAAE,EAAE,EAC5B,SAAS,CAAC,EAAE,YAAY,EAAE,GACzB,OAAO,CAAC,YAAY,CAAC,CAiEvB"}