@mnemoverse/mcp-memory-server 0.1.0

package/README.md

@@ -0,0 +1,131 @@
+# @mnemoverse/mcp-memory-server
+
+Persistent AI memory for Claude Code, Cursor, VS Code, and any MCP client.
+
+Your agent remembers everything — across sessions, projects, and tools. One memory, everywhere.
+
+## Quick Start
+
+### 1. Get a free API key
+
+Sign up at [console.mnemoverse.com](https://console.mnemoverse.com) — takes 30 seconds, no credit card.
+
+### 2. Connect to your AI tool
+
+**Claude Code:**
+
+```bash
+claude mcp add mnemoverse -e MNEMOVERSE_API_KEY=mk_live_YOUR_KEY -- npx @mnemoverse/mcp-memory-server
+```
+
+**Cursor** — add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "mnemoverse": {
+      "command": "npx",
+      "args": ["@mnemoverse/mcp-memory-server"],
+      "env": {
+        "MNEMOVERSE_API_KEY": "mk_live_YOUR_KEY"
+      }
+    }
+  }
+}
+```
+
+**VS Code** — add to settings.json:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "mnemoverse": {
+        "command": "npx",
+        "args": ["@mnemoverse/mcp-memory-server"],
+        "env": {
+          "MNEMOVERSE_API_KEY": "mk_live_YOUR_KEY"
+        }
+      }
+    }
+  }
+}
+```
+
+**Windsurf** — add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mnemoverse": {
+      "command": "npx",
+      "args": ["@mnemoverse/mcp-memory-server"],
+      "env": {
+        "MNEMOVERSE_API_KEY": "mk_live_YOUR_KEY"
+      }
+    }
+  }
+}
+```
+
+### 3. Done
+
+Your AI now has persistent memory. Try:
+
+> "Remember that I prefer Railway for deployments"
+
+Then in a new session:
+
+> "Where should I deploy this?"
+
+It remembers.
+
+## Tools
+
+| Tool | What it does |
+|------|-------------|
+| `memory_write` | Store a memory — insight, preference, lesson learned |
+| `memory_read` | Search memories by natural language query |
+| `memory_feedback` | Rate memories as helpful or not (improves future recall) |
+| `memory_stats` | Check how many memories stored, which domains exist |
+
+## Ideas: What to Remember
+
+- **User preferences**: "I use dark mode", "I prefer Tailwind over CSS modules"
+- **Project context**: "This project uses PostgreSQL + Prisma", "Deploy to Railway"
+- **Lessons learned**: "Always run tests before push on this repo"
+- **Decisions made**: "We chose REST over GraphQL because of caching simplicity"
+- **People & roles**: "Alice is the designer, Bob owns the API"
+- **Past mistakes**: "Don't deploy on Fridays — learned this the hard way"
+
+## Universal Memory
+
+The same API key works across all tools. Write a memory in Claude Code — read it in Cursor. Learn something in VS Code — your GPT Custom Action knows it too.
+
+```
+                    ┌── Claude Code (this MCP server)
+                    ├── Cursor (this MCP server)
+   Mnemoverse API ──├── VS Code (this MCP server)
+   (one memory)     ├── GPT (Custom Actions)
+                    ├── Python SDK (pip install mnemoverse)
+                    └── REST API (curl)
+```
+
+## Configuration
+
+| Env Variable | Required | Default |
+|-------------|----------|---------|
+| `MNEMOVERSE_API_KEY` | Yes | — |
+| `MNEMOVERSE_API_URL` | No | `https://core.mnemoverse.com/api/v1` |
+
+## Links
+
+- [Documentation](https://mnemoverse.com/docs/api/mcp-server)
+- [Python SDK](https://mnemoverse.com/docs/api/python-sdk)
+- [API Reference](https://mnemoverse.com/docs/api/reference)
+- [Console (get API key)](https://console.mnemoverse.com)
+- [GitHub](https://github.com/mnemoverse/mcp-memory-server)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const API_URL = process.env.MNEMOVERSE_API_URL || "https://core.mnemoverse.com/api/v1";
+const API_KEY = process.env.MNEMOVERSE_API_KEY || "";
+if (!API_KEY) {
+    console.error("Error: MNEMOVERSE_API_KEY environment variable is required.\n" +
+        "Get your free key at https://console.mnemoverse.com");
+    process.exit(1);
+}
+async function apiFetch(path, options = {}) {
+    const res = await fetch(`${API_URL}${path}`, {
+        ...options,
+        headers: {
+            "Content-Type": "application/json",
+            "X-Api-Key": API_KEY,
+            ...(options.headers || {}),
+        },
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Mnemoverse API error ${res.status}: ${text}`);
+    }
+    return res.json();
+}
+// --- Server setup ---
+const server = new McpServer({
+    name: "mnemoverse-memory",
+    version: "0.1.0",
+});
+// --- Tool: memory_write ---
+server.tool("memory_write", "Store a memory — insight, pattern, preference, or fact. Persists across sessions. Use this when the user teaches you something worth remembering, or when you learn a lesson from a task.", {
+    content: z
+        .string()
+        .min(1)
+        .max(10000)
+        .describe("The memory to store — what happened, what was learned"),
+    concepts: z
+        .array(z.string())
+        .optional()
+        .describe("Key concepts for linking related memories (e.g. ['deploy', 'friday', 'staging'])"),
+    domain: z
+        .string()
+        .optional()
+        .describe("Namespace to organize memories (e.g. 'engineering', 'user:alice', 'project:acme')"),
+}, async ({ content, concepts, domain }) => {
+    const result = await apiFetch("/memory/write", {
+        method: "POST",
+        body: JSON.stringify({
+            content,
+            concepts: concepts || [],
+            domain: domain || "general",
+        }),
+    });
+    const r = result;
+    if (r.stored) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Stored (importance: ${r.importance.toFixed(2)}). ID: ${r.atom_id}`,
+                },
+            ],
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Filtered — ${r.reason} (importance: ${r.importance.toFixed(2)})`,
+            },
+        ],
+    };
+});
+// --- Tool: memory_read ---
+server.tool("memory_read", "Search memories by natural language query. Returns the most relevant stored memories. Use this before starting a task to check if you already know something about it.", {
+    query: z
+        .string()
+        .min(1)
+        .max(5000)
+        .describe("Natural language query — what are you looking for?"),
+    top_k: z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .optional()
+        .describe("Max results to return (default: 5)"),
+    domain: z
+        .string()
+        .optional()
+        .describe("Filter by domain namespace"),
+}, async ({ query, top_k, domain }) => {
+    const result = await apiFetch("/memory/read", {
+        method: "POST",
+        body: JSON.stringify({
+            query,
+            top_k: top_k || 5,
+            domain: domain || undefined,
+            include_associations: true,
+        }),
+    });
+    const r = result;
+    if (r.items.length === 0) {
+        return {
+            content: [
+                { type: "text", text: "No memories found for this query." },
+            ],
+        };
+    }
+    const lines = r.items.map((item, i) => `${i + 1}. [${(item.relevance * 100).toFixed(0)}%] ${item.content}` +
+        (item.concepts.length > 0
+            ? ` (${item.concepts.join(", ")})`
+            : ""));
+    return {
+        content: [
+            {
+                type: "text",
+                text: lines.join("\n\n") + `\n\n(${r.search_time_ms.toFixed(0)}ms)`,
+            },
+        ],
+    };
+});
+// --- Tool: memory_feedback ---
+server.tool("memory_feedback", "Report whether a retrieved memory was helpful. Positive feedback makes memories easier to find next time. Negative feedback lets them fade. Call this after using memories from memory_read.", {
+    atom_ids: z
+        .array(z.string())
+        .min(1)
+        .describe("IDs of memories to give feedback on (from memory_read results)"),
+    outcome: z
+        .number()
+        .min(-1)
+        .max(1)
+        .describe("How helpful was this? 1.0 = very helpful, 0 = neutral, -1.0 = harmful/wrong"),
+}, async ({ atom_ids, outcome }) => {
+    const result = await apiFetch("/memory/feedback", {
+        method: "POST",
+        body: JSON.stringify({ atom_ids, outcome }),
+    });
+    const r = result;
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Feedback recorded for ${r.updated_count} memor${r.updated_count === 1 ? "y" : "ies"}.`,
+            },
+        ],
+    };
+});
+// --- Tool: memory_stats ---
+server.tool("memory_stats", "Get memory statistics — how many memories are stored, which domains exist, average quality scores. Useful for understanding the current state of memory.", {}, async () => {
+    const result = await apiFetch("/memory/stats");
+    const r = result;
+    const text = [
+        `Memories: ${r.total_atoms} (${r.episodes} episodes, ${r.prototypes} prototypes)`,
+        `Associations: ${r.hebbian_edges} Hebbian edges`,
+        `Domains: ${r.domains.length > 0 ? r.domains.join(", ") : "general"}`,
+        `Avg quality: valence ${r.avg_valence.toFixed(2)}, importance ${r.avg_importance.toFixed(2)}`,
+    ].join("\n");
+    return { content: [{ type: "text", text }] };
+});
+// --- Start ---
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("MCP server error:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/llms.txt

@@ -0,0 +1,52 @@
+# Mnemoverse MCP Memory Server
+
+> Persistent AI memory via Model Context Protocol. Store and recall memories across sessions.
+
+## Tools
+
+### memory_write
+Store a memory — insight, pattern, preference, or fact. Persists across sessions.
+
+Parameters:
+- content (string, required): The memory to store — what happened, what was learned. 1-10000 chars.
+- concepts (string[], optional): Key concepts for linking related memories. Example: ["deploy", "friday", "staging"]
+- domain (string, optional): Namespace to organize memories. Example: "engineering", "user:alice"
+
+Returns: {stored: boolean, atom_id: string|null, importance: number, reason: string}
+
+### memory_read
+Search memories by natural language query. Returns most relevant stored memories ranked by relevance.
+
+Parameters:
+- query (string, required): Natural language query — what are you looking for? 1-5000 chars.
+- top_k (integer, optional, default 5): Max results to return. Range: 1-50.
+- domain (string, optional): Filter by domain namespace.
+
+Returns: List of memories with relevance scores, concepts, and domain.
+
+### memory_feedback
+Report whether a retrieved memory was helpful. Positive feedback strengthens recall. Negative lets memories fade.
+
+Parameters:
+- atom_ids (string[], required): IDs of memories to give feedback on.
+- outcome (number, required): How helpful? Range: -1.0 (harmful) to 1.0 (very helpful).
+
+Returns: {updated_count: number}
+
+### memory_stats
+Get memory statistics — count, domains, quality scores.
+
+Parameters: none
+
+Returns: {total_atoms, episodes, prototypes, hebbian_edges, domains, avg_valence, avg_importance}
+
+## Setup
+Environment: MNEMOVERSE_API_KEY (required), MNEMOVERSE_API_URL (optional, default https://core.mnemoverse.com/api/v1)
+Transport: stdio
+Command: npx @mnemoverse/mcp-memory-server
+
+## Links
+- Docs: https://mnemoverse.com/docs/api/mcp-server
+- API Reference: https://mnemoverse.com/docs/api/reference
+- Console: https://console.mnemoverse.com
+- Source: https://github.com/mnemoverse/mcp-memory-server

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@mnemoverse/mcp-memory-server",
+  "version": "0.1.0",
+  "description": "MCP server for Mnemoverse Memory API — persistent AI memory across Claude Code, Cursor, VS Code, and any MCP client",
+  "type": "module",
+  "bin": {
+    "mcp-memory-server": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "memory",
+    "ai",
+    "claude",
+    "cursor",
+    "mnemoverse",
+    "persistent-memory",
+    "model-context-protocol"
+  ],
+  "author": "Mnemoverse <hello@mnemoverse.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mnemoverse/mcp-memory-server"
+  },
+  "homepage": "https://mnemoverse.com/docs/api/mcp-server",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3",
+    "@types/node": "^22.15.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/index.ts

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const API_URL =
+  process.env.MNEMOVERSE_API_URL || "https://core.mnemoverse.com/api/v1";
+const API_KEY = process.env.MNEMOVERSE_API_KEY || "";
+
+if (!API_KEY) {
+  console.error(
+    "Error: MNEMOVERSE_API_KEY environment variable is required.\n" +
+      "Get your free key at https://console.mnemoverse.com"
+  );
+  process.exit(1);
+}
+
+async function apiFetch(
+  path: string,
+  options: RequestInit = {}
+): Promise<unknown> {
+  const res = await fetch(`${API_URL}${path}`, {
+    ...options,
+    headers: {
+      "Content-Type": "application/json",
+      "X-Api-Key": API_KEY,
+      ...((options.headers as Record<string, string>) || {}),
+    },
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Mnemoverse API error ${res.status}: ${text}`);
+  }
+
+  return res.json();
+}
+
+// --- Server setup ---
+
+const server = new McpServer({
+  name: "mnemoverse-memory",
+  version: "0.1.0",
+});
+
+// --- Tool: memory_write ---
+
+server.tool(
+  "memory_write",
+  "Store a memory — insight, pattern, preference, or fact. Persists across sessions. Use this when the user teaches you something worth remembering, or when you learn a lesson from a task.",
+  {
+    content: z
+      .string()
+      .min(1)
+      .max(10000)
+      .describe("The memory to store — what happened, what was learned"),
+    concepts: z
+      .array(z.string())
+      .optional()
+      .describe("Key concepts for linking related memories (e.g. ['deploy', 'friday', 'staging'])"),
+    domain: z
+      .string()
+      .optional()
+      .describe("Namespace to organize memories (e.g. 'engineering', 'user:alice', 'project:acme')"),
+  },
+  async ({ content, concepts, domain }) => {
+    const result = await apiFetch("/memory/write", {
+      method: "POST",
+      body: JSON.stringify({
+        content,
+        concepts: concepts || [],
+        domain: domain || "general",
+      }),
+    });
+
+    const r = result as {
+      stored: boolean;
+      atom_id: string | null;
+      importance: number;
+      reason: string;
+    };
+
+    if (r.stored) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Stored (importance: ${r.importance.toFixed(2)}). ID: ${r.atom_id}`,
+          },
+        ],
+      };
+    }
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: `Filtered — ${r.reason} (importance: ${r.importance.toFixed(2)})`,
+        },
+      ],
+    };
+  }
+);
+
+// --- Tool: memory_read ---
+
+server.tool(
+  "memory_read",
+  "Search memories by natural language query. Returns the most relevant stored memories. Use this before starting a task to check if you already know something about it.",
+  {
+    query: z
+      .string()
+      .min(1)
+      .max(5000)
+      .describe("Natural language query — what are you looking for?"),
+    top_k: z
+      .number()
+      .int()
+      .min(1)
+      .max(50)
+      .optional()
+      .describe("Max results to return (default: 5)"),
+    domain: z
+      .string()
+      .optional()
+      .describe("Filter by domain namespace"),
+  },
+  async ({ query, top_k, domain }) => {
+    const result = await apiFetch("/memory/read", {
+      method: "POST",
+      body: JSON.stringify({
+        query,
+        top_k: top_k || 5,
+        domain: domain || undefined,
+        include_associations: true,
+      }),
+    });
+
+    const r = result as {
+      items: Array<{
+        content: string;
+        relevance: number;
+        concepts: string[];
+        domain: string;
+      }>;
+      search_time_ms: number;
+    };
+
+    if (r.items.length === 0) {
+      return {
+        content: [
+          { type: "text" as const, text: "No memories found for this query." },
+        ],
+      };
+    }
+
+    const lines = r.items.map(
+      (item, i) =>
+        `${i + 1}. [${(item.relevance * 100).toFixed(0)}%] ${item.content}` +
+        (item.concepts.length > 0
+          ? ` (${item.concepts.join(", ")})`
+          : "")
+    );
+
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: lines.join("\n\n") + `\n\n(${r.search_time_ms.toFixed(0)}ms)`,
+        },
+      ],
+    };
+  }
+);
+
+// --- Tool: memory_feedback ---
+
+server.tool(
+  "memory_feedback",
+  "Report whether a retrieved memory was helpful. Positive feedback makes memories easier to find next time. Negative feedback lets them fade. Call this after using memories from memory_read.",
+  {
+    atom_ids: z
+      .array(z.string())
+      .min(1)
+      .describe("IDs of memories to give feedback on (from memory_read results)"),
+    outcome: z
+      .number()
+      .min(-1)
+      .max(1)
+      .describe("How helpful was this? 1.0 = very helpful, 0 = neutral, -1.0 = harmful/wrong"),
+  },
+  async ({ atom_ids, outcome }) => {
+    const result = await apiFetch("/memory/feedback", {
+      method: "POST",
+      body: JSON.stringify({ atom_ids, outcome }),
+    });
+
+    const r = result as { updated_count: number };
+
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: `Feedback recorded for ${r.updated_count} memor${r.updated_count === 1 ? "y" : "ies"}.`,
+        },
+      ],
+    };
+  }
+);
+
+// --- Tool: memory_stats ---
+
+server.tool(
+  "memory_stats",
+  "Get memory statistics — how many memories are stored, which domains exist, average quality scores. Useful for understanding the current state of memory.",
+  {},
+  async () => {
+    const result = await apiFetch("/memory/stats");
+
+    const r = result as {
+      total_atoms: number;
+      episodes: number;
+      prototypes: number;
+      hebbian_edges: number;
+      domains: string[];
+      avg_valence: number;
+      avg_importance: number;
+    };
+
+    const text = [
+      `Memories: ${r.total_atoms} (${r.episodes} episodes, ${r.prototypes} prototypes)`,
+      `Associations: ${r.hebbian_edges} Hebbian edges`,
+      `Domains: ${r.domains.length > 0 ? r.domains.join(", ") : "general"}`,
+      `Avg quality: valence ${r.avg_valence.toFixed(2)}, importance ${r.avg_importance.toFixed(2)}`,
+    ].join("\n");
+
+    return { content: [{ type: "text" as const, text }] };
+  }
+);
+
+// --- Start ---
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error("MCP server error:", err);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"]
+}