Settings Reference

All settings are loaded from environment variables and an optional .env file. The zero-config default is an in-memory store with keyword-only retrieval — no API keys required.

Copy .env.example to .env and edit. See Configuration for resolution order and code-level construction.

Storage (`STORAGE_*`)

Variable	Default	Description
`STORAGE_BACKEND`	`memory`	Storage backend: `memory` or `file`
`STORAGE_PATH`	`.contextseek/store`	Root directory when `backend=file`
`STORAGE_URI_SCHEME`	`contextseek://`	URI scheme used for scope refs
`STORAGE_COLD_BACKEND`	(empty)	Optional cold-tier backend type; empty disables tiered storage
`STORAGE_COLD_PATH`	`.contextseek/cold`	Root directory for cold-tier file backend

For OceanBase see the OB_* section below and Storage backends.

OceanBase (`OB_*`)

Variable	Default	Description
`OB_HOST`	`127.0.0.1`	OceanBase host
`OB_PORT`	`2881`	OceanBase port
`OB_USER`	`root@test`	Connection user
`OB_PASSWORD`	(empty)	Connection password
`OB_DB_NAME`	`test`	Database name
`OB_TABLE_NAME`	`contextseek_items`	Vector table name

OceanBase is instantiated via the runtime factory or examples — these vars are not read by the default from_settings() path unless you call from_runtime_config().

Embedding (`EMBEDDING_*`)

Variable	Default	Description
`EMBEDDING_PROVIDER`	`none`	`none` (disabled) or `langchain`
`EMBEDDING_CLASS_PATH`	(empty)	Fully qualified class, e.g. `langchain_openai.OpenAIEmbeddings`
`EMBEDDING_MODEL`	(empty)	Model name passed to the provider constructor
`EMBEDDING_DIMS`	`0`	Vector dimensions — required when provider ≠ `none`
`EMBEDDING_KWARGS`	`{}`	Extra kwargs forwarded to the provider constructor (JSON object)

Provider API keys (OPENAI_API_KEY, DASHSCOPE_API_KEY, etc.) are read directly by the LangChain class, not by ContextSeek.

LLM (`LLM_*`)

Shared LLM client used by: reranker, summarizer, evolution engine, dream engine, conflict judge.

Variable	Default	Description
`LLM_PROVIDER`	`none`	`none` (disabled) or `langchain`
`LLM_CLASS_PATH`	(empty)	Fully qualified class, e.g. `langchain_openai.ChatOpenAI`
`LLM_MODEL`	(empty)	Chat model name
`LLM_KWARGS`	`{}`	Extra kwargs forwarded to the provider constructor (JSON object)

Summarizer (`SUMMARIZER_*`)

Drives L0 abstract and L1 summary generation on every add().

Variable	Default	Description
`SUMMARIZER_PROVIDER`	`llm`	`none` (disabled) or `llm` (uses `LLM_*`)
`SUMMARIZER_L0_MAX_CHARS`	`100`	Character budget for L0 abstract
`SUMMARIZER_L1_MAX_CHARS`	`2000`	Character budget for L1 summary

When SUMMARIZER_PROVIDER=llm but no LLM is configured, the summarizer is skipped and a one-time warning is emitted. Retrieval falls back to L2-only behavior.

Retrieval (`RETRIEVAL_*`)

Variable	Default	Description
`RETRIEVAL_DEFAULT_K`	`20`	Default candidate pool size
`RETRIEVAL_RECALL_ROUTES`	`["phrase","terms"]`	JSON list: `phrase`, `terms`, `vector`
`RETRIEVAL_CANDIDATE_MULTIPLIER`	`4`	Oversampling factor before rerank
`RETRIEVAL_VECTOR_WEIGHT`	`0.7`	Hybrid score weight for vector similarity
`RETRIEVAL_FTS_WEIGHT`	`0.3`	Hybrid score weight for full-text search
`RETRIEVAL_TERM_WEIGHT`	`0.15`	Term overlap contribution to heuristic score
`RETRIEVAL_RECENCY_WEIGHT`	`0.05`	Recency contribution to heuristic score
`RETRIEVAL_FEEDBACK_WEIGHT`	`0.20`	`relevance_boost` contribution to heuristic score
`RETRIEVAL_ARCHIVE_PENALTY`	`0.50`	Score multiplier for archived items
`RETRIEVAL_PROVENANCE_WEIGHT`	`0.15`	Provenance confidence contribution
`RETRIEVAL_LINK_BOOST`	`0.10`	Score bonus for items with supporting links
`RETRIEVAL_LINK_REFUTE_PENALTY`	`0.40`	Score penalty for items with refuting links
`RETRIEVAL_LINK_SUPERSEDE_PENALTY`	`0.35`	Score penalty for superseded items
`RETRIEVAL_RERANKER_MODE`	`heuristic`	`heuristic` or `llm`
`RETRIEVAL_LLM_RERANK_TOP_N`	`20`	Candidate count passed to LLM reranker

Evolution (`EVOLUTION_*`)

Variable	Default	Description
`EVOLUTION_ENABLED`	`false`	Master switch — enables full `compact()` pipeline
`EVOLUTION_DEDUPE_BY_HASH`	`true`	Hash-based exact deduplication on `compact()`
`EVOLUTION_SEMANTIC_MERGE`	`true`	Similarity-based cluster merge on `compact()`
`EVOLUTION_SEMANTIC_MERGE_THRESHOLD`	`0.72`	Cosine similarity threshold for merge clustering
`EVOLUTION_MIN_CLUSTER_SIZE`	`3`	Minimum items required to form a merge cluster
`EVOLUTION_DECAY_HALF_LIFE_DAYS`	`7.0`	Half-life for importance decay (days)
`EVOLUTION_EXTRACT_MIN_AGE_SECONDS`	`60.0`	Minimum item age before extraction is attempted
`EVOLUTION_DISTILL_MIN_USE_COUNT`	`10`	Minimum `access_count` before skill distillation
`EVOLUTION_DISTILL_MIN_RELEVANCE_BOOST`	`1.2`	Minimum `relevance_boost` before distillation
`EVOLUTION_EPHEMERAL_TTL_SECONDS`	`3600.0`	TTL for ephemeral items before archival
`EVOLUTION_LLM_MERGE_ENABLED`	`false`	LLM synthesis for cluster merge
`EVOLUTION_LLM_CONFLICT_CHECK_ENABLED`	`false`	LLM contradiction judge on write
`EVOLUTION_LLM_STAGE_INFER_ENABLED`	`false`	LLM stage classification on write
`EVOLUTION_LLM_DISTILL_ENABLED`	`false`	LLM skill distillation
`EVOLUTION_LLM_FEEDBACK_ENABLED`	`false`	LLM feedback reason parsing

Dream (`DREAM_*`)

Variable	Default	Description
`DREAM_LLM_ENABLED`	`false`	LLM-assisted consolidation and divergence in dream cycles

Prompts (`PROMPT_*`)

Override any LLM prompt template. Placeholders vary by template ({query}, {content}, {items}, etc.). Escape literal braces in JSON-embedded examples as {{ and }}.

Variable	Template purpose
`PROMPT_SUMMARIZER_ABSTRACT_TEMPLATE`	L0 abstract generation
`PROMPT_SUMMARIZER_SUMMARY_TEMPLATE`	L1 summary generation
`PROMPT_RETRIEVAL_RELEVANCE_TEMPLATE`	LLM reranker scoring
`PROMPT_CONFLICT_JUDGE_TEMPLATE`	Contradiction detection on write
`PROMPT_STAGE_CLASSIFIER_TEMPLATE`	LLM stage inference on write
`PROMPT_FEEDBACK_TAG_TEMPLATE`	Feedback reason parsing
`PROMPT_MERGE_SYNTHESIS_TEMPLATE`	Cluster merge synthesis
`PROMPT_DISTILL_CANDIDATE_TEMPLATE`	Skill distillation candidate scoring
`PROMPT_DISTILL_RENDER_TEMPLATE`	Skill distillation rendering
`PROMPT_DREAM_CONSOLIDATION_TEMPLATE`	Dream consolidation step
`PROMPT_DREAM_DIVERGENCE_TEMPLATE`	Dream divergence/hypothesis step

See commented blocks in .env.example for all template keys and their placeholder variables.

Security (`SECURITY_*`)

Variable	Default	Description
`SECURITY_ACL_ENABLED`	`true`	Enforce read/write ACL policies
`SECURITY_ALLOW_ANY_SOURCE`	`true`	When `false`, only `SECURITY_ALLOWED_SOURCES` may write
`SECURITY_ALLOWED_SOURCES`	`[]`	JSON list of allowed source identifiers
`SECURITY_REDACT_SENSITIVE`	`false`	Redact matched fields on write
`SECURITY_REDACTION_TOKEN`	`[REDACTED]`	Replacement token for redacted values
`SECURITY_REDACT_FIELDS`	`[]`	JSON list of field names to redact
`SECURITY_DROP_FIELDS`	`[]`	JSON list of field names to drop entirely

Observability (`OBSERVABILITY_*`)

Variable	Default	Description
`OBSERVABILITY_AUDIT_ENABLED`	`false`	Enable JSONL audit log
`OBSERVABILITY_AUDIT_PATH`	`.contextseek/audit.jsonl`	Audit log file path
`OBSERVABILITY_METRICS_ENABLED`	`false`	Enable Prometheus text metrics export
`OBSERVABILITY_METRICS_PATH`	`.contextseek/metrics.prom`	Metrics file path
`OBSERVABILITY_TRACE_SAMPLE_RATE`	`1.0`	Fraction of requests to trace (0.0–1.0)

Lifecycle (`LIFECYCLE_*`)

Variable	Default	Description
`LIFECYCLE_INTERVAL_SECONDS`	`3600.0`	Scheduler check interval (seconds)
`LIFECYCLE_AUTO_COMPACT`	`true`	Allow scheduler to trigger compaction
`LIFECYCLE_COMPACT_MIN_ITEMS`	`5`	Minimum item count before compaction runs

Scope lint

Variable	Default	Description
`SCOPE_LINT`	`false`	Check scope strings on every `ctx.add()` call and emit `ScopeLintWarning` for malformed scopes

When SCOPE_LINT=true, the following rules are checked:

Condition	Warning
Empty scope string	Strongly recommend using a hierarchical scope
No `/` separator (flat scope)	At least two levels recommended for isolation
Depth > 6 levels	Too deep — may narrow retrieval to near-zero results
Uppercase letters or spaces	Use lowercase kebab-case

This check is off by default; enable it during development only. You can also configure it in code:

from contextseek import ContextSeek
from contextseek.config.settings import ContextSeekSettings

ctx = ContextSeek.from_settings(ContextSeekSettings(scope_lint=True))

Quick reference: minimal production `.env`

# Storage
STORAGE_BACKEND=file
STORAGE_PATH=.contextseek/data

# Embeddings (OpenAI example)
EMBEDDING_PROVIDER=langchain
EMBEDDING_CLASS_PATH=langchain_openai.OpenAIEmbeddings
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_DIMS=1536
OPENAI_API_KEY=sk-...

# LLM
LLM_PROVIDER=langchain
LLM_CLASS_PATH=langchain_openai.ChatOpenAI
LLM_MODEL=gpt-4o-mini

# Retrieval
RETRIEVAL_RECALL_ROUTES=["phrase","terms","vector"]

# Phase 1 LLM features
RETRIEVAL_RERANKER_MODE=llm
RETRIEVAL_LLM_RERANK_TOP_N=20
DREAM_LLM_ENABLED=true

# Observability
OBSERVABILITY_AUDIT_ENABLED=true

# Evolution (enable after Phase 1 is stable)
EVOLUTION_ENABLED=true

See Phased LLM rollout before enabling all LLM features at once.

← Configuration · API reference · Storage backends

FilesExpand file tree

settings.md

Latest commit

History

settings.md

File metadata and controls

Settings Reference

Storage (STORAGE_*)

OceanBase (OB_*)

Embedding (EMBEDDING_*)

LLM (LLM_*)

Summarizer (SUMMARIZER_*)

Retrieval (RETRIEVAL_*)

Evolution (EVOLUTION_*)

Dream (DREAM_*)

Prompts (PROMPT_*)

Security (SECURITY_*)

Observability (OBSERVABILITY_*)

Lifecycle (LIFECYCLE_*)