@shodh/memory-mcp 0.1.4 → 0.1.6

package/README.md

@@ -1,13 +1,37 @@
-# Shodh-Memory MCP Server
+<p align="center">
+  <img src="https://raw.githubusercontent.com/varun29ankuS/shodh-memory/main/assets/logo.png" width="120" alt="Shodh-Memory">
+</p>
 
-Persistent AI memory with semantic search. Store observations, decisions, learnings, and recall them across sessions.
+<h1 align="center">Shodh-Memory MCP Server</h1>
+
+<p align="center">
+  <strong>v0.1.6</strong> | Persistent cognitive memory for AI agents
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@shodh/memory-mcp"><img src="https://img.shields.io/npm/v/@shodh/memory-mcp" alt="npm"></a>
+  <a href="https://github.com/varun29ankuS/shodh-memory/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License"></a>
+</p>
+
+<p align="center">
+  <a href="https://www.shodh-rag.com/memory">Documentation</a> |
+  <a href="https://github.com/varun29ankuS/shodh-memory">GitHub</a> |
+  <a href="https://pypi.org/project/shodh-memory/">Python SDK</a> |
+  <a href="https://crates.io/crates/shodh-memory">Rust Crate</a>
+</p>
+
+---
 
 ## Features
 
-- **Semantic Search**: Find memories by meaning, not just keywords
-- **Memory Types**: Categorize as Observation, Decision, Learning, Error, Pattern, etc.
-- **Persistent**: Memories survive across sessions and restarts
-- **Fast**: Sub-millisecond retrieval with vector indexing
+- **Cognitive Architecture**: 3-tier memory (working, session, long-term) based on Cowan's model
+- **Hebbian Learning**: "Neurons that fire together wire together" - associations strengthen with use
+- **Semantic Search**: Find memories by meaning using MiniLM-L6 embeddings
+- **Knowledge Graph**: Entity extraction and relationship tracking
+- **Memory Consolidation**: Automatic decay, replay, and strengthening
+- **1-Click Install**: Auto-downloads native server binary for your platform
+- **Offline-First**: All models bundled (~15MB), no internet required after install
+- **Fast**: Sub-millisecond graph lookup, 30-50ms semantic search
 
 ## Installation
 
@@ -19,7 +43,10 @@ Add to your MCP client config:
   "mcpServers": {
     "shodh-memory": {
       "command": "npx",
-      "args": ["-y", "@shodh/memory-mcp"]
+      "args": ["-y", "@shodh/memory-mcp"],
+      "env": {
+        "SHODH_API_KEY": "your-api-key-here"
+      }
     }
   }
 }
@@ -32,26 +59,149 @@ Config file locations:
 
 **For Cursor/other MCP clients**: Similar configuration with the npx command.
 
-## Tools
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SHODH_API_KEY` | **Required**. API key for authentication | - |
+| `SHODH_API_URL` | Backend server URL | `http://127.0.0.1:3030` |
+| `SHODH_USER_ID` | User ID for memory isolation | `claude-code` |
+| `SHODH_NO_AUTO_SPAWN` | Set to `true` to disable auto-starting the backend | `false` |
+| `SHODH_STREAM` | Enable/disable streaming ingestion | `true` |
+| `SHODH_PROACTIVE` | Enable/disable proactive memory surfacing | `true` |
+
+## MCP Tools
 
 | Tool | Description |
 |------|-------------|
 | `remember` | Store a memory with optional type and tags |
 | `recall` | Semantic search to find relevant memories |
+| `proactive_context` | Auto-surface relevant memories for current context |
 | `context_summary` | Get categorized context for session bootstrap |
 | `list_memories` | List all stored memories |
 | `forget` | Delete a specific memory by ID |
 | `memory_stats` | Get statistics about stored memories |
+| `recall_by_tags` | Find memories by tag |
+| `recall_by_date` | Find memories within a date range |
+| `verify_index` | Check vector index health |
+| `repair_index` | Repair orphaned memories |
+| `consolidation_report` | View memory consolidation activity |
+
+## REST API (for Developers)
+
+The server exposes a REST API at `http://127.0.0.1:3030`:
+
+```javascript
+// Store a memory
+const res = await fetch("http://127.0.0.1:3030/api/remember", {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+    "X-API-Key": "your-api-key"
+  },
+  body: JSON.stringify({
+    user_id: "my-app",
+    content: "User prefers dark mode",
+    memory_type: "Observation",
+    tags: ["preferences", "ui"]
+  })
+});
+
+// Semantic search
+const results = await fetch("http://127.0.0.1:3030/api/recall", {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+    "X-API-Key": "your-api-key"
+  },
+  body: JSON.stringify({
+    user_id: "my-app",
+    query: "user preferences",
+    limit: 5
+  })
+});
+```
+
+### Key Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | Health check |
+| `/api/remember` | POST | Store a memory |
+| `/api/recall` | POST | Semantic search |
+| `/api/recall/tags` | POST | Search by tags |
+| `/api/recall/date` | POST | Search by date range |
+| `/api/memories` | POST | List all memories |
+| `/api/memory/{id}` | GET/PUT/DELETE | CRUD operations |
+| `/api/context_summary` | POST | Get context summary |
+| `/api/relevant` | POST | Proactive context surfacing |
+| `/api/batch_remember` | POST | Store multiple memories |
+| `/api/upsert` | POST | Create or update by external_id |
+| `/api/graph/{user_id}/stats` | GET | Knowledge graph statistics |
+| `/api/consolidation/report` | POST | Memory consolidation report |
+| `/api/index/verify` | POST | Verify index integrity |
+| `/metrics` | GET | Prometheus metrics |
+
+## Cognitive Features
+
+### Hebbian Learning
+Memories that are frequently accessed together form stronger associations. The system automatically:
+- Forms edges between co-retrieved memories
+- Strengthens connections with repeated co-activation
+- Enables Long-Term Potentiation (LTP) for permanent associations
+
+### Memory Consolidation
+Background processes maintain memory health:
+- **Decay**: Unused memories gradually lose activation
+- **Replay**: High-value memories are periodically replayed
+- **Pruning**: Weak associations are removed
+- **Promotion**: Important memories move to long-term storage
+
+### 3-Tier Architecture
+Based on Cowan's working memory model:
+1. **Working Memory**: Recent, highly active memories
+2. **Session Memory**: Current session context
+3. **Long-Term Memory**: Persistent storage with vector indexing
+
+## How It Works
+
+1. **Install**: `npx -y @shodh/memory-mcp` downloads the package
+2. **Auto-spawn**: On first run, downloads the native server binary (~15MB)
+3. **Connect**: MCP client connects to the server via stdio
+4. **Ready**: Start using `remember` and `recall` tools
+
+The backend server runs locally and stores all data on your machine. No cloud dependency.
 
 ## Usage Examples
 
 ```
 "Remember that the user prefers Rust over Python for systems programming"
 "Recall what I know about user's programming preferences"
+"What context do you have about this project?"
 "List my recent memories"
-"Show memory stats"
+"Show me the consolidation report"
 ```
 
+## Platform Support
+
+| Platform | Architecture | Status |
+|----------|--------------|--------|
+| Linux | x64 | Supported |
+| macOS | x64 | Supported |
+| macOS | ARM64 (M1/M2) | Supported |
+| Windows | x64 | Supported |
+
+## Related Packages
+
+- **Python SDK**: `pip install shodh-memory` - Native Python bindings
+- **Rust Crate**: `cargo add shodh-memory` - Use as a library
+
+## Links
+
+- [Documentation](https://www.shodh-rag.com/memory)
+- [GitHub Repository](https://github.com/varun29ankuS/shodh-memory)
+- [Issue Tracker](https://github.com/varun29ankuS/shodh-memory/issues)
+
 ## License
 
 Apache-2.0

package/dist/index.js

@@ -4878,21 +4878,198 @@ class StdioServerTransport {
 }
 
 // index.ts
+import { spawn } from "child_process";
+import * as path from "path";
+import * as fs from "fs";
+import { fileURLToPath } from "url";
+var __filename2 = fileURLToPath(import.meta.url);
+var __dirname2 = path.dirname(__filename2);
 var API_URL = process.env.SHODH_API_URL || "http://127.0.0.1:3030";
-var API_KEY = process.env.SHODH_API_KEY || "shodh-dev-key-change-in-production";
+var WS_URL = API_URL.replace(/^http/, "ws") + "/api/stream";
 var USER_ID = process.env.SHODH_USER_ID || "claude-code";
+var API_KEY = process.env.SHODH_API_KEY;
+if (!API_KEY) {
+  console.error("ERROR: SHODH_API_KEY environment variable not set.");
+  console.error("");
+  console.error("To fix, add to your MCP config (claude_desktop_config.json or mcp.json):");
+  console.error(`  "env": { "SHODH_API_KEY": "your-api-key" }`);
+  console.error("");
+  console.error("Or set in your shell:");
+  console.error("  export SHODH_API_KEY=your-api-key");
+  console.error("");
+  console.error("For local development, use the same key set in SHODH_DEV_API_KEY on the server.");
+  process.exit(1);
+}
 var RETRY_ATTEMPTS = 3;
 var RETRY_DELAY_MS = 1000;
 var REQUEST_TIMEOUT_MS = 1e4;
+var STREAM_ENABLED = process.env.SHODH_STREAM !== "false";
+var STREAM_MIN_CONTENT_LENGTH = 50;
+var PROACTIVE_SURFACING = process.env.SHODH_PROACTIVE !== "false";
+var PROACTIVE_MIN_CONTEXT_LENGTH = 30;
+var streamSocket = null;
+var streamConnecting = false;
+var streamReconnectTimer = null;
+var streamBuffer = [];
+var MAX_BUFFER_SIZE = 100;
+var streamHandshakeComplete = false;
+async function connectStream() {
+  if (!STREAM_ENABLED || streamConnecting || streamSocket?.readyState === WebSocket.OPEN) {
+    return;
+  }
+  streamConnecting = true;
+  streamHandshakeComplete = false;
+  try {
+    streamSocket = new WebSocket(WS_URL);
+    streamSocket.onopen = () => {
+      streamConnecting = false;
+      console.error("[Stream] WebSocket connected to", WS_URL);
+      const handshake = JSON.stringify({
+        user_id: USER_ID,
+        mode: "conversation",
+        extraction_config: {
+          checkpoint_interval_ms: 5000,
+          max_buffer_size: 50,
+          auto_dedupe: true,
+          extract_entities: true
+        }
+      });
+      streamSocket?.send(handshake);
+      console.error("[Stream] Sent handshake for user:", USER_ID);
+    };
+    streamSocket.onmessage = (event) => {
+      try {
+        const response = JSON.parse(event.data);
+        if (response.type === "ack" && response.message_type === "handshake") {
+          streamHandshakeComplete = true;
+          console.error("[Stream] Handshake ACK received, streaming ready");
+          const bufferedCount = streamBuffer.length;
+          while (streamBuffer.length > 0) {
+            const msg = streamBuffer.shift();
+            if (msg && streamSocket?.readyState === WebSocket.OPEN) {
+              streamSocket.send(msg);
+            }
+          }
+          if (bufferedCount > 0) {
+            console.error(`[Stream] Flushed ${bufferedCount} buffered messages`);
+          }
+        }
+      } catch {}
+    };
+    streamSocket.onclose = (event) => {
+      console.error("[Stream] WebSocket closed:", event.code, event.reason || "(no reason)");
+      streamSocket = null;
+      streamConnecting = false;
+      streamHandshakeComplete = false;
+      if (STREAM_ENABLED && !streamReconnectTimer) {
+        streamReconnectTimer = setTimeout(() => {
+          streamReconnectTimer = null;
+          console.error("[Stream] Attempting reconnect...");
+          connectStream().catch(() => {});
+        }, 5000);
+      }
+    };
+    streamSocket.onerror = (error) => {
+      console.error("[Stream] WebSocket error:", error);
+    };
+  } catch (err) {
+    console.error("[Stream] Failed to create WebSocket:", err);
+    streamConnecting = false;
+  }
+}
+function streamMemory(content, tags = [], source = "assistant", timestamp) {
+  if (!STREAM_ENABLED || content.length < STREAM_MIN_CONTENT_LENGTH)
+    return;
+  const message = JSON.stringify({
+    type: "content",
+    content: content.slice(0, 4000),
+    source,
+    timestamp: timestamp || new Date().toISOString(),
+    tags: ["stream", ...tags],
+    metadata: {}
+  });
+  if (streamSocket?.readyState === WebSocket.OPEN && streamHandshakeComplete) {
+    streamSocket.send(message);
+    console.error(`[Stream] Sent memory (${content.length} chars) with tags:`, tags);
+  } else {
+    if (streamBuffer.length < MAX_BUFFER_SIZE) {
+      streamBuffer.push(message);
+      console.error(`[Stream] Buffered memory (socket not ready, buffer size: ${streamBuffer.length})`);
+    }
+    connectStream().catch(() => {});
+  }
+}
+function streamFlush() {
+  if (!STREAM_ENABLED)
+    return;
+  if (streamSocket?.readyState === WebSocket.OPEN && streamHandshakeComplete) {
+    streamSocket.send(JSON.stringify({ type: "flush" }));
+  }
+}
+console.error("[Stream] Initializing connection to", WS_URL);
+connectStream().catch((err) => {
+  console.error("[Stream] Initial connection failed:", err);
+});
 function getContent(m) {
-  return m.experience?.content || "";
+  return m.content || m.experience?.content || "";
 }
 function getType(m) {
-  return m.experience?.experience_type || "Observation";
+  return m.memory_type || m.experience?.memory_type || m.experience?.experience_type || "Observation";
 }
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+async function surfaceRelevant(context, maxResults = 3) {
+  if (!PROACTIVE_SURFACING || context.length < PROACTIVE_MIN_CONTEXT_LENGTH) {
+    return null;
+  }
+  try {
+    const controller = new AbortController;
+    const timeoutId = setTimeout(() => controller.abort(), 3000);
+    const response = await fetch(`${API_URL}/api/relevant`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-API-Key": API_KEY
+      },
+      body: JSON.stringify({
+        user_id: USER_ID,
+        context: context.slice(0, 2000),
+        config: {
+          semantic_threshold: 0.65,
+          max_results: maxResults
+        }
+      }),
+      signal: controller.signal
+    });
+    clearTimeout(timeoutId);
+    if (!response.ok)
+      return null;
+    const result = await response.json();
+    return result.memories || null;
+  } catch {
+    return null;
+  }
+}
+function formatSurfacedMemories(memories) {
+  if (!memories || memories.length === 0)
+    return "";
+  const formatted = memories.map((m, i) => `  ${i + 1}. [${(m.relevance_score * 100).toFixed(0)}%] ${m.content.slice(0, 80)}...`).join(`
+`);
+  return `
+
+[Relevant memories surfaced]
+${formatted}`;
+}
+function streamToolCall(toolName, args, resultText) {
+  if (["remember", "recall", "forget", "list_memories"].includes(toolName))
+    return;
+  const argsStr = JSON.stringify(args, null, 2);
+  const content = `Tool: ${toolName}
+Input: ${argsStr}
+Result: ${resultText.slice(0, 1000)}${resultText.length > 1000 ? "..." : ""}`;
+  streamMemory(content, ["tool-call", toolName], "tool");
+}
 async function apiCall(endpoint, method = "GET", body) {
   let lastError = null;
   for (let attempt = 1;attempt <= RETRY_ATTEMPTS; attempt++) {
@@ -4945,7 +5122,7 @@ async function isServerAvailable() {
 }
 var server = new Server({
   name: "shodh-memory",
-  version: "0.1.2"
+  version: "0.1.51"
 }, {
   capabilities: {
     tools: {},
@@ -4975,6 +5152,43 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
               type: "array",
               items: { type: "string" },
               description: "Optional tags for categorization"
+            },
+            created_at: {
+              type: "string",
+              description: "Optional ISO 8601 timestamp for the memory (e.g., '2025-12-15T06:30:00Z'). If not provided, uses current time."
+            },
+            emotional_valence: {
+              type: "number",
+              description: "Emotional valence: -1.0 (negative) to 1.0 (positive), 0.0 = neutral. E.g., bug found: -0.3, feature shipped: 0.7"
+            },
+            emotional_arousal: {
+              type: "number",
+              description: "Arousal level: 0.0 (calm) to 1.0 (highly aroused). E.g., routine task: 0.2, critical issue: 0.9"
+            },
+            emotion: {
+              type: "string",
+              description: "Dominant emotion label (e.g., 'joy', 'frustration', 'surprise')"
+            },
+            source_type: {
+              type: "string",
+              enum: ["user", "system", "api", "file", "web", "ai_generated", "inferred"],
+              description: "Source type: where the information came from"
+            },
+            credibility: {
+              type: "number",
+              description: "Credibility score: 0.0 to 1.0 (1.0 = verified facts, 0.3 = inferred)"
+            },
+            episode_id: {
+              type: "string",
+              description: "Episode ID - groups memories into coherent episodes/conversations"
+            },
+            sequence_number: {
+              type: "number",
+              description: "Sequence number within episode (1, 2, 3...)"
+            },
+            preceding_memory_id: {
+              type: "string",
+              description: "ID of the preceding memory (for temporal chains)"
             }
           },
           required: ["content"]
@@ -4982,7 +5196,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "recall",
-        description: "Search memories by semantic similarity. Use this to find relevant past experiences, decisions, or context.",
+        description: "Search memories using different retrieval modes. Use this to find relevant past experiences, decisions, or context. Modes: 'semantic' (vector similarity), 'associative' (graph traversal - follows learned connections between memories), 'hybrid' (combines both with density-dependent weighting).",
         inputSchema: {
           type: "object",
           properties: {
@@ -4994,6 +5208,12 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
               type: "number",
               description: "Maximum number of results (default: 5)",
               default: 5
+            },
+            mode: {
+              type: "string",
+              enum: ["semantic", "associative", "hybrid"],
+              description: "Retrieval mode: 'semantic' for pure vector similarity, 'associative' for graph-based traversal (follows learned connections), 'hybrid' for density-dependent combination (default)",
+              default: "hybrid"
             }
           },
           required: ["query"]
@@ -5048,12 +5268,12 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         inputSchema: {
           type: "object",
           properties: {
-            memory_id: {
+            id: {
               type: "string",
               description: "The ID of the memory to delete"
             }
           },
-          required: ["memory_id"]
+          required: ["id"]
         }
       },
       {
@@ -5064,6 +5284,22 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {}
         }
       },
+      {
+        name: "verify_index",
+        description: "Verify vector index integrity - diagnose orphaned memories that are stored but not searchable. Returns health status and count of orphaned memories.",
+        inputSchema: {
+          type: "object",
+          properties: {}
+        }
+      },
+      {
+        name: "repair_index",
+        description: "Repair vector index by re-indexing orphaned memories. Use this when verify_index shows unhealthy status. Returns count of repaired memories.",
+        inputSchema: {
+          type: "object",
+          properties: {}
+        }
+      },
       {
         name: "recall_by_tags",
         description: "Search memories by tags. Returns memories matching ANY of the provided tags.",
@@ -5139,12 +5375,100 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           },
           required: ["start", "end"]
         }
+      },
+      {
+        name: "consolidation_report",
+        description: "Get a report of what the memory system has been learning. Shows memory strengthening/decay events, edge formation, fact extraction, and maintenance cycles. Use this to understand how your memories are evolving.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            since: {
+              type: "string",
+              description: "Start of report period (ISO 8601 format). Defaults to 24 hours ago."
+            },
+            until: {
+              type: "string",
+              description: "End of report period (ISO 8601 format). Defaults to now."
+            }
+          }
+        }
+      },
+      {
+        name: "proactive_context",
+        description: "REQUIRED: Call this tool with EVERY user message to surface relevant memories and build conversation history. Pass the user's message as context. This enables: (1) retrieving memories relevant to what the user is asking, (2) building persistent memory of the conversation for future sessions. The system analyzes entities, semantic similarity, and recency to find contextually appropriate memories. Auto-ingest stores the context automatically. USAGE: Always call this FIRST when you receive a user message, passing their message as the context parameter.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            context: {
+              type: "string",
+              description: "The current conversation context or topic (e.g., recent messages, current task description)"
+            },
+            semantic_threshold: {
+              type: "number",
+              description: "Minimum semantic similarity (0.0-1.0) for memories to be surfaced (default: 0.65)",
+              default: 0.65
+            },
+            entity_match_weight: {
+              type: "number",
+              description: "Weight for entity matching in relevance scoring (0.0-1.0, default: 0.4)",
+              default: 0.4
+            },
+            recency_weight: {
+              type: "number",
+              description: "Weight for recency boost in relevance scoring (0.0-1.0, default: 0.2)",
+              default: 0.2
+            },
+            max_results: {
+              type: "number",
+              description: "Maximum number of memories to surface (default: 5)",
+              default: 5
+            },
+            memory_types: {
+              type: "array",
+              items: { type: "string" },
+              description: "Filter to specific memory types (e.g., ['Decision', 'Learning', 'Context']). Empty means all types."
+            },
+            auto_ingest: {
+              type: "boolean",
+              description: "Automatically store the context as a Conversation memory (default: true). Set to false to only surface memories without storing.",
+              default: true
+            }
+          },
+          required: ["context"]
+        }
+      },
+      {
+        name: "streaming_status",
+        description: "Check the status of WebSocket streaming connection. Use this to diagnose if streaming memory ingestion is working.",
+        inputSchema: {
+          type: "object",
+          properties: {}
+        }
       }
     ]
   };
 });
+function autoStreamContext(toolName, args) {
+  if (["proactive_context", "streaming_status"].includes(toolName))
+    return;
+  let context = "";
+  if (args.query && typeof args.query === "string") {
+    context = `Query: ${args.query}`;
+  } else if (args.content && typeof args.content === "string") {
+    context = args.content;
+  } else if (args.context && typeof args.context === "string") {
+    context = args.context;
+  }
+  if (context.length >= 20) {
+    streamMemory(context, ["auto-context", toolName], "user");
+  }
+}
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
+  if (STREAM_ENABLED && (!streamSocket || streamSocket.readyState !== WebSocket.OPEN)) {
+    connectStream().catch(() => {});
+  }
+  autoStreamContext(name, args);
   const serverUp = await isServerAvailable();
   if (!serverUp) {
     return {
@@ -5159,42 +5483,64 @@ To start: cd shodh-memory && cargo run`
       isError: true
     };
   }
-  try {
+  const executeTool = async () => {
     switch (name) {
       case "remember": {
-        const { content, type = "Observation", tags = [] } = args;
-        const result = await apiCall("/api/record", "POST", {
+        const {
+          content,
+          type = "Observation",
+          tags = [],
+          created_at,
+          emotional_valence,
+          emotional_arousal,
+          emotion,
+          source_type,
+          credibility,
+          episode_id,
+          sequence_number,
+          preceding_memory_id
+        } = args;
+        const result = await apiCall("/api/remember", "POST", {
           user_id: USER_ID,
-          experience: {
-            content,
-            experience_type: type,
-            tags
-          }
+          content,
+          memory_type: type,
+          tags,
+          ...created_at && { created_at },
+          ...emotional_valence !== undefined && { emotional_valence },
+          ...emotional_arousal !== undefined && { emotional_arousal },
+          ...emotion && { emotion },
+          ...source_type && { source_type },
+          ...credibility !== undefined && { credibility },
+          ...episode_id && { episode_id },
+          ...sequence_number !== undefined && { sequence_number },
+          ...preceding_memory_id && { preceding_memory_id }
         });
         return {
           content: [
             {
               type: "text",
               text: `Remembered: "${content.slice(0, 50)}${content.length > 50 ? "..." : ""}"
-Memory ID: ${result.memory_id}`
+Memory ID: ${result.id}`
             }
           ]
         };
       }
       case "recall": {
-        const { query, limit = 5 } = args;
-        const result = await apiCall("/api/retrieve", "POST", {
+        const { query, limit = 5, mode = "hybrid" } = args;
+        const result = await apiCall("/api/recall", "POST", {
           user_id: USER_ID,
           query,
-          limit
+          limit,
+          mode
         });
         const memories = result.memories || [];
+        const stats = result.retrieval_stats;
         if (memories.length === 0) {
           return {
             content: [
               {
                 type: "text",
-                text: `No memories found for: "${query}"`
+                text: `No memories found for: "${query}" (mode: ${mode})`
               }
             ]
           };
@@ -5207,13 +5553,21 @@ Memory ID: ${result.memory_id}`
         }).join(`
 
 `);
+        let statsText = "";
+        if (stats && (mode === "associative" || mode === "hybrid")) {
+          const graphPct = (stats.graph_weight * 100).toFixed(0);
+          const semPct = (stats.semantic_weight * 100).toFixed(0);
+          statsText = `
+
+[Stats: ${stats.mode} mode | graph=${graphPct}% semantic=${semPct}% | density=${stats.graph_density.toFixed(2)} | ${stats.graph_candidates} graph + ${stats.semantic_candidates} semantic candidates | ${stats.entities_activated} entities | ${(stats.retrieval_time_us / 1000).toFixed(1)}ms]`;
+        }
         return {
           content: [
             {
               type: "text",
-              text: `Found ${memories.length} relevant memories:
+              text: `Found ${memories.length} relevant memories (${mode} mode):
 
-${formatted}`
+${formatted}${statsText}`
             }
           ]
         };
@@ -5345,13 +5699,13 @@ ${formatted}`
         };
       }
       case "forget": {
-        const { memory_id } = args;
-        await apiCall(`/api/memory/${memory_id}?user_id=${USER_ID}`, "DELETE");
+        const { id } = args;
+        await apiCall(`/api/memory/${id}?user_id=${USER_ID}`, "DELETE");
         return {
           content: [
             {
               type: "text",
-              text: `Deleted memory: ${memory_id}`
+              text: `Deleted memory: ${id}`
             }
           ]
         };
@@ -5368,6 +5722,71 @@ ${JSON.stringify(result, null, 2)}`
           ]
         };
       }
+      case "verify_index": {
+        const result = await apiCall("/api/index/verify", "POST", {
+          user_id: USER_ID
+        });
+        const statusIcon = result.is_healthy ? "✓" : "⚠";
+        const healthText = result.is_healthy ? "Healthy" : "Unhealthy - orphaned memories detected";
+        let response = `Index Integrity Report
+`;
+        response += `━━━━━━━━━━━━━━━━━━━━━━━━━
+`;
+        response += `Status: ${statusIcon} ${healthText}
+`;
+        response += `Total in storage: ${result.total_storage}
+`;
+        response += `Total indexed: ${result.total_indexed}
+`;
+        response += `Orphaned count: ${result.orphaned_count}
+`;
+        if (result.orphaned_count > 0) {
+          response += `
+Recommendation: Run repair_index to fix orphaned memories.`;
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: response
+            }
+          ]
+        };
+      }
+      case "repair_index": {
+        const result = await apiCall("/api/index/repair", "POST", {
+          user_id: USER_ID
+        });
+        const statusIcon = result.is_healthy ? "✓" : "⚠";
+        let response = `Index Repair Results
+`;
+        response += `━━━━━━━━━━━━━━━━━━━━━
+`;
+        response += `Status: ${statusIcon} ${result.success ? "Success" : "Partial success"}
+`;
+        response += `Total in storage: ${result.total_storage}
+`;
+        response += `Total indexed: ${result.total_indexed}
+`;
+        response += `Repaired: ${result.repaired}
+`;
+        response += `Failed: ${result.failed}
+`;
+        response += `Index healthy: ${result.is_healthy ? "Yes" : "No"}
+`;
+        if (result.failed > 0) {
+          response += `
+Note: ${result.failed} memories could not be repaired (embedding generation failed).`;
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: response
+            }
+          ]
+        };
+      }
       case "recall_by_tags": {
         const { tags, limit = 20 } = args;
         const result = await apiCall("/api/recall/tags", "POST", {
@@ -5472,9 +5891,219 @@ ${formatted}`
           ]
         };
       }
+      case "proactive_context": {
+        const {
+          context,
+          semantic_threshold = 0.65,
+          entity_match_weight = 0.4,
+          recency_weight = 0.2,
+          max_results = 5,
+          memory_types = [],
+          auto_ingest = true
+        } = args;
+        if (auto_ingest && context.length > 100) {
+          streamMemory(context.slice(0, 2000), ["proactive-context"]);
+          streamFlush();
+        }
+        const result = await apiCall("/api/relevant", "POST", {
+          user_id: USER_ID,
+          context,
+          config: {
+            semantic_threshold,
+            entity_match_weight,
+            semantic_weight: 1 - entity_match_weight - recency_weight,
+            recency_weight,
+            max_results,
+            memory_types
+          }
+        });
+        const memories = result.memories || [];
+        const entities = result.detected_entities || [];
+        if (memories.length === 0) {
+          if (entities.length > 0) {
+            const entityList = entities.map((e) => `  - "${e.text}" (${e.entity_type}, ${(e.confidence * 100).toFixed(0)}% confidence)`).join(`
+`);
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `No relevant memories surfaced for this context.
+
+Detected entities:
+${entityList}
+
+[Latency: ${result.latency_ms.toFixed(1)}ms]`
+                }
+              ]
+            };
+          }
+          return {
+            content: [
+              {
+                type: "text",
+                text: `No relevant memories surfaced for this context.
+
+[Latency: ${result.latency_ms.toFixed(1)}ms]`
+              }
+            ]
+          };
+        }
+        const formatted = memories.map((m, i) => {
+          const score = (m.relevance_score * 100).toFixed(0);
+          const entityMatchStr = m.matched_entities && m.matched_entities.length > 0 ? `
+   Entity matches: ${m.matched_entities.join(", ")}` : "";
+          const semScore = (m.semantic_similarity * 100).toFixed(0);
+          return `${i + 1}. [${score}% relevant] ${m.content.slice(0, 100)}${m.content.length > 100 ? "..." : ""}
+   Type: ${m.memory_type} | semantic=${semScore}% | reason: ${m.relevance_reason}${entityMatchStr}`;
+        }).join(`
+
+`);
+        const entitySummary = entities.length > 0 ? `
+
+Detected entities: ${entities.map((e) => `"${e.text}" (${e.entity_type})`).join(", ")}` : "";
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Surfaced ${memories.length} relevant memories:
+
+${formatted}${entitySummary}
+
+[Latency: ${result.latency_ms.toFixed(1)}ms | Threshold: ${(semantic_threshold * 100).toFixed(0)}%]`
+            }
+          ]
+        };
+      }
+      case "streaming_status": {
+        const wsState = streamSocket?.readyState;
+        const stateNames = ["CONNECTING", "OPEN", "CLOSING", "CLOSED"];
+        const stateName = wsState !== undefined ? stateNames[wsState] || "UNKNOWN" : "NULL";
+        const status = {
+          enabled: STREAM_ENABLED,
+          ws_url: WS_URL,
+          socket_state: stateName,
+          handshake_complete: streamHandshakeComplete,
+          buffer_size: streamBuffer.length,
+          connecting: streamConnecting,
+          reconnect_pending: streamReconnectTimer !== null
+        };
+        if (!streamSocket || streamSocket.readyState !== WebSocket.OPEN) {
+          connectStream().catch(() => {});
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Streaming Status:
+
+` + `Enabled: ${status.enabled}
+` + `WebSocket URL: ${status.ws_url}
+` + `Socket State: ${status.socket_state}
+` + `Handshake Complete: ${status.handshake_complete}
+` + `Buffer Size: ${status.buffer_size}
+` + `Currently Connecting: ${status.connecting}
+` + `Reconnect Pending: ${status.reconnect_pending}
+
+` + (status.handshake_complete ? "✓ Streaming is ACTIVE" : "✗ Streaming is NOT ACTIVE - attempting reconnect...")
+            }
+          ]
+        };
+      }
+      case "consolidation_report": {
+        const { since, until } = args;
+        const result = await apiCall("/api/consolidation/report", "POST", {
+          user_id: USER_ID,
+          since,
+          until
+        });
+        const stats = result.statistics;
+        const sections = [];
+        const eventCount = result.strengthened_memories.length + result.decayed_memories.length + result.formed_associations.length + result.strengthened_associations.length + result.potentiated_associations.length + result.pruned_associations.length + result.extracted_facts.length + result.reinforced_facts.length;
+        sections.push(`CONSOLIDATION REPORT (${eventCount} events)`);
+        sections.push(`Period: ${result.period.start} to ${result.period.end}`);
+        sections.push("=".repeat(50));
+        if (stats.memories_strengthened > 0 || stats.memories_decayed > 0 || stats.memories_at_risk > 0) {
+          const memoryLines = [];
+          if (stats.memories_strengthened > 0)
+            memoryLines.push(`  + ${stats.memories_strengthened} memories strengthened`);
+          if (stats.memories_decayed > 0)
+            memoryLines.push(`  - ${stats.memories_decayed} memories decayed`);
+          if (stats.memories_at_risk > 0)
+            memoryLines.push(`  ! ${stats.memories_at_risk} memories at risk of forgetting`);
+          sections.push(`MEMORY CHANGES:
+${memoryLines.join(`
+`)}`);
+        }
+        if (stats.edges_formed > 0 || stats.edges_strengthened > 0 || stats.edges_potentiated > 0 || stats.edges_pruned > 0) {
+          const edgeLines = [];
+          if (stats.edges_formed > 0)
+            edgeLines.push(`  + ${stats.edges_formed} new associations formed`);
+          if (stats.edges_strengthened > 0)
+            edgeLines.push(`  + ${stats.edges_strengthened} associations strengthened`);
+          if (stats.edges_potentiated > 0)
+            edgeLines.push(`  * ${stats.edges_potentiated} associations became permanent (LTP)`);
+          if (stats.edges_pruned > 0)
+            edgeLines.push(`  - ${stats.edges_pruned} weak associations pruned`);
+          sections.push(`ASSOCIATIONS (Hebbian Learning):
+${edgeLines.join(`
+`)}`);
+        }
+        if (stats.facts_extracted > 0 || stats.facts_reinforced > 0) {
+          const factLines = [];
+          if (stats.facts_extracted > 0)
+            factLines.push(`  + ${stats.facts_extracted} facts extracted`);
+          if (stats.facts_reinforced > 0)
+            factLines.push(`  + ${stats.facts_reinforced} facts reinforced`);
+          sections.push(`FACTS:
+${factLines.join(`
+`)}`);
+        }
+        if (stats.maintenance_cycles > 0) {
+          const durationSec = (stats.total_maintenance_duration_ms / 1000).toFixed(2);
+          sections.push(`MAINTENANCE: ${stats.maintenance_cycles} cycle(s) completed (${durationSec}s total)`);
+        }
+        if (eventCount === 0) {
+          sections.push("No consolidation activity in this period. Store and access memories to trigger learning.");
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: sections.join(`
+
+`)
+            }
+          ]
+        };
+      }
       default:
         throw new Error(`Unknown tool: ${name}`);
     }
+  };
+  try {
+    const result = await executeTool();
+    const resultText = result.content.map((c) => c.text).join(`
+`);
+    streamToolCall(name, args, resultText);
+    if (PROACTIVE_SURFACING && !["remember", "recall", "forget", "list_memories", "proactive_context", "context_summary", "memory_stats"].includes(name)) {
+      const contextParts = [];
+      if (args && typeof args === "object") {
+        for (const [key, value] of Object.entries(args)) {
+          if (typeof value === "string" && value.length > 10) {
+            contextParts.push(value);
+          }
+        }
+      }
+      const context = contextParts.join(" ").slice(0, 1000);
+      if (context.length >= PROACTIVE_MIN_CONTEXT_LENGTH) {
+        const surfaced = await surfaceRelevant(context, 3);
+        if (surfaced && surfaced.length > 0) {
+          const surfacedText = formatSurfacedMemories(surfaced);
+          result.content[result.content.length - 1].text += surfacedText;
+        }
+      }
+    }
+    return result;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     let helpText = "";
@@ -5554,11 +6183,98 @@ ID: ${memory.id}`
     throw new Error(`Failed to read memory: ${message}`);
   }
 });
+var AUTO_SPAWN_ENABLED = process.env.SHODH_NO_AUTO_SPAWN !== "true";
+var serverProcess = null;
+function getBinaryPath() {
+  const platform = process.platform;
+  const binDir = path.join(__dirname2, "..", "bin");
+  let wrapperName;
+  let fallbackName;
+  if (platform === "win32") {
+    wrapperName = "shodh-memory.bat";
+    fallbackName = "shodh-memory-server.exe";
+  } else {
+    wrapperName = "shodh-memory";
+    fallbackName = "shodh-memory-server";
+  }
+  const wrapperPath = path.join(binDir, wrapperName);
+  if (fs.existsSync(wrapperPath)) {
+    return wrapperPath;
+  }
+  const binaryPath = path.join(binDir, fallbackName);
+  if (fs.existsSync(binaryPath)) {
+    return binaryPath;
+  }
+  return null;
+}
+async function isServerRunning() {
+  try {
+    const controller = new AbortController;
+    const timeout = setTimeout(() => controller.abort(), 2000);
+    const response = await fetch(`${API_URL}/health`, {
+      signal: controller.signal
+    });
+    clearTimeout(timeout);
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+async function waitForServer(maxAttempts = 30) {
+  for (let i = 0;i < maxAttempts; i++) {
+    if (await isServerRunning()) {
+      return true;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 500));
+  }
+  return false;
+}
+async function ensureServerRunning() {
+  if (await isServerRunning()) {
+    console.error("[shodh-memory] Backend server already running at", API_URL);
+    return;
+  }
+  if (!AUTO_SPAWN_ENABLED) {
+    console.error("[shodh-memory] Auto-spawn disabled. Please start the server manually.");
+    return;
+  }
+  const binaryPath = getBinaryPath();
+  if (!binaryPath) {
+    console.error("[shodh-memory] Server binary not found. Please run: npx @shodh/memory-mcp");
+    console.error("[shodh-memory] Or download from: https://github.com/varun29ankuS/shodh-memory/releases");
+    return;
+  }
+  console.error("[shodh-memory] Starting backend server...");
+  serverProcess = spawn(binaryPath, [], {
+    detached: true,
+    stdio: "ignore",
+    env: {
+      ...process.env,
+      SHODH_DEV_API_KEY: API_KEY
+    }
+  });
+  serverProcess.unref();
+  console.error("[shodh-memory] Waiting for server to start...");
+  const started = await waitForServer();
+  if (started) {
+    console.error("[shodh-memory] Backend server started successfully");
+  } else {
+    console.error("[shodh-memory] Warning: Server may not have started properly");
+  }
+}
+process.on("exit", () => {
+  if (serverProcess && !serverProcess.killed) {
+    serverProcess.kill();
+  }
+});
 async function main() {
+  await ensureServerRunning();
   const transport = new StdioServerTransport;
   await server.connect(transport);
-  console.error("Shodh-Memory MCP server v0.1.2 running");
+  console.error("Shodh-Memory MCP server v0.1.51 running");
   console.error(`Connecting to: ${API_URL}`);
   console.error(`User ID: ${USER_ID}`);
+  console.error(`Streaming: ${STREAM_ENABLED ? "enabled" : "disabled"}`);
+  console.error(`Proactive surfacing: ${PROACTIVE_SURFACING ? "enabled" : "disabled (SHODH_PROACTIVE=false)"}`);
 }
 main().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shodh/memory-mcp",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "mcpName": "io.github.varun29ankuS/shodh-memory",
   "description": "MCP server for persistent AI memory - store and recall context across sessions",
   "type": "module",
@@ -11,10 +11,12 @@
   "scripts": {
     "start": "bun run index.ts",
     "build": "bun build index.ts --outdir dist --target node",
+    "postinstall": "node scripts/postinstall.cjs",
     "prepublishOnly": "npm run build"
   },
   "files": [
     "dist",
+    "scripts",
     "README.md"
   ],
   "dependencies": {

package/scripts/postinstall.cjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * Postinstall script for @shodh/memory-mcp
+ *
+ * Downloads the appropriate shodh-memory-server binary for the current platform
+ * from GitHub releases.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const { execSync } = require('child_process');
+
+const VERSION = '0.1.6';
+const REPO = 'varun29ankuS/shodh-memory';
+const BIN_DIR = path.join(__dirname, '..', 'bin');
+
+// Platform detection
+function getPlatformInfo() {
+  const platform = process.platform;
+  const arch = process.arch;
+
+  if (platform === 'linux' && arch === 'x64') {
+    return { name: 'shodh-memory-linux-x64', ext: '.tar.gz', binary: 'shodh-memory-server' };
+  } else if (platform === 'darwin' && arch === 'x64') {
+    return { name: 'shodh-memory-macos-x64', ext: '.tar.gz', binary: 'shodh-memory-server' };
+  } else if (platform === 'darwin' && arch === 'arm64') {
+    return { name: 'shodh-memory-macos-arm64', ext: '.tar.gz', binary: 'shodh-memory-server' };
+  } else if (platform === 'win32' && arch === 'x64') {
+    return { name: 'shodh-memory-windows-x64', ext: '.zip', binary: 'shodh-memory-server.exe' };
+  } else {
+    return null;
+  }
+}
+
+// Download file with redirect following
+function download(url, dest) {
+  return new Promise((resolve, reject) => {
+    const file = fs.createWriteStream(dest);
+
+    const request = (url) => {
+      https.get(url, (response) => {
+        if (response.statusCode === 302 || response.statusCode === 301) {
+          // Follow redirect
+          request(response.headers.location);
+          return;
+        }
+
+        if (response.statusCode !== 200) {
+          reject(new Error(`Failed to download: ${response.statusCode}`));
+          return;
+        }
+
+        response.pipe(file);
+        file.on('finish', () => {
+          file.close();
+          resolve();
+        });
+      }).on('error', (err) => {
+        fs.unlink(dest, () => {});
+        reject(err);
+      });
+    };
+
+    request(url);
+  });
+}
+
+// Extract archive
+function extract(archive, dest, platformInfo) {
+  if (platformInfo.ext === '.tar.gz') {
+    execSync(`tar -xzf "${archive}" -C "${dest}"`, { stdio: 'inherit' });
+  } else if (platformInfo.ext === '.zip') {
+    // Use PowerShell on Windows
+    execSync(`powershell -Command "Expand-Archive -Path '${archive}' -DestinationPath '${dest}' -Force"`, { stdio: 'inherit' });
+  }
+}
+
+async function main() {
+  const platformInfo = getPlatformInfo();
+
+  if (!platformInfo) {
+    console.log('[shodh-memory] Unsupported platform:', process.platform, process.arch);
+    console.log('[shodh-memory] You will need to run the server manually.');
+    return;
+  }
+
+  console.log('[shodh-memory] Installing server binary for', process.platform, process.arch);
+
+  // Create bin directory
+  if (!fs.existsSync(BIN_DIR)) {
+    fs.mkdirSync(BIN_DIR, { recursive: true });
+  }
+
+  const binaryPath = path.join(BIN_DIR, platformInfo.binary);
+
+  // Check if already installed
+  if (fs.existsSync(binaryPath)) {
+    console.log('[shodh-memory] Binary already installed at', binaryPath);
+    return;
+  }
+
+  // Download URL
+  const downloadUrl = `https://github.com/${REPO}/releases/download/v${VERSION}/${platformInfo.name}${platformInfo.ext}`;
+  const archivePath = path.join(BIN_DIR, `${platformInfo.name}${platformInfo.ext}`);
+
+  console.log('[shodh-memory] Downloading from', downloadUrl);
+
+  try {
+    await download(downloadUrl, archivePath);
+    console.log('[shodh-memory] Downloaded archive');
+
+    // Extract
+    extract(archivePath, BIN_DIR, platformInfo);
+    console.log('[shodh-memory] Extracted binary');
+
+    // Clean up archive
+    fs.unlinkSync(archivePath);
+
+    // Make executable (Unix)
+    if (process.platform !== 'win32') {
+      fs.chmodSync(binaryPath, 0o755);
+    }
+
+    console.log('[shodh-memory] Server binary installed at', binaryPath);
+  } catch (err) {
+    console.error('[shodh-memory] Failed to install binary:', err.message);
+    console.log('[shodh-memory] You can manually download from:', `https://github.com/${REPO}/releases`);
+  }
+}
+
+main();