Struct EnrichArgs 

pub struct EnrichArgs {

    pub operation: Option<EnrichOperation>,
    pub mode: Option<EnrichMode>,
    pub limit: Option<usize>,
    pub dry_run: bool,
    pub namespace: Option<String>,
    pub claude_binary: Option<PathBuf>,
    pub claude_model: Option<String>,
    pub claude_timeout: u64,
    pub codex_binary: Option<PathBuf>,
    pub codex_model: Option<String>,
    pub codex_timeout: u64,
    pub opencode_binary: Option<PathBuf>,
    pub opencode_model: Option<String>,
    pub opencode_timeout: u64,
    pub openrouter_model: Option<String>,
    pub openrouter_api_key: Option<String>,
    pub openrouter_timeout: u64,
    pub openrouter_base_url: Option<String>,
    pub max_cost_usd: Option<f64>,
    pub resume: bool,
    pub retry_failed: bool,
    pub until_empty: bool,
    pub max_runtime: Option<u64>,
    pub max_attempts: u32,
    pub status: bool,
    pub list_dead: bool,
    pub requeue_dead: bool,
    pub prune_dead_orphans: bool,
    pub ignore_backoff: bool,
    pub body_extract_graph_only: bool,
    pub rest_concurrency: Option<u32>,
    pub min_output_chars: usize,
    pub max_output_chars: usize,
    pub preserve_check: bool,
    pub prompt_template: Option<PathBuf>,
    pub llm_parallelism: u32,
    pub json: bool,
    pub db: Option<String>,
    pub wait_job_singleton: Option<u64>,
    pub force_job_singleton: bool,
    pub names: Vec<String>,
    pub names_file: Option<PathBuf>,
    pub preflight_check: bool,
    pub fallback_mode: Option<EnrichMode>,
    pub rate_limit_buffer: u64,
    pub max_load_check: bool,
    pub circuit_breaker_threshold: u32,
    pub preserve_threshold: f64,
    pub codex_model_validate: bool,
    pub codex_model_fallback: Option<String>,
}

Arguments for the enrich subcommand.

Fields

operation: Option<EnrichOperation>

Enrichment operation to run. Required for write operations; optional for the read-only queue inspectors (--status / --list-dead / --requeue-dead), where it defaults to memory-bindings when omitted (GAP-SG-31).

mode: Option<EnrichMode>

LLM provider to use. Required for write operations; not needed for the read-only queue inspectors (--status / --list-dead / --requeue-dead), which never call the LLM (GAP-SG-31).

limit: Option<usize>

Maximum number of items to process in this run. Omit for all.

dry_run: bool

Preview items without calling the LLM (zero tokens consumed).

namespace: Option<String>

Namespace to operate on. Default: global.

claude_binary: Option<PathBuf>

Path to the Claude Code binary. Default: auto-detect from PATH.

claude_model: Option<String>

Claude model to use (e.g. claude-sonnet-4-6).

claude_timeout: u64

Timeout per item in seconds when using Claude Code. Default: 300.

codex_binary: Option<PathBuf>

Path to the Codex CLI binary. Default: auto-detect from PATH.

codex_model: Option<String>

Codex model to use (e.g. o4-mini).

codex_timeout: u64

Timeout per item in seconds when using Codex. Default: 300.

opencode_binary: Option<PathBuf>

Path to the OpenCode binary. Default: auto-detect from PATH.

opencode_model: Option<String>

OpenCode model to use.

opencode_timeout: u64

Timeout per item in seconds when using OpenCode. Default: 300.

openrouter_model: Option<String>

OpenRouter text model to use (REQUIRED with –mode openrouter; no default).

openrouter_api_key: Option<String>

OpenRouter API key. Falls back to OPENROUTER_API_KEY env or stored config.

openrouter_timeout: u64

Timeout per item in seconds when using OpenRouter. Default: 600.

GAP-SG-17: raised from 300 to 600 because dense bodies (close to the ~32K-token context ceiling of the configured model) routinely take longer than five minutes to generate via deepseek-v4-flash:nitro. Raise it further for very large corpora; lower it for short snippets.

openrouter_base_url: Option<String>

Optional OpenRouter base URL override (reserved; defaults to the public API).

max_cost_usd: Option<f64>

Abort when cumulative cost exceeds this USD budget (API key only; ignored for OAuth).

resume: bool

Resume a previously interrupted run (skip already-done items).

retry_failed: bool

Retry only items that failed in a previous run.

until_empty: bool

GAP-ENRICH-BACKLOG-CONVERGE: loop scan→drain internally until the queue empties of eligible items or –max-runtime elapses; removes the need for an external bash retry loop.

max_runtime: Option<u64>

GAP-ENRICH-BACKLOG-CONVERGE: wall-clock ceiling in seconds for –until-empty. Defaults to 3600 when omitted.

max_attempts: u32

GAP-ENRICH-BACKLOG-CONVERGE: attempts per item before it becomes a dead-letter (status=‘dead’). Range 1..=20. Default 8.

GAP-SG-21: the default was raised from 5 to 8 because GAP-SG-09 now reclassifies malformed / non-JSON LLM output as TRANSIENT (retryable) rather than a permanent HardFailure. A flaky structured-output model (e.g. deepseek-v4-flash:nitro) may emit several bad generations in a row even after JSON repair (GAP-SG-10) recovers most of them; the extra attempts give the backlog room to converge before an item is parked in the dead-letter sink. Permanent faults (ProviderError, NotFound) still dead-letter on the first attempt regardless of this value.

status: bool

GAP-ENRICH-BACKLOG-CONVERGE: read-only mode — report queue and backlog counts without calling the LLM or acquiring the singleton.

list_dead: bool

GAP-SG-23: list every dead-letter item (status=‘dead’) for the current operation with its error_class, attempt count and last error message. Read-only — no LLM, no singleton. Use it to inspect what --requeue-dead would resurrect before running it.

requeue_dead: bool

GAP-SG-11/14: resurrect dead-letter items — move every status='dead' row back to pending, zeroing attempt, next_retry_at, error and error_class. Distinct from --retry-failed, which only resets the legacy status='failed' rows; dead-letter rows are the terminal sink of the v1.0.96 converge loop and are never re-selected without this flag. No LLM call or singleton is taken — it only rewrites queue statuses.

prune_dead_orphans: bool

GAP-SG-66: prune ORPHAN dead-letter rows — remove every status='dead' memory row whose item_key (the memory name) no longer exists in the main DB for this namespace. These are terminal “not found” failures that --requeue-dead can never recover (re-processing re-fails the same way), so they inflate queue_dead forever. Read-only on the main DB; deletes only confirmed-orphan rows from the queue sidecar. Entity-keyed dead rows are left untouched. No LLM, no singleton — like --list-dead.

ignore_backoff: bool

GAP-SG-16: ignore the per-item backoff cooldown (next_retry_at) when selecting candidates, so items waiting on exponential backoff are processed immediately. Use to drain a backlog whose cooldown windows are long but the provider has recovered. Without it, --status reports such items under waiting and they are skipped until their next_retry_at.

body_extract_graph_only: bool

GAP-SG-28: read-only body-extract — extract entities/relationships into the graph WITHOUT rewriting (or truncating) the memory body. The default body-extract restructures the stored body in place; with this flag the body is left untouched and only graph bindings are persisted (additive, via the same upsert path as memory-bindings). Ignored for every other operation.

rest_concurrency: Option<u32>

GAP-ENRICH-BACKLOG-CONVERGE: REST concurrency for –mode openrouter (clamp 1..=16, default 8). Distinct from the legacy –llm-parallelism.

min_output_chars: usize

Minimum output character count for body-enrich. Default: 500.

max_output_chars: usize

Maximum output character count for body-enrich. Default: 2000.

preserve_check: bool

Check that enriched body preserves all facts from the original (LLM judge). Default: true.

prompt_template: Option<PathBuf>

Path to a custom prompt template file for body-enrich.

llm_parallelism: u32

Number of parallel LLM workers (default 1 = serial). Each worker claims items atomically from the queue DB via UPDATE…RETURNING. Range: 1–32. For 2321 entities, –llm-parallelism 4 reduces wall time ~4×.

json: bool

Emit NDJSON output. Always true; flag accepted for compatibility.

db: Option<String>

Database path override.

wait_job_singleton: Option<u64>

G30: poll for the job singleton every second for up to N seconds when another invocation holds the lock. Default: 0 (fail fast).

force_job_singleton: bool

G30: force acquisition of the singleton lock by removing a stale lock file from a previously crashed invocation. Use only when you are certain no other enrich/ingest is running.

names: Vec<String>

G37: select a specific subset of memory names to enrich instead of the full candidate set. Comma-separated, e.g. --names a,b,c. Empty when omitted (processes all candidates).

GAP-SG-18: also a cooldown remedy — when --status shows items under waiting (parked on next_retry_at backoff), pass the exact names here to re-enqueue and process just that subset on the next run instead of waiting for every cooldown to elapse. REQUIRED for --operation augment-bindings, which refuses to re-scan the whole namespace.

names_file: Option<PathBuf>

G37: read the subset of memory names from a file (one per line). Lines starting with # and empty lines are ignored. Combined with --names (union) when both are set.

preflight_check: bool

G35: probe the LLM provider with a 1-turn ping before processing the batch. Aborts with a clear error if the rate-limit window is closed (avoids burning N turns only to fail on item 1).

fallback_mode: Option<EnrichMode>

G35: if a preflight probe or in-flight call hits the Claude rate limit, fall back to --fallback-mode (typically codex) instead of failing the batch. Ignored when --mode is already codex.

rate_limit_buffer: u64

G35: number of seconds before the OAuth rate-limit reset at which the preflight probe should refuse to start. Default 300 (5 min).

max_load_check: bool

G28-D: refuse to start when the 1-minute load average exceeds 2 × ncpus (or SQLITE_GRAPHRAG_MAX_LOAD_PER_NCPU if set). Set to false to skip the check on contended CI runners.

circuit_breaker_threshold: u32

G28-D: when the system is saturated, abort the job after this many consecutive HardFailure outcomes. Default 5.

preserve_threshold: f64

G29 Step 4: minimum trigram-Jaccard similarity between the original body and the LLM-rewritten body for the rewrite to be accepted. Scores below the threshold are rejected and emitted as EnrichItemResult::PreservationFailed. Default 0.7 (per the G29 gap specification). Ignored when --operation is not body-enrich.

codex_model_validate: bool

G33 Step 3: when set, validate --codex-model against the ChatGPT Pro OAuth accepted-model list and abort with a suggestion when the value is unknown. Default true (fail fast to avoid burning OAuth turns). Set to false to opt out.

codex_model_fallback: Option<String>

G33 Step 3: when set together with an invalid --codex-model, automatically substitute the supplied default (e.g. gpt-5.5) instead of aborting. The substitution is recorded in the NDJSON stream as provider_substituted: true for traceability.

Trait Implementations

impl Args for EnrichArgs

fn group_id() -> Option<Id>

Report the ArgGroup::id for this set of arguments

fn augment_args<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate Self via FromArgMatches::from_arg_matches_mut

fn augment_args_for_update<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate self via FromArgMatches::update_from_arg_matches_mut

impl FromArgMatches for EnrichArgs

fn from_arg_matches(__clap_arg_matches: &ArgMatches) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn from_arg_matches_mut( __clap_arg_matches: &mut ArgMatches, ) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn update_from_arg_matches( &mut self, __clap_arg_matches: &ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

fn update_from_arg_matches_mut( &mut self, __clap_arg_matches: &mut ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.