# How the ai-memory Scope Resolver Handles .ai-memory.toml Marker Files

> Learn how the ScopeResolver in akitaonrails/ai-memory finds and parses .ai-memory.toml marker files, prioritizing workspace, project, and strategy settings for your AI memory.

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

---

**The `ScopeResolver` in `akitaonrails/ai-memory` uses a deterministic walk-up algorithm to find the nearest [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) marker file, parses its `workspace`, `project`, and `project_strategy` fields, and gives those values absolute precedence over CLI flags or environment variables.**

The `ai-memory` database isolates every read and write operation inside a specific workspace and project pair. To map any filesystem location to the correct scope, the `ScopeResolver` implements a discovery algorithm centered on [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) marker files. Understanding how this resolver walks the directory tree and applies precedence rules is essential for configuring multi-project repositories correctly.

## How the ScopeResolver Walk-Up Algorithm Discovers Marker Files

The `ScopeResolver` logic lives in [`crates/ai-memory-store/src/scope.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/scope.rs) and is driven by a simple walk-up search. According to the `akitaonrails/ai-memory` source code, the resolver begins at the current working directory and searches upward toward the home directory—or the filesystem root—for a file named [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml).

The first file encountered during this ascent is the **nearest** marker and is treated as authoritative. This deterministic behavior guarantees that every request touching the database is tied to the exact workspace and project defined by the closest configuration. The `ScopeResolver` invokes this logic through its `lookup_existing` and `resolve_many_existing` methods, ensuring consistent resolution across all operations.

## Parsing [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) Fields for Workspace and Project

Once the nearest marker is located in [`crates/ai-memory-cli/src/marker.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/marker.rs), the resolver parses the TOML contents to extract three critical fields.

- **`workspace`** — The declared workspace name becomes the active workspace for the request.
- **`project`** — When provided, this value is used as the project name directly.
- **`project_strategy`** — When `project` is omitted, this setting controls how the project name is derived.

If the marker specifies a `workspace`, that name is applied immediately. If it also names a `project`, that project is used directly. When a `project` is omitted, the resolver falls back to default derivation logic, as documented in [`docs/marker-file.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/marker-file.md).

## How `project_strategy` Controls Default Project Names

The `project_strategy` field influences phantom project creation when no explicit `project` is declared in the marker. The [`docs/design-decisions.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/design-decisions.md) file explains the two strategies implemented in `akitaonrails/ai-memory`.

**`basename` (default)** — Creates a project named after the current subdirectory. This is the standard behavior when users run commands from nested folders inside a repository.

**`repo-root`** — Forces the project name to match the repository root rather than the current subdirectory. Setting `project_strategy = "repo-root"` ensures that all commands inside the repository map to a single project scope.

## Why Marker Files Always Win Over Runtime Configuration

Marker files take absolute precedence in the `ai-memory` resolution chain. Even when a client supplies `--workspace` or `--project` flags, the resolver prioritizes values found in the nearest [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml). As noted in the CLI configuration, a [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) marker naming a project always wins over runtime flags and environment variables.

This design ensures that repository-local configuration is immutable and predictable, preventing accidental cross-project writes from nested directories.

## Fallback Behavior When No Marker File Exists

If the walk-up search reaches the home directory or root without finding [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml), the resolver falls back to a global default workspace. Typically this is `"home"` or `"oss"`, depending on the installation context, and the default project-derivation strategy is applied.

For example, a marker placed at `~/.ai-memory.toml` can define `workspace = "home"` to serve as the ultimate fallback for all operations outside explicit project trees.

## Practical Examples of Scope Resolution

You can observe the resolver behavior directly through the `ai-memory` CLI.

**Example 1 — Resolved scope from a nested directory:**

```bash
cd /Users/me/projects/acme/api
ai-memory show

```

Output:

```text
ai-memory: scope acme/api (workspace + project from /Users/me/projects/acme/.ai-memory.toml)

```

**Example 2 — Overriding the default project strategy at the repository root:**

Create [`/Users/me/projects/acme/.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main//Users/me/projects/acme/.ai-memory.toml) with the following contents:

```toml
workspace = "acme"
project_strategy = "repo-root"

```

Then run:

```bash
cd /Users/me/projects/acme/api
ai-memory show

```

Output:

```text
ai-memory: scope acme/api (workspace + project from /Users/me/projects/acme/.ai-memory.toml)

```

**Example 3 — Global fallback when no marker exists:**

```bash
cd /tmp/some/isolated/dir
ai-memory show

```

Output:

```text
ai-memory: scope home/default (fallback to global workspace "home")

```

## Key Implementation Files

The scope resolution system is implemented across the following source files:

- [`crates/ai-memory-cli/src/marker.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/marker.rs) — Discovers the nearest [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) and parses its fields.
- [`crates/ai-memory-store/src/scope.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/scope.rs) — Implements `ScopeResolver`, calling marker discovery and applying resolution rules.
- [`docs/marker-file.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/marker-file.md) — Documents the marker file format, walk-up algorithm, and precedence rules.
- [`docs/design-decisions.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/design-decisions.md) — Explains the `project_strategy` options and why markers take priority over runtime flags.

## Summary

- The `ScopeResolver` walks up from the current working directory to find the **nearest** [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml), and that file is always authoritative.
- Parsed fields include `workspace`, `project`, and `project_strategy`, which determine the final scope pair.
- **`project_strategy = "repo-root"`** changes derivation from the current subdirectory to the repository root.
- Marker files override **all** runtime flags and environment variables.
- If no marker is found, the resolver falls back to a global workspace such as `"home"`.

## Frequently Asked Questions

### What happens if multiple [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) files exist in the directory tree?

Only the nearest [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) to the current working directory is authoritative. The resolver stops at the first file found during the upward walk and ignores any higher-level markers.

### Can CLI flags override values in a [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) marker file?

No. According to the `akitaonrails/ai-memory` source code, a [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) marker naming a project always wins over both `--workspace` and `--project` CLI flags.

### What is the difference between `basename` and `repo-root` project strategies?

The default `basename` strategy derives the project name from the current subdirectory, while `repo-root` forces the project name to match the repository root. The latter is useful when you want all nested directories to share a single project scope.

### Where does the scope resolver look if no marker file is found?

The resolver walks upward until it reaches the home directory or filesystem root. If no [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) is found, it falls back to the global default workspace, typically `"home"`, and applies the default project derivation logic.