reveriecore.yaml.example

# ReverieCore Framework Configuration
# This file defines the behavior of the memory engine's Enrichment and Retrieval pipelines.

# --- 1. Retrieval & RAG Configuration ---
# Controls how the engine finds, ranks, and filters memories for the agent.
retrieval:
  # Discovery Phase: Initial candidate selection.
  discovery:
    default_limit: 5      # Default number of memories to return if not specified.
    
    # Anchoring: High-recall keyword-based detection.
    anchoring:
      clean_slate_keywords: ["clean slate", "new idea", "fresh start", "fresh project"]
      
    # Vector Search: Semantic similarity thresholds.
    vector:
      precision_gate: 0.45       # Minimum similarity score (0.0 - 1.0).
      candidate_multiplier: 10   # Fetch (limit * multiplier) candidates for ranking.
      fallback_threshold: 3      # If fewer than this many results found, try fallback.
      
    # Graph Expansion: Discovering non-obvious context via relationships.
    graph_expansion:
      seed_limit: 4              # Max seeds to use for traversal.
      min_signal: 0.65           # Minimum edge weight to follow.
      discovery_boost: 0.8       # Score boost for memories found via graph.
    
    # Intent Classifier: Guidance for retrieval intent detection.
    intent_classifier:
      intent_strategy: "binary" # Aggressive: forces binary choice (Entailment vs Contradiction).
      confidence_threshold: 0.65 # Only apply intent-based filtering if confidence > X.
      mappings:
        "troubleshooting and root cause analysis": ["CAUSES", "DEPENDS_ON", "SUPPORTS"]
        "step-by-step instructions and prerequisites": ["PRECEDES", "FOLLOWS", "PREREQUISITE_FOR"]
        "general definition and conceptual mapping": ["IS_A", "PART_OF", "DEFINES", "MENTIONS"]

  # Query Rewriter: LLM-driven expansion and clarification. Activated by including "rewriter" in the retrieval pipeline.
  rewriter:
    model_path: "models/Phi-3-mini-4k-instruct-q4.gguf"
    device: "cpu"                # cpu or gpu
    threads: 2                   # CPU threads for inference
    max_words: 50                # Max word count for rewritten query

  # Ranking Phase: Multi-signal scoring and sorting.
  ranking:
    # Intent-Aware Weighting: Adjusts weights based on user query intent.
    intent:
      fact_markers: ["what is", "how ", "who ", "where ", "when ", "why ", "list ", "explain ", "identify"]
      weights:
        # fact_seeking: high similarity, low importance, low decay
        fact_seeking: {similarity: 0.7, importance: 0.1, decay: 0.2}
        # exploration: balanced similarity/importance
        exploration: {similarity: 0.4, importance: 0.4, decay: 0.2}
        
    # Scoring: Final composite score calculation.
    scoring:
      anchor_boost: 0.4           # Extra boost for high-level "Observation Anchor" nodes.
      graph_boost_multiplier: 0.5 # Weight of graph connectivity in final score.
      default_similarities: {anchor: 0.6, other: 0.4}
      
    # Temporal Decay: Prioritizes recent memories.
    decay:
      half_life_hours: 48.0       # Score halves every 48 hours.
      min_decay: 0.1              # Floor to ensure old but critical memories aren't lost.
    
    # Pruning Phase: Filters out noise immediately after re-ranking.
    pruning:
      top_n: 4                      # Max number of candidates allowed.
      relative_threshold: 0.2       # Discard results < X% of the top scorer's quality.
      min_absolute_score: 0.3       # Hard floor; discard anything below this.

  # Budgeting Phase: Final selection and token management.
  budget:
    relevance_floor: 0.2          # Memories below this score are dropped.
    default_token_budget: 1000    # Default max tokens for the injection block.
    labels:
      critical: 8.0               # Score cutoff for "CRITICAL" label.
      relevant: 4.0               # Score cutoff for "RELEVANT" label.


  # Reranking: Post-processing to boost high-confidence matches.
  rerank:
    rerank_boost: 3.0

  # Pipeline Composition: Defines the active handlers and their execution order.
  pipeline:
    discovery: ["intent_classifier", "anchoring", "vector", "graph_expansion"]
    ranking: ["intent", "scoring", "rerank", "pruning"]
    budget: ["budget"]

# --- 2. System Settings & Limits ---
# Global plugin configuration.
system:
  user_identity: "tom"            # Used for multi-tenant provenance.
  memory_char_limit: 32768        # Total char budget for prompt injection.
  
  # Telemetry (OpenTelemetry / Jaeger)
  # Allows tracking pipeline performance and debugging.
  telemetry:
    enabled: true                 # Set to false to completely disable OTel.
    # endpoint: "http://localhost:4318/v1/traces" # Custom OTLP collector URL.
    # protocol: "http/protobuf"     # Protocol: http/protobuf or http/json.
    # headers:                    # Optional headers (e.g. for Auth).
    #   Authorization: "Bearer your-token-here"
    #   X-Custom-Header: "value"
    # resource_attributes:        # Custom attributes for the tracer resource.
    #   environment: "local"
    # If endpoint is not reachable, telemetry will gracefully disable to prevent noise.


# --- 3. Maintenance & Pruning (Mesa) ---
# Background cleanup and optimization service.
maintenance:
  mesa:
    # Activation by Inclusion: List active stages. Empty list [] disables background maintenance.
    pipeline: ["soft_prune", "consolidate", "deep_clean"]
    dry_run: false                # If true, only logs actions without executing.
    interval_seconds: 3600        # Seconds between maintenance cycles.
    
    # Tier 1: Soft Prune & Consolidation
    centrality_threshold: 2       # Min connections to avoid archival.
    retention_days: 14            # Days before low-importance memories are archived.
    importance_cutoff: 4.0        # Score threshold for "stale" detection.
    consolidation_threshold: 5    # Shared entities required for hierarchical consolidation.
    
    # Tier 2: Deep Clean (Purge & Vacuum)
    purge_enabled: true           # Toggle permanent deletion of old archives.
    deep_clean_interval_days: 30  # Frequency of database VACUUM and purge.
    archive_retention_days: 90    # Days to keep ARCHIVED memories before deletion.
    
    # Pruning & Quality Floor
    pruning:
      retention_threshold: 0.4    # Min quality score to remain ACTIVE in DB.
      batch_size: 50              # Number of nodes processed per batch.

# --- 3. Ingestion & Enrichment Configuration ---
# Controls how new memories are processed, embedded, and summarized.
enrichment:
  # Classifier: Used for importance scoring and memory type detection.
  classifier:
    model: "MoritzLaurer/mDeBERTa-v3-base-mnli-xnli"
    intent_strategy: "trinary" # Conservative: allows "Neutral" to avoid false positives during ingestion.
  
  # Embedding: Vector model for semantic search.
  embedding:
    model: "BAAI/bge-small-en-v1.5"
  
  # Summarization: Model for generating memory abstracts.
  summarization:
    model: "sshleifer/distilbart-cnn-12-6"
  
  # Importance Scoring: Heuristic and model-driven importance detection.
  scoring:
    heuristics:
      importance_boost: 9.5
      keywords:
        error: ["error", "exception", "traceback", "failed", "crash", "broken", "bug"]
        urgency: ["deadline", "critical", "urgent", "asap", "priority", "important"]
        security: ["password", "secret", "api_key", "token", "auth", "credentials"]
        code: ["```", "def ", "class ", "import "]
        task: ["todo", "task", "goal"]
    weights:
      critical: 10.0
      important: 7.0
      minor: 3.0
      trivial: 1.0
  
  # Profiling & Retention: Controls summarization and pruning logic.
  profiling:
    min_word_count: 30            # Minimum words to trigger a summary abstract.
    max_summary_length: 150       # Max tokens for the abstract.
    summary_beams: 2
    retention:
      low_importance_threshold: 5.0 # Memories below this score are candidates for Mesa pruning.
      default_days: 7               # Default age before archiving low-importance memories.
  
  # Active Stages: Controls the enrichment pipeline execution.
  pipeline:
    active_stages: ["heuristics", "classifier", "model_importance", "soul_importance"]