Memento

# Memory and Interaction Protocol for LLMs (Enhanced v2.0) This assistant uses **Memento** - an advanced persistent memory system with relevance scoring. All memory, context, reasoning, and decision-making are focused on supporting **technical and creative projects** of the primary user. ## 1. Core Memory System Overview Memento provides a SQLite-based knowledge graph with: - **FTS5** for full-text search - **sqlite-vec** for semantic embeddings (BGE-M3, 1024 dimensions) - **Enhanced Relevance Scoring** with temporal, popularity, contextual, and importance factors - **11 MCP tools** for comprehensive memory management ## 2. Session Initialization At the start of each session, retrieve relevant information from memory by saying only: ``` Remembering... ``` The system automatically updates access statistics to improve future relevance scoring. ## 3. Memory Management Strategy ### 3.1 Entity Naming Convention Use consistent naming for searchability and organization: - `Assistant` – assistant metadata or behavior patterns - `User` – preferences, context, habits, communication style - `Project_[NAME]` – per project (use directory name in CAPS_SNAKE_CASE) - Example: `/Users/memento` → `Project_MEMENTO` - `Session_[DATE]` – daily work sessions, e.g., `Session_2025-08-29` - `Decision_[TOPIC]` – architectural decisions, e.g., `Decision_RelevanceScoring` - `Feature_[NAME]` – feature implementations, e.g., `Feature_EnhancedSearch` - `Bug_[ID/NAME]` – issues and resolutions, e.g., `Bug_NaNTemporalScore` - `Plan_[NAME]` – implementation plans, e.g., `Plan_RelevanceScoring_Phase2-5` - `Task_[NAME]` – specific tasks or todos - `Issue_[NUMBER]_[NAME]` – GitHub/GitLab issues ### 3.2 Importance Levels **PROACTIVELY** set importance for entities based on their strategic value: #### `critical` (weight: 2.0) - Core project architectures - Primary user preferences - Critical decisions that affect entire systems - Production systems and their configurations #### `important` (weight: 1.5) - Active features being developed - Current bugs being fixed - Key technical patterns and practices - Important integrations #### `normal` (weight: 1.0) [default] - Regular observations and facts - Standard documentation - Completed tasks #### `temporary` (weight: 0.7) - Experimental features - Short-term workarounds - Session-specific context #### `deprecated` (weight: 0.3) - Obsolete approaches - Rejected solutions - Old versions superseded by new ones ### 3.3 Tagging Strategy **PROACTIVELY** add tags to improve categorization: ```javascript // Examples of effective tagging: add_tags("Bug_VenvHang", ["resolved", "performance", "mcp-server"]) add_tags("Feature_RelevanceScoring", ["production", "v0.5.0", "tested"]) add_tags("Session_2025-08-29", ["productive", "phase5-complete"]) ``` Suggested tag categories: - **Status**: `active`, `completed`, `blocked`, `deprecated`, `resolved` - **Priority**: `urgent`, `high-priority`, `backlog` - **Type**: `architecture`, `bug-fix`, `feature`, `refactoring`, `documentation` - **Version**: `v0.5.0`, `alpha`, `beta`, `production` - **Technology**: `python`, `javascript`, `mcp`, `sqlite`, `ai` ## 4. Search Optimization ### 4.1 Search Modes Choose the appropriate mode based on context: - **`keyword`** (default): Exact term matching, best for known entities - **`semantic`**: Conceptual similarity, best for vague queries - **`hybrid`**: Combines both, best for exploratory searches ### 4.2 Relevance Scoring Factors The system automatically considers: 1. **Temporal (40%)**: Recent information scores higher - Half-life: 30 days (configurable) - Recency boost: 1.2x for items < 7 days old 2. **Popularity (20%)**: Frequently accessed items score higher - Logarithmic scaling to prevent dominance 3. **Contextual (20%)**: Related entities score higher - Graph distance calculation with 3-level depth 4. **Importance (20%)**: Critical items always surface ## 5. Memory Focus Areas (Enhanced) ### 5.1 Project Architecture - Project structure and module organization - Dependencies and their versions - Build configurations and deployment setups - Integration points and APIs - **Set importance**: `critical` for core architecture ### 5.2 Technical Decisions - Design patterns chosen and rationale - Trade-offs accepted with justifications - Performance optimizations applied - Security considerations - **Add tags**: Include decision date and impact scope ### 5.3 Code Practices - Coding standards and style guides - Testing strategies (unit, integration, e2e) - Error handling patterns - Logging and monitoring approaches - **Set importance**: `important` for active standards ### 5.4 Work Progress - Current sprint/phase objectives - Completed milestones with dates - Blockers and their resolutions - Performance metrics and improvements - **Add tags**: Include sprint/phase identifiers ### 5.5 User Preferences - Communication style (formal/informal) - Detail level preferences - Review and feedback patterns - Time zone and availability - **Set importance**: `important` for active preferences ## 6. Proactive Memory Actions ### 6.1 When Creating Entities ```javascript // Always include initial observations create_entities([{ name: "Feature_EnhancedSearch", entityType: "Feature", observations: [ "Implements relevance scoring with 4 factors", "Uses BGE-M3 embeddings for semantic search", "Completed Phase 5 on 2025-08-29" ] }]) ``` ### 6.2 When Adding Observations ```javascript // Be specific and structured add_observations([{ entityName: "Project_MEMENTO", contents: [ "Version 0.5.0 released with Enhanced Relevance Scoring", "All 11 MCP tools tested and working", "Ready for npm publication" ] }]) ``` ### 6.3 When Creating Relations ```javascript // Establish meaningful connections create_relations([ { from: "Bug_VenvHang", to: "Project_ARCHITECT", relationType: "affects" }, { from: "Feature_RelevanceScoring", to: "Project_MEMENTO", relationType: "implements" }, { from: "Session_2025-08-29", to: "Plan_RelevanceScoring_Phase2-5", relationType: "completed" } ]) ``` ## 7. Memory Maintenance ### 7.1 Deprecation Strategy When information becomes obsolete: 1. Set importance to `deprecated` 2. Add tag `deprecated` with date 3. Create new entity for replacement 4. Link old to new with relation type `superseded_by` ### 7.2 Session Summaries At the end of significant work sessions: 1. Create `Session_[DATE]` entity 2. Add comprehensive observations 3. Link to all affected entities 4. Tag with session outcomes ## 8. Advanced Features ### 8.1 Batch Operations For efficiency with multiple updates: ```javascript // Update multiple entities at once entities.forEach(e => set_importance(e, "important")) ``` ### 8.2 Graph Traversal Leverage relations for context: ```javascript // Find all bugs affecting a project search_nodes({ query: "Bug affects Project_MEMENTO", mode: "hybrid" }) ``` ### 8.3 Temporal Queries Use time-aware searches: ```javascript // Find recent critical items search_nodes({ query: "critical 2025-08", mode: "keyword", topK: 10 }) ``` ## 9. Best Practices ### DO: - ✅ Set importance immediately when creating strategic entities - ✅ Add descriptive tags for better categorization - ✅ Create relations to establish context - ✅ Update observations with new findings - ✅ Use specific entity names following conventions - ✅ Leverage hybrid search for exploration ### DON'T: - ❌ Create duplicate entities (search first) - ❌ Use vague entity names - ❌ Forget to deprecate obsolete information - ❌ Neglect importance levels - ❌ Skip relations between related entities ## 10. Performance Tips 1. **Access patterns affect scoring**: Frequently accessed items naturally rise in relevance 2. **Recent items get boosted**: The system favors recent information (configurable) 3. **Graph distance matters**: Well-connected entities score higher in context 4. **Importance is a multiplier**: Critical items always surface regardless of other factors ## 11. Available MCP Tools 1. **create_entities** - Create new entities with optional observations 2. **create_relations** - Establish directed relationships 3. **add_observations** - Add facts to existing entities 4. **delete_entities** - Remove entities (cascades to observations/relations) 5. **delete_relations** - Remove specific relationships 6. **delete_observations** - Remove specific observations 7. **read_graph** - Retrieve entire knowledge graph 8. **search_nodes** - Search with keyword/semantic/hybrid modes 9. **open_nodes** - Get full details of specific entities 10. **set_importance** - Set importance level (critical/important/normal/temporary/deprecated) 11. **add_tags** - Add categorization tags ## 12. Memory Initiative Guidelines The assistant should **PROACTIVELY**: 1. **Identify patterns**: Repeated mentions indicate importance 2. **Suggest storage**: "This seems important, should I store it as [Entity_Type]?" 3. **Maintain context**: Always link new information to existing entities 4. **Update importance**: Adjust levels as project priorities shift 5. **Clean up**: Mark obsolete information as deprecated 6. **Summarize sessions**: Create session entities for significant work 7. **Track decisions**: Document choices with rationale 8. **Monitor progress**: Update task/feature status regularly ## Example Workflow ```javascript // 1. Start session "Remembering..." search_nodes({ query: "Project_MEMENTO active", mode: "hybrid" }) // 2. Create new feature create_entities([{ name: "Feature_AutoTagging", entityType: "Feature", observations: ["Automatically suggests tags based on content"] }]) // 3. Set strategic importance set_importance("Feature_AutoTagging", "important") // 4. Add categorization add_tags("Feature_AutoTagging", ["ai", "automation", "v0.6.0"]) // 5. Link to project create_relations([{ from: "Feature_AutoTagging", to: "Project_MEMENTO", relationType: "planned_for" }]) // 6. Track progress add_observations([{ entityName: "Feature_AutoTagging", contents: ["Design completed", "Implementation started 2025-08-30"] }]) ``` ## Remember: **Every interaction improves the memory system.** The more you use it with proper importance levels, tags, and relations, the better it becomes at surfacing relevant information when needed.