# How to Override Project Scope in ai-memory Using a .ai-memory.toml Marker File > Override ai-memory project scope with a .ai-memory.toml marker file. Learn how this simple file controls project detection for accurate scope management. - Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory) - Tags: how-to-guide - Published: 2026-08-31 --- **Place a [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) file containing a `project` key in your directory tree to override automatic project detection; the nearest marker file takes precedence over inferred directory names.** The ai-memory CLI determines your active workspace and project by traversing the directory tree for a configuration marker. According to the akitaonrails/ai-memory source code, adding a [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) file to your repository or any parent directory explicitly pins the project name and overrides the default inference mechanism that typically uses the current working directory name. ## Understanding Project Scope Resolution Order The resolution logic follows a strict hierarchy that prioritizes explicit configuration over automatic detection. As implemented in [`crates/ai-memory-cli/src/config.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/config.rs), the system evaluates scope in the following order: 1. **Explicit CLI flags** (`--workspace`, `--project`) passed directly to the command. 2. **Nearest [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml)** marker file that names a project, which always wins over implicit defaults. 3. **Fallback strategies**, including the repo-root derivation or the basename of the current working directory if no marker is present. This hierarchy ensures that local configuration overrides global defaults while still allowing temporary CLI overrides for single commands. ## Configuring the [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) Marker File The marker file uses TOML syntax and must be named exactly [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml). When placed in a directory, ai-memory discovers it by walking upward from the current working directory until the first match is found, as implemented in [`crates/ai-memory-cli/src/marker.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/marker.rs) (lines 106-126). ### Explicit Project Assignment To override project scope deterministically, specify the `project` key (and optionally `workspace`): ```toml # .ai-memory.toml workspace = "production" project = "api-service" ``` When this file is present, all ai-memory commands executed from that directory or any subdirectory will use **"api-service"** as the project name, regardless of the actual folder name on disk. This is documented in [`docs/marker-file.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/marker-file.md) (lines 394-446), which notes that the nearest marker file is authoritative and later directories are ignored. ### Repository-Root Strategy Alternatively, use the `project_strategy` key to derive the project name from the repository root rather than the current subdirectory: ```toml # .ai-memory.toml workspace = "my-workspace" project_strategy = "repo-root" ``` Setting `project_strategy = "repo-root"` instructs the CLI to walk up to the main repository root and use that directory name as the project identifier. This configuration allows multiple subdirectories to share the same project without hardcoding the name, as described in [`docs/marker-file.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/marker-file.md) (lines 26-31). ## Source Code Implementation Details The marker file discovery and scope resolution logic resides in the CLI crate with two primary components: **Marker Discovery** – The `find_marker` logic in [`crates/ai-memory-cli/src/marker.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/marker.rs) (lines 106-126) walks upward from the current working directory looking for [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml), parsing the keys `workspace`, `project`, and `project_strategy`. **Scope Resolution** – The `resolve_scope` function in [`crates/ai-memory-cli/src/config.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/config.rs) (lines 408-417) first checks for the marker file's presence, then applies install-wide defaults, and finally falls back to the derived name from the current directory. ## Practical Usage Examples The following examples demonstrate how to implement project scope overrides in different scenarios. **Override with Explicit Project Name:** ```toml # .ai-memory.toml placed in repository root workspace = "platform-team" project = "payment-gateway" ``` ```bash # From any subdirectory $ ai-memory status ▶︎ Workspace: platform-team ▶︎ Project: payment-gateway ``` **Override with Repository Root Strategy:** ```toml # .ai-memory.toml project_strategy = "repo-root" workspace = "shared-workspace" ``` **Temporary CLI Override:** To force a different project for a single command without modifying the marker file, use CLI flags which take precedence over the marker: ```bash $ ai-memory --project "temporary-project" status ``` The marker file remains unchanged and will be consulted for subsequent commands that omit the flags. ## Summary - **Explicit configuration wins**: A [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) file containing a `project` key overrides implicit directory-name inference. - **Nearest marker authority**: The CLI walks up from the current working directory and uses the first [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) found, ignoring parent directories (as documented in [`docs/marker-file.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/marker-file.md) at line 169). - **Flexible assignment strategies**: Use either explicit `project = "name"` or dynamic `project_strategy = "repo-root"` depending on whether you need a fixed name or repository-derived identification. - **Source locations**: Implementation resides in [`crates/ai-memory-cli/src/marker.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/marker.rs) (discovery) and [`crates/ai-memory-cli/src/config.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/config.rs) (resolution). - **CLI precedence**: Command-line flags (`--workspace`, `--project`) override even the marker file configuration for one-off commands. ## Frequently Asked Questions ### What takes precedence: CLI flags or the [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) marker file? **Explicit CLI flags take precedence.** The resolution order implemented in [`crates/ai-memory-cli/src/config.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/config.rs) checks CLI arguments first, then falls back to the nearest marker file. This allows you to use `--project` or `--workspace` for temporary overrides without altering your persistent configuration. ### Can I use multiple marker files in nested directories? **No, only the nearest marker file is authoritative.** According to [`docs/marker-file.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/marker-file.md) (line 169), the CLI stops at the first [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) encountered when walking up the directory tree from the current working directory. Parent directories beyond that point are ignored, preventing configuration merging or conflicts between nested projects. ### What happens if the marker file exists but doesn't specify a project? **The system falls back to default inference.** If [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) is present but omits both the `project` key and `project_strategy`, the CLI proceeds to derive the project name from the directory structure (typically the current working directory basename or repository root, depending on default settings). ### How does `project_strategy = "repo-root"` differ from setting an explicit `project` name? **Explicit assignment pins a specific string**, while **repo-root derives it dynamically.** When you set `project = "my-project"`, that exact value is used regardless of location. When using `project_strategy = "repo-root"`, the CLI calculates the project name from the repository's root directory name, allowing the same marker file to work across differently named clones or ensuring consistency across subdirectories without hardcoding.