@cartisien/engram-mcp 0.1.0

package/README.md

@@ -0,0 +1,114 @@
+# @cartisien/engram-mcp
+
+> Persistent semantic memory for AI agents — MCP server powered by [@cartisien/engram](https://github.com/Cartisien/engram)
+
+Give any MCP-compatible AI client (Claude Desktop, Cursor, Windsurf) persistent memory that survives across sessions.
+
+```
+npx -y @cartisien/engram-mcp
+```
+
+---
+
+## What it does
+
+Exposes 5 tools to any MCP client:
+
+| Tool | Description |
+|------|-------------|
+| `remember` | Store a memory with automatic embedding |
+| `recall` | Semantic search across stored memories |
+| `history` | Recent conversation history |
+| `forget` | Delete one memory, a session, or entries before a date |
+| `stats` | Memory statistics for a session |
+
+Memories are stored in SQLite. Semantic search uses local Ollama embeddings (`nomic-embed-text`) — no API key, no cloud. Falls back to keyword search if Ollama isn't available.
+
+---
+
+## Quick Start
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "engram": {
+      "command": "npx",
+      "args": ["-y", "@cartisien/engram-mcp"],
+      "env": {
+        "ENGRAM_DB": "~/.engram/memory.db"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You'll see `remember`, `recall`, `history`, `forget`, and `stats` available as tools.
+
+### Cursor / Windsurf
+
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "engram": {
+      "command": "npx",
+      "args": ["-y", "@cartisien/engram-mcp"]
+    }
+  }
+}
+```
+
+---
+
+## Configuration
+
+| Env Var | Default | Description |
+|---------|---------|-------------|
+| `ENGRAM_DB` | `~/.engram/memory.db` | SQLite database path |
+| `ENGRAM_EMBEDDING_URL` | `http://localhost:11434` | Ollama base URL for embeddings |
+
+### Local Embeddings (Recommended)
+
+Install [Ollama](https://ollama.ai) and pull the embedding model:
+
+```bash
+ollama pull nomic-embed-text
+```
+
+Semantic search activates automatically. Without Ollama, keyword search is used.
+
+---
+
+## Example Usage
+
+Once connected, your agent can:
+
+```
+remember(sessionId="myagent", content="User prefers TypeScript over JavaScript", role="user")
+
+recall(sessionId="myagent", query="what are the user's coding preferences?", limit=5)
+# Returns: [{ content: "User prefers TypeScript...", similarity: 0.82 }, ...]
+
+history(sessionId="myagent", limit=10)
+
+stats(sessionId="myagent")
+# { total: 42, byRole: { user: 20, assistant: 22 }, withEmbeddings: 42 }
+```
+
+---
+
+## Part of the Cartisien Memory Suite
+
+- [`@cartisien/engram`](https://github.com/Cartisien/engram) — core memory SDK
+- `@cartisien/engram-mcp` — this package, MCP server
+- `@cartisien/extensa` — vector infrastructure *(coming soon)*
+- `@cartisien/cogito` — agent identity & lifecycle *(coming soon)*
+
+---
+
+MIT © [Cartisien Interactive](https://cartisien.com)

package/dist/engram.d.ts

@@ -0,0 +1,99 @@
+export interface MemoryEntry {
+    id: string;
+    sessionId: string;
+    content: string;
+    role: 'user' | 'assistant' | 'system';
+    timestamp: Date;
+    metadata?: Record<string, unknown>;
+    similarity?: number;
+}
+export interface RecallOptions {
+    limit?: number;
+    before?: Date;
+    after?: Date;
+    role?: 'user' | 'assistant' | 'system';
+}
+export interface EngramConfig {
+    dbPath?: string;
+    maxContextLength?: number;
+    embeddingUrl?: string;
+    embeddingModel?: string;
+    semanticSearch?: boolean;
+}
+/**
+ * Engram - Persistent memory for AI assistants
+ *
+ * A lightweight, SQLite-backed memory system that gives your AI assistants
+ * the ability to remember conversations across sessions.
+ * v0.2 adds semantic search via Ollama embeddings (nomic-embed-text).
+ *
+ * @example
+ * ```typescript
+ * import { Engram } from '@cartisien/engram';
+ *
+ * const memory = new Engram({ dbPath: './memory.db' });
+ *
+ * // Store a memory
+ * await memory.remember('user_123', 'User prefers dark mode and TypeScript', 'user');
+ *
+ * // Retrieve relevant memories semantically
+ * const context = await memory.recall('user_123', 'What are this user\'s preferences?', 5);
+ * ```
+ */
+export declare class Engram {
+    private db;
+    private maxContextLength;
+    private dbPath;
+    private initialized;
+    private embeddingUrl;
+    private embeddingModel;
+    private semanticSearch;
+    constructor(config?: EngramConfig);
+    private init;
+    /**
+     * Fetch embedding vector from Ollama
+     */
+    private embed;
+    /**
+     * Cosine similarity between two vectors
+     */
+    private cosineSimilarity;
+    /**
+     * Store a memory entry
+     */
+    remember(sessionId: string, content: string, role?: 'user' | 'assistant' | 'system', metadata?: Record<string, unknown>): Promise<MemoryEntry>;
+    /**
+     * Recall memories for a session.
+     *
+     * With semantic search enabled (default), embeds the query and ranks
+     * results by cosine similarity. Falls back to keyword search if Ollama
+     * is unreachable or no embeddings are stored.
+     */
+    recall(sessionId: string, query?: string, limit?: number, options?: RecallOptions): Promise<MemoryEntry[]>;
+    /**
+     * Get recent conversation history for a session
+     */
+    history(sessionId: string, limit?: number): Promise<MemoryEntry[]>;
+    /**
+     * Forget (delete) memories
+     */
+    forget(sessionId: string, options?: {
+        before?: Date;
+        id?: string;
+    }): Promise<number>;
+    /**
+     * Get memory statistics for a session
+     */
+    stats(sessionId: string): Promise<{
+        total: number;
+        byRole: Record<string, number>;
+        oldest: Date | null;
+        newest: Date | null;
+        withEmbeddings: number;
+    }>;
+    /**
+     * Close the database connection
+     */
+    close(): Promise<void>;
+}
+export default Engram;

package/dist/engram.js

@@ -0,0 +1,283 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Engram = void 0;
+const crypto_1 = require("crypto");
+/**
+ * Engram - Persistent memory for AI assistants
+ *
+ * A lightweight, SQLite-backed memory system that gives your AI assistants
+ * the ability to remember conversations across sessions.
+ * v0.2 adds semantic search via Ollama embeddings (nomic-embed-text).
+ *
+ * @example
+ * ```typescript
+ * import { Engram } from '@cartisien/engram';
+ *
+ * const memory = new Engram({ dbPath: './memory.db' });
+ *
+ * // Store a memory
+ * await memory.remember('user_123', 'User prefers dark mode and TypeScript', 'user');
+ *
+ * // Retrieve relevant memories semantically
+ * const context = await memory.recall('user_123', 'What are this user\'s preferences?', 5);
+ * ```
+ */
+class Engram {
+    constructor(config = {}) {
+        this.initialized = false;
+        this.dbPath = config.dbPath || ':memory:';
+        this.maxContextLength = config.maxContextLength || 4000;
+        this.embeddingUrl = config.embeddingUrl || 'http://192.168.68.73:11434';
+        this.embeddingModel = config.embeddingModel || 'nomic-embed-text';
+        this.semanticSearch = config.semanticSearch !== false;
+    }
+    async init() {
+        if (this.initialized)
+            return;
+        const sqlite3 = require('sqlite3').verbose();
+        const { open } = require('sqlite');
+        this.db = await open({
+            filename: this.dbPath,
+            driver: sqlite3.Database
+        });
+        await this.db.exec(`
+      CREATE TABLE IF NOT EXISTS memories (
+        id TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL,
+        content TEXT NOT NULL,
+        role TEXT CHECK(role IN ('user', 'assistant', 'system')),
+        timestamp INTEGER NOT NULL,
+        metadata TEXT,
+        content_hash TEXT NOT NULL,
+        embedding TEXT
+      );
+    `);
+        // Add embedding column if upgrading from v0.1
+        try {
+            await this.db.exec(`ALTER TABLE memories ADD COLUMN embedding TEXT`);
+        }
+        catch {
+            // Column already exists, ignore
+        }
+        await this.db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_session_timestamp
+      ON memories(session_id, timestamp DESC);
+    `);
+        await this.db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_content
+      ON memories(content);
+    `);
+        this.initialized = true;
+    }
+    /**
+     * Fetch embedding vector from Ollama
+     */
+    async embed(text) {
+        try {
+            const response = await fetch(`${this.embeddingUrl}/api/embeddings`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ model: this.embeddingModel, prompt: text }),
+                signal: AbortSignal.timeout(5000)
+            });
+            if (!response.ok)
+                return null;
+            const data = await response.json();
+            return data.embedding ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Cosine similarity between two vectors
+     */
+    cosineSimilarity(a, b) {
+        let dot = 0, magA = 0, magB = 0;
+        for (let i = 0; i < a.length; i++) {
+            dot += a[i] * b[i];
+            magA += a[i] * a[i];
+            magB += b[i] * b[i];
+        }
+        const denom = Math.sqrt(magA) * Math.sqrt(magB);
+        return denom === 0 ? 0 : dot / denom;
+    }
+    /**
+     * Store a memory entry
+     */
+    async remember(sessionId, content, role = 'user', metadata) {
+        await this.init();
+        const id = (0, crypto_1.createHash)('sha256')
+            .update(`${sessionId}:${content}:${Date.now()}`)
+            .digest('hex')
+            .slice(0, 16);
+        const contentHash = (0, crypto_1.createHash)('sha256')
+            .update(content)
+            .digest('hex')
+            .slice(0, 16);
+        const truncated = content.slice(0, this.maxContextLength);
+        // Fetch embedding if semantic search enabled
+        let embeddingJson = null;
+        if (this.semanticSearch) {
+            const vector = await this.embed(truncated);
+            if (vector)
+                embeddingJson = JSON.stringify(vector);
+        }
+        const entry = {
+            id,
+            sessionId,
+            content: truncated,
+            role,
+            timestamp: new Date(),
+            metadata
+        };
+        await this.db.run(`INSERT INTO memories (id, session_id, content, role, timestamp, metadata, content_hash, embedding)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [
+            entry.id,
+            entry.sessionId,
+            entry.content,
+            entry.role,
+            entry.timestamp.getTime(),
+            metadata ? JSON.stringify(metadata) : null,
+            contentHash,
+            embeddingJson
+        ]);
+        return entry;
+    }
+    /**
+     * Recall memories for a session.
+     *
+     * With semantic search enabled (default), embeds the query and ranks
+     * results by cosine similarity. Falls back to keyword search if Ollama
+     * is unreachable or no embeddings are stored.
+     */
+    async recall(sessionId, query, limit = 10, options = {}) {
+        await this.init();
+        // Build base query
+        let sql = `
+      SELECT id, session_id, content, role, timestamp, metadata, embedding
+      FROM memories
+      WHERE session_id = ?
+    `;
+        const params = [sessionId];
+        if (options.role) {
+            sql += ` AND role = ?`;
+            params.push(options.role);
+        }
+        if (options.after) {
+            sql += ` AND timestamp >= ?`;
+            params.push(options.after.getTime());
+        }
+        if (options.before) {
+            sql += ` AND timestamp <= ?`;
+            params.push(options.before.getTime());
+        }
+        // Try semantic search
+        if (query && query.trim() && this.semanticSearch) {
+            const queryVector = await this.embed(query);
+            if (queryVector) {
+                sql += ` ORDER BY timestamp DESC`;
+                const rows = await this.db.all(sql, params);
+                // Score each row by cosine similarity
+                const scored = rows
+                    .map((row) => {
+                    let similarity = 0;
+                    if (row.embedding) {
+                        try {
+                            const vec = JSON.parse(row.embedding);
+                            similarity = this.cosineSimilarity(queryVector, vec);
+                        }
+                        catch { /* malformed, skip */ }
+                    }
+                    return { row, similarity };
+                })
+                    .sort((a, b) => b.similarity - a.similarity)
+                    .slice(0, limit);
+                return scored.map(({ row, similarity }) => ({
+                    id: row.id,
+                    sessionId: row.session_id,
+                    content: row.content,
+                    role: row.role,
+                    timestamp: new Date(row.timestamp),
+                    metadata: row.metadata ? JSON.parse(row.metadata) : undefined,
+                    similarity
+                }));
+            }
+            // Ollama unreachable — fall through to keyword search
+        }
+        // Keyword fallback
+        if (query && query.trim()) {
+            const keywords = query.toLowerCase().split(/\s+/).filter(k => k.length > 2);
+            if (keywords.length > 0) {
+                sql += ` AND (` + keywords.map(() => `LOWER(content) LIKE ?`).join(' OR ') + `)`;
+                params.push(...keywords.map(k => `%${k}%`));
+            }
+        }
+        sql += ` ORDER BY timestamp DESC LIMIT ?`;
+        params.push(limit);
+        const rows = await this.db.all(sql, params);
+        return rows.map((row) => ({
+            id: row.id,
+            sessionId: row.session_id,
+            content: row.content,
+            role: row.role,
+            timestamp: new Date(row.timestamp),
+            metadata: row.metadata ? JSON.parse(row.metadata) : undefined
+        }));
+    }
+    /**
+     * Get recent conversation history for a session
+     */
+    async history(sessionId, limit = 20) {
+        return this.recall(sessionId, undefined, limit, {});
+    }
+    /**
+     * Forget (delete) memories
+     */
+    async forget(sessionId, options) {
+        await this.init();
+        if (options?.id) {
+            const result = await this.db.run('DELETE FROM memories WHERE session_id = ? AND id = ?', [sessionId, options.id]);
+            return result.changes || 0;
+        }
+        let sql = 'DELETE FROM memories WHERE session_id = ?';
+        const params = [sessionId];
+        if (options?.before) {
+            sql += ' AND timestamp < ?';
+            params.push(options.before.getTime());
+        }
+        const result = await this.db.run(sql, params);
+        return result.changes || 0;
+    }
+    /**
+     * Get memory statistics for a session
+     */
+    async stats(sessionId) {
+        await this.init();
+        const totalRow = await this.db.get('SELECT COUNT(*) as count FROM memories WHERE session_id = ?', [sessionId]);
+        const total = totalRow?.count || 0;
+        const roleRows = await this.db.all('SELECT role, COUNT(*) as count FROM memories WHERE session_id = ? GROUP BY role', [sessionId]);
+        const byRole = {};
+        roleRows.forEach((row) => { byRole[row.role] = row.count; });
+        const range = await this.db.get('SELECT MIN(timestamp) as oldest, MAX(timestamp) as newest FROM memories WHERE session_id = ?', [sessionId]);
+        const embRow = await this.db.get('SELECT COUNT(*) as count FROM memories WHERE session_id = ? AND embedding IS NOT NULL', [sessionId]);
+        return {
+            total,
+            byRole,
+            oldest: range?.oldest ? new Date(range.oldest) : null,
+            newest: range?.newest ? new Date(range.newest) : null,
+            withEmbeddings: embRow?.count || 0
+        };
+    }
+    /**
+     * Close the database connection
+     */
+    async close() {
+        if (this.db) {
+            await this.db.close();
+            this.initialized = false;
+        }
+    }
+}
+exports.Engram = Engram;
+exports.default = Engram;

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/index.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const engram_js_1 = require("../engram.js");
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const DB_PATH = process.env.ENGRAM_DB || path.join(os.homedir(), '.engram', 'memory.db');
+const EMBEDDING_URL = process.env.ENGRAM_EMBEDDING_URL || 'http://192.168.68.73:11434';
+// Ensure DB directory exists
+const dbDir = path.dirname(DB_PATH);
+if (!fs.existsSync(dbDir))
+    fs.mkdirSync(dbDir, { recursive: true });
+const memory = new engram_js_1.Engram({
+    dbPath: DB_PATH,
+    embeddingUrl: EMBEDDING_URL,
+    semanticSearch: true,
+});
+const server = new index_js_1.Server({ name: 'engram', version: '0.1.0' }, { capabilities: { tools: {} } });
+server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: 'remember',
+            description: 'Store a memory entry for a session. Embeddings are generated automatically for semantic recall.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    sessionId: { type: 'string', description: 'Session identifier (e.g. agent name or user ID)' },
+                    content: { type: 'string', description: 'The memory content to store' },
+                    role: { type: 'string', enum: ['user', 'assistant', 'system'], description: 'Role of the memory source', default: 'user' },
+                },
+                required: ['sessionId', 'content'],
+            },
+        },
+        {
+            name: 'recall',
+            description: 'Retrieve relevant memories using semantic search. Falls back to keyword search if embeddings unavailable.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    sessionId: { type: 'string', description: 'Session identifier' },
+                    query: { type: 'string', description: 'Search query — semantic similarity is used' },
+                    limit: { type: 'number', description: 'Max results to return (default 10)', default: 10 },
+                },
+                required: ['sessionId', 'query'],
+            },
+        },
+        {
+            name: 'history',
+            description: 'Get recent conversation history for a session in chronological order.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    sessionId: { type: 'string', description: 'Session identifier' },
+                    limit: { type: 'number', description: 'Max entries to return (default 20)', default: 20 },
+                },
+                required: ['sessionId'],
+            },
+        },
+        {
+            name: 'forget',
+            description: 'Delete memories for a session. Delete all, one by ID, or entries before a date.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    sessionId: { type: 'string', description: 'Session identifier' },
+                    id: { type: 'string', description: 'Specific memory ID to delete (optional)' },
+                    before: { type: 'string', description: 'ISO date string — delete entries before this date (optional)' },
+                },
+                required: ['sessionId'],
+            },
+        },
+        {
+            name: 'stats',
+            description: 'Get memory statistics for a session.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    sessionId: { type: 'string', description: 'Session identifier' },
+                },
+                required: ['sessionId'],
+            },
+        },
+    ],
+}));
+server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+    try {
+        switch (name) {
+            case 'remember': {
+                const entry = await memory.remember(args.sessionId, args.content, args.role || 'user');
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(entry, null, 2) }],
+                };
+            }
+            case 'recall': {
+                const entries = await memory.recall(args.sessionId, args.query, args.limit || 10);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(entries, null, 2) }],
+                };
+            }
+            case 'history': {
+                const entries = await memory.history(args.sessionId, args.limit || 20);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(entries, null, 2) }],
+                };
+            }
+            case 'forget': {
+                const options = {};
+                if (args.id)
+                    options.id = args.id;
+                if (args.before)
+                    options.before = new Date(args.before);
+                const deleted = await memory.forget(args.sessionId, options);
+                return {
+                    content: [{ type: 'text', text: `Deleted ${deleted} memor${deleted === 1 ? 'y' : 'ies'}.` }],
+                };
+            }
+            case 'stats': {
+                const stats = await memory.stats(args.sessionId);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(stats, null, 2) }],
+                };
+            }
+            default:
+                return {
+                    content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+                    isError: true,
+                };
+        }
+    }
+    catch (err) {
+        return {
+            content: [{ type: 'text', text: `Error: ${err.message}` }],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write('Engram MCP server running\n');
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal: ${err.message}\n`);
+    process.exit(1);
+});

package/engram.ts

@@ -0,0 +1,385 @@
+import { createHash } from 'crypto';
+import { open, Database as SQLiteDatabase } from 'sqlite';
+
+export interface MemoryEntry {
+  id: string;
+  sessionId: string;
+  content: string;
+  role: 'user' | 'assistant' | 'system';
+  timestamp: Date;
+  metadata?: Record<string, unknown>;
+  similarity?: number;
+}
+
+export interface RecallOptions {
+  limit?: number;
+  before?: Date;
+  after?: Date;
+  role?: 'user' | 'assistant' | 'system';
+}
+
+export interface EngramConfig {
+  dbPath?: string;
+  maxContextLength?: number;
+  embeddingUrl?: string;
+  embeddingModel?: string;
+  semanticSearch?: boolean;
+}
+
+/**
+ * Engram - Persistent memory for AI assistants
+ *
+ * A lightweight, SQLite-backed memory system that gives your AI assistants
+ * the ability to remember conversations across sessions.
+ * v0.2 adds semantic search via Ollama embeddings (nomic-embed-text).
+ *
+ * @example
+ * ```typescript
+ * import { Engram } from '@cartisien/engram';
+ *
+ * const memory = new Engram({ dbPath: './memory.db' });
+ *
+ * // Store a memory
+ * await memory.remember('user_123', 'User prefers dark mode and TypeScript', 'user');
+ *
+ * // Retrieve relevant memories semantically
+ * const context = await memory.recall('user_123', 'What are this user\'s preferences?', 5);
+ * ```
+ */
+export class Engram {
+  private db!: SQLiteDatabase;
+  private maxContextLength: number;
+  private dbPath: string;
+  private initialized: boolean = false;
+  private embeddingUrl: string;
+  private embeddingModel: string;
+  private semanticSearch: boolean;
+
+  constructor(config: EngramConfig = {}) {
+    this.dbPath = config.dbPath || ':memory:';
+    this.maxContextLength = config.maxContextLength || 4000;
+    this.embeddingUrl = config.embeddingUrl || 'http://192.168.68.73:11434';
+    this.embeddingModel = config.embeddingModel || 'nomic-embed-text';
+    this.semanticSearch = config.semanticSearch !== false;
+  }
+
+  private async init(): Promise<void> {
+    if (this.initialized) return;
+
+    const sqlite3 = require('sqlite3').verbose();
+    const { open } = require('sqlite');
+
+    this.db = await open({
+      filename: this.dbPath,
+      driver: sqlite3.Database
+    });
+
+    await this.db.exec(`
+      CREATE TABLE IF NOT EXISTS memories (
+        id TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL,
+        content TEXT NOT NULL,
+        role TEXT CHECK(role IN ('user', 'assistant', 'system')),
+        timestamp INTEGER NOT NULL,
+        metadata TEXT,
+        content_hash TEXT NOT NULL,
+        embedding TEXT
+      );
+    `);
+
+    // Add embedding column if upgrading from v0.1
+    try {
+      await this.db.exec(`ALTER TABLE memories ADD COLUMN embedding TEXT`);
+    } catch {
+      // Column already exists, ignore
+    }
+
+    await this.db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_session_timestamp
+      ON memories(session_id, timestamp DESC);
+    `);
+
+    await this.db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_content
+      ON memories(content);
+    `);
+
+    this.initialized = true;
+  }
+
+  /**
+   * Fetch embedding vector from Ollama
+   */
+  private async embed(text: string): Promise<number[] | null> {
+    try {
+      const response = await fetch(`${this.embeddingUrl}/api/embeddings`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ model: this.embeddingModel, prompt: text }),
+        signal: AbortSignal.timeout(5000)
+      });
+      if (!response.ok) return null;
+      const data = await response.json() as { embedding: number[] };
+      return data.embedding ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Cosine similarity between two vectors
+   */
+  private cosineSimilarity(a: number[], b: number[]): number {
+    let dot = 0, magA = 0, magB = 0;
+    for (let i = 0; i < a.length; i++) {
+      dot += a[i] * b[i];
+      magA += a[i] * a[i];
+      magB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(magA) * Math.sqrt(magB);
+    return denom === 0 ? 0 : dot / denom;
+  }
+
+  /**
+   * Store a memory entry
+   */
+  async remember(
+    sessionId: string,
+    content: string,
+    role: 'user' | 'assistant' | 'system' = 'user',
+    metadata?: Record<string, unknown>
+  ): Promise<MemoryEntry> {
+    await this.init();
+
+    const id = createHash('sha256')
+      .update(`${sessionId}:${content}:${Date.now()}`)
+      .digest('hex')
+      .slice(0, 16);
+
+    const contentHash = createHash('sha256')
+      .update(content)
+      .digest('hex')
+      .slice(0, 16);
+
+    const truncated = content.slice(0, this.maxContextLength);
+
+    // Fetch embedding if semantic search enabled
+    let embeddingJson: string | null = null;
+    if (this.semanticSearch) {
+      const vector = await this.embed(truncated);
+      if (vector) embeddingJson = JSON.stringify(vector);
+    }
+
+    const entry: MemoryEntry = {
+      id,
+      sessionId,
+      content: truncated,
+      role,
+      timestamp: new Date(),
+      metadata
+    };
+
+    await this.db.run(
+      `INSERT INTO memories (id, session_id, content, role, timestamp, metadata, content_hash, embedding)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        entry.id,
+        entry.sessionId,
+        entry.content,
+        entry.role,
+        entry.timestamp.getTime(),
+        metadata ? JSON.stringify(metadata) : null,
+        contentHash,
+        embeddingJson
+      ]
+    );
+
+    return entry;
+  }
+
+  /**
+   * Recall memories for a session.
+   *
+   * With semantic search enabled (default), embeds the query and ranks
+   * results by cosine similarity. Falls back to keyword search if Ollama
+   * is unreachable or no embeddings are stored.
+   */
+  async recall(
+    sessionId: string,
+    query?: string,
+    limit: number = 10,
+    options: RecallOptions = {}
+  ): Promise<MemoryEntry[]> {
+    await this.init();
+
+    // Build base query
+    let sql = `
+      SELECT id, session_id, content, role, timestamp, metadata, embedding
+      FROM memories
+      WHERE session_id = ?
+    `;
+    const params: (string | number)[] = [sessionId];
+
+    if (options.role) {
+      sql += ` AND role = ?`;
+      params.push(options.role);
+    }
+    if (options.after) {
+      sql += ` AND timestamp >= ?`;
+      params.push(options.after.getTime());
+    }
+    if (options.before) {
+      sql += ` AND timestamp <= ?`;
+      params.push(options.before.getTime());
+    }
+
+    // Try semantic search
+    if (query && query.trim() && this.semanticSearch) {
+      const queryVector = await this.embed(query);
+      if (queryVector) {
+        sql += ` ORDER BY timestamp DESC`;
+        const rows = await this.db.all(sql, params);
+
+        // Score each row by cosine similarity
+        const scored = rows
+          .map((row: any) => {
+            let similarity = 0;
+            if (row.embedding) {
+              try {
+                const vec: number[] = JSON.parse(row.embedding);
+                similarity = this.cosineSimilarity(queryVector, vec);
+              } catch { /* malformed, skip */ }
+            }
+            return { row, similarity };
+          })
+          .sort((a, b) => b.similarity - a.similarity)
+          .slice(0, limit);
+
+        return scored.map(({ row, similarity }) => ({
+          id: row.id,
+          sessionId: row.session_id,
+          content: row.content,
+          role: row.role,
+          timestamp: new Date(row.timestamp),
+          metadata: row.metadata ? JSON.parse(row.metadata) : undefined,
+          similarity
+        }));
+      }
+      // Ollama unreachable — fall through to keyword search
+    }
+
+    // Keyword fallback
+    if (query && query.trim()) {
+      const keywords = query.toLowerCase().split(/\s+/).filter(k => k.length > 2);
+      if (keywords.length > 0) {
+        sql += ` AND (` + keywords.map(() => `LOWER(content) LIKE ?`).join(' OR ') + `)`;
+        params.push(...keywords.map(k => `%${k}%`));
+      }
+    }
+
+    sql += ` ORDER BY timestamp DESC LIMIT ?`;
+    params.push(limit);
+
+    const rows = await this.db.all(sql, params);
+    return rows.map((row: any) => ({
+      id: row.id,
+      sessionId: row.session_id,
+      content: row.content,
+      role: row.role,
+      timestamp: new Date(row.timestamp),
+      metadata: row.metadata ? JSON.parse(row.metadata) : undefined
+    }));
+  }
+
+  /**
+   * Get recent conversation history for a session
+   */
+  async history(sessionId: string, limit: number = 20): Promise<MemoryEntry[]> {
+    return this.recall(sessionId, undefined, limit, {});
+  }
+
+  /**
+   * Forget (delete) memories
+   */
+  async forget(
+    sessionId: string,
+    options?: { before?: Date; id?: string }
+  ): Promise<number> {
+    await this.init();
+
+    if (options?.id) {
+      const result = await this.db.run(
+        'DELETE FROM memories WHERE session_id = ? AND id = ?',
+        [sessionId, options.id]
+      );
+      return result.changes || 0;
+    }
+
+    let sql = 'DELETE FROM memories WHERE session_id = ?';
+    const params: (string | number)[] = [sessionId];
+
+    if (options?.before) {
+      sql += ' AND timestamp < ?';
+      params.push(options.before.getTime());
+    }
+
+    const result = await this.db.run(sql, params);
+    return result.changes || 0;
+  }
+
+  /**
+   * Get memory statistics for a session
+   */
+  async stats(sessionId: string): Promise<{
+    total: number;
+    byRole: Record<string, number>;
+    oldest: Date | null;
+    newest: Date | null;
+    withEmbeddings: number;
+  }> {
+    await this.init();
+
+    const totalRow = await this.db.get(
+      'SELECT COUNT(*) as count FROM memories WHERE session_id = ?',
+      [sessionId]
+    );
+    const total = totalRow?.count || 0;
+
+    const roleRows = await this.db.all(
+      'SELECT role, COUNT(*) as count FROM memories WHERE session_id = ? GROUP BY role',
+      [sessionId]
+    );
+    const byRole: Record<string, number> = {};
+    roleRows.forEach((row: any) => { byRole[row.role] = row.count; });
+
+    const range = await this.db.get(
+      'SELECT MIN(timestamp) as oldest, MAX(timestamp) as newest FROM memories WHERE session_id = ?',
+      [sessionId]
+    );
+
+    const embRow = await this.db.get(
+      'SELECT COUNT(*) as count FROM memories WHERE session_id = ? AND embedding IS NOT NULL',
+      [sessionId]
+    );
+
+    return {
+      total,
+      byRole,
+      oldest: range?.oldest ? new Date(range.oldest) : null,
+      newest: range?.newest ? new Date(range.newest) : null,
+      withEmbeddings: embRow?.count || 0
+    };
+  }
+
+  /**
+   * Close the database connection
+   */
+  async close(): Promise<void> {
+    if (this.db) {
+      await this.db.close();
+      this.initialized = false;
+    }
+  }
+}
+
+export default Engram;

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@cartisien/engram-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for @cartisien/engram \u2014 persistent semantic memory for AI agents",
+  "main": "dist/index.js",
+  "bin": {
+    "engram-mcp": "dist/src/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "sqlite": "^5.1.1",
+    "sqlite3": "^5.1.7"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { Engram } from '../engram.js';
+import * as os from 'os';
+import * as path from 'path';
+import * as fs from 'fs';
+
+const DB_PATH = process.env.ENGRAM_DB || path.join(os.homedir(), '.engram', 'memory.db');
+const EMBEDDING_URL = process.env.ENGRAM_EMBEDDING_URL || 'http://192.168.68.73:11434';
+
+// Ensure DB directory exists
+const dbDir = path.dirname(DB_PATH);
+if (!fs.existsSync(dbDir)) fs.mkdirSync(dbDir, { recursive: true });
+
+const memory = new Engram({
+  dbPath: DB_PATH,
+  embeddingUrl: EMBEDDING_URL,
+  semanticSearch: true,
+});
+
+const server = new Server(
+  { name: 'engram', version: '0.1.0' },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: 'remember',
+      description: 'Store a memory entry for a session. Embeddings are generated automatically for semantic recall.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          sessionId: { type: 'string', description: 'Session identifier (e.g. agent name or user ID)' },
+          content: { type: 'string', description: 'The memory content to store' },
+          role: { type: 'string', enum: ['user', 'assistant', 'system'], description: 'Role of the memory source', default: 'user' },
+        },
+        required: ['sessionId', 'content'],
+      },
+    },
+    {
+      name: 'recall',
+      description: 'Retrieve relevant memories using semantic search. Falls back to keyword search if embeddings unavailable.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          sessionId: { type: 'string', description: 'Session identifier' },
+          query: { type: 'string', description: 'Search query — semantic similarity is used' },
+          limit: { type: 'number', description: 'Max results to return (default 10)', default: 10 },
+        },
+        required: ['sessionId', 'query'],
+      },
+    },
+    {
+      name: 'history',
+      description: 'Get recent conversation history for a session in chronological order.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          sessionId: { type: 'string', description: 'Session identifier' },
+          limit: { type: 'number', description: 'Max entries to return (default 20)', default: 20 },
+        },
+        required: ['sessionId'],
+      },
+    },
+    {
+      name: 'forget',
+      description: 'Delete memories for a session. Delete all, one by ID, or entries before a date.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          sessionId: { type: 'string', description: 'Session identifier' },
+          id: { type: 'string', description: 'Specific memory ID to delete (optional)' },
+          before: { type: 'string', description: 'ISO date string — delete entries before this date (optional)' },
+        },
+        required: ['sessionId'],
+      },
+    },
+    {
+      name: 'stats',
+      description: 'Get memory statistics for a session.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          sessionId: { type: 'string', description: 'Session identifier' },
+        },
+        required: ['sessionId'],
+      },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args = {} } = request.params;
+
+  try {
+    switch (name) {
+      case 'remember': {
+        const entry = await memory.remember(
+          args.sessionId as string,
+          args.content as string,
+          (args.role as 'user' | 'assistant' | 'system') || 'user'
+        );
+        return {
+          content: [{ type: 'text', text: JSON.stringify(entry, null, 2) }],
+        };
+      }
+
+      case 'recall': {
+        const entries = await memory.recall(
+          args.sessionId as string,
+          args.query as string,
+          (args.limit as number) || 10
+        );
+        return {
+          content: [{ type: 'text', text: JSON.stringify(entries, null, 2) }],
+        };
+      }
+
+      case 'history': {
+        const entries = await memory.history(
+          args.sessionId as string,
+          (args.limit as number) || 20
+        );
+        return {
+          content: [{ type: 'text', text: JSON.stringify(entries, null, 2) }],
+        };
+      }
+
+      case 'forget': {
+        const options: { id?: string; before?: Date } = {};
+        if (args.id) options.id = args.id as string;
+        if (args.before) options.before = new Date(args.before as string);
+        const deleted = await memory.forget(args.sessionId as string, options);
+        return {
+          content: [{ type: 'text', text: `Deleted ${deleted} memor${deleted === 1 ? 'y' : 'ies'}.` }],
+        };
+      }
+
+      case 'stats': {
+        const stats = await memory.stats(args.sessionId as string);
+        return {
+          content: [{ type: 'text', text: JSON.stringify(stats, null, 2) }],
+        };
+      }
+
+      default:
+        return {
+          content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+          isError: true,
+        };
+    }
+  } catch (err: any) {
+    return {
+      content: [{ type: 'text', text: `Error: ${err.message}` }],
+      isError: true,
+    };
+  }
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write('Engram MCP server running\n');
+}
+
+main().catch((err) => {
+  process.stderr.write(`Fatal: ${err.message}\n`);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "moduleResolution": "node",
+    "outDir": "./dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": [
+    "src/**/*",
+    "engram.ts"
+  ]
+}