mcp-prose-memory 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Soroush
+
+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,193 @@
+# mcp-prose-memory
+
+An MCP (Model Context Protocol) server for prose-based persistent memory with markdown storage. Enables LLMs to maintain context across sessions using a structured markdown file.
+
+## Features
+
+- Prose-based memory storage in markdown format
+- Structured sections for organized context
+- YAML frontmatter for metadata
+- Simple tools for reading and updating memory
+- Configurable storage location via environment variable
+
+## Installation
+
+```bash
+npm install -g mcp-prose-memory
+```
+
+Or use directly with npx:
+
+```bash
+npx mcp-prose-memory
+```
+
+## Configuration
+
+### Claude Desktop
+
+Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "npx",
+      "args": ["mcp-prose-memory"]
+    }
+  }
+}
+```
+
+### Claude CLI
+
+Add to your Claude CLI configuration (`~/.claude/mcp-servers.json`):
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "npx",
+      "args": ["mcp-prose-memory"]
+    }
+  }
+}
+```
+
+### Custom Memory Location
+
+By default, memory is stored at `~/.mcp/memory.md`. Override with the `MEMORY_PATH` environment variable:
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "npx",
+      "args": ["mcp-prose-memory"],
+      "env": {
+        "MEMORY_PATH": "/path/to/your/memory.md"
+      }
+    }
+  }
+}
+```
+
+## Document Structure
+
+The memory document uses YAML frontmatter and markdown sections:
+
+```markdown
+---
+version: 2
+updated: 2025-01-15T10:30:00.000Z
+---
+
+## Work Context
+
+Professional context, projects, colleagues, tools.
+
+## Personal Context
+
+Location, preferences, interests, personal facts.
+
+## Top of Mind
+
+Current focuses, active tasks.
+
+## Brief History
+
+Past events, completed work.
+
+## Other Instructions
+
+Standing rules, behavioral preferences.
+```
+
+## Tools
+
+### memory_get
+
+Get the full memory document or a specific section.
+
+**Parameters:**
+- `section` (optional): One of `work`, `personal`, `top_of_mind`, `history`, `instructions`
+
+**Example:**
+```json
+{ "section": "work" }
+```
+
+### memory_update_section
+
+Replace the content of a specific section.
+
+**Parameters:**
+- `section` (required): Section to update
+- `content` (required): New content (prose/markdown)
+
+**Example:**
+```json
+{
+  "section": "personal",
+  "content": "Based in Berlin, Germany. Prefers concise communication."
+}
+```
+
+### memory_remember
+
+Get the current document with guidance for integrating new information. Use this when asked to "remember" something.
+
+**Parameters:**
+- `info` (required): The information to remember
+
+**Example:**
+```json
+{ "info": "User prefers dark mode" }
+```
+
+### memory_context
+
+Get the full memory document for session initialization. Equivalent to `memory_get` without parameters.
+
+### memory_quick_add
+
+Quickly append a fact to a section as a bullet point. More efficient than `memory_remember` + `memory_update_section` for simple facts.
+
+**Parameters:**
+- `section` (required): Section to append to
+- `fact` (required): The fact to add
+
+**Example:**
+```json
+{
+  "section": "personal",
+  "fact": "Prefers tea over coffee"
+}
+```
+
+## Sections
+
+| Section | Purpose |
+|---------|---------|
+| `work` | Professional context, projects, colleagues, tools |
+| `personal` | Location, preferences, interests, personal facts |
+| `top_of_mind` | Current focuses, active tasks |
+| `history` | Past events, completed work |
+| `instructions` | Standing rules, behavioral preferences |
+
+## Development
+
+```bash
+git clone https://github.com/gabrimatic/mcp-prose-memory.git
+cd mcp-prose-memory
+npm install
+npm run build
+```
+
+## Developer
+
+By [Soroush](https://gabrimatic.info)
+
+## License
+
+MIT

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { getSection, updateSection, getFullContext, appendToSection, } from "./store.js";
+const server = new Server({ name: "mcp-prose-memory", version: "1.0.0" }, { capabilities: { tools: {} } });
+const SECTIONS = ["work", "personal", "top_of_mind", "history", "instructions"];
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "memory_get",
+            description: "Get full memory document or a specific section. Use without params for full doc.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    section: {
+                        type: "string",
+                        enum: SECTIONS,
+                        description: "Optional: specific section to retrieve (work|personal|top_of_mind|history|instructions)",
+                    },
+                },
+            },
+        },
+        {
+            name: "memory_update_section",
+            description: "Replace the content of a specific section. Content should be prose/markdown.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    section: {
+                        type: "string",
+                        enum: SECTIONS,
+                        description: "Section to update: work|personal|top_of_mind|history|instructions",
+                    },
+                    content: {
+                        type: "string",
+                        description: "New content for the section (prose/markdown)",
+                    },
+                },
+                required: ["section", "content"],
+            },
+        },
+        {
+            name: "memory_remember",
+            description: "Get current document with hint to integrate new info. Use when asked to 'remember' something.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    info: {
+                        type: "string",
+                        description: "The information to remember (for context)",
+                    },
+                },
+                required: ["info"],
+            },
+        },
+        {
+            name: "memory_context",
+            description: "Get full memory document for session start. Returns the complete markdown file.",
+            inputSchema: {
+                type: "object",
+                properties: {},
+            },
+        },
+        {
+            name: "memory_quick_add",
+            description: "Quickly append a fact to a section. Use for simple 'remember X' requests. More efficient than memory_remember + memory_update_section.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    section: {
+                        type: "string",
+                        enum: SECTIONS,
+                        description: "Section: work|personal|top_of_mind|history|instructions"
+                    },
+                    fact: {
+                        type: "string",
+                        description: "The fact to add (will be appended as a bullet point)"
+                    }
+                },
+                required: ["section", "fact"]
+            }
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case "memory_get": {
+                if (args?.section) {
+                    const sectionType = args.section;
+                    if (!SECTIONS.includes(sectionType)) {
+                        throw new Error(`Invalid section: ${sectionType}`);
+                    }
+                    const content = await getSection(sectionType);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: content || `(${sectionType} section is empty)`,
+                            },
+                        ],
+                    };
+                }
+                const fullDoc = await getFullContext();
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: fullDoc || "(No memory document exists yet)",
+                        },
+                    ],
+                };
+            }
+            case "memory_update_section": {
+                const sectionType = args?.section;
+                const content = args?.content;
+                if (!sectionType || !SECTIONS.includes(sectionType)) {
+                    throw new Error(`Invalid section: ${sectionType}`);
+                }
+                if (!content) {
+                    throw new Error("Content is required");
+                }
+                const doc = await updateSection(sectionType, content);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Updated ${sectionType} section. Document last updated: ${doc.metadata.updated}`,
+                        },
+                    ],
+                };
+            }
+            case "memory_remember": {
+                const info = args?.info;
+                if (!info) {
+                    throw new Error("Info is required");
+                }
+                const fullDoc = await getFullContext();
+                const hint = `
+To integrate this information into memory:
+
+1. Choose the appropriate section:
+   - work: professional context, projects, colleagues, tools
+   - personal: location, preferences, interests, personal facts
+   - top_of_mind: current focuses, active tasks
+   - history: past events, completed work
+   - instructions: standing rules, behavioral preferences
+
+2. Keep content concise and well-organized
+3. Use memory_update_section to save changes
+
+INFO TO REMEMBER: ${info}
+
+CURRENT DOCUMENT:
+${fullDoc || "(empty)"}`;
+                return { content: [{ type: "text", text: hint }] };
+            }
+            case "memory_context": {
+                const fullDoc = await getFullContext();
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: fullDoc || "(No memory document exists yet)",
+                        },
+                    ],
+                };
+            }
+            case "memory_quick_add": {
+                const sectionType = args?.section;
+                const fact = args?.fact;
+                if (!sectionType || !SECTIONS.includes(sectionType)) {
+                    throw new Error(`Invalid section: ${sectionType}`);
+                }
+                if (!fact) {
+                    throw new Error("Fact is required");
+                }
+                await appendToSection(sectionType, fact);
+                return {
+                    content: [{ type: "text", text: `Added to ${sectionType}.` }]
+                };
+            }
+            default:
+                return { content: [{ type: "text", text: `Unknown tool: ${name}` }] };
+        }
+    }
+    catch (e) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${e instanceof Error ? e.message : e}`,
+                },
+            ],
+        };
+    }
+});
+const transport = new StdioServerTransport();
+server.connect(transport).catch(console.error);

package/dist/store.d.ts

@@ -0,0 +1,19 @@
+export type SectionType = "work" | "personal" | "top_of_mind" | "history" | "instructions";
+export interface DocumentMetadata {
+    version: number;
+    updated: string;
+}
+export interface MemoryDocument {
+    metadata: DocumentMetadata;
+    sections: Record<SectionType, string>;
+}
+declare const MEMORY_PATH: string;
+declare const SECTION_HEADERS: Record<SectionType, string>;
+declare const SECTION_ORDER: SectionType[];
+export declare function loadDocument(): Promise<MemoryDocument>;
+export declare function saveDocument(doc: MemoryDocument): Promise<void>;
+export declare function getSection(sectionType: SectionType): Promise<string>;
+export declare function updateSection(sectionType: SectionType, content: string): Promise<MemoryDocument>;
+export declare function getFullContext(): Promise<string>;
+export declare function appendToSection(sectionType: SectionType, fact: string): Promise<void>;
+export { MEMORY_PATH, SECTION_ORDER, SECTION_HEADERS };

package/dist/store.js

@@ -0,0 +1,151 @@
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { existsSync } from "fs";
+import { dirname } from "path";
+import { homedir } from "os";
+const MEMORY_PATH = process.env.MEMORY_PATH || `${homedir()}/.mcp/memory.md`;
+const SECTION_HEADERS = {
+    work: "## Work Context",
+    personal: "## Personal Context",
+    top_of_mind: "## Top of Mind",
+    history: "## Brief History",
+    instructions: "## Other Instructions",
+};
+const SECTION_ORDER = ["work", "personal", "top_of_mind", "history", "instructions"];
+async function ensureDir(path) {
+    const dir = dirname(path);
+    if (!existsSync(dir))
+        await mkdir(dir, { recursive: true });
+}
+function parseYamlFrontmatter(content) {
+    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+    if (!frontmatterMatch) {
+        return {
+            metadata: { version: 2, updated: new Date().toISOString() },
+            body: content,
+        };
+    }
+    const [, yaml, body] = frontmatterMatch;
+    const metadata = { version: 2, updated: new Date().toISOString() };
+    for (const line of yaml.split("\n")) {
+        const match = line.match(/^(\w+):\s*(.+)$/);
+        if (match) {
+            const [, key, value] = match;
+            if (key === "version")
+                metadata.version = parseInt(value, 10);
+            if (key === "updated")
+                metadata.updated = value;
+        }
+    }
+    return { metadata, body };
+}
+function parseSections(body) {
+    const sections = {
+        work: "",
+        personal: "",
+        top_of_mind: "",
+        history: "",
+        instructions: "",
+    };
+    const sectionPattern = /^## (Work Context|Personal Context|Top of Mind|Brief History|Other Instructions)\n/gm;
+    const headerToType = {
+        "Work Context": "work",
+        "Personal Context": "personal",
+        "Top of Mind": "top_of_mind",
+        "Brief History": "history",
+        "Other Instructions": "instructions",
+    };
+    const matches = [];
+    let match;
+    while ((match = sectionPattern.exec(body)) !== null) {
+        const type = headerToType[match[1]];
+        if (type) {
+            matches.push({
+                type,
+                start: match.index,
+                headerEnd: match.index + match[0].length,
+            });
+        }
+    }
+    for (let i = 0; i < matches.length; i++) {
+        const current = matches[i];
+        const nextStart = matches[i + 1]?.start ?? body.length;
+        const content = body.slice(current.headerEnd, nextStart).trim();
+        sections[current.type] = content;
+    }
+    return sections;
+}
+function serializeDocument(doc) {
+    const lines = [
+        "---",
+        `version: ${doc.metadata.version}`,
+        `updated: ${doc.metadata.updated}`,
+        "---",
+        "",
+    ];
+    for (const sectionType of SECTION_ORDER) {
+        lines.push(SECTION_HEADERS[sectionType]);
+        lines.push("");
+        const content = doc.sections[sectionType];
+        if (content) {
+            lines.push(content);
+            lines.push("");
+        }
+    }
+    return lines.join("\n");
+}
+export async function loadDocument() {
+    try {
+        const content = await readFile(MEMORY_PATH, "utf-8");
+        const { metadata, body } = parseYamlFrontmatter(content);
+        const sections = parseSections(body);
+        return { metadata, sections };
+    }
+    catch (e) {
+        if (e.code === "ENOENT") {
+            return {
+                metadata: { version: 2, updated: new Date().toISOString() },
+                sections: {
+                    work: "",
+                    personal: "",
+                    top_of_mind: "",
+                    history: "",
+                    instructions: "",
+                },
+            };
+        }
+        throw e;
+    }
+}
+export async function saveDocument(doc) {
+    doc.metadata.updated = new Date().toISOString();
+    await ensureDir(MEMORY_PATH);
+    await writeFile(MEMORY_PATH, serializeDocument(doc));
+}
+export async function getSection(sectionType) {
+    const doc = await loadDocument();
+    return doc.sections[sectionType];
+}
+export async function updateSection(sectionType, content) {
+    const doc = await loadDocument();
+    doc.sections[sectionType] = content.trim();
+    await saveDocument(doc);
+    return doc;
+}
+export async function getFullContext() {
+    try {
+        return await readFile(MEMORY_PATH, "utf-8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT") {
+            return "";
+        }
+        throw e;
+    }
+}
+export async function appendToSection(sectionType, fact) {
+    const doc = await loadDocument();
+    const existing = doc.sections[sectionType].trim();
+    doc.sections[sectionType] = existing ? `${existing}\n- ${fact.trim()}` : `- ${fact.trim()}`;
+    await saveDocument(doc);
+}
+export { MEMORY_PATH, SECTION_ORDER, SECTION_HEADERS };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "mcp-prose-memory",
+  "version": "1.0.0",
+  "description": "MCP server for prose-based persistent memory with markdown storage",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-prose-memory": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "memory",
+    "claude",
+    "ai",
+    "markdown"
+  ],
+  "author": "Soroush (https://gabrimatic.info)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gabrimatic/mcp-prose-memory.git"
+  },
+  "bugs": {
+    "url": "https://github.com/gabrimatic/mcp-prose-memory/issues"
+  },
+  "homepage": "https://github.com/gabrimatic/mcp-prose-memory#readme"
+}

package/templates/memory.md

@@ -0,0 +1,14 @@
+---
+version: 2
+updated:
+---
+
+## Work Context
+
+## Personal Context
+
+## Top of Mind
+
+## Brief History
+
+## Other Instructions