# How to Configure the Auto-Scope Resolver for Dynamic Workspace/Project Routing in ai-memory

> Learn to configure the auto-scope resolver in ai-memory for dynamic workspace project routing. Use CLI flags, env variables, or a TOML file for easy setup.

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

---

**Configure ai-memory's auto-scope resolver by using CLI flags (`--workspace` and `--project`), setting the `AI_MEMORY_AUTO_SCOPE` environment variable, or creating a [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) marker file in your project root.**

The akitaonrails/ai-memory repository implements a dynamic routing system that automatically determines which workspace and project context to use for each request. Understanding how to configure the auto-scope resolver for dynamic workspace/project routing ensures your AI memory contexts remain organized and isolated across different projects.

## Understanding the Resolution Order

The auto-scope resolver evaluates configuration sources in strict priority order. When you execute any ai-memory command, the resolver checks for explicit CLI flags first, then environment variables, and finally marker files. If none are found, it falls back to default values defined in `ScopeResolver::lookup_existing` within [`crates/ai-memory-store/src/scope.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/scope.rs).

## Configuration Methods

### CLI Flags (Highest Priority)

The most direct method involves passing explicit identifiers to any ai-memory sub-command. According to the source implementation in the CLI layer, the `--workspace` and `--project` flags override all other configuration sources.

```bash
ai-memory --workspace my_ws --project my_proj embed \
    --model gpt-4o-mini "Hello world"

```

### Environment Variables

For shell-session persistence, set the `AI_MEMORY_AUTO_SCOPE` environment variable. The parser in [`crates/ai-memory-cli/src/config.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/config.rs) reads this variable, which accepts a comma-separated list of key-value pairs. The legacy `AI_MEMORY_AUTO_PROJECT` variable is also supported for backward compatibility.

```bash
export AI_MEMORY_AUTO_SCOPE="workspace=my_ws,project=my_proj"
ai-memory bootstrap   # the resolver will use the IDs above

```

### Marker Files (.ai-memory.toml)

Place a hidden [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) file in your project directory to bind that directory tree to specific workspace and project IDs. The resolver walks up the directory tree until it finds this marker, implementing the discovery logic in the scope resolution module.

```toml

# .ai-memory.toml placed in the project root

workspace = "my_ws"
project   = "my_proj"

```

Any command executed from this directory or its descendants automatically uses these configured IDs.

## Implementation Details

The core resolution logic resides in [`crates/ai-memory-store/src/scope.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/scope.rs), which defines the `ScopeResolver` struct. Key methods include `resolve_many_existing` for batch operations and `lookup_existing` for retrieving specific scope contexts.

In [`crates/ai-memory-mcp/src/server.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/server.rs), HTTP handlers access the resolver through the `scope_resolver()` method, which returns a fresh instance bound to the current request's reader pool. This dynamic instantiation occurs via `ScopeResolver::new(&reader, ws, proj)` for every request, ensuring complete isolation between concurrent operations.

## Fallback Behavior

When no configuration sources are present, the resolver defaults to the **default workspace** (`default`) and the **current project** (the most recently used project for that workspace). This fallback mechanism ensures the system remains functional even without explicit configuration, as implemented in the `lookup_existing` method.

## Programmatic Usage

For Rust developers integrating ai-memory directly, instantiate the resolver explicitly with your desired identifiers to bypass automatic detection:

```rust
use ai_memory_store::{ScopeResolver, ReaderPool};

fn do_something(reader: &ReaderPool) {
    // Resolve using explicit IDs (overrides env/marker)
    let resolver = ScopeResolver::new(reader, "my_ws", "my_proj");
    let page = resolver.lookup_existing("my_page").unwrap();
    // … use `page` …
}

```

This approach gives you full control over scope resolution by directly invoking the constructor defined in [`crates/ai-memory-store/src/scope.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/scope.rs).

## Summary

- The auto-scope resolver evaluates **CLI flags**, then **environment variables**, then **marker files** to determine workspace and project routing.
- Core implementation files include [`crates/ai-memory-store/src/scope.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/scope.rs) for resolution logic and [`crates/ai-memory-cli/src/config.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/config.rs) for environment parsing.
- **Fallback defaults** apply when no sources are found, using the `default` workspace and most recent project.
- The resolver is instantiated dynamically for each request via `ScopeResolver::new()`.

## Frequently Asked Questions

### What is the priority order for auto-scope configuration sources?

The resolver checks sources in strict sequence: first explicit CLI flags (`--workspace`, `--project`), then the `AI_MEMORY_AUTO_SCOPE` environment variable, then [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) marker files in the directory hierarchy. If none exist, it falls back to default workspace and current project values defined in the scope resolver implementation.

### Can I use multiple configuration methods at once?

Yes, but only the highest-priority source takes effect. For example, if you specify `--workspace` on the command line, it overrides any environment variable or marker file settings for that execution. The environment variable overrides marker files but is overridden by CLI flags.

### Where is the auto-scope resolver implemented in the source code?

The core 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) within the `ScopeResolver` struct. The CLI integration parsing `AI_MEMORY_AUTO_SCOPE` is in [`crates/ai-memory-cli/src/config.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/config.rs), while the MCP server exposes it through `scope_resolver()` in [`crates/ai-memory-mcp/src/server.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/server.rs).

### What happens if no workspace or project is configured?

The system defaults to the workspace named `default` and selects the most recently used project for that workspace. This fallback behavior is handled by the `lookup_existing` method in [`crates/ai-memory-store/src/scope.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/scope.rs).