palinode.config.yaml.example

# =============================================================================
# Palinode Configuration
# =============================================================================
# Copy this file to `palinode.config.yaml` in your Palinode directory.
# All values shown are defaults — only override what you need.

# -----------------------------------------------------------------------------
# Memory Directory
# -----------------------------------------------------------------------------
# Where Palinode stores markdown memory files and the SQLite-vec index.
# All paths below are relative to this directory unless absolute.
#
# Leave `memory_dir` commented out to inherit the PALINODE_DIR environment
# variable — this is the recommended setup. The Quick Start exports
# `PALINODE_DIR=~/.palinode`, and PALINODE_DIR overrides `memory_dir` at load
# time; setting `memory_dir` here too only invites the two to disagree (files
# write to one directory while the DB attaches to another, and search silently
# returns nothing). Uncomment and set an absolute path only if you are NOT
# using PALINODE_DIR.
# memory_dir: "~/.palinode"

# SQLite-vec database location (relative to memory_dir)
db_path: ".palinode.db"

# -----------------------------------------------------------------------------
# Capture (mechanical cross-linking during indexing)
# -----------------------------------------------------------------------------
capture:
  cross_refs:
    enabled: true
    # Floor below which a bare slug/title token is NOT matched in prose, to
    # avoid false-positive substring hits on short names.
    min_token_len: 6

# -----------------------------------------------------------------------------
# Ingestion Pipeline
# -----------------------------------------------------------------------------
ingestion:
  # Inbox directory for dropped files (relative to memory_dir)
  inbox_dir: "inbox/raw"
  processed_dir: "inbox/processed"

  # Maximum characters to extract from PDFs
  pdf_max_chars: 10000
  # Maximum characters to extract from URLs
  url_max_chars: 10000

  # Transcriptor API for audio/video files
  transcriptor:
    url: "http://localhost:8787"
    timeout_seconds: 600

# -----------------------------------------------------------------------------
# Embeddings
# -----------------------------------------------------------------------------
embeddings:
  # Embedding backend (Ollama)
  primary:
    model: "bge-m3"
    url: "http://localhost:11434"
    dimensions: 1024
    # Timeout for first call (model loading)
    timeout_seconds: 120
    connect_timeout_seconds: 10

# -----------------------------------------------------------------------------
# Auto-Summary
# -----------------------------------------------------------------------------
auto_summary:
  enabled: true
  # Model used for generating summaries (should be fast and small)
  model: "qwen2.5:14b-instruct"
  # Maximum summary length in characters
  max_chars: 120
  # Minimum content length to trigger summary generation
  min_content_chars: 200
  # Wire protocol for the CHAT *primary* (model @ ollama_url):
  #   "ollama" (default) — Ollama-native /api/generate.
  #   "openai"           — an OpenAI-compatible /v1/chat/completions endpoint
  #                        (LM Studio, vLLM, a shim). Use when the primary is e.g.
  #                        an MLX model served by LM Studio. With "openai", ANY
  #                        primary failure cascades to llm_fallbacks (a remote
  #                        primary's connect drop is what backups exist for).
  # api: "openai"
  # Ollama URL for summary generation (uses embeddings.primary.url if not set).
  # When api: "openai" this is the OpenAI-compat base URL of the primary.
  # ollama_url: "http://localhost:11434"
  # OpenAI-compat fallback chain for the CHAT role (auto-description/-summary),
  # walked in order on primary failure. Only fires on the watcher-driven
  # /generate-summaries backfill — never the /save hot path — so enrichment still
  # lands during a primary outage without egressing on every save. Empty (the
  # default) = no fallback. Each entry is an OpenAI-compat /v1/chat/completions
  # endpoint. Example ladder (LM Studio MLX primary → local vLLM → Sonnet shim):
  # api: "openai"
  # model: "qwen3-coder-30b-a3b-instruct-dwq"
  # ollama_url: "http://lmstudio-host:1234"     # LM Studio (e.g. a Mac Studio)
  # llm_fallbacks:
  #   - model: "qwen-coder"                     # local vLLM (fast, on-LAN)
  #     url: "http://vllm-host:8000"
  #   - model: "claude-sonnet-4-6"              # label only; shim sets SHIM_MODEL
  #     url: "http://127.0.0.1:4010"            # local Sonnet shim (last resort)
  # Per-/generate-summaries-run cap on how many deferred files may escalate to the
  # fallback chain, bounding egress (esp. to the Sonnet link) when the primary is
  # down and one backfill spans a large backlog. 0 = unlimited. Only applies with
  # llm_fallbacks.
  # llm_fallback_max_per_run: 10

# -----------------------------------------------------------------------------
# Search Defaults
# -----------------------------------------------------------------------------
search:
  # Hybrid search combines vector similarity with BM25 keyword matching.
  # This catches exact terms (model names, IDs, code) that vectors miss.
  hybrid_enabled: true
  # Balance: 0.0 = vector only, 1.0 = BM25 only, 0.5 = equal weight
  hybrid_weight: 0.5
  # Default threshold for MCP server searches (lower = more results)
  mcp_threshold: 0.4
  # Default threshold for FastAPI searches (higher = more precision)
  api_threshold: 0.6
  # Default number of results
  default_limit: 10
  # Status values to exclude from search results
  exclude_status:
    - "archived"

# -----------------------------------------------------------------------------
# Consolidation
# -----------------------------------------------------------------------------
# Three-tier memory freshness:
#   Tier 1: Session append — free, every session exit (hook or MCP call).
#           Appends summary to daily/{date}.md + one-liner to projects/{slug}-status.md.
#   Tier 2: Nightly dedup — lightweight LLM pass over today's notes.
#           UPDATE/SUPERSEDE only. No restructuring, no archival.
#   Tier 3: Weekly deep clean — full compaction with MERGE/ARCHIVE.
#           Restructures status files, archives processed daily notes.
#
# HOW TO INSTALL CRON JOBS:
#   # Nightly — lightweight dedup of today's sessions (Tier 2)
#   0 11 * * * cd /path/to/palinode && PALINODE_DIR=/path/to/data \
#     venv/bin/python -m palinode.consolidation.cron --nightly --days 1 \
#     >> /path/to/data/logs/consolidation.log 2>&1
#
#   # Weekly — full compaction (Tier 3)
#   0 11 * * 0 cd /path/to/palinode && PALINODE_DIR=/path/to/data \
#     venv/bin/python -m palinode.consolidation.cron --days 3 \
#     >> /path/to/data/logs/consolidation.log 2>&1
#
# TIMING NOTES:
#   - Times above are UTC. Adjust for your timezone (11:00 UTC = 4am PT).
#   - Nightly runs daily; weekly runs Sundays. On Sundays both fire —
#     nightly first (UPDATE/SUPERSEDE), then weekly (full ops). No conflict.
#   - The `schedule` field below is informational only — actual scheduling
#     is via crontab, systemd timers, or your preferred scheduler.
#
consolidation:
  enabled: true
  # Informational — actual schedule lives in crontab (see above)
  schedule: "0 11 * * 0"  # Sunday 4am PT (11:00 UTC)
  # How many days of daily notes to process (weekly full pass)
  lookback_days: 7

  # LLM API for consolidation (any OpenAI-compatible endpoint)
  llm_url: "http://localhost:8000"  # vLLM, Ollama, etc.
  # llm_model: model path or identifier for your LLM backend
  # Examples:
  #   vLLM:   "/model" (default path)
  #   Ollama: "llama3.1:8b" or "qwen2.5:14b-instruct"
  llm_model: "/model"
  llm_temperature: 0.3
  llm_max_tokens: 2000

  # Which operations the weekly full pass may apply. The nightly pass has
  # its own, separately-scoped restriction below (nightly.allowed_ops) —
  # this one only governs the weekly pass.
  allowed_ops: ["KEEP", "UPDATE", "MERGE", "SUPERSEDE", "ARCHIVE", "RETRACT"]

  # Nightly pass configuration (Tier 2)
  nightly:
    enabled: true
    # How many days to look back (1 = today only)
    lookback_days: 1
    # Restrict to safe, additive operations — no cross-date restructuring.
    # MERGE is allowed but the executor enforces a same-day guard: only facts
    # sharing the same [YYYY-MM-DD] date prefix may be merged in a nightly run.
    # Cross-date or undated MERGE proposals are rejected with a log warning.
    allowed_ops: ["UPDATE", "SUPERSEDE", "MERGE"]

  # Write-time contradiction check (Tier 2a — ADR-004)
  # When enabled, every palinode_save schedules a background contradiction check
  # against the top-k most similar existing memories. Validated updates are
  # applied in a separate commit.
  # Runs asynchronously — never blocks the save caller.
  #
  # Default: disabled. Flip to true after validating in a dev environment.
  # Sync opt-in: set query param ?sync=true on /save or pass --sync to CLI.
  write_time:
    enabled: false
    queue_max_size: 1000
    check_timeout_seconds: 30
    pending_dir: ".palinode/pending"
    sweep_on_startup: true

  # Optional: map project entity refs to keywords for auto-grouping
  # daily notes that don't contain explicit `project/foo` entity refs.
  # keyword_map:
  #   "project/my-app": ["my-app", "MyApp", "the app"]

# -----------------------------------------------------------------------------
# Compaction
# -----------------------------------------------------------------------------
compaction:
  # Layer split heuristics — these keywords classify ## section headings
  # into Identity (slow-changing) vs Status (fast-changing) layers.
  #
  # HOW THESE WERE DETERMINED:
  # Initial guesses based on common markdown heading conventions.
  # Not scientifically derived — tune them to match your actual file structure.
  #
  # HOW TO EVOLVE THEM:
  # 1. Run: curl -X POST http://localhost:6340/split-layers
  # 2. Run: git -C ~/palinode-data diff  (see what was classified)
  # 3. Add/remove keywords below to correct misclassifications
  # 4. Or: add `layer_hint: status` to a file's frontmatter to force-override
  #
  layer_split:
    identity_keywords:
      - "architecture"
      - "context"
      - "people"
      - "canon"
      - "what this is"
      - "key decisions"
      - "overview"
      - "about"
      - "design"
      - "stack"
      - "key files"
      - "follow-up"
      - "who"
      - "background"
      - "principles"
    status_keywords:
      - "current"
      - "status"
      - "milestone"
      - "active"
      - "this week"
      - "open"
      - "consolidation log"
      - "todo"
      - "in progress"
      - "recent"
      - "progress"
      - "now"
      - "today"
      - "next"
      - "blocking"
    # Fallback: sections with a date like 2026-03-29 → Status
    date_pattern: "\\d{4}-\\d{2}-\\d{2}"

# -----------------------------------------------------------------------------
# Temporal Decay
# -----------------------------------------------------------------------------
# Gates the demand-decay importance re-rank band in hybrid search (a memory's
# effective importance decays toward baseline the longer it goes unread).
decay:
  enabled: false

# -----------------------------------------------------------------------------
# Services
# -----------------------------------------------------------------------------
services:
  # FastAPI server
  api:
    host: "127.0.0.1"  # SECURITY: bind to localhost only. Set to 0.0.0.0 only if you need LAN access.
    port: 6340
    log_level: "INFO"

  # File watcher daemon
  watcher:
    # Debounce: ignore rapid file changes within this window
    debounce_seconds: 1.0

# -----------------------------------------------------------------------------
# Git Integration
# -----------------------------------------------------------------------------
git:
  # Auto-commit after saves
  auto_commit: true
  # Auto-push after commits (requires remote configured)
  auto_push: false
  # Commit message prefix
  commit_prefix: "palinode"

# -----------------------------------------------------------------------------
# Logging
# -----------------------------------------------------------------------------
logging:
  # JSONL operation log (relative to memory_dir)
  operations_log: "logs/operations.jsonl"
  # Log to stdout as well
  console: true