ai-memory Configuration: Using TOML Files and Environment Variables

ai-memory reads its entire runtime configuration at startup by merging a TOML configuration file from the data directory with environment variables prefixed with AI_MEMORY_, using the Figment library to handle precedence and type safety.

The akitaonrails/ai-memory repository implements a layered configuration system that prioritizes operational flexibility. Instead of scattering environment variable lookups throughout the codebase, the application uses a single-load pattern that materializes all settings into an immutable Config struct at launch.

Configuration Architecture

The configuration system is centralized in crates/ai-memory-cli/src/config.rs and relies on the Figment library to merge multiple configuration sources. The implementation deliberately loads settings exactly once through Config::load(), ensuring that no other code paths call std::env::var directly. This design guarantees consistency and makes the configuration snapshot immutable for the application lifetime.

Two providers feed into the Figment merger:

• Toml::file: Reads config.toml from the data directory (data_dir)
• Env::prefixed("AI_MEMORY_"): Captures all environment variables starting with AI_MEMORY_

Because the environment provider is added after the TOML provider, environment variables automatically override file-based settings without additional logic.

TOML File Setup

By default, ai-memory expects a config.toml file inside the designated data directory. The repository ships with a reference template located at crates/ai-memory-cli/templates/config.default.toml that demonstrates all available configuration keys.

To create your own configuration file:

# Create the data directory

mkdir -p $HOME/.ai-memory

# Copy the default template (adjust path based on repository location)

cp crates/ai-memory-cli/templates/config.default.toml $HOME/.ai-memory/config.toml

# Edit the configuration

$EDITOR $HOME/.ai-memory/config.toml

The TOML structure maps directly to the Config struct defined in crates/ai-memory-cli/src/config.rs. Key fields include:

• data_dir: Path to persistent storage
• bind: Socket address (defaults to "127.0.0.1:49374")
• server_url: External server endpoint
• log_level: Logging verbosity

Environment Variable Overrides

All configuration keys can be overridden at runtime using environment variables with the AI_MEMORY_ prefix. Figment automatically converts these variables into the appropriate types during deserialization.

For example, to expose the server on all network interfaces without modifying the TOML file:

export AI_MEMORY_BIND=0.0.0.0:49374
ai-memory serve

Similarly, you can inject sensitive credentials like LLM API keys:

export AI_MEMORY_LLM_PROVIDER=openai
export AI_MEMORY_OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx
ai-memory serve

Configuration Structure and Future-Proofing

The Config struct in crates/ai-memory-cli/src/config.rs (lines 52-61) defines the schema for all settings. The implementation deliberately does not enable deny_unknown_fields on the deserializer, allowing forward compatibility. New configuration keys can be added to future versions without breaking existing deployments that may contain outdated TOML files or extraneous environment variables.

Missing keys fall back to their Default implementations (such as DecaySettings), ensuring the system starts gracefully even with minimal configuration.

Programmatic Access

For Rust developers extending ai-memory, the configuration is accessible through the Config struct:

use ai_memory_cli::config::Config;

fn main() -> anyhow::Result<()> {
    // Loads merged configuration (TOML + environment)
    let cfg = Config::load()?;
    println!("Server binding to: {}", cfg.bind);
    println!("Server URL: {}", cfg.server_url);
    Ok(())
}

This single call handles the complexity of merging file and environment sources, returning a fully populated configuration object.

Summary

• ai-memory uses Figment to merge TOML files and AI_MEMORY_ prefixed environment variables
• Configuration loads exactly once at startup via Config::load() in crates/ai-memory-cli/src/config.rs
• The TOML template ships at crates/ai-memory-cli/templates/config.default.toml for reference
• Environment variables automatically override TOML values due to provider ordering
• The system allows unknown fields for forward compatibility
• Default values (like 127.0.0.1:49374 for binding) are provided via Rust's Default trait

Frequently Asked Questions

Where does ai-memory look for the config.toml file?

ai-memory searches for config.toml inside the data directory specified by the data_dir configuration value. This can be set via the --data-dir CLI flag, the data_dir key in the TOML file, or the AI_MEMORY_DATA_DIR environment variable.

Do environment variables override TOML settings in ai-memory?

Yes. The configuration loader adds the Env provider after the Toml provider, so any environment variable prefixed with AI_MEMORY_ takes precedence over the corresponding TOML entry. For example, AI_MEMORY_BIND overrides the bind key in the configuration file.

What happens if I add an unknown configuration key to my TOML file?

The deserializer ignores unknown fields rather than rejecting them. This deliberate design choice, implemented in crates/ai-memory-cli/src/config.rs (lines 45-50), allows you to upgrade ai-memory without removing deprecated keys from your configuration, and enables forward compatibility with future settings.

Can I configure ai-memory entirely through environment variables without a TOML file?

Yes. While ai-memory looks for a TOML file, you can rely entirely on environment variables. Any configuration key defined in the Config struct can be set via an AI_MEMORY_ prefixed variable. Missing values will use their Rust Default implementations, allowing the server to start with zero configuration files present.

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