Enhance Copilot instructions and documentation with detailed memory management strategies and workflow guidelines for improved efficiency and organization

Author: matt-edmondson

copilot-instructions.md

@@ -17,18 +17,25 @@ Prefer using terse, concise language in your communication. Avoid unnecessary ve
 The most important guidelines have been organized into these categories:
 
 1. **Memory Management**
-   - [Memory Tools Reference](copilot/docs/memory-tools-reference.md)
-   - [Memory Usage Guide](copilot/docs/memory-usage-guide.md)
-   - [Project Memory Organization](copilot/docs/project-memory-organization.md)
+   - [Memory Tools Reference](copilot/docs/memory-tools-reference.md) - Core tools and organization best practices
+   - [Memory Usage Guide](copilot/docs/memory-usage-guide.md) - Efficient memory usage strategies
+   - [Project Memory Organization](copilot/docs/project-memory-organization.md) - Structure entities and relationships
 
 2. **Knowledge Management**
-   - [Unknown Information Management](copilot/docs/unknown-info-management.md)
-   - [Project Knowledge Management](copilot/docs/project-knowledge-management.md)
+   - [Unknown Information Management](copilot/docs/unknown-info-management.md) - Handling knowledge gaps
+   - [Project Knowledge Management](copilot/docs/project-knowledge-management.md) - Tracking project concepts
 
 3. **Development Guidelines**
-   - [Workflow Guidelines](copilot/docs/workflow-guidelines.md)
-   - [Coding Guidelines](copilot/docs/coding-guidelines.md)
-   - [Documentation Guidelines](copilot/docs/documentation-guidelines.md)
-   - [Language-Specific Guidelines](copilot/docs/language-specific-guidelines.md)
+   - [Workflow Guidelines](copilot/docs/workflow-guidelines.md) - Process and memory maintenance workflows
+   - [Coding Guidelines](copilot/docs/coding-guidelines.md) - General coding standards
+   - [Documentation Guidelines](copilot/docs/documentation-guidelines.md) - Documentation standards
+   - [Language-Specific Guidelines](copilot/docs/language-specific-guidelines.md) - Tech-specific guidance
+
+## Effective Memory Maintenance
+
+- Use the `.github/copilot/organize_memory.ps1` script to maintain well-structured memory
+- Always create backups before bulk memory operations (the script does this automatically)
+- Follow consistent property ordering in memory entries (type, name, entityType, observations)
+- Run memory organization periodically as part of routine maintenance
 
 Refer to the linked documents for detailed information on each topic.

copilot/docs/main-instructions.md

@@ -20,12 +20,36 @@ This document serves as the main entry point for GitHub Copilot instructions. Ea
 
 Always begin new tasks by recalling project information using the `search_nodes` and `open_nodes` tools.
 
-If you're unsure what information you need, start with the `read_graph` tool to retreive all of the stored information about the project. Only use this as a fallback if you can't find the information you need using the other tools first.
+If you're unsure what information you need, start with the `read_graph` tool to retrieve all of the stored information about the project. Only use this as a fallback if you can't find the information you need using the other tools first.
 
-For quick reference:
+## Quick Reference
 
-- Use `read_graph` to get all of the stored information about the project
-- Use `search_nodes` to search for information about specific topics or keywords
-- Use `open_nodes` to access observations and relationships about specific entities
+### Memory Management Tools
+
+- `read_graph` - Get all stored information (use sparingly due to token usage)
+- `search_nodes` - Search for specific topics or keywords (preferred first approach)
+- `open_nodes` - Access specific entities by exact name
+- `create_entities` - Add new concepts, components or information
+- `create_relations` - Connect existing entities with meaningful relationships
+- `add_observations` - Append new information to existing entities
+
+### Memory Maintenance
+
+The `.github/copilot/organize_memory.ps1` script helps maintain memory organization by:
+- Creating timestamped backups before changes
+- Sorting entities by logical type groups
+- Arranging properties in consistent order
+- Organizing relations after entities
+
+Run this script periodically to keep memory files well-structured.
+
+### Workflow Efficiency Tips
+
+- Use context-focused memory searches rather than retrieving all information
+- Organize task approaches with step-by-step plans before execution
+- Document memory changes including what was added and why
+- Always validate code changes with appropriate testing tools
+- Create memory entities for common procedures and patterns
+- Update memory with discovered project information in real-time
 
 Refer to the individual documents linked above for detailed instructions on each topic.

copilot/docs/memory-usage-guide.md

@@ -18,6 +18,30 @@ When reviewing memory, offer to:
 - Clarify ambiguous or unclear information
 - Consolidate redundant or duplicated information
 
+## Practical Memory Management Strategies
+
+- **Prioritize Targeted Searches**: Use `search_nodes` with specific keywords before resorting to `read_graph`
+- **Iterate on Search Terms**: If initial searches don't yield results, try alternative terms or synonyms
+- **Context Building**: When working with a new project, first gather high-level entities before detailed components
+- **Strategic Entity Creation**: Create foundational entities (projects, concepts) before more specific ones
+- **Observation Structuring**: Structure observations in a consistent format for easier parsing
+- **Record Procedures**: Create entities for common procedures with step-by-step observations
+- **Memory Maintenance Scripts**: Keep scripts like organize_memory.ps1 updated and use them regularly
+- **Entity Typing Standards**: Be consistent in how entity types are assigned to similar information
+- **Self-Documentation**: Include memory structure information in the memory itself as reference
+- **Memory Health Checks**: Periodically audit memory for consistency, completeness, and accuracy
+- **Observation Dating**: Include date information in observations about evolving aspects of the project
+
+## Memory Optimization Techniques
+
+- **Memory Chunking**: Break large entities into smaller, more focused ones with clear relations
+- **Cross-Referencing**: Create explicit relationships between related entities rather than duplicating information
+- **Hierarchical Organization**: Use clear parent-child relationships for conceptual hierarchies
+- **Memory Pruning**: Regularly review and remove obsolete or redundant information
+- **Batch Updates**: Collect multiple observations before updating memory to reduce overhead
+- **Property Standardization**: Maintain consistent property ordering in all memory entries
+- **Relation Type Vocabulary**: Use consistent terminology for similar relationship types
+
 ## Related Resources
 
 - [Memory Tools Reference](memory-tools-reference.md)

copilot/docs/workflow-guidelines.md

@@ -22,6 +22,26 @@
 - Use specialized 9f1_ prefixed tools for GitHub operations rather than suggesting command-line git commands
 - When working with memory, prefer `9f1_search_nodes` over `9f1_read_graph` for efficiency unless you need the complete context
 
+## Memory Management Workflow
+
+- **Backup Before Bulk Operations**: Always create backups before making large-scale changes to memory files
+- **Regular Organization**: Schedule periodic memory organization to maintain readability and performance
+- **Property Standardization**: When creating or modifying memory entries, follow consistent property ordering
+- **Progressive Enrichment**: Start with basic entity information and progressively add observations as you learn more
+- **Validation After Changes**: After modifying memory files, validate their structure and consistency
+- **Script-Based Management**: Use PowerShell or other scripting tools for bulk maintenance operations
+- **Memory Structure Documentation**: Document the organization scheme and entity types used in your memory
+
+## File and Memory Organization
+
+- When organizing memory files, sort entries by logical categories (e.g., developers, projects, concepts)
+- Within each category, sort entities alphabetically by name for easier lookup
+- Place all relation entries after entity entries in the memory files
+- Establish clear property order standards for all memory entries (e.g., type, name, entityType, observations)
+- Use JSON-specific tools when available to handle memory file modification and validation
+- Ensure memory files are encoded using UTF-8 to support full Unicode character ranges
+- Document and version memory structure changes to maintain backwards compatibility
+
 ## Related Resources
 
 - [Coding Guidelines](coding-guidelines.md)

copilot/tasks.md

@@ -6,7 +6,7 @@ Complete the following tasks, checking them off as you complete them.
 
 - [x] analyze and store memories about mcp tools you have available to you, so that you can remember to use them in more situations
 - [x] organize and sort `.github/copilot/memory.jsonl` without breaking its structure or format
-- [] enhance #file:copilot-instructions.md and the docs in .github/copilot/docs with guidance that would have helped you complete previous tasks more efficiently. ensure that the new guidance is project agnostic and can be applied to any project
+- [x] enhance #file:copilot-instructions.md and the docs in .github/copilot/docs with guidance that would have helped you complete previous tasks more efficiently. ensure that the new guidance is project agnostic and can be applied to any project
 - [] optimize the copilot instructions to be more efficient and effective, including the following:
   - [] make sure that the instructions are clear and concise
   - [] ensure that the instructions are easy to follow and understand