Memory Bank MCP

Implementation Reference

• src/mcp/memoryBankMcp.ts:64-307 (registration)

  Registration of the initialize_memory_bank tool on the MCP server, including Zod input schema (goal required, geminiApiKey and location optional) and the complete handler function that orchestrates memory bank initialization.

    'initialize_memory_bank',
    {
      goal: z.string().min(10, 'Project goal must be at least 10 characters'),
      geminiApiKey: z.string().optional().describe('Gemini API key (optional)'),
      location: z.string().describe('Absolute path where memory-bank folder will be created')
    },
    async ({ goal, geminiApiKey, location }) => {
      try {
        // Diagnostics: Log environment info
        console.log(`Current working directory: ${process.cwd()}`);
        console.log(`Node version: ${process.version}`);
        console.log(`Platform: ${process.platform}`);
        
        // Determine where to create the memory-bank directory
        let baseDir;
        let memoryBankDir;
        
        if (location) {
          // Use user-specified location as the base directory
          if (path.isAbsolute(location)) {
            // If absolute path is provided, use it directly as base directory
            baseDir = location;
          } else {
            // If relative path is provided, resolve against current working directory
            baseDir = path.resolve(process.cwd(), location);
          }
          console.log(`Using user specified base location: ${baseDir}`);
        } else {
          // If no location provided, use current working directory as base
          baseDir = process.cwd();
          console.log(`No location specified, using current directory as base: ${baseDir}`);
        }
        
        // Create memory-bank directory inside the base directory
        memoryBankDir = path.join(baseDir, 'memory-bank');
        console.log(`Will create Memory Bank structure at: ${memoryBankDir}`);
        
        // Ensure parent directory exists if needed
        const parentDir = path.dirname(memoryBankDir);
        try {
          await fs.ensureDir(parentDir);
          console.log(`Ensured parent directory exists: ${parentDir}`);
        } catch (error) {
          console.error(`Error ensuring parent directory: ${error}`);
          throw new Error(`Cannot create or access parent directory: ${error}`);
        }
        
        // Set global memory bank directory
        MEMORY_BANK_DIR = memoryBankDir;
        
        console.log(`Will create Memory Bank at: ${MEMORY_BANK_DIR}`);
        
        // Ensure memory-bank directory exists before passing to createMemoryBankStructure
        try {
          await fs.ensureDir(MEMORY_BANK_DIR);
          console.log(`Created Memory Bank root directory: ${MEMORY_BANK_DIR}`);
        } catch (error) {
          console.error(`Error creating Memory Bank directory: ${error}`);
          throw new Error(`Cannot create Memory Bank directory: ${error}`);
        }
  
        // Temporarily set the API key if provided
        if (geminiApiKey) {
          process.env.GEMINI_API_KEY = geminiApiKey;
        }
  
        // First, set up the .byterules file before creating other files
        // This ensures the byterules file is in place before other operations
        const byterulesDest = path.join(MEMORY_BANK_DIR, '.byterules');
        
        try {
          // Debug: List all search paths we're going to try
          console.log('Searching for .byterules template file...');
          
          // Get the ESM compatible dirname
          const __filename = fileURLToPath(import.meta.url);
          const __dirname = dirname(__filename);
          console.log(`Current file directory: ${__dirname}`);
          
          // Try multiple possible locations for the .byterules file
          const possiblePaths = [
            path.join(process.cwd(), 'src', 'templates', '.byterules'),          // From current working dir
            path.join(__dirname, '..', 'templates', '.byterules'),               // From mcp dir to templates
            path.join(__dirname, '..', '..', 'src', 'templates', '.byterules'),  // From mcp dir up two levels
            path.join(process.cwd(), 'templates', '.byterules'),                 // Direct templates folder
            path.join(process.cwd(), '.byterules')                               // Root of project
          ];
          
          // Manually create .byterules content as fallback
          const defaultByterules = `# Memory Bank Document Orchestration Standard
  
  ## Directory Validation
  
  Before any operation (create/update/reference/review), ensure you are in the correct project root directory. Specifically:
  
  - A valid Memory Bank system **must contain** this \`.byterules\` file at its root.
  - If this file is missing, halt operations and **navigate to the correct directory** using:
  
  \`\`\`bash
  cd /your/project/root
  \`\`\`
  
  Failing to validate the directory can lead to misplaced or inconsistent documentation.
  
  ---
  
  ## System Overview
  
  Memory Bank is a structured documentation system designed to maintain project knowledge in an organized, accessible format. This \`.byterules\` file serves as the standard guide for how the system works across all projects.
  
  ## Standard Document Types
  
  ### 1. Project Brief (projectbrief.md)
  - **Purpose**: Core document that defines project objectives, scope, and vision
  - **When to Use**: Reference when making any major project decisions
  - **Workflow Step**: Start here; all other documents derive from this foundation
  - **Critical For**: Maintaining alignment with business goals throughout development
  
  ### 2. Product Context (productContext.md)
  - **Purpose**: Documents product functionality from a user perspective
  - **When to Use**: When designing features and establishing requirements
  - **Workflow Step**: Second document in sequence, expands on project brief goals
  - **Critical For**: Ensuring user needs drive technical decisions
  
  ### 3. System Patterns (systemPatterns.md)
  - **Purpose**: Establishes system architecture and component relationships
  - **When to Use**: During system design and when making integration decisions
  - **Workflow Step**: Third document, translates product needs to technical design
  - **Critical For**: Maintaining a coherent and scalable technical architecture
  
  ### 4. Tech Context (techContext.md)
  - **Purpose**: Specifies technology stack and implementation details
  - **When to Use**: During development and when onboarding technical team members
  - **Workflow Step**: Fourth document, makes concrete technology choices
  - **Critical For**: Technical consistency and efficient development
  
  ### 5. Active Context (activeContext.md)
  - **Purpose**: Tracks current tasks, open issues, and development focus
  - **When to Use**: Daily, during planning sessions, and when switching tasks
  - **Workflow Step**: Fifth document, operationalizes the technical approach
  - **Critical For**: Day-to-day execution and short-term planning
  
  ### 6. Progress (progress.md)
  - **Purpose**: Documents completed work, milestones, and project history
  - **When to Use**: After completing significant work or during reviews
  - **Workflow Step**: Ongoing document that records the project journey
  - **Critical For**: Tracking accomplishments and learning from experience
  
  ## Standard Workflows
  
  ### Documentation Sequence
  Always follow this sequence for document creation and reference:
  1. **Project Brief** → Foundation of all project decisions
  2. **Product Context** → User-focused requirements and features
  3. **System Patterns** → Architecture and component design
  4. **Tech Context** → Technology choices and implementation guidelines
  5. **Active Context** → Current work and immediate focus
  6. **Progress** → Historical record and milestone tracking
  
  ### Document Lifecycle Management
  Each document follows a standard lifecycle:
  1. **Creation**: Establish initial content based on project needs
  2. **Reference**: Use document for planning and decision-making
  3. **Update**: Revise when relevant factors change
  4. **Review**: Periodically validate for accuracy and completeness
  5. **Archive**: Maintain as historical reference when superseded
  
  ## Best Practices
  
  ### Document Quality Standards
  - **Clarity**: Write in clear, concise language
  - **Completeness**: Include all relevant information
  - **Consistency**: Use consistent terminology across documents
  - **Structure**: Follow standardized document formats
  - **Granularity**: Balance detail with readability
  - **Traceability**: Link related concepts across documents
  
  ### Document Integration Principles
  - **Vertical Traceability**: Ensure business goals trace to technical implementation
  - **Horizontal Consistency**: Maintain alignment across documents at the same level
  - **Change Impact Analysis**: Update related documents when one changes
  - **Decision Recording**: Document the reasoning behind significant decisions
  
  
  `;
          
          // Try each path and use the first one that exists
          let bytesRulesFound = false;
          
          for (const testPath of possiblePaths) {
            console.log(`Checking path: ${testPath}`);
            
            if (await fs.pathExists(testPath)) {
              console.log(`✓ Found .byterules at: ${testPath}`);
              await fs.copy(testPath, byterulesDest);
              console.log(`Standard .byterules file copied to: ${byterulesDest}`);
              bytesRulesFound = true;
              break;
            } else {
              console.log(`✗ Not found at: ${testPath}`);
            }
          }
          
          // If no .byterules file found, create one with the default content
          if (!bytesRulesFound) {
            console.log('No .byterules template found, creating default');
            await fs.writeFile(byterulesDest, defaultByterules, 'utf-8');
            console.log(`Default .byterules file created at: ${byterulesDest}`);
          }
          
        } catch (error) {
          console.error(`Error setting up .byterules file: ${error}`);
          throw new Error(`Failed to set up .byterules file: ${error}`);
        }
        
        // Now create the full structure
        await createMemoryBankStructure(MEMORY_BANK_DIR);
  
        // Generate document contents
        const documentContents = await generateAllDocuments(goal);
  
        // Save each document
        for (const [docType, content] of Object.entries(documentContents)) {
          const filePath = path.join(MEMORY_BANK_DIR, `${docType}.md`);
          await saveDocument(content, filePath);
        }
  
        return {
          content: [
            { 
              type: 'text', 
              text: `✅ Memory Bank successfully created!\n\nLocation: ${MEMORY_BANK_DIR}\n\nGenerated Documents:\n- projectbrief.md\n- productContext.md\n- systemPatterns.md\n- techContext.md\n- activeContext.md\n- progress.md\n- .byterules` 
            }
          ]
        };
      } catch (error) {
        console.error('Error creating Memory Bank:', error);
        return {
          content: [{ type: 'text', text: `❌ Error: ${error instanceof Error ? error.message : String(error)}` }],
          isError: true
        };
      }
    }
  );

• src/mcp/memoryBankMcp.ts:70-306 (handler)

  The core handler function for executing the tool logic: sets up the memory-bank directory, handles .byterules, imports helpers for structure creation, document generation via Gemini, and saving files.

    async ({ goal, geminiApiKey, location }) => {
      try {
        // Diagnostics: Log environment info
        console.log(`Current working directory: ${process.cwd()}`);
        console.log(`Node version: ${process.version}`);
        console.log(`Platform: ${process.platform}`);
        
        // Determine where to create the memory-bank directory
        let baseDir;
        let memoryBankDir;
        
        if (location) {
          // Use user-specified location as the base directory
          if (path.isAbsolute(location)) {
            // If absolute path is provided, use it directly as base directory
            baseDir = location;
          } else {
            // If relative path is provided, resolve against current working directory
            baseDir = path.resolve(process.cwd(), location);
          }
          console.log(`Using user specified base location: ${baseDir}`);
        } else {
          // If no location provided, use current working directory as base
          baseDir = process.cwd();
          console.log(`No location specified, using current directory as base: ${baseDir}`);
        }
        
        // Create memory-bank directory inside the base directory
        memoryBankDir = path.join(baseDir, 'memory-bank');
        console.log(`Will create Memory Bank structure at: ${memoryBankDir}`);
        
        // Ensure parent directory exists if needed
        const parentDir = path.dirname(memoryBankDir);
        try {
          await fs.ensureDir(parentDir);
          console.log(`Ensured parent directory exists: ${parentDir}`);
        } catch (error) {
          console.error(`Error ensuring parent directory: ${error}`);
          throw new Error(`Cannot create or access parent directory: ${error}`);
        }
        
        // Set global memory bank directory
        MEMORY_BANK_DIR = memoryBankDir;
        
        console.log(`Will create Memory Bank at: ${MEMORY_BANK_DIR}`);
        
        // Ensure memory-bank directory exists before passing to createMemoryBankStructure
        try {
          await fs.ensureDir(MEMORY_BANK_DIR);
          console.log(`Created Memory Bank root directory: ${MEMORY_BANK_DIR}`);
        } catch (error) {
          console.error(`Error creating Memory Bank directory: ${error}`);
          throw new Error(`Cannot create Memory Bank directory: ${error}`);
        }
  
        // Temporarily set the API key if provided
        if (geminiApiKey) {
          process.env.GEMINI_API_KEY = geminiApiKey;
        }
  
        // First, set up the .byterules file before creating other files
        // This ensures the byterules file is in place before other operations
        const byterulesDest = path.join(MEMORY_BANK_DIR, '.byterules');
        
        try {
          // Debug: List all search paths we're going to try
          console.log('Searching for .byterules template file...');
          
          // Get the ESM compatible dirname
          const __filename = fileURLToPath(import.meta.url);
          const __dirname = dirname(__filename);
          console.log(`Current file directory: ${__dirname}`);
          
          // Try multiple possible locations for the .byterules file
          const possiblePaths = [
            path.join(process.cwd(), 'src', 'templates', '.byterules'),          // From current working dir
            path.join(__dirname, '..', 'templates', '.byterules'),               // From mcp dir to templates
            path.join(__dirname, '..', '..', 'src', 'templates', '.byterules'),  // From mcp dir up two levels
            path.join(process.cwd(), 'templates', '.byterules'),                 // Direct templates folder
            path.join(process.cwd(), '.byterules')                               // Root of project
          ];
          
          // Manually create .byterules content as fallback
          const defaultByterules = `# Memory Bank Document Orchestration Standard
  
  ## Directory Validation
  
  Before any operation (create/update/reference/review), ensure you are in the correct project root directory. Specifically:
  
  - A valid Memory Bank system **must contain** this \`.byterules\` file at its root.
  - If this file is missing, halt operations and **navigate to the correct directory** using:
  
  \`\`\`bash
  cd /your/project/root
  \`\`\`
  
  Failing to validate the directory can lead to misplaced or inconsistent documentation.
  
  ---
  
  ## System Overview
  
  Memory Bank is a structured documentation system designed to maintain project knowledge in an organized, accessible format. This \`.byterules\` file serves as the standard guide for how the system works across all projects.
  
  ## Standard Document Types
  
  ### 1. Project Brief (projectbrief.md)
  - **Purpose**: Core document that defines project objectives, scope, and vision
  - **When to Use**: Reference when making any major project decisions
  - **Workflow Step**: Start here; all other documents derive from this foundation
  - **Critical For**: Maintaining alignment with business goals throughout development
  
  ### 2. Product Context (productContext.md)
  - **Purpose**: Documents product functionality from a user perspective
  - **When to Use**: When designing features and establishing requirements
  - **Workflow Step**: Second document in sequence, expands on project brief goals
  - **Critical For**: Ensuring user needs drive technical decisions
  
  ### 3. System Patterns (systemPatterns.md)
  - **Purpose**: Establishes system architecture and component relationships
  - **When to Use**: During system design and when making integration decisions
  - **Workflow Step**: Third document, translates product needs to technical design
  - **Critical For**: Maintaining a coherent and scalable technical architecture
  
  ### 4. Tech Context (techContext.md)
  - **Purpose**: Specifies technology stack and implementation details
  - **When to Use**: During development and when onboarding technical team members
  - **Workflow Step**: Fourth document, makes concrete technology choices
  - **Critical For**: Technical consistency and efficient development
  
  ### 5. Active Context (activeContext.md)
  - **Purpose**: Tracks current tasks, open issues, and development focus
  - **When to Use**: Daily, during planning sessions, and when switching tasks
  - **Workflow Step**: Fifth document, operationalizes the technical approach
  - **Critical For**: Day-to-day execution and short-term planning
  
  ### 6. Progress (progress.md)
  - **Purpose**: Documents completed work, milestones, and project history
  - **When to Use**: After completing significant work or during reviews
  - **Workflow Step**: Ongoing document that records the project journey
  - **Critical For**: Tracking accomplishments and learning from experience
  
  ## Standard Workflows
  
  ### Documentation Sequence
  Always follow this sequence for document creation and reference:
  1. **Project Brief** → Foundation of all project decisions
  2. **Product Context** → User-focused requirements and features
  3. **System Patterns** → Architecture and component design
  4. **Tech Context** → Technology choices and implementation guidelines
  5. **Active Context** → Current work and immediate focus
  6. **Progress** → Historical record and milestone tracking
  
  ### Document Lifecycle Management
  Each document follows a standard lifecycle:
  1. **Creation**: Establish initial content based on project needs
  2. **Reference**: Use document for planning and decision-making
  3. **Update**: Revise when relevant factors change
  4. **Review**: Periodically validate for accuracy and completeness
  5. **Archive**: Maintain as historical reference when superseded
  
  ## Best Practices
  
  ### Document Quality Standards
  - **Clarity**: Write in clear, concise language
  - **Completeness**: Include all relevant information
  - **Consistency**: Use consistent terminology across documents
  - **Structure**: Follow standardized document formats
  - **Granularity**: Balance detail with readability
  - **Traceability**: Link related concepts across documents
  
  ### Document Integration Principles
  - **Vertical Traceability**: Ensure business goals trace to technical implementation
  - **Horizontal Consistency**: Maintain alignment across documents at the same level
  - **Change Impact Analysis**: Update related documents when one changes
  - **Decision Recording**: Document the reasoning behind significant decisions
  
  
  `;
          
          // Try each path and use the first one that exists
          let bytesRulesFound = false;
          
          for (const testPath of possiblePaths) {
            console.log(`Checking path: ${testPath}`);
            
            if (await fs.pathExists(testPath)) {
              console.log(`✓ Found .byterules at: ${testPath}`);
              await fs.copy(testPath, byterulesDest);
              console.log(`Standard .byterules file copied to: ${byterulesDest}`);
              bytesRulesFound = true;
              break;
            } else {
              console.log(`✗ Not found at: ${testPath}`);
            }
          }
          
          // If no .byterules file found, create one with the default content
          if (!bytesRulesFound) {
            console.log('No .byterules template found, creating default');
            await fs.writeFile(byterulesDest, defaultByterules, 'utf-8');
            console.log(`Default .byterules file created at: ${byterulesDest}`);
          }
          
        } catch (error) {
          console.error(`Error setting up .byterules file: ${error}`);
          throw new Error(`Failed to set up .byterules file: ${error}`);
        }
        
        // Now create the full structure
        await createMemoryBankStructure(MEMORY_BANK_DIR);
  
        // Generate document contents
        const documentContents = await generateAllDocuments(goal);
  
        // Save each document
        for (const [docType, content] of Object.entries(documentContents)) {
          const filePath = path.join(MEMORY_BANK_DIR, `${docType}.md`);
          await saveDocument(content, filePath);
        }
  
        return {
          content: [
            { 
              type: 'text', 
              text: `✅ Memory Bank successfully created!\n\nLocation: ${MEMORY_BANK_DIR}\n\nGenerated Documents:\n- projectbrief.md\n- productContext.md\n- systemPatterns.md\n- techContext.md\n- activeContext.md\n- progress.md\n- .byterules` 
            }
          ]
        };
      } catch (error) {
        console.error('Error creating Memory Bank:', error);
        return {
          content: [{ type: 'text', text: `❌ Error: ${error instanceof Error ? error.message : String(error)}` }],
          isError: true
        };
      }
    }

• src/utils/gemini.ts:109-189 (helper)

  Supporting utility that generates initial content for all memory bank documents using the Gemini API based on the project goal.

  export async function generateAllDocuments(goal: string): Promise<Record<string, string>> {
    const currentDate = new Date().toLocaleDateString('tr-TR');
    
    const basePrompt = `
  You are a project documentation expert. You will create comprehensive documentation for the following project:
  
  PROJECT PURPOSE: ${goal}
  
  Create the following documents for this project:
  `;
  
    const documentTypes = {
      projectbrief: `
  1. Project Brief (projectbrief.md):
     - Explain the general purpose and vision of the project
     - List the main objectives
     - Define the target audience
     - Specify key features
     - Determine success criteria
     - Present a realistic timeline`,
      
      productContext: `
  2. Product Context (productContext.md):
     - Conduct market analysis
     - Evaluate competitive landscape
     - Write user stories
     - List requirements
     - Explain workflows
     - Define product roadmap`,
      
      systemPatterns: `
  3. System Patterns (systemPatterns.md):
     - Explain architectural design
     - Define data models
     - Specify API definitions
     - Show component structure
     - List integration points
     - Explain scalability strategy`,
      
      techContext: `
  4. Technology Context (techContext.md):
     - List technologies used
     - Specify software development tools
     - Define development environment
     - Explain testing strategy
     - Define deployment process
     - Explain continuous integration approach`,
      
      activeContext: `
  5. Active Context (activeContext.md):
     - Explain current sprint goals
     - List ongoing tasks
     - Specify known issues
     - Define priorities
     - Explain next steps
     - Add meeting notes`,
      
      progress: `
  6. Progress Report (progress.md):
     - List completed tasks
     - Specify milestones
     - Report test results
     - Show performance metrics
     - Summarize feedback
     - Maintain a changelog`
    };
    
  
    const results: Record<string, string> = {};
  
    for (const [docType, docPrompt] of Object.entries(documentTypes)) {
      console.log(`Creating ${docType} document...`);
      
      const fullPrompt = `${basePrompt}${docPrompt}\n\nPlease create content only for the "${docType}" document. Use Markdown format with section headers marked by ##. At the end of the document, add the note "Created on ${currentDate}".`;
      
      const content = await generateContent(fullPrompt);
      results[docType] = content;
    }
  
    return results;
  }

• src/utils/fileManager.ts:8-64 (helper)

  Helper function called by handler to create the memory bank directory structure and README.md file.

  export async function createMemoryBankStructure(outputDir: string): Promise<void> {
    try {
      console.log(`Creating Memory Bank structure in existing directory: ${outputDir}`);
      
      // Verify directory exists
      if (!await fs.pathExists(outputDir)) {
        console.warn(`Directory does not exist: ${outputDir}, will create it`);
        await fs.ensureDir(outputDir);
      }
      
      // No subdirectories needed - using a flat structure for simplicity
      console.log(`Using flat structure for Memory Bank in "${outputDir}"`);
      
      // Create a README.md file with component descriptions
      const readmePath = path.join(outputDir, 'README.md');
      const readmeContent = `# Memory Bank
  
  This directory serves as a structured repository for your project information and notes.
  
  ## Directory Structure
  - **resources**: Images, diagrams, and other resources
  - **temp**: Temporary files and drafts
  - **archive**: Archived documents
  - **references**: Reference materials and documentation
  
  ## Core Documents
  - **projectbrief.md**: Project goals, scope, and vision
  - **productContext.md**: Product features, user stories, and market context
  - **systemPatterns.md**: System architecture, design patterns, and component structure
  - **techContext.md**: Technology stack, frameworks, and technical specifications
  - **activeContext.md**: Active tasks, current sprint, and in-progress work
  - **progress.md**: Progress tracking, milestones, and project history
  
  ## Document Management
  This Memory Bank uses a structured approach to organize project knowledge. Each document serves a specific purpose in the project lifecycle and should be maintained according to the rules specified in the \`.byterules\` file.
  
  See the \`.byterules\` file for detailed guidelines on how to maintain and update these documents.
  `;
      try {
        await fs.writeFile(readmePath, readmeContent, 'utf-8');
        console.log(`README file created at: ${readmePath}`);
      } catch (error) {
        const err = error as any;
        console.error(`Error creating README file: ${err.code} - ${err.message}`);
        // Continue without README
      }
      
      console.log(`Memory Bank structure successfully created in "${outputDir}".`);
    } catch (error) {
      console.error(`Error creating directory structure at ${outputDir}:`, error);
      if (error instanceof Error) {
        throw new Error(`Failed to create Memory Bank structure: ${error.message} (Code: ${(error as any).code || 'UNKNOWN'})`);
      } else {
        throw new Error(`Failed to create Memory Bank structure: Unknown error`);
      }
    }
  }

• src/utils/fileManager.ts:71-84 (helper)

  Helper function used in loop to save each generated document to its .md file.

  export async function saveDocument(content: string, filePath: string): Promise<void> {
    try {
      // Ensure directory exists
      await fs.ensureDir(path.dirname(filePath));
      
      // Write file
      await fs.writeFile(filePath, content, 'utf-8');
      
      console.log(`Document saved: ${filePath}`);
    } catch (error) {
      console.error('Error saving document:', error);
      throw new Error(`Failed to save document: ${error}`);
    }
  }