# Understanding the Configuration Levels in SymbolicAI: A Three-Tier Priority Guide

> Explore SymbolicAI's three-tier configuration levels: working directory, Python environment, and user home. Understand how settings are prioritized for efficient runtime configuration.

- Repository: [ExtensityAI/symbolicai](https://github.com/extensityai/symbolicai)
- Tags: how-to-guide
- Published: 2026-03-01

---

**SymbolicAI resolves runtime settings through a three-tier priority system that checks the current working directory first, then the Python environment directory, and finally the user home directory.**

SymbolicAI, an open-source neuro-symbolic AI framework developed by ExtensityAI, organizes its runtime behavior through a hierarchical configuration system defined in [`symai/backend/settings.py`](https://github.com/extensityai/symbolicai/blob/main/symai/backend/settings.py). Understanding the different configuration levels in SymbolicAI enables developers to isolate debug settings, manage environment-specific API credentials, and maintain persistent user preferences without modifying source code.

## The Three-Tier Configuration Hierarchy

The configuration resolution logic in SymbolicAI follows a strict priority order implemented in the `SymAIConfig` class. When the library initializes, it searches for JSON configuration files across three distinct levels, stopping at the first match it encounters.

### Level 1: Debug Mode (Current Working Directory)

The highest priority configuration level targets active development scenarios. When a [`symai.config.json`](https://github.com/extensityai/symbolicai/blob/main/symai.config.json) file exists in the **current working directory** (where the Python process starts), SymbolicAI uses this file exclusively.

This debug mode, referenced in [`symai/backend/settings.py`](https://github.com/extensityai/symbolicai/blob/main/symai/backend/settings.py) lines 8-12 and 46-48, allows developers to test different engine configurations or API credentials without affecting global settings. Simply placing a configuration file in your project root overrides all other levels.

### Level 2: Environment-Specific Configuration (${PYTHON_PREFIX}/.symai)

If no debug configuration exists in the working directory, SymbolicAI falls back to the **Python environment directory**. The library checks for a hidden `.symai` folder located at `${PYTHON_PREFIX}/.symai`, where `PYTHON_PREFIX` represents the root of the current virtual environment or conda environment.

As implemented in [`symai/backend/settings.py`](https://github.com/extensityai/symbolicai/blob/main/symai/backend/settings.py) lines 16-19 and 49-51, this level isolates settings per interpreter instance. Configuration files placed here—such as [`symai.config.json`](https://github.com/extensityai/symbolicai/blob/main/symai.config.json), [`symsh.config.json`](https://github.com/extensityai/symbolicai/blob/main/symsh.config.json), or [`symserver.config.json`](https://github.com/extensityai/symbolicai/blob/main/symserver.config.json)—apply to all projects using that specific Python environment but remain invisible to other environments or the global user space.

### Level 3: User Home Directory Configuration (~/.symai)

The final fallback level targets persistent, user-wide settings. When neither debug nor environment-specific configurations exist, SymbolicAI resolves to the **user home directory**, specifically `~/.symai` (or the equivalent home path on Windows).

This global level, defined in [`symai/backend/settings.py`](https://github.com/extensityai/symbolicai/blob/main/symai/backend/settings.py) lines 18-22 and 52-53, serves as the default storage for permanent credentials, preferred engine selections, and cross-project preferences. When you run `symai.setup()` or save API keys for the first time, the library writes to this location.

## How SymAIConfig Manages Configuration Resolution

The `SymAIConfig` class in [`symai/backend/settings.py`](https://github.com/extensityai/symbolicai/blob/main/symai/backend/settings.py) encapsulates the priority logic and provides a programmatic interface for interacting with these levels. Rather than manually checking directories, developers use this class to resolve, load, and save configurations transparently.

Key methods include:

- **`config_dir`** – Returns the active configuration directory based on the current priority rules. This property dynamically evaluates whether the working directory, environment directory, or home directory should be used.

- **`get_config_path(filename)`** – Resolves an individual configuration file (such as [`symai.config.json`](https://github.com/extensityai/symbolicai/blob/main/symai.config.json)) to its absolute path according to the priority hierarchy. This method optionally supports forcing a home-directory fallback.

- **`load_config(filename)`** – Reads JSON data from the resolved path while maintaining an internal cache of the last-used location. This ensures subsequent operations target the same file.

- **`save_config(filename, data)`** – Writes JSON data to the appropriate configuration level, creating directories if necessary.

Because each level uses identical filenames, the library switches seamlessly between project-local debug settings, environment-scoped configurations, and global user preferences without requiring code changes.

## Practical Code Examples for SymbolicAI Configuration

The following examples demonstrate how to interact with the three configuration levels programmatically using the `SymAIConfig` class and global configuration objects.

Load the primary configuration and identify the active directory:

```python
from symai.backend.settings import SymAIConfig

# Load the primary SymbolicAI configuration (symai.config.json)

symai_cfg = SymAIConfig().load_config("symai.config.json")
print("Active config directory →", SymAIConfig().config_dir)

```

Override settings using the debug level (current working directory):

```python
from symai.backend.settings import SymAIConfig
import json

# Get the path for the current working directory level

debug_path = SymAIConfig().get_config_path("symai.config.json")

# Write a debug configuration to override other levels

debug_config = {"engine": "gpt-4o-mini", "debug": True}
debug_path.write_text(json.dumps(debug_config))

```

Access global configuration dictionaries:

```python
from symai import SYMAI_CONFIG, SYMSH_CONFIG, SYMSERVER_CONFIG

# Access pre-loaded configuration dictionaries

print(SYMAI_CONFIG)      # Main library configuration

print(SYMSH_CONFIG)      # Shell configuration

print(SYMSERVER_CONFIG)  # Server configuration

```

Retrieve the cached active path for a specific configuration file:

```python
from symai.backend.settings import SymAIConfig

# Access the cached location used for the most recent read/write

active_path = SymAIConfig().get_active_path("symai.config.json")
print("File actually read/written:", active_path)

```

## Summary

SymbolicAI implements a robust three-tier configuration system that balances flexibility, isolation, and persistence:

- **Debug Mode (Level 1)**: Uses [`symai.config.json`](https://github.com/extensityai/symbolicai/blob/main/symai.config.json) in the current working directory for project-specific overrides during development.
- **Environment-Specific (Level 2)**: Stores settings in `${PYTHON_PREFIX}/.symai` to isolate configurations per Python virtual environment or conda environment.
- **User Home Directory (Level 3)**: Maintains global preferences in `~/.symai` for cross-project, persistent settings.

The `SymAIConfig` class in [`symai/backend/settings.py`](https://github.com/extensityai/symbolicai/blob/main/symai/backend/settings.py) automates resolution across these levels, providing transparent access to configuration files regardless of which tier is active.

## Frequently Asked Questions

### What is the priority order for configuration levels in SymbolicAI?

SymbolicAI checks configuration levels in the following strict priority order: first the **current working directory** (debug mode), then the **Python environment directory** (`${PYTHON_PREFIX}/.symai`), and finally the **user home directory** (`~/.symai`). The library stops at the first level where it finds a valid configuration file, meaning a file in your project root will override environment and global settings.

### How do I create a debug configuration for a single project?

To create a project-specific debug configuration, place a file named [`symai.config.json`](https://github.com/extensityai/symbolicai/blob/main/symai.config.json) in your project's root directory (the current working directory where you run Python). SymbolicAI will automatically detect and use this file with highest priority. You can verify the active path by running `SymAIConfig().get_config_path("symai.config.json")` to confirm it resolves to your local file rather than the global or environment locations.

### Where does SymbolicAI store API keys and credentials permanently?

SymbolicAI stores permanent credentials and user-wide preferences in the **home directory configuration level** at `~/.symai` (or the equivalent path on Windows). When you run initial setup or save API keys without a project-specific configuration present, the `SymAIConfig` class writes to this location. This ensures your credentials persist across different Python environments and project directories while remaining isolated from version control.

### Can I use different configurations for different Python virtual environments?

Yes, SymbolicAI supports environment-specific configurations through the **Python prefix level**. Each virtual environment or conda environment has its own `${PYTHON_PREFIX}/.symai` directory where you can place [`symai.config.json`](https://github.com/extensityai/symbolicai/blob/main/symai.config.json) or related files. Settings stored here apply only to projects using that specific interpreter, allowing you to maintain different API keys or engine preferences for development, staging, and production environments without conflicts.