config.default.yaml

# ============================================================================
# ZettelForge Configuration — Reference Defaults
# ============================================================================
#
# Resolution order (highest priority wins):
#   1. Environment variables   → TYPEDB_HOST=db.internal
#   2. config.yaml             → copy this file, rename to config.yaml
#   3. config.default.yaml     → this file (checked into git)
#   4. Hardcoded defaults      → in src/zettelforge/config.py
#
# Usage:
#   cp config.default.yaml config.yaml   # create your local config
#   $EDITOR config.yaml                   # customize
#   # config.yaml is in .gitignore — safe for credentials
#
# Python access:
#   from zettelforge.config import get_config
#   cfg = get_config()
#   cfg.typedb.host       # "localhost"
#   cfg.retrieval.default_k  # 10
#
# ============================================================================


# ── Storage ─────────────────────────────────────────────────────────────────
# Where LanceDB vectors, JSONL notes, and entity indexes are persisted.
#
# Examples:
#   data_dir: ~/.amem                       # default — home directory
#   data_dir: /var/lib/zettelforge/data     # Linux system path
#   data_dir: /home/site/data               # Azure App Service mount
#   data_dir: C:\Users\analyst\zettelforge  # Windows
#
# Env override: AMEM_DATA_DIR=/data/zettelforge
#
storage:
  data_dir: ~/.amem


# ── TypeDB (Ontology Layer) ─────────────────────────────────────────────────
# STIX 2.1 knowledge graph server. Stores entities, relationships, aliases.
# Requires a running TypeDB container (see docker/docker-compose.yml).
#
# Examples:
#   # Local Docker (default)
#   host: localhost
#   port: 1729
#
#   # Remote server on your LAN
#   host: 192.168.1.50
#   port: 1729
#
#   # Azure Container Instance
#   host: zettelforge-typedb.eastus2.azurecontainer.io
#   port: 1729
#
# Credentials are required when using the TypeDB backend. Supply them via
# environment variables — never commit plaintext secrets to version control.
#
# Env overrides:
#   TYPEDB_HOST=db.internal
#   TYPEDB_PORT=1729
#   TYPEDB_DATABASE=zettelforge
#   TYPEDB_USERNAME=admin
#   TYPEDB_PASSWORD=s3cret
#
typedb:
  host: localhost
  port: 1729
  database: zettelforge
  username: ${TYPEDB_USERNAME}
  password: ${TYPEDB_PASSWORD}


# ── Storage Backend ────────────────────────────────────────────────────────
# Which backend to use for notes, knowledge graph, and entity index.
#
# Options:
#   backend: sqlite    # SQLite + LanceDB (default, zero config, ACID)
#   backend: typedb    # TypeDB (requires zettelforge-enterprise extension)
#
# Env override: ZETTELFORGE_BACKEND=sqlite
#
backend: sqlite


# ── Embeddings ──────────────────────────────────────────────────────────────
# Vector embeddings for semantic search.
#
# Provider options:
#   fastembed  — In-process ONNX (default). No server needed. 130MB model.
#                7ms per embed. Model auto-downloads on first use.
#   ollama     — HTTP server. Requires `ollama serve` running.
#                ~30ms per embed (HTTP round-trip).
#
# Examples:
#   # fastembed (default — zero server dependencies)
#   provider: fastembed
#   model: nomic-ai/nomic-embed-text-v1.5-Q     # 768-dim, quantized, 130MB
#   dimensions: 768
#
#   # fastembed full-precision (better quality, 520MB)
#   provider: fastembed
#   model: nomic-ai/nomic-embed-text-v1.5        # 768-dim, full, 520MB
#   dimensions: 768
#
#   # Ollama nomic-v2-moe (MoE architecture, better quality)
#   provider: ollama
#   url: http://127.0.0.1:11434
#   model: nomic-embed-text-v2-moe               # 768-dim, 1GB
#   dimensions: 768
#
#   # Ollama qwen3-embedding (highest quality, large)
#   provider: ollama
#   url: http://127.0.0.1:11434
#   model: qwen3-embedding                        # 4096-dim, 4.7GB
#   dimensions: 4096
#
# IMPORTANT: The `dimensions` field MUST match your embedding model's output.
# If you change the model, update dimensions and run rebuild_index.py to
# re-embed all existing notes. Mismatched dimensions will cause indexing
# errors and empty search results.
#
# Common model dimensions:
#   nomic-embed-text-v1.5-Q       → 768
#   nomic-embed-text-v2-moe       → 768
#   qwen3-embedding               → 4096
#   text-embedding-3-small (OpenAI) → 1536
#   mxbai-embed-large             → 1024
#
# Env overrides:
#   ZETTELFORGE_EMBEDDING_PROVIDER=ollama
#   ZETTELFORGE_EMBEDDING_DIM=4096
#   AMEM_EMBEDDING_URL=http://gpu-box:11434
#   AMEM_EMBEDDING_MODEL=nomic-embed-text-v2-moe
#
embedding:
  provider: fastembed
  url: http://127.0.0.1:11434
  model: nomic-ai/nomic-embed-text-v1.5-Q
  dimensions: 768


# ── LLM ─────────────────────────────────────────────────────────────────────
# Language model for fact extraction, intent classification, causal triple
# extraction, and RAG synthesis.
#
# Provider selects the backend registered in zettelforge.llm_providers:
#   local           — in-process LLM inference (see local_backend below; requires zettelforge[local] or zettelforge[local-onnx])
#   ollama          — Ollama HTTP API
#   litellm         — LiteLLM routing to 100+ providers (RFC-012; requires zettelforge[litellm])
#   mock            — test-only canned responses
#
# local_backend selects the in-process inference engine when provider=local:
#   llama-cpp-python     — GGUF models via llama-cpp-python (default; requires zettelforge[local])
#   onnxruntime-genai    — ONNX models via ONNX Runtime GenAI (requires zettelforge[local-onnx])
#
# Examples:
#   # Default — Ollama on localhost
#   provider: ollama
#   model: qwen3.5:9b
#
#   # In-process GGUF (fully offline)
#   provider: local
#   local_backend: llama-cpp-python
#   model: Qwen/Qwen2.5-3B-Instruct-GGUF
#
#   # In-process ONNX (AMD GPU via ROCm)
#   provider: local
#   local_backend: onnxruntime-genai
#   model: microsoft/Phi-3-mini-4k-instruct-onnx
#   extra:
#     filename: phi3-mini-4k-instruct-q4.onnx
#     provider: rocm            # cpu, cuda, dml, rocm, openvino, coreml
#
#   # LiteLLM — unified routing (requires pip install zettelforge[litellm])
#   # Model name determines the provider. Examples:
#   #   gpt-4o, gpt-4o-mini                      → OpenAI
#   #   claude-sonnet-4-20250514, claude-3-opus   → Anthropic
#   #   gemini/gemini-2.0-flash                   → Google Gemini
#   #   groq/llama-3.3-70b-versatile              → Groq
#   #   together_ai/meta-llama/Llama-3.3-70B      → Together AI
#   #   openrouter/anthropic/claude-3.5-sonnet    → OpenRouter
#   #   bedrock/anthropic.claude-3-sonnet         → AWS Bedrock
#   provider: litellm
#   model: gpt-4o
#   api_key: ${OPENAI_API_KEY}
#
# api_key supports ${ENV_VAR} references — never commit raw API keys.
#   api_key: ${OPENAI_API_KEY}
#
# fallback: name of a backup provider invoked on transient failure of
# the primary. Leave empty to preserve the implicit ``local -> ollama``
# fallback for backward compatibility.
#
# extra: provider-specific kwargs forwarded to the constructor. Examples:
#   extra:
#     filename: qwen2.5-3b-instruct-q4_k_m.gguf   # local provider
#     n_ctx: 4096
#
# Env overrides:
#   ZETTELFORGE_LLM_PROVIDER=ollama
#   ZETTELFORGE_LLM_MODEL=qwen2.5:7b
#   ZETTELFORGE_LLM_URL=http://gpu-box:11434
#   ZETTELFORGE_LLM_API_KEY=***
#   ZETTELFORGE_LLM_TIMEOUT=60
#   ZETTELFORGE_LLM_MAX_RETRIES=2
#   ZETTELFORGE_LLM_FALLBACK=ollama
#   ZETTELFORGE_LLM_LOCAL_BACKEND=onnxruntime-genai   # only when provider=local
#
llm:
  provider: ollama
  model: qwen3.5:9b
  url: http://localhost:11434
  api_key: ""
  temperature: 0.1
  timeout: 180.0  # v2.5.2: bumped from 60s for reasoning-model headroom
  max_retries: 2
  fallback: ""
  local_backend: llama-cpp-python  # used when provider=local (RFC-011)
  max_tokens: 400
  max_tokens_causal: 8000
  max_tokens_synthesis: 2500
  max_tokens_extraction: 2500
  max_tokens_ner: 2500
  max_tokens_evolve: 2500
  reasoning_model: false
  extra: {}


# ── Two-Phase Extraction Pipeline ──────────────────────────────────────────
# Controls the Mem0-style remember_with_extraction() pipeline.
# Phase 1: LLM extracts salient facts with importance scores.
# Phase 2: Each fact is compared to existing notes — ADD/UPDATE/DELETE/NOOP.
#
# Examples:
#   # Default — balanced
#   max_facts: 5
#   min_importance: 3
#
#   # Aggressive filtering (only keep the most important facts)
#   max_facts: 3
#   min_importance: 7
#
#   # Permissive (keep everything the LLM extracts)
#   max_facts: 10
#   min_importance: 1
#
extraction:
  max_facts: 5
  min_importance: 3


# ── LLM NER (Conversational Entity Extraction) ─────────────────────────────
# Always-on background LLM-based named entity recognition.
# Runs in the enrichment queue after every remember() call.
# Extracts person, location, organization, event, activity, temporal entities
# using the configured LLM provider, and merges with regex-extracted entities.
#
# Set enabled: false to disable (e.g., for performance testing, or when no
# LLM is available). Regex extraction always runs regardless of this setting.
#
# Env override: ZETTELFORGE_LLM_NER_ENABLED=false
#
llm_ner:
  enabled: true


# ── Retrieval ───────────────────────────────────────────────────────────────
# Controls how recall() finds and ranks relevant memories.
# Blended retrieval merges vector similarity + graph traversal results.
#
# Examples:
#   # Default — general purpose
#   default_k: 10
#   similarity_threshold: 0.25
#   entity_boost: 2.5
#   max_graph_depth: 2
#
#   # High precision (fewer, more relevant results)
#   default_k: 5
#   similarity_threshold: 0.50
#   entity_boost: 3.0
#   max_graph_depth: 1
#
#   # High recall (cast a wide net)
#   default_k: 25
#   similarity_threshold: 0.10
#   entity_boost: 1.5
#   max_graph_depth: 3
#
# similarity_threshold: minimum cosine similarity to include a result (0.0–1.0)
# entity_boost: multiplicative boost per overlapping entity between query and note
# max_graph_depth: how many hops to traverse in the knowledge graph
#
retrieval:
  default_k: 10
  similarity_threshold: 0.25
  entity_boost: 2.5
  max_graph_depth: 2


# ── Synthesis ───────────────────────────────────────────────────────────────
# Controls RAG answer generation from retrieved memories.
#
# Output formats:
#   direct_answer       — short factual response
#   synthesized_brief   — paragraph summary with sources
#   timeline_analysis   — chronological reconstruction
#   relationship_map    — entity relationship summary
#
# Tier filter controls which quality tiers of notes are included:
#   A = authoritative (high confidence, verified sources)
#   B = operational (working knowledge, moderate confidence)
#   C = support (low confidence, inferred, speculative)
#
# Examples:
#   # Default — include A and B tier notes
#   tier_filter: [A, B]
#
#   # Strict — only authoritative sources
#   tier_filter: [A]
#
#   # Permissive — include everything
#   tier_filter: [A, B, C]
#
synthesis:
  max_context_tokens: 3000
  default_format: direct_answer
  tier_filter:
    - A
    - B


# ── Governance ──────────────────────────────────────────────────────────────
# Validation rules applied before remember() and recall() operations.
# Enforces data classification, retention, access control, and audit logging.
#
# PII detection (RFC-013, optional) uses Microsoft Presidio to scan content
# for personally identifiable information before storage. Disabled by default.
# Requires: pip install zettelforge[pii]
#
# PII action options:
#   log       — detect and warn, pass content through unchanged
#   redact    — replace PII with [REDACTED] before storage
#   block     — raise exception if any PII is detected
#
# Examples:
#   # Production (default)
#   enabled: true
#   min_content_length: 1
#
#   # Testing / benchmarks (skip validation for speed)
#   enabled: false
#
#   # Strict (reject very short inputs)
#   enabled: true
#   min_content_length: 20
#
#   # PII log-only (see what PII flows through your pipeline)
#   enabled: true
#   min_content_length: 1
#   pii:
#     enabled: true
#     action: log
#
#   # PII redact (automatically remove PII before storage)
#   enabled: true
#   min_content_length: 1
#   pii:
#     enabled: true
#     action: redact
#
#   # PII block (strict — reject content with detected PII)
#   enabled: true
#   min_content_length: 1
#   pii:
#     enabled: true
#     action: block
#
# Env overrides:
#   ZETTELFORGE_PII_ENABLED=true
#   ZETTELFORGE_PII_ACTION=redact
#   ZETTELFORGE_LIMITS_MAX_CONTENT_LENGTH=104857600
#   ZETTELFORGE_LIMITS_RECALL_TIMEOUT=60
#   ZETTELFORGE_MEMORY_DEFENSE_ENABLED=true
#   ZETTELFORGE_MEMORY_DEFENSE_MODE=audit       # audit | block | quarantine
#   ZETTELFORGE_MEMORY_DEFENSE_MIN_CALIBRATION=50
#   ZETTELFORGE_MEMORY_DEFENSE_KAPPA=2.0
#
governance:
  enabled: true
  min_content_length: 1
  pii:
    enabled: false
    action: log
    redact_placeholder: "[REDACTED]"
    entities: []
    language: en
    nlp_model: en_core_web_sm
  limits:
    max_content_length: 52428800  # 50 MB, 0 = unlimited
    recall_timeout_seconds: 30.0  # seconds, 0 = unlimited
  memory_defense:
    enabled: true
    mode: audit  # audit | block | quarantine
    min_calibration_notes: 50
    max_reference_notes: 50
    kappa: 2.0
    lexical_weight: 0.25
    ngram_size: 3
    monitored_domains: []  # empty = all domains
    quarantine_path: ""  # default: <storage.data_dir>/quarantine/memory_anomalies.jsonl
    quarantine_raw_content: true


# ── LanceDB Maintenance (RFC-009 Phase 1.5) ─────────────────────────────────
# Background daemon that prunes stale LanceDB version-history per shard.
#
# Examples:
#   # Default — clean up every hour, keep versions < 1 hour old
#   cleanup_interval_minutes: 60
#   cleanup_older_than_seconds: 3600
#
#   # Aggressive cleanup (high-ingestion environments)
#   cleanup_interval_minutes: 15
#   cleanup_older_than_seconds: 600
#
#   # Disable cleanup entirely
#   cleanup_interval_minutes: 0
#
lance:
  cleanup_interval_minutes: 60
  cleanup_older_than_seconds: 3600


# ── Cache
# In-memory cache for TypeDB query results. Reduces round-trips for
# frequently accessed entities and relationships.
#
# Examples:
#   # Default — 5 minute TTL, 1024 entries
#   ttl_seconds: 300
#   max_entries: 1024
#
#   # Aggressive caching (high-throughput environments)
#   ttl_seconds: 600
#   max_entries: 4096
#
#   # Disable caching (always query TypeDB fresh)
#   ttl_seconds: 0
#   max_entries: 0
#
cache:
  ttl_seconds: 300
  max_entries: 1024


# ── Logging ─────────────────────────────────────────────────────────────────
# Controls what ZettelForge logs during operation.
#
# Levels: DEBUG, INFO, WARNING, ERROR
#
# Examples:
#   # Production (default)
#   level: INFO
#   log_intents: true
#   log_causal: true
#
#   # Quiet (errors only)
#   level: ERROR
#   log_intents: false
#   log_causal: false
#
#   # Debug (verbose, for development)
#   level: DEBUG
#   log_intents: true
#   log_causal: true
#
logging:
  level: INFO
  log_intents: true
  log_causal: true


# ── Web UI (RFC-015) ─────────────────────────────────────────────────────────
# ZettelForge Web Management Interface — SPA served at GET /.
#
# Examples:
#   # Default — enabled on 0.0.0.0:8088
#   enabled: true
#   host: 0.0.0.0
#   port: 8088
#
#   # Custom port (e.g., behind nginx reverse proxy)
#   enabled: true
#   host: 127.0.0.1
#   port: 9000
#
#   # Disable web UI entirely (library-only mode)
#   enabled: false
#
# Env overrides:
#   ZETTELFORGE_WEB_ENABLED=true
#   ZETTELFORGE_WEB_PORT=8088
#   ZETTELFORGE_WEB_UI_DIR=/path/to/ui
#
web:
  enabled: true
  host: 0.0.0.0
  port: 8088