@shodh/memory-mcp 0.1.0 → 0.1.2

package/README.md

@@ -11,36 +11,25 @@ Persistent AI memory with semantic search. Store observations, decisions, learni
 
 ## Installation
 
-### 1. Start the shodh-memory backend
+Add to your MCP client config:
 
-```bash
-# Download and run the server
-cargo install shodh-memory
-shodh-memory-server
-```
-
-Or with Docker:
-```bash
-docker run -p 3030:3030 shodh/memory
-```
-
-### 2. Configure your MCP client
-
-**For Claude Desktop** (`~/.claude/claude_desktop_config.json`):
+**Claude Desktop / Claude Code** (`claude_desktop_config.json`):
 ```json
 {
   "mcpServers": {
     "shodh-memory": {
       "command": "npx",
-      "args": ["@shodh/memory-mcp"],
-      "env": {
-        "SHODH_API_URL": "http://127.0.0.1:3030"
-      }
+      "args": ["-y", "@shodh/memory-mcp"]
     }
   }
 }
 ```
 
+Config file locations:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+
 **For Cursor/other MCP clients**: Similar configuration with the npx command.
 
 ## Tools
@@ -49,6 +38,7 @@ docker run -p 3030:3030 shodh/memory
 |------|-------------|
 | `remember` | Store a memory with optional type and tags |
 | `recall` | Semantic search to find relevant memories |
+| `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 |
@@ -62,24 +52,6 @@ docker run -p 3030:3030 shodh/memory
 "Show memory stats"
 ```
 
-## Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `SHODH_API_URL` | `http://127.0.0.1:3030` | Backend server URL |
-| `SHODH_API_KEY` | (dev key) | API key for authentication |
-| `SHODH_USER_ID` | `default` | User ID for memory isolation |
-
-## Architecture
-
-```
-┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
-│   AI Client     │────▶│   MCP Server    │────▶│ Shodh Backend   │
-│ (Claude, etc.)  │     │  (this package) │     │  (Rust server)  │
-└─────────────────┘     └─────────────────┘     └─────────────────┘
-                              stdio              REST API
-```
-
 ## License
 
 Apache-2.0

package/dist/index.js

@@ -4881,26 +4881,71 @@ class StdioServerTransport {
 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 USER_ID = process.env.SHODH_USER_ID || "claude-code";
+var RETRY_ATTEMPTS = 3;
+var RETRY_DELAY_MS = 1000;
+var REQUEST_TIMEOUT_MS = 1e4;
+function getContent(m) {
+  return m.experience?.content || "";
+}
+function getType(m) {
+  return m.experience?.experience_type || "Observation";
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 async function apiCall(endpoint, method = "GET", body) {
-  const options = {
-    method,
-    headers: {
-      "Content-Type": "application/json",
-      "X-API-Key": API_KEY
+  let lastError = null;
+  for (let attempt = 1;attempt <= RETRY_ATTEMPTS; attempt++) {
+    try {
+      const controller = new AbortController;
+      const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+      const options = {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          "X-API-Key": API_KEY
+        },
+        signal: controller.signal
+      };
+      if (body) {
+        options.body = JSON.stringify(body);
+      }
+      const response = await fetch(`${API_URL}${endpoint}`, options);
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const errorText = await response.text().catch(() => "Unknown error");
+        throw new Error(`API error ${response.status}: ${errorText}`);
+      }
+      return await response.json();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      if (lastError.message.includes("API error 4")) {
+        throw lastError;
+      }
+      if (attempt < RETRY_ATTEMPTS) {
+        console.error(`Attempt ${attempt} failed: ${lastError.message}. Retrying in ${RETRY_DELAY_MS}ms...`);
+        await sleep(RETRY_DELAY_MS * attempt);
+      }
     }
-  };
-  if (body) {
-    options.body = JSON.stringify(body);
   }
-  const response = await fetch(`${API_URL}${endpoint}`, options);
-  if (!response.ok) {
-    throw new Error(`API error: ${response.status} ${response.statusText}`);
+  throw new Error(`Failed after ${RETRY_ATTEMPTS} attempts: ${lastError?.message || "Unknown error"}`);
+}
+async function isServerAvailable() {
+  try {
+    const controller = new AbortController;
+    const timeoutId = setTimeout(() => controller.abort(), 2000);
+    const response = await fetch(`${API_URL}/health`, {
+      signal: controller.signal
+    });
+    clearTimeout(timeoutId);
+    return response.ok;
+  } catch {
+    return false;
   }
-  return response.json();
 }
 var server = new Server({
   name: "shodh-memory",
-  version: "0.1.0"
+  version: "0.1.2"
 }, {
   capabilities: {
     tools: {},
@@ -4954,6 +4999,35 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           required: ["query"]
         }
       },
+      {
+        name: "context_summary",
+        description: "Get a condensed summary of recent learnings, decisions, and context. Use this at the start of a session to quickly understand what you've learned before.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            include_decisions: {
+              type: "boolean",
+              description: "Include recent decisions (default: true)",
+              default: true
+            },
+            include_learnings: {
+              type: "boolean",
+              description: "Include recent learnings (default: true)",
+              default: true
+            },
+            include_context: {
+              type: "boolean",
+              description: "Include project context (default: true)",
+              default: true
+            },
+            max_items: {
+              type: "number",
+              description: "Maximum items per category (default: 5)",
+              default: 5
+            }
+          }
+        }
+      },
       {
         name: "list_memories",
         description: "List all stored memories",
@@ -4995,6 +5069,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 });
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
+  const serverUp = await isServerAvailable();
+  if (!serverUp) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Memory server unavailable at ${API_URL}. Please ensure shodh-memory-server is running.
+
+To start: cd shodh-memory && cargo run`
+        }
+      ],
+      isError: true
+    };
+  }
   try {
     switch (name) {
       case "remember": {
@@ -5035,8 +5123,12 @@ Memory ID: ${result.memory_id}`
             ]
           };
         }
-        const formatted = memories.map((m, i) => `${i + 1}. [${((m.score || 0) * 100).toFixed(0)}%] ${m.content}
-   ID: ${m.memory_id.slice(0, 8)}...`).join(`
+        const formatted = memories.map((m, i) => {
+          const content = getContent(m);
+          const score = ((m.score || 0) * 100).toFixed(0);
+          return `${i + 1}. [${score}% match] ${content}
+   Type: ${getType(m)} | ID: ${m.id.slice(0, 8)}...`;
+        }).join(`
 
 `);
         return {
@@ -5050,6 +5142,98 @@ ${formatted}`
           ]
         };
       }
+      case "context_summary": {
+        const {
+          include_decisions = true,
+          include_learnings = true,
+          include_context = true,
+          max_items = 5
+        } = args;
+        const result = await apiCall("/api/memories", "POST", {
+          user_id: USER_ID
+        });
+        const memories = result.memories || [];
+        if (memories.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "No memories stored yet. Start remembering things to build context!"
+              }
+            ]
+          };
+        }
+        const decisions = [];
+        const learnings = [];
+        const context = [];
+        const patterns = [];
+        const errors2 = [];
+        for (const m of memories) {
+          const type = getType(m);
+          switch (type) {
+            case "Decision":
+              decisions.push(m);
+              break;
+            case "Learning":
+              learnings.push(m);
+              break;
+            case "Context":
+              context.push(m);
+              break;
+            case "Pattern":
+              patterns.push(m);
+              break;
+            case "Error":
+              errors2.push(m);
+              break;
+          }
+        }
+        const sections = [];
+        if (include_context && context.length > 0) {
+          const items = context.slice(0, max_items).map((m) => `  - ${getContent(m).slice(0, 100)}`);
+          sections.push(`PROJECT CONTEXT:
+${items.join(`
+`)}`);
+        }
+        if (include_decisions && decisions.length > 0) {
+          const items = decisions.slice(0, max_items).map((m) => `  - ${getContent(m).slice(0, 100)}`);
+          sections.push(`DECISIONS MADE:
+${items.join(`
+`)}`);
+        }
+        if (include_learnings && learnings.length > 0) {
+          const items = learnings.slice(0, max_items).map((m) => `  - ${getContent(m).slice(0, 100)}`);
+          sections.push(`LEARNINGS:
+${items.join(`
+`)}`);
+        }
+        if (patterns.length > 0) {
+          const items = patterns.slice(0, max_items).map((m) => `  - ${getContent(m).slice(0, 100)}`);
+          sections.push(`PATTERNS NOTICED:
+${items.join(`
+`)}`);
+        }
+        if (errors2.length > 0) {
+          const items = errors2.slice(0, Math.min(3, max_items)).map((m) => `  - ${getContent(m).slice(0, 100)}`);
+          sections.push(`ERRORS TO AVOID:
+${items.join(`
+`)}`);
+        }
+        const summary = sections.length > 0 ? sections.join(`
+
+`) : `${memories.length} memories stored, but none categorized as decisions, learnings, or context. Consider using those types when remembering.`;
+        return {
+          content: [
+            {
+              type: "text",
+              text: `CONTEXT SUMMARY (${memories.length} total memories)
+${"=".repeat(40)}
+
+${summary}`
+            }
+          ]
+        };
+      }
       case "list_memories": {
         const { limit = 20 } = args;
         const result = await apiCall("/api/memories", "POST", {
@@ -5066,8 +5250,11 @@ ${formatted}`
             ]
           };
         }
-        const formatted = memories.map((m, i) => `${i + 1}. ${m.content.slice(0, 80)}${m.content.length > 80 ? "..." : ""}
-   Type: ${m.experience_type || "unknown"} | ID: ${m.memory_id.slice(0, 8)}...`).join(`
+        const formatted = memories.map((m, i) => {
+          const content = getContent(m);
+          return `${i + 1}. ${content.slice(0, 80)}${content.length > 80 ? "..." : ""}
+   Type: ${getType(m)} | ID: ${m.id.slice(0, 8)}...`;
+        }).join(`
 
 `);
         return {
@@ -5110,11 +5297,26 @@ ${JSON.stringify(result, null, 2)}`
     }
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
+    let helpText = "";
+    if (message.includes("ECONNREFUSED") || message.includes("fetch failed")) {
+      helpText = `
+
+The memory server appears to be offline. Start it with:
+  cd shodh-memory && cargo run`;
+    } else if (message.includes("API error 401")) {
+      helpText = `
+
+Authentication failed. Check your SHODH_API_KEY.`;
+    } else if (message.includes("API error 404")) {
+      helpText = `
+
+Endpoint not found. The server may be running an older version.`;
+    }
     return {
       content: [
         {
           type: "text",
-          text: `Error: ${message}`
+          text: `Error: ${message}${helpText}`
         }
       ],
       isError: true
@@ -5128,12 +5330,15 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => {
     });
     const memories = result.memories || [];
     return {
-      resources: memories.slice(0, 50).map((m) => ({
-        uri: `memory://${m.memory_id}`,
-        name: m.content.slice(0, 50) + (m.content.length > 50 ? "..." : ""),
-        mimeType: "text/plain",
-        description: `Type: ${m.experience_type || "unknown"}`
-      }))
+      resources: memories.slice(0, 50).map((m) => {
+        const content = getContent(m);
+        return {
+          uri: `memory://${m.id}`,
+          name: content.slice(0, 50) + (content.length > 50 ? "..." : ""),
+          mimeType: "text/plain",
+          description: `Type: ${getType(m)}`
+        };
+      })
     };
   } catch {
     return { resources: [] };
@@ -5146,20 +5351,21 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
     const result = await apiCall("/api/memories", "POST", {
       user_id: USER_ID
     });
-    const memory = (result.memories || []).find((m) => m.memory_id === memoryId);
+    const memory = (result.memories || []).find((m) => m.id === memoryId);
     if (!memory) {
       throw new Error(`Memory not found: ${memoryId}`);
     }
+    const content = getContent(memory);
     return {
       contents: [
         {
           uri,
           mimeType: "text/plain",
-          text: `Content: ${memory.content}
+          text: `Content: ${content}
 
-Type: ${memory.experience_type || "unknown"}
+Type: ${getType(memory)}
 Created: ${memory.created_at || "unknown"}
-ID: ${memory.memory_id}`
+ID: ${memory.id}`
         }
       ]
     };
@@ -5171,6 +5377,8 @@ ID: ${memory.memory_id}`
 async function main() {
   const transport = new StdioServerTransport;
   await server.connect(transport);
-  console.error("Shodh-Memory MCP server running");
+  console.error("Shodh-Memory MCP server v0.1.2 running");
+  console.error(`Connecting to: ${API_URL}`);
+  console.error(`User ID: ${USER_ID}`);
 }
 main().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shodh/memory-mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "mcpName": "io.github.varun29ankuS/shodh-memory",
   "description": "MCP server for persistent AI memory - store and recall context across sessions",
   "type": "module",