@cartisien/engram-mcp 0.1.0 → 0.2.0

package/dist/src/index.js

@@ -37,46 +37,54 @@ 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 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';
-// Ensure DB directory exists
+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_js_1.Engram({
+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.1.0' }, { capabilities: { tools: {} } });
+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 are generated automatically for semantic recall.',
+            description: 'Store a memory entry for a session. Embeddings and graph extraction happen automatically.',
             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' },
+                    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 using semantic search. Falls back to keyword search if embeddings unavailable.',
+            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 — semantic similarity is used' },
-                    limit: { type: 'number', description: 'Max results to return (default 10)', default: 10 },
+                    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'],
             },
@@ -88,75 +96,206 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
                 type: 'object',
                 properties: {
                     sessionId: { type: 'string', description: 'Session identifier' },
-                    limit: { type: 'number', description: 'Max entries to return (default 20)', default: 20 },
+                    limit: { type: 'number', description: 'Max entries (default 20)', default: 20 },
                 },
                 required: ['sessionId'],
             },
         },
         {
             name: 'forget',
-            description: 'Delete memories for a session. Delete all, one by ID, or entries before a date.',
+            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 string — delete entries before this date (optional)' },
+                    before: { type: 'string', description: 'ISO date — delete entries before this date (optional)' },
                 },
                 required: ['sessionId'],
             },
         },
         {
             name: 'stats',
-            description: 'Get memory statistics for a session.',
+            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');
-                return {
-                    content: [{ type: 'text', text: JSON.stringify(entry, null, 2) }],
-                };
+                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 entries = await memory.recall(args.sessionId, args.query, args.limit || 10);
-                return {
-                    content: [{ type: 'text', text: JSON.stringify(entries, null, 2) }],
-                };
+                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) }],
-                };
+                return { content: [{ type: 'text', text: JSON.stringify(entries, null, 2) }] };
             }
             case 'forget': {
-                const options = {};
+                const opts = {};
                 if (args.id)
-                    options.id = args.id;
+                    opts.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'}.` }],
-                };
+                    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) }],
-                };
+                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 {
@@ -175,7 +314,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
 async function main() {
     const transport = new stdio_js_1.StdioServerTransport();
     await server.connect(transport);
-    process.stderr.write('Engram MCP server running\n');
+    process.stderr.write('Engram MCP server v0.2.0 running\n');
 }
 main().catch((err) => {
     process.stderr.write(`Fatal: ${err.message}\n`);

package/package.json

@@ -1,22 +1,24 @@
 {
   "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",
+  "version": "0.2.0",
+  "description": "MCP server for @cartisien/engram — persistent semantic memory for AI agents",
+  "type": "module",
+  "main": "dist/src/index.js",
   "bin": {
     "engram-mcp": "dist/src/index.js"
   },
   "scripts": {
     "build": "tsc",
-    "start": "node dist/index.js"
+    "start": "node dist/src/index.js"
   },
   "dependencies": {
+    "@cartisien/engram": "^0.6.1",
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "sqlite": "^5.1.1",
     "sqlite3": "^5.1.7"
   },
   "devDependencies": {
+    "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
-    "@types/node": "^20.0.0"
+    "vitest": "^2.0.0"
   }
-}
+}

package/src/index.ts

@@ -5,15 +5,16 @@ import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
-import { Engram } from '../engram.js';
+import { Engram } from '@cartisien/engram';
 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';
+const GRAPH_MODEL = process.env.ENGRAM_GRAPH_MODEL || 'qwen2.5:32b';
+const CONSOLIDATE_MODEL = process.env.ENGRAM_CONSOLIDATE_MODEL || 'qwen2.5:32b';
 
-// Ensure DB directory exists
 const dbDir = path.dirname(DB_PATH);
 if (!fs.existsSync(dbDir)) fs.mkdirSync(dbDir, { recursive: true });
 
@@ -21,37 +22,44 @@ const memory = new Engram({
   dbPath: DB_PATH,
   embeddingUrl: EMBEDDING_URL,
   semanticSearch: true,
+  graphMemory: process.env.ENGRAM_GRAPH === '1',
+  graphModel: GRAPH_MODEL,
+  consolidateModel: CONSOLIDATE_MODEL,
 });
 
 const server = new Server(
-  { name: 'engram', version: '0.1.0' },
+  { name: 'engram', version: '0.2.0' },
   { capabilities: { tools: {} } }
 );
 
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: [
+    // ── Session memory ──────────────────────────────────────────────────
     {
       name: 'remember',
-      description: 'Store a memory entry for a session. Embeddings are generated automatically for semantic recall.',
+      description: 'Store a memory entry for a session. Embeddings and graph extraction happen automatically.',
       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' },
+          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 using semantic search. Falls back to keyword search if embeddings unavailable.',
+      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 — semantic similarity is used' },
-          limit: { type: 'number', description: 'Max results to return (default 10)', default: 10 },
+          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'],
       },
@@ -62,36 +70,128 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       inputSchema: {
         type: 'object',
         properties: {
-          sessionId: { type: 'string', description: 'Session identifier' },
-          limit: { type: 'number', description: 'Max entries to return (default 20)', default: 20 },
+          sessionId:  { type: 'string', description: 'Session identifier' },
+          limit:      { type: 'number', description: 'Max entries (default 20)', default: 20 },
         },
         required: ['sessionId'],
       },
     },
     {
       name: 'forget',
-      description: 'Delete memories for a session. Delete all, one by ID, or entries before a date.',
+      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 string — delete entries before this date (optional)' },
+          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: 'Get memory statistics for a session.',
+      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' },
+          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'],
+      },
+    },
   ],
 }));
 
@@ -100,26 +200,33 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
   try {
     switch (name) {
+
+      // ── Session ──────────────────────────────────────────────────────
+
       case 'remember': {
         const entry = await memory.remember(
           args.sessionId as string,
           args.content as string,
-          (args.role as 'user' | 'assistant' | 'system') || 'user'
+          (args.role as 'user' | 'assistant' | 'system') || 'user',
+          args.metadata as Record<string, unknown> | undefined
         );
-        return {
-          content: [{ type: 'text', text: JSON.stringify(entry, null, 2) }],
-        };
+        return { content: [{ type: 'text', text: JSON.stringify(entry, null, 2) }] };
       }
 
       case 'recall': {
+        const tiers = args.tiers
+          ? (args.tiers as string).split(',').map(t => t.trim()) as any
+          : undefined;
         const entries = await memory.recall(
           args.sessionId as string,
           args.query as string,
-          (args.limit as number) || 10
+          (args.limit as number) || 10,
+          {
+            tiers,
+            userId: args.userId as string | undefined,
+          }
         );
-        return {
-          content: [{ type: 'text', text: JSON.stringify(entries, null, 2) }],
-        };
+        return { content: [{ type: 'text', text: JSON.stringify(entries, null, 2) }] };
       }
 
       case 'history': {
@@ -127,26 +234,80 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           args.sessionId as string,
           (args.limit as number) || 20
         );
-        return {
-          content: [{ type: 'text', text: JSON.stringify(entries, null, 2) }],
-        };
+        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'}.` }],
-        };
+        const opts: Parameters<typeof memory.forget>[1] = {};
+        if (args.id) opts.id = args.id as string;
+        if (args.before) opts.before = new Date(args.before as string);
+        const deleted = await memory.forget(args.sessionId as string, opts);
+        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) }],
-        };
+        return { content: [{ type: 'text', text: JSON.stringify(stats, null, 2) }] };
+      }
+
+      case 'consolidate': {
+        const result = await memory.consolidate(args.sessionId as string, {
+          batch:  args.batch  as number | undefined,
+          keep:   args.keep   as number | undefined,
+          dryRun: args.dryRun as boolean | undefined,
+        });
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+      }
+
+      case 'graph': {
+        const result = await memory.graph(
+          args.sessionId as string,
+          args.entity as string
+        );
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+      }
+
+      // ── User-scoped ───────────────────────────────────────────────────
+
+      case 'remember_user': {
+        const entry = await memory.rememberUser(
+          args.userId as string,
+          args.content as string,
+          (args.role as 'user' | 'assistant' | 'system') || 'user',
+          args.metadata as Record<string, unknown> | undefined
+        );
+        return { content: [{ type: 'text', text: JSON.stringify(entry, null, 2) }] };
+      }
+
+      case 'recall_user': {
+        const entries = await memory.recallUser(
+          args.userId as string,
+          args.query as string | undefined,
+          (args.limit as number) || 10
+        );
+        return { content: [{ type: 'text', text: JSON.stringify(entries, null, 2) }] };
+      }
+
+      case 'forget_user': {
+        const opts: Parameters<typeof memory.forgetUser>[1] = {};
+        if (args.id) opts.id = args.id as string;
+        if (args.before) opts.before = new Date(args.before as string);
+        const deleted = await memory.forgetUser(args.userId as string, opts);
+        return { content: [{ type: 'text', text: `Deleted ${deleted} user memor${deleted === 1 ? 'y' : 'ies'}.` }] };
+      }
+
+      case 'consolidate_user': {
+        const result = await memory.consolidateUser(args.userId as string, {
+          batch:  args.batch  as number | undefined,
+          keep:   args.keep   as number | undefined,
+          dryRun: args.dryRun as boolean | undefined,
+        });
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+      }
+
+      case 'user_stats': {
+        const stats = await memory.userStats(args.userId as string);
+        return { content: [{ type: 'text', text: JSON.stringify(stats, null, 2) }] };
       }
 
       default:
@@ -166,7 +327,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  process.stderr.write('Engram MCP server running\n');
+  process.stderr.write('Engram MCP server v0.2.0 running\n');
 }
 
 main().catch((err) => {

package/tests/mcp.test.ts

@@ -0,0 +1,274 @@
+/**
+ * MCP server tool coverage tests.
+ * We test the tool definitions (schema) and the handler dispatch logic
+ * by exercising the Engram SDK directly — the same code paths the MCP
+ * server uses. This avoids needing a running MCP transport in CI.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { Engram } from '@cartisien/engram';
+
+// Mirror the handler logic so we can test every case without transport
+async function dispatch(memory: Engram, name: string, args: Record<string, unknown>) {
+  switch (name) {
+    case 'remember':
+      return memory.remember(
+        args.sessionId as string,
+        args.content as string,
+        (args.role as any) || 'user',
+        args.metadata as any
+      );
+    case 'recall':
+      return memory.recall(
+        args.sessionId as string,
+        args.query as string,
+        (args.limit as number) || 10,
+        { tiers: args.tiers ? (args.tiers as string).split(',') as any : undefined,
+          userId: args.userId as string | undefined }
+      );
+    case 'history':
+      return memory.history(args.sessionId as string, (args.limit as number) || 20);
+    case 'forget': {
+      const opts: any = {};
+      if (args.id) opts.id = args.id;
+      if (args.before) opts.before = new Date(args.before as string);
+      return memory.forget(args.sessionId as string, opts);
+    }
+    case 'stats':
+      return memory.stats(args.sessionId as string);
+    case 'consolidate':
+      return memory.consolidate(args.sessionId as string, {
+        batch: args.batch as any, keep: args.keep as any, dryRun: args.dryRun as any
+      });
+    case 'graph':
+      return memory.graph(args.sessionId as string, args.entity as string);
+    case 'remember_user':
+      return memory.rememberUser(args.userId as string, args.content as string, (args.role as any) || 'user', args.metadata as any);
+    case 'recall_user':
+      return memory.recallUser(args.userId as string, args.query as string | undefined, (args.limit as number) || 10);
+    case 'forget_user': {
+      const opts: any = {};
+      if (args.id) opts.id = args.id;
+      if (args.before) opts.before = new Date(args.before as string);
+      return memory.forgetUser(args.userId as string, opts);
+    }
+    case 'consolidate_user':
+      return memory.consolidateUser(args.userId as string, {
+        batch: args.batch as any, keep: args.keep as any, dryRun: args.dryRun as any
+      });
+    case 'user_stats':
+      return memory.userStats(args.userId as string);
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+describe('MCP tool handlers — all 12 tools', () => {
+  let memory: Engram;
+
+  beforeEach(() => {
+    memory = new Engram({ dbPath: ':memory:', semanticSearch: false });
+  });
+  afterEach(async () => { await memory.close(); });
+
+  // ── remember ─────────────────────────────────────────────────────────────
+
+  it('remember: stores entry and returns id', async () => {
+    const entry: any = await dispatch(memory, 'remember', {
+      sessionId: 's1', content: 'Test fact', role: 'user'
+    });
+    expect(entry.id).toBeTruthy();
+    expect(entry.content).toBe('Test fact');
+    expect(entry.tier).toBe('working');
+  });
+
+  it('remember: stores with metadata', async () => {
+    const entry: any = await dispatch(memory, 'remember', {
+      sessionId: 's1', content: 'Fact with meta', metadata: { source: 'test' }
+    });
+    expect(entry.id).toBeTruthy();
+  });
+
+  // ── recall ────────────────────────────────────────────────────────────────
+
+  it('recall: returns stored memories', async () => {
+    await dispatch(memory, 'remember', { sessionId: 's1', content: 'GovScout uses React' });
+    const results: any = await dispatch(memory, 'recall', { sessionId: 's1', query: 'GovScout' });
+    expect(results.length).toBeGreaterThanOrEqual(1);
+    expect(results[0].content).toContain('GovScout');
+  });
+
+  it('recall: returns empty for unknown session', async () => {
+    const results: any = await dispatch(memory, 'recall', { sessionId: 'nobody', query: 'anything' });
+    expect(results).toEqual([]);
+  });
+
+  it('recall: blends user memories when userId provided', async () => {
+    await dispatch(memory, 'remember', { sessionId: 's1', content: 'Session fact' });
+    await dispatch(memory, 'remember_user', { userId: 'u1', content: 'User fact' });
+    const results: any = await dispatch(memory, 'recall', { sessionId: 's1', query: 'fact', userId: 'u1' });
+    const contents = results.map((r: any) => r.content);
+    expect(contents).toContain('Session fact');
+    expect(contents).toContain('User fact');
+  });
+
+  it('recall: tier filter works', async () => {
+    await dispatch(memory, 'remember', { sessionId: 's1', content: 'Working tier fact' });
+    const results: any = await dispatch(memory, 'recall', {
+      sessionId: 's1', query: 'fact', tiers: 'working'
+    });
+    expect(results.every((r: any) => r.tier === 'working')).toBe(true);
+  });
+
+  // ── history ───────────────────────────────────────────────────────────────
+
+  it('history: returns chronological entries', async () => {
+    await dispatch(memory, 'remember', { sessionId: 's1', content: 'First' });
+    await new Promise(r => setTimeout(r, 5));
+    await dispatch(memory, 'remember', { sessionId: 's1', content: 'Second' });
+    const entries: any = await dispatch(memory, 'history', { sessionId: 's1' });
+    expect(entries[0].content).toBe('First');
+    expect(entries[1].content).toBe('Second');
+  });
+
+  // ── forget ────────────────────────────────────────────────────────────────
+
+  it('forget: deletes all session memories', async () => {
+    await dispatch(memory, 'remember', { sessionId: 's1', content: 'To delete' });
+    const deleted: any = await dispatch(memory, 'forget', { sessionId: 's1' });
+    expect(deleted).toBe(1);
+    const results: any = await dispatch(memory, 'recall', { sessionId: 's1', query: 'delete' });
+    expect(results).toEqual([]);
+  });
+
+  it('forget: deletes by id', async () => {
+    const e: any = await dispatch(memory, 'remember', { sessionId: 's1', content: 'Target' });
+    await dispatch(memory, 'remember', { sessionId: 's1', content: 'Keep' });
+    const deleted: any = await dispatch(memory, 'forget', { sessionId: 's1', id: e.id });
+    expect(deleted).toBe(1);
+    const left: any = await dispatch(memory, 'history', { sessionId: 's1' });
+    expect(left.map((r: any) => r.content)).not.toContain('Target');
+  });
+
+  // ── stats ─────────────────────────────────────────────────────────────────
+
+  it('stats: returns total, byRole, byTier', async () => {
+    await dispatch(memory, 'remember', { sessionId: 's1', content: 'f1', role: 'user' });
+    await dispatch(memory, 'remember', { sessionId: 's1', content: 'f2', role: 'assistant' });
+    const stats: any = await dispatch(memory, 'stats', { sessionId: 's1' });
+    expect(stats.total).toBe(2);
+    expect(stats.byRole.user).toBe(1);
+    expect(stats.byRole.assistant).toBe(1);
+    expect(stats.byTier.working).toBe(2);
+  });
+
+  // ── consolidate ───────────────────────────────────────────────────────────
+
+  it('consolidate: dry run returns summarized count', async () => {
+    const result: any = await dispatch(memory, 'consolidate', {
+      sessionId: 's1', dryRun: true
+    });
+    expect(typeof result.summarized).toBe('number');
+    expect(result.created).toBe(0);
+  });
+
+  it('consolidate: returns zeros for empty session', async () => {
+    const result: any = await dispatch(memory, 'consolidate', { sessionId: 'empty' });
+    expect(result.summarized).toBe(0);
+    expect(result.created).toBe(0);
+    expect(result.archived).toBe(0);
+  });
+
+  // ── graph ─────────────────────────────────────────────────────────────────
+
+  it('graph: returns entity + relationships + memories', async () => {
+    const result: any = await dispatch(memory, 'graph', {
+      sessionId: 's1', entity: 'govscout'
+    });
+    expect(result.entity).toBe('govscout');
+    expect(Array.isArray(result.relationships)).toBe(true);
+    expect(Array.isArray(result.relatedMemories)).toBe(true);
+  });
+
+  // ── remember_user ─────────────────────────────────────────────────────────
+
+  it('remember_user: stores and returns user entry', async () => {
+    const entry: any = await dispatch(memory, 'remember_user', {
+      userId: 'u1', content: 'Prefers TypeScript'
+    });
+    expect(entry.userId).toBe('u1');
+    expect(entry.content).toBe('Prefers TypeScript');
+    expect(entry.tier).toBe('working');
+  });
+
+  // ── recall_user ───────────────────────────────────────────────────────────
+
+  it('recall_user: retrieves user memories', async () => {
+    await dispatch(memory, 'remember_user', { userId: 'u1', content: 'Loves dark mode' });
+    const results: any = await dispatch(memory, 'recall_user', { userId: 'u1' });
+    expect(results.length).toBe(1);
+    expect(results[0].content).toBe('Loves dark mode');
+  });
+
+  it('recall_user: isolated between users', async () => {
+    await dispatch(memory, 'remember_user', { userId: 'u1', content: 'U1 fact' });
+    await dispatch(memory, 'remember_user', { userId: 'u2', content: 'U2 fact' });
+    const u1: any = await dispatch(memory, 'recall_user', { userId: 'u1' });
+    expect(u1.map((r: any) => r.content)).not.toContain('U2 fact');
+  });
+
+  it('recall_user: empty for unknown user', async () => {
+    const results: any = await dispatch(memory, 'recall_user', { userId: 'nobody' });
+    expect(results).toEqual([]);
+  });
+
+  // ── forget_user ───────────────────────────────────────────────────────────
+
+  it('forget_user: deletes all user memories', async () => {
+    await dispatch(memory, 'remember_user', { userId: 'u1', content: 'To delete' });
+    const deleted: any = await dispatch(memory, 'forget_user', { userId: 'u1' });
+    expect(deleted).toBe(1);
+    const left: any = await dispatch(memory, 'recall_user', { userId: 'u1' });
+    expect(left).toEqual([]);
+  });
+
+  it('forget_user: deletes by id', async () => {
+    const e: any = await dispatch(memory, 'remember_user', { userId: 'u1', content: 'Target' });
+    await dispatch(memory, 'remember_user', { userId: 'u1', content: 'Keep' });
+    await dispatch(memory, 'forget_user', { userId: 'u1', id: e.id });
+    const left: any = await dispatch(memory, 'recall_user', { userId: 'u1' });
+    expect(left.map((r: any) => r.content)).not.toContain('Target');
+    expect(left.map((r: any) => r.content)).toContain('Keep');
+  });
+
+  // ── consolidate_user ──────────────────────────────────────────────────────
+
+  it('consolidate_user: dry run on empty user', async () => {
+    const result: any = await dispatch(memory, 'consolidate_user', {
+      userId: 'nobody', dryRun: true
+    });
+    expect(result.summarized).toBe(0);
+  });
+
+  // ── user_stats ────────────────────────────────────────────────────────────
+
+  it('user_stats: returns counts', async () => {
+    await dispatch(memory, 'remember_user', { userId: 'u1', content: 'f1', role: 'user' });
+    await dispatch(memory, 'remember_user', { userId: 'u1', content: 'f2', role: 'assistant' });
+    const stats: any = await dispatch(memory, 'user_stats', { userId: 'u1' });
+    expect(stats.total).toBe(2);
+    expect(stats.byTier.working).toBe(2);
+    expect(stats.byRole.user).toBe(1);
+  });
+
+  it('user_stats: zeros for unknown user', async () => {
+    const stats: any = await dispatch(memory, 'user_stats', { userId: 'nobody' });
+    expect(stats.total).toBe(0);
+  });
+
+  // ── unknown tool ──────────────────────────────────────────────────────────
+
+  it('unknown tool: throws', async () => {
+    await expect(dispatch(memory, 'nonexistent', {})).rejects.toThrow('Unknown tool');
+  });
+});

package/tsconfig.test.json

@@ -0,0 +1,5 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": { "rootDir": "." },
+  "include": ["src/**/*", "tests/**/*"]
+}