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;
  }