Memory Bank

Overview

Issue: AI Memory Loss

AI assistants like VJSP face a fundamental limitation: they reset completely between sessions. This memory loss means project architecture, objectives, technologies, and current status must be re-explained with every new conversation. This creates a critical efficiency dilemma: the AI model either edits without a proper understanding of the project (leading to errors and inconsistent solutions) or must spend significant time and resources analyzing the entire codebase in each session—a process that is both costly and slow for large-scale projects.

Without solving this memory problem, AI assistants remain powerful yet stateless tools, unable to act as true continuous development partners.

Solution: Memory Bank

Memory Bank is a structured documentation system that enables VJSP to better understand your project and preserve context across coding sessions. It transforms your AI assistant from a stateless tool into a persistent development partner with perfect project recall. VJSP automatically reads your Memory Bank files at the start of every new session to reconstruct its understanding of the project.

When Memory Bank is active, VJSP displays [Memory Bank: Active] at the beginning of each task and provides a brief summary of your project context, ensuring consistency without repetitive explanations.

Key Advantages

• Language-agnostic: Works with any programming language or framework
• Efficient project comprehension: Helps VJSP grasp project purpose and tech stack
• Context persistence: Maintains project knowledge across sessions without file scanning in every new conversation
• Faster onboarding: VJSP gains immediate project context at the start of new sessions
• Self-documenting projects: Generates valuable documentation as a byproduct

How Memory Bank Works

Memory Bank is built on VJSP's Custom Rules feature, providing a dedicated framework for project documentation. Memory Bank files are standard Markdown files stored in the .vjsp/rules/memory-bank directory of your project repository. They are not hidden or proprietary—they are regular documentation files accessible to both you and VJSP.

At the start of each task, VJSP reads all Memory Bank files to build a comprehensive understanding of the project. This process is fully automated and requires no action from you. VJSP then displays [Memory Bank: Active] at the start of its response, indicating successful activation, and briefly summarizes its project understanding.

Files are organized hierarchically to build a complete view of the project:

Core Memory Bank Files

brief.md

Manually created and maintained by you

• Project fundamentals
• High-level project overview
• Core requirements and objectives

Example: "Build a React inventory management system with barcode scanning functionality. The system needs to support multiple warehouses and integrate with our existing ERP system."

Note: VJSP does not edit this file directly but may suggest improvements if it identifies ways to enhance the project summary.

product.md

• Explains the project's raison d'être
• Describes the problem being solved
• Outlines how the product should function
• User experience objectives

Example: "The inventory system supports multiple warehouses and real-time updates. It solves inventory discrepancy issues by providing barcode scanning to ensure accurate stock counts."

context.md

• The most frequently updated file
• Contains current work priorities and recent changes
• Tracks active decisions and considerations
• Next steps in development

Example: "Barcode scanning component is currently being implemented; API integration was completed in the last session. Next steps include adding error handling for network failures."

architecture.md

• Documents system architecture
• Records key technical decisions
• Lists design patterns in use
• Explains component relationships
• Critical implementation pathways

Example: "Redux is used for state management with a normalized store structure. The application follows a modular architecture, with API communication, state management, and UI components housed in separate services."

tech.md

• Lists technologies and frameworks in use
• Describes development setup
• Documents technical constraints
• Records dependencies and tool configurations
• Tool usage patterns

Example: "React 18, TypeScript, Firebase, and Jest for testing. Development requires Node.js 16+ and uses Vite as the build tool."

Additional Context Files

Create additional files as needed to organize:

• Complex feature documentation
• Integration specifications
• API documentation
• Testing strategies
• Deployment procedures

These supplementary files help organize more detailed information that does not fit into the core files.

tasks.md

Optional file for documenting repetitive tasks

• Stores workflows for tasks that follow similar patterns
• Records files that need modification
• Documents step-by-step procedures
• Notes important considerations and pitfalls

Examples: Adding support for new AI models, implementing API endpoints, or any task that requires repeating similar work.

Getting Started with Memory Bank

Initial Setup

1. Create the .vjsp/rules/memory-bank/ directory in your project
2. Write a basic project summary in .vjsp/rules/memory-bank/brief.md
3. Create the file .vjsp/rules/memory-bank-instructions.md
4. Switch to Architect mode
5. Verify that the best available AI model is selected—do not use lightweight models
6. Instruct VJSP to initialize memory bank
7. Wait for VJSP to analyze your project and initialize the Memory Bank files
8. Validate the file contents to ensure accurate project descriptions. Update files if necessary.

Project Summary Tips

• Start simple—it can be as detailed or high-level as you prefer
• Focus on what matters most to you
• VJSP will help fill in gaps and ask clarifying questions
• You can update it as the project evolves

Example prompt for a meaningful summary:

Provide a concise yet comprehensive description of this project, highlighting its key objectives, core features, technologies used, and business importance. Then, write this description into an appropriately named text file that reflects the project content, ensuring clarity and professionalism in the writing. Keep it succinct.

Using Memory Bank

Core Workflow

Memory Bank Initialization

Initialization is a critical step as it lays the foundation for all future project interactions. When you request initialization with the command initialize memory bank, VJSP will:

1. Perform an exhaustive analysis of your project, including:
   • All source code files and their interrelationships
   • Configuration files and build system settings
   • Project structure and organizational patterns
   • Documentation and comments
   • Dependencies and external integrations
   • Testing frameworks and patterns
2. Create comprehensive Memory Bank files in the .vjsp/rules/memory-bank directory
3. Provide a detailed summary of its project understanding
4. Request you to verify the accuracy of the generated files

⚠️ Important

After initialization, take the time to carefully review and correct the generated files. Any misunderstandings or missing information at this stage will impact all future interactions. Thorough initialization will significantly boost VJSP's effectiveness, while hasty or incomplete initialization will permanently limit its ability to assist you effectively.

Memory Bank Updates

Memory Bank updates occur when:

1. New project patterns are identified
2. Following the implementation of significant changes
3. When you explicitly request an update memory bank
4. When context requires clarification

To perform a Memory Bank update, VJSP will:

1. Review all project files
2. Document the current state
3. Record insights and patterns
4. Update all Memory Bank files as needed

You can guide VJSP to focus on specific information sources with commands like update memory bank using information from @/Makefile.

Regular Task Execution

At the start of each task, VJSP:

1. Reads all Memory Bank files
2. Includes [Memory Bank: Active] at the start of its response
3. Provides a brief summary of its project understanding
4. Proceeds to execute the requested task

At the end of a task, if significant changes were made, VJSP may suggest updating the Memory Bank with the phrase: "Would you like me to update memory bank to reflect these changes?"

Adding Task Workflows

When you complete a repetitive task, you can document it for future reference. This is particularly useful for tasks like adding features that follow existing patterns.

To document a task, use the commands add task or store this as a task. VJSP will:

1. Create or update the tasks.md file in the Memory Bank directory
2. Document the task with the current context, including:
   • Task name and description
   • List of files that need modification
   • Step-by-step workflow
   • Important considerations
   • Example implementations

When starting a new task, VJSP checks if it matches any documented tasks and follows the established workflow to ensure no steps are missed.

Key Commands

• initialize memory bank - Use when starting a new project
• update memory bank - Triggers a full re-analysis for contextual documentation of the current task. Note: This operation is resource-intensive and not recommended for lightweight models due to potential reduced effectiveness. Can be used multiple times and works well with specific instructions, e.g., update memory bank using information from @/Makefile
• add task / store this as a task - Documents repetitive tasks for future reference

Status Indicators

VJSP uses status indicators to clearly communicate Memory Bank status:

• [Memory Bank: Active] - Indicates Memory Bank files have been successfully read and are in use
• [Memory Bank: Missing] - Indicates Memory Bank files cannot be found or are empty

These indicators appear at the start of VJSP's responses, providing immediate confirmation of Memory Bank status.

Documentation Updates

Memory Bank updates should occur automatically when:

• New project patterns are identified
• Following the implementation of significant changes
• When you explicitly request an update memory bank
• When context requires clarification

Context Window Management

As you work with VJSP, your context window will eventually become full. When you notice slower response times or less accurate references:

1. Instruct VJSP to update memory bank to document the current state
2. Start a new conversation/task
3. VJSP will automatically access your Memory Bank in the new conversation

This process ensures continuity across multiple sessions without losing critical context.

Handling Inconsistencies

If VJSP detects inconsistencies between Memory Bank files:

1. It will prioritize information in brief.md as the source of truth
2. Point out any inconsistencies to you
3. Proceed with the most reliable information available

This ensures VJSP can still work effectively even if documentation is not perfect.

Frequently Asked Questions

Where are Memory Bank files stored?

Memory Bank files are regular Markdown files stored in your project repository, typically in the .vjsp/rules/memory-bank/ directory. They are not hidden system files—they are designed to be part of your project documentation.

How often should I update Memory Bank?

Update Memory Bank after major milestones or directional changes. For active development, updating every few sessions is beneficial. Use the update memory bank command when you want to ensure all context is preserved.

Can I edit Memory Bank files manually?

Yes! While VJSP manages most files, you can edit any of them manually. The brief.md file is specifically designed to be maintained by you. VJSP respects manual edits to all files.

What happens if Memory Bank files are missing?

If Memory Bank files are missing, VJSP will display [Memory Bank: Missing] at the start of its responses and recommend initializing the Memory Bank.

Does Memory Bank work with all AI models?

Memory Bank is compatible with all AI models, but more powerful models will create more comprehensive and accurate Memory Bank files. Lightweight models may struggle with the resource-intensive process of analyzing and updating Memory Bank files.

Can I use Memory Bank across multiple projects?

Yes! Each project has its own Memory Bank located in its .vjsp/rules/memory-bank/ directory. VJSP automatically uses the correct Memory Bank for each project.

Does Memory Bank consume my context window?

Yes, Memory Bank does occupy some context window space at the start of each session as it loads all Memory Bank files. This is, however, a strategic tradeoff that delivers significant overall efficiency gains. By preloading project context:

• You eliminate repetitive explanations that consume far more context over time
• You reach productive outcomes with fewer back-and-forth interactions
• You maintain a consistent understanding throughout the session

Testing shows that while Memory Bank uses more tokens initially, it drastically reduces the total number of interactions needed to achieve results. This means less time explaining and more time building.

Best Practices

Getting Started

• Begin with a basic project summary and let the structure evolve incrementally
• Let VJSP help create the initial structure
• Review and adjust files as needed to match your workflow
• Validate the accuracy of generated files after initialization

Ongoing Work

• Allow patterns to emerge naturally as you work
• Do not force documentation updates—they should happen organically
• Trust the process—value compounds over time
• Pay attention to context confirmation at the start of sessions
• Use status indicators to confirm Memory Bank is active

Documentation Workflow

• brief.md is your foundation
• context.md changes most frequently
• All files work together to maintain project intelligence
• Update after major milestones or directional changes

Optimizing Memory Bank Performance

• Keep Memory Bank files concise and focused
• Use supplementary files for detailed documentation
• Update regularly but not excessively
• Use specific update commands when focusing on particular aspects

Remember

Memory Bank is VJSP's only link to previous work. Its effectiveness depends entirely on maintaining clear, accurate documentation and confirming context preservation in every interaction. When you see [Memory Bank: Active] at the start of a response, you can be confident that VJSP has a comprehensive understanding of your project.