config.example.yaml

# Mnemonic Configuration File
# Copy this file to config.yaml and adjust for your machine:
#   cp config.example.yaml config.yaml
# All paths support ~ expansion for home directory

# Project Registry
# Maps directory paths and aliases to canonical project names.
# The resolver ensures consistent naming regardless of working directory.
projects:
  - name: "mnemonic"
    paths:
      - "~/Projects/mem"
    aliases:
      - "mem"
      - "sdk"
      - "mnemonic-sdk"

# LLM Provider Configuration
# Supports any OpenAI-compatible API (LM Studio, Google Gemini, etc.)
# For authenticated providers, set the LLM_API_KEY environment variable.
llm:
  # Endpoint URL for the LLM API
  # LM Studio (local):  "http://localhost:1234/v1"
  # Google Gemini:       "https://generativelanguage.googleapis.com/v1beta/openai"
  endpoint: "http://localhost:1234/v1"

  # Model name for chat/conversation
  # LM Studio:  "qwen/qwen3.5-9b"
  # Gemini:     "gemini-3-flash-preview"
  chat_model: "qwen/qwen3.5-9b"

  # Model name for embeddings
  # LM Studio:  "text-embedding-embeddinggemma-300m-qat"
  # Gemini:     "gemini-embedding-2-preview"
  embedding_model: "text-embedding-embeddinggemma-300m-qat"

  # Maximum tokens in model responses (thinking models need headroom for reasoning)
  max_tokens: 8192

  # Temperature for sampling (0.0 = deterministic, 2.0 = more random)
  temperature: 0.3

  # Request timeout in seconds (needs headroom for tool-use synthesis)
  timeout_sec: 120

  # Maximum simultaneous LLM requests (local models: 2, cloud APIs: 5+)
  max_concurrent: 8

# Storage Configuration
store:
  # Path to SQLite database file
  db_path: "~/.mnemonic/memory.db"

  # Journal mode: "delete" (default), "wal" (write-ahead logging, recommended)
  journal_mode: "wal"

# Memory Configuration
memory:
  # Maximum number of memories in working memory (higher = richer context per query)
  max_working_memory: 12

# Perception Configuration
perception:
  # Enable all perception modules
  enabled: true

  # LLM gating: send each event to the LLM for a "worth remembering?" decision.
  # When false (recommended), only the fast heuristic filter is used.
  llm_gating_enabled: false

  # Filesystem perception (watches for file changes)
  filesystem:
    enabled: true

    # Directories to watch for changes
    # Watch the full home directory for comprehensive awareness
    watch_dirs:
      - "~/Projects"

    # Glob patterns to exclude from perception
    # These use substring matching — any path containing the pattern is excluded.
    exclude_patterns:
      # --- Version control & package managers ---
      - ".git/"
      - "node_modules/"
      - ".npm/"
      - ".cache/"
      - "__pycache__/"
      - ".DS_Store"

      # --- Python virtual environments & build artifacts ---
      - "venv/"
      - ".venv/"
      - "site-packages/"
      - ".tox/"
      - ".eggs/"
      - ".mypy_cache/"
      - ".ruff_cache/"
      - ".pytest_cache/"

      # --- ML experiment logs ---
      - "wandb/"

      # --- macOS Library (all app/system internal state) ---
      - "/Library/"

      # --- macOS app bundles (binary data, not useful as memories) ---
      - ".photoslibrary/"
      - ".app/"
      - ".appex/"
      - ".musiclibrary/"
      - ".fcpbundle/"
      - ".maildownload/"
      - ".imapmessages/"

      # --- Trash & system ---
      - ".Trash/"
      - "/.Spotlight-"
      - ".localized"
      - ".CFUserTextEncoding"

      # --- App internal state ---
      - ".lmstudio/"
      - ".vscode/"
      - ".idea/"
      - ".mnemonic/"
      - ".claude/"
      - ".claude.json"
      - "evolution/conversations/"
      - "evolution/sessions.json"

      # --- Linux desktop/app internal state ---
      - ".config/Code/"
      - ".config/google-chrome/"
      - ".config/chromium/"
      - ".config/BraveSoftware/"
      - ".config/gtk-"
      - ".config/dbus-"
      - ".local/share/gnome-shell/"
      - ".local/share/Trash/"
      - ".local/state/wireplumber/"
      - "/dconf/"
      - "/gconf/"
      - "/pulse/"
      - "/pipewire/"
      - ".copilot/"
      - ".github-copilot/"
      - "/snap/"
      - ".egg-info/"

    # Maximum file content size to process (in bytes) — Gemini has 1M+ context
    max_content_bytes: 524288

    # --- Attention-based watching (Linux only, ignored on macOS) ---
    # Hard cap on inotify watches to prevent starving VS Code and other apps.
    # Linux default inotify limit is 65536; we leave headroom for other apps.
    max_watches: 20000

    # How deep to add inotify watches at startup (shallow = fast, safe).
    # Deeper directories are polled in the background instead.
    shallow_depth: 5

    # How often (seconds) to poll cold (non-inotify) directories for changes.
    poll_interval_sec: 45

    # How many changes in a poll window before promoting a cold dir to inotify.
    promotion_threshold: 3

    # Minutes of inactivity before an inotify watch is demoted back to polling.
    demotion_timeout_min: 30

  # Git perception (monitors git repos for working tree changes)
  # Provides richer context than raw filesystem events and uses zero inotify watches.
  git:
    enabled: true
    poll_interval_sec: 45
    max_repo_depth: 3

  # Terminal perception (captures shell commands and output)
  terminal:
    enabled: true

    # Shell to monitor: "auto" (detect from env), "bash", "zsh", etc.
    shell: "auto"

    # Poll interval in seconds
    poll_interval_sec: 10

    # Patterns to exclude from perception
    exclude_patterns:
      - "^cd "
      - "^ls "
      - "^pwd$"

  # Clipboard perception (monitors clipboard changes)
  clipboard:
    enabled: false

    # Poll interval in seconds
    poll_interval_sec: 5

    # Maximum clipboard content size (in bytes)
    max_content_bytes: 102400

  # Heuristics for filtering perceived content
  heuristics:
    # Minimum content length to consider (characters)
    min_content_length: 10

    # Maximum content length to consider (characters)
    max_content_length: 100000

    # Frequency threshold (how many times to see content before encoding)
    # Lower = more memories captured; higher = only repeated patterns
    frequency_threshold: 2

    # Frequency window in minutes
    frequency_window_min: 15

# Encoding Configuration
encoding:
  # Enable semantic encoding of memories
  enabled: true

  # Maximum number of concepts to extract per memory
  max_concepts: 8

  # Limit for similarity search results
  find_similar_limit: 5

  # Enable contextual encoding using surrounding memories
  enable_contextual_encoding: true

  # Number of preceding memories to use for context
  context_lookback_count: 5

  # Number of semantically similar memories to include as context
  context_semantic_count: 3

  # Maximum concurrent encoding goroutines (cloud APIs can handle more parallelism)
  max_concurrent_encodings: 6

  # Enable LLM-based association type classification (similar → caused_by, part_of, etc.)
  enable_llm_classification: true

  # Maximum tokens for encoding LLM completions (higher = more room for structured JSON output)
  completion_max_tokens: 1024

  # Controlled vocabulary for concept extraction.
  # The LLM is instructed to prefer these exact terms so similar memories share matching tags.
  # Add domain-specific terms for your workflow. Remove terms you don't care about.
  # Leave empty to allow fully free-form concept generation.
  concept_vocabulary:
    - go
    - python
    - javascript
    - typescript
    - sql
    - bash
    - html
    - css
    - docker
    - git
    - linux
    - macos
    - systemd
    - build
    - ci
    - deployment
    - debugging
    - testing
    - refactoring
    - configuration
    - migration
    - documentation
    - review
    - api
    - database
    - filesystem
    - networking
    - security
    - authentication
    - performance
    - logging
    - ui
    - cli
    - memory
    - encoding
    - retrieval
    - embedding
    - agent
    - llm
    - daemon
    - mcp
    - watcher
    - decision
    - error
    - fix
    - insight
    - learning
    - planning
    - research
    - dependency
    - schema
    - config

# Consolidation Configuration
consolidation:
  # Enable memory consolidation
  enabled: true

  # Consolidation interval (e.g., "1h", "6h", "24h")
  interval: "1h"

  # Decay rate for memory strength (0.0-1.0)
  decay_rate: 0.95

  # Threshold below which memories fade away (0.0-1.0)
  fade_threshold: 0.3

  # Threshold below which memories are archived (0.0-1.0)
  archive_threshold: 0.1

  # Upper bound applied in salience decay. Encoding clamps new memories to
  # [0, 1.0]; without a matching ceiling here, post-decay attribute boosts
  # (satisfying+success, frustrating) compound above 1.0 and strand memories
  # above the fade threshold forever. Set <= 0 to disable. Default: 1.0.
  salience_ceiling: 1.0

  # Retention window before permanent deletion (e.g., "90d", "6w")
  retention_window: "90d"

  # Maximum memories to process per consolidation cycle
  max_memories_per_cycle: 100

  # Maximum merge operations per consolidation cycle
  max_merges_per_cycle: 5

  # Minimum cluster size for merging memories
  min_cluster_size: 3

  # Archive non-MCP memories with 0 recalls after this many days (0 = disabled)
  never_recalled_archive_days: 30

# Retrieval Configuration
retrieval:
  # Maximum hops in associative retrieval graph
  max_hops: 3

  # Activation threshold for memory retrieval (0.0-1.0)
  activation_threshold: 0.1

  # Decay factor for activation spreading (0.0-1.0)
  decay_factor: 0.7

  # Maximum results to return from retrieval
  max_results: 10

  # Maximum tool invocations per synthesis
  max_tool_calls: 8

  # Maximum tokens per synthesis LLM call (needs headroom for thinking models)
  synthesis_max_tokens: 2048

  # Weight of embedding vs FTS in score merge (0.0-1.0; higher = more embedding weight)
  merge_alpha: 0.6

  # Bonus for memories found by both FTS and embedding search
  dual_hit_bonus: 0.15

  # Weight of user feedback in ranking (0.0-1.0).
  # Memories rated "helpful" get +feedback_weight, "irrelevant" get -feedback_weight.
  feedback_weight: 0.15

  # Per-source multipliers for unfiltered recall.
  # Noisier sources (filesystem, clipboard) are down-weighted relative to MCP memories.
  # Unknown sources default to 1.0.
  source_weights:
    mcp: 1.0
    terminal: 0.8
    clipboard: 0.6
    filesystem: 0.5

# Metacognition Configuration
metacognition:
  # Enable metacognitive reflection
  enabled: true

  # Reflection interval (e.g., "4h", "24h")
  interval: "4h"

# Dreaming Configuration (memory replay / REM-like consolidation)
dreaming:
  # Enable dreaming agent
  enabled: true

  # Interval between dream cycles (e.g., "1h", "3h")
  interval: "1h"

  # Number of memories to replay per cycle
  batch_size: 60

  # Minimum salience threshold for replay (0.0-1.0)
  salience_threshold: 0.3

  # Multiplier for association strength during replay (>1.0 = strengthen)
  association_boost_factor: 1.15

  # Salience threshold below which dead memories get demoted (0.0-1.0)
  noise_prune_threshold: 0.15

# Episoding Configuration (groups raw events into fixed time-window episodes)
episoding:
  # Enable episoding agent
  enabled: true

  # Fixed episode window size in minutes — events are batched into this window
  # then synthesized by the LLM when the window closes
  episode_window_size_min: 10

  # Minimum number of events to synthesize an episode (below this, episode is
  # closed without LLM synthesis to save resources)
  min_events_per_episode: 2

# Abstraction Configuration (synthesizes principles and axioms from patterns)
abstraction:
  # Enable abstraction agent
  enabled: true

  # Interval between abstraction cycles (e.g., "2h", "6h")
  interval: "2h"

  # Minimum pattern strength to consider for principle synthesis (0.0-1.0)
  # Patterns start at 0.5. Setting to 0.5 lets any non-decayed pattern qualify —
  # the consolidation concept gates (PRs #412/#414) keep junk out at pattern
  # creation time, so trusting patterns at the starting line is fine.
  min_strength: 0.5

  # Maximum LLM calls per abstraction cycle
  max_llm_calls: 10

  # Archive escape hatch for chronically-demoted abstractions.
  # Each abstraction carries a demotion_streak counter incremented on any
  # grounding-verification cycle where the grounding ratio falls below the
  # "healthy" threshold (0.5) and reset to 0 on any healthy cycle. When the
  # streak reaches archive_demotion_streak AND the abstraction's confidence
  # has decayed below archive_decay_confidence AND the abstraction is past
  # the 7-day young-grace window, it is moved to "archived" — breaking the
  # otherwise-endless demote-forever loop for abstractions stuck in the
  # 0.1-0.3 grounding band. Streak-based rather than age-based so the exit
  # remains correct under adaptive-scheduler cadence.
  archive_decay_confidence: 0.2
  archive_demotion_streak: 10

# Orchestrator Configuration (autonomous scheduler and health monitoring)
orchestrator:
  # Enable orchestrator
  enabled: true

  # Dynamically adjust agent intervals based on system load
  adaptive_intervals: true

  # Maximum database size in MB before triggering consolidation
  max_db_size_mb: 500

  # Interval between retrieval self-tests (e.g., "6h", "12h")
  self_test_interval: "12h"

  # Automatically restart failed agents
  auto_recovery: true

  # Interval between health monitoring checks (e.g., "5m", "15m")
  monitor_interval: "5m"

# MCP Server Configuration (Model Context Protocol for AI agents)
mcp:
  # Enable MCP server (run with: mnemonic mcp)
  enabled: true

# Agent SDK Configuration (self-evolving coding assistant)
agent_sdk:
  # Enable Agent SDK dashboard integration
  enabled: true

  # Path to the agent's evolution directory (principles, strategies, changelog)
  evolution_dir: "./sdk/agent/evolution"

  # Port for the Python WebSocket chat server (default: 9998)
  web_port: 9998

# Training Data Capture
# Captures full LLM request/response pairs as JSONL for fine-tuning a bespoke local model.
# Data is written to capture_dir as daily JSONL files (e.g., capture_2026-03-17.jsonl).
# Enable this when you want to collect training data from the running daemon.
training:
  capture_enabled: false
  capture_dir: "~/.mnemonic/training-data"

# Coaching Configuration (Claude teaches the local LLM)
coaching:
  # Path to the YAML file Claude writes to improve local LLM prompts.
  # Both the daemon and MCP server read this file on startup.
  coaching_file: "~/.mnemonic/coaching.yaml"

# API Server Configuration
api:
  # Bind address
  host: "127.0.0.1"

  # Port number
  port: 9999

  # Request timeout in seconds
  request_timeout_sec: 180

# Web UI Configuration
web:
  # Enable web UI
  enabled: true

# Logging Configuration
logging:
  # Log level: "debug", "info", "warn", "error"
  level: "info"

  # Output format: "json" or "text"
  format: "json"

  # Log file path (leave empty for stdout only)
  file: "~/.mnemonic/mnemonic.log"