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

The ScopeResolver in akitaonrails/ai-memory uses a deterministic walk-up algorithm to find the nearest .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 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 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.

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 Fields for Workspace and Project

Once the nearest marker is located in 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.

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 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. As noted in the CLI configuration, a .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, 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:

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

Output:

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 with the following contents:

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

Then run:

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

Output:

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

Example 3 — Global fallback when no marker exists:

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

Output:

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 — Discovers the nearest .ai-memory.toml and parses its fields.
• crates/ai-memory-store/src/scope.rs — Implements ScopeResolver, calling marker discovery and applying resolution rules.
• docs/marker-file.md — Documents the marker file format, walk-up algorithm, and precedence rules.
• 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, 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 files exist in the directory tree?

Only the nearest .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 marker file?

No. According to the akitaonrails/ai-memory source code, a .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 is found, it falls back to the global default workspace, typically "home", and applies the default project derivation logic.

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