config.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/Entrolution/causantic/main/config.schema.json",
  "title": "Causantic Configuration",
  "description": "Configuration schema for Causantic",
  "type": "object",
  "properties": {
    "clustering": {
      "type": "object",
      "description": "HDBSCAN clustering settings",
      "properties": {
        "threshold": {
          "type": "number",
          "minimum": 0.01,
          "maximum": 0.5,
          "default": 0.1,
          "description": "Angular distance threshold for cluster assignment"
        },
        "minClusterSize": {
          "type": "integer",
          "minimum": 2,
          "maximum": 100,
          "default": 4,
          "description": "Minimum points required to form a cluster"
        },
        "incrementalThreshold": {
          "type": "number",
          "minimum": 0.01,
          "maximum": 1,
          "default": 0.3,
          "description": "Ratio of new chunks (vs total at last full recluster) that triggers a full recluster. 0.3 = 30%."
        }
      },
      "additionalProperties": false
    },
    "traversal": {
      "type": "object",
      "description": "Chain walking settings",
      "properties": {
        "maxDepth": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 50,
          "description": "Safety cap on chain walking depth"
        }
      },
      "additionalProperties": false
    },
    "tokens": {
      "type": "object",
      "description": "Token budget settings",
      "properties": {
        "claudeMdBudget": {
          "type": "integer",
          "minimum": 100,
          "maximum": 10000,
          "default": 500,
          "description": "Token budget for CLAUDE.md memory section"
        },
        "mcpMaxResponse": {
          "type": "integer",
          "minimum": 500,
          "maximum": 50000,
          "default": 20000,
          "description": "Maximum tokens for MCP tool responses"
        }
      },
      "additionalProperties": false
    },
    "storage": {
      "type": "object",
      "description": "Storage paths",
      "properties": {
        "dbPath": {
          "type": "string",
          "default": "~/.causantic/memory.db",
          "description": "Path to SQLite database file (~ expands to home)"
        },
        "vectorPath": {
          "type": "string",
          "default": "~/.causantic/vectors",
          "description": "Path to LanceDB vector store directory"
        }
      },
      "additionalProperties": false
    },
    "llm": {
      "type": "object",
      "description": "LLM settings for optional features",
      "properties": {
        "clusterRefreshModel": {
          "type": "string",
          "default": "claude-3-haiku-20240307",
          "description": "Model to use for cluster description refresh"
        },
        "refreshRateLimitPerMin": {
          "type": "integer",
          "minimum": 1,
          "maximum": 1000,
          "default": 30,
          "description": "Rate limit for LLM refresh calls per minute"
        },
        "enableLabelling": {
          "type": "boolean",
          "default": true,
          "description": "Enable LLM-based cluster labelling. Requires Anthropic API key. Set to false for fully local usage without an API key."
        }
      },
      "additionalProperties": false
    },
    "encryption": {
      "type": "object",
      "description": "Database encryption settings",
      "properties": {
        "enabled": {
          "type": "boolean",
          "default": false,
          "description": "Enable database encryption at rest"
        },
        "cipher": {
          "type": "string",
          "enum": ["chacha20", "sqlcipher"],
          "default": "chacha20",
          "description": "Encryption cipher (chacha20 is 2-3x faster on ARM)"
        },
        "keySource": {
          "type": "string",
          "enum": ["keychain", "env", "prompt"],
          "default": "keychain",
          "description": "Where to get encryption key: keychain (OS secret store), env (CAUSANTIC_DB_KEY), prompt (CLI only)"
        },
        "auditLog": {
          "type": "boolean",
          "default": false,
          "description": "Log database access attempts to ~/.causantic/audit.log"
        }
      },
      "additionalProperties": false
    },
    "vectors": {
      "type": "object",
      "description": "Vector storage settings",
      "properties": {
        "ttlDays": {
          "type": "integer",
          "minimum": 1,
          "maximum": 3650,
          "default": 90,
          "description": "TTL in days for vectors. Vectors accessed within this period are kept."
        },
        "maxCount": {
          "type": "integer",
          "minimum": 0,
          "maximum": 10000000,
          "default": 0,
          "description": "Maximum number of vectors to keep. Oldest by last_accessed are evicted. 0 = unlimited."
        }
      },
      "additionalProperties": false
    },
    "embedding": {
      "type": "object",
      "description": "Embedding inference settings",
      "properties": {
        "device": {
          "type": "string",
          "enum": ["auto", "coreml", "cuda", "cpu", "wasm"],
          "default": "auto",
          "description": "Device for embedding inference. 'auto' detects hardware capabilities."
        },
        "model": {
          "type": "string",
          "enum": ["jina-small", "nomic-v1.5", "jina-code", "bge-small"],
          "default": "jina-small",
          "description": "Embedding model. Changing model requires running 'npx causantic reindex' to re-embed all chunks."
        },
        "eager": {
          "type": "boolean",
          "default": false,
          "description": "Embed chunks eagerly during ingestion. When false, chunks are stored without vectors."
        }
      },
      "additionalProperties": false
    },
    "maintenance": {
      "type": "object",
      "description": "Maintenance schedule settings",
      "properties": {
        "clusterHour": {
          "type": "integer",
          "minimum": 0,
          "maximum": 23,
          "default": 2,
          "description": "Hour of day (0-23) to run reclustering. Prune and cleanup run 1h and 1.5h after."
        }
      },
      "additionalProperties": false
    },
    "retrieval": {
      "type": "object",
      "description": "Search retrieval pipeline settings",
      "properties": {
        "mmrLambda": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "default": 0.7,
          "description": "MMR lambda: 0 = pure diversity, 1 = pure relevance"
        },
        "feedbackWeight": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "default": 0.1,
          "description": "How much retrieval feedback influences cluster expansion scoring. 0 = disabled, 1 = maximum influence."
        },
        "primary": {
          "type": "string",
          "enum": ["keyword", "vector", "hybrid"],
          "default": "hybrid",
          "description": "Primary retrieval method. 'keyword' = FTS5 only, 'vector' = vector only, 'hybrid' = BM25+vector+RRF."
        },
        "vectorEnrichment": {
          "type": "boolean",
          "default": false,
          "description": "Use vector search to enrich keyword results when primary is 'keyword'."
        }
      },
      "additionalProperties": false
    },
    "lengthPenalty": {
      "type": "object",
      "description": "Length penalty settings to favour focused chunks over large keyword-rich ones",
      "properties": {
        "enabled": {
          "type": "boolean",
          "default": true,
          "description": "Enable logarithmic length penalty for scoring"
        },
        "referenceTokens": {
          "type": "number",
          "minimum": 1,
          "default": 500,
          "description": "Reference token count. Chunks at this size receive no penalty; larger chunks are penalised logarithmically."
        }
      },
      "additionalProperties": false
    },
    "recency": {
      "type": "object",
      "description": "Recency boost settings for time-decay scoring",
      "properties": {
        "decayFactor": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "default": 0.3,
          "description": "Amplitude of the time-decay boost (multiplied by exp decay)"
        },
        "halfLifeHours": {
          "type": "number",
          "minimum": 1,
          "maximum": 8760,
          "default": 48,
          "description": "Half-life in hours for the decay function"
        }
      },
      "additionalProperties": false
    },
    "semanticIndex": {
      "type": "object",
      "description": "Semantic index layer settings for cluster-level search",
      "properties": {
        "enabled": {
          "type": "boolean",
          "default": false,
          "description": "Enable semantic index generation. Requires eager embedding."
        },
        "targetDescriptionTokens": {
          "type": "integer",
          "minimum": 10,
          "maximum": 1000,
          "default": 130,
          "description": "Target description length in tokens for index entries"
        },
        "batchRefreshLimit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10000,
          "default": 500,
          "description": "Maximum entries to backfill per maintenance run"
        },
        "useForSearch": {
          "type": "boolean",
          "default": true,
          "description": "Use index entries for search when available"
        }
      },
      "additionalProperties": false
    },
    "repomap": {
      "type": "object",
      "description": "Structural repo map settings",
      "properties": {
        "enabled": {
          "type": "boolean",
          "default": true,
          "description": "Enable repo map generation for session context"
        },
        "maxTokens": {
          "type": "integer",
          "minimum": 100,
          "maximum": 10000,
          "default": 1024,
          "description": "Maximum tokens for the repo map output"
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}