@nockdev/awf 6.2.0

package/.agent/core/MEMORY_CONSOLIDATION.yaml

@@ -0,0 +1,352 @@
+# DOMYH Awesome Code — Memory Consolidation Engine v6.2.0
+# Auto-consolidate, merge, and optimize memory storage
+# Reduce token usage by 30%+ through intelligent compression
+
+version: "6.1.2"
+engine: memory_consolidation
+
+# =============================================================================
+# CONSOLIDATION OVERVIEW
+# =============================================================================
+
+overview:
+  purpose: "Automatically merge, compress, and organize memories"
+  goal: "Reduce memory token usage by 30% while preserving information"
+  inspiration: "Human memory consolidation during sleep"
+
+# =============================================================================
+# CONSOLIDATION TRIGGERS
+# =============================================================================
+
+triggers:
+  # Time-based
+  scheduled:
+    session_end:
+      enabled: true
+      delay: 0 # Immediate on session end
+
+    periodic:
+      enabled: true
+      interval: 3600 # Every hour during active session
+
+  # Count-based
+  threshold:
+    memory_count:
+      threshold: 50
+      action: consolidate_similar
+
+    decision_count:
+      threshold: 20
+      action: merge_decisions
+
+    error_count:
+      threshold: 30
+      action: consolidate_errors
+
+    session_count:
+      threshold: 10
+      action: archive_old_sessions
+
+  # Size-based
+  size:
+    total_tokens:
+      threshold: 5000
+      action: aggressive_consolidation
+
+    single_file_tokens:
+      threshold: 2000
+      action: split_and_summarize
+
+  # Explicit
+  command:
+    trigger: "/mem consolidate"
+    options:
+      - "--aggressive" # Maximum compression
+      - "--preserve" # Minimal consolidation
+      - "--category=X" # Target specific category
+
+# =============================================================================
+# CONSOLIDATION STRATEGIES
+# =============================================================================
+
+strategies:
+  # Strategy 1: Merge Similar Memories
+  merge_similar:
+    method: semantic_similarity
+
+    # Algorithm specification (v6.2.0 - HSA integration)
+    algorithm:
+      type: cosine_similarity
+      embedding_model: hsa # Prefer HSA hybrid search
+      fallback: tfidf_vectorizer # If no HSA/API available
+      hsa_config:
+        prefer_hybrid: true
+        vector_weight: 0.7
+        bm25_weight: 0.3
+      implementation: |
+        # Cosine similarity formula:
+        # cos(θ) = (A · B) / (||A|| × ||B||)
+        # Where A and B are embedding vectors
+
+    threshold: 0.85
+
+    process:
+      1: compute_pairwise_similarity
+      2: identify_similar_clusters
+      3: merge_clusters_into_single_memory
+      4: preserve_unique_details
+      5: update_references
+
+    merge_rules:
+      keep: most_recent
+      combine: unique_details
+      discard: redundant_phrases
+
+    example:
+      before:
+        - "User prefers short responses"
+        - "User wants concise answers"
+        - "User likes brief explanations"
+      after:
+        - "User prefers concise, brief responses"
+
+  # Strategy 2: Collapse Temporal Sequences
+  collapse_sequences:
+    method: temporal_proximity
+    threshold_minutes: 5
+
+    process:
+      1: identify_sequential_memories
+      2: group_by_time_window
+      3: create_summary_for_group
+      4: archive_originals
+
+    example:
+      before:
+        - "10:01 - Started auth implementation"
+        - "10:02 - Created auth service"
+        - "10:03 - Added JWT validation"
+        - "10:04 - Fixed token expiry"
+      after:
+        - "10:01-10:04 - Implemented auth service with JWT (4 steps)"
+
+  # Strategy 3: Build Topic Hierarchies
+  build_hierarchies:
+    method: topic_clustering
+    levels: [category, topic, detail]
+
+    process:
+      1: extract_topics_from_memories
+      2: cluster_by_topic_similarity
+      3: create_hierarchy_structure
+      4: summarize_at_each_level
+
+    example:
+      flat:
+        - "PostgreSQL is the database"
+        - "Using pgx/v5 driver"
+        - "Connection pooling enabled"
+        - "Migrations use Atlas"
+      hierarchical:
+        category: Database
+        topic: PostgreSQL Setup
+        details:
+          - driver: pgx/v5
+          - pooling: enabled
+          - migrations: Atlas
+
+  # Strategy 4: Extract Patterns
+  extract_patterns:
+    method: frequency_analysis
+    min_occurrences: 3
+
+    process:
+      1: identify_repeated_elements
+      2: extract_as_pattern
+      3: replace_instances_with_reference
+      4: store_pattern_separately
+
+    example:
+      instances:
+        - "Fixed error by adding null check"
+        - "Resolved issue with null check"
+        - "Added null check to fix bug"
+      pattern:
+        name: "Null Check Fix Pattern"
+        solution: "Add null check before access"
+        instances: 3
+
+  # Strategy 5: Semantic Compression
+  semantic_compression:
+    method: key_information_extraction
+    target_reduction: 50%
+
+    techniques:
+      remove_redundancy:
+        - duplicate_phrases
+        - filler_words
+        - restated_information
+
+      preserve_essentials:
+        - key_entities
+        - relationships
+        - decisions
+        - outcomes
+
+      compress_details:
+        - verbose_explanations → bullet_points
+        - long_descriptions → key_phrases
+        - full_examples → pattern_references
+
+    example:
+      before: |
+        We decided to use PostgreSQL as our primary database because 
+        it offers strong consistency, ACID compliance, and excellent 
+        support for complex queries. We also considered MongoDB but 
+        decided against it due to our need for relational data.
+      after: |
+        Decision: PostgreSQL (not MongoDB)
+        Reasons: ACID, consistency, relational needs
+
+# =============================================================================
+# CONSOLIDATION PROCESS
+# =============================================================================
+
+process:
+  # Phase 1: Analysis
+  analyze:
+    collect_memories: all_active
+    compute_similarities: pairwise
+    identify_clusters: agglomerative
+    estimate_reduction: tokens
+
+  # Phase 2: Plan
+  plan:
+    select_strategy: based_on_analysis
+    prioritize_targets: by_token_savings
+    create_backup: always
+    estimate_time: based_on_size
+
+  # Phase 3: Execute
+  execute:
+    apply_strategies: in_order
+    validate_each_step: true
+    rollback_on_error: true
+
+  # Phase 4: Verify
+  verify:
+    compare_information_coverage: true
+    check_reference_integrity: true
+    validate_token_reduction: true
+
+  # Phase 5: Update
+  update:
+    update_active_memories: true
+    update_indexes: true
+    update_embeddings: if_changed
+    log_consolidation: true
+
+# =============================================================================
+# OUTPUT FILES
+# =============================================================================
+
+output:
+  # Consolidated view
+  consolidated_memory:
+    path: memory/consolidated.md
+    format: markdown
+    max_tokens: 2000
+
+  # Consolidation log
+  consolidation_log:
+    path: memory/consolidation_log.json
+    include:
+      - timestamp
+      - strategy_used
+      - tokens_before
+      - tokens_after
+      - reduction_percent
+      - items_merged
+
+  # Archive of originals
+  archive:
+    path: memory/archive/consolidation/
+    naming: "{date}_{strategy}.json"
+    retention: 30_days
+
+# =============================================================================
+# SAFETY MEASURES
+# =============================================================================
+
+safety:
+  # Always backup before consolidation
+  backup:
+    enabled: true
+    location: memory/archive/safety_backups/
+    retention: 7_days
+
+  # Protected content
+  never_consolidate:
+    - user_corrections
+    - security_findings
+    - active_errors
+    - current_session
+
+  # Require confirmation for
+  confirm_required:
+    aggressive_consolidation: true
+    large_batch_merge: true
+    cross_category_merge: true
+
+  # Rollback capability
+  rollback:
+    enabled: true
+    max_rollback_depth: 5
+    command: "/mem rollback {consolidation_id}"
+
+# =============================================================================
+# METRICS
+# =============================================================================
+
+metrics:
+  track:
+    - total_consolidations
+    - tokens_saved
+    - compression_ratio
+    - information_preserved
+    - rollback_count
+
+  output:
+    path: memory/metrics.json
+    update: after_each_consolidation
+
+  alerts:
+    low_information_preservation:
+      threshold: 0.9
+      action: require_review
+
+    high_rollback_rate:
+      threshold: 0.1
+      action: adjust_thresholds
+
+# =============================================================================
+# INTEGRATION
+# =============================================================================
+
+integration:
+  # Memory engine
+  memory_engine:
+    notify_on_consolidation: true
+    update_pointers: true
+
+  # Context loader
+  context_loader:
+    invalidate_cache_on_consolidation: true
+
+  # Active memory
+  active_memory:
+    trigger_reflection_after: true
+
+  # Semantic engine
+  semantic_engine:
+    reindex_after_consolidation: true

package/.agent/core/MEMORY_ENGINE.yaml

@@ -0,0 +1,353 @@
+# DOMYH Awesome Code — Memory Engine Configuration v6.0
+# Implements 5-Tier Memory Architecture with Active Management
+# Based on 2025-2026 Best Practices: Anthropic, MemGPT/Letta, LangGraph
+
+version: "6.1.2"
+engine: hierarchical_memory_v6_with_graph
+
+# =============================================================================
+# SUB-ENGINES (Progressive Loading)
+# =============================================================================
+
+sub_engines:
+  # Phase 2: Core Memory Management
+  summarization: core/SUMMARIZATION_ENGINE.yaml
+  cleanup: core/CLEANUP_ENGINE.yaml
+  utilities: core/MEMORY_UTILS.yaml
+
+  # Phase 3: Semantic Memory
+  semantic: core/SEMANTIC_ENGINE.yaml # Optional vector DB
+
+  # Phase 4: Intelligent Memory (2025+ Best Practices)
+  context_loader: core/CONTEXT_LOADER.yaml # Just-in-Time loading
+  context_injector: core/CONTEXT_INJECTOR.yaml # Smart injection
+  context_priority: core/CONTEXT_PRIORITY.yaml # Priority scoring
+  active_memory: core/ACTIVE_MEMORY.yaml # Self-directing memory
+  consolidation: core/MEMORY_CONSOLIDATION.yaml # Auto-consolidation
+
+  # Phase 5: Centralized Configs (v6.2.0 Cleanup)
+  scoring_formula: core/SCORING_FORMULA.yaml # SSoT for scoring
+  memory_paths: core/MEMORY_PATHS.yaml # SSoT for paths
+  token_budgets: core/TOKEN_BUDGETS.yaml # SSoT for token limits
+
+  # Phase 6: v6.0 Upgrades (2025-2026 Best Practices)
+  state_machine: core/STATE_MACHINE.yaml # LangGraph-inspired flow
+  reflection: core/REFLECTION_ENGINE.yaml # Critic + Reflexion
+  graph_memory: core/GRAPH_MEMORY.yaml # 5th tier: Knowledge Graph
+  mcp_tools: core/MCP_TOOLS.yaml # Model Context Protocol
+  hybrid_router: core/HYBRID_ROUTER.yaml # Multi-strategy routing
+  context_optimization: core/CONTEXT_OPTIMIZATION.yaml # Caching + compaction
+
+# Archive structure (paths defined in MEMORY_PATHS.yaml)
+archive:
+  reference: core/MEMORY_PATHS.yaml # Single Source of Truth
+  base_path: memory/archive/
+  subdirs:
+    - sessions
+    - errors
+    - decisions
+    - audits
+    - phases
+    - consolidation # Phase 4: Consolidation backups
+    - forgotten # Phase 4: Soft-deleted memories
+
+# =============================================================================
+# LAYER CONFIGURATION
+# =============================================================================
+
+layers:
+  # Layer 1: Working Memory (in-context, always active)
+  working:
+    max_tokens: 500
+    persistence: none
+    content:
+      - current_task
+      - last_3_interactions
+      - active_errors
+    auto_manage: true
+    priority: critical
+
+  # Layer 2: Session Notes (file-based, human-readable)
+  session:
+    max_tokens: 2000
+    persistence: file
+    file: memory/session.md
+    format: markdown
+    content:
+      - session_history
+      - workflow_log
+      - agent_notes
+    load_on: session_start
+    save_on:
+      - workflow_complete
+      - every_10_interactions
+      - session_end
+    priority: high
+
+  # Layer 3: Project State (JSON, structured)
+  state:
+    max_tokens: 500
+    persistence: json
+    files:
+      main: memory/state.json
+      audit: memory/audit_summary.json
+      decisions: memory/decisions.md
+    content:
+      - project_info
+      - skill_preferences
+      - audit_scores
+      - pending_tasks
+    load_on: project_open
+    save_on:
+      - state_change
+      - workflow_complete
+      - decision_made
+    priority: high
+
+  # Layer 4: Semantic Memory (optional, vector DB)
+  semantic:
+    enabled: false # Opt-in feature
+    max_tokens: 2500
+    persistence: lancedb
+    database: memory/vectors/
+    content:
+      - full_audit_history
+      - code_reviews
+      - detailed_decisions
+    load_on: semantic_query
+    index_on:
+      - audit_complete
+      - review_complete
+    priority: low
+
+# =============================================================================
+# MEMORY OPERATIONS
+# =============================================================================
+
+operations:
+  # Save operations
+  save:
+    on_decision:
+      target: [state, session]
+      format:
+        date: ISO8601
+        content: structured
+      append_to: decisions.md
+
+    on_audit_complete:
+      target: [state, session]
+      compress: true
+      keep_fields:
+        - score
+        - critical_count
+        - high_count
+        - fixed_count
+        - top_issues
+
+    on_workflow_complete:
+      target: [session, state]
+      summarize: true
+      max_summary_tokens: 200
+
+    on_error_resolved:
+      target: [session]
+      log_solution: true
+
+  # Load operations
+  load:
+    on_session_start:
+      layers: [state, session]
+      max_tokens: 3000
+      prioritize: recent
+
+    on_context_request:
+      layers: [state]
+      specific_keys: true
+
+    on_semantic_search:
+      layers: [semantic]
+      top_k: 5
+      min_score: 0.85 # Research-backed: Microsoft Azure AI optimal threshold
+
+# =============================================================================
+# SUMMARIZATION STRATEGY
+# =============================================================================
+
+summarization:
+  strategy: hierarchical
+
+  triggers:
+    - token_threshold: 8000
+    - session_age_hours: 2
+    - workflow_count: 5
+
+  levels:
+    # Level 1: Light summarization
+    light:
+      trigger_tokens: 5000
+      actions:
+        - compress_old_interactions
+        - keep_last_5_exchanges
+
+    # Level 2: Medium summarization
+    medium:
+      trigger_tokens: 8000
+      actions:
+        - summarize_session_notes
+        - archive_resolved_errors
+        - keep_decisions_only
+
+    # Level 3: Aggressive summarization
+    aggressive:
+      trigger_tokens: 10000
+      actions:
+        - compress_all_to_summary
+        - keep_critical_only
+        - unload_all_optional
+
+# =============================================================================
+# CLEANUP RULES
+# =============================================================================
+
+cleanup:
+  triggers:
+    - on_workflow_switch
+    - on_phase_complete
+    - at_token_threshold
+    - on_session_end
+
+  rules:
+    on_workflow_switch:
+      - unload_previous_workflow_context
+      - keep_decisions
+      - keep_errors
+      - summarize_completed_work
+
+    on_phase_complete:
+      - archive_phase_artifacts
+      - update_state_json
+      - compress_phase_notes
+
+    at_token_threshold:
+      threshold: 10000
+      actions:
+        - trigger_medium_summarization
+        - unload_layer_semantic
+        - alert_user_if_critical
+
+    on_session_end:
+      - save_all_layers
+      - update_timestamps
+      - log_session_metrics
+
+# =============================================================================
+# CROSS-SESSION PERSISTENCE
+# =============================================================================
+
+cross_session:
+  enabled: true
+
+  persist:
+    - project_state
+    - decisions_log
+    - audit_history
+    - skill_preferences
+    - pending_tasks
+
+  restore_on_resume:
+    - last_workflow
+    - pending_tasks
+    - unresolved_errors
+    - active_branch
+
+  resume_command: "/recap"
+
+  handoff:
+    enabled: true
+    format: markdown
+    include:
+      - current_task
+      - context_summary
+      - pending_actions
+      - key_decisions
+
+# =============================================================================
+# MEMORY HOOKS
+# =============================================================================
+
+hooks:
+  pre_save:
+    - validate_json_schema
+    - check_token_budget
+    - sanitize_sensitive_data
+
+  post_save:
+    - update_timestamps
+    - log_metrics
+    - trigger_backup_if_needed
+
+  pre_load:
+    - check_file_exists
+    - validate_version
+    - migrate_if_needed
+
+  post_load:
+    - update_session_cache
+    - log_load_metrics
+    - check_staleness
+
+# =============================================================================
+# METRICS & MONITORING
+# =============================================================================
+
+metrics:
+  track:
+    - tokens_by_layer
+    - save_frequency
+    - load_latency
+    - compression_ratio
+    - decision_count
+    - audit_count
+
+  alerts:
+    high_token_usage:
+      threshold: 10000
+      action: warn_user
+
+    stale_state:
+      threshold_hours: 24
+      action: suggest_recap
+
+    frequent_errors:
+      threshold_count: 5
+      action: log_pattern
+
+# =============================================================================
+# INTEGRATION
+# =============================================================================
+
+integration:
+  token_loading:
+    sync: true
+    respect_budgets: true
+
+  flow_engine:
+    trigger_saves: true
+    trigger_loads: true
+
+  router:
+    provide_context: true
+    use_state_for_routing: true
+
+  workflows:
+    /recap:
+      load: [state, session, decisions]
+      display: summary
+
+    /audit:
+      save: [audit_summary, decisions]
+      update: state
+
+    /init:
+      create: [state, session]
+      reset: all