Understanding the Config Load Path in ai-memory: Why a Single Source of Truth Matters

The ai-memory project centralizes all configuration handling in a single Config::load path that executes once at startup, producing an immutable, typed configuration struct shared across the entire runtime via Arc<Config>.

The ai-memory Rust project implements a strict architectural invariant requiring exactly one config-read path to guarantee system consistency. This design centralizes environment variables, TOML files, and CLI arguments into a single typed struct that serves as the immutable source of truth for all runtime components.

What is the Config Load Path?

The config load path in ai-memory refers to the static method Config::load defined in crates/ai-memory-cli/src/config.rs. This method is invoked exactly once during application initialization—specifically at line 54 of crates/ai-memory-cli/src/main.rs—and returns a fully populated Config struct containing all runtime settings.

Configuration Sources Merged by Config::load

The Config::load implementation uses the Figment library to merge three distinct configuration sources into a single coherent structure:

1. Environment Variables: All variables prefixed with AI_MEMORY_ are captured via Figment's Env::prefixed("AI_MEMORY_") provider (see lines 98-102 in crates/ai-memory-cli/src/config.rs).
2. Optional TOML File: If a config.toml path is supplied as an argument, Figment merges its contents with the environment variables.
3. CLI Arguments: Command-line overrides are applied via Figment's Cli provider, taking precedence over file and environment settings.

The resulting Config struct (lines 105-140) contains fields such as data_dir, bind, server_url, base_path, home_dir, log_level, and optional LLM settings.

Why ai-memory Enforces Only One Config-Read Path

The project's architecture explicitly forbids multiple configuration reads, as documented in docs/design-decisions.md (lines 249-252) and docs/ARCHITECTURE.md (lines 449-452). This invariant provides four critical benefits:

Atomicity and Consistency

By loading configuration a single time, the entire process obtains a snapshot of the environment, file, and CLI values. No component later reaches back into std::env or re-parses the TOML, preventing divergent settings where different subsystems might observe different configuration states.

Performance Optimization

Re-reading the environment or files repeatedly would add unnecessary CPU overhead, especially during startup when many subsystems (store, LLM provider, HTTP server) require identical configuration data. The single-read approach eliminates redundant I/O and parsing operations.

Safety and Invariant Enforcement

The codebase explicitly rejects "process.env double-read paths" to prevent bugs where a later change to an environment variable would silently affect only part of the system. Once Config::load completes, the configuration becomes effectively immutable, enforcing stability throughout the application lifecycle.

Simplified Dependency Management

All downstream crates receive a reference to the already-constructed Config via Arc<Config> or &Config. This eliminates the need for each crate to import Figment or perform its own environment lookup, keeping dependencies lean and the codebase easier to audit.

Implementation: Loading and Sharing Configuration

In practice, the configuration is loaded at application startup and shared across components using Rust's atomic reference counting:

use std::sync::Arc;
use ai_memory_cli::config::Config;

// 1️⃣ Load the config once (usually at program start)
let config_path = std::env::args().nth(1);
let cfg = Arc::new(Config::load(config_path.as_deref(), None)?);

// 2️⃣ Share the config with other components
let store = ai_memory_store::Store::new(cfg.clone())?;
let llm   = ai_memory_llm::LlmProvider::new(cfg.clone())?;

// 3️⃣ Access a field (e.g., the data directory) anywhere you have `&Config`
println!("Data directory: {}", cfg.data_dir.display());

This pattern ensures that the store, llm, and HTTP server components all reference the identical configuration snapshot created during the single load operation in main.rs.

Summary

• Single Load Location: Config::load in crates/ai-memory-cli/src/config.rs is the sole entry point for configuration, invoked once in main.rs.
• Triple Source Merge: Environment variables (AI_MEMORY_*), optional TOML files, and CLI arguments are merged via Figment into one typed struct.
• Immutable Distribution: The resulting Config is wrapped in Arc<Config> and shared across all crates, preventing subsequent environment reads.
• Architectural Invariant: The "One config-read path" rule is documented as the first core invariant in docs/ARCHITECTURE.md to prevent consistency bugs and redundant I/O.
• Performance Benefit: Eliminates redundant parsing and environment variable lookups during the critical startup phase.

Frequently Asked Questions

What happens if the config.toml file is missing?

Config::load handles missing files gracefully by treating the TOML source as optional. If no path is provided or the file does not exist, the method proceeds with environment variables and CLI arguments only, ensuring the application can start with purely environment-based configuration.

Can I reload configuration without restarting the application?

No. The architecture explicitly forbids runtime configuration reloading to maintain system stability. Since Config is loaded once and shared via Arc, there is no mechanism to propagate changes to already-initialized components without violating the single-read invariant and risking inconsistent state across subsystems.

How does Figment resolve conflicts between environment variables and CLI arguments?

Figment applies providers in a specific merge order: environment variables are loaded first, then merged with the optional TOML file, and finally overwritten by CLI arguments. This hierarchy ensures that command-line flags take highest precedence, followed by file settings, then environment variables, as implemented in the Config::load method.

Why not call std::env::var directly in each module instead of using Config::load?

Direct environment variable access is explicitly prohibited by the design decisions documented in docs/design-decisions.md. Scattered std::env calls would create multiple config-read paths, breaking atomicity and allowing different modules to observe different values if the environment changes between reads. Centralizing through Config::load guarantees every component sees the identical snapshot.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}