Module constants

Expand description

Compile-time constants: embedding dimensions, limits and thresholds. Compile-time constants shared across the crate.

Grouped into embedding configuration, length and size limits, SQLite pragmas and retrieval tuning knobs. Values are taken from the PRD and must stay in sync with the migrations under migrations/.

§Dynamic concurrency permit calculation

The maximum number of simultaneous instances can be adjusted at runtime using the formula:

permits = min(cpus, available_memory_mb / LLM_WORKER_RSS_MB) * 0.5

where available_memory_mb is obtained via sysinfo::System::available_memory() converted to MiB. The result is capped at MAX_CONCURRENT_CLI_INSTANCES and floored at 1.

§Layout

The constants live in themed submodules and are re-exported here, so every crate::constants::X path in the crate keeps resolving unchanged. The split happened in v1.2.5, when the single file had reached 960 lines against the project’s own 800-line ceiling (GAP-SG-89).

Constants§

AGENT_SURFACE_ALIAS_ARRAYS: GAP-SG-142: derived result arrays suppressed once the agent-native surface reshapes their canonical source.
AGENT_SURFACE_FIELD_SYNONYMS: GAP-SG-230: field spellings the agent-native surface treats as ONE key.
AGENT_SURFACE_RESULT_KEYS: GAP-SG-142: envelope members searched, in order, for the primary result array reshaped by crate::agent_surface.
AUTOSPLIT_PARTITION_MAX_BYTES: Byte budget for one auto-split partition (sub-memory) in ingest (GAP-SG-04/07).
BACKUP_BUSY_RETRY_DELAY_MS: Pause, in milliseconds, between sqlite3_backup_step retries after a transient Busy/Locked.
BATCH_PARTIAL_FAILURE_EXIT_CODE: Exit code for partial batch failure (PRD line 1822). Conflicts with DbBusy in v1.x; in v2.0.0 DbBusy migrates to 15 and this code takes 13 per PRD.
BROKEN_PIPE_EXIT_CODE: Process exit code returned when stdout is a closed pipe.
BUSY_TIMEOUT_MILLIS: PRAGMA busy_timeout value applied on every connection.
CACHE_SIZE_KB: PRAGMA cache_size value in kibibytes (negative means KiB).
CHUNK_OVERLAP_TOKENS: Token overlap between consecutive chunks.
CHUNK_SIZE_TOKENS: Chunk size expressed in tokens for body splitting.
CLI_LOCK_DEFAULT_WAIT_SECS: Maximum time in seconds an instance waits to acquire a concurrency slot.
CLI_LOCK_EXIT_CODE: Process exit code returned when the lock is busy and no wait was requested (EX_TEMPFAIL).
CLI_LOCK_POLL_INTERVAL_MS: Polling interval in milliseconds used by --wait-lock between try_lock_exclusive attempts.
COOPERATIVE_YIELD_SLEEP_MS: Pause, in milliseconds, appended to a cooperative yield between enrich batches (PRIO-05).
CURRENT_SCHEMA_VERSION: Current schema version, equal to the highest migration number in migrations/Vnnn__*.sql.
DB_BUSY_EXIT_CODE: Exit code for DbBusy in v2.0.0 (migrated from 13 to free 13 for batch failure).
DEADLOCK_CHECK_INTERVAL_SECS: Poll interval, in seconds, of the deadlock-detection watchdog thread.
DEDUP_FUZZY_THRESHOLD: Jaccard threshold above which two memories are considered fuzzy duplicates.
DEDUP_SEMANTIC_THRESHOLD: Cosine distance threshold below which two memories are semantic duplicates.
DEFAULT_AGENT_SURFACE_MAX_ITEMS: Default cap on emitted result elements (--max-items). 0 means no cap, preserving the pre-GAP-SG-142 envelope byte for byte.
DEFAULT_AGENT_SURFACE_MAX_OUTPUT_BYTES: Default cap on the serialized envelope in bytes (--max-output-bytes). 0 disables the ceiling.
DEFAULT_AGENT_SURFACE_TRUNCATE_CONTENT: Default cap on string length in characters (--truncate-content). 0 disables content truncation.
DEFAULT_EMBEDDING_DIM: Default embedding vector dimensionality for a NEWLY created database.
DEFAULT_EMBEDDING_HTTP_TIMEOUT_SECS: Default total per-request budget, in seconds, for an OpenRouter embeddings HTTP call when neither --openrouter-timeout nor XDG embedding.timeout_secs supplies a value (GAP-SG-141 B3).
DEFAULT_ENRICH_CIRCUIT_BREAKER_RESET_SECS: Cooldown, in seconds, before a tripped per-worker circuit breaker allows the next attempt (enrich parallel drain).
DEFAULT_ENRICH_LLM_PARALLELISM: Default subprocess worker count for enrich when --llm-parallelism is omitted (GAP-SG-141).
DEFAULT_ENRICH_MAX_RUNTIME_SECS: Default wall-clock budget, in seconds, for one enrich run when --max-runtime is omitted.
DEFAULT_ENRICH_REST_CONCURRENCY: Default REST fan-out for enrich --mode openrouter when --rest-concurrency is omitted (GAP-SG-141).
DEFAULT_ENRICH_SCAN_PAGE_SIZE: GAP-SG-185 / v1.2.4: default keyset page size for enrich scan collectors.
DEFAULT_HYBRID_MAX_GRAPH_RESULTS: DEFAULT cap on hybrid-search --with-graph graph matches.
DEFAULT_K_RECALL: Default k used by recall when the caller omits --k.
DEFAULT_LLM_PROBE_TIMEOUT_MS: Fail-fast probe budget for LLM backends before spawning (ms). Override via XDG llm.probe_timeout_ms.
DEFAULT_LOG_LEVEL: Default tracing filter level when neither CLI -v/-q nor XDG log.level is set (GAP-SG-93).
DEFAULT_MAX_HOPS: Default traversal depth for related when --hops is omitted.
DEFAULT_MAX_RSS_MB: Maximum process RSS in MiB before aborting embedding operations. Users can override via --max-rss-mb. Set to 8 GiB by default.
DEFAULT_MIN_WEIGHT: Default minimum weight filter applied during graph traversal.
DEFAULT_OPENROUTER_CHAT_TIMEOUT_SECS: Default per-item budget, in seconds, for an OpenRouter chat-completion when --openrouter-timeout is omitted.
DEFAULT_OPENROUTER_CHAT_URL: Default OpenRouter chat completions endpoint (override via XDG network.openrouter.chat_url or alias network.chat_url).
DEFAULT_OPENROUTER_EMBEDDINGS_URL: Default OpenRouter embeddings endpoint (override via XDG network.openrouter.embeddings_url or alias network.embed_url).
DEFAULT_RATE_LIMIT_DEADLINE_SECS: Deadline, in seconds, a drain keeps absorbing provider rate limits before giving up on the run.
DEFAULT_RAYON_THREADS: Default worker count for the global Rayon pool.
DEFAULT_REEMBED_CLAIM_BATCH: GAP-SG-141 (B1): how many ReEmbed queue rows a single claim takes.
DEFAULT_RELATION_WEIGHT: Default weight assigned to newly created relationships.
DEFAULT_STDIN_READ_TIMEOUT_SECS: Deadline, in seconds, for reading a memory body from stdin.
DERIVED_NAME_MAX_LEN: Maximum byte length for an ingest-derived kebab-case name.
DUPLICATE_EXIT_CODE: Process exit code returned when a duplicate memory or entity is detected (exit 9).
EMBEDDING_DIM_RANGE: Accepted range for any embedding dimensionality, override or recorded.
EMBEDDING_MAX_TOKENS: Maximum tokens accepted by an embedding input before chunking.
EMBEDDING_REQUEST_MAX_TOKENS: Maximum token count for a SINGLE embedding request input (GAP-SG-02).
EMBED_RUNTIME_MAX_WORKER_THREADS: Upper bound on Tokio worker threads for the shared embedding runtime (GAP-SG-141 B2).
EMBED_RUNTIME_MIN_WORKER_THREADS: Lower bound on Tokio worker threads for the shared embedding runtime (GAP-SG-141 B2).
EMBED_SLOT_RETRY_DELAY_MS: Pause, in milliseconds, before retrying a query embedding that lost the race for an LLM slot.
EMBED_TIMEOUT_PER_EXTRA_BATCH_ITEM_SECS: Extra timeout, in seconds, granted per item beyond the first in a batched embedding call (GAP-4).
ENRICH_BACKOFF_CEILING_SECS: Ceiling, in seconds, on the exponential backoff a rate-limited drain waits between attempts.
ENRICH_BODY_LOG_PREVIEW_CHARS: Number of chars of a memory body kept in a LOG or diagnostic line.
ENRICH_BODY_PREVIEW_CHARS: Number of chars of a memory body shown to the model as a PREVIEW.
ENRICH_BODY_SUBJECT_CHARS: Number of chars of a memory body sent when the body ITSELF is the subject.
ENRICH_GENERIC_DESCRIPTION_MAX_CHARS: Minimum description length, in chars, below which a description is judged generic and eligible for rewriting.
ENRICH_HIGH_WEIGHT_THRESHOLD: Relationship weight at or above which an edge counts as HIGH weight.
ENRICH_INITIAL_MAX_TOKENS: Initial max_tokens budget sent on an enrich chat-completion request (GAP-SG-70/71).
ENRICH_MAX_LENGTH_RETRIES: Maximum number of max_tokens-growth re-attempts after a truncated (finish_reason: "length") enrich chat-completion, before giving up and returning the truncation as an error (GAP-SG-70/71).
ENRICH_MAX_TOKENS_CEILING: Upper bound on max_tokens growth for an enrich chat-completion (GAP-SG-70/71).
ENRICH_MAX_TOKENS_GROWTH_FACTOR: Multiplier applied to max_tokens each time OpenRouter reports finish_reason: "length" on an enrich chat-completion (GAP-SG-70/71).
ENRICH_QUALITY_ACCEPT_RATE_WEIGHT: Weight given to the accept rate when blending it with mean grounding score into a single quality figure.
ENRICH_QUALITY_MEAN_SCORE_WEIGHT: Weight given to the mean grounding score in the same blend.
ENRICH_SCAN_PAGE_SIZE_RANGE: Accepted range for enrich.scan_page_size / --scan-page-size.
ENRICH_SCAN_WATCHDOG_POLL_MS: Poll interval, in milliseconds, of the watchdog that interrupts an over-budget enrich scan.
ENRICH_UNTIL_EMPTY_IDLE_NAP_SECS: Nap, in seconds, taken by an --until-empty drain when every remaining item is still serving its backoff.
ENTITY_EMBED_CACHE_MAX_ENTRIES: DEFAULT entry ceiling for the process-wide entity-embedding cache.
ENTITY_EMBED_CACHE_TTL_SECS: DEFAULT time-to-live, in seconds, of one entity-embedding cache entry.
FASTEMBED_BATCH_SIZE: Batch size for fastembed encoding calls.
HEALTH_SUPER_HUB_DEGREE_THRESHOLD: Degree above which health reports an entity as a super-hub.
HEALTH_SUPER_HUB_SAMPLE_LIMIT: How many super-hubs health names in its warning string.
JOB_SINGLETON_POLL_INTERVAL_MS: G28-B (v1.0.68): polling interval in milliseconds used by acquire_job_singleton between retry attempts when another invocation already holds the singleton for (job_type, namespace).
K_DEEP_RESEARCH_GRAPH_EDGES_LIMIT: Maximum edges pulled when deep-research expands the graph around its hits.
K_ENRICH_BODY_CONTEXT_ENTITIES_LIMIT: Linked entities pulled into the prompt context when enriching a body.
K_ENTITIES_SEARCH: Default k for entity KNN searches during graph expansion.
K_GRAPH_ENTITIES_DEFAULT_LIMIT: Default --limit for graph entities when omitted.
K_GRAPH_MATCHES_LIMIT: Maximum result count from the recursive graph CTE in recall.
K_HISTORY_DEFAULT_LIMIT: Default --limit for history when omitted.
K_LIST_LIMIT_MAX: Inclusive upper bound for --limit on commands that page over stored rows.
K_LIST_TEXT_DEFAULT_LIMIT: Default --limit for list in a HUMAN format, when the caller omits it.
K_MAX_HOPS_CEILING: Inclusive upper bound for --max-hops and --depth on graph traversal.
K_MAX_SUB_QUERIES_CEILING: Inclusive upper bound for deep-research --max-sub-queries.
K_MEMORIES_DEFAULT: Default k for memory KNN searches when the caller omits --k.
K_QUERY_RANGE_MAX: Inclusive upper bound for -k/--k on every retrieval command.
K_RELATED_DEFAULT_LIMIT: Default --limit for related when omitted.
K_VOCABULARY_MAX_KEYS: Hard ceiling on distinct key names collected for a suggestion.
K_VOCABULARY_MAX_SUGGESTIONS: Alternatives named in a refusal message.
K_VOCABULARY_SAMPLE_ELEMENTS: Elements sampled when the surface builds the key vocabulary for a SUGGESTION.
LLM_SLOT_ASSUMED_AVAILABLE_MB: Memory assumed available when the LLM slot default is computed without sysinfo at hand.
LLM_SLOT_POLL_INTERVAL_MS: How long the LLM slot acquirer sleeps between polls while every slot is busy.
LLM_WORKER_RSS_MB: DEFAULT expected RSS, in MiB, budgeted for one LLM/REST worker.
LOW_MEMORY_EXIT_CODE: Process exit code returned when available memory is below crate::constants::MIN_AVAILABLE_MEMORY_MB.
MAX_BODY_CHARS_BEFORE_CHUNK: Body character count above which the body is split into chunks.
MAX_CONCURRENT_CLI_INSTANCES: Maximum number of CLI instances running simultaneously.
MAX_EMBED_PASSAGE_FAN_OUT: Highest REST fan-out width the batched passage embedder will use (v1.2.8, plan step 6).
MAX_ENRICH_REST_CONCURRENCY: Highest REST fan-out enrich --mode openrouter accepts (GAP-SG-266).
MAX_ENTITIES_PER_MEMORY: Default upper bound on distinct entities persisted per memory.
MAX_ENTITY_TYPE_LEN: Maximum length, in characters, of an entities.type label.
MAX_GRAPH_HOPS: Maximum number of hops allowed in graph traversals.
MAX_MEMORY_BODY_LEN: Hard upper bound on memory body length in bytes.
MAX_MEMORY_DESCRIPTION_LEN: Maximum character length for a memory description field.
MAX_MEMORY_NAME_LEN: Maximum byte length for a memory name field in kebab-case.
MAX_NAMESPACES_ACTIVE: Maximum number of simultaneously active namespaces (deleted_at IS NULL). Exit 5 when exceeded.
MAX_RELATIONSHIPS_PER_MEMORY: Upper bound on distinct relationships persisted per memory.
MAX_RETRY_AFTER_SECS: Ceiling, in seconds, on a single Retry-After sleep inside the HTTP retry loops of crate::chat_api and crate::embedding_api.
MAX_SQLITE_BUSY_RETRIES: Maximum attempts when a statement returns SQLITE_BUSY.
MAX_TOTAL_LLM_WORKERS: DEFAULT joint ceiling on max_concurrency × llm_parallelism for one host.
MIN_AVAILABLE_MEMORY_MB: Minimum available memory in MiB required before starting model loading.
MIN_EMBED_PASSAGE_FAN_OUT: Lowest REST fan-out width the batched passage embedder will use (v1.2.8, plan step 6).
MIN_ENRICH_REST_CONCURRENCY: Lowest REST fan-out enrich --mode openrouter accepts (GAP-SG-266).
MIN_RELATION_WEIGHT: Minimum relationship weight required for traversal inclusion.
MMAP_SIZE_BYTES: PRAGMA mmap_size value in bytes applied to each connection.
NAME_SLUG_REGEX: PRD-canonical regex that validates names and namespaces. Allows 1 char [a-z0-9] OR a 2-80 char string starting with a letter and ending with a letter/digit, containing only [a-z0-9-]. Rejects the __ prefix (internal reserved).
OMP_NUM_THREADS_DEFAULT: Default value injected into OMP_NUM_THREADS when not set by the user.
ORT_INTRA_OP_NUM_THREADS_DEFAULT: Default value injected into ORT_INTRA_OP_NUM_THREADS when not set.
ORT_NUM_THREADS_DEFAULT: Default value injected into ORT_NUM_THREADS when not set by the user.
PASSAGE_PREFIX: Prefix prepended to bodies before embedding as required by E5 models.
PURGE_RETENTION_DAYS_DEFAULT: Default retention period (days) used by purge when --retention-days is omitted.
QUERY_PREFIX: Prefix prepended to queries before embedding as required by E5 models.
QUERY_TIMEOUT_MILLIS: Query timeout applied to statements in milliseconds.
REEMBED_CLAIM_BATCH_RANGE: Accepted range for enrich.reembed_claim_batch.
REMEMBER_MAX_CONTROLLED_BATCH_CHUNKS: Ceiling on chunks per controlled micro-batch in remember.
REMEMBER_MAX_CONTROLLED_BATCH_PADDED_TOKENS: Maximum padded-token budget per controlled micro-batch in remember.
REMEMBER_MAX_SAFE_MULTI_CHUNKS: Explicit operational guard for multi-chunk documents in remember.
RRF_K_DEFAULT: Default k constant used by Reciprocal Rank Fusion in hybrid-search.
SCHEMA_USER_VERSION: Canonical value of PRAGMA user_version written after migrations.
SHUTDOWN_EXIT_CODE: Process exit code returned when shutdown is requested via SIGINT/SIGTERM/SIGHUP (v1.0.82, GAP-002 final).
SQLITE_BUSY_BASE_DELAY_MS: Base delay in milliseconds for the first SQLITE_BUSY retry.
SQLITE_BUSY_MAX_DELAY_MS: Ceiling on ONE busy-retry sleep, in milliseconds.
SQLITE_GRAPHRAG_VERSION: Crate version string sourced from CARGO_PKG_VERSION at build time.
SYSTEM_LOAD_REFRESH_INTERVAL_SECS: Minimum interval, in seconds, between two /proc/loadavg reads.
TEXT_BODY_PREVIEW_LEN: Character size of the body preview emitted in text/markdown formats.
TEXT_DESCRIPTION_PREVIEW_LEN: Character length of the description preview shown in list output.
USAGE_EXIT_CODE: Process exit code returned when the argv is a valid parse but an invalid combination (EX_USAGE in spirit, 2 by this project’s contract).
VOCABULARY_SUGGESTION_MIN_SIMILARITY: Jaro-Winkler similarity below which a candidate is not offered as a fix.
WAL_AUTOCHECKPOINT_PAGES: PRAGMA wal_autocheckpoint threshold in pages.
WEIGHT_FTS_DEFAULT: Default weight for the BM25 text contribution in the hybrid-search RRF formula.
WEIGHT_VEC_DEFAULT: Default weight for the vector contribution in the hybrid-search RRF formula.

Functions§

agent_surface_field_synonym_groups: GAP-SG-274: the synonym groups that apply to command, in table order.
clamp_retry_after_secs: Clamps a server-advised Retry-After to MAX_RETRY_AFTER_SECS, warning when the cap actually bites.
embedding_dim: Resolves the active embedding dimensionality (single source of truth).
embedding_dim_from_runtime: Reads the CLI --embedding-dim flag or the XDG key embedding.dim.
entity_embed_cache_max_entries: Entity-cache entry ceiling: XDG embedding.entity_cache_max_entries or ENTITY_EMBED_CACHE_MAX_ENTRIES. 0 falls back to the default.
entity_embed_cache_ttl_secs: Entity-cache TTL in seconds: XDG embedding.entity_cache_ttl_secs or ENTITY_EMBED_CACHE_TTL_SECS. 0 falls back to the default.
hybrid_search_max_graph_results: Graph-match ceiling for hybrid-search: the --max-graph-results flag, then XDG search.hybrid.max_graph_results, then DEFAULT_HYBRID_MAX_GRAPH_RESULTS.
joint_parallelism_ceiling: Joint fan-out ceiling in force for this process.
joint_parallelism_ceiling_for: Per-process fan-out width still allowed once max_concurrency processes are counted against max_total_llm_workers.
llm_worker_rss_mb: Per-worker RSS budget in MiB: XDG llm.worker_rss_mb or LLM_WORKER_RSS_MB.
max_entities_per_memory: Resolves the per-memory entity cap (flag/XDG/runtime_config).
max_relationships_per_memory: Resolves the per-memory relationship cap (flag/XDG/runtime_config).
max_total_llm_workers: Joint worker ceiling: XDG parallelism.max_total_workers or MAX_TOTAL_LLM_WORKERS. 0 falls back to the default.
name_slug_regex: Returns a reference to the compiled NAME_SLUG_REGEX pattern. Compiled once on first call, cached via OnceLock.
set_active_embedding_dim: Records the dimensionality found in the opened database (schema_meta.dim).
set_joint_parallelism_ceiling: Publishes the joint fan-out ceiling derived from the resolved --max-concurrency (called once, from main).