@cartisien/engram-mcp 0.2.0 → 0.3.1

package/dist/engram.js

@@ -1,283 +0,0 @@
-"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

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

package/dist/src/index.js

@@ -1,322 +0,0 @@
-#!/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_1 = require("@cartisien/engram");
-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';
-const GRAPH_MODEL = process.env.ENGRAM_GRAPH_MODEL || 'qwen2.5:32b';
-const CONSOLIDATE_MODEL = process.env.ENGRAM_CONSOLIDATE_MODEL || 'qwen2.5:32b';
-const dbDir = path.dirname(DB_PATH);
-if (!fs.existsSync(dbDir))
-    fs.mkdirSync(dbDir, { recursive: true });
-const memory = new engram_1.Engram({
-    dbPath: DB_PATH,
-    embeddingUrl: EMBEDDING_URL,
-    semanticSearch: true,
-    graphMemory: process.env.ENGRAM_GRAPH === '1',
-    graphModel: GRAPH_MODEL,
-    consolidateModel: CONSOLIDATE_MODEL,
-});
-const server = new index_js_1.Server({ name: 'engram', version: '0.2.0' }, { capabilities: { tools: {} } });
-server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
-    tools: [
-        // ── Session memory ──────────────────────────────────────────────────
-        {
-            name: 'remember',
-            description: 'Store a memory entry for a session. Embeddings and graph extraction happen automatically.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    sessionId: { type: 'string', description: 'Session identifier' },
-                    content: { type: 'string', description: 'Memory content to store' },
-                    role: { type: 'string', enum: ['user', 'assistant', 'system'], default: 'user' },
-                    metadata: { type: 'object', description: 'Optional key-value metadata' },
-                },
-                required: ['sessionId', 'content'],
-            },
-        },
-        {
-            name: 'recall',
-            description: 'Retrieve relevant memories via semantic search (falls back to keyword). Searches working + long_term tiers. Pass userId to blend in cross-session user facts.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    sessionId: { type: 'string', description: 'Session identifier' },
-                    query: { type: 'string', description: 'Search query' },
-                    limit: { type: 'number', description: 'Max results (default 10)', default: 10 },
-                    userId: { type: 'string', description: 'Optional: also blend in this user\'s cross-session memories' },
-                    tiers: { type: 'string', description: 'Comma-separated tiers to search: working,long_term,archived (default: working,long_term)' },
-                },
-                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 (default 20)', default: 20 },
-                },
-                required: ['sessionId'],
-            },
-        },
-        {
-            name: 'forget',
-            description: 'Delete session memories. 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 — delete entries before this date (optional)' },
-                },
-                required: ['sessionId'],
-            },
-        },
-        {
-            name: 'stats',
-            description: 'Memory statistics for a session — total, by role, by tier (working/long_term/archived), graph counts.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    sessionId: { type: 'string', description: 'Session identifier' },
-                },
-                required: ['sessionId'],
-            },
-        },
-        {
-            name: 'consolidate',
-            description: 'Consolidate old working memories into dense long-term summaries via LLM. Archives originals.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    sessionId: { type: 'string', description: 'Session identifier' },
-                    batch: { type: 'number', description: 'Number of memories to consolidate (default 50)' },
-                    keep: { type: 'number', description: 'Most recent N to leave untouched (default 20)' },
-                    dryRun: { type: 'boolean', description: 'Preview summaries without writing (default false)' },
-                },
-                required: ['sessionId'],
-            },
-        },
-        {
-            name: 'graph',
-            description: 'Query the knowledge graph for an entity — returns relationships and source memories. Requires ENGRAM_GRAPH=1.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    sessionId: { type: 'string', description: 'Session identifier' },
-                    entity: { type: 'string', description: 'Entity name to look up (case-insensitive)' },
-                },
-                required: ['sessionId', 'entity'],
-            },
-        },
-        // ── User-scoped (cross-session) memory ──────────────────────────────
-        {
-            name: 'remember_user',
-            description: 'Store a user-scoped memory that persists across all sessions. Use for preferences, identity, long-term facts.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    userId: { type: 'string', description: 'User identifier' },
-                    content: { type: 'string', description: 'Memory content to store' },
-                    role: { type: 'string', enum: ['user', 'assistant', 'system'], default: 'user' },
-                    metadata: { type: 'object', description: 'Optional key-value metadata' },
-                },
-                required: ['userId', 'content'],
-            },
-        },
-        {
-            name: 'recall_user',
-            description: 'Recall user-scoped memories — works from any session context.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    userId: { type: 'string', description: 'User identifier' },
-                    query: { type: 'string', description: 'Search query (optional — returns all if omitted)' },
-                    limit: { type: 'number', description: 'Max results (default 10)', default: 10 },
-                },
-                required: ['userId'],
-            },
-        },
-        {
-            name: 'forget_user',
-            description: 'Delete user-scoped memories.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    userId: { type: 'string', description: 'User identifier' },
-                    id: { type: 'string', description: 'Specific memory ID (optional)' },
-                    before: { type: 'string', description: 'ISO date — delete entries before this date (optional)' },
-                },
-                required: ['userId'],
-            },
-        },
-        {
-            name: 'consolidate_user',
-            description: 'Consolidate user-scoped working memories into long-term summaries.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    userId: { type: 'string', description: 'User identifier' },
-                    batch: { type: 'number', description: 'Number of memories to consolidate (default 50)' },
-                    keep: { type: 'number', description: 'Most recent N to leave untouched (default 20)' },
-                    dryRun: { type: 'boolean', description: 'Preview without writing (default false)' },
-                },
-                required: ['userId'],
-            },
-        },
-        {
-            name: 'user_stats',
-            description: 'Memory statistics for a user — total, by role, by tier.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    userId: { type: 'string', description: 'User identifier' },
-                },
-                required: ['userId'],
-            },
-        },
-    ],
-}));
-server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
-    const { name, arguments: args = {} } = request.params;
-    try {
-        switch (name) {
-            // ── Session ──────────────────────────────────────────────────────
-            case 'remember': {
-                const entry = await memory.remember(args.sessionId, args.content, args.role || 'user', args.metadata);
-                return { content: [{ type: 'text', text: JSON.stringify(entry, null, 2) }] };
-            }
-            case 'recall': {
-                const tiers = args.tiers
-                    ? args.tiers.split(',').map(t => t.trim())
-                    : undefined;
-                const entries = await memory.recall(args.sessionId, args.query, args.limit || 10, {
-                    tiers,
-                    userId: args.userId,
-                });
-                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 opts = {};
-                if (args.id)
-                    opts.id = args.id;
-                if (args.before)
-                    opts.before = new Date(args.before);
-                const deleted = await memory.forget(args.sessionId, opts);
-                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) }] };
-            }
-            case 'consolidate': {
-                const result = await memory.consolidate(args.sessionId, {
-                    batch: args.batch,
-                    keep: args.keep,
-                    dryRun: args.dryRun,
-                });
-                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
-            }
-            case 'graph': {
-                const result = await memory.graph(args.sessionId, args.entity);
-                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
-            }
-            // ── User-scoped ───────────────────────────────────────────────────
-            case 'remember_user': {
-                const entry = await memory.rememberUser(args.userId, args.content, args.role || 'user', args.metadata);
-                return { content: [{ type: 'text', text: JSON.stringify(entry, null, 2) }] };
-            }
-            case 'recall_user': {
-                const entries = await memory.recallUser(args.userId, args.query, args.limit || 10);
-                return { content: [{ type: 'text', text: JSON.stringify(entries, null, 2) }] };
-            }
-            case 'forget_user': {
-                const opts = {};
-                if (args.id)
-                    opts.id = args.id;
-                if (args.before)
-                    opts.before = new Date(args.before);
-                const deleted = await memory.forgetUser(args.userId, opts);
-                return { content: [{ type: 'text', text: `Deleted ${deleted} user memor${deleted === 1 ? 'y' : 'ies'}.` }] };
-            }
-            case 'consolidate_user': {
-                const result = await memory.consolidateUser(args.userId, {
-                    batch: args.batch,
-                    keep: args.keep,
-                    dryRun: args.dryRun,
-                });
-                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
-            }
-            case 'user_stats': {
-                const stats = await memory.userStats(args.userId);
-                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 v0.2.0 running\n');
-}
-main().catch((err) => {
-    process.stderr.write(`Fatal: ${err.message}\n`);
-    process.exit(1);
-});