title: Configuration Reference description: Complete reference for config.toml and environment variables in phorvec.

Configuration Reference

phorvec is configured through a config.toml file and a set of environment variables. Environment variables always take precedence over config.toml values, which makes them convenient for per-environment overrides in CI or containerized deployments.

The default configuration file location is ~/.phorvec/config.toml. You can specify an alternate path with the --config flag:

phorvec serve --config /etc/phorvec/config.toml

Environment Variables

Full config.toml Reference

The sections below document every configuration key. Keys shown with a default value are optional; omitting them uses the stated default.

[server]

Controls the MCP server process.

[server]
# Address and port for TCP mode. Ignored when using --stdio.
bind_addr = "127.0.0.1:3000"

# Maximum number of concurrent MCP connections.
max_connections = 64

# Idle connection timeout in seconds. Connections with no activity
# for this duration are closed.
connection_timeout_secs = 300

# Log level for this process. Overrides PHORVEC_LOG_LEVEL if set.
# Accepted: "error" | "warn" | "info" | "debug" | "trace"
log_level = "info"

# Path to write structured JSON logs. If unset, logs go to stderr.
# log_file = "/var/log/phorvec/server.log"

[embedding]

Controls the local embedding model used for all vector operations.

[embedding]
# Path to the ONNX model file. Defaults to the bundled nomic-embed-text model.
# Override this to use a different ONNX-format embedding model.
# model_path = "/path/to/custom/model.onnx"

# Number of dimensions in the embedding output. Must match the model.
# The bundled nomic-embed-text model produces 768-dimensional vectors.
dimensions = 768

# Maximum number of tokens the model accepts per input.
# Inputs longer than this are truncated before embedding.
max_tokens = 512

# Number of embedding requests to batch together for efficiency.
# Higher values improve throughput at the cost of latency for individual requests.
batch_size = 32

# Number of threads used by the ONNX runtime.
# Defaults to the number of logical CPU cores.
# num_threads = 4

[context]

Controls the context store behavior for all agents.

[context]
# Default importance weight assigned to new context items.
# Range: 0.0–1.0
default_importance = 0.7

# Half-life for importance decay, in hours.
# An item's importance is halved every this many hours.
# Set to 0 to disable decay.
decay_half_life_hours = 48.0

# Importance threshold below which items are candidates for archival.
# Range: 0.0–1.0
archive_threshold = 0.1

# Maximum number of items stored in a single context branch.
# When the limit is reached, the lowest-importance items are archived.
max_branch_items = 2000

# Maximum number of context branches per agent.
max_branches = 50

[context.consolidation]

Controls the automatic consolidation scheduler for context branches.

[context.consolidation]
# Whether to run consolidation on a schedule.
enabled = true

# How often to run consolidation, in minutes.
interval_minutes = 60

# Cosine similarity threshold above which two items are considered duplicates.
# Range: 0.0–1.0. Higher values mean stricter deduplication.
dedup_threshold = 0.92

[security]

Controls secret detection and audit logging.

[security]
# Policy applied when a secret is detected in a write operation.
# "reject" aborts the write and returns an error.
# "redact" replaces the secret value with a placeholder and continues.
secret_policy = "reject"

# Whether secret scanning is enabled.
secret_scanning_enabled = true

# File path glob patterns that will never be indexed by the RAG pipeline.
# Evaluated against the absolute path of each file.
denied_path_patterns = [
  "**/.env",
  "**/.env.*",
  "**/secrets/**",
  "**/credentials/**",
  "**/*.pem",
  "**/*.key",
  "**/*.pfx",
  "**/*.p12"
]

# Number of days to retain rotated audit log files.
audit_retention_days = 90

# Directory where rotated audit JSONL files are written.
# Defaults to PHORVEC_AUDIT_DIR or ~/.phorvec/audit
# audit_dir = "/var/log/phorvec/audit"

[storage]

Top-level storage settings.

[storage]
# Storage backend: "lancedb" (default, recommended) or "lite" (pure-Rust
# HNSW + SQLite, suitable for constrained environments).
backend = "lancedb"

# Directory where .avdb files are stored.
# Defaults to PHORVEC_DATA_DIR or ~/.phorvec/data
# data_dir = "/var/lib/phorvec/data"

# Handle pool settings: maximum number of simultaneously open .avdb handles.
# Handles beyond this limit are evicted using LRU.
max_open_handles = 128

# How long an idle handle stays open before being evicted, in seconds.
handle_idle_timeout_secs = 600

[storage.lite]

Settings specific to the lite (SQLite-based) storage backend.

[storage.lite]
# SQLite WAL mode. Strongly recommended to leave enabled.
# WAL mode improves concurrent read performance significantly.
wal_mode = true

# SQLite page size in bytes. Must be a power of 2 between 512 and 65536.
# 4096 is the SQLite default and works well for most workloads.
page_size = 4096

# Maximum size of the SQLite page cache in kilobytes.
# Larger cache improves read performance for large databases.
cache_size_kb = 65536

# How often SQLite checkpoints the WAL file, in seconds.
# More frequent checkpoints keep the WAL file small; less frequent
# checkpoints improve write throughput.
checkpoint_interval_secs = 30

# Whether to enable SQLite VACUUM on database open if fragmentation
# exceeds the threshold below.
auto_vacuum_enabled = true

# Fragmentation ratio above which auto-vacuum is triggered.
# Range: 0.0–1.0
auto_vacuum_threshold = 0.3

[quantization]

Controls vector quantization for the HNSW index.

[quantization]
# Quantization mode to use.
# "float32" — no size reduction, full precision
# "int8"    — 4× size reduction, minimal quality loss
# "binary"  — 32× size reduction, suitable for very large indexes
# "auto"    — selects mode based on index size and auto_thresholds below
mode = "auto"

[quantization.auto_thresholds]

Thresholds that drive the auto quantization mode.

[quantization.auto_thresholds]
# Number of vectors above which the index switches from float32 to int8.
int8_threshold = 10_000

# Number of vectors above which the index switches from int8 to binary.
binary_threshold = 100_000

[health]

Agent health monitoring thresholds. See Enterprise Features — Agent Health Monitoring.

[health]
# EMA smoothing factor. Range: 0.0–1.0.
# Higher values make the EMA more responsive to recent observations.
ema_alpha = 0.1

[health.thresholds]
coherence_warning = 0.6
coherence_critical = 0.4
contribution_warning = 0.2
contribution_critical = 0.05
prediction_error_warning = 0.4
prediction_error_critical = 0.6
latency_warning_ms = 500
latency_critical_ms = 2000
success_rate_warning = 0.90
success_rate_critical = 0.75

[retention]

Default retention policy applied to all agents. Per-agent overrides can be set via retention_status.

[retention]
# Number of days an item remains in the Active zone before
# being eligible for archival (subject to importance threshold).
active_days = 30

# Number of days an item remains in the Archived zone before
# moving to the PurgeQueue.
archive_days = 90

# Grace period in days between entering the PurgeQueue and
# permanent deletion by retention_sweep.
purge_grace_days = 7

Complete Example

A complete config.toml for a production deployment:

[server]
bind_addr = "127.0.0.1:3000"
max_connections = 32
log_level = "warn"

[embedding]
dimensions = 768
batch_size = 16

[context]
decay_half_life_hours = 24.0
max_branch_items = 1000

[context.consolidation]
enabled = true
interval_minutes = 30
dedup_threshold = 0.95

[security]
secret_policy = "reject"
audit_retention_days = 365
denied_path_patterns = ["**/.env", "**/.env.*", "**/*.pem", "**/*.key"]

[storage]
backend = "lite"
max_open_handles = 64

[storage.lite]
wal_mode = true
cache_size_kb = 32768

[quantization]
mode = "auto"
pca_enabled = true
pca_dimensions = 128

[quantization.auto_thresholds]
int8_threshold = 10_000
binary_threshold = 100_000

[retention]
active_days = 14
archive_days = 60
purge_grace_days = 7