@more-md/mcp-memory 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ugur Cekmez and more.md contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# @more-md/mcp-memory
+
+Portable long-term memory for AI assistants — as an **MCP server**.
+
+Connect it once and your assistant can remember things across chats, and the
+same memory follows you from Claude to Cursor to any other MCP-capable
+assistant. You hold the key (a short PIN); the memory is encrypted at rest and
+lives at a URL you control ([mem.more.md](https://mem.more.md)).
+
+## Why an MCP server (and not "just give the AI a URL")?
+
+Telling a chat model to *"fetch this URL and use it as your memory"* is the
+exact shape of a prompt‑injection attack — a web page telling the assistant to
+persist your data somewhere. Well‑aligned models refuse it, and they're right
+to.
+
+An MCP server flips that around:
+
+- **You** add this server to your assistant's config (with your memory URL +
+  PIN). That explicit, user‑performed connection is the authorization.
+- The assistant calls **typed tools** (`remember`, `recall`) — it never treats
+  a fetched web page as instructions.
+- Every call is HTTPS, authed with your PIN. Your data goes only to the memory
+  URL you configured.
+
+## Get your memory URL + PIN
+
+Visit **https://mem.more.md** (or ask any assistant that already minted a
+session for you). You'll get a URL like `https://mem.more.md/AbC12xyz` and a
+4‑digit PIN. Keep them — that pair is your portable memory.
+
+## Connect it
+
+### Claude Desktop / Claude Code / Cursor (and most MCP clients)
+
+Add this to your MCP config (`claude_desktop_config.json`, `.cursor/mcp.json`,
+`.mcp.json`, …). Once published to npm:
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "npx",
+      "args": ["-y", "@more-md/mcp-memory"],
+      "env": {
+        "MEM_URL": "https://mem.more.md/AbC12xyz",
+        "MEM_PIN": "1234"
+      }
+    }
+  }
+}
+```
+
+Running from a local checkout instead:
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "node",
+      "args": ["/absolute/path/to/packages/mcp-memory/dist/index.js"],
+      "env": { "MEM_URL": "https://mem.more.md/AbC12xyz", "MEM_PIN": "1234" }
+    }
+  }
+}
+```
+
+Restart the client. You'll see a `memory` server with three tools.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `remember` | Save a memory (`title`, `body`, `memory_type`: episodic/semantic, `importance` 1‑10). |
+| `recall` | Search your memory by keyword or meaning before answering about the past. |
+| `recall_day` | Read everything saved on a given calendar day. |
+
+The assistant decides when to call these — a good one saves durable facts
+(your name, preferences, projects) as `semantic` and checks `recall` before
+answering questions about earlier context. You can always tell it to save or
+forget something specific.
+
+## Privacy
+
+- Encrypted at rest; reachable only with your PIN.
+- Export or delete everything anytime (`/export`, delete tools/endpoints).
+- Open source. Nothing is stored that you didn't ask for.
+
+## Develop
+
+```bash
+npm install
+npm run build      # → dist/
+npm test           # unit tests (mocked fetch)
+```
+
+MIT © more.md

package/dist/client.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Thin, dependency-free client over the mem.more.md REST API. Kept separate
+ * from the MCP wiring so the request/response mapping is unit-testable with a
+ * mocked `fetch` — no MCP transport needed.
+ *
+ * Auth model (this is the whole trust story): the USER puts their memory URL +
+ * PIN in their MCP client config. That explicit, user-performed connection is
+ * the authorization — the assistant never fetches an arbitrary URL and follows
+ * its contents. It calls typed tools that hit exactly these endpoints with the
+ * PIN the user provided.
+ */
+export interface MemConfig {
+    /** Full memory URL including the short code, e.g. https://mem.more.md/AbC12xyz */
+    memUrl: string;
+    /** The user's 4-digit PIN (or longer). Sent as X-Mem-PIN. */
+    pin: string;
+    /** Injectable for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+export type MemoryType = "episodic" | "semantic";
+export interface RememberInput {
+    title: string;
+    body: string;
+    memoryType?: MemoryType;
+    importance?: number;
+}
+export declare class MemError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+/** Normalize the configured URL to `<origin>/<shortCode>` with no trailing slash. */
+export declare function normalizeMemUrl(raw: string): string;
+export declare function createMemClient(cfg: MemConfig): {
+    base: string;
+    /** Save one memory entry. Wraps POST /entries. */
+    remember(input: RememberInput): Promise<{
+        shortCode?: string;
+    }>;
+    /** Search memories by keyword/meaning. Wraps GET /entries?q= */
+    recall(query: string, limit?: number): Promise<unknown>;
+    /** Read every entry from a given day. Wraps GET /:y/:m/:d */
+    recallDay(year: number, month: number, day: number): Promise<unknown>;
+};
+export type MemClient = ReturnType<typeof createMemClient>;

package/dist/client.js

@@ -0,0 +1,100 @@
+/**
+ * Thin, dependency-free client over the mem.more.md REST API. Kept separate
+ * from the MCP wiring so the request/response mapping is unit-testable with a
+ * mocked `fetch` — no MCP transport needed.
+ *
+ * Auth model (this is the whole trust story): the USER puts their memory URL +
+ * PIN in their MCP client config. That explicit, user-performed connection is
+ * the authorization — the assistant never fetches an arbitrary URL and follows
+ * its contents. It calls typed tools that hit exactly these endpoints with the
+ * PIN the user provided.
+ */
+export class MemError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "MemError";
+    }
+}
+/** Normalize the configured URL to `<origin>/<shortCode>` with no trailing slash. */
+export function normalizeMemUrl(raw) {
+    const trimmed = raw.trim().replace(/\/+$/, "");
+    if (!/^https?:\/\//i.test(trimmed)) {
+        throw new MemError(`MEM_URL must be a full https URL like https://mem.more.md/<code> (got "${raw}")`);
+    }
+    return trimmed;
+}
+export function createMemClient(cfg) {
+    const base = normalizeMemUrl(cfg.memUrl);
+    const pin = cfg.pin.trim();
+    const doFetch = cfg.fetchImpl ?? fetch;
+    if (!pin)
+        throw new MemError("MEM_PIN is required.");
+    async function call(path, init) {
+        const res = await doFetch(`${base}${path}`, {
+            ...init,
+            headers: {
+                "X-Mem-PIN": pin,
+                Accept: "application/json",
+                ...(init.headers ?? {}),
+            },
+        });
+        const text = await res.text();
+        let json = undefined;
+        try {
+            json = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            /* non-JSON body */
+        }
+        if (!res.ok) {
+            const msg = (json && typeof json === "object" && "error" in json
+                ? String(json.error)
+                : "") || `Memory request failed (HTTP ${res.status}).`;
+            throw new MemError(msg, res.status);
+        }
+        return json;
+    }
+    return {
+        base,
+        /** Save one memory entry. Wraps POST /entries. */
+        async remember(input) {
+            const title = input.title?.trim();
+            const bodyText = input.body?.trim();
+            if (!title)
+                throw new MemError("A short `title` is required to save a memory.");
+            if (!bodyText)
+                throw new MemError("A `body` is required to save a memory.");
+            const payload = {
+                title,
+                body: bodyText,
+                memory_type: input.memoryType ?? "episodic",
+                ...(typeof input.importance === "number"
+                    ? { importance: Math.max(1, Math.min(10, Math.round(input.importance))) }
+                    : {}),
+            };
+            const out = (await call("/entries", {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(payload),
+            }));
+            return { shortCode: out?.entry?.short_code };
+        },
+        /** Search memories by keyword/meaning. Wraps GET /entries?q= */
+        async recall(query, limit = 10) {
+            const q = query?.trim();
+            const params = new URLSearchParams();
+            if (q)
+                params.set("q", q);
+            params.set("limit", String(Math.max(1, Math.min(50, limit))));
+            return call(`/entries?${params.toString()}`, { method: "GET" });
+        },
+        /** Read every entry from a given day. Wraps GET /:y/:m/:d */
+        async recallDay(year, month, day) {
+            const mm = String(month).padStart(2, "0");
+            const dd = String(day).padStart(2, "0");
+            return call(`/${year}/${mm}/${dd}`, { method: "GET" });
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * @more-md/mcp-memory — portable long-term memory for AI assistants, as an MCP
+ * server.
+ *
+ * WHY THIS EXISTS (the trust story): asking a chat model to "fetch a URL and
+ * use it as memory" is the exact shape of a prompt-injection attack, so aligned
+ * models refuse it — correctly. The safe path is an MCP tool the USER connects
+ * explicitly: the user puts their memory URL + PIN in their client config, that
+ * connection IS the authorization, and the assistant calls typed tools
+ * (`remember` / `recall`) instead of following instructions off a web page.
+ *
+ * Configure it in any MCP client (Claude Desktop, Cursor, Claude Code, …):
+ *
+ *   {
+ *     "mcpServers": {
+ *       "memory": {
+ *         "command": "npx",
+ *         "args": ["-y", "@more-md/mcp-memory"],
+ *         "env": {
+ *           "MEM_URL": "https://mem.more.md/<your-code>",
+ *           "MEM_PIN": "<your-pin>"
+ *         }
+ *       }
+ *     }
+ *   }
+ *
+ * Get MEM_URL + MEM_PIN at https://mem.more.md (or from any assistant that
+ * minted a session for you).
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type MemClient } from "./client.js";
+export declare function buildServer(client: MemClient): McpServer;

package/dist/index.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+/**
+ * @more-md/mcp-memory — portable long-term memory for AI assistants, as an MCP
+ * server.
+ *
+ * WHY THIS EXISTS (the trust story): asking a chat model to "fetch a URL and
+ * use it as memory" is the exact shape of a prompt-injection attack, so aligned
+ * models refuse it — correctly. The safe path is an MCP tool the USER connects
+ * explicitly: the user puts their memory URL + PIN in their client config, that
+ * connection IS the authorization, and the assistant calls typed tools
+ * (`remember` / `recall`) instead of following instructions off a web page.
+ *
+ * Configure it in any MCP client (Claude Desktop, Cursor, Claude Code, …):
+ *
+ *   {
+ *     "mcpServers": {
+ *       "memory": {
+ *         "command": "npx",
+ *         "args": ["-y", "@more-md/mcp-memory"],
+ *         "env": {
+ *           "MEM_URL": "https://mem.more.md/<your-code>",
+ *           "MEM_PIN": "<your-pin>"
+ *         }
+ *       }
+ *     }
+ *   }
+ *
+ * Get MEM_URL + MEM_PIN at https://mem.more.md (or from any assistant that
+ * minted a session for you).
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { createMemClient, MemError } from "./client.js";
+function loadConfig() {
+    const memUrl = (process.env.MEM_URL ?? "").trim();
+    const pin = (process.env.MEM_PIN ?? "").trim();
+    if (!memUrl || !pin) {
+        process.stderr.write("[more-md-memory] Missing config. Set MEM_URL (https://mem.more.md/<code>) and MEM_PIN " +
+            "in your MCP client's `env`. Get them at https://mem.more.md.\n");
+        process.exit(1);
+    }
+    return { memUrl, pin };
+}
+function ok(text) {
+    return { content: [{ type: "text", text }] };
+}
+function fail(err) {
+    const msg = err instanceof MemError
+        ? err.message
+        : err instanceof Error
+            ? err.message
+            : String(err);
+    return { content: [{ type: "text", text: `Memory error: ${msg}` }], isError: true };
+}
+export function buildServer(client) {
+    const server = new McpServer({ name: "more-md-memory", version: "0.1.0" });
+    server.tool("remember", "Save a memory to the user's portable store so it survives across chats and assistants. " +
+        "Use for durable facts (name, preferences, projects → memory_type 'semantic') and for " +
+        "notable moments in the conversation (memory_type 'episodic'). Skip anything the user " +
+        "marked private or that looks like a password or secret.", {
+        title: z.string().min(1).describe("A short 5-10 word summary of what to remember."),
+        body: z.string().min(1).describe("The detail to store, in a sentence or two."),
+        memory_type: z
+            .enum(["episodic", "semantic"])
+            .default("episodic")
+            .describe("'semantic' for durable facts about the user; 'episodic' for events/turns."),
+        importance: z
+            .number()
+            .min(1)
+            .max(10)
+            .optional()
+            .describe("1-10; use 8+ for durable facts you'll want to resurface later."),
+    }, async ({ title, body, memory_type, importance }) => {
+        try {
+            await client.remember({ title, body, memoryType: memory_type, importance });
+            return ok(`Saved to memory: "${title}".`);
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.tool("recall", "Search the user's portable memory before answering anything that refers to the past or to " +
+        "durable facts about them. Returns matching entries (most relevant first).", {
+        query: z.string().describe("What to look for (keywords or a natural-language phrase)."),
+        limit: z.number().min(1).max(50).default(10).describe("Max entries to return."),
+    }, async ({ query, limit }) => {
+        try {
+            const res = await client.recall(query, limit);
+            return ok(JSON.stringify(res, null, 2));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.tool("recall_day", "Read every memory entry saved on a specific calendar day (the user's store is organized by " +
+        "date). Useful for 'what did we do on <date>' questions.", {
+        year: z.number().int().describe("Full year, e.g. 2026."),
+        month: z.number().int().min(1).max(12).describe("Month 1-12."),
+        day: z.number().int().min(1).max(31).describe("Day of month 1-31."),
+    }, async ({ year, month, day }) => {
+        try {
+            const res = await client.recallDay(year, month, day);
+            return ok(JSON.stringify(res, null, 2));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    return server;
+}
+async function main() {
+    const cfg = loadConfig();
+    const client = createMemClient({ memUrl: cfg.memUrl, pin: cfg.pin });
+    const server = buildServer(client);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write(`[more-md-memory] connected · ${client.base}\n`);
+}
+// Only run when invoked as the entry point (tests import buildServer directly).
+const isEntry = typeof process !== "undefined" &&
+    Array.isArray(process.argv) &&
+    /mcp-memory[\\/](dist|src)[\\/]index\.(js|ts)$/.test(process.argv[1] ?? "");
+if (isEntry) {
+    main().catch((err) => {
+        process.stderr.write(`[more-md-memory] fatal: ${String(err)}\n`);
+        process.exit(1);
+    });
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+    "name": "@more-md/mcp-memory",
+    "version": "0.1.0",
+    "description": "Portable long-term memory for AI assistants, as an MCP server. Connect Claude Desktop, Cursor, or any MCP client to a mem.more.md memory the user controls.",
+    "type": "module",
+    "bin": {
+        "more-md-memory": "dist/index.js"
+    },
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist/",
+        "README.md",
+        "LICENSE"
+    ],
+    "engines": {
+        "node": ">=20"
+    },
+    "scripts": {
+        "build": "tsc -p tsconfig.json",
+        "typecheck": "tsc --noEmit -p tsconfig.json",
+        "test": "vitest run",
+        "start": "node dist/index.js",
+        "prepublishOnly": "npm run build"
+    },
+    "keywords": [
+        "mcp",
+        "model-context-protocol",
+        "memory",
+        "more.md",
+        "mem.more.md",
+        "ai",
+        "claude",
+        "cursor"
+    ],
+    "author": "Ugur Cekmez <hello@more.md>",
+    "license": "MIT",
+    "homepage": "https://mem.more.md",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/more-md/monorepo.git",
+        "directory": "packages/mcp-memory"
+    },
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.25.3",
+        "zod": "^4.3.6"
+    },
+    "devDependencies": {
+        "typescript": "^5",
+        "vitest": "^3",
+        "@types/node": "^22"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}