@cartisien/engram-mcp 0.2.0 → 0.3.0

package/dist/tools/search.d.ts

@@ -0,0 +1,72 @@
+import type { Engram } from '@cartisien/engram';
+export interface SearchInput {
+    query: string;
+    session_id?: string;
+    search_type?: 'hybrid' | 'semantic' | 'fts' | 'graph';
+    limit?: number;
+    offset?: number;
+    semantic_weight?: number;
+    filters?: {
+        role?: string[];
+        tier?: string[];
+        date_after?: string;
+        date_before?: string;
+    };
+}
+export declare function toolSearch(engram: Engram, input: SearchInput): Promise<import("../response.js").McpResponse<unknown>>;
+export declare const SEARCH_SCHEMA: {
+    readonly name: "search";
+    readonly description: "Raw hybrid search with pagination and filtering. Use for precise control over results.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly query: {
+                readonly type: "string";
+            };
+            readonly session_id: {
+                readonly type: "string";
+            };
+            readonly search_type: {
+                readonly type: "string";
+                readonly enum: readonly ["hybrid", "semantic", "fts", "graph"];
+                readonly default: "hybrid";
+            };
+            readonly limit: {
+                readonly type: "number";
+                readonly default: 10;
+            };
+            readonly offset: {
+                readonly type: "number";
+                readonly default: 0;
+            };
+            readonly semantic_weight: {
+                readonly type: "number";
+                readonly description: "0-1, weight for semantic vs BM25 (not yet configurable in v0.7)";
+            };
+            readonly filters: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly role: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly tier: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly date_after: {
+                        readonly type: "string";
+                    };
+                    readonly date_before: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+        readonly required: readonly ["query"];
+    };
+};

package/dist/tools/search.js

@@ -0,0 +1,96 @@
+import { extractEntities } from '../analysis/entities.js';
+import { themeNames } from '../analysis/themes.js';
+import { ok, fail } from '../response.js';
+import { defaultSession } from '../client.js';
+export async function toolSearch(engram, input) {
+    const start = Date.now();
+    const sessionId = input.session_id ?? defaultSession();
+    if (!input.query?.trim()) {
+        return fail('INVALID_INPUT', 'query is required', sessionId, start);
+    }
+    const limit = Math.min(input.limit ?? 10, 100);
+    const offset = input.offset ?? 0;
+    const tiers = input.filters?.tier
+        ?? ['working', 'long_term'];
+    // Determine threshold by search type
+    const threshold = input.search_type === 'fts' ? 0 : 0.5;
+    try {
+        // Fetch enough to support offset
+        const all = await engram.recall(sessionId, input.query, {
+            limit: limit + offset + 20,
+            threshold,
+            tiers,
+            after: input.filters?.date_after ? new Date(input.filters.date_after) : undefined,
+            before: input.filters?.date_before ? new Date(input.filters.date_before) : undefined,
+        });
+        // Post-filter by role
+        let filtered = all;
+        if (input.filters?.role?.length) {
+            const roles = new Set(input.filters.role);
+            filtered = all.filter(m => roles.has(m.role));
+        }
+        const total = filtered.length;
+        const page = filtered.slice(offset, offset + limit);
+        // Analyze query
+        const queryEntities = extractEntities(input.query).map(e => e.name);
+        const queryThemes = themeNames(input.query, 2);
+        const results = page.map(m => ({
+            memory_id: m.id,
+            content: m.content,
+            role: m.role,
+            tier: m.tier,
+            timestamp: m.timestamp.toISOString(),
+            scores: {
+                semantic: m.similarity ?? 0,
+                final: m.similarity ?? 0,
+            },
+        }));
+        const suggestions = [];
+        if (queryThemes.length > 0) {
+            suggestions.push(`Try 'recall' with theme_filter: [\"${queryThemes[0]}\"] for contextual results`);
+        }
+        return ok({
+            results,
+            pagination: {
+                total,
+                returned: results.length,
+                offset,
+                has_more: offset + limit < total,
+            },
+            query_analysis: {
+                entities_detected: queryEntities.slice(0, 5),
+                themes_implied: queryThemes,
+                search_type_used: input.search_type ?? 'hybrid',
+            },
+        }, sessionId, start, suggestions);
+    }
+    catch (err) {
+        return fail('SEARCH_FAILED', String(err), sessionId, start);
+    }
+}
+export const SEARCH_SCHEMA = {
+    name: 'search',
+    description: 'Raw hybrid search with pagination and filtering. Use for precise control over results.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: { type: 'string' },
+            session_id: { type: 'string' },
+            search_type: { type: 'string', enum: ['hybrid', 'semantic', 'fts', 'graph'], default: 'hybrid' },
+            limit: { type: 'number', default: 10 },
+            offset: { type: 'number', default: 0 },
+            semantic_weight: { type: 'number', description: '0-1, weight for semantic vs BM25 (not yet configurable in v0.7)' },
+            filters: {
+                type: 'object',
+                properties: {
+                    role: { type: 'array', items: { type: 'string' } },
+                    tier: { type: 'array', items: { type: 'string' } },
+                    date_after: { type: 'string' },
+                    date_before: { type: 'string' },
+                },
+            },
+        },
+        required: ['query'],
+    },
+};
+//# sourceMappingURL=search.js.map

package/dist/tools/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/tools/search.ts"],"names":[],"mappings":"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"}

package/dist/tools/stats.d.ts

@@ -0,0 +1,23 @@
+import type { Engram } from '@cartisien/engram';
+export interface StatsInput {
+    session_id?: string;
+    include_graph?: boolean;
+}
+export declare function toolStats(engram: Engram, input: StatsInput): Promise<import("../response.js").McpResponse<unknown>>;
+export declare const STATS_SCHEMA: {
+    readonly name: "stats";
+    readonly description: "Get memory statistics for a session: counts by role/tier, embeddings coverage, importance scores, and graph metrics.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly session_id: {
+                readonly type: "string";
+            };
+            readonly include_graph: {
+                readonly type: "boolean";
+                readonly default: true;
+                readonly description: "Include entity graph node/edge counts";
+            };
+        };
+    };
+};

package/dist/tools/stats.js

@@ -0,0 +1,47 @@
+import { ok, fail } from '../response.js';
+import { defaultSession } from '../client.js';
+export async function toolStats(engram, input) {
+    const start = Date.now();
+    const sessionId = input.session_id ?? defaultSession();
+    try {
+        const stats = await engram.stats(sessionId);
+        const suggestions = [];
+        if (stats.byTier?.working > 80) {
+            suggestions.push(`${stats.byTier.working} working memories — consider running 'consolidate'`);
+        }
+        if (stats.total === 0) {
+            suggestions.push(`No memories in session '${sessionId}' — use 'remember' to start storing memories`);
+        }
+        return ok({
+            session_id: sessionId,
+            total_memories: stats.total,
+            by_role: stats.byRole,
+            by_tier: stats.byTier,
+            oldest: stats.oldest?.toISOString() ?? null,
+            newest: stats.newest?.toISOString() ?? null,
+            with_embeddings: stats.withEmbeddings,
+            avg_importance: stats.avgImportance != null
+                ? Math.round(stats.avgImportance * 100) / 100
+                : null,
+            graph: input.include_graph !== false ? {
+                nodes: stats.graphNodes ?? 0,
+                edges: stats.graphEdges ?? 0,
+            } : undefined,
+        }, sessionId, start, suggestions);
+    }
+    catch (err) {
+        return fail('STATS_FAILED', String(err), sessionId, start);
+    }
+}
+export const STATS_SCHEMA = {
+    name: 'stats',
+    description: 'Get memory statistics for a session: counts by role/tier, embeddings coverage, importance scores, and graph metrics.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            session_id: { type: 'string' },
+            include_graph: { type: 'boolean', default: true, description: 'Include entity graph node/edge counts' },
+        },
+    },
+};
+//# sourceMappingURL=stats.js.map

package/dist/tools/stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.js","sourceRoot":"","sources":["../../src/tools/stats.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAO9C,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,MAAc,EAAE,KAAiB;IAC/D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzB,MAAM,SAAS,GAAG,KAAK,CAAC,UAAU,IAAI,cAAc,EAAE,CAAC;IAEvD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAE5C,MAAM,WAAW,GAAa,EAAE,CAAC;QACjC,IAAI,KAAK,CAAC,MAAM,EAAE,OAAO,GAAG,EAAE,EAAE,CAAC;YAC/B,WAAW,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,OAAO,oDAAoD,CAAC,CAAC;QAChG,CAAC;QACD,IAAI,KAAK,CAAC,KAAK,KAAK,CAAC,EAAE,CAAC;YACtB,WAAW,CAAC,IAAI,CAAC,2BAA2B,SAAS,8CAA8C,CAAC,CAAC;QACvG,CAAC;QAED,OAAO,EAAE,CAAC;YACR,UAAU,EAAE,SAAS;YACrB,cAAc,EAAE,KAAK,CAAC,KAAK;YAC3B,OAAO,EAAE,KAAK,CAAC,MAAM;YACrB,OAAO,EAAE,KAAK,CAAC,MAAM;YACrB,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,IAAI;YAC3C,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,IAAI;YAC3C,eAAe,EAAE,KAAK,CAAC,cAAc;YACrC,cAAc,EAAE,KAAK,CAAC,aAAa,IAAI,IAAI;gBACzC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,aAAa,GAAG,GAAG,CAAC,GAAG,GAAG;gBAC7C,CAAC,CAAC,IAAI;YACR,KAAK,EAAE,KAAK,CAAC,aAAa,KAAK,KAAK,CAAC,CAAC,CAAC;gBACrC,KAAK,EAAE,KAAK,CAAC,UAAU,IAAI,CAAC;gBAC5B,KAAK,EAAE,KAAK,CAAC,UAAU,IAAI,CAAC;aAC7B,CAAC,CAAC,CAAC,SAAS;SACd,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;IAEpC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IAC7D,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,IAAI,EAAE,OAAO;IACb,WAAW,EAAE,sHAAsH;IACnI,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC9B,aAAa,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,uCAAuC,EAAE;SACxG;KACF;CACO,CAAC"}

package/package.json

@@ -1,24 +1,39 @@
 {
   "name": "@cartisien/engram-mcp",
-  "version": "0.2.0",
-  "description": "MCP server for @cartisien/engram — persistent semantic memory for AI agents",
+  "version": "0.3.0",
+  "description": "MCP server for Engram — structured agent memory as relational intelligence",
   "type": "module",
-  "main": "dist/src/index.js",
+  "main": "dist/server.js",
   "bin": {
-    "engram-mcp": "dist/src/index.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "start": "node dist/src/index.js"
+    "engram-mcp": "dist/server.js"
   },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "ai",
+    "memory",
+    "engram",
+    "agents"
+  ],
+  "author": "Cartisien Interactive",
+  "license": "MIT",
   "dependencies": {
-    "@cartisien/engram": "^0.6.1",
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "sqlite3": "^5.1.7"
+    "@cartisien/engram": "2.0.0"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.0.0",
-    "vitest": "^2.0.0"
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/server.js"
   }
-}
+}

package/README.md

@@ -1,114 +0,0 @@
-# @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

@@ -1,99 +0,0 @@
-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;