memory-bank-large-repos-part2.md

Phase 4: Defining AI Memory Bank Interaction Rules (.cursor/rules/memory-bank.mdc)

Goal: To create a dedicated rules file (memory-bank.mdc) that instructs AI assistants (like yourself) on how to effectively utilize and interact with the project's memory bank, which exclusively uses embedded Mermaid diagrams.

1. Propose Content for memory-bank.mdc:

   • Based on our established memory bank structure (with only embedded diagrams), content guidelines, and the principles of AI interaction discussed, propose the full content for a new file named memory-bank.mdc. This file will reside in the project's .cursor/rules/ directory.
   • The content should be in Markdown format and include:
     • Preamble: A clear statement about the AI's absolute reliance on this memory bank for project context, especially after a "memory reset."
     • Memory Bank Structure Overview:
       • A brief explanation of the memory-bank/ directory.
       • An embedded Mermaid diagram illustrating the high-level structure (e.g., global files, component subdirectories like services/, modules/). This diagram must not show any separate diagram directories.
       • Mention of key global files (e.g., 00-project-global-overview.md, 01-global-architecture.md, CONTRIBUTING_GUIDELINES.md, INDEX.md) and their purpose in AI navigation.
       • The pattern for component-specific documentation (e.g., services/some-service/00-overview.md, 01-architecture-and-design.md).
     • Core Interaction Principles & Workflow:
       • Mandatory Initial Consultation: AI must always start by consulting relevant parts of the memory bank.
       • Navigation Strategy: How to use the global overview, architecture documents, INDEX.md, and then drill down into component-specific files. This should align with the "Memory Bank Navigation Protocol" (detailed in Phase 5).
       • Diagram Interpretation: Explicit instructions to recognize, interpret, and utilize information from embedded Mermaid diagrams exclusively.
       • Adherence to CONTRIBUTING_GUIDELINES.md: AI must be aware of and follow the content and (embedded) diagramming standards defined therein when suggesting updates.
     • Proactive Maintenance and Updates:
       • Reiterate the AI's role in suggesting updates or new content for the memory bank, as per the "Memory Bank Maintenance Rule" (detailed in Phase 5).
       • Specifically mention suggesting new or updated embedded Mermaid diagrams.
     • Relationship to Other Rules: Briefly state that this memory-bank.mdc file is focused on memory bank interaction and complements other rules in .cursor/rules/ (like a project-core-context.mdc which might cover broader project coding standards or workflows).
     • Concluding Reminder: Re-emphasize the critical nature of the memory bank for the AI's effectiveness.

2. Review and Approval:

   • I will review the proposed content for memory-bank.mdc. We may iterate on this.

3. File Creation (Simulated):

   • Once approved, we will consider this memory-bank.mdc file as defined and ready to be notionally placed in .cursor/rules/. (You don't need to actually create the file, just have the content finalized).

Completion Criteria for Phase 4:

• The complete content for memory-bank.mdc has been proposed and approved.
• There's a shared understanding of how this file will govern AI interaction with the memory bank (which uses only embedded diagrams).

(AI, once the content for memory-bank.mdc is approved, please confirm readiness for Phase 5.)

---

Phase 5: Defining General AI Interaction, Navigation, Maintenance, Versioning, and Conflict Resolution

Goal: To establish clear overarching rules for AI interaction, efficient navigation (interpreting embedded Mermaid diagrams), proactive maintenance, and conflict resolution, complementing the specific memory-bank.mdc.

1. AI Interaction Rules (e.g., for a general .cursor/rules/project-core-context.mdc and module-specific .mdc files, if any, beyond memory-bank.mdc): When proposing content for these rules:

   • Main Project Context Rule (Example: .cursor/rules/project-core-context.mdc):
     • Add to point 5: "Diagram Awareness and Interpretation: Recognize and interpret embedded Mermaid diagrams within .md files in the memory-bank/ to enhance your contextual understanding. Use the information conveyed by these diagrams in your responses and analysis. Refer to memory-bank.mdc for detailed memory bank interaction protocols."
   • Module/Service-Specific Context Rules: When defining rules for specific modules, explicitly reference key embedded Mermaid diagrams within that module's memory bank (e.g., "Refer to the API interaction sequence diagram embedded in memory-bank/services/payment-service/01-architecture-and-design.md before generating client code for this service. Consult memory-bank.mdc for how to approach the memory bank.").

2. Memory Bank Navigation Protocol (for AI Assistants - to be documented in memory-bank/CONTRIBUTING_GUIDELINES.md or a dedicated AI protocol file, and referenced by memory-bank.mdc):

   • Diagram Example for this Protocol: The prompt itself should include an example embedded Mermaid flowchart visualizing this navigation protocol, to be placed in the CONTRIBUTING_GUIDELINES.md.

     graph TD
         A[Start: AI Receives Query/Task] --> B{Is query trivial?};
         B -- Yes --> C[Answer directly];
         B -- No --> D["Consult `00-project-global-overview.md` and `01-global-architecture.md` (ref: `memory-bank.mdc`)"];
         D --> E{Query specific to a module/service?};
         E -- Yes --> F[Navigate to `memory-bank/module-or-service/`];
         F --> G["Consult `00-overview.md` then `01-architecture.md`, etc. (ref: `memory-bank.mdc`)"];
         E -- No --> H[Search `memory-bank/INDEX.md` for keywords];
         G --> J{Information found? - Prioritize embedded Mermaid diagrams};
         H --> J;
         J -- Yes --> K[Synthesize info, check `last-updated`, cross-ref tags, interpret embedded Mermaid diagrams];
         J -- No --> L["Indicate missing info, suggest update (ref: `memory-bank.mdc`)"];
         K --> M[Generate Response / Perform Task];
     

     Loading
   • (Other points of the Navigation Protocol remain as before: Hierarchical Search, Keyword Index, Cross-Reference Following, Recency Check)

3. Memory Bank Maintenance Rule (Operational Rule for AI Assistants - also to be documented and referenced by memory-bank.mdc):

   • Proactive Update & Augmentation Suggestions: Enhance this to: "...you MUST proactively suggest specific, actionable updates or additions to the relevant .md files in the memory-bank/. This includes suggesting where new embedded Mermaid diagrams could clarify complex points, or where existing embedded Mermaid diagrams need updating to reflect changes. Frame suggestions clearly (e.g., 'Suggest adding an embedded Mermaid sequence diagram to memory-bank/services/order-processing/02-api-and-interfaces.md to illustrate the new asynchronous order fulfillment callback mechanism.'). Follow guidance in memory-bank.mdc for this process."
   • Conflict Resolution Protocol: The prompt should suggest an embedded Mermaid flowchart diagram here too for the CONTRIBUTING_GUIDELINES.md.

     graph TD
         A[AI Detects Conflict: Memory Bank vs. Codebase] --> B{Report Conflict Clearly};
         B --> C[State Codebase Source & Memory Bank Source of Discrepancy];
         C --> D{For Immediate Task: Prioritize Codebase Implementation};
         D --> E[Propose Update to Memory Bank OR Ask for Clarification];
         E --> F[Human User Reviews & Approves/Clarifies];
     

     Loading
   • (Other points of Maintenance Rule remain as before: Primacy, Consultation, Consistency Check, Assistance)

4. Memory Bank Versioning Strategy (Managed by Human Team): (Remains as before)

Completion Criteria for Phase 5:

• AI interaction rules explicitly addressing embedded Mermaid diagram interpretation (and referencing memory-bank.mdc) are approved.
• The Memory Bank Navigation Protocol, including an illustrative embedded flowchart, is approved.
• The Memory Bank Maintenance Rule, including proactive suggestions for embedded Mermaid diagram creation/updates and a conflict resolution flowchart, is approved.
• The Versioning Strategy is acknowledged.

(AI, once these are approved, please confirm readiness for Phase 6.)

---

Phase 6: Content Review and Refinement

Goal: To critically review all content generated for the memory bank, ensuring every piece of information is concise, directly relevant, and optimized to assist AI assistants in making decisions about software architecture, design, and coding.

1. Collaborative Review:

   • We (human and AI) will systematically go through each .md file created in the memory-bank/.
   • Focus Question for Review: "Does this piece of information directly help an AI understand the project's architecture, make design decisions, or write/modify code effectively? Is it presented in the most concise and actionable way for these purposes?"

2. Identify Areas for Refinement:

   • Pinpoint information that might be:
     • Too general or vague to be useful for technical tasks.
     • Tangential to core architectural or coding concerns (e.g., overly detailed project management specifics, historical notes that don't impact current design choices, very niche user support issues unless they directly reflect core functionality or constraints).
     • Redundant with information better placed elsewhere or already clearly implied by more critical documentation.
     • Not actionable from an AI's perspective for design, architecture, or coding tasks.
   • Identify sections that could be more concise or clearly structured (e.g., using bullet points, tables, or focused explanations) for easier AI parsing and understanding.

3. Propose and Implement Changes:

   • For identified areas, you (AI) will propose specific changes. This might include:
     • Removing sentences, paragraphs, or entire sections deemed irrelevant to the AI's core technical tasks.
     • Rewriting content to be more direct, highlighting technical implications, constraints, patterns, and design rationale.
     • Reorganizing information within a file for better logical flow and relevance to AI decision-making.
     • Ensuring that crucial information like design rationale, critical dependencies, APIs, and key patterns are explicitly and clearly stated.
   • I will review your proposed changes, and we'll iterate until the content is approved as optimally focused.

4. Verification of Relevance and Focus:

   • After revisions, we will perform a final pass to confirm that the memory bank primarily contains information that is crucial for understanding the 'why' and 'how' of the system's technical design and implementation, directly aiding in future architecture and coding work.

Completion Criteria for Phase 6:

• All existing memory bank documents have been reviewed against the core goal of supporting AI in architecture and coding.
• Necessary revisions to enhance focus, relevance, and conciseness have been proposed, approved, and implemented.
• The memory bank is confirmed to be highly targeted and optimized for its primary technical assistance functions.
• You (AI) confirm a clear understanding that the primary utility of the memory bank is to support these technical decision-making and code generation processes.

(AI, once all content has been reviewed and refined, please confirm readiness for Phase 7.)

---

Phase 7: Activation and Ongoing Collaboration

Goal: To formally activate the refined memory bank and establish it as the central, evolving knowledge repository using exclusively embedded Mermaid diagrams.

1. Formal Activation:

   • We declare the memory bank, as reviewed and refined in Phase 6, to be formally active and the primary source of structured project context for AI assistance.
   • You (AI) will commit to using this memory bank and adhering to the memory-bank.mdc rules as the foundational guide for understanding the project.

2. Initial Population Support (If Further Sections Needed or for Validation):

   • As a practical application of the refined memory bank and rules, I may ask you to help populate any remaining placeholder sections or draft new documentation for a specific module/service.
   • This task will follow all approved templates, guidelines (including exclusive use of embedded Mermaid diagrams), and the memory-bank.mdc rules (e.g., "Based on your understanding of the new-feature-module, draft the 00-overview.md and 01-architecture-and-design.md files for it. Please ensure the 01-architecture-and-design.md includes relevant embedded Mermaid diagrams (e.g., component, sequence) to clearly illustrate its design.").

3. Continuous Improvement and Maintenance:

   • The memory bank is a living document. Both human team members and you (AI) are responsible for its continuous improvement.
   • You will proactively suggest updates, new entries, or refinements to the memory bank (including new or updated embedded Mermaid diagrams) based on ongoing development work, changes in the codebase, or new insights gained, following the "Memory Bank Maintenance Rule" outlined in Phase 5 and guided by memory-bank.mdc.
   • Human team members will also contribute updates and review AI-suggested changes.

Completion Criteria for Phase 7:

• You acknowledge the formal activation of the refined memory bank and your commitment to the established protocols and the memory-bank.mdc file.
• You are ready and equipped to assist with any further population tasks and to proactively contribute to the continuous improvement and maintenance of the memory bank, exclusively using embedded Mermaid diagrams.

This concludes the setup, refinement, and activation process for our project memory bank. Let's begin with Phase 0 confirmation.