How to Override Project Scope in ai-memory Using a .ai-memory.toml Marker File

Place a .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 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, the system evaluates scope in the following order:

1. Explicit CLI flags (--workspace, --project) passed directly to the command.
2. Nearest .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 Marker File

The marker file uses TOML syntax and must be named exactly .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 (lines 106-126).

Explicit Project Assignment

To override project scope deterministically, specify the project key (and optionally workspace):

# .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 (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:

# .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 (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 (lines 106-126) walks upward from the current working directory looking for .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 (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:

# .ai-memory.toml placed in repository root

workspace = "platform-team"
project = "payment-gateway"

# From any subdirectory

$ ai-memory status
▶︎ Workspace: platform-team
▶︎ Project:   payment-gateway

Override with Repository Root Strategy:

# .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:

$ 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 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 found, ignoring parent directories (as documented in 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 (discovery) and 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 marker file?

Explicit CLI flags take precedence. The resolution order implemented in 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 (line 169), the CLI stops at the first .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 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.

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