Configuration reference

Use this page to configure ZettelForge 2.8.0. ZettelForge reads config.yaml or config.yml from your working directory or the source checkout. You do not need a file for the default SQLite store. Before you use this reference, complete the Quickstart and confirm that ZettelForge imports successfully.

cp config.default.yaml config.yaml
$EDITOR config.yaml

The source checkout ignores config.yaml, but environment variables remain the safer place for credentials. Check your own repository rules before you store secrets in a file.

Resolution order

ZettelForge resolves each setting from these sources, highest priority first:

1. Environment variables (ZETTELFORGE_*, TYPEDB_*, AMEM_*)
2. config.yaml or config.yml in the working directory
3. config.yaml or config.yml in the project root
4. config.default.yaml in the project root
5. Hardcoded defaults in src/zettelforge/config.py

Configuration wiring is in progress

The 2.8.0 parser accepts every field listed below, but some fields are not connected to their runtime consumers. Each affected section says exactly what the running base release uses. A parsed value is not proof that a feature is active.

Quick reference

Section	What it controls
storage	Where ZettelForge writes data
backend	SQLite (default) or TypeDB graph store
embedding	Embedding provider and model
llm	LLM provider, model, token limits
llm_ner	Background named-entity recognition
enrichment	Master switch for background enrichment dispatch
extraction	Two-phase fact extraction pipeline
retrieval	Recall scoring and cross-encoder reranking
synthesis	RAG answer generation
governance	Validation, PII detection, operation limits, memory defense
lance	LanceDB version-history cleanup
cache	TypeDB query result cache
logging	Log level and verbosity
telemetry	Environment-only operational telemetry location and debug flag
web	Web management interface
opencti	OpenCTI connection settings (in progress)

---

storage

Where ZettelForge stores notes, vector indexes, and entity indexes.

Key	Default	Description
data_dir	~/.amem	Root data directory. The web API reads this field. The library storage path currently reads AMEM_DATA_DIR directly, so a YAML-only change does not move library data.

Environment variable: AMEM_DATA_DIR

storage:
  data_dir: ~/.amem

---

backend

Which database backend ZettelForge uses for notes, knowledge graphs, and entity indexes.

Value	Description
sqlite	SQLite plus LanceDB. Default. Requires no external database service.
typedb	Parsed, but backend selection is in progress. The 2.8.0 base storage factory still creates SQLite.

Default: sqlite

Environment variable: ZETTELFORGE_BACKEND

backend: sqlite

Use SQLite in the 2.8.0 base release. The storage factory reads ZETTELFORGE_BACKEND, but it still returns SQLite for every value; YAML backend is not connected to that factory. TypeDB selection is in progress.

---

typedb

TypeDB connection settings. ZettelForge parses these values and resolves the credential references, but the 2.8.0 base storage factory does not create a TypeDB backend. Runtime use is in progress.

Key	Default	Description
host	localhost	TypeDB server hostname or IP.
port	1729	TypeDB port.
database	zettelforge	TypeDB database name.
username	""	TypeDB username. Use ${TYPEDB_USERNAME} to pull from the environment.
password	""	TypeDB password. Use ${TYPEDB_PASSWORD} to pull from the environment.

Environment variables: TYPEDB_HOST, TYPEDB_PORT, TYPEDB_DATABASE, TYPEDB_USERNAME, TYPEDB_PASSWORD

Never commit credentials to version control. Use environment references:

typedb:
  host: localhost
  port: 1729
  database: zettelforge
  username: ${TYPEDB_USERNAME}
  password: ${TYPEDB_PASSWORD}

---

embedding

Embedding model used for semantic vector search.

Key	Default	Description
provider	fastembed	Parsed from YAML. The embedding runtime currently reads ZETTELFORGE_EMBEDDING_PROVIDER or this hardcoded default.
url	http://127.0.0.1:11434	Parsed from YAML. The embedding runtime currently reads AMEM_EMBEDDING_URL or this hardcoded default.
model	nomic-ai/nomic-embed-text-v1.5-Q	Parsed from YAML. The embedding runtime currently reads AMEM_EMBEDDING_MODEL or this hardcoded default.
dimensions	768	Output dimension. Must match the model's actual output. Changing the model requires updating this field and running rebuild_index.py to re-embed all notes.
threads	8	ONNX intra-op thread count for in-process embeddings. Set 0 to use the ONNX Runtime default.

Environment variables: ZETTELFORGE_EMBEDDING_PROVIDER, AMEM_EMBEDDING_URL, AMEM_EMBEDDING_MODEL, ZETTELFORGE_EMBEDDING_DIM

Common model dimensions:

Model	Dimensions
nomic-ai/nomic-embed-text-v1.5-Q	768
nomic-ai/nomic-embed-text-v1.5	768
nomic-embed-text-v2-moe (Ollama)	768
qwen3-embedding (Ollama)	4096

embedding:
  provider: fastembed
  model: nomic-ai/nomic-embed-text-v1.5-Q
  dimensions: 768
  threads: 8

Dimension mismatch

If you change the embedding model, update dimensions to match and rebuild the index. The runtime logs embedding_dimension_mismatch and skips the incompatible vector.

---

llm

Language model for fact extraction, intent classification, causal triple extraction, and RAG synthesis.

The table lists the source fallback defaults in the v2.8.0 release.

Key	Default	Description
provider	ollama	Backend provider: ollama, local, litellm, or mock.
model	qwen3.5:9b	Model identifier passed to the selected provider. This is a published Ollama tag; ZettelForge does not install it for you.
url	http://localhost:11434	Provider URL. Used by ollama and local providers.
api_key	""	API key for cloud providers. Use ${ENV_VAR} syntax — never commit raw keys.
temperature	0.1	Parsed, but current task call sites pass their own temperatures. Changing this field does not override those calls. Runtime wiring is in progress.
timeout	180.0	Request timeout in seconds. Raised from 60s in v2.5.2 to accommodate reasoning models.
max_retries	2	Number of retry attempts on transient failure.
fallback	""	Name of a backup provider invoked on primary failure. Empty preserves the implicit local → ollama fallback chain.
local_backend	llama-cpp-python	In-process inference engine when provider: local. Options: llama-cpp-python (GGUF via llama-cpp-python, requires pip install zettelforge[local]) or onnxruntime-genai (ONNX, requires pip install zettelforge[local-onnx]).
max_tokens	400	Default output token limit.
max_tokens_causal	8000	Token limit for causal triple extraction.
max_tokens_synthesis	2500	Token limit for RAG synthesis.
max_tokens_extraction	2500	Token limit for fact extraction.
max_tokens_ner	2500	Token limit for LLM NER.
max_tokens_evolve	2500	Token limit for memory evolution.
reasoning_model	false	Set true when using a reasoning-optimized model. ZettelForge then raises the timeout and task-specific token limits to known-good floors.
extra	{}	Provider-specific kwargs forwarded to the constructor. Example: filename: qwen2.5-3b-instruct-q4_k_m.gguf for the local provider.

Environment variables: ZETTELFORGE_LLM_PROVIDER, ZETTELFORGE_LLM_MODEL, ZETTELFORGE_LLM_URL, ZETTELFORGE_LLM_API_KEY, ZETTELFORGE_LLM_TIMEOUT, ZETTELFORGE_LLM_MAX_RETRIES, ZETTELFORGE_LLM_FALLBACK, ZETTELFORGE_LLM_LOCAL_BACKEND, ZETTELFORGE_LLM_MAX_TOKENS, ZETTELFORGE_LLM_MAX_TOKENS_CAUSAL, ZETTELFORGE_LLM_MAX_TOKENS_SYNTHESIS, ZETTELFORGE_LLM_MAX_TOKENS_EXTRACTION, ZETTELFORGE_LLM_MAX_TOKENS_NER, ZETTELFORGE_LLM_MAX_TOKENS_EVOLVE, ZETTELFORGE_LLM_REASONING_MODEL

Install the default model

The v2.8.0 source and config.default.yaml select the published Ollama tag qwen3.5:9b. Install that tag in Ollama or set ZETTELFORGE_LLM_MODEL or llm.model to a model your chosen provider can load.

Provider examples

# Ollama on localhost with an explicit installed model
llm:
  provider: ollama
  model: qwen3.5:9b
  url: http://localhost:11434

# In-process GGUF — fully offline (requires zettelforge[local])
llm:
  provider: local
  local_backend: llama-cpp-python
  model: Qwen/Qwen2.5-3B-Instruct-GGUF
  extra:
    filename: qwen2.5-3b-instruct-q4_k_m.gguf

# LiteLLM routing — OpenAI, Anthropic, Google, Groq, and more
# (requires zettelforge[litellm])
llm:
  provider: litellm
  model: gpt-4o
  api_key: ${OPENAI_API_KEY}

# LiteLLM — Anthropic
llm:
  provider: litellm
  model: claude-sonnet-4-20250514
  api_key: ${ANTHROPIC_API_KEY}

# LiteLLM — Groq
llm:
  provider: litellm
  model: groq/llama-3.3-70b-versatile
  api_key: ${GROQ_API_KEY}

---

llm_ner

Background named-entity recognition. When enrichment is enabled, ZettelForge dispatches it after remember() to extract persons, locations, organizations, events, activities, and temporal entities with the configured LLM. Regex extraction runs independently.

Key	Default	Description
enabled	true	Set false to disable LLM NER (e.g. performance testing or offline environments).

Environment variable: ZETTELFORGE_LLM_NER_ENABLED

---

enrichment

Background enrichment dispatch controls causal extraction, LLM NER, and memory evolution jobs after writes. YAML and the environment variable both control the runtime gate.

Key	Default	Description
enabled	true	Set false to skip background enrichment jobs. Use this for deterministic tests and offline ingestion when LLM calls are unavailable.

Environment variable: ZETTELFORGE_ENRICHMENT_ENABLED

enrichment:
  enabled: false

---

extraction

These values are parser defaults only in 2.8.0. remember_with_extraction() uses its max_facts and min_importance arguments instead of this section. YAML wiring is in progress. Phase 1 extracts salient facts with importance scores; phase 2 compares each fact to existing notes and decides ADD, UPDATE, DELETE, or NOOP.

Key	Default	Description
max_facts	5	Maximum facts extracted per document.
min_importance	3	Minimum importance score (1–10) to keep a fact. Higher values produce fewer, more selective extractions.

extraction:
  max_facts: 5
  min_importance: 3

---

retrieval

Controls how recall() finds and ranks memories. Blended retrieval merges vector similarity with knowledge graph traversal results.

Key	Default	Description
default_k	10	Parsed, but recall() currently uses its own k=10 argument default.
similarity_threshold	0.25	Parsed; the current recall path does not read this field.
entity_boost	2.5	Parsed; the current recall path does not read this field.
max_graph_depth	2	Parsed; the current recall path does not read this field.
rerank_enabled	true	Whether to apply cross-encoder reranking after initial retrieval. Improves relevance at the cost of additional ONNX inference.
rerank_max_candidates	8	Number of candidates passed to the cross-encoder. Tuned for the CTI benchmark suite (2026-06-09).
rerank_doc_chars	256	Number of characters from each candidate document given to the reranker.
rerank_model	Xenova/ms-marco-MiniLM-L-6-v2	Cross-encoder model used for reranking.
entity_max_fanout	25	Drop query entities whose graph fan-out exceeds this many notes. Set 0 to keep all resolved entities.
rerank_threads	8	ONNX intra-op thread count for cross-encoder reranking. Set 0 to use the ONNX Runtime default.

Environment variable: ZETTELFORGE_RERANK_ENABLED

---

synthesis

ZettelForge parses this section, but synthesize() does not consume these three defaults in 2.8.0. Pass format and tier_filter to synthesize() directly. Runtime wiring for this section is in progress.

Key	Default	Description
max_context_tokens	3000	Parser default. The shared generator uses its constructor default and does not read this field.
default_format	direct_answer	Parser default. MemoryManager.synthesize() independently defaults to direct_answer.
tier_filter	["A", "B"]	Parser default. With no method argument, the current generator includes A, B, and C.

Format availability

direct_answer runs in the ZettelForge base release. Requests for synthesized_brief, timeline_analysis, or relationship_map fall back to direct_answer; native extended formats are in progress.

---

governance

Nested PII, limit, and memory-defense settings are applied before or during operations. The top-level fields below are parsed but are not consulted by the 2.8.0 MemoryManager; their runtime wiring is in progress.

Top-level keys

Key	Default	Description
enabled	true	Parsed; the current manager does not use this as a master switch.
min_content_length	1	Parsed; the current manager does not enforce this field.

governance.pii

PII detection via Microsoft Presidio (optional). Requires pip install zettelforge[pii]. Disabled by default; no new dependencies unless activated.

Note: ZettelForge's CTI allowlist excludes IP addresses, URLs, and domain names from PII detection since these are legitimate threat intelligence indicators.

Key	Default	Description
enabled	false	Enable PII scanning.
action	log	What to do when PII is detected: log (warn only, pass through), redact (replace with placeholder), block (raise exception).
redact_placeholder	[REDACTED]	Replacement text when action: redact.
entities	[]	PII entity types to detect. Empty list detects all supported types.
language	en	Language for NLP model.
nlp_model	en_core_web_sm	spaCy model for Presidio.

Environment variables: ZETTELFORGE_PII_ENABLED, ZETTELFORGE_PII_ACTION

governance.limits

Operation limits for DoS mitigation. A value of 0 disables the limit.

Key	Default	Description
max_content_length	52428800 (50 MB)	Maximum content size in bytes for a single remember() call.
recall_timeout_seconds	30.0	Maximum time in seconds allowed for a recall() query.

Environment variables: ZETTELFORGE_LIMITS_MAX_CONTENT_LENGTH, ZETTELFORGE_LIMITS_RECALL_TIMEOUT

governance.memory_defense

Write-time anomaly detection against memory poisoning attempts (SEC-011 / MemSAD). Requires at least min_calibration_notes stored notes before it activates — new instances operate unchecked until calibration is reached.

Key	Default	Description
enabled	true	Enable memory defense.
mode	audit	Response mode: audit (log only), block (reject anomalous writes), quarantine (write to quarantine log, not main store).
min_calibration_notes	50	Minimum notes required before anomaly detection activates.
max_reference_notes	50	Number of recent notes used as the anomaly baseline.
kappa	2.0	Anomaly detection sensitivity multiplier. Higher values flag fewer writes.
lexical_weight	0.25	Weight given to lexical similarity in the anomaly score (versus semantic similarity).
ngram_size	3	N-gram size for lexical comparison.
monitored_domains	[]	Domains to monitor. Empty list monitors all domains.
quarantine_path	""	Path to the quarantine JSONL file. Defaults to <data_dir>/quarantine/memory_anomalies.jsonl.
quarantine_raw_content	true	Include the raw content in quarantine entries for forensic inspection.

Environment variables: ZETTELFORGE_MEMORY_DEFENSE_ENABLED, ZETTELFORGE_MEMORY_DEFENSE_MODE, ZETTELFORGE_MEMORY_DEFENSE_MIN_CALIBRATION, ZETTELFORGE_MEMORY_DEFENSE_KAPPA

---

lance

LanceDB version-history cleanup daemon. LanceDB accumulates version files on every write; this daemon prunes old versions to prevent unbounded disk growth.

Key	Default	Description
cleanup_interval_minutes	60	How often the cleanup daemon runs. Set to 0 to disable cleanup.
cleanup_older_than_seconds	3600	LanceDB version files older than this are eligible for deletion.

---

cache

In-memory LRU and TTL cache for computed embeddings. It is active with the default SQLite and LanceDB path.

Key	Default	Description
ttl_seconds	300	Cache entry lifetime in seconds. 0 disables the cache.
max_entries	1024	Maximum number of cached entries.

---

logging

Key	Default	Description
level	INFO	Active log level: DEBUG, INFO, WARNING, or ERROR.
log_intents	true	Parsed but not consumed.
log_causal	true	Parsed but not consumed.
log_file	""	Parsed but not consumed; runtime writes under <AMEM_DATA_DIR>/logs.
audit_log_file	""	Parsed but not consumed; runtime writes under <AMEM_DATA_DIR>/logs.
log_to_stdout	true	Parsed but not consumed; runtime emits warnings and errors to standard error.
max_bytes	10485760	Parsed but not consumed; the same value is currently hardcoded by logging setup.
backup_count	9	Parsed but not consumed; the same value is currently hardcoded by logging setup.
audit_backup_count	52	Parsed but not consumed; the same value is currently hardcoded by logging setup.

Environment variable: ZETTELFORGE_LOG_LEVEL

---

telemetry

Operational telemetry writes recall and synthesis events for quality monitoring. In the verified checkout, telemetry path and debug controls are environment-only; a YAML telemetry: section is not applied by the config loader.

Key	Default	Description
ZETTELFORGE_TELEMETRY_DIR	~/.amem/telemetry	Directory for telemetry JSONL files.
ZETTELFORGE_TELEMETRY_DEBUG	false	Parsed into the config object, but the telemetry runtime does not consume it in 2.8.0.

---

web

These fields are parsed, but the 2.8.0 web/app.py launcher does not read them. Start the web app with its --host and --port arguments. The launcher defaults to 127.0.0.1:8088 and requires ZETTELFORGE_WEB_API_KEY before binding to all interfaces. YAML and environment wiring for this section is in progress.

Key	Default	Description
enabled	true	Parser default; the launcher does not read it.
host	0.0.0.0	Parser default; the launcher independently defaults to 127.0.0.1.
port	8088	Parser default; pass --port to the launcher.
ui_dir	""	Parser default; the launcher serves its packaged web/ui directory.

Environment variables: ZETTELFORGE_WEB_ENABLED, ZETTELFORGE_WEB_PORT, ZETTELFORGE_WEB_UI_DIR

---

opencti

Connection settings reserved for OpenCTI integration. The parser accepts these keys, but the 2.8.0 base release does not consume them for sync. Automatic sync is in progress. See Configure OpenCTI for the current manual exchange path.

Key	Default	Description
url	http://localhost:8080	OpenCTI API base URL.
token	""	Parsed token value. Use the OPENCTI_TOKEN environment variable; ${OPENCTI_TOKEN} interpolation is not implemented for this YAML field.
sync_interval	0	Parsed polling interval in seconds. No scheduler consumes it in the base release.

Environment variables: OPENCTI_URL, OPENCTI_TOKEN, OPENCTI_SYNC_INTERVAL