# What Does `project_strategy = "repo-root"` Mean in `.ai-memory.toml`?

> Understand project_strategy = "repo-root" in .ai-memory.toml. Learn how this setting defines your repository's top-level directory as the project root for ai-memory indexing.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: getting-started
- Published: 2026-09-09

---

**Setting `project_strategy = "repo-root"` in your [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) configuration file instructs the ai-memory system to treat the repository's top-level directory—the folder containing the `.git` metadata—as the canonical project root, resolving all indexed file paths relative to this location.**

The `akitaonrails/ai-memory` repository uses this TOML configuration key to determine how the codebase is partitioned and indexed. When this strategy is active, scope-resolution helpers and path lookup functions operate within a unified workspace that encompasses the entire repository rather than isolating specific subdirectories.

## How `project_strategy` Defines Project Boundaries

The `project_strategy` configuration option controls how ai-memory identifies the root of your project workspace. When set to **`"repo-root"`**, the system treats the directory containing the `.git` folder as the absolute project boundary and resolves all stored memory index paths relative to this location.

This configuration directly impacts the **scope-resolution helpers** implemented in the source code. Functions such as `ScopeResolver::lookup_existing_scope` use this root directory as the canonical base for workspace and project identifiers, ensuring that the entire codebase is treated as one logical unit. This approach is ideal for **monorepos** or single-project repositories where you want unified indexing rather than segmented subdirectories.

## Implementation in the Source Code

According to the `akitaonrails/ai-memory` source code and architecture documentation, the configuration parsing and scope resolution logic explicitly handles the `"repo-root"` strategy.

### Configuration Parsing

In [`crates/ai-memory-mcp/src/config.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/config.rs), the system deserializes the [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) file. The `project_strategy` field is parsed from the TOML structure, with `"repo-root"` triggering repository-root-based path resolution.

### Scope Resolution Logic

The path resolution implementation resides in [`crates/ai-memory-store/src/scope_resolver.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/scope_resolver.rs). The `ScopeResolver` struct applies the configured strategy as follows:

- When `project_strategy` equals `"repo-root"`, the resolver initializes with the repository's top-level directory as the base path.
- Methods like `lookup_existing_scope` search for project identifiers starting from this root directory.
- All indexed pages store their paths relative to this root, ensuring portable references across different clone locations.

For a high-level overview of how projects and scopes interact, see [`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/ARCHITECTURE.md) in the repository root.

## Practical Configuration Examples

### Basic TOML Configuration

Define the strategy in your repository root:

```toml

# .ai-memory.toml

project_strategy = "repo-root"

```

### Loading Configuration in Rust

Retrieve the parsed configuration value programmatically:

```rust
use ai_memory_mcp::config::Config;

// Loads .ai-memory.toml from the repository root
let cfg = Config::load().expect("failed to load .ai-memory.toml");

assert_eq!(cfg.project_strategy, "repo-root");

```

### Resolving File Paths

Use the scope resolver to handle path resolution:

```rust
use ai_memory_store::ScopeResolver;

let resolver = ScopeResolver::new(&cfg);
let page_path = resolver.resolve_path("src/main.rs")?;
// page_path is now stored relative to the repo root

```

### CLI Usage

When using the ai-memory command-line interface, the tool automatically respects the `project_strategy` setting:

```bash

# Indexes src/lib.rs relative to the repo root defined in .ai-memory.toml

ai-memory index --path src/lib.rs

```

## Summary

- **`project_strategy = "repo-root"`** designates the repository's top-level directory as the project boundary for ai-memory indexing.
- All paths in the memory index resolve relative to the repository root, ensuring consistent references regardless of where the repository is cloned.
- The configuration is parsed in [`crates/ai-memory-mcp/src/config.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/config.rs) and applied in [`crates/ai-memory-store/src/scope_resolver.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/scope_resolver.rs) via the `ScopeResolver` struct.
- This strategy suits monorepos and single-project repositories requiring unified codebase management.

## Frequently Asked Questions

### What happens if I omit `project_strategy` from my [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml)?

If the `project_strategy` key is missing, ai-memory typically defaults to `"repo-root"` behavior for repositories containing a `.git` directory. However, explicit configuration is recommended to ensure deterministic path resolution across different environments.

### Can I use `project_strategy = "repo-root"` in a subdirectory of a monorepo?

Yes, but ai-memory will still resolve the repository root by locating the `.git` directory parent, not the subdirectory containing the [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) file. To treat a subdirectory as an isolated project, you would need a different strategy value that segments the workspace.

### How does this setting affect the `ScopeResolver::lookup_existing_scope` function?

When `"repo-root"` is active, `ScopeResolver::lookup_existing_scope` searches for existing project scopes starting from the repository root directory. This ensures that scope lookups encompass the entire repository structure rather than being constrained to a specific subfolder.

### Where is the project strategy validated in the source code?

The project strategy string is parsed and validated in [`crates/ai-memory-mcp/src/config.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/config.rs) during the TOML deserialization process. The validated configuration then drives the path resolution logic in [`crates/ai-memory-store/src/scope_resolver.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/scope_resolver.rs).