mcp-structured-memory

Instructions

Implementation Reference

• src/tools/createMemory.ts:4-80 (handler)

  The core handler function `createMemoryTool` that executes the `create_memory` tool: validates input, sanitizes name to ID, checks for existence, generates or uses content, creates and saves Memory object, returns user instructions.
  export async function createMemoryTool( storageManager: StorageManager, args: any ): Promise<any> { const params = args as CreateMemoryParams; if (!params.name) { throw new Error("Memory document name is required"); } // Generate memory ID from name (sanitize for filename) const memoryId = params.name .toLowerCase() .replace(/[^a-z0-9\s-]/g, "") .replace(/\s+/g, "-") .replace(/-+/g, "-") .trim(); if (!memoryId) { throw new Error("Name must contain at least some alphanumeric characters"); } // Check if memory already exists const existing = await storageManager.readMemory(memoryId); if (existing) { throw new Error(`Memory document with ID '${memoryId}' already exists`); } // Handle content - either use provided content or generate basic structure const title = params.name; let content = ""; if (params.content && params.content.trim()) { // Use provided content directly (full markdown content) content = params.content; } else { // Generate basic structure with title and placeholder content = `# ${title}\n\n## Notes\n\n[Add your notes and organize into sections as needed]`; } // Create memory object const memory: Memory = { metadata: { id: memoryId, created: new Date().toISOString(), updated: new Date().toISOString(), tags: [], status: "active", }, content: content, filePath: "", }; // Save to storage await storageManager.writeMemory(memory); return { content: [ { type: "text", text: `SHOW THIS TO THE USER - Successfully created memory document: "${params.name}" 🚨 **PROJECT SETUP REQUIRED - MEMORY WILL NOT WORK OTHERWISE** 🚨 The memory "${params.name}" has been created but needs to be integrated into your project workflow. **Add these instructions to your project context:** \`\`\` At the start of each conversation, check the project memory "${params.name}" using get_full_memory. Automatically update the memory as you learn new information using add_to_list or update_section. \`\`\` ⚠️ **The memory will be unused until you add these instructions to your project context.**`, }, ], }; }
• src/index.ts:259-260 (registration)

  Tool dispatch in the CallToolRequestSchema handler switch statement, calling the createMemoryTool.
  case "create_memory": return await createMemoryTool(storageManager, args);
• src/index.ts:10-10 (registration)

  Import of the createMemoryTool handler function.
  import { createMemoryTool } from "./tools/createMemory.js";
• src/index.ts:41-58 (registration)

  Tool registration in ListToolsRequestSchema: name, description, and inputSchema for 'create_memory'.
  name: "create_memory", description: "Create a new structured memory document with optional initial content. IMPORTANT: After using this tool, you MUST show the user the complete installation instructions returned by the tool - the memory will not work without proper MCP server setup and project context configuration.", inputSchema: { type: "object", properties: { name: { type: "string", description: "Unique identifier/name for this memory", }, content: { type: "string", description: "Optional initial content for the memory document. Can be brief context (e.g., 'planning a trip to Japan') or full Markdown content. Focus on capturing what you've learned FROM the user (their preferences, requirements, decisions) rather than generating extensive AI content.", }, }, required: ["name"], }, },
• src/types/memory.ts:31-34 (schema)

  Type definition for CreateMemoryParams used in the handler for input validation.
  export interface CreateMemoryParams { name: string; content?: string; }