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

Setting project_strategy = "repo-root" in your .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, the system deserializes the .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. 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 in the repository root.

Practical Configuration Examples

Basic TOML Configuration

Define the strategy in your repository root:

# .ai-memory.toml

project_strategy = "repo-root"

Loading Configuration in Rust

Retrieve the parsed configuration value programmatically:

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:

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:

# 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 and applied in 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?

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 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 during the TOML deserialization process. The validated configuration then drives the path resolution logic in crates/ai-memory-store/src/scope_resolver.rs.

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