@199-bio/engram 0.8.0 → 0.10.0

package/src/transport/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Transport layer for Engram MCP Server
+ * Supports both stdio (local) and HTTP (remote/Railway) transports
+ */
+
+export type TransportMode = "stdio" | "http";
+
+/**
+ * Detect transport mode from environment variables
+ * Default: stdio (preserves existing behavior)
+ */
+export function getTransportMode(): TransportMode {
+  const mode = process.env.ENGRAM_TRANSPORT?.toLowerCase();
+  if (mode === "http" || mode === "sse") return "http";
+  return "stdio";
+}
+
+/**
+ * Get HTTP port from environment
+ * Railway provides PORT, we also support ENGRAM_MCP_PORT
+ */
+export function getHttpPort(): number {
+  return parseInt(process.env.PORT || process.env.ENGRAM_MCP_PORT || "3000", 10);
+}

package/src/web/chat-handler.ts

@@ -1,6 +1,6 @@
 /**
  * Chat Handler for Engram Web Interface
- * Uses Claude Haiku 4.5 with tools for entity/memory management
+ * Uses Claude Opus 4.5 with tools for entity/memory management
  */
 
 import Anthropic from "@anthropic-ai/sdk";
@@ -9,22 +9,22 @@ import { KnowledgeGraph } from "../graph/knowledge-graph.js";
 import { HybridSearch } from "../retrieval/hybrid.js";
 import { getAnthropicApiKey } from "../settings.js";
 
-// Tool definitions for Claude
+// Tool definitions for Claude - optimized for LLM consumption
 const TOOLS: Anthropic.Tool[] = [
   {
     name: "list_entities",
-    description: "List all entities in the knowledge graph. Use this to see what people, organizations, and places are stored.",
+    description: "Returns array of {name, type, id}. Filters: type (person|organization|place), limit. Default limit=50.",
     input_schema: {
       type: "object" as const,
       properties: {
         type: {
           type: "string",
           enum: ["person", "organization", "place"],
-          description: "Filter by entity type (optional)",
+          description: "Filter: person, organization, or place",
         },
         limit: {
-          type: "number",
-          description: "Maximum number of entities to return (default: 50)",
+          type: "integer",
+          description: "Max results (default: 50)",
         },
       },
       required: [],
@@ -32,13 +32,13 @@ const TOOLS: Anthropic.Tool[] = [
   },
   {
     name: "get_entity",
-    description: "Get detailed information about an entity including its observations and relationships.",
+    description: "Returns {name, type, observations[], relationships_from[], relationships_to[]} or {error}.",
     input_schema: {
       type: "object" as const,
       properties: {
         name: {
           type: "string",
-          description: "The entity name to look up",
+          description: "Exact entity name (case-sensitive)",
         },
       },
       required: ["name"],
@@ -46,13 +46,13 @@ const TOOLS: Anthropic.Tool[] = [
   },
   {
     name: "delete_entity",
-    description: "Delete an entity and all its observations and relationships. Use this to remove incorrect or duplicate entities.",
+    description: "Permanently removes entity + all observations + all relationships. Returns {success, deleted} or {error}.",
     input_schema: {
       type: "object" as const,
       properties: {
         name: {
           type: "string",
-          description: "The entity name to delete",
+          description: "Exact entity name to delete",
         },
       },
       required: ["name"],
@@ -60,17 +60,17 @@ const TOOLS: Anthropic.Tool[] = [
   },
   {
     name: "merge_entities",
-    description: "Merge one entity into another. All observations and relationships from the source will be moved to the target, then the source is deleted. Use this to fix duplicates.",
+    description: "Moves all data from 'merge' into 'keep', then deletes 'merge'. Use for deduplication. Returns {success, kept, merged, observations_moved, relations_moved} or {error}.",
     input_schema: {
       type: "object" as const,
       properties: {
         keep: {
           type: "string",
-          description: "The entity name to keep (target)",
+          description: "Entity name to preserve (target)",
         },
         merge: {
           type: "string",
-          description: "The entity name to merge and delete (source)",
+          description: "Entity name to merge then delete (source)",
         },
       },
       required: ["keep", "merge"],
@@ -78,17 +78,17 @@ const TOOLS: Anthropic.Tool[] = [
   },
   {
     name: "rename_entity",
-    description: "Rename an entity to a new name.",
+    description: "Changes entity name. Returns {success, old_name, new_name} or {error}.",
     input_schema: {
       type: "object" as const,
       properties: {
         old_name: {
           type: "string",
-          description: "Current entity name",
+          description: "Current exact name",
         },
         new_name: {
           type: "string",
-          description: "New entity name",
+          description: "New name",
         },
       },
       required: ["old_name", "new_name"],
@@ -96,7 +96,7 @@ const TOOLS: Anthropic.Tool[] = [
   },
   {
     name: "delete_relationship",
-    description: "Delete a relationship between two entities.",
+    description: "Removes specific relationship. All 3 params must match exactly. Returns {success, deleted} or {error}.",
     input_schema: {
       type: "object" as const,
       properties: {
@@ -110,7 +110,7 @@ const TOOLS: Anthropic.Tool[] = [
         },
         type: {
           type: "string",
-          description: "Relationship type (e.g., 'works_at', 'knows')",
+          description: "Relationship type (e.g., works_at, knows, lives_in)",
         },
       },
       required: ["from", "to", "type"],
@@ -118,17 +118,17 @@ const TOOLS: Anthropic.Tool[] = [
   },
   {
     name: "search_memories",
-    description: "Search through stored memories.",
+    description: "Hybrid BM25+semantic search. Returns {results[{id, content, timestamp, score}], count}.",
     input_schema: {
       type: "object" as const,
       properties: {
         query: {
           type: "string",
-          description: "Search query",
+          description: "Search query (keywords or natural language)",
         },
         limit: {
-          type: "number",
-          description: "Maximum results (default: 10)",
+          type: "integer",
+          description: "Max results (default: 10)",
         },
       },
       required: ["query"],
@@ -136,13 +136,13 @@ const TOOLS: Anthropic.Tool[] = [
   },
   {
     name: "delete_memory",
-    description: "Delete a memory by its ID (soft-delete, can be recovered).",
+    description: "Soft-delete (recoverable). Returns {success, disabled_id} or {error}.",
     input_schema: {
       type: "object" as const,
       properties: {
         id: {
           type: "string",
-          description: "The memory ID to delete",
+          description: "Memory UUID",
         },
       },
       required: ["id"],
@@ -150,13 +150,13 @@ const TOOLS: Anthropic.Tool[] = [
   },
   {
     name: "edit_memory",
-    description: "Edit an existing memory's content or importance.",
+    description: "Updates content and/or importance. Returns {success, memory_id, updated_fields[]} or {error}.",
     input_schema: {
       type: "object" as const,
       properties: {
         id: {
           type: "string",
-          description: "The memory ID to edit",
+          description: "Memory UUID",
         },
         content: {
           type: "string",
@@ -164,7 +164,9 @@ const TOOLS: Anthropic.Tool[] = [
         },
         importance: {
           type: "number",
-          description: "New importance (0-1): 0.9=core identity, 0.8=major, 0.5=normal, 0.3=minor",
+          minimum: 0,
+          maximum: 1,
+          description: "0-1: 0.9=identity, 0.8=major, 0.5=normal, 0.3=minor",
         },
       },
       required: ["id"],
@@ -172,17 +174,19 @@ const TOOLS: Anthropic.Tool[] = [
   },
   {
     name: "create_memory",
-    description: "Create a new memory. Use for storing user information, preferences, or facts.",
+    description: "Stores new memory. Returns {success, memory_id, content}.",
     input_schema: {
       type: "object" as const,
       properties: {
         content: {
           type: "string",
-          description: "The information to store",
+          description: "Information to store",
         },
         importance: {
           type: "number",
-          description: "0-1 score: 0.9=core identity, 0.8=major, 0.5=normal (default), 0.3=minor",
+          minimum: 0,
+          maximum: 1,
+          description: "0-1: 0.9=identity, 0.8=major, 0.5=normal (default), 0.3=minor",
         },
       },
       required: ["content"],
@@ -190,13 +194,13 @@ const TOOLS: Anthropic.Tool[] = [
   },
   {
     name: "create_entity",
-    description: "Create a new entity (person, organization, or place).",
+    description: "Creates new entity. Returns {success, entity_id, name, type} or {error} if exists.",
     input_schema: {
       type: "object" as const,
       properties: {
         name: {
           type: "string",
-          description: "The entity name",
+          description: "Entity name",
         },
         type: {
           type: "string",
@@ -209,7 +213,7 @@ const TOOLS: Anthropic.Tool[] = [
   },
   {
     name: "create_relationship",
-    description: "Create a relationship between two entities.",
+    description: "Links two entities. Auto-creates entities as 'person' if missing. Returns {success, relationship}.",
     input_schema: {
       type: "object" as const,
       properties: {
@@ -223,7 +227,7 @@ const TOOLS: Anthropic.Tool[] = [
         },
         type: {
           type: "string",
-          description: "Relationship type (e.g., 'works_at', 'lives_in', 'knows', 'sibling_of')",
+          description: "Relationship type (e.g., works_at, lives_in, knows, sibling_of, parent_of)",
         },
       },
       required: ["from", "to", "type"],
@@ -231,7 +235,7 @@ const TOOLS: Anthropic.Tool[] = [
   },
   {
     name: "find_duplicates",
-    description: "Find potential duplicate entities that could be merged.",
+    description: "Detects similar entity names. Returns {groups[{keep, duplicates[]}], total_duplicates}.",
     input_schema: {
       type: "object" as const,
       properties: {},
@@ -240,7 +244,7 @@ const TOOLS: Anthropic.Tool[] = [
   },
   {
     name: "auto_tidy",
-    description: "Automatically merge all detected duplicate entities.",
+    description: "Auto-merges all detected duplicates. Returns {entities_merged, observations_moved, relations_moved}.",
     input_schema: {
       type: "object" as const,
       properties: {},
@@ -249,16 +253,34 @@ const TOOLS: Anthropic.Tool[] = [
   },
 ];
 
-const SYSTEM_PROMPT = `You are a helpful assistant for managing Engram, a personal memory system. You help users:
-- View and search their memories
-- Manage entities (people, organizations, places)
-- Fix incorrect relationships
-- Merge duplicate entities
-- Delete incorrect data
-
-Be concise and helpful. When making changes, confirm what you did. If asked to do something destructive, confirm first unless the user is explicit.
-
-When listing entities or memories, format them clearly. Use the tools available to you.`;
+const SYSTEM_PROMPT = `You are a helpful assistant for managing Engram, a personal memory system. You have extended thinking capabilities - use them to reason carefully about complex requests.
+
+## Your Capabilities
+- Search and retrieve memories using semantic + keyword hybrid search
+- Manage entities (people, organizations, places) - create, rename, merge, delete
+- Manage relationships between entities
+- Create, edit, and delete memories
+- Find and auto-merge duplicate entities
+
+## Critical Behaviors
+1. **Always search first**: When asked about anything that might be in memory, use search_memories FIRST before answering. Don't assume you know the answer.
+2. **Multi-step reasoning**: For complex requests, break them into steps. Search, analyze results, then act.
+3. **Confirm destructive actions**: Unless the user is explicit, ask before deleting or merging data.
+4. **Be precise**: Use exact entity names when making changes. Check spelling.
+5. **Context awareness**: Remember what the user discussed earlier in this conversation.
+
+## Response Style
+- Be concise but thorough
+- Format lists and results clearly using markdown
+- When you find relevant memories, quote the key parts
+- If you're uncertain, say so and explain your reasoning
+
+## Tool Usage
+- search_memories: Use liberally - hybrid search is fast and effective
+- list_entities: Good for getting an overview before specific operations
+- get_entity: Get full details including observations and relationships
+- find_duplicates: Run this when asked about data quality or cleanup
+- auto_tidy: Only use when user explicitly wants automatic cleanup`;
 
 interface ChatMessage {
   role: "user" | "assistant";
@@ -267,7 +289,7 @@ interface ChatMessage {
 
 // Stream event types for SSE
 export interface StreamEvent {
-  type: "text" | "tool_start" | "tool_end" | "error" | "done";
+  type: "text" | "thinking" | "tool_start" | "tool_end" | "error" | "done";
   content?: string;
   tool?: string;
   result?: unknown;
@@ -301,13 +323,23 @@ export class ChatHandler {
   refreshClient(): void {
     const apiKey = getAnthropicApiKey();
     if (apiKey) {
-      this.client = new Anthropic({ apiKey });
+      if (!this.client) {
+        console.error("[Engram] ChatHandler: API key configured");
+      }
+      this.client = new Anthropic({
+        apiKey,
+        defaultHeaders: {
+          "anthropic-beta": "interleaved-thinking-2025-05-14",
+        },
+      });
     } else {
       this.client = null;
     }
   }
 
   isConfigured(): boolean {
+    // Re-check API key in case it was added after startup
+    this.refreshClient();
     return this.client !== null;
   }
 
@@ -341,6 +373,7 @@ export class ChatHandler {
 
   // Queue-aware chat method
   async chat(userMessage: string): Promise<string> {
+    this.refreshClient();
     if (!this.client) {
       return "Chat is not configured. Set ANTHROPIC_API_KEY environment variable.";
     }
@@ -357,6 +390,7 @@ export class ChatHandler {
 
   // Streaming chat with callbacks for real-time updates
   async *chatStream(userMessage: string): AsyncGenerator<StreamEvent> {
+    this.refreshClient();
     if (!this.client) {
       yield { type: "error", content: "Chat is not configured. Set ANTHROPIC_API_KEY environment variable." };
       return;
@@ -377,18 +411,22 @@ export class ChatHandler {
       }
 
       let continueLoop = true;
-      let fullResponse = "";
 
       while (continueLoop) {
         const stream = this.client.messages.stream({
-          model: "claude-haiku-4-5-20241022",
-          max_tokens: 1024,
+          model: "claude-opus-4-5-20251101",
+          max_tokens: 16000,
           system: SYSTEM_PROMPT,
           tools: TOOLS,
           messages: this.conversationHistory,
+          thinking: {
+            type: "enabled",
+            budget_tokens: 8000,
+          },
         });
 
         let currentToolUse: { id: string; name: string; input: string } | null = null;
+        let isThinking = false;
 
         for await (const event of stream) {
           if (event.type === "content_block_start") {
@@ -399,28 +437,23 @@ export class ChatHandler {
                 input: "",
               };
               yield { type: "tool_start", tool: event.content_block.name };
+            } else if (event.content_block.type === "thinking") {
+              isThinking = true;
+              yield { type: "thinking", content: "" };
             }
           } else if (event.type === "content_block_delta") {
             if (event.delta.type === "text_delta") {
-              fullResponse += event.delta.text;
               yield { type: "text", content: event.delta.text };
+            } else if (event.delta.type === "thinking_delta") {
+              // Stream thinking content for transparency
+              yield { type: "thinking", content: event.delta.thinking };
             } else if (event.delta.type === "input_json_delta" && currentToolUse) {
               currentToolUse.input += event.delta.partial_json;
             }
           } else if (event.type === "content_block_stop") {
-            if (currentToolUse) {
-              // Execute the tool
-              let toolInput: Record<string, unknown> = {};
-              try {
-                toolInput = JSON.parse(currentToolUse.input || "{}");
-              } catch {
-                toolInput = {};
-              }
-
-              const result = await this.executeTool(currentToolUse.name, toolInput);
-              yield { type: "tool_end", tool: currentToolUse.name, result };
-              currentToolUse = null;
-            }
+            // Don't execute tools here - wait for finalMessage to avoid double execution
+            currentToolUse = null;
+            isThinking = false;
           }
         }
 
@@ -428,7 +461,7 @@ export class ChatHandler {
         const finalMessage = await stream.finalMessage();
 
         if (finalMessage.stop_reason === "tool_use") {
-          // Process tool results and continue
+          // Process tool results (execute only once, here)
           const toolUseBlocks = finalMessage.content.filter(
             (block): block is Anthropic.ToolUseBlock => block.type === "tool_use"
           );
@@ -436,10 +469,13 @@ export class ChatHandler {
           const toolResults: Anthropic.ToolResultBlockParam[] = [];
           for (const toolUse of toolUseBlocks) {
             const result = await this.executeTool(toolUse.name, toolUse.input as Record<string, unknown>);
+            const isError = typeof result === "object" && result !== null && "error" in result;
+            yield { type: "tool_end", tool: toolUse.name, result };
             toolResults.push({
               type: "tool_result",
               tool_use_id: toolUse.id,
               content: JSON.stringify(result),
+              is_error: isError,
             });
           }
 
@@ -492,11 +528,15 @@ export class ChatHandler {
       }
 
       let response = await this.client.messages.create({
-        model: "claude-haiku-4-5-20241022",
-        max_tokens: 1024,
+        model: "claude-opus-4-5-20251101",
+        max_tokens: 16000,
         system: SYSTEM_PROMPT,
         tools: TOOLS,
         messages: this.conversationHistory,
+        thinking: {
+          type: "enabled",
+          budget_tokens: 8000,
+        },
       });
 
       // Handle tool use loop
@@ -508,10 +548,12 @@ export class ChatHandler {
         const toolResults: Anthropic.ToolResultBlockParam[] = [];
         for (const toolUse of toolUseBlocks) {
           const result = await this.executeTool(toolUse.name, toolUse.input as Record<string, unknown>);
+          const isError = typeof result === "object" && result !== null && "error" in result;
           toolResults.push({
             type: "tool_result",
             tool_use_id: toolUse.id,
             content: JSON.stringify(result),
+            is_error: isError,
           });
         }
 
@@ -527,11 +569,15 @@ export class ChatHandler {
 
         // Continue the conversation
         response = await this.client.messages.create({
-          model: "claude-haiku-4-5-20241022",
-          max_tokens: 1024,
+          model: "claude-opus-4-5-20251101",
+          max_tokens: 16000,
           system: SYSTEM_PROMPT,
           tools: TOOLS,
           messages: this.conversationHistory,
+          thinking: {
+            type: "enabled",
+            budget_tokens: 8000,
+          },
         });
       }