# ai-memory Configuration: Using TOML Files and Environment Variables

> Learn how ai-memory configures itself using TOML files and environment variables. Discover how the AI_MEMORY_ prefix and Figment library manage settings for robust runtime configuration.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: how-to-guide
- Published: 2026-09-12

---

**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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/templates/config.default.toml) that demonstrates all available configuration keys.

To create your own configuration file:

```bash

# 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`](https://github.com/akitaonrails/ai-memory/blob/main/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:

```bash
export AI_MEMORY_BIND=0.0.0.0:49374
ai-memory serve

```

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

```bash
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`](https://github.com/akitaonrails/ai-memory/blob/main/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:

```rust
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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/config.rs)
- The TOML template ships at [`crates/ai-memory-cli/templates/config.default.toml`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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.